🩺Debug Checklist

Systematic step-by-step workflow for debugging Docs-Dispatcher issues.

Overview

This checklist provides:

• Pre-flight checks before making requests

• Request debugging workflow

• Response analysis techniques

• Log analysis

• Network debugging

• Provider health checks

• When to contact support

• Information to include in support requests

Quick Diagnostic Flow

Issue Detected
      ↓
[Pre-Flight Checklist] ←────────┐
      ↓                          │
Authentication OK?               │
      ↓ yes                      │
Configuration OK?                │
      ↓ yes                      │
Validation Passes?               │
      ↓ yes                      │
[Make Request]                   │
      ↓                          │
Success? ──yes──→ [Done]         │
      ↓ no                       │
[Debug Response]                 │
      ↓                          │
[Analyze Logs]                   │
      ↓                          │
[Check Provider Status]          │
      ↓                          │
Can Fix? ──yes──→ [Fix] ─────────┘
      ↓ no
[Contact Support]

Pre-Flight Checklist

Run through this checklist before making dispatch requests.

1. Authentication Check

// ✅ Pre-Flight Step 1: Verify Authentication
async function checkAuthentication() {
  console.log('\n=== Step 1: Authentication Check ===\n');

  const jwt = process.env.JWT_TOKEN;

  // Check 1: Token exists
  if (!jwt) {
    console.error('✗ JWT token not found');
    console.log('Fix: Set JWT_TOKEN environment variable');
    console.log('Get token: POST https://api.docs-dispatcher.io/auth');
    return false;
  }
  console.log('✓ JWT token found');

  // Check 2: Token format
  const parts = jwt.split('.');
  if (parts.length !== 3) {
    console.error('✗ Invalid JWT format');
    console.log('Expected: xxx.yyy.zzz (header.payload.signature)');
    return false;
  }
  console.log('✓ JWT format valid');

  // Check 3: Token expiration
  try {
    const payload = JSON.parse(atob(parts[1]));
    const expiresAt = new Date(payload.expiresAt || payload.exp * 1000);
    const now = new Date();
    const minutesLeft = (expiresAt - now) / 1000 / 60;

    if (minutesLeft <= 0) {
      console.error('✗ JWT token expired');
      console.log(`Expired: ${expiresAt.toISOString()}`);
      console.log('Fix: Refresh token');
      return false;
    }

    if (minutesLeft < 10) {
      console.warn(`⚠ JWT expires in ${Math.floor(minutesLeft)} minutes`);
      console.log('Consider refreshing soon');
    } else {
      console.log(`✓ JWT valid for ${Math.floor(minutesLeft)} minutes`);
    }

  } catch (error) {
    console.error('✗ Cannot decode JWT payload');
    return false;
  }

  // Check 4: Test token with API
  try {
    const response = await fetch(
      'https://api.docs-dispatcher.io/api/v1/users/me',
      { headers: { 'Authorization': `Bearer ${jwt}` } }
    );

    if (!response.ok) {
      console.error('✗ JWT rejected by API');
      return false;
    }

    const user = await response.json();
    console.log(`✓ Authenticated as: ${user.email} (${user.role})`);
    console.log(`  Company: ${user.company.name}`);

    return true;

  } catch (error) {
    console.error('✗ API authentication test failed:', error.message);
    return false;
  }
}

// Run check
const authOk = await checkAuthentication();
if (!authOk) {
  console.error('\n🛑 Authentication check failed. Fix before proceeding.\n');
  process.exit(1);
}

2. Configuration Check

// ✅ Pre-Flight Step 2: Verify Configuration
async function checkConfiguration(service, providerName = null) {
  console.log('\n=== Step 2: Configuration Check ===\n');
  console.log(`Service: ${service}`);
  console.log(`Provider: ${providerName || 'auto-detect'}\n`);

  const jwt = process.env.JWT_TOKEN;

  // Check 1: Get user configs
  const userConfigs = await fetch(
    'https://api.docs-dispatcher.io/api/v1/users/me/configs',
    { headers: { 'Authorization': `Bearer ${jwt}` } }
  ).then(r => r.json());

  const userConfig = userConfigs.find(c =>
    c.service === service &&
    (!providerName || c.providerName === providerName)
  );

  // Check 2: Get company configs
  const companyConfigs = await fetch(
    'https://api.docs-dispatcher.io/api/v1/companies/me/configs',
    { headers: { 'Authorization': `Bearer ${jwt}` } }
  ).then(r => r.json());

  const companyConfig = companyConfigs.find(c =>
    c.service === service &&
    (!providerName || c.providerName === providerName)
  );

  // Check 3: Determine what will be used
  let willUse = null;
  let source = null;

  if (providerName) {
    willUse = providerName;
    source = 'explicit';
    const configured = userConfig || companyConfig;
    if (!configured) {
      console.warn(`⚠ Provider '${providerName}' not configured (will fail)`);
    } else {
      console.log(`✓ Provider '${providerName}' configured at ${configured === userConfig ? 'user' : 'company'} level`);
    }
  } else {
    if (userConfig?.isActive) {
      willUse = userConfig.providerName;
      source = 'user override';
      console.log(`✓ Will use user override: ${willUse}`);
    } else if (companyConfig?.isActive) {
      willUse = companyConfig.providerName;
      source = 'company default';
      console.log(`✓ Will use company default: ${willUse}`);
    } else {
      console.error('✗ No active configuration found');
      console.log('\nFix options:');
      console.log('  1. Configure at: https://app.docs-dispatcher.io/admin/configs');
      console.log('  2. Specify providerName explicitly in request');
      return false;
    }
  }

  // Check 4: Verify active
  const activeConfig = userConfig || companyConfig;
  if (activeConfig && !activeConfig.isActive) {
    console.error(`✗ Configuration is INACTIVE`);
    console.log('Fix: Activate configuration in Templater UI');
    return false;
  }

  console.log(`\n✓ Configuration OK: ${willUse} (${source})`);
  return true;
}

// Run check
const configOk = await checkConfiguration('invoicing', 'qonto');
if (!configOk) {
  console.error('\n🛑 Configuration check failed. Fix before proceeding.\n');
  process.exit(1);
}

3. Template Check

// ✅ Pre-Flight Step 3: Verify Template
async function checkTemplate(templateId) {
  console.log('\n=== Step 3: Template Check ===\n');
  console.log(`Template ID: ${templateId}\n`);

  const jwt = process.env.JWT_TOKEN;

  try {
    // Check 1: Template exists
    const response = await fetch(
      `https://api.docs-dispatcher.io/api/v1/templates/${templateId}`,
      { headers: { 'Authorization': `Bearer ${jwt}` } }
    );

    if (!response.ok) {
      console.error('✗ Template not found or not accessible');
      console.log('Check: https://app.docs-dispatcher.io/templates');
      return false;
    }

    const template = await response.json();
    console.log('✓ Template found');
    console.log(`  Name: ${template.name}`);
    console.log(`  Status: ${template.status}`);
    console.log(`  Content Type: ${template.contentType}`);
    console.log(`  Render Engine: ${template.renderEngine}`);

    // Check 2: Template active
    if (template.status !== 'ACTIVE') {
      console.warn(`⚠ Template status is '${template.status}' (not ACTIVE)`);
      console.log('Consider publishing template');
    }

    // Check 3: Template has data schema
    if (template.dataSchema) {
      console.log(`  Data Schema: ${Object.keys(template.dataSchema).length} fields`);

      if (template.dataSchema.required) {
        console.log(`  Required fields: ${template.dataSchema.required.join(', ')}`);
      }
    }

    return true;

  } catch (error) {
    console.error('✗ Template check failed:', error.message);
    return false;
  }
}

// Run check
const templateOk = await checkTemplate(123);
if (!templateOk) {
  console.error('\n🛑 Template check failed. Fix before proceeding.\n');
  process.exit(1);
}

4. Data Validation Check

// ✅ Pre-Flight Step 4: Validate Request Data
async function checkRequestData(service, requestData) {
  console.log('\n=== Step 4: Request Data Validation ===\n');

  // Build validation endpoint
  const endpoint = `https://api.docs-dispatcher.io/api/${service}/validate`;

  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.JWT_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(requestData)
    });

    const validation = await response.json();

    if (validation.valid) {
      console.log('✓ Request data valid');

      if (validation.warnings?.length > 0) {
        console.log('\n⚠ Warnings:');
        validation.warnings.forEach(warn => {
          console.log(`  - ${warn.field}: ${warn.message}`);
        });
      }

      return true;
    } else {
      console.error('✗ Request data validation failed\n');
      console.error(`Errors found: ${validation.errors.length}\n`);

      validation.errors.forEach((error, index) => {
        console.error(`Error ${index + 1}:`);
        console.error(`  Field: ${error.field}`);
        console.error(`  Message: ${error.message}`);
        if (error.value !== undefined) {
          console.error(`  Current value: ${JSON.stringify(error.value)}`);
        }
        if (error.expected !== undefined) {
          console.error(`  Expected: ${JSON.stringify(error.expected)}`);
        }
        console.error();
      });

      return false;
    }

  } catch (error) {
    console.error('✗ Validation request failed:', error.message);
    return false;
  }
}

// Run check
const requestData = {
  providerName: 'qonto',
  documentType: 'INVOICE',
  template: {
    id: 123,
    data: {
      invoiceNumber: 'INV-2026-001',
      customer: { name: 'Acme Corp', email: '[email protected]' },
      items: [{ description: 'Service', quantity: 1, unitPrice: 1000 }],
      total: 1000
    }
  }
};

const dataOk = await checkRequestData('invoicing', requestData);
if (!dataOk) {
  console.error('\n🛑 Data validation failed. Fix errors before proceeding.\n');
  process.exit(1);
}

Complete Pre-Flight Function

// ✅ Complete Pre-Flight Check
async function preFlightCheck(service, requestData) {
  console.log('╔════════════════════════════════════════╗');
  console.log('║   DOCS-DISPATCHER PRE-FLIGHT CHECK   ║');
  console.log('╚════════════════════════════════════════╝');

  const checks = [
    { name: 'Authentication', fn: () => checkAuthentication() },
    { name: 'Configuration', fn: () => checkConfiguration(service, requestData.providerName) },
    { name: 'Template', fn: () => checkTemplate(requestData.template.id) },
    { name: 'Request Data', fn: () => checkRequestData(service, requestData) }
  ];

  const results = [];

  for (const check of checks) {
    try {
      const passed = await check.fn();
      results.push({ check: check.name, passed });

      if (!passed) {
        console.error(`\n🛑 ${check.name} check FAILED`);
        console.error('Fix issues above before proceeding.\n');
        return false;
      }
    } catch (error) {
      console.error(`\n✗ ${check.name} check threw error:`, error.message);
      results.push({ check: check.name, passed: false, error: error.message });
      return false;
    }
  }

  // All checks passed
  console.log('\n╔════════════════════════════════════════╗');
  console.log('║  ✓ ALL PRE-FLIGHT CHECKS PASSED      ║');
  console.log('║    Ready for dispatch                ║');
  console.log('╚════════════════════════════════════════╝\n');

  return true;
}

// Run complete check
const ready = await preFlightCheck('invoicing', requestData);
if (ready) {
  console.log('Proceeding with dispatch...');
  // Make actual dispatch call
}

Request Debugging

Debug Dispatch Request

// Debug actual dispatch request
async function debugDispatch(service, requestData) {
  console.log('\n=== Dispatching with Debug ===\n');

  const startTime = Date.now();

  // Log request
  console.log('Request:');
  console.log(JSON.stringify(requestData, null, 2));
  console.log();

  try {
    const response = await fetch(
      `https://api.docs-dispatcher.io/api/${service}`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.JWT_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestData)
      }
    );

    const duration = Date.now() - startTime;

    console.log(`Response received in ${duration}ms`);
    console.log(`Status: ${response.status} ${response.statusText}`);
    console.log('Headers:');
    response.headers.forEach((value, key) => {
      console.log(`  ${key}: ${value}`);
    });
    console.log();

    const result = await response.json();

    if (response.ok) {
      console.log('✓ Dispatch successful');
      console.log(`Dispatch ID: ${result.dispatchId}`);
      console.log('Response:');
      console.log(JSON.stringify(result, null, 2));

      return { success: true, result, duration };
    } else {
      console.error('✗ Dispatch failed');
      console.error('Error:', result.error);
      console.error('Message:', result.message);

      if (result.details) {
        console.error('Details:');
        console.error(JSON.stringify(result.details, null, 2));
      }

      if (result.requestId) {
        console.error(`\nRequest ID: ${result.requestId}`);
        console.error('Include this ID when contacting support');
      }

      return { success: false, error: result, duration };
    }

  } catch (error) {
    const duration = Date.now() - startTime;

    console.error('✗ Request failed with exception');
    console.error('Error:', error.message);
    console.error('Stack:', error.stack);

    return { success: false, error: error.message, duration };
  }
}

Response Analysis

Analyze Error Response

// Detailed error analysis
function analyzeErrorResponse(error, requestData) {
  console.log('\n=== Error Response Analysis ===\n');

  // Error category
  const category = {
    400: 'Client Error - Bad Request',
    401: 'Authentication Error',
    403: 'Authorization Error',
    404: 'Not Found',
    409: 'Conflict',
    422: 'Validation Error',
    429: 'Rate Limit Exceeded',
    500: 'Server Error',
    503: 'Service Unavailable'
  }[error.status] || 'Unknown Error';

  console.log(`Category: ${category}`);
  console.log(`Error Code: ${error.error}`);
  console.log(`Message: ${error.message}`);
  console.log();

  // Suggest fixes
  const fixes = {
    'provider_not_configured': [
      'Configure provider at https://app.docs-dispatcher.io/admin/configs',
      'Or specify providerName explicitly in request'
    ],
    'token_expired': [
      'Refresh JWT token',
      'POST https://api.docs-dispatcher.io/auth'
    ],
    'template_not_found': [
      'Verify template ID exists',
      'Check template.id in request matches existing template',
      'List templates at https://app.docs-dispatcher.io/templates'
    ],
    'validation_failed': [
      'Fix validation errors listed in details',
      'Use validation endpoint before dispatch',
      'Check required fields match template schema'
    ],
    'rate_limit_exceeded': [
      'Implement exponential backoff',
      'Wait for retry-after period',
      'Reduce request frequency'
    ],
    'provider_error': [
      'Check provider credentials in config',
      'Verify provider API status',
      'Review provider-specific requirements'
    ]
  };

  const suggestions = fixes[error.error] || ['Contact support with requestId'];

  console.log('Suggested Fixes:');
  suggestions.forEach((fix, index) => {
    console.log(`  ${index + 1}. ${fix}`);
  });
  console.log();

  // Context
  if (error.details) {
    console.log('Error Context:');
    console.log(JSON.stringify(error.details, null, 2));
    console.log();
  }

  // Request that caused error
  console.log('Failed Request:');
  console.log(JSON.stringify(requestData, null, 2));
  console.log();

  // Support info
  if (error.requestId) {
    console.log('Support Information:');
    console.log(`  Request ID: ${error.requestId}`);
    console.log('  Email: [email protected]');
    console.log('  Include: Request ID, error details, expected behavior');
  }
}

Log Analysis

Enable Debug Logging

// Comprehensive logger
class DebugLogger {
  constructor() {
    this.logs = [];
    this.startTime = Date.now();
  }

  log(level, category, message, data = null) {
    const entry = {
      timestamp: new Date().toISOString(),
      elapsed: Date.now() - this.startTime,
      level: level,
      category: category,
      message: message,
      data: data
    };

    this.logs.push(entry);

    const icon = { info: 'ℹ', success: '✓', warning: '⚠', error: '✗' }[level] || '•';
    const color = {
      info: '\x1b[36m',    // Cyan
      success: '\x1b[32m', // Green
      warning: '\x1b[33m', // Yellow
      error: '\x1b[31m'    // Red
    }[level] || '\x1b[0m';

    console.log(
      `${color}[${entry.elapsed}ms] ${icon} [${category}] ${message}\x1b[0m`
    );

    if (data) {
      console.log(JSON.stringify(data, null, 2));
    }
  }

  info(category, message, data) {
    this.log('info', category, message, data);
  }

  success(category, message, data) {
    this.log('success', category, message, data);
  }

  warning(category, message, data) {
    this.log('warning', category, message, data);
  }

  error(category, message, data) {
    this.log('error', category, message, data);
  }

  export() {
    return {
      logs: this.logs,
      summary: {
        total: this.logs.length,
        byLevel: this.logs.reduce((acc, log) => {
          acc[log.level] = (acc[log.level] || 0) + 1;
          return acc;
        }, {}),
        duration: Date.now() - this.startTime
      }
    };
  }

  saveToFile(filename) {
    const fs = require('fs');
    fs.writeFileSync(filename, JSON.stringify(this.export(), null, 2));
    console.log(`\nLogs saved to: ${filename}`);
  }
}

// Usage
const logger = new DebugLogger();

logger.info('AUTH', 'Starting authentication');
logger.success('AUTH', 'JWT token valid');
logger.info('CONFIG', 'Checking configuration');
logger.warning('CONFIG', 'Using company default (no user override)');
logger.info('DISPATCH', 'Sending request');
logger.error('DISPATCH', 'Request failed', { error: 'provider_error' });

// Save logs
logger.saveToFile('dispatch-debug.json');

Network Debugging

Test Network Connectivity

// Network diagnostic tool
async function networkDiagnostics() {
  console.log('\n=== Network Diagnostics ===\n');

  const endpoints = [
    { name: 'API Health', url: 'https://api.docs-dispatcher.io/health' },
    { name: 'Dispatcher API', url: 'https://api.docs-dispatcher.io/health' },
    { name: 'API Dispatch', url: 'https://api.docs-dispatcher.io/api/invoicing' }
  ];

  for (const endpoint of endpoints) {
    console.log(`Testing: ${endpoint.name}`);
    console.log(`  URL: ${endpoint.url}`);

    const start = Date.now();

    try {
      const response = await fetch(endpoint.url, {
        method: endpoint.url.includes('/api/') ? 'POST' : 'GET',
        headers: {
          'Authorization': `Bearer ${process.env.JWT_TOKEN}`,
          'Content-Type': 'application/json'
        }
      });

      const duration = Date.now() - start;

      console.log(`  Status: ${response.status} ${response.statusText}`);
      console.log(`  Time: ${duration}ms`);

      if (response.ok || response.status === 400) {
        console.log('  ✓ Reachable\n');
      } else {
        console.log(`  ⚠ Unexpected status\n`);
      }

    } catch (error) {
      const duration = Date.now() - start;
      console.log(`  ✗ Failed: ${error.message}`);
      console.log(`  Time: ${duration}ms\n`);

      // Diagnose error
      if (error.code === 'ENOTFOUND') {
        console.log('  Issue: DNS resolution failed');
        console.log('  Check: DNS settings, internet connectivity');
      } else if (error.code === 'ECONNREFUSED') {
        console.log('  Issue: Connection refused');
        console.log('  Check: Firewall, proxy settings');
      } else if (error.code === 'ETIMEDOUT') {
        console.log('  Issue: Connection timeout');
        console.log('  Check: Network latency, timeout settings');
      }
      console.log();
    }
  }
}

DNS and SSL Check

// Check DNS and SSL
async function checkDnsAndSsl() {
  console.log('\n=== DNS and SSL Check ===\n');

  const hosts = [
    'api.docs-dispatcher.io',
    'api.docs-dispatcher.io'
  ];

  for (const host of hosts) {
    console.log(`Host: ${host}`);

    // DNS lookup (Node.js)
    try {
      const dns = require('dns').promises;
      const addresses = await dns.resolve4(host);
      console.log(`  ✓ DNS resolves to: ${addresses.join(', ')}`);
    } catch (error) {
      console.log(`  ✗ DNS failed: ${error.message}`);
    }

    // SSL check
    try {
      const https = require('https');
      const options = {
        host: host,
        port: 443,
        method: 'GET',
        path: '/',
        rejectUnauthorized: true
      };

      await new Promise((resolve, reject) => {
        const req = https.request(options, (res) => {
          console.log(`  ✓ SSL certificate valid`);
          resolve();
        });

        req.on('error', reject);
        req.end();
      });

    } catch (error) {
      console.log(`  ✗ SSL error: ${error.message}`);
    }

    console.log();
  }
}

Provider Health Checks

// Check provider API status
async function checkProviderHealth(providerName) {
  console.log(`\n=== Provider Health Check: ${providerName} ===\n`);

  // Status pages
  const statusPages = {
    qonto: 'https://status.qonto.com/api/v2/status.json',
    brevo: 'https://status.brevo.com/api/v2/status.json',
    yousign: 'https://status.yousign.com/api/v2/status.json',
    ovh: 'https://status.ovh.com/api/status'
  };

  const statusUrl = statusPages[providerName];

  if (!statusUrl) {
    console.log('No public status page available');
    return null;
  }

  try {
    const response = await fetch(statusUrl, { timeout: 5000 });
    const data = await response.json();

    const isOperational = data.status?.indicator === 'none' ||
                         data.status === 'operational';

    if (isOperational) {
      console.log('✓ Provider API operational');
    } else {
      console.warn('⚠ Provider API issues detected');
      console.log(`Status: ${data.status?.description || data.status}`);
    }

    if (data.page?.updated_at) {
      console.log(`Last updated: ${data.page.updated_at}`);
    }

    return { operational: isOperational, data };

  } catch (error) {
    console.log(`Cannot check status: ${error.message}`);
    console.log(`Check manually: ${statusUrl.replace('/api/v2/status.json', '')}`);
    return null;
  }
}

When to Contact Support

Support Criteria

Contact support when:

1. All pre-flight checks pass but dispatch still fails

2. Intermittent issues that can't be reproduced consistently

3. Provider errors that aren't documented

4. Performance issues (slow responses, timeouts)

5. Unexpected behavior not covered in documentation

Gather Support Information

// Collect information for support ticket
async function collectSupportInfo(service, requestData, errorResponse) {
  console.log('\n=== Collecting Support Information ===\n');

  const info = {
    timestamp: new Date().toISOString(),
    environment: {
      nodeVersion: process.version,
      platform: process.platform,
      arch: process.arch
    },
    request: {
      service: service,
      endpoint: `https://api.docs-dispatcher.io/api/${service}`,
      method: 'POST',
      data: requestData
    },
    error: errorResponse,
    system: {
      // Redact sensitive data
      jwtPresent: !!process.env.JWT_TOKEN,
      jwtLength: process.env.JWT_TOKEN?.length,
      configuredProviders: await getConfiguredProviders()
    }
  };

  // Save to file
  const filename = `support-info-${Date.now()}.json`;
  require('fs').writeFileSync(filename, JSON.stringify(info, null, 2));

  console.log('Support information saved to:', filename);
  console.log('\nWhen contacting support:');
  console.log('  Email: [email protected]');
  console.log('  Subject: Dispatch Error - [Brief description]');
  console.log('  Include:');
  console.log(`    - This file: ${filename}`);
  console.log(`    - Request ID: ${errorResponse.requestId}`);
  console.log('    - Steps to reproduce');
  console.log('    - Expected vs actual behavior');

  return info;
}

async function getConfiguredProviders() {
  try {
    const configs = await fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${process.env.JWT_TOKEN}` }
    }).then(r => r.json());

    return configs.map(c => ({
      service: c.service,
      provider: c.providerName,
      active: c.isActive
    }));
  } catch {
    return [];
  }
}

Complete Debug Workflow

// Master debug function
async function debugCompleteWorkflow(service, requestData) {
  console.log('╔══════════════════════════════════════════════════╗');
  console.log('║   DOCS-DISPATCHER COMPLETE DEBUG WORKFLOW      ║');
  console.log('╚══════════════════════════════════════════════════╝\n');

  const logger = new DebugLogger();

  try {
    // Phase 1: Pre-flight
    logger.info('PREFLIGHT', 'Starting pre-flight checks');

    const authOk = await checkAuthentication();
    if (!authOk) throw new Error('Authentication failed');
    logger.success('PREFLIGHT', 'Authentication OK');

    const configOk = await checkConfiguration(service, requestData.providerName);
    if (!configOk) throw new Error('Configuration failed');
    logger.success('PREFLIGHT', 'Configuration OK');

    const templateOk = await checkTemplate(requestData.template.id);
    if (!templateOk) throw new Error('Template check failed');
    logger.success('PREFLIGHT', 'Template OK');

    const dataOk = await checkRequestData(service, requestData);
    if (!dataOk) throw new Error('Data validation failed');
    logger.success('PREFLIGHT', 'Data validation OK');

    // Phase 2: Dispatch
    logger.info('DISPATCH', 'Sending request');
    const result = await debugDispatch(service, requestData);

    if (result.success) {
      logger.success('DISPATCH', 'Request successful', {
        dispatchId: result.result.dispatchId,
        duration: result.duration
      });

      console.log('\n✓ Debug workflow completed successfully');
      return result.result;
    } else {
      logger.error('DISPATCH', 'Request failed', result.error);

      // Phase 3: Error analysis
      logger.info('ANALYSIS', 'Analyzing error');
      analyzeErrorResponse(result.error, requestData);

      // Phase 4: Provider check
      if (requestData.providerName) {
        logger.info('PROVIDER', `Checking ${requestData.providerName} health`);
        await checkProviderHealth(requestData.providerName);
      }

      // Phase 5: Support info
      logger.info('SUPPORT', 'Collecting support information');
      await collectSupportInfo(service, requestData, result.error);

      throw new Error('Dispatch failed - see analysis above');
    }

  } catch (error) {
    logger.error('WORKFLOW', 'Debug workflow failed', {
      error: error.message,
      stack: error.stack
    });

    // Save logs
    logger.saveToFile(`debug-${Date.now()}.json`);

    throw error;
  }
}

// Run complete debug workflow
await debugCompleteWorkflow('invoicing', requestData);

Quick Reference

Command-Line Debug Tool

#!/bin/bash
# debug-dispatch.sh

echo "=== Docs-Dispatcher Debug Tool ==="
echo

# Check JWT
if [ -z "$JWT_TOKEN" ]; then
  echo "✗ JWT_TOKEN not set"
  exit 1
fi
echo "✓ JWT_TOKEN found"

# Test authentication
echo
echo "Testing authentication..."
curl -s -o /dev/null -w "Status: %{http_code}\n" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  https://api.docs-dispatcher.io/api/v1/users/me

# Test API health
echo
echo "Testing API health..."
curl -s https://api.docs-dispatcher.io/health | jq .

# Validate request
echo
echo "Validating request..."
curl -X POST https://api.docs-dispatcher.io/api/invoicing/validate \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request.json \
  | jq .

echo
echo "Debug complete"

Summary

Pre-flight checklist (always run):

1. ✅ Authentication valid?

2. ✅ Configuration active?

3. ✅ Template accessible?

4. ✅ Request data valid?

When debugging failures:

1. Analyze error response

2. Check provider health

3. Review logs

4. Test network connectivity

5. Collect support info if needed

Support contact criteria:

• Pre-flight checks pass

• Intermittent issues

• Undocumented errors

• Performance problems

• Unexpected behavior

Include in support tickets:

• Request ID

• Support info JSON

• Steps to reproduce

• Expected vs actual behavior

• Debug logs

Related Documentation

• Common Errors - Error codes and solutions

• Provider Issues - Provider-specific debugging

• Configuration Problems - Config debugging

• Validation - Pre-validation guide

Remember: 90% of issues can be caught with pre-flight checks. Always validate before dispatching!