@scalda/sdk

Scalda product-analytics SDK for browser and Node.js. Event-based, with client-side batching, a persisted queue, automatic sessions, and retry with exponential backoff. The SDK is the "thick client" — the server just validates and stores (see the OpenAPI contract at GET /api/analytics/v1/openapi.yaml).

Verification status: conformance-verified locally — 37 unit tests plus the shared cross-language harness bash sdk/e2e.sh typescript (see e2e/README.md). This is the reference SDK against which the other languages' contract is frozen (sdk/CONFORMANCE.md).

Install

pnpm add @scalda/sdk

Browser

import { Scalda } from '@scalda/sdk/browser';

const analytics = new Scalda({ apiKey: 'skc_…' }); // client key (public)

analytics.track('button_clicked', { button_id: 'signup' });
analytics.identify('user_42', { plan: 'pro' });
await analytics.flush();

Node.js

import { Scalda } from '@scalda/sdk/node';

const analytics = new Scalda({ apiKey: 'sks_…' }); // server key (private)

analytics.track('purchase', { amount: 1990, currency: 'RUB' });
analytics.identify('user_42', { plan: 'pro' });
await analytics.flush();      // call on graceful shutdown
await analytics.shutdown();   // final flush + stop the timer

Key kinds. skc_* keys are meant for public client bundles (cannot backdate events). sks_* keys are private, server-side only, and may backdate. Never ship an sks_* key in a browser bundle.

API

| Method | Description | |---|---| | new Scalda(options) | Configure and start. apiKey is required. | | track(name, properties?) | Queue an event. Returns immediately. | | identify(userId, userProperties?) | Bind a user id to this device. | | setUserProperties(properties) | Update user properties without identify. | | reset() | Logout — clear user id and session, keep device id. | | flush() | Force-send the queue. Returns a Promise. | | shutdown() | Final flush + stop the flush timer. |

Options

| Option | Default | | |---|---|---| | apiKey | — | required | | endpoint | Scalda cloud (https://scalda.ai/api/analytics/v1/events) | full URL of …/api/analytics/v1/events | | flushIntervalMs | 10000 | periodic flush | | flushAtQueueSize | 50 | flush when the queue reaches this size | | maxQueueSize | 10000 | drop oldest beyond this (emits $queue_overflow_dropped) | | sessionTimeoutMs | 1800000 | idle timeout that ends a session | | disableSessionTracking | false | | | debug | false | log to console | | optOut | false | GDPR kill switch — everything becomes a no-op | | defaultProperties | {} | merged into every event's properties | | gzip | false | gzip the request body (Node only) |

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build

End-to-end against a local Scalda api: see e2e/README.md.