🔌Configuration Problems

Complete guide to debugging Docs-Dispatcher's hybrid 3-tier configuration resolution system.

Overview

This guide covers:

Hybrid config resolution (Company → User → Explicit)
Missing provider configuration
Invalid credentials
Config validation errors
Config inheritance issues
Testing config resolution
Debug logging for config
Common configuration mistakes

Configuration Architecture

3-Tier Resolution System

┌─────────────────────────────────────────────────────────────┐
│ Tier 1: COMPANY DEFAULT CONFIG                             │
│ - Set by admin at company level                            │
│ - Applies to all users in company                          │
│ - Lowest priority                                           │
└────────────────────────┬────────────────────────────────────┘
                         │ (can be overridden)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│ Tier 2: USER OVERRIDE CONFIG                               │
│ - Set by user for their account                            │
│ - Overrides company default                                │
│ - Medium priority                                           │
└────────────────────────┬────────────────────────────────────┘
                         │ (can be overridden)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│ Tier 3: EXPLICIT providerName IN REQUEST                   │
│ - Specified in API request body                            │
│ - Overrides all other configs                              │
│ - Highest priority (ALWAYS WINS)                           │
└─────────────────────────────────────────────────────────────┘

Resolution Order

When Dispatcher receives a request:

Check for explicit providerName in request → Use if present
Check for user override config → Use if exists
Check for company default config → Use if exists
No config found → Return 400 error

Common Configuration Issues

Issue 1: "Provider not configured"

Error:

{
  "error": "provider_not_configured",
  "message": "No configuration found for service 'invoicing' and provider 'qonto'",
  "details": {
    "provider": "qonto",
    "service": "invoicing",
    "userId": 123,
    "companyId": 456,
    "checkedLevels": ["explicit", "user", "company"]
  }
}

Causes:

Provider not configured at any level
Configuration exists but is inactive
Wrong service/provider combination
User/company mismatch

Solution 1: Check All Configuration Levels

// Complete configuration checker
async function checkProviderConfiguration(providerName, service) {
  console.log(`\n=== Configuration Check: ${providerName} (${service}) ===\n`);

  const jwt = await getJWT();

  // 1. Check if provider is valid for service
  console.log('1. Validating provider/service combination...');
  const validProviders = {
    invoicing: ['ipaidthat', 'pennylane', 'qonto', 'superpdp'],
    esign: ['signaturit', 'universign', 'yousign'],
    postal: ['mysendingbox'],
    sms: ['brevo', 'ovh', 'sms_factor', 'sms_magic'],
    email: [], // SMTP only
    file: [], // Internal
    upload: [] // Internal
  };

  if (!validProviders[service].includes(providerName)) {
    console.error(
      `✗ Invalid provider '${providerName}' for service '${service}'\n` +
      `  Valid providers: ${validProviders[service].join(', ')}`
    );
    return { valid: false, reason: 'invalid_provider' };
  }
  console.log('✓ Provider valid for service');

  // 2. Check user config
  console.log('\n2. Checking user configuration...');
  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.providerName === providerName && c.service === service
  );

  if (userConfig) {
    console.log('✓ User config found');
    console.log(`  - Active: ${userConfig.isActive}`);
    console.log(`  - Default: ${userConfig.isDefault}`);

    if (!userConfig.isActive) {
      console.warn('  ⚠ Config is INACTIVE');
      return {
        valid: false,
        reason: 'config_inactive',
        level: 'user',
        config: userConfig
      };
    }

    return {
      valid: true,
      level: 'user',
      config: userConfig
    };
  }
  console.log('✗ No user config');

  // 3. Check company config
  console.log('\n3. Checking company configuration...');
  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.providerName === providerName && c.service === service
  );

  if (companyConfig) {
    console.log('✓ Company config found');
    console.log(`  - Active: ${companyConfig.isActive}`);
    console.log(`  - Default: ${companyConfig.isDefault}`);

    if (!companyConfig.isActive) {
      console.warn('  ⚠ Config is INACTIVE');
      return {
        valid: false,
        reason: 'config_inactive',
        level: 'company',
        config: companyConfig
      };
    }

    return {
      valid: true,
      level: 'company',
      config: companyConfig
    };
  }
  console.log('✗ No company config');

  // 4. Not configured at any level
  console.error(
    `\n✗ Provider '${providerName}' not configured at any level.\n\n` +
    'Configure at:\n' +
    '- Company level: https://app.docs-dispatcher.io/admin/configs\n' +
    '- User level: https://app.docs-dispatcher.io/account/configs\n'
  );

  return {
    valid: false,
    reason: 'not_configured'
  };
}

// Usage
const check = await checkProviderConfiguration('qonto', 'invoicing');
if (!check.valid) {
  console.error(`Configuration invalid: ${check.reason}`);
} else {
  console.log(`✓ Using ${check.level} config`);
}

Solution 2: Create Missing Configuration

// Create provider configuration
async function createProviderConfig(providerName, service, config, level = 'company') {
  const jwt = await getJWT();

  const endpoint = level === 'user'
    ? 'https://api.docs-dispatcher.io/api/v1/users/me/configs'
    : 'https://api.docs-dispatcher.io/api/v1/companies/me/configs';

  const configData = {
    service: service,
    providerName: providerName,
    isDefault: true,
    isActive: true,
    config: config
  };

  console.log(`Creating ${level} config for ${providerName}...`);

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

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Config creation failed: ${error.message}`);
  }

  const result = await response.json();
  console.log('✓ Configuration created:', result.id);

  return result;
}

// Example: Create Qonto config
await createProviderConfig('qonto', 'invoicing', {
  apiKey: 'qonto_live_abc123',
  organizationSlug: 'acme-corp',
  useSandbox: false
}, 'company');

Issue 2: Configuration Priority Confusion

Scenario:

Company default: Qonto
User override: PennyLane
Request: providerName = "ipaidthat"

Which provider will be used? → iPaidThat (explicit always wins)

Understanding Priority

// Visualize configuration priority
async function showConfigPriority(service) {
  const jwt = await getJWT();

  console.log(`\n=== Configuration Priority for ${service} ===\n`);

  // Get all configs
  const [userConfigs, companyConfigs] = await Promise.all([
    fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json()),
    fetch('/api/v1/companies/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json())
  ]);

  const userConfig = userConfigs.find(c => c.service === service);
  const companyConfig = companyConfigs.find(c => c.service === service);

  // Show priority
  console.log('Priority 1 (Highest): EXPLICIT providerName in request');
  console.log('  → Always used if specified\n');

  console.log('Priority 2: USER override');
  if (userConfig) {
    console.log(`  ✓ Configured: ${userConfig.providerName}`);
    console.log(`    Active: ${userConfig.isActive}`);
  } else {
    console.log('  ✗ Not configured');
  }
  console.log();

  console.log('Priority 3 (Lowest): COMPANY default');
  if (companyConfig) {
    console.log(`  ✓ Configured: ${companyConfig.providerName}`);
    console.log(`    Active: ${companyConfig.isActive}`);
  } else {
    console.log('  ✗ Not configured');
  }
  console.log();

  // Show what will be used
  console.log('Without explicit provider in request:');
  if (userConfig?.isActive) {
    console.log(`  → Will use: ${userConfig.providerName} (user override)`);
  } else if (companyConfig?.isActive) {
    console.log(`  → Will use: ${companyConfig.providerName} (company default)`);
  } else {
    console.log('  → ERROR: No configuration available');
  }
}

// Usage
await showConfigPriority('invoicing');

Output:

=== Configuration Priority for invoicing ===

Priority 1 (Highest): EXPLICIT providerName in request
  → Always used if specified

Priority 2: USER override
  ✓ Configured: pennylane
    Active: true

Priority 3 (Lowest): COMPANY default
  ✓ Configured: qonto
    Active: true

Without explicit provider in request:
  → Will use: pennylane (user override)

Issue 3: Invalid Credentials

Error:

{
  "error": "provider_error",
  "message": "Authentication failed with provider 'qonto'",
  "details": {
    "providerError": {
      "code": "INVALID_CREDENTIALS",
      "message": "API key is invalid or expired"
    }
  }
}

Solution: Validate Credentials

// Comprehensive credential validator
async function validateProviderCredentials(providerName, config) {
  console.log(`\n=== Validating ${providerName} credentials ===\n`);

  const validators = {
    qonto: validateQontoCredentials,
    pennylane: validatePennyLaneCredentials,
    ipaidthat: validateIpaidThatCredentials,
    brevo: validateBrevoCredentials,
    ovh: validateOVHCredentials,
    universign: validateUniversignCredentials,
    signaturit: validateSignaturitCredentials,
    yousign: validateYousignCredentials,
    mysendingbox: validateMySendingBoxCredentials
  };

  const validator = validators[providerName];

  if (!validator) {
    console.log(`No automatic validator for ${providerName}`);
    console.log('Manual validation required.');
    return null;
  }

  try {
    const result = await validator(config);
    console.log('✓ Credentials valid');
    return result;
  } catch (error) {
    console.error(`✗ Credential validation failed: ${error.message}`);
    throw error;
  }
}

// Provider-specific validators

async function validateQontoCredentials(config) {
  const response = await fetch('https://api.qonto.com/v2/organizations', {
    headers: { 'Authorization': `Bearer ${config.apiKey}` }
  });

  if (!response.ok) {
    throw new Error(
      'Qonto API key invalid. ' +
      'Generate new key at https://app.qonto.com/settings/api'
    );
  }

  const data = await response.json();
  console.log('Organizations:', data.organizations.length);
  data.organizations.forEach(org => {
    console.log(`  - ${org.slug}: ${org.name}`);
  });

  // Verify org slug
  const orgExists = data.organizations.some(o =>
    o.slug === config.organizationSlug
  );

  if (!orgExists) {
    throw new Error(
      `Organization slug '${config.organizationSlug}' not found. ` +
      `Available: ${data.organizations.map(o => o.slug).join(', ')}`
    );
  }

  return data;
}

async function validatePennyLaneCredentials(config) {
  const response = await fetch(
    `https://api.pennylane.com/api/v1/companies/${config.companyId}`,
    { headers: { 'Authorization': `Bearer ${config.apiKey}` } }
  );

  if (!response.ok) {
    throw new Error(
      'PennyLane credentials invalid. ' +
      'Check API key and company ID at https://app.pennylane.com/settings/api'
    );
  }

  const company = await response.json();
  console.log(`Company: ${company.name}`);

  return company;
}

async function validateBrevoCredentials(config) {
  const response = await fetch('https://api.brevo.com/v3/account', {
    headers: { 'api-key': config.apiKey }
  });

  if (!response.ok) {
    throw new Error(
      'Brevo API key invalid. ' +
      'Get new key at https://app.brevo.com/settings/keys/api'
    );
  }

  const account = await response.json();
  console.log(`Account: ${account.email}`);
  console.log(`SMS credits: ${account.plan.credits.sms}`);

  return account;
}

async function validateUniversignCredentials(config) {
  // Universign uses username/password, not API key
  const response = await fetch(config.apiUrl + '/organizations', {
    headers: {
      'Authorization': 'Basic ' + btoa(`${config.username}:${config.password}`)
    }
  });

  if (!response.ok) {
    throw new Error(
      'Universign credentials invalid. ' +
      'Check username and password'
    );
  }

  const orgs = await response.json();
  console.log('Organizations:', orgs.length);

  return orgs;
}

Issue 4: Config Validation Errors

Error:

{
  "error": "config_validation_failed",
  "message": "Provider configuration is invalid",
  "details": {
    "errors": [
      {
        "field": "config.apiKey",
        "message": "API key is required"
      },
      {
        "field": "config.organizationSlug",
        "message": "Organization slug must be lowercase alphanumeric"
      }
    ]
  }
}

Solution: Validate Config Schema

// Validate config structure before saving
function validateConfigSchema(providerName, config) {
  const schemas = {
    qonto: {
      required: ['apiKey', 'organizationSlug'],
      optional: ['useSandbox'],
      validators: {
        apiKey: (v) => typeof v === 'string' && v.length > 0,
        organizationSlug: (v) => /^[a-z0-9\-]+$/.test(v),
        useSandbox: (v) => typeof v === 'boolean'
      }
    },
    pennylane: {
      required: ['apiKey', 'companyId'],
      optional: ['useSandbox'],
      validators: {
        apiKey: (v) => typeof v === 'string' && v.length > 0,
        companyId: (v) => typeof v === 'string' && v.length > 0,
        useSandbox: (v) => typeof v === 'boolean'
      }
    },
    brevo: {
      required: ['apiKey'],
      optional: ['sender'],
      validators: {
        apiKey: (v) => typeof v === 'string' && v.startsWith('xkeysib-'),
        sender: (v) => typeof v === 'string' && v.length <= 11
      }
    },
    universign: {
      required: ['username', 'password', 'apiUrl'],
      optional: ['webhookSecret'],
      validators: {
        username: (v) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
        password: (v) => typeof v === 'string' && v.length >= 8,
        apiUrl: (v) => v.startsWith('https://'),
        webhookSecret: (v) => typeof v === 'string'
      }
    }
  };

  const schema = schemas[providerName];

  if (!schema) {
    console.warn(`No schema validation for ${providerName}`);
    return { valid: true };
  }

  const errors = [];

  // Check required fields
  for (const field of schema.required) {
    if (!(field in config)) {
      errors.push({
        field: `config.${field}`,
        message: `${field} is required`
      });
      continue;
    }

    // Validate field value
    const validator = schema.validators[field];
    if (validator && !validator(config[field])) {
      errors.push({
        field: `config.${field}`,
        message: `${field} has invalid format or value`,
        value: config[field]
      });
    }
  }

  // Validate optional fields if present
  for (const field of schema.optional) {
    if (field in config) {
      const validator = schema.validators[field];
      if (validator && !validator(config[field])) {
        errors.push({
          field: `config.${field}`,
          message: `${field} has invalid format or value`,
          value: config[field]
        });
      }
    }
  }

  if (errors.length > 0) {
    console.error('Config validation errors:');
    errors.forEach(err => {
      console.error(`  - ${err.field}: ${err.message}`);
    });
    return { valid: false, errors };
  }

  console.log('✓ Config schema valid');
  return { valid: true };
}

// Usage
const config = {
  apiKey: 'qonto_live_abc123',
  organizationSlug: 'acme-corp',
  useSandbox: false
};

const validation = validateConfigSchema('qonto', config);
if (!validation.valid) {
  throw new Error('Invalid configuration');
}

Issue 5: Config Inheritance Issues

Scenario: User expects company default but user override is active.

// Show effective configuration
async function showEffectiveConfig(service) {
  const jwt = await getJWT();

  console.log(`\n=== Effective Configuration for ${service} ===\n`);

  // Get configs
  const [userConfigs, companyConfigs] = await Promise.all([
    fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json()),
    fetch('/api/v1/companies/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json())
  ]);

  const userConfig = userConfigs.find(c => c.service === service);
  const companyConfig = companyConfigs.find(c => c.service === service);

  // Determine effective config
  let effective = null;
  let source = null;

  if (userConfig?.isActive) {
    effective = userConfig;
    source = 'user override';
  } else if (companyConfig?.isActive) {
    effective = companyConfig;
    source = 'company default';
  }

  // Display
  if (effective) {
    console.log(`Provider: ${effective.providerName}`);
    console.log(`Source: ${source}`);
    console.log(`Active: ${effective.isActive}`);
    console.log(`Default: ${effective.isDefault}`);
    console.log();

    // Show inheritance
    if (source === 'user override' && companyConfig) {
      console.log('Note: User override is hiding company default:');
      console.log(`  Company has: ${companyConfig.providerName}`);
      console.log(`  User overrides with: ${userConfig.providerName}`);
      console.log();
      console.log('To use company default:');
      console.log('  1. Remove user override, OR');
      console.log('  2. Deactivate user override, OR');
      console.log('  3. Specify providerName in request explicitly');
    }
  } else {
    console.error('✗ No active configuration found');
    console.log();
    console.log('To fix:');
    console.log('  1. Configure at company level (admin), OR');
    console.log('  2. Configure at user level, OR');
    console.log('  3. Always specify providerName explicitly in requests');
  }
}

Testing Configuration Resolution

Test Resolution Logic

// Test which provider will be used
async function testConfigResolution(service, explicitProvider = null) {
  console.log(`\n=== Testing Config Resolution ===`);
  console.log(`Service: ${service}`);
  console.log(`Explicit provider: ${explicitProvider || 'none'}`);
  console.log();

  const jwt = await getJWT();

  // Get configs
  const [userConfigs, companyConfigs] = await Promise.all([
    fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json()),
    fetch('/api/v1/companies/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json())
  ]);

  const userConfig = userConfigs.find(c => c.service === service);
  const companyConfig = companyConfigs.find(c => c.service === service);

  // Resolution logic
  let resolved = null;
  let source = null;

  if (explicitProvider) {
    // Check if explicit provider is configured
    const explicitConfig =
      userConfigs.find(c => c.providerName === explicitProvider) ||
      companyConfigs.find(c => c.providerName === explicitProvider);

    if (explicitConfig) {
      resolved = explicitProvider;
      source = 'explicit (configured)';
    } else {
      resolved = explicitProvider;
      source = 'explicit (NOT configured - will fail)';
    }
  } else if (userConfig?.isActive) {
    resolved = userConfig.providerName;
    source = 'user override';
  } else if (companyConfig?.isActive) {
    resolved = companyConfig.providerName;
    source = 'company default';
  } else {
    resolved = null;
    source = 'NONE - request will fail';
  }

  // Results
  console.log('Resolution steps:');
  console.log(`  1. Check explicit: ${explicitProvider ? '✓ ' + explicitProvider : '✗ none'}`);
  console.log(`  2. Check user: ${userConfig?.isActive ? '✓ ' + userConfig.providerName : '✗ none'}`);
  console.log(`  3. Check company: ${companyConfig?.isActive ? '✓ ' + companyConfig.providerName : '✗ none'}`);
  console.log();

  if (resolved) {
    console.log(`✓ Will use provider: ${resolved} (${source})`);
  } else {
    console.error('✗ NO PROVIDER WILL BE USED - Request will fail with 400');
    console.log();
    console.log('To fix: Configure provider at company or user level');
  }

  return { resolved, source };
}

// Test scenarios
await testConfigResolution('invoicing'); // No explicit
await testConfigResolution('invoicing', 'pennylane'); // With explicit
await testConfigResolution('sms'); // Different service

Simulate Dispatch

// Simulate what dispatch will do
async function simulateDispatch(service, requestData) {
  console.log(`\n=== Simulating Dispatch ===\n`);

  // 1. Extract explicit provider
  const explicitProvider = requestData.providerName;
  console.log(`Step 1: Check explicit provider in request`);
  console.log(`  → ${explicitProvider || 'none'}`);

  // 2. Resolve config
  const resolution = await testConfigResolution(service, explicitProvider);

  if (!resolution.resolved) {
    console.error('\n✗ Dispatch will FAIL: No provider configuration');
    return { success: false, error: 'provider_not_configured' };
  }

  // 3. Verify provider valid for service
  const validProviders = {
    invoicing: ['ipaidthat', 'pennylane', 'qonto', 'superpdp'],
    esign: ['signaturit', 'universign', 'yousign'],
    postal: ['mysendingbox'],
    sms: ['brevo', 'ovh', 'sms_factor', 'sms_magic']
  };

  console.log(`\nStep 2: Verify provider valid for service`);
  if (!validProviders[service].includes(resolution.resolved)) {
    console.error(`  ✗ Provider '${resolution.resolved}' not valid for ${service}`);
    return { success: false, error: 'invalid_provider' };
  }
  console.log(`  ✓ Valid`);

  // 4. Check config credentials
  console.log(`\nStep 3: Check provider credentials`);
  console.log(`  (Would test API credentials here)`);

  // Success
  console.log(`\n✓ Dispatch would succeed with provider: ${resolution.resolved}`);
  return {
    success: true,
    provider: resolution.resolved,
    source: resolution.source
  };
}

// Test
const result = await simulateDispatch('invoicing', {
  documentType: 'INVOICE',
  template: { id: 123, data: {} }
  // No providerName = will use default
});

Debug Logging

Enable Config Debug Mode

// Comprehensive config logger
class ConfigDebugger {
  constructor(jwt) {
    this.jwt = jwt;
    this.logs = [];
  }

  log(level, message, data = null) {
    const entry = {
      timestamp: new Date().toISOString(),
      level: level,
      message: message,
      data: data
    };

    this.logs.push(entry);

    const icon = {
      info: 'ℹ',
      success: '✓',
      warning: '⚠',
      error: '✗'
    }[level] || '';

    console.log(`[${entry.timestamp}] ${icon} ${message}`);
    if (data) {
      console.log(JSON.stringify(data, null, 2));
    }
  }

  async debugConfigResolution(service, providerName = null) {
    this.log('info', `Starting config resolution debug for ${service}`);

    // Step 1: Get user configs
    this.log('info', 'Fetching user configurations...');
    const userConfigs = await fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${this.jwt}` }
    }).then(r => r.json());

    this.log('info', `Found ${userConfigs.length} user configs`);
    const userConfig = userConfigs.find(c =>
      c.service === service &&
      (!providerName || c.providerName === providerName)
    );

    if (userConfig) {
      this.log('success', 'User config found', {
        provider: userConfig.providerName,
        active: userConfig.isActive,
        default: userConfig.isDefault
      });
    } else {
      this.log('info', 'No matching user config');
    }

    // Step 2: Get company configs
    this.log('info', 'Fetching company configurations...');
    const companyConfigs = await fetch('/api/v1/companies/me/configs', {
      headers: { 'Authorization': `Bearer ${this.jwt}` }
    }).then(r => r.json());

    this.log('info', `Found ${companyConfigs.length} company configs`);
    const companyConfig = companyConfigs.find(c =>
      c.service === service &&
      (!providerName || c.providerName === providerName)
    );

    if (companyConfig) {
      this.log('success', 'Company config found', {
        provider: companyConfig.providerName,
        active: companyConfig.isActive,
        default: companyConfig.isDefault
      });
    } else {
      this.log('info', 'No matching company config');
    }

    // Step 3: Resolution
    this.log('info', 'Resolving configuration...');

    let resolved = null;
    let source = null;

    if (providerName) {
      resolved = providerName;
      source = 'explicit';
      this.log('success', 'Using explicit provider from request', {
        provider: providerName
      });
    } else if (userConfig?.isActive) {
      resolved = userConfig.providerName;
      source = 'user';
      this.log('success', 'Using user override config', {
        provider: resolved
      });
    } else if (companyConfig?.isActive) {
      resolved = companyConfig.providerName;
      source = 'company';
      this.log('success', 'Using company default config', {
        provider: resolved
      });
    } else {
      this.log('error', 'No configuration resolved - dispatch will fail');
    }

    // Summary
    this.log('info', 'Resolution complete', {
      resolved: resolved,
      source: source,
      willSucceed: resolved !== null
    });

    return {
      resolved,
      source,
      userConfig,
      companyConfig,
      logs: this.logs
    };
  }

  exportLogs() {
    return JSON.stringify(this.logs, null, 2);
  }
}

// Usage
const debugger = new ConfigDebugger(jwt);
const result = await debugger.debugConfigResolution('invoicing', 'qonto');

// Export logs
console.log('\n=== Debug Logs ===');
console.log(debugger.exportLogs());

Common Configuration Mistakes

Mistake 1: Inactive Configuration

// Check for inactive configs
async function findInactiveConfigs() {
  const jwt = await getJWT();

  const [userConfigs, companyConfigs] = await Promise.all([
    fetch('/api/v1/users/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json()),
    fetch('/api/v1/companies/me/configs', {
      headers: { 'Authorization': `Bearer ${jwt}` }
    }).then(r => r.json())
  ]);

  const inactive = [
    ...userConfigs.filter(c => !c.isActive).map(c => ({ ...c, level: 'user' })),
    ...companyConfigs.filter(c => !c.isActive).map(c => ({ ...c, level: 'company' }))
  ];

  if (inactive.length > 0) {
    console.log('\n⚠ Inactive configurations found:\n');
    inactive.forEach(config => {
      console.log(`- ${config.service} / ${config.providerName} (${config.level})`);
      console.log(`  To activate: Set isActive: true in Templater UI`);
    });
  } else {
    console.log('✓ No inactive configurations');
  }

  return inactive;
}

Mistake 2: Multiple Defaults

// Check for multiple defaults per service
async function checkMultipleDefaults() {
  const jwt = await getJWT();

  const configs = await fetch('/api/v1/users/me/configs', {
    headers: { 'Authorization': `Bearer ${jwt}` }
  }).then(r => r.json());

  const byService = configs.reduce((acc, config) => {
    if (!acc[config.service]) acc[config.service] = [];
    acc[config.service].push(config);
    return acc;
  }, {});

  console.log('\n=== Checking for multiple defaults ===\n');

  for (const [service, serviceConfigs] of Object.entries(byService)) {
    const defaults = serviceConfigs.filter(c => c.isDefault);

    if (defaults.length > 1) {
      console.warn(`⚠ Service '${service}' has ${defaults.length} defaults:`);
      defaults.forEach(d => {
        console.log(`  - ${d.providerName}`);
      });
      console.log('  Fix: Keep only one as default\n');
    } else if (defaults.length === 1) {
      console.log(`✓ ${service}: ${defaults[0].providerName}`);
    } else {
      console.log(`ℹ ${service}: No default set`);
    }
  }
}

Mistake 3: Wrong Service Type

// Detect configs with wrong service type
async function validateServiceTypes() {
  const jwt = await getJWT();

  const validServiceTypes = [
    'invoicing', 'esign', 'postal', 'sms', 'email', 'file', 'upload'
  ];

  const configs = await fetch('/api/v1/users/me/configs', {
    headers: { 'Authorization': `Bearer ${jwt}` }
  }).then(r => r.json());

  const invalid = configs.filter(c =>
    !validServiceTypes.includes(c.service)
  );

  if (invalid.length > 0) {
    console.error('\n✗ Invalid service types found:\n');
    invalid.forEach(config => {
      console.error(`- Config ID ${config.id}: service='${config.service}'`);
      console.error(`  Valid types: ${validServiceTypes.join(', ')}`);
    });
  } else {
    console.log('✓ All service types valid');
  }

  return invalid;
}

Best Practices

1. Use Company Defaults

// Set up company defaults for all users
const companyDefaults = {
  invoicing: 'qonto',
  esign: 'universign',
  postal: 'mysendingbox',
  sms: 'brevo'
};

for (const [service, provider] of Object.entries(companyDefaults)) {
  await createProviderConfig(provider, service, {
    // Provider-specific config
  }, 'company');
}

2. User Overrides for Exceptions

// Only override when necessary
// Example: Sales rep with personal accounting
await createProviderConfig('pennylane', 'invoicing', {
  apiKey: 'personal_api_key',
  companyId: 'personal_company'
}, 'user');

3. Explicit Provider for Edge Cases

// Use explicit provider for special cases
const dispatchToSpecialProvider = async (data) => {
  return await dispatch({
    providerName: 'ipaidthat', // Explicit override
    documentType: 'INVOICE',
    template: data
  });
};

4. Validate Before Saving

// Always validate before saving config
async function saveConfig(providerName, service, config, level) {
  // 1. Validate schema
  const schemaCheck = validateConfigSchema(providerName, config);
  if (!schemaCheck.valid) {
    throw new Error('Config schema validation failed');
  }

  // 2. Test credentials
  try {
    await validateProviderCredentials(providerName, config);
  } catch (error) {
    throw new Error(`Credential validation failed: ${error.message}`);
  }

  // 3. Save config
  return await createProviderConfig(providerName, service, config, level);
}

Common Errors - Error codes and solutions
Provider Issues - Provider-specific problems
Provider Configurations - Setup guide
Validation - Test configurations

Summary

Key configuration concepts:

3-tier resolution: Company → User → Explicit (highest priority)
Explicit always wins: providerName in request overrides all
Check all levels: User override may hide company default
Validate credentials: Test API keys before saving
Use company defaults: Set defaults for all users
User overrides sparingly: Only for special cases
Debug systematically: Check user → company → explicit
Keep configs active: Inactive configs won't be used

Quick debugging:

Check if provider configured: GET /api/v1/users/me/configs
Check company config: GET /api/v1/companies/me/configs
Verify credentials: Test provider API directly
Test resolution: Use simulation tool
Check active status: Ensure isActive: true

Configuration is key to successful dispatching. When in doubt, use explicit providerName in requests to bypass resolution complexity.

PreviousProvider Issues NextDebug Checklist

Last updated 5 days ago

hashtagOverview

hashtagConfiguration Architecture

hashtag3-Tier Resolution System

hashtagResolution Order

hashtagCommon Configuration Issues

hashtagIssue 1: "Provider not configured"

hashtagSolution 1: Check All Configuration Levels

hashtagSolution 2: Create Missing Configuration

hashtagIssue 2: Configuration Priority Confusion

hashtagUnderstanding Priority

hashtagIssue 3: Invalid Credentials

hashtagSolution: Validate Credentials

hashtagIssue 4: Config Validation Errors

hashtagSolution: Validate Config Schema

hashtagIssue 5: Config Inheritance Issues

hashtagTesting Configuration Resolution

hashtagTest Resolution Logic

hashtagSimulate Dispatch

hashtagDebug Logging

hashtagEnable Config Debug Mode

hashtagCommon Configuration Mistakes

hashtagMistake 1: Inactive Configuration

hashtagMistake 2: Multiple Defaults

hashtagMistake 3: Wrong Service Type

hashtagBest Practices

hashtag1. Use Company Defaults

hashtag2. User Overrides for Exceptions

hashtag3. Explicit Provider for Edge Cases

hashtag4. Validate Before Saving

hashtagRelated Documentation

hashtagSummary

Overview

Configuration Architecture

3-Tier Resolution System

Resolution Order

Common Configuration Issues

Issue 1: "Provider not configured"

Solution 1: Check All Configuration Levels

Solution 2: Create Missing Configuration

Issue 2: Configuration Priority Confusion

Understanding Priority

Issue 3: Invalid Credentials

Solution: Validate Credentials

Issue 4: Config Validation Errors

Solution: Validate Config Schema

Issue 5: Config Inheritance Issues

Testing Configuration Resolution

Test Resolution Logic

Simulate Dispatch

Debug Logging

Enable Config Debug Mode

Common Configuration Mistakes

Mistake 1: Inactive Configuration

Mistake 2: Multiple Defaults

Mistake 3: Wrong Service Type

Best Practices

1. Use Company Defaults

2. User Overrides for Exceptions

3. Explicit Provider for Edge Cases

4. Validate Before Saving

Related Documentation

Summary