Client Configuration

Learn how to configure the Cognipeer Console SDK client for different environments and use cases.

Basic Configuration

import { ConsoleClient } from '@cognipeer/console-sdk';

const client = new ConsoleClient({
  apiKey: 'your-api-key',
});

Configuration Options

API Key (Required)

Your Cognipeer Console API token:

const client = new ConsoleClient({
  apiKey: process.env.COGNIPEER_API_KEY!,
});

Security Best Practice

Always use environment variables for API keys. Never commit API keys to version control.

Base URL (Optional)

Override the default API endpoint:

const client = new ConsoleClient({
  apiKey: 'your-api-key',
  baseURL: 'https://custom.api.example.com',
});

Default: https://console.cognipeer.com/api/client/v1

Timeout (Optional)

Request timeout in milliseconds:

const client = new ConsoleClient({
  apiKey: 'your-api-key',
  timeout: 30000, // 30 seconds
});

Default: 60000 (60 seconds)

Max Retries (Optional)

Maximum number of retry attempts for failed requests:

const client = new ConsoleClient({
  apiKey: 'your-api-key',
  maxRetries: 5,
});

Default: 3

Only 429 Too Many Requests and 502/503/504 responses are retried — statuses where the request was rejected before any side effect. A 500 is never retried automatically, since it's ambiguous whether the server processed the request before failing; handle that case in your own code if you need to.

If the response includes a Retry-After header, the client waits that long instead of its default exponential backoff — except past 30 seconds, where it gives up waiting and throws immediately instead of blocking your call for minutes. The thrown CognipeerAPIError carries the parsed value on retryAfterMs either way, so you can reschedule the request yourself when that happens.

If you have your own retry logic around SDK calls, set maxRetries: 0 to avoid retrying the same request twice.

Custom Fetch (Optional)

Provide a custom fetch implementation:

import fetch from 'node-fetch';

const client = new ConsoleClient({
  apiKey: 'your-api-key',
  fetch: fetch as any,
});

Environment-Specific Configurations

Development

const client = new ConsoleClient({
  apiKey: process.env.DEV_API_KEY!,
  baseURL: 'http://localhost:3000/api/client/v1',
  timeout: 120000, // Longer timeout for debugging
});

Production

const client = new ConsoleClient({
  apiKey: process.env.PROD_API_KEY!,
  baseURL: 'https://console.cognipeer.com/api/client/v1',
  timeout: 60000,
  maxRetries: 3,
});

Testing

const client = new ConsoleClient({
  apiKey: 'test-api-key',
  baseURL: 'http://localhost:3000/api/client/v1',
  maxRetries: 0, // No retries in tests
});

Configuration Patterns

Singleton Pattern

Create a single client instance for your application:

// config/client.ts
let clientInstance: ConsoleClient | null = null;

export function getClient(): ConsoleClient {
  if (!clientInstance) {
    clientInstance = new ConsoleClient({
      apiKey: process.env.COGNIPEER_API_KEY!,
    });
  }
  return clientInstance;
}

// usage.ts
import { getClient } from './config/client';

const client = getClient();

Factory Pattern

Create clients dynamically:

function createClient(options: {
  environment: 'development' | 'production';
  apiKey: string;
}): ConsoleClient {
  const baseURLs = {
    development: 'http://localhost:3000/api/client/v1',
    production: 'https://console.cognipeer.com/api/client/v1',
  };

  return new ConsoleClient({
    apiKey: options.apiKey,
    baseURL: baseURLs[options.environment],
  });
}

const client = createClient({
  environment: 'production',
  apiKey: process.env.COGNIPEER_API_KEY!,
});

Multi-Tenant Pattern

Manage multiple clients for different tenants:

class ClientManager {
  private clients: Map<string, ConsoleClient> = new Map();

  getClient(tenantId: string, apiKey: string): ConsoleClient {
    if (!this.clients.has(tenantId)) {
      this.clients.set(
        tenantId,
        new ConsoleClient({ apiKey })
      );
    }
    return this.clients.get(tenantId)!;
  }
}

const manager = new ClientManager();
const clientA = manager.getClient('tenant-a', 'key-a');
const clientB = manager.getClient('tenant-b', 'key-b');

Error Handling Configuration

Configure error handling globally:

import { CognipeerAPIError } from '@cognipeer/console-sdk';

const client = new ConsoleClient({
  apiKey: process.env.COGNIPEER_API_KEY!,
});

async function safeRequest<T>(fn: () => Promise<T>): Promise<T | null> {
  try {
    return await fn();
  } catch (error) {
    if (error instanceof CognipeerAPIError) {
      console.error('API Error:', error.message);
      console.error('Status:', error.statusCode);
    }
    return null;
  }
}

// Usage
const response = await safeRequest(() =>
  client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }],
  })
);

Logging Configuration

Add request/response logging:

class LoggingClient extends ConsoleClient {
  async chat.completions.create(params: any) {
    console.log('[Request]', JSON.stringify(params, null, 2));
    const response = await super.chat.completions.create(params);
    console.log('[Response]', JSON.stringify(response, null, 2));
    return response;
  }
}

Environment Variables

Recommended environment variables:

# .env.example
COGNIPEER_API_KEY=your-api-key
COGNIPEER_BASE_URL=https://console.cognipeer.com/api/client/v1
COGNIPEER_TIMEOUT=60000
COGNIPEER_MAX_RETRIES=3

Load configuration from environment:

const client = new ConsoleClient({
  apiKey: process.env.COGNIPEER_API_KEY!,
  baseURL: process.env.COGNIPEER_BASE_URL,
  timeout: parseInt(process.env.COGNIPEER_TIMEOUT || '60000'),
  maxRetries: parseInt(process.env.COGNIPEER_MAX_RETRIES || '3'),
});

Best Practices

1. Use Environment Variables: Never hardcode API keys
2. Singleton Pattern: Reuse client instances
3. Error Handling: Always wrap requests in try/catch
4. Timeouts: Set appropriate timeouts for your use case
5. Retries: Configure retries based on your requirements
6. Logging: Add logging for debugging in development

See Also

• Authentication
• Error Handling
• Getting Started