maintainx-debug-bundle

name	maintainx-debug-bundle
description	Comprehensive debugging toolkit for MaintainX integrations. Use when experiencing complex issues, need detailed logging, or troubleshooting integration problems with MaintainX. Trigger with phrases like "debug maintainx", "maintainx troubleshoot", "maintainx detailed logs", "diagnose maintainx", "maintainx issue".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(curl:*), Bash(node:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

MaintainX Debug Bundle

Overview

Complete debugging toolkit for diagnosing and resolving MaintainX integration issues with detailed logging, diagnostic scripts, and troubleshooting procedures.

Prerequisites

• MaintainX API access configured
• Node.js environment
• curl for direct API testing

Instructions

Step 1: Environment Diagnostic

// scripts/diagnose-env.ts
import axios from 'axios';

interface DiagnosticResult {
  category: string;
  check: string;
  status: 'PASS' | 'FAIL' | 'WARN';
  message: string;
}

async function runDiagnostics(): Promise<DiagnosticResult[]> {
  const results: DiagnosticResult[] = [];

  // Check 1: API Key presence
  const apiKey = process.env.MAINTAINX_API_KEY;
  results.push({
    category: 'Environment',
    check: 'API Key Configured',
    status: apiKey ? 'PASS' : 'FAIL',
    message: apiKey ? 'API key is set' : 'MAINTAINX_API_KEY not found',
  });

  // Check 2: API Key format
  if (apiKey) {
    const isValidFormat = apiKey.length > 20 && !apiKey.includes(' ');
    results.push({
      category: 'Environment',
      check: 'API Key Format',
      status: isValidFormat ? 'PASS' : 'WARN',
      message: isValidFormat
        ? 'API key format appears valid'
        : 'API key format may be incorrect',
    });
  }

  // Check 3: Network connectivity
  try {
    await axios.get('https://api.getmaintainx.com', { timeout: 5000 });
    results.push({
      category: 'Network',
      check: 'API Reachable',
      status: 'PASS',
      message: 'Can reach MaintainX API endpoint',
    });
  } catch (error: any) {
    results.push({
      category: 'Network',
      check: 'API Reachable',
      status: 'FAIL',
      message: `Cannot reach API: ${error.message}`,
    });
  }

  // Check 4: Authentication
  if (apiKey) {
    try {
      const response = await axios.get(
        'https://api.getmaintainx.com/v1/users?limit=1',
        {
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
          },
          timeout: 10000,
        }
      );
      results.push({
        category: 'Authentication',
        check: 'API Key Valid',
        status: 'PASS',
        message: 'Successfully authenticated with API',
      });
    } catch (error: any) {
      const status = error.response?.status;
      results.push({
        category: 'Authentication',
        check: 'API Key Valid',
        status: 'FAIL',
        message: `Authentication failed: HTTP ${status || error.message}`,
      });
    }
  }

  // Check 5: Node.js version
  const nodeVersion = process.version;
  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0]);
  results.push({
    category: 'Environment',
    check: 'Node.js Version',
    status: majorVersion >= 18 ? 'PASS' : 'WARN',
    message: `Node.js ${nodeVersion} (18+ recommended)`,
  });

  return results;
}

// Print results
async function main() {
  console.log('=== MaintainX Integration Diagnostics ===\n');

  const results = await runDiagnostics();

  // Group by category
  const categories = [...new Set(results.map(r => r.category))];

  categories.forEach(category => {
    console.log(`\n${category}:`);
    results
      .filter(r => r.category === category)
      .forEach(r => {
        const icon = r.status === 'PASS' ? '[OK]' : r.status === 'FAIL' ? '[!!]' : '[?]';
        console.log(`  ${icon} ${r.check}: ${r.message}`);
      });
  });

  // Summary
  const passed = results.filter(r => r.status === 'PASS').length;
  const failed = results.filter(r => r.status === 'FAIL').length;
  const warned = results.filter(r => r.status === 'WARN').length;

  console.log(`\n=== Summary ===`);
  console.log(`Passed: ${passed}, Failed: ${failed}, Warnings: ${warned}`);

  if (failed > 0) {
    console.log('\nAction Required: Fix failed checks before proceeding.');
    process.exit(1);
  }
}

main().catch(console.error);

Step 2: Request/Response Logger

// src/debug/logger.ts
import axios, { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse } from 'axios';
import fs from 'fs';
import path from 'path';

interface LogEntry {
  timestamp: string;
  requestId: string;
  method: string;
  url: string;
  requestHeaders: Record<string, string>;
  requestBody?: any;
  responseStatus?: number;
  responseHeaders?: Record<string, string>;
  responseBody?: any;
  duration?: number;
  error?: string;
}

class DebugLogger {
  private logs: LogEntry[] = [];
  private logFile: string;

  constructor(logDir = './logs') {
    if (!fs.(logDir)) {
      fs.(logDir, { :  });
    }
    . = path.(logDir, );
  }

  () {
    
    client...(
       {
         requestId = ;
        (config  ). = {
          requestId,
          : .(),
        };

         :  = {
          :  ().(),
          requestId,
          : config.?.() || ,
          : ,
          : .(config.  <, >),
          : config.,
        };

        ..(entry);
        .();

        .();
         config;
      },
       {
        .(, error);
         .(error);
      }
    );

    
    client...(
       {
         metadata = (response.  ).;
         entry = ..( l. === metadata?.);

         (entry) {
          entry. = response.;
          entry. = response.  <, >;
          entry. = response.;
          entry. = .() - metadata.;
          .();

          .();
        }

         response;
      },
       {
         metadata = (error.  )?.;
         entry = ..( l. === metadata?.);

         (entry) {
          entry. = error.?.;
          entry. = error.?.;
          entry. = error.;
          entry. = metadata ? .() - metadata. : ;
          .();

          .();
        }

         .(error);
      }
    );
  }

   (: <, >): <, > {
     sanitized = { ...headers };
     (sanitized.) {
      sanitized. = ;
    }
     sanitized;
  }

   () {
    fs.(., .(., , ));
  }

  (): [] {
     .;
  }

  ():  {
     .;
  }

  () {
    .();
    .();
    .();

     errors = ..( l. || (l. && l. >= ));
     (errors. > ) {
      .();
      errors.( {
        .();
      });
    }
  }
}

 {  };

Step 3: API Health Check Script

#!/bin/bash
# scripts/health-check.sh

set -e

echo "=== MaintainX API Health Check ==="
echo ""

# Check environment
if [ -z "$MAINTAINX_API_KEY" ]; then
  echo "[FAIL] MAINTAINX_API_KEY not set"
  exit 1
fi
echo "[OK] API key configured"

# Test endpoints
ENDPOINTS=(
  "/v1/users?limit=1"
  "/v1/workorders?limit=1"
  "/v1/assets?limit=1"
  "/v1/locations?limit=1"
)

BASE_URL="https://api.getmaintainx.com"

for endpoint in "${ENDPOINTS[@]}"; do
  echo -n "Testing $endpoint... "

  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    -H "Authorization: Bearer $MAINTAINX_API_KEY" \
    -H "Content-Type: application/json" \
    "$BASE_URL$endpoint")

  if [ "$HTTP_CODE" == "200" ]; then
    echo "[OK] HTTP $HTTP_CODE"
  elif [ "$HTTP_CODE" == "429" ]; then
     
  
     
  


 
 

Step 4: Data Validation Tool

// scripts/validate-data.ts
import { MaintainXClient } from '../src/api/maintainx-client';

interface ValidationIssue {
  resource: string;
  resourceId: string;
  issue: string;
  severity: 'error' | 'warning' | 'info';
}

async function validateData(client: MaintainXClient): Promise<ValidationIssue[]> {
  const issues: ValidationIssue[] = [];

  console.log('Validating MaintainX data...\n');

  // Validate Work Orders
  console.log('Checking work orders...');
  const workOrders = await client.getWorkOrders({ limit: 100 });

  workOrders.workOrders.forEach(wo => {
    // Check for missing title
    if (!wo.title || wo.title.trim() === '') {
      issues.push({
        : ,
        : wo.,
        : ,
        : ,
      });
    }

    
     (wo. ===  && wo.) {
       dueDate =  (wo.);
       (dueDate <  ()) {
        issues.({
          : ,
          : wo.,
          : ,
          : ,
        });
      }
    }

    
     (wo. ===  && (!wo. || wo.. === )) {
      issues.({
        : ,
        : wo.,
        : ,
        : ,
      });
    }
  });

  
  .();
   assets =  client.({ :  });

  assets..( {
    
     (!asset.) {
      issues.({
        : ,
        : asset.,
        : ,
        : ,
      });
    }

    
     (asset. === ) {
      issues.({
        : ,
        : asset.,
        : ,
        : ,
      });
    }
  });

   issues;
}


  () {
   client =  ();
   issues =  (client);

  .();

   (issues. === ) {
    .();
    ;
  }

  
   errors = issues.( i. === );
   warnings = issues.( i. === );
   infos = issues.( i. === );

   (errors. > ) {
    .();
    errors.( .());
  }

   (warnings. > ) {
    .();
    warnings.( .());
  }

   (infos. > ) {
    .();
    infos.( .());
  }

  .();
}

().(.);

Step 5: Network Debug with Verbose Logging

#!/bin/bash
# scripts/verbose-request.sh

# Make a verbose request to MaintainX API
curl -v \
  -H "Authorization: Bearer $MAINTAINX_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.getmaintainx.com/v1/workorders?limit=1" 2>&1 | tee maintainx-debug.log

echo ""
echo "Full output saved to maintainx-debug.log"

Step 6: Support Bundle Generator

// scripts/generate-support-bundle.ts
import fs from 'fs';
import path from 'path';
import { execSync } from 'child_process';

interface SupportBundle {
  generated: string;
  environment: Record<string, string>;
  nodeVersion: string;
  npmVersion: string;
  installedPackages: string[];
  diagnostics: any;
  recentLogs: any[];
}

async function generateSupportBundle(): Promise<void> {
  console.log('Generating MaintainX Support Bundle...\n');

  const bundle: SupportBundle = {
    generated: new Date().toISOString(),
    environment: {
      NODE_ENV: process.env.NODE_ENV || 'development',
      MAINTAINX_API_KEY: process.env.MAINTAINX_API_KEY ?  : ,
    },
    : process.,
    : ().().(),
    : [],
    : {},
    : [],
  };

  
   {
     packageJson = .(fs.(, ));
    bundle. = .(packageJson. || {});
  }  (e) {
    bundle. = [];
  }

  
   logsDir = ;
   (fs.(logsDir)) {
     logFiles = fs.(logsDir)
      .( f.())
      .()
      .(-);

    logFiles.( {
       {
         content = .(fs.(path.(logsDir, file), ));
        bundle..({ file, : content.(-) });
      }  (e) {
        
      }
    });
  }

  
   bundlePath = ;
  fs.(bundlePath, .(bundle, , ));

  .();
  .();
  .();
  .();
  .();
  .();
  .();
}

().(.);

Output

• Environment diagnostic report
• Request/response logs with timing
• API health check results
• Data validation issues
• Support bundle for troubleshooting

Debug Commands Quick Reference

# Run environment diagnostics
npx ts-node scripts/diagnose-env.ts

# API health check
./scripts/health-check.sh

# Validate data
npx ts-node scripts/validate-data.ts

# Generate support bundle
npx ts-node scripts/generate-support-bundle.ts

# Verbose API request
./scripts/verbose-request.sh

Resources

• MaintainX Help Center
• MaintainX API Status
• MaintainX Community

Next Steps

For rate limit handling, see maintainx-rate-limits.