Configuration

The SDK accepts a configuration object when you create a new CircadifySDK instance. Only apiKey is required.

Basic Configuration

Pass a CircadifyConfig object to the constructor. Only apiKey is required — everything else has sensible defaults.

import { CircadifySDK } from '@circadify/sdk';

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
});

Full Configuration

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  baseUrl: 'https://api.circadify.com',
  measurementDuration: 30,
  debug: false,

  onProgress: (event) => {
    console.log(`${event.phase}: ${event.percent}%`);
  },

  onQualityWarning: (warning) => {
    console.warn(warning.type, warning.message);
  },
});

Configuration Reference

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your API key (`ck_test_` for test, `ck_live_` for production).
`baseUrl`	`string`	`'https://api.circadify.com'`	Custom API base URL.
`measurementDuration`	`number`	`30`	Target measurement duration in seconds.
`debug`	`boolean`	`false`	Enable debug logging to the browser console.
`onProgress`	`function`	`undefined`	Called during measurement with progress updates.
`onQualityWarning`	`function`	`undefined`	Called when scan quality degrades (lighting, motion, face position, occlusion).
`wasmConfig`	`WasmConfig`	`undefined`	Override CDN URLs for self-hosted WASM modules.

CircadifyConfig Interface

interface CircadifyConfig {
  apiKey: string;
  baseUrl?: string;
  measurementDuration?: number;
  debug?: boolean;
  onProgress?: (event: MeasurementProgress) => void;
  onQualityWarning?: (warning: QualityWarning) => void;
  wasmConfig?: WasmConfig;
}

Progress Callback

The onProgress callback fires throughout measurement with a MeasurementProgress object:

interface MeasurementProgress {
  percent: number;    // 0-100
  phase: 'initializing' | 'readiness' | 'capturing' | 'uploading' | 'processing';
  elapsed: number;    // Seconds since measurement started
  remaining?: number; // Estimated seconds remaining (when available)
}

Phase	Progress	What’s happening
`initializing`	0–5%	Creating session, loading vision engine
`readiness`	5–10%	Opening camera, waiting for quality checks to pass
`capturing`	10–60%	Capturing and preprocessing frames
`uploading`	60–80%	Uploading preprocessed data
`processing`	80–100%	Backend inference running

Quality Warning Callback

The onQualityWarning callback fires when capture quality degrades:

interface QualityWarning {
  type: 'lighting' | 'motion' | 'face_position' | 'occlusion';
  message: string;
  severity: 'low' | 'medium' | 'high';
}

Use this to show guidance to the user — “Hold still”, “Move to better lighting”, etc.

Self-Hosting WASM

For air-gapped or regulated environments, host the vision engine files on your own infrastructure:

interface WasmConfig {
  mediapipeWasmUrl?: string;
  mediapipeModelUrl?: string;
  opencvUrl?: string;
}

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  wasmConfig: {
    mediapipeWasmUrl: 'https://cdn.yourcompany.com/circadify/wasm/',
    mediapipeModelUrl: 'https://cdn.yourcompany.com/circadify/models/',
    opencvUrl: 'https://cdn.yourcompany.com/circadify/geometry.js',
  },
});

Contact support@circadify.com for the WASM distribution package.

Next Steps

Methods — SDK method reference
Events — Event handling and callbacks
Error Codes — Error handling reference