Configuration

The Cordia SDK is highly configurable. All options have sensible defaults so you can get started with just apiKey and your Discord client reference.

All Options

Option (JS / Python)	Type	Default	Description
`apiKey / api_key`	`string / str`	required	Your bot's API key from the Cordia dashboard
`discordClient / bot`	`discord.js Client / discord.py Bot`	recommended	Discord client object used to auto-detect bot ID and shard metadata
`botId / bot_id`	`string / str`	optional	Manual bot ID override (rarely needed)
`baseUrl / base_url`	`string / str`	`https://api.cordialane.com/api/v1`	API base URL (or set `CORDIA_API_URL` env var)
`heartbeatInterval / heartbeat_interval`	`number / int`	`30000`	Heartbeat interval in milliseconds (min: 30000)
`autoHeartbeat / auto_heartbeat`	`boolean / bool`	`true / True`	Auto-start heartbeat on client creation
`debug`	`boolean / bool`	`false / False`	Enable debug logging to console
`batchSize / batch_size`	`number / int`	`10`	Max events before auto-flush (1-100)
`flushInterval / flush_interval`	`number / int`	`60000`	The base auto-flush interval. Note: v1.2.1+ uses Adaptive Flushing which speeds up during traffic spikes.
`autoScale / auto_scale`	`boolean / bool`	`false / False`	Automatically increase batch limits if rate limited (now enhanced with Adaptive Flushing logic).
`maxRetries` (JS only)	`number`	`3`	Max retry attempts on failure (0-10)
`timeout` (JS only)	`number`	`10000`	Request timeout in milliseconds (min: 1000)

Adaptive Flushing (v1.2.1+)

Cordia v1.2.1 introduced Adaptive Flushing. Instead of a rigid timer, the SDK now "breathes" with your bot's traffic:

Busy Period: If your bot hits the batchSize before the timer, the SDK automatically speeds up the flush frequency (reducing the interval by 5s each time, down to a minimum of 15s).
Quiet Period: When the queue becomes empty, the SDK gradually slows back down until it reaches your original flushInterval.

This ensures high-traffic spikes are cleared quickly for real-time analytics, while low-traffic bots save on network and CPU resources.

URL Resolution

The API base URL is resolved in this priority order:

config.baseUrl / base_url — explicitly passed in config
CORDIA_API_URL — environment variable
https://api.cordialane.com/api/v1 — default fallback

JavaScript / TypeScript

Development setup

typescript

// Option 1: Pass directly in config
const cordia = new CordiaClient({
  apiKey: 'your-key',
  discordClient: client,
  baseUrl: 'https://api.cordialane.com/api/v1',
});

// Option 2: Use environment variable
// .env file: CORDIA_API_URL=https://api.cordialane.com/api/v1
const cordia = new CordiaClient({
  apiKey: 'your-key',
  discordClient: client,
  // baseUrl will use CORDIA_API_URL automatically
});

Python

Development setup

python

# Option 1: Pass directly in config
cordia_client = cordia.CordiaClient(
    api_key="your-key",
    bot=bot,
    base_url="https://api.cordialane.com/api/v1",
)

# Option 2: Use environment variable
import os
cordia_client = cordia.CordiaClient(
    api_key=os.getenv("CORDIA_API_KEY"),
    bot=bot,
    base_url=os.getenv("CORDIA_API_URL", "https://api.cordialane.com/api/v1"),
)

Environment Variables

Variable	Description
`CORDIA_API_URL`	Override the default API base URL
`CORDIA_API_KEY`	Your bot's API key

Full Config Example

JavaScript / TypeScript

Full configuration

typescript

import { CordiaClient } from 'cordia';

const cordia = new CordiaClient({
  // Required
  apiKey: process.env.CORDIA_API_KEY!,
  discordClient: client,

  // Optional — Heartbeat
  heartbeatInterval: 30000,  // 30 seconds
  autoHeartbeat: true,

  // Optional — Event batching
  batchSize: 50,
  flushInterval: 60000,  // 60 seconds
  autoScale: true,       // Auto-increase if rate limited

  // Optional — Reliability
  maxRetries: 3,
  timeout: 10000,  // 10 seconds

  // Optional — Debugging
  debug: process.env.NODE_ENV === 'development',
});

Python

Full configuration

python

import cordia
import os

cordia_client = cordia.CordiaClient(
    # Required
    api_key=os.getenv("CORDIA_API_KEY"),
    bot=bot,

    # Optional — Heartbeat
    heartbeat_interval=30000,  # 30 seconds
    auto_heartbeat=True,

    # Optional — Event batching
    batch_size=50,
    flush_interval=60000,  # 60 seconds
    auto_scale=True,       # Auto-increase if rate limited

    # Optional — Debugging
    debug=True,
)
# Don't forget to call start() to initialize the background tasks
cordia_client.start(bot.loop)

⚠️Validation

The SDK validates all config options on initialization. If you pass invalid values (e.g., negative batch size), it will throw a descriptive error at startup rather than failing silently later.

Startup Verification & Handshaking

When the Cordia SDK initializes, it performs an asynchronous background handshake with the Cordia API to verify your apiKey and auto-detected bot identity.

ℹ️How Handshake Works

Success: If the key is valid, the SDK continues silently in the background.
Version Handshake (New in v1.2.1): The API will also check your SDK version. If a newer version is available, the SDK will print a friendly nudge in your console to update:
text
```
[Cordia] 🆕 A new SDK version is available: 1.2.1 (You are on 1.1.0)
```
Invalid Key (401/404): If the key is invalid or your bot cannot be found, the SDK will log a loud error message to your console and safely disable itself. This prevents it from spamming failed requests or wasting your bot's resources.
Network Error: If the Cordia API is temporarily unreachable, the SDK will log a warning but remain active, queuing events and attempting to verify again later.

💡Shard Detection Logs (Debug Mode)

If you enable debug, the SDK logs the detected shardId / totalShardsonce on startup (first heartbeat). If you pass a Discord client too early (before it's ready), Cordia will warn and keep resolving shard metadata lazily.

Installation

Easy Setup (Ready-to-use)