Initialization

Overview

The Invariance SDK is initialized through the static `Invariance.init()` factory method. This creates a configured client instance that manages transport (batching and flushing receipts to the API), observability (tracing, anomaly detection), and optional monitor polling.

Before initializing, you typically generate an Ed25519 keypair using `Invariance.generateKeypair()`. The private key is used to sign every receipt, creating a cryptographic audit trail. The public key is registered with the server so signatures can be verified independently.

The client uses a batched transport layer that queues receipts and flushes them periodically (default: every 5 seconds or 50 receipts). When you're done, call `inv.shutdown()` to flush remaining receipts and clean up timers.

Architecture

The Invariance class is a thin orchestrator that owns a Transport instance (HTTP batching), an InvarianceTracer (observability), and optional monitor polling. Sessions and agents are created through it but manage their own receipt chains independently.

Important Notes

Quick Example

import { Invariance } from '@invariance/sdk';

// Generate a signing keypair (do this once, store securely)
const { privateKey, publicKey } = Invariance.generateKeypair();

// Initialize the SDK
const inv = Invariance.init({
  apiKey: 'dev_your_api_key',
  privateKey,
});

// ... use inv.session(), inv.wrap(), etc. ...

// Clean shutdown — flushes remaining receipts
await inv.shutdown();

Type Definitions

interface InvarianceConfig {
  apiKey: string;
  apiUrl?: string;
  privateKey?: string;
  policies?: PolicyRule[];
  flushIntervalMs?: number;
  maxBatchSize?: number;
  maxQueueSize?: number;
  onError?: ErrorHandler;
  mode?: 'DEV' | 'PROD';
  sampleRate?: number;
  anomalyThreshold?: number;
  onAnomaly?: (node: TraceEvent) => void;
  devOutput?: 'ui' | 'console' | 'both';
  captureReplaySnapshots?: boolean;
  onMonitorTrigger?: (event: MonitorTriggerEvent) => void;
  monitorPollIntervalMs?: number;
}

API Reference

Walkthrough

npm install @invariance/sdk

import { Invariance } from '@invariance/sdk';

const { privateKey, publicKey } = Invariance.generateKeypair();
// Save privateKey to .env or secrets manager

const inv = Invariance.init({
  apiKey: process.env.INVARIANCE_API_KEY!,
  privateKey: process.env.INVARIANCE_PRIVATE_KEY!,
  flushIntervalMs: 5000,
  maxBatchSize: 50,
  mode: 'PROD',
  onError: (err) => console.error('[Invariance]', err),
});

const healthy = await inv.healthCheck();
if (!healthy) throw new Error('Cannot reach Invariance API');

process.on('SIGINT', async () => {
  await inv.shutdown();
  process.exit(0);
});

Configuration

Error Handling

import { InvarianceError } from '@invariance/sdk';

try {
  const inv = Invariance.init({ apiKey: '' });
} catch (err) {
  if (err instanceof InvarianceError) {
    console.error(err.code);    // 'INIT_FAILED'
    console.error(err.message); // 'apiKey is required'
  }
}

Use Cases

• Initialize the SDK in your application entry point with API key and signing key
• Generate keypairs for new agents or during onboarding
• Configure batching intervals for high-throughput vs. low-latency use cases
• Set up policy rules at initialization to enforce guardrails across all actions

Related Modules