@cross-deck/node 0.1.0 → 1.1.0

package/dist/crossdeck-server-BXQaFjVx.d.mts

@@ -0,0 +1,1414 @@
+import { EventEmitter } from 'node:events';
+
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+interface CrossdeckErrorPayload {
+    type: CrossdeckErrorType;
+    /**
+     * Error code. The canonical set is the `CrossdeckErrorCode` literal
+     * union exported from `./error-codes` (derived from
+     * `CROSSDECK_ERROR_CODES`). Typed as `string` here so the SDK can
+     * still surface server-returned codes that aren't (yet) in the
+     * catalogue without a wholesale recompile of every consumer.
+     *
+     * For type-safe code comparisons in caller code, use:
+     *   `import { CrossdeckErrorCode, isCrossdeckErrorCode } from "@cross-deck/node"`
+     *   `if (isCrossdeckErrorCode(err.code) && err.code === "webhook_invalid_signature") {}`
+     */
+    code: string;
+    message: string;
+    requestId?: string;
+    status?: number;
+    retryAfterMs?: number;
+}
+declare class CrossdeckError extends Error {
+    readonly type: CrossdeckErrorType;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(payload: CrossdeckErrorPayload);
+    /**
+     * JSON representation suitable for structured loggers. Without this,
+     * `console.log(err)` and most log frameworks (Pino, Winston) emit
+     * only `name` + `message` + `stack` — losing `type`, `code`,
+     * `requestId`, `status`, `retryAfterMs`. With `toJSON`, calling
+     * `JSON.stringify(err)` or passing the error to a logger that
+     * serialises via JSON includes the full diagnostic surface.
+     *
+     * Stripe pattern. Critical for production observability.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Authentication failure — the secret key is missing, invalid, or
+ * revoked. Maps to `type: "authentication_error"`. Includes codes:
+ * `invalid_secret_key`, `webhook_invalid_signature`,
+ * `webhook_replay_window_exceeded`, and any 401 from the backend.
+ *
+ *   if (err instanceof CrossdeckAuthenticationError) { ... }
+ *
+ * Stripe pattern — typed subclasses make caller error-handling
+ * clean and let TypeScript narrow on `instanceof`.
+ */
+declare class CrossdeckAuthenticationError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Caller is authenticated but doesn't have permission for the
+ * requested resource. Maps to `type: "permission_error"`.
+ */
+declare class CrossdeckPermissionError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Request is malformed or violates a validation rule. Maps to
+ * `type: "invalid_request_error"`. Includes codes like
+ * `missing_user_id`, `missing_event_name`, `serialization_failed`,
+ * and any 4xx (other than 401/403/429) from the backend.
+ */
+declare class CrossdeckValidationError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Rate limit exceeded. Maps to `type: "rate_limit_error"`. Carries
+ * `retryAfterMs` from the server's `Retry-After` header — caller
+ * should back off and retry only after that delay.
+ */
+declare class CrossdeckRateLimitError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Network-layer failure — `fetch` threw, the request timed out, or
+ * the response body was unparseable. Maps to `type: "network_error"`
+ * with codes `fetch_failed`, `request_timeout`, or `internal_error`
+ * (`invalid_json_response`). Almost always transient; the SDK auto-
+ * retries event-queue flushes.
+ */
+declare class CrossdeckNetworkError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Backend returned a 5xx or the SDK detected an unexpected
+ * internal state. Maps to `type: "internal_error"`.
+ */
+declare class CrossdeckInternalError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Misconfigured SDK options at construction time. Maps to
+ * `type: "configuration_error"`. Includes codes like
+ * `invalid_secret_key`, `webhook_missing_secret`. Never retryable —
+ * always a developer fix.
+ */
+declare class CrossdeckConfigurationError extends CrossdeckError {
+    constructor(payload: CrossdeckErrorPayload);
+}
+/**
+ * Construct the right `CrossdeckError` subclass for a given payload's
+ * `type`. Used by `crossdeckErrorFromResponse` + by any internal call
+ * site that throws — gives every thrown error its semantic subclass
+ * without forcing every call site to know the mapping.
+ */
+declare function makeCrossdeckError(payload: CrossdeckErrorPayload): CrossdeckError;
+
+/**
+ * Breadcrumb ring buffer — context attached to every error report.
+ *
+ * Sentry / Datadog / Bugsnag all ship the same idea: keep a rolling
+ * record of the last N "things the process did" (HTTP calls, queued
+ * events, custom log lines, function invocations). When an error fires,
+ * attach the buffer so the engineer reading the error can see exactly
+ * how the process got into the broken state. The single most powerful
+ * debugging signal in error monitoring — without breadcrumbs, errors
+ * are stack traces with no story.
+ *
+ * Implementation: a circular buffer with a fixed cap. Old entries are
+ * evicted as new ones arrive. The default cap (50) is enough to cover
+ * ~5 minutes of typical request activity without ballooning the error
+ * payload. Sentry uses 100 by default but the SDK is more aggressive
+ * about size since we ship breadcrumbs over the wire with every error,
+ * not as a separate batch.
+ *
+ * Verbatim port of `@cross-deck/web/src/breadcrumbs.ts`. The data
+ * structure has zero browser dependencies; same code works in Node.
+ *
+ * Privacy: breadcrumbs from `track()` calls auto-flow through the same
+ * property sanitiser (`event-validation.ts`) before reaching this
+ * buffer, so a function/symbol/Error-shape in a tracked property won't
+ * crash subsequent error reports.
+ */
+type BreadcrumbCategory = "navigation" | "ui.click" | "ui.input" | "http" | "console" | "custom" | "info";
+type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+interface Breadcrumb {
+    /** epoch ms */
+    timestamp: number;
+    category: BreadcrumbCategory;
+    level?: BreadcrumbLevel;
+    /** Short human-readable description. */
+    message?: string;
+    /** Arbitrary key/value context for the crumb. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Stack-trace parser — normalises V8 / Firefox / Safari stack strings
+ * into a common frame shape.
+ *
+ * Why hand-rolled, not `stack-trace-js` / `error-stack-parser`: those
+ * weigh 5–15 KB after minification and we'd be pulling in their full
+ * feature matrix just for the parser. The patterns below cover the
+ * three shapes any modern runtime emits, totalling ~80 lines.
+ *
+ * Port of `@cross-deck/web/src/stack-parser.ts`. Two differences:
+ *   1. `isInAppFrame` heuristics are Node-aware (`node_modules/`,
+ *      `node:` core URLs, `internal/` Node internals,
+ *      `@cross-deck/node` self-skip) instead of browser-aware
+ *      (extension URLs, CDN hostnames).
+ *   2. Path separator handling accepts both `/` (Unix / V8 standard)
+ *      and `\` (Windows native paths sometimes leak into `error.stack`
+ *      on Node-for-Windows deployments).
+ *
+ * Defensive: never throws. An unparseable line becomes a `raw` frame
+ * with just the literal text. Engineers reading errors still get the
+ * raw stack as fallback.
+ */
+interface StackFrame {
+    /** Function name, or "?" if anonymous / unparseable. */
+    function: string;
+    /** Source file URL the frame ran in. Empty when unknown. */
+    filename: string;
+    /** 1-indexed line number, or 0 when unknown. */
+    lineno: number;
+    /** 1-indexed column number, or 0 when unknown. */
+    colno: number;
+    /**
+     * True when the frame is in the app's own code (best-effort:
+     * detected by URL not in node_modules/, not a node: core URL, etc.).
+     * Powers the dashboard's "your code vs library code" view.
+     */
+    in_app: boolean;
+    /** Raw line from the stack string for debugging when parse fails. */
+    raw: string;
+}
+
+/**
+ * Runtime info enrichment — the Node SDK equivalent of
+ * `@cross-deck/web/src/device-info.ts`.
+ *
+ * Detects the host platform (Lambda / Firebase Functions v1 / v2 /
+ * Cloud Run / Vercel / plain Node), region, service name + version,
+ * and instance ID. Auto-merged into every event's `properties` and
+ * every captured-error's `runtime` block.
+ *
+ * Privacy posture (parity with web's device-info.ts):
+ *   - No fingerprinting / hardware identifiers.
+ *   - No precise geolocation (region only — the platform's own metadata).
+ *   - No IP collection (backend logs the request IP for rate-limit
+ *     purposes; not stored on the event document).
+ *
+ * Detection runs ONCE per process — the returned `RuntimeInfo` is a
+ * frozen reference cached at module level. Zero per-event overhead.
+ * Caller-supplied overrides (serviceName / serviceVersion / appVersion
+ * via `CrossdeckServer` options) win over env-derived values on the
+ * first call — that's the SDK constructor.
+ */
+type RuntimeHost = "aws-lambda" | "azure-functions" | "google-app-engine" | "firebase-functions-v1" | "firebase-functions-v2" | "cloud-run" | "vercel" | "netlify" | "heroku" | "render" | "railway" | "fly" | "kubernetes" | "node";
+interface RuntimeInfo {
+    nodeVersion: string;
+    /** `os.platform()` — "darwin" | "linux" | "win32" | … */
+    platform: string;
+    /** `os.release()` — kernel release string, e.g. "5.15.0-1071-aws". */
+    platformRelease: string;
+    hostname: string;
+    host: RuntimeHost;
+    region: string | null;
+    serviceName: string | null;
+    serviceVersion: string | null;
+    /**
+     * Process-stable ID. Lambda log stream name when on Lambda; revision +
+     * pid on Cloud Run / Firebase v2; pid as string otherwise. Used by the
+     * dashboard to distinguish events from different instances of the same
+     * function name + version.
+     */
+    instanceId: string | null;
+    /** Caller-supplied app version. Attached as `appVersion` on every event. */
+    appVersion: string | null;
+}
+
+declare const SDK_NAME = "@cross-deck/node";
+declare const SDK_VERSION = "1.1.0";
+declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+declare const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * Pinned Crossdeck API version sent on every request as
+ * `Crossdeck-Api-Version`. Forward-compat with backend evolution —
+ * server-side breaking changes ship under a new version date; pinning
+ * means the SDK keeps speaking the version it was built against until
+ * the SDK explicitly bumps. Stripe pattern (`Stripe-Version`).
+ *
+ * Bump this in lockstep with backend version releases. Document the
+ * deprecation policy in CHANGELOG.
+ */
+declare const CROSSDECK_API_VERSION = "2025-01-01";
+interface HttpRetriesConfig {
+    /** Max attempts INCLUSIVE of the first call. Default 3 (1 initial + 2 retries). 1 disables retries. */
+    maxAttempts?: number;
+    /** Statuses considered retryable. Default: 408, 500, 502, 503, 504. */
+    retryableStatuses?: number[];
+}
+interface HttpRequestInfo {
+    method: "GET" | "POST";
+    url: string;
+    headers: Record<string, string>;
+    /** The serialised body string, when one was set. */
+    bodyPreview?: string;
+    /** Attempt number, starting at 1. Useful for distinguishing retries. */
+    attempt: number;
+}
+interface HttpResponseInfo {
+    method: "GET" | "POST";
+    url: string;
+    status: number;
+    durationMs: number;
+    attempt: number;
+    /** True if the request was a synthetic test-mode response. */
+    testMode: boolean;
+}
+
+/**
+ * Public wire types for @cross-deck/node.
+ *
+ * These mirror the v1 backend API (see backend/src/api/v1-types.ts) so the
+ * Node SDK speaks the same JSON shape the Web SDK + dashboard + workers do.
+ * Per-module types (Breadcrumb, CapturedError, StackFrame, RuntimeInfo,
+ * DebugSignal) live in the module that defines them — types.ts only carries
+ * the shared / wire-level surface.
+ *
+ * Keep in lockstep with `sdks/web/src/types.ts`. Same field names, same
+ * nullability. Where Node intentionally diverges from the web wire shape
+ * (no anonymousId-by-default, env implied by secret key prefix), the
+ * comment explains why.
+ */
+
+type Environment = "production" | "sandbox";
+type AuditRail = "apple" | "stripe" | "google" | "manual";
+interface PublicEntitlement {
+    object: "entitlement";
+    key: string;
+    isActive: boolean;
+    validUntil?: number | null;
+    source: {
+        rail: AuditRail;
+        productId: string;
+        subscriptionId: string;
+    };
+    updatedAt: number;
+}
+interface EntitlementsListResponse {
+    object: "list";
+    data: PublicEntitlement[];
+    crossdeckCustomerId: string;
+    env: Environment;
+}
+interface AliasResult {
+    object: "alias_result";
+    crossdeckCustomerId: string;
+    linked: Array<{
+        type: "developer";
+        id: string;
+    } | {
+        type: "anonymous";
+        id: string;
+    }>;
+    mergePending: boolean;
+    env: Environment;
+}
+interface IngestResponse {
+    object: "list";
+    received: number;
+    env: Environment;
+    throttled?: {
+        dropped: number;
+        sampleRate: number;
+        retryAfterMs: number;
+    };
+}
+interface PurchaseResult {
+    object: "purchase_result";
+    crossdeckCustomerId: string;
+    env: Environment;
+    entitlements: PublicEntitlement[];
+}
+/**
+ * Response shape from `GET /v1/sdk/heartbeat`. Used by
+ * `server.heartbeat()` to validate the secret key at boot and surface
+ * the backend's view of which project + app the key maps to. Clock
+ * skew between client + server can be detected from `serverTime`.
+ */
+interface HeartbeatResponse {
+    object: "heartbeat";
+    ok: true;
+    projectId: string;
+    appId: string;
+    platform: "node" | "web" | "ios" | "android";
+    env: Environment;
+    /** Server's view of `Date.now()` at the moment the response was sent. */
+    serverTime: number;
+}
+interface ForgetResult {
+    object: "forgot";
+    crossdeckCustomerId: string | null;
+    queuedAt: number;
+    env: Environment;
+}
+/**
+ * Options for `new CrossdeckServer(...)`. The trio of `secretKey` (required)
+ * + a sensible set of opt-in knobs covers the v1.0.0 surface.
+ *
+ * Defaults are tuned for serverless deployment (the dominant Node deployment
+ * shape today): flush-on-exit ON, error capture ON, entitlement TTL 60s,
+ * idempotent retried event queue, generous timeouts.
+ */
+interface CrossdeckServerOptions {
+    /** Secret API key. MUST start with `cd_sk_test_` or `cd_sk_live_`. Required. */
+    secretKey: string;
+    /** Override the API base URL. Default `https://api.cross-deck.com/v1`. */
+    baseUrl?: string;
+    /**
+     * Per-request abort timeout (ms). Default 15_000.
+     *
+     * On expiry: `CrossdeckError({ type: "network_error", code: "request_timeout" })`.
+     * Pass `0` to disable; per-call overrides allowed via the HTTP layer. A
+     * captive portal or hung connection would otherwise inherit the runtime's
+     * default and lock up the queue.
+     */
+    timeoutMs?: number;
+    /** Override the SDK version reported on the wire. Default: package version. */
+    sdkVersion?: string;
+    /**
+     * Optional informational appId stamped onto event batches. The server
+     * trusts the API key's resolved app routing — this is best-effort metadata,
+     * not the source of truth.
+     */
+    appId?: string;
+    /**
+     * Error capture configuration. Default: ON with `onUncaughtException` +
+     * `onUnhandledRejection` + `wrapFetch` all enabled.
+     *
+     * Pass `false` to disable error capture entirely (the SDK still ships
+     * the manual `captureError(err)` API, it just doesn't auto-wire process
+     * handlers). Pass a partial object to override individual defaults.
+     *
+     * Setting `false` is the right call if you have a separate error tracker
+     * (Sentry, Datadog) and don't want duplicates. Setting `true` (the
+     * default) is the right call for everyone else — that's why you installed
+     * a backend SDK.
+     */
+    errorCapture?: boolean | Partial<ErrorCaptureConfig>;
+    /** Maximum events buffered before forced flush. Default 20. Parity with web SDK. */
+    eventFlushBatchSize?: number;
+    /** Idle ms after the last track() before flushing. Default 1500. Parity with web SDK. */
+    eventFlushIntervalMs?: number;
+    /**
+     * Install `process.on('beforeExit')` + `SIGTERM` + `SIGINT` handlers that
+     * synchronously drain the event queue before exit. Default `true`.
+     *
+     * **Critical for Cloud Functions / Lambda.** Without this, a function
+     * cold-starts, fires 3 events, and exits before the HTTP POSTs complete —
+     * the events vanish silently. With it, the queue drains bounded by
+     * `flushOnExitTimeoutMs` before the process is allowed to terminate.
+     *
+     * Set `false` only if your runtime already manages SDK shutdown
+     * explicitly (some test harnesses, custom signal handlers).
+     */
+    flushOnExit?: boolean;
+    /**
+     * Bounded timeout for the on-exit drain (ms). Default 2000.
+     *
+     * Two seconds is enough to flush a handful of events over a healthy
+     * network without holding up the function teardown so long that the
+     * platform's own SIGKILL (typically 5-10s after SIGTERM) preempts us.
+     */
+    flushOnExitTimeoutMs?: number;
+    /**
+     * Fire a heartbeat in the background the moment the SDK is
+     * constructed. Default `true`.
+     *
+     * This is what makes the dashboard's "Verify install" surface
+     * actually work in cold-start serverless: the moment the customer's
+     * process boots and runs `new CrossdeckServer({...})`, we phone
+     * home, the dashboard row flips LIVE, and the caller doesn't have
+     * to add an explicit `await server.heartbeat()` to their bootstrap.
+     *
+     * Fire-and-forget. Failures are swallowed (the SDK still works for
+     * events even if this boot ping can't reach the backend). The
+     * caller's process never blocks on this.
+     *
+     * Set `false` if you want the prior v1.0.0 behaviour where the
+     * caller controlled when (or whether) the first network ping fired
+     * — e.g., very latency-sensitive cold paths, or environments where
+     * the very first request must not race with an SDK-initiated call.
+     * `testMode: true` also disables this implicitly.
+     */
+    bootHeartbeat?: boolean;
+    /**
+     * TTL for the entitlement cache (ms). Default 60_000 (60s).
+     *
+     * Once `getEntitlements()` has warmed the cache, subsequent
+     * `isEntitled(key)` calls are memory reads for the next `ttlMs` — no
+     * HTTP round-trip. Without this, a hot-path entitlement gate adds
+     * 50-200ms per request. Stripe + Mixpanel ship the same TTL pattern
+     * server-side for the same reason.
+     *
+     * Pass `0` to disable caching (every `isEntitled` requires a fresh
+     * `getEntitlements()` call to populate the cache — useful for tests).
+     */
+    entitlementCacheTtlMs?: number;
+    /**
+     * Service name for runtime enrichment. Attached to every event + error
+     * as `properties.serviceName`. Default: env-detected via
+     * `K_SERVICE` (Cloud Run / Cloud Functions v2) /
+     * `AWS_LAMBDA_FUNCTION_NAME` (Lambda) /
+     * `FUNCTION_NAME` (Cloud Functions v1). Falls back to `process.pid` if
+     * no env signal is present.
+     */
+    serviceName?: string;
+    /**
+     * Service version. Default: env-detected via `K_REVISION` /
+     * `AWS_LAMBDA_FUNCTION_VERSION`. Surfaces in dashboards as the build
+     * cohort the event/error originated from.
+     */
+    serviceVersion?: string;
+    /**
+     * App version attached as `appVersion` on every event/error. Parity
+     * with `@cross-deck/web`'s `appVersion` option — same role.
+     */
+    appVersion?: string;
+    /**
+     * Enable verbose diagnostic logging via NorthStar §16 debug signal
+     * vocabulary. Default `false`. Equivalent to `server.setDebugMode(true)`
+     * after construction.
+     */
+    debug?: boolean;
+    /**
+     * Breadcrumb buffer size. Default 50 (parity with web SDK). The last
+     * N tracked events + manual breadcrumbs are attached to every error
+     * report — "what was the request doing right before it failed."
+     */
+    breadcrumbsMaxSize?: number;
+    /**
+     * **Test mode.** When `true`, every HTTP call short-circuits to a
+     * synthetic success response — no network goes out. The synthetic
+     * shape matches each endpoint's contract (e.g. `getEntitlements`
+     * returns `{ object: "list", data: [], … }`). For caller test
+     * suites that don't want to mock `globalThis.fetch` directly.
+     *
+     * `onRequest` / `onResponse` hooks still fire in test mode so
+     * audit pipelines can observe synthetic traffic.
+     *
+     * Default `false`. Never enable in production.
+     */
+    testMode?: boolean;
+    /**
+     * Inspection hook fired BEFORE every HTTP request (including
+     * retries). Use for debugging, audit logging, custom metrics.
+     * Synchronous — errors thrown by the hook are swallowed, the
+     * request continues.
+     */
+    onRequest?: (info: HttpRequestInfo) => void;
+    /**
+     * Inspection hook fired AFTER every HTTP response. Same contract
+     * as `onRequest`. Carries `durationMs`, `attempt` number, and
+     * `testMode` flag (true if the response was synthetic).
+     */
+    onResponse?: (info: HttpResponseInfo) => void;
+    /**
+     * Retry config for idempotent GET requests. Default: 3 attempts
+     * with exponential backoff + full jitter, retrying on 408 + 5xx
+     * (except 501) and on network failures. POST retries are handled
+     * by the EventQueue separately (with batch-level Idempotency-Key
+     * reuse). Set `maxAttempts: 1` to disable GET retries.
+     */
+    httpRetries?: HttpRetriesConfig;
+    /**
+     * Override the runtime token in the `User-Agent` header
+     * (`@cross-deck/node/<sdk-version> <runtimeToken>`). Default
+     * detects `node/<process.versions.node> <process.platform>`.
+     * Override for custom builds (Bun, Deno-shim, electron) that want
+     * to report a more specific runtime label.
+     */
+    runtimeToken?: string;
+}
+/**
+ * Per-call options accepted by every async public method on
+ * `CrossdeckServer`. Carries cancellation + per-call timeout
+ * overrides. Inherits Stripe's pattern of "request options" as a
+ * trailing arg.
+ *
+ *   const ctrl = new AbortController();
+ *   const flight = server.heartbeat({ signal: ctrl.signal });
+ *   setTimeout(() => ctrl.abort(), 100);
+ *   await flight; // throws CrossdeckNetworkError({ code: "request_aborted" })
+ */
+interface RequestOptions {
+    /**
+     * Caller-supplied AbortSignal. When aborted, the in-flight `fetch`
+     * is cancelled and the call throws
+     * `CrossdeckNetworkError({ code: "request_aborted" })`. Composes
+     * with the per-request timeout — whichever fires first wins.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-call timeout override (ms). Defaults to the client's
+     * `timeoutMs`. Pass `0` to disable.
+     */
+    timeoutMs?: number;
+}
+interface IdentityHints {
+    customerId?: string;
+    userId?: string;
+    anonymousId?: string;
+}
+interface IdentifyOptions {
+    email?: string;
+    traits?: Record<string, unknown>;
+}
+interface AliasIdentityInput extends IdentifyOptions {
+    userId: string;
+    anonymousId: string;
+}
+type ErrorLevel = "error" | "warning" | "info";
+/** Properties payload for `track()`. Arbitrary JSON-serialisable bag, ≤ 8 KB. */
+type EventProperties = Record<string, unknown>;
+interface ServerEvent {
+    eventId?: string;
+    name: string;
+    timestamp?: number;
+    properties?: EventProperties;
+    developerUserId?: string;
+    anonymousId?: string;
+    crossdeckCustomerId?: string;
+    level?: ErrorLevel;
+    tags?: Record<string, string>;
+    categoryTags?: string[];
+}
+interface IngestOptions extends RequestOptions {
+    idempotencyKey?: string;
+}
+interface SyncPurchaseInput {
+    rail?: "apple";
+    signedTransactionInfo: string;
+    signedRenewalInfo?: string;
+    appAccountToken?: string;
+}
+type GrantDuration = "P30D" | "P90D" | "P1Y" | "lifetime";
+interface GrantEntitlementInput {
+    customerId: string;
+    entitlementKey: string;
+    duration: GrantDuration;
+    reason: string;
+}
+interface RevokeEntitlementInput {
+    customerId: string;
+    entitlementKey: string;
+    reason: string;
+}
+interface EntitlementMutationResult {
+    object: "entitlement_mutation";
+    action: "grant" | "revoke";
+    crossdeckCustomerId: string;
+    entitlement: PublicEntitlement;
+    env: Environment;
+}
+type AuditDecision = "applied" | "no_op" | "rejected";
+interface AuditEntry {
+    eventId: string;
+    rail: AuditRail;
+    env: Environment;
+    eventType: string;
+    projectId: string;
+    subscriptionId?: string;
+    customerId?: string;
+    fromState?: string;
+    toState?: string;
+    decision: AuditDecision;
+    reason?: string;
+    derivedSignal?: string;
+    signatureVerified: boolean;
+    reconciledWithProvider: boolean;
+    rawEventReceivedAt: number;
+    processedAt: number;
+}
+/**
+ * Diagnostic snapshot returned by `server.diagnostics()`. Stable shape
+ * regardless of init state — callers don't need to narrow.
+ *
+ * Differs from web SDK's Diagnostics in two ways:
+ *   - No `anonymousId` / `crossdeckCustomerId` / `developerUserId` (Node
+ *     SDK has no per-device identity — identity is per-request).
+ *   - No `clock` block (no heartbeat round-trip — Node SDK doesn't ship
+ *     one).
+ *   - Adds `runtime` (Node version, OS, host, region, service) and
+ *     `errors` (session count, fingerprints tracked).
+ */
+interface Diagnostics {
+    sdkVersion: string;
+    baseUrl: string;
+    /** First 12 chars of the secret key (incl. `cd_sk_test_` / `cd_sk_live_` prefix). For correlation in support tickets. */
+    secretKeyPrefix: string;
+    env: Environment;
+    runtime: {
+        nodeVersion: string;
+        platform: string;
+        hostname: string;
+        /** Which serverless / hosting platform the SDK detected. "node" if no platform signal. */
+        host: RuntimeHost;
+        region: string | null;
+        serviceName: string | null;
+        serviceVersion: string | null;
+        instanceId: string | null;
+    };
+    entitlements: {
+        count: number;
+        lastUpdated: number;
+        ttlMs: number;
+        /** Cumulative count of listener invocations that threw. Swallowed inside the cache; surfaced here. */
+        listenerErrors: number;
+    };
+    events: {
+        buffered: number;
+        dropped: number;
+        inFlight: number;
+        lastFlushAt: number;
+        lastError: string | null;
+        consecutiveFailures: number;
+        nextRetryAt: number | null;
+    };
+    errors: {
+        /** Total error reports captured in this process lifetime. */
+        sessionCount: number;
+        /** Number of distinct fingerprints currently inside the rate-limit window. */
+        fingerprintsTracked: number;
+        /** Whether the global handlers (uncaughtException / unhandledRejection) are installed. */
+        handlersInstalled: boolean;
+    };
+}
+
+/**
+ * Error capture — the third Crossdeck USP, the headline reason backend
+ * developers install observability SDKs.
+ *
+ * Catches every error source a Node process can hand us and ships them
+ * as Crossdeck events. The pipeline reuses the analytics queue:
+ *   - Same retry-with-backoff + Idempotency-Key (duplicate batches
+ *     dedup server-side)
+ *   - Same property sanitisation (one bad context blob can't poison
+ *     the batch)
+ *   - Same on-the-wire enrichment via runtime-info
+ *
+ * Error sources captured (each toggleable):
+ *   1. `process.on('uncaughtException')`  — uncaught synchronous errors
+ *   2. `process.on('unhandledRejection')` — unhandled promise rejections
+ *   3. `globalThis.fetch` wrap            — 5xx + network failures
+ *   4. `console.error` wrap (default OFF) — noisy, opt-in
+ *   5. `server.captureError(err)`         — manual try/catch API
+ *   6. `server.captureMessage(msg)`       — non-error signals
+ *
+ * Adapted from `@cross-deck/web/src/error-capture.ts`. Three runtime
+ * differences:
+ *   - `window.onerror` → `process.on('uncaughtException')`. Node's
+ *     uncaught-exception handler receives an `Error` directly, not an
+ *     `ErrorEvent` wrapper — `buildFromUnknown` handles both.
+ *   - `window.onunhandledrejection` → `process.on('unhandledRejection')`.
+ *     Same shape (the rejection's `reason`); same handler logic.
+ *   - `XMLHttpRequest` wrap → dropped (no XHR in Node).
+ *
+ * Defensive design rules (parity with web):
+ *   - The error handler must NEVER throw — if our own code crashed
+ *     while reporting an error, we'd take down the host's last-resort
+ *     error path. Every callback wrapped in try/swallow.
+ *   - Recursion guard: a `_reporting` flag prevents reporting our own
+ *     errors recursively forever.
+ *   - Rate limited per-fingerprint: max N reports per minute to defend
+ *     against runaway loops (e.g. an error in a per-request middleware).
+ *   - Session cap (per process lifetime): hard limit after which we
+ *     stop reporting. The dashboard sees "1 unique error" instead of
+ *     a million events.
+ *   - Self-skip for `api.cross-deck.com` requests so a Crossdeck
+ *     outage doesn't self-amplify back into the queue.
+ */
+
+interface CapturedError {
+    /** When the error fired (epoch ms). */
+    timestamp: number;
+    /** error.unhandled | error.unhandledrejection | error.handled | error.message | error.http */
+    kind: "error.unhandled" | "error.unhandledrejection" | "error.handled" | "error.message" | "error.http";
+    level: ErrorLevel;
+    message: string;
+    /** The error class name when we have it (TypeError, ReferenceError, etc.) */
+    errorType: string | null;
+    /** Parsed stack frames, empty when unavailable. */
+    frames: StackFrame[];
+    /** Raw stack string for fallback display. */
+    rawStack: string | null;
+    /** djb2 hash of message + top frames — groups identical errors. */
+    fingerprint: string;
+    /** Snapshot of the breadcrumb buffer at the moment the error fired. */
+    breadcrumbs: Breadcrumb[];
+    /** Free-form context attached via `server.setContext()`. */
+    context: Record<string, unknown>;
+    /** Free-form tags attached via `server.setTag()`. */
+    tags: Record<string, string>;
+    /** Set only on `error.http` — the request that failed. */
+    http?: {
+        url: string;
+        method: string;
+        status: number;
+        statusText?: string;
+    };
+}
+interface ErrorCaptureConfig {
+    /** Master switch. Default true. */
+    enabled: boolean;
+    /** Hook `process.on('uncaughtException')`. Default true. */
+    onUncaughtException: boolean;
+    /** Hook `process.on('unhandledRejection')`. Default true. */
+    onUnhandledRejection: boolean;
+    /** Wrap `globalThis.fetch` to capture 5xx + network failures. Default true. */
+    wrapFetch: boolean;
+    /** Wrap `console.error`. Default false (noisy). */
+    captureConsole: boolean;
+    /**
+     * Drop errors matching these substrings / regexes. Tested against
+     * `message`. Default: empty (Node has no equivalent of the
+     * browser's `ResizeObserver` / `Script error.` noise).
+     */
+    ignoreErrors: Array<string | RegExp>;
+    /**
+     * Only capture errors whose top in-app frame filename matches one
+     * of these. Empty array means "no allowlist — capture everything".
+     */
+    allowPaths: Array<string | RegExp>;
+    /**
+     * Drop errors whose top frame filename matches any of these.
+     * Default: SDK self-skip pattern (`@cross-deck/node`).
+     */
+    denyPaths: Array<string | RegExp>;
+    /**
+     * Sample rate, 0–1. 1.0 = send every error. 0.5 = send half (per
+     * fingerprint, deterministically — so a given fingerprint always
+     * either always sends or never does, no flapping). Default 1.0.
+     */
+    sampleRate: number;
+    /**
+     * Maximum errors per fingerprint per minute. Defends against
+     * runaway loops. Default 5.
+     */
+    maxPerFingerprintPerMinute: number;
+    /**
+     * Total cap per process lifetime, regardless of fingerprint. Hard
+     * limit after which we stop reporting. Default 100.
+     */
+    maxPerSession: number;
+}
+
+/**
+ * Super-properties + group analytics — Mixpanel pattern.
+ *
+ * Super properties are key/value pairs the developer registers ONCE
+ * via `server.register({ tenant: "acme" })` that get attached to
+ * every subsequent event of THIS SDK instance. They're the single
+ * most-used feature in Mixpanel-style analytics: "every event from
+ * this process should have `tenant` and `serviceName` on it" instead
+ * of remembering to pass them on every `track()` call.
+ *
+ * Groups are organisational identifiers: a customer might belong to
+ * an `org` ("acme"), a `team` ("design"), and a `plan` ("enterprise").
+ * Each event carries `$groups.{type}: id` so B2B dashboards can pivot:
+ * "Acme's team:design fired 142 paywall_shown events this week".
+ *
+ * Node port differences from `@cross-deck/web/src/super-properties.ts`:
+ *   - No `KeyValueStorage` backing. In-memory only. Node processes are
+ *     short-lived (Lambda freezes between invocations, Cloud Functions
+ *     tear down containers); super-properties typically belong to the
+ *     SDK instance lifetime, not persistence-across-process.
+ *   - The Store reset clears both bags (parity with web's clear()).
+ *
+ * The store is reset on `server.shutdown()` — both super properties
+ * and groups are cleared because their lifetime is tied to the SDK
+ * instance, not to the process.
+ */
+interface GroupMembership {
+    id: string;
+    traits?: Record<string, unknown>;
+}
+
+/**
+ * Per-customer entitlement cache with TTL — the third Crossdeck USP
+ * on the server.
+ *
+ * Why this exists: server-side gating code looks like
+ *
+ *   if (server.isEntitled(customerId, "pro")) { … }
+ *
+ * inside a request handler. Without a cache, every request makes an
+ * HTTP round-trip to `GET /v1/entitlements?customerId=…` — 50-200ms
+ * per request, every request, for every customer. The cache makes
+ * `isEntitled()` a `Map.get()` after the first warm.
+ *
+ * Differences from `@cross-deck/web/src/entitlement-cache.ts`:
+ *   - **Per-customer**, not singleton. Web SDK has one user per browser
+ *     tab; Node SDK has many users hitting one server. The cache is
+ *     keyed by `crossdeckCustomerId`.
+ *   - **TTL-bounded**. Each customer's entry expires after `ttlMs`
+ *     (default 60_000) and the next read returns `false` until
+ *     `getEntitlements()` refreshes. Stripe + Mixpanel ship the same
+ *     pattern server-side.
+ *   - **Subscriber API unchanged** — `subscribe(listener)` fires after
+ *     any mutation (set / clear / per-customer expiry-driven eviction
+ *     is NOT considered a mutation, by design — listeners shouldn't
+ *     re-render just because a TTL elapsed).
+ *
+ * The cache holds only ACTIVE entitlements — `setForCustomer` filters.
+ * `isEntitled()` returns `false` when:
+ *   - the customer has no cached entry
+ *   - the entry has expired
+ *   - the requested key isn't in the active set
+ */
+
+type EntitlementsListener = (customerId: string, entitlements: PublicEntitlement[]) => void;
+interface EntitlementCacheOptions {
+    /** TTL in ms. Default 60_000 (60s). 0 disables caching (every read is cold). */
+    ttlMs?: number;
+    /**
+     * Maximum number of customers cached at once. Long-running multi-tenant
+     * servers handling a long tail of customers would otherwise leak Map
+     * entries forever. Default 10_000 — enough for any realistic deployment.
+     * When the cap is reached, the OLDEST entry (by insertion / refresh
+     * order) is evicted to make room. Eviction does NOT fire listeners
+     * (passive eviction is not a mutation by design).
+     */
+    maxCustomers?: number;
+}
+
+/**
+ * @cross-deck/node — `CrossdeckServer`, the orchestrator.
+ *
+ * v1.0.0 expands beyond the v0.1.0 thin HTTP client to ship the three
+ * Crossdeck USPs on the server:
+ *
+ *   1. Errors — `captureError`, `captureMessage`, auto-wired
+ *      `process.on('uncaughtException')` + `process.on('unhandledRejection')`,
+ *      `globalThis.fetch` wrap, stack-frame parsing, breadcrumb
+ *      attachment, fingerprint dedup, rate-limit per fingerprint.
+ *      [USP 1 — landed v1.0.0]
+ *
+ *   2. Analytics — `track()` switches from sync-HTTP-per-event to
+ *      enqueue-and-batch via `EventQueue` (durable, retried, idempotent
+ *      per batch). `flush-on-exit` drains before Cloud Function / Lambda
+ *      teardown so events don't vanish silently.
+ *      [USP 1 ships queue + flush-on-exit; super-props + auto-events
+ *       arrive in USP 2]
+ *
+ *   3. Entitlements — TTL-cached `isEntitled()` so hot-path gates are
+ *      memory reads after first warm.
+ *      [USP 3 — pending]
+ *
+ * Cross-cutting: every event + error carries `runtime.*` enrichment
+ * (Node version, OS, host, region, function name, instance ID) auto-
+ * attached via `collectRuntimeInfo()`.
+ *
+ * The non-event endpoints (identify / aliasIdentity / forget /
+ * getEntitlements / getCustomerEntitlements / syncPurchases /
+ * grantEntitlement / revokeEntitlement / getAuditEntry) stay as direct
+ * HTTP — they're transactional, not telemetry. Only `track()` changed
+ * to queue-based.
+ */
+
+/**
+ * Typed event names + payloads emitted by `CrossdeckServer`. Caller
+ * subscribes via the standard EventEmitter API:
+ *
+ *   server.on("queue.flush_failed", ({ error, attempt }) => { ... });
+ *   server.once("sdk.shutdown", () => { ... });
+ *
+ * The typed `on` / `off` / `emit` overloads narrow the listener
+ * arguments to the right shape. Untyped event names still work for
+ * forward compat with any backend-side additions.
+ */
+interface CrossdeckServerEvents {
+    /** Fired once per batch on successful flush. */
+    "queue.flush_succeeded": [info: {
+        batchSize: number;
+        durationMs: number;
+    }];
+    /** Fired on every failed flush attempt. */
+    "queue.flush_failed": [info: {
+        error: CrossdeckError | string;
+        attempt: number;
+        nextRetryMs: number;
+    }];
+    /** Fired when the queue drops oldest events due to HARD_BUFFER_CAP. */
+    "queue.dropped": [info: {
+        count: number;
+    }];
+    /** Fired when the buffer changes size — used by callers wanting backpressure-aware tracking. */
+    "queue.buffer_changed": [info: {
+        size: number;
+    }];
+    /** Fired when an error is captured (manual or auto). */
+    "error.captured": [info: {
+        fingerprint: string;
+        kind: string;
+        message: string;
+    }];
+    /** Fired once after `getEntitlements()` warms the cache for a customer. */
+    "entitlements.warmed": [info: {
+        customerId: string;
+        count: number;
+    }];
+    /** Fired on `shutdown()` / `[Symbol.dispose]` / `[Symbol.asyncDispose]`. */
+    "sdk.shutdown": [info: {
+        reason: "shutdown" | "dispose" | "asyncDispose";
+    }];
+}
+declare class CrossdeckServer extends EventEmitter {
+    private readonly http;
+    private readonly sdkVersion;
+    private readonly baseUrl;
+    private readonly appId;
+    private readonly env;
+    private readonly secretKeyPrefix;
+    /**
+     * Process-stable pseudo-anonymous ID. Used as the default identity
+     * for `track()` / `captureError()` calls where the caller doesn't
+     * supply one (e.g. an `uncaughtException` handler has no per-request
+     * context). Stable for the SDK instance's lifetime so events from
+     * the same process correlate.
+     */
+    private readonly processAnonymousId;
+    private readonly runtime;
+    private readonly runtimeProperties;
+    private readonly breadcrumbs;
+    private readonly eventQueue;
+    private readonly errorTracker;
+    private readonly flushOnExit;
+    private readonly superProps;
+    private readonly entitlementCache;
+    private readonly debug;
+    /**
+     * Alias map — `developerUserId` / `anonymousId` → canonical
+     * `crossdeckCustomerId`. Populated by `getEntitlements()` so a
+     * subsequent `isEntitled({ userId }, "pro")` resolves to the same
+     * cache entry the prior `getEntitlements({ userId })` populated.
+     *
+     * Bounded by `MAX_CUSTOMER_ID_ALIASES` (matches the entitlement
+     * cache's default max-customers for symmetry — if the underlying
+     * cache entry was evicted, a stale alias is dead weight anyway).
+     * Long-running multi-tenant servers handling a long tail of customers
+     * are the failure mode this bound defends against.
+     */
+    private customerIdAliases;
+    /** Mutable error-state — modified by setTag / setContext / setErrorBeforeSend. */
+    private errorContext;
+    private errorTags;
+    private errorBeforeSend;
+    constructor(options: CrossdeckServerOptions);
+    identify(userId: string, anonymousId: string, options?: IdentifyOptions & RequestOptions): Promise<AliasResult>;
+    aliasIdentity(input: AliasIdentityInput, options?: RequestOptions): Promise<AliasResult>;
+    forget(hints: IdentityHints, options?: RequestOptions): Promise<ForgetResult>;
+    getEntitlements(hints: IdentityHints, options?: RequestOptions): Promise<EntitlementsListResponse>;
+    getCustomerEntitlements(customerId: string, options?: RequestOptions): Promise<EntitlementsListResponse>;
+    /**
+     * Synchronous entitlement check. Returns `true` iff the customer
+     * has the entitlement AND the cache entry is fresh (within
+     * `entitlementCacheTtlMs`, default 60s). Returns `false` when the
+     * cache is cold or expired.
+     *
+     * The hint can be any combination of `customerId` / `userId` /
+     * `anonymousId`. After `getEntitlements({ userId })` populates the
+     * cache, subsequent `isEntitled({ userId }, "pro")` calls within
+     * TTL are memory reads (no HTTP). The "warm cache" pattern that
+     * makes hot-path entitlement gates cheap.
+     *
+     *   await server.getEntitlements({ userId });    // warm
+     *   if (server.isEntitled({ userId }, "pro")) {  // synchronous
+     *     // ...
+     *   }
+     *
+     * Caller is responsible for re-warming after TTL elapses. The cache
+     * does NOT auto-refresh on read (would block the hot path).
+     */
+    isEntitled(hint: IdentityHints | string, key: string): boolean;
+    /**
+     * Snapshot of the customer's cached entitlements. Returns `[]` when
+     * the cache is cold or expired. Same hint resolution as
+     * `isEntitled()`.
+     */
+    listEntitlements(hint: IdentityHints | string): PublicEntitlement[];
+    /**
+     * Subscribe to entitlement-cache mutations. Listener fires after
+     * `getEntitlements()` populates the cache or `shutdown()` clears
+     * it. Returns an idempotent unsubscribe function.
+     *
+     * Used by callers that want to react to entitlement changes (e.g.
+     * a websocket layer notifying connected clients of plan upgrades).
+     * Listener errors are swallowed — surfaced via
+     * `diagnostics().entitlements.listenerErrors`.
+     */
+    onEntitlementsChange(listener: EntitlementsListener): () => void;
+    /**
+     * Queue an event for batched delivery. Returns synchronously — the
+     * HTTP round-trip happens in the background.
+     *
+     * Behaviour parity with `@cross-deck/web`'s `track()`:
+     *   - Synchronous return, void.
+     *   - Throws sync on `missing_event_name`.
+     *   - Property bag sanitised through `validateEventProperties`.
+     *   - Runtime info (`runtime.*`) auto-merged into every event's
+     *     properties. Caller-supplied properties win on key collision.
+     *   - Breadcrumb auto-emitted (unless the name starts with `error.`,
+     *     which would cause a cycle).
+     *
+     * Differences from `@cross-deck/web`:
+     *   - Single-argument signature `track(event)` instead of
+     *     `track(name, properties)` — the Node wire shape needs the full
+     *     `ServerEvent` (identity hint, optional level + tags + categoryTags).
+     *   - Auto-fills `anonymousId` with `this.processAnonymousId` when no
+     *     identity hint is supplied. A captureError from
+     *     `uncaughtException` has no per-request context; without the
+     *     auto-fill, the event would be rejected at queue enqueue.
+     */
+    track(event: ServerEvent): void;
+    /**
+     * Immediate POST of one or more events. For bulk imports / replay
+     * scenarios where the caller wants synchronous confirmation. Bypasses
+     * the queue — no batching, no auto-fill of identity, no
+     * runtime-enrichment.
+     *
+     * Use `track()` for the standard fire-and-forget telemetry path.
+     * Use `ingest()` when you need:
+     *   - The IngestResponse synchronously.
+     *   - Strict per-event identity validation (no auto-fill).
+     *   - Caller-controlled idempotency key.
+     */
+    ingest(events: ServerEvent[], options?: IngestOptions): Promise<IngestResponse>;
+    /**
+     * Validate the secret key against the Crossdeck API and return the
+     * resolved project + app metadata. Useful at boot to fail fast on a
+     * misconfigured deployment — without this, a wrong secret key only
+     * surfaces on the first event flush attempt, which may be minutes
+     * after process start.
+     *
+     *   const { projectId, appId, env, serverTime } = await server.heartbeat();
+     *
+     * Throws `CrossdeckError` on:
+     *   - `authentication_error` — secret key invalid / revoked
+     *   - `network_error` — couldn't reach the backend
+     *   - `request_timeout` — backend slow / unreachable
+     *
+     * Side effect: success records `(serverTime, clientTime)` for clock-
+     * skew detection in `diagnostics().clock` (Phase 2 — not yet exposed
+     * in this SDK release but the data is captured).
+     *
+     * Not auto-called. Caller decides whether the trade-off (one extra
+     * boot request + ~50ms p50 latency) is worth the early-failure
+     * signal. For serverless cold-starts, it usually is — cheap
+     * compared to the cost of a silent broken secret in production.
+     */
+    heartbeat(options?: RequestOptions): Promise<HeartbeatResponse>;
+    /**
+     * Drain the event queue. Resolves when the in-flight batch completes
+     * (success or failure). On failure, events stay queued for the next
+     * scheduled retry — the resolved promise does NOT throw.
+     *
+     * Typical callers:
+     *   - End of a Lambda handler: `await server.flush()` before return
+     *     so events land before the platform freezes the process.
+     *   - Express server shutdown: `await server.flush()` inside the
+     *     SIGTERM handler.
+     *   - Tests: drain between assertions.
+     *
+     * Idempotent — flush on an empty queue is a no-op.
+     */
+    flush(): Promise<void>;
+    syncPurchases(input: SyncPurchaseInput, options?: RequestOptions): Promise<PurchaseResult>;
+    grantEntitlement(input: GrantEntitlementInput, options?: RequestOptions): Promise<EntitlementMutationResult>;
+    /**
+     * Grant multiple entitlements in one logical call. Backend lacks a
+     * bulk endpoint today, so this is a client-side fan-out — each
+     * grant fires a separate request. Results return as a
+     * settled-promise array so partial failures don't drop the rest:
+     * the caller decides how to handle each `{ ok, value }` /
+     * `{ ok: false, error }` entry.
+     *
+     * Use for ops sweeps (e.g. "grant the entire `pro` tier a one-time
+     * `pro_q1_bonus` entitlement"). The bounded concurrency (default
+     * `maxConcurrency: 5`) avoids hammering the backend; the rate-
+     * limit policy on the server still kicks in if needed.
+     */
+    bulkGrantEntitlement(grants: GrantEntitlementInput[], options?: RequestOptions & {
+        maxConcurrency?: number;
+    }): Promise<Array<{
+        input: GrantEntitlementInput;
+        ok: true;
+        value: EntitlementMutationResult;
+    } | {
+        input: GrantEntitlementInput;
+        ok: false;
+        error: CrossdeckError;
+    }>>;
+    revokeEntitlement(input: RevokeEntitlementInput, options?: RequestOptions): Promise<EntitlementMutationResult>;
+    /**
+     * Revoke multiple entitlements in one logical call. Same
+     * settled-array contract as `bulkGrantEntitlement` — see that
+     * doc for behaviour notes.
+     */
+    bulkRevokeEntitlement(revokes: RevokeEntitlementInput[], options?: RequestOptions & {
+        maxConcurrency?: number;
+    }): Promise<Array<{
+        input: RevokeEntitlementInput;
+        ok: true;
+        value: EntitlementMutationResult;
+    } | {
+        input: RevokeEntitlementInput;
+        ok: false;
+        error: CrossdeckError;
+    }>>;
+    getAuditEntry(eventId: string, options?: RequestOptions): Promise<AuditEntry>;
+    /**
+     * Manually capture an error from a try/catch block.
+     *
+     *   try { … } catch (err) {
+     *     server.captureError(err, { context: { jobId }, tags: { flow: "checkout" } });
+     *   }
+     *
+     * The error ships through the same event queue analytics rides on
+     * (retried, idempotent, runtime-enriched). Returns silently — never
+     * throws, even if error capture is disabled.
+     */
+    captureError(error: unknown, options?: {
+        context?: Record<string, unknown>;
+        tags?: Record<string, string>;
+        level?: ErrorLevel;
+    }): void;
+    /**
+     * Capture a non-error signal as an issue. Sentry's `captureMessage`
+     * pattern — for "we hit the deprecated code path" / "soft-warning
+     * triggered" signals where there's no Error to throw.
+     */
+    captureMessage(message: string, level?: ErrorLevel): void;
+    /**
+     * Attach a tag to every subsequent error report. Sentry pattern.
+     * Tags are flat string key/value (queryable in the dashboard);
+     * use `setContext()` for structured blobs.
+     */
+    setTag(key: string, value: string): void;
+    /** Bulk-set tags. Merges with existing tags. */
+    setTags(tags: Record<string, string>): void;
+    /**
+     * Attach a structured context blob to every subsequent error report.
+     * Unlike tags (flat key/value), context is a named bag of arbitrary
+     * JSON-serialisable data.
+     *
+     *   server.setContext("cart", { items: 3, total: 42.99 });
+     */
+    setContext(name: string, data: Record<string, unknown>): void;
+    /**
+     * Add a custom breadcrumb to the rolling buffer. The last 50
+     * breadcrumbs are attached to every subsequent error report —
+     * "what was the request doing right before things broke."
+     */
+    addBreadcrumb(crumb: Breadcrumb): void;
+    /**
+     * Install a pre-send hook for errors. Return null to drop the report,
+     * or a modified `CapturedError` to scrub fields. Sentry's
+     * `beforeSend` pattern — the only place to add app-specific PII
+     * redaction (auth tokens in URLs, etc.) before the report leaves the
+     * process.
+     *
+     * The hook is called LAST, after rate-limit + sampling + path gates
+     * already passed. A throwing hook falls back to the original error.
+     */
+    setErrorBeforeSend(hook: ((err: CapturedError) => CapturedError | null) | null): void;
+    /**
+     * Register super-properties — every subsequent event carries these
+     * keys on its `properties` bag automatically. Mixpanel pattern.
+     *
+     *   server.register({ tenant: "acme", plan: "pro" });
+     *   server.track({ name: "paywall_shown", developerUserId: userId });
+     *   //          ^ event carries `tenant` + `plan` in properties
+     *
+     * Values that are `null` are deleted (the explicit "stop tracking
+     * this key" idiom). Sanitised through `validateEventProperties` so
+     * a `{ avatar: <Buffer> }` payload can't poison the queue.
+     *
+     * Returns a defensive snapshot of the resulting bag.
+     *
+     * **Multi-tenant servers — read carefully.** Super-properties are
+     * PROCESS-SCOPED. In a single Node process handling requests for
+     * many tenants (the common multi-tenant SaaS shape), calling
+     * `server.register({ tenant: "acme" })` taints EVERY subsequent
+     * event from that process — including ones serving tenant "beta".
+     * That's almost never what you want.
+     *
+     * The right pattern for per-request properties is to pass them on
+     * the `track()` call itself:
+     *
+     *   server.track({
+     *     name: "paywall_shown",
+     *     developerUserId: req.user.id,
+     *     properties: { tenant: req.tenantId, plan: req.user.plan },
+     *   });
+     *
+     * Reserve `register()` for properties that genuinely apply to every
+     * event from this process — e.g. service version, region, build
+     * commit. For those, `runtime-info` already provides
+     * `runtime.serviceVersion` etc. automatically.
+     */
+    register(properties: Record<string, unknown>): Record<string, unknown>;
+    /** Remove a single super-property key. Idempotent. */
+    unregister(key: string): void;
+    /** Snapshot of the current super-property bag. */
+    getSuperProperties(): Record<string, unknown>;
+    /**
+     * Associate the current SDK instance with a group (org, team,
+     * account, plan). Mixpanel / Segment Group Analytics pattern.
+     *
+     *   server.group("org", "acme_inc");
+     *   server.group("team", "design", { headcount: 12 });
+     *
+     * Once set, every subsequent event carries `$groups.<type>: id` on
+     * its `properties` bag, enabling B2B dashboard pivots. Pass
+     * `id: null` to clear a group membership.
+     *
+     * Group traits are sanitised through `validateEventProperties`.
+     */
+    group(type: string, id: string | null, traits?: Record<string, unknown>): void;
+    /** Snapshot of current group memberships keyed by type. */
+    getGroups(): Record<string, GroupMembership>;
+    diagnostics(): Diagnostics;
+    /**
+     * Tear down handlers and clear in-memory state. Tests + custom
+     * lifecycle callers only. Production code should rely on
+     * `flush-on-exit` instead.
+     */
+    shutdown(reason?: "shutdown" | "dispose" | "asyncDispose"): void;
+    /**
+     * Convert a `CapturedError` into a `ServerEvent` and push through
+     * `track()`. Goes through the same queue / enrichment / breadcrumb
+     * pipeline analytics events do.
+     */
+    on<K extends keyof CrossdeckServerEvents>(event: K, listener: (...args: CrossdeckServerEvents[K]) => void): this;
+    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once<K extends keyof CrossdeckServerEvents>(event: K, listener: (...args: CrossdeckServerEvents[K]) => void): this;
+    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    off<K extends keyof CrossdeckServerEvents>(event: K, listener: (...args: CrossdeckServerEvents[K]) => void): this;
+    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    emit<K extends keyof CrossdeckServerEvents>(event: K, ...args: CrossdeckServerEvents[K]): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+    /**
+     * Synchronous readiness check — "is the SDK in a state where it
+     * should accept new traffic?". Used by Kubernetes readiness probes
+     * and backpressure-aware callers.
+     *
+     * Returns `false` if:
+     *   - The event queue is in a sustained retry storm
+     *     (`consecutiveFailures >= 5`).
+     *   - The event queue's buffered count is at >= 80% of HARD_BUFFER_CAP.
+     *
+     * Otherwise `true`. The default isn't "perfectly healthy" — the
+     * SDK is happy to enqueue events even during transient flush
+     * failures because the queue's retry path handles them. Only
+     * sustained failure flips this to `false`.
+     */
+    isReady(): boolean;
+    /**
+     * Async wait until `isReady()` returns true OR the timeout elapses.
+     * Resolves `true` on ready, `false` on timeout. Polls every 50ms by
+     * default — backpressure for callers writing high-volume servers.
+     *
+     *   if (!(await server.awaitReady(2000))) {
+     *     // shed load — SDK is in a retry storm, don't queue more
+     *   }
+     */
+    awaitReady(timeoutMs?: number, pollIntervalMs?: number): Promise<boolean>;
+    /**
+     * Snapshot for Kubernetes liveness + readiness probes. `healthy`
+     * stays true unless the SDK is in a catastrophic state (which
+     * currently can't happen without crashing the process). `ready`
+     * matches `isReady()`.
+     *
+     *   app.get("/healthz", (_req, res) => {
+     *     const h = server.getHealth();
+     *     res.status(h.healthy ? 200 : 503).json(h);
+     *   });
+     */
+    getHealth(): {
+        ready: boolean;
+        healthy: boolean;
+        bufferedEvents: number;
+        inFlight: number;
+        consecutiveFailures: number;
+        lastFlushAt: number;
+        lastError: string | null;
+        errorHandlersInstalled: boolean;
+    };
+    /**
+     * Sync disposal hook — runs when a `using` declaration exits scope
+     * (TC39 explicit-resource-management, Node 20+ / TS 5.2+).
+     *
+     *   using server = new CrossdeckServer({ ... });
+     *   // ... use server ...
+     *   // at end of block, server[Symbol.dispose]() runs automatically
+     *
+     * `Symbol.dispose` is synchronous so we can't await `flush()` here
+     * — for that, use `await using` + `[Symbol.asyncDispose]()`. This
+     * sync variant just calls `shutdown()` (handler cleanup +
+     * in-memory state wipe).
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Async disposal hook — runs when an `await using` declaration
+     * exits scope. Awaits `flush()` THEN runs `shutdown()`. Use this
+     * variant when the caller needs the queue drained before exit
+     * (the common case for serverless handlers).
+     *
+     *   await using server = new CrossdeckServer({ ... });
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    private reportCapturedError;
+    /**
+     * Populate the entitlement cache from a fresh server response.
+     * Records aliases so `userId` / `anonymousId` hints supplied to
+     * `getEntitlements()` resolve to the same cache entry on subsequent
+     * `isEntitled({ userId }, ...)` calls.
+     *
+     * Bounds the alias map at MAX_CUSTOMER_ID_ALIASES — once full, the
+     * oldest aliases (by insertion order) are evicted FIFO. Symmetric
+     * with the entitlement cache's max-customers cap.
+     */
+    private populateEntitlementCache;
+    private touchAlias;
+    /**
+     * Resolve any hint shape (canonical customerId / userId hint /
+     * anonymousId hint / raw string) to a `crossdeckCustomerId` if we
+     * have a cache entry for it.
+     */
+    private resolveCacheCustomerId;
+    private identityPayload;
+    /**
+     * Resolve event identity. Caller-supplied wins; falls back to
+     * `processAnonymousId` so events from `captureError` /
+     * uncaughtException always have at least one identity hint.
+     */
+    private resolveIdentity;
+    /**
+     * Strict normalisation for `ingest()` — no auto-fill of identity,
+     * caller must supply at least one hint per event. Matches v0.1.0
+     * behaviour for backward compatibility with bulk-import callers.
+     */
+    private normalizeIngestEvent;
+}
+
+export { type StackFrame as $, type AliasIdentityInput as A, type Breadcrumb as B, CROSSDECK_API_VERSION as C, DEFAULT_BASE_URL as D, type EntitlementCacheOptions as E, type EventProperties as F, type ForgetResult as G, type GrantDuration as H, type GrantEntitlementInput as I, type GroupMembership as J, type HeartbeatResponse as K, type HttpRequestInfo as L, type HttpResponseInfo as M, type HttpRetriesConfig as N, type IdentifyOptions as O, type IdentityHints as P, type IngestOptions as Q, type IngestResponse as R, type PublicEntitlement as S, type PurchaseResult as T, type RequestOptions as U, type RevokeEntitlementInput as V, type RuntimeHost as W, type RuntimeInfo as X, SDK_NAME as Y, SDK_VERSION as Z, type ServerEvent as _, type AliasResult as a, type SyncPurchaseInput as a0, makeCrossdeckError as a1, type AuditDecision as b, type AuditEntry as c, type BreadcrumbCategory as d, type BreadcrumbLevel as e, type CapturedError as f, CrossdeckAuthenticationError as g, CrossdeckConfigurationError as h, CrossdeckError as i, type CrossdeckErrorPayload as j, type CrossdeckErrorType as k, CrossdeckInternalError as l, CrossdeckNetworkError as m, CrossdeckPermissionError as n, CrossdeckRateLimitError as o, CrossdeckServer as p, type CrossdeckServerOptions as q, CrossdeckValidationError as r, DEFAULT_TIMEOUT_MS as s, type Diagnostics as t, type EntitlementMutationResult as u, type EntitlementsListResponse as v, type EntitlementsListener as w, type Environment as x, type ErrorCaptureConfig as y, type ErrorLevel as z };