Skip to main content

Configuration

Learn how to configure the Conviso Node SDK for your specific needs.

Basic Configuration​

The minimum configuration requires only your Conviso API key:

import { CDPClient } from '@codematic.io/cdp-node';

const client = new CDPClient({
  cdpApiKey: 'your-cdp-api-key'
});

Configuration Examples​

Development Environment​

const client = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY,
  debug: true,
  timeout: 15000,
  maxConcurrentRequests: 5
});

Production Environment​

const client = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY,
  debug: false,
  timeout: 10000,
  maxConcurrentRequests: 20,
  cdpLogger: productionLogger
});

Migration Scenario (Dual-Write)​

const client = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY,
  sendToCustomerIo: true,
  customerIo: {
    siteId: process.env.CUSTOMERIO_SITE_ID,
    apiKey: process.env.CUSTOMERIO_API_KEY,
    region: 'us'
  },
  debug: false
});

Custom Endpoint with Logging​

import pino from 'pino';

const logger = pino();

const client = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY,
  cdpEndpoint: 'https://staging-api.opencdp.io/gateway/data-gateway',
  cdpLogger: {
    debug: (msg) => logger.debug(msg),
    error: (msg, ctx) => logger.error(ctx, msg),
    warn: (msg) => logger.warn(msg)
  }
});

Configuration Options​

CDPConfig Interface​

interface CDPConfig {
  // Required
  cdpApiKey: string;
  
  // Optional Conviso settings
  cdpEndpoint?: string;
  cdpLogger?: Logger;
  maxConcurrentRequests?: number;
  timeout?: number;
  
  // Optional Customer.io settings
  sendToCustomerIo?: boolean;
  customerIo?: {
    siteId: string;
    apiKey: string;
    region?: 'us' | 'eu';
  };
  
  // General settings
  debug?: boolean;
}

Required Options​

cdpApiKey​

Your Conviso API key for authentication.

cdpApiKey: 'your-cdp-api-key'
Keep Your API Key Secret

Never commit your API key to version control. Use environment variables instead:

cdpApiKey: process.env.CDP_API_KEY

Optional Conviso Settings​

cdpEndpoint​

Custom endpoint URL for the Conviso API. Defaults to https://api.opencdp.io/gateway/data-gateway.

cdpEndpoint: 'https://custom-endpoint.example.com'

Use case: Testing against a staging environment or using a custom proxy.

maxConcurrentRequests​

Maximum number of concurrent requests to the Conviso API. Default: 10, Maximum: 30.

maxConcurrentRequests: 20

Use case: Adjust based on your application's traffic patterns. Higher values allow more parallel requests but may impact system resources.

Concurrency Limiting

The SDK uses p-limit internally to prevent overwhelming the Conviso API with too many concurrent requests. Requests beyond the limit are queued automatically.

timeout​

timeout is in milliseconds. The built-in default is 10000 (10 seconds). Leave it unset to keep that default.

The timeout is how long the SDK waits for one gateway host to answer a single request. On a timeout, a network error, or a non-success status, the SDK tries the next host immediately:

  1. https://api.opencdp.io/gateway/data-gateway
  2. https://api.open-cdp.com/gateway/data-gateway
  3. https://api.open-cdp.xyz/gateway/data-gateway

To wait 5 seconds on each host, pass 5000:

timeout: 5000 // 5 seconds

cdpLogger​

Custom logger implementation. Defaults to console logging.

const customLogger = {
  debug: (message: string) => myLogger.debug(message),
  error: (message: string, context?: Record<string, any>) => myLogger.error(message, context),
  warn: (message: string) => myLogger.warn(message)
};

const client = new CDPClient({
  cdpApiKey: 'your-key',
  cdpLogger: customLogger
});

Use case: Integrate with your existing logging infrastructure (e.g., Winston, Pino, Bunyan).

Debug Mode​

debug​

Enable debug logging for troubleshooting. Default: false.

debug: true
Production Warning

Debug mode increases memory usage and log verbosity. Do not enable in production.

What gets logged in debug mode:

  • Connection status
  • Identify/track calls with user IDs
  • Email and push notification sends
  • Customer.io dual-write operations
  • Error details with stack traces

Customer.io Dual-Write​

sendToCustomerIo​

Enable dual-write to Customer.io. Default: false.

sendToCustomerIo: true

customerIo​

Customer.io credentials for dual-write mode.

customerIo: {
  siteId: 'your-customer-io-site-id',
  apiKey: 'your-customer-io-api-key',
  region: 'us' // or 'eu' for European data centers
}
When to Use Dual-Write

Dual-write is useful when migrating from Customer.io to Codematic CDP. It sends data to both platforms simultaneously. See our Dual-Write Guide for more information.

Environment Variables​

A recommended approach for managing configuration:

# .env file
CDP_API_KEY=your-cdp-api-key
CDP_ENDPOINT=https://api.opencdp.io/gateway/data-gateway
CDP_MAX_CONCURRENT=20
CDP_TIMEOUT=10000

# For dual-write
CUSTOMERIO_SITE_ID=your-site-id
CUSTOMERIO_API_KEY=your-api-key
CUSTOMERIO_REGION=us
// config.ts
import { CDPClient } from '@codematic.io/cdp-node';

export const cdpClient = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY!,
  cdpEndpoint: process.env.CDP_ENDPOINT,
  maxConcurrentRequests: parseInt(process.env.CDP_MAX_CONCURRENT || '10'),
  timeout: parseInt(process.env.CDP_TIMEOUT || '10000'),
  sendToCustomerIo: process.env.CUSTOMERIO_SITE_ID ? true : false,
  customerIo: process.env.CUSTOMERIO_SITE_ID ? {
    siteId: process.env.CUSTOMERIO_SITE_ID,
    apiKey: process.env.CUSTOMERIO_API_KEY!,
    region: (process.env.CUSTOMERIO_REGION as 'us' | 'eu') || 'us'
  } : undefined,
  debug: process.env.NODE_ENV === 'development'
});

Connection Testing​

Test your configuration with the ping() method:

const client = new CDPClient({
  cdpApiKey: process.env.CDP_API_KEY
});

try {
  await client.ping();
  console.log('Successfully connected to CDP!');
} catch (error) {
  console.error('Failed to connect:', error);
}
tip

Call ping() once during application startup to verify your configuration is correct. Don't call it before every request—connections are automatically managed via connection pooling.

Next Steps​