@cross-deck/node 1.2.0 → 1.5.0

package/dist/{crossdeck-server-BZVZEuS-.d.mts → crossdeck-server-oAaKBnUU.d.mts}

@@ -111,6 +111,96 @@ declare class CrossdeckConfigurationError extends CrossdeckError {
  */
 declare function makeCrossdeckError(payload: CrossdeckErrorPayload): CrossdeckError;
 
+/**
+ * Public, typed accessor for the bank-grade behavioural contracts
+ * this SDK ships. The full architecture — schema, distribution,
+ * audit loop, pillar taxonomy — lives in `contracts/README.md`
+ * at the monorepo root.
+ *
+ * Why a typed surface (vs. plain JSON access): contract IDs and
+ * pillar names are part of Crossdeck's public commitment to
+ * customers. Reading them through `CrossdeckContracts` means the
+ * compiler catches drift the moment a contract is renamed or
+ * retired. Tools that consume contracts at runtime (dashboards,
+ * AI assistants, customer integration tests) get the exact same
+ * shape every SDK ships, with no parsing layer to drift.
+ *
+ * --- BINARY STABILITY ---
+ * `Contract` is treated as an evolving — but back-compat — wire
+ * shape. Fields may be added in any minor release. Existing
+ * fields will not be removed or repurposed except in a major
+ * version bump, even if all known contracts stop using them.
+ * Customers can rely on `id`, `pillar`, `status`, `appliesTo`,
+ * `codeRef`, `testRef`, `registeredAt`, `firstRegisteredIn`,
+ * and `bundledIn` being present on every contract in every
+ * future minor/patch release of this SDK.
+ */
+type ContractPillar = "revenue" | "entitlements" | "analytics" | "webhooks" | "errors" | "lifecycle" | "identity";
+type ContractStatus = "enforced" | "proposed" | "retired";
+type ContractAppliesTo = "web" | "node" | "react-native" | "swift" | "android" | "backend";
+interface ContractTestRef {
+    readonly file: string;
+    readonly name: string;
+}
+interface Contract {
+    readonly id: string;
+    readonly pillar: ContractPillar;
+    readonly status: ContractStatus;
+    readonly claim: string;
+    readonly appliesTo: readonly ContractAppliesTo[];
+    readonly codeRef: readonly string[];
+    readonly testRef: readonly ContractTestRef[];
+    readonly registeredAt: string;
+    readonly firstRegisteredIn: string;
+    readonly bundledIn: string;
+}
+/**
+ * Typed entry point to the bank-grade contracts bundled with this
+ * SDK release. Stable, side-effect-free, tree-shakeable.
+ *
+ * @example Audit at app boot
+ * ```ts
+ * import { CrossdeckContracts } from "@cross-deck/node";
+ *
+ * for (const c of CrossdeckContracts.all()) {
+ *   console.log(`[crossdeck] ${c.id} (${c.pillar})`);
+ * }
+ * ```
+ */
+declare const CrossdeckContracts: {
+    readonly all: () => readonly Contract[];
+    readonly allIncludingHistorical: () => readonly Contract[];
+    readonly byId: (id: string) => Contract | undefined;
+    readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
+    readonly withStatus: (status: ContractStatus) => readonly Contract[];
+    readonly sdkVersion: "1.5.0";
+    readonly bundledIn: "@cross-deck/node@1.5.0";
+    /**
+     * Resolve a failing test back to the contract it exercises.
+     * Used by test-framework hooks to find the contract id of a
+     * failed contract test so `reportContractFailure(...)` can stamp
+     * the right `contract_id` on the emitted event.
+     */
+    readonly findByTestName: (name: string) => Contract | undefined;
+};
+/**
+ * Input to {@link CrossdeckServer.reportContractFailure}. Mirrors
+ * the per-SDK shape exactly — the Crossdeck dashboard joins
+ * `crossdeck.contract_failed` events across every SDK on
+ * `contract_id`, so the property bag has to agree.
+ */
+interface ContractFailureInput {
+    contractId: string;
+    failureReason: string;
+    runContext: "ci" | "dogfood" | "customer-app";
+    runId: string;
+    testRef?: {
+        file: string;
+        name: string;
+    };
+    extra?: Record<string, unknown>;
+}
+
 /**
  * Breadcrumb ring buffer — context attached to every error report.
  *
@@ -251,8 +341,6 @@ interface RuntimeInfo {
     appVersion: string | null;
 }
 
-declare const SDK_NAME = "@cross-deck/node";
-declare const SDK_VERSION = "1.2.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 declare const DEFAULT_TIMEOUT_MS = 15000;
 /**
@@ -411,6 +499,10 @@ interface PurchaseResult {
     crossdeckCustomerId: string;
     env: Environment;
     entitlements: PublicEntitlement[];
+    /** True when the response came from the backend's idempotency
+     * cache instead of fresh processing. Backend also returns
+     * `Idempotent-Replayed: true` as a response header (v1.4.0). */
+    idempotent_replay?: boolean;
 }
 /**
  * Response shape from `GET /v1/sdk/heartbeat`. Used by
@@ -464,6 +556,25 @@ interface CrossdeckServerOptions {
      * not the source of truth.
      */
     appId?: string;
+    /**
+     * Apply Crossdeck's PII scrubber to every `track()` payload before
+     * enqueue. Default `true` (parity with Web / RN / Swift SDKs — Node
+     * pre-v1.4.0 was the odd one out and SHIPPED EMAILS UNREDACTED, a
+     * privacy contract drift versus the README claim).
+     *
+     * The scrubber rewrites email-shaped and card-number-shaped
+     * substrings to `<email>` / `<card>` sentinels recursively across
+     * nested maps + arrays. See `scrubPii` / `scrubPiiFromProperties`.
+     *
+     * **Blast radius of setting `false`:** every `track()` payload —
+     * including event names with embedded emails ("user wes@example.com
+     * upgraded"), trait values, group memberships, error context blobs
+     * — ships verbatim to Crossdeck and downstream warehouses /
+     * analytics exports. Disable only for explicit compliance use
+     * cases (regulator-required audit trails where the raw value MUST
+     * be preserved) and document the decision at the call site.
+     */
+    scrubPii?: boolean;
     /**
      * Error capture configuration. Default: ON with `onUncaughtException` +
      * `onUnhandledRejection` + `wrapFetch` all enabled.
@@ -674,6 +785,14 @@ interface RequestOptions {
      * `timeoutMs`. Pass `0` to disable.
      */
     timeoutMs?: number;
+    /**
+     * Override the deterministic Idempotency-Key derivation (v1.4.0).
+     * The SDK derives a stable key from the request body so retries
+     * collapse on the backend. Override only when an outer
+     * orchestrator (job runner, retry harness) needs a different
+     * idempotency window — and document why at the call site.
+     */
+    idempotencyKey?: string;
 }
 interface IdentityHints {
     customerId?: string;
@@ -1164,6 +1283,10 @@ declare class CrossdeckServer extends EventEmitter {
     private readonly baseUrl;
     private readonly appId;
     private readonly env;
+    /** PII scrubber toggle. Default true — parity with Web/RN/Swift.
+     * Pre-v1.4.0 the Node SDK shipped track() payloads UNREDACTED,
+     * a privacy contract drift versus the README. */
+    private readonly scrubPii;
     private readonly secretKeyPrefix;
     /**
      * Process-stable pseudo-anonymous ID. Used as the default identity
@@ -1209,22 +1332,22 @@ declare class CrossdeckServer extends EventEmitter {
     private errorContext;
     private errorTags;
     private errorBeforeSend;
+    /**
+     * Dedup gate for `sdk.shutdown`. Both `shutdown()` (async) and
+     * `shutdownSync()` need to emit so direct callers of EITHER see
+     * the event (the async path's listener guarantees pre-launch
+     * tests, the sync path covers `Symbol.dispose` + tests that call
+     * `shutdownSync()` directly). Without this flag, `shutdown()`'s
+     * tail call into `shutdownSync()` would emit twice.
+     */
+    private didEmitShutdown;
     constructor(options: CrossdeckServerOptions);
     /**
-     * Emit the one-time `sdk.boot` telemetry event and, when the runtime
-     * is serverless with no `entitlementStore`, the honest "no cold-start
-     * durability" warning.
-     *
-     * Why a `track()` event and not the heartbeat: `GET /v1/sdk/heartbeat`
-     * carries no request body, so it cannot transport a structured
-     * `durability` fact. The event pipeline can — every `track()` event
-     * lands as an aggregatable document the backend can query, so
-     * Crossdeck can compute fleet-wide "% serverless-with-no-durable-
-     * store" from `sdk.boot` events (denominator = all `sdk.boot`,
-     * numerator = those with `durability.coldStartDurable === false`).
-     * The event rides the existing batched + retried + idempotent queue
-     * and is drained by flush-on-exit, so it survives a serverless
-     * teardown — it is NOT a local-only debug log.
+     * Emit the honest "no cold-start durability" warning when the runtime
+     * is serverless AND no `entitlementStore` is wired. Local-only debug
+     * signal — no network call, no phone-home. Safe to fire from the
+     * constructor before `setImmediate` because there is no I/O on this
+     * path.
      *
      * `isServerless` AND no store is the gap: a cold start begins with an
      * empty in-memory cache and a brief Crossdeck outage in that window
@@ -1232,11 +1355,29 @@ declare class CrossdeckServer extends EventEmitter {
      * unavoidable without a store — so the SDK STATES it (a
      * `sdk.no_durable_store` debug warning) rather than hiding it.
      *
-     * Called once, from the deferred boot block — so it inherits the
-     * `testMode` / `bootHeartbeat:false` opt-outs and never fires before
-     * the constructor returns.
+     * Audit P1 #9: this used to live INSIDE `emitBootTelemetry()` which
+     * itself sat inside the `bootHeartbeat` gate, so any developer who
+     * set `bootHeartbeat: false` silently disabled the entire reason
+     * `entitlementStore` exists. Now split: warning fires
+     * unconditionally; the boot phone-home stays gated.
      */
-    private emitBootTelemetry;
+    private emitDurabilityWarning;
+    /**
+     * Emit the one-time `sdk.boot` telemetry event — the aggregatable
+     * fact the backend pivots on (compute fleet-wide
+     * "% serverless-with-no-durable-store"). Rides the batched + retried
+     * + idempotent queue and is drained by flush-on-exit, so it survives
+     * a serverless teardown.
+     *
+     * Why a `track()` event and not the heartbeat: `GET /v1/sdk/heartbeat`
+     * carries no request body, so it cannot transport a structured
+     * `durability` fact.
+     *
+     * Gated by `bootHeartbeat` (and `testMode`) because it IS a phone-
+     * home — the unconditional surface is `emitDurabilityWarning()`,
+     * which has no network call.
+     */
+    private emitBootTelemetryEvent;
     identify(userId: string, anonymousId: string, options?: IdentifyOptions & RequestOptions): Promise<AliasResult>;
     aliasIdentity(input: AliasIdentityInput, options?: RequestOptions): Promise<AliasResult>;
     forget(hints: IdentityHints, options?: RequestOptions): Promise<ForgetResult>;
@@ -1324,6 +1465,14 @@ declare class CrossdeckServer extends EventEmitter {
      *     `uncaughtException` has no per-request context; without the
      *     auto-fill, the event would be rejected at queue enqueue.
      */
+    /**
+     * Emit `crossdeck.contract_failed` with the canonical property
+     * shape. Same wire shape every Crossdeck SDK uses for contract
+     * verification telemetry — see `contracts/README.md` for the
+     * full pattern. No new endpoint, no special path; goes through
+     * the standard server-side `track()` pipeline.
+     */
+    reportContractFailure(input: ContractFailureInput): void;
     track(event: ServerEvent): void;
     /**
      * Immediate POST of one or more events. For bulk imports / replay
@@ -1534,11 +1683,36 @@ declare class CrossdeckServer extends EventEmitter {
     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.
+     * Tear down handlers and clear in-memory state.
+     *
+     * **v1.4.0 bank-grade contract:** `shutdown()` AWAITS `flush()`
+     * before dropping the queue, so callers don't silently lose
+     * every queued event on a clean shutdown. The pre-v1.4.0
+     * behaviour (sync `eventQueue.reset()` with no flush) was the
+     * default for both `shutdown()` and `[Symbol.dispose]`; only
+     * `await using` + `[Symbol.asyncDispose]` flushed correctly.
+     *
+     * Production servers should still prefer `await server.flush()`
+     * (visible) followed by `server.shutdown()` so the flush
+     * outcome is observable — `shutdown()`'s internal flush swallows
+     * errors as a best-effort drain.
+     *
+     * Use [[shutdownSync]] only when the runtime cannot await
+     * (e.g. inside `Symbol.dispose` — see below).
+     */
+    shutdown(reason?: "shutdown" | "dispose" | "asyncDispose"): Promise<void>;
+    /**
+     * Synchronous teardown — drops the in-memory queue WITHOUT
+     * flushing, then clears all in-memory state. Used by
+     * `[Symbol.dispose]` (which has no await) and tests that need
+     * an unconditional sync wipe. Production code should use
+     * [[shutdown]] (async) instead so queued events are flushed.
+     *
+     * A queue with items at sync-shutdown logs a warning recommending
+     * `[Symbol.asyncDispose]` or `await server.shutdown()` — silent
+     * loss is incompatible with the bank-grade contract.
      */
-    shutdown(reason?: "shutdown" | "dispose" | "asyncDispose"): void;
+    shutdownSync(reason?: "shutdown" | "dispose" | "asyncDispose"): void;
     /**
      * Convert a `CapturedError` into a `ServerEvent` and push through
      * `track()`. Goes through the same queue / enrichment / breadcrumb
@@ -1607,17 +1781,21 @@ declare class CrossdeckServer extends EventEmitter {
      *   // ... 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` is synchronous so it CANNOT await the queue
+     * flush.** A queue with pending events at sync-dispose time will
+     * be DROPPED — `shutdownSync` warns to the console when this
+     * happens. For the common case of "drain the queue before
+     * exit", switch to `await using` + `[Symbol.asyncDispose]` (or
+     * call `await server.shutdown()` explicitly before the variable
+     * goes out of scope).
      */
     [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).
+     * exits scope. Awaits the bank-grade `shutdown()` which flushes
+     * the queue THEN tears down. Use this variant for any code path
+     * that owns queued events at exit (serverless handlers,
+     * background workers, end-of-request hooks).
      *
      *   await using server = new CrossdeckServer({ ... });
      */
@@ -1677,6 +1855,15 @@ declare class CrossdeckServer extends EventEmitter {
      * Resolve any hint shape (canonical customerId / userId hint /
      * anonymousId hint / raw string) to a `crossdeckCustomerId` if we
      * have a cache entry for it.
+     *
+     * String overload is STRICT on the canonical-id shape. Pre-fix
+     * `isFresh(raw)` treated any string with a cache entry as a valid
+     * canonical id — if tenant A's userId happened to collide with
+     * tenant B's crossdeckCustomerId, A's call would resolve to B's
+     * cached entitlements. Bounded by the `cdcust_` prefix convention
+     * (which both SDKs and the backend mint, see
+     * backend/src/lib/customers.ts) — anything else is treated purely
+     * as an alias lookup, never as a canonical id. Audit P1 #19.
      */
     private resolveCacheCustomerId;
     private identityPayload;
@@ -1694,4 +1881,4 @@ declare class CrossdeckServer extends EventEmitter {
     private normalizeIngestEvent;
 }
 
-export { type ServerEvent as $, type AliasIdentityInput as A, type Breadcrumb as B, CROSSDECK_API_VERSION as C, DEFAULT_BASE_URL as D, type EntitlementCacheOptions as E, type ErrorLevel as F, type EventProperties as G, type ForgetResult as H, type GrantDuration as I, type GrantEntitlementInput as J, type GroupMembership as K, type HeartbeatResponse as L, type HttpRequestInfo as M, type HttpResponseInfo as N, type HttpRetriesConfig as O, type IdentifyOptions as P, type IdentityHints as Q, type IngestOptions as R, type IngestResponse as S, type PublicEntitlement as T, type PurchaseResult as U, type RequestOptions as V, type RevokeEntitlementInput as W, type RuntimeHost as X, type RuntimeInfo as Y, SDK_NAME as Z, SDK_VERSION as _, type AliasResult as a, type StackFrame as a0, type StoredEntitlements as a1, type SyncPurchaseInput as a2, makeCrossdeckError as a3, 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 EntitlementStore as v, type EntitlementsListResponse as w, type EntitlementsListener as x, type Environment as y, type ErrorCaptureConfig as z };
+export { type PurchaseResult as $, type AliasIdentityInput as A, type Breadcrumb as B, CROSSDECK_API_VERSION as C, DEFAULT_BASE_URL as D, type Diagnostics as E, type EntitlementCacheOptions as F, type EntitlementMutationResult as G, type EntitlementStore as H, type EntitlementsListResponse as I, type EntitlementsListener as J, type Environment as K, type ErrorCaptureConfig as L, type ErrorLevel as M, type EventProperties as N, type ForgetResult as O, type GrantDuration as P, type GrantEntitlementInput as Q, type GroupMembership as R, type HeartbeatResponse as S, type HttpRequestInfo as T, type HttpResponseInfo as U, type HttpRetriesConfig as V, type IdentifyOptions as W, type IdentityHints as X, type IngestOptions as Y, type IngestResponse as Z, type PublicEntitlement as _, type AliasResult as a, type RequestOptions as a0, type RevokeEntitlementInput as a1, type RuntimeHost as a2, type RuntimeInfo as a3, type ServerEvent as a4, type StackFrame as a5, type StoredEntitlements as a6, type SyncPurchaseInput as a7, makeCrossdeckError as a8, type AuditDecision as b, type AuditEntry as c, type BreadcrumbCategory as d, type BreadcrumbLevel as e, type CapturedError as f, type Contract as g, type ContractAppliesTo as h, type ContractFailureInput as i, type ContractPillar as j, type ContractStatus as k, type ContractTestRef as l, CrossdeckAuthenticationError as m, CrossdeckConfigurationError as n, CrossdeckContracts as o, CrossdeckError as p, type CrossdeckErrorPayload as q, type CrossdeckErrorType as r, CrossdeckInternalError as s, CrossdeckNetworkError as t, CrossdeckPermissionError as u, CrossdeckRateLimitError as v, CrossdeckServer as w, type CrossdeckServerOptions as x, CrossdeckValidationError as y, DEFAULT_TIMEOUT_MS as z };