@cross-deck/node 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to `@cross-deck/node` will be documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.1] — 2026-05-27
+
+`crossdeck.contract_failed` is now single-fire to a dedicated
+reliability endpoint instead of the customer's `track()` pipeline.
+Independent-controller flow per Privacy Policy §6; schema-locked by
+`contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+`ContractFailureInput.extra` removed (schema-lock forbids unbounded
+fields); `ContractFailureInput.deviceClass` added.
+
+## [1.5.0] — 2026-05-26
+
+Minor — `CrossdeckContracts` + `reportContractFailure(...)` ship as a
+new public surface on every SDK simultaneously. Additive only; no
+behavioural change to existing APIs.
+
+**Added:**
+
+- **`CrossdeckContracts` namespace** — typed access to the bank-grade
+  contract registry. Methods: `all()`, `allIncludingHistorical()`,
+  `byId(id)`, `byPillar(pillar)`, `withStatus(status)`,
+  `findByTestName(name)`. Properties: `sdkVersion`, `bundledIn`
+  (e.g. `"@cross-deck/node@1.5.0"`).
+- **`Contract` type + `ContractPillar` / `ContractStatus` /
+  `ContractAppliesTo` unions + `ContractTestRef` + `ContractFailureInput`
+  interfaces** exported from the top-level entry. Treated as
+  binary-stable.
+- **`CrossdeckServer.reportContractFailure(input)` method** — fires a
+  typed `crossdeck.contract_failed` server event through the standard
+  `track()` pipeline. Wire properties: `contract_id`, `sdk_version`
+  (auto-stamped), `sdk_platform` (auto-stamped to `"node"`),
+  `failure_reason`, `run_context` (`ci` | `dogfood` | `customer-app`),
+  `run_id`, plus optional `test_file` / `test_name` from `input.testRef`.
+
+**Fixed:**
+
+- `shutdownSync()` now emits the `sdk.shutdown` EventEmitter signal
+  with the correct reason — previously only the async `shutdown()`
+  path emitted, leaving consumers of `Symbol.dispose` /
+  `shutdownSync()` direct-callers blind. Async path is unchanged
+  thanks to a private dedup gate so listeners still fire exactly
+  once per teardown.
+- Test infrastructure: shutdown-flush + track-PII-scrub tests were
+  reading `body.data` from captured fetch payloads but the wire
+  shape uses `body.events` (matching backend + Web/RN SDKs). Tests
+  fixed to read the correct field; behaviour was already correct.
+
+**Changed:**
+
+- Contract registry source files migrated to camelCase keys
+  (`appliesTo`, `codeRef`, `testRef`, `registeredAt`,
+  `firstRegisteredIn`). The bundled `contracts.json` sidecar uses
+  the new keys; `bundledIn` is build-stamped, never in source.
+
 ## [1.4.2] — 2026-05-26
 
 Patch — fix `tests/shutdown-flush.test.ts` compile error under

package/README.md

@@ -569,6 +569,64 @@ const failed = results.filter((r) => !r.ok);
 
 Symmetric `bulkRevokeEntitlement(revokes[], options?)`.
 
+## Bank-grade contracts
+
+The SDK ships its own contracts registry — every behavioural guarantee the SDK makes (per-user cache isolation, deterministic Idempotency-Key, queue durability, etc.) lives in `contracts/**/*.json` at the monorepo root and is **bundled into every release**. The customer's lockfile pins SDK code + contracts atomically — drift between what the SDK does and what it claims is structurally impossible. See [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md) for the full architecture.
+
+### `CrossdeckContracts` — typed access to the bundled registry
+
+```ts
+import { CrossdeckContracts } from "@cross-deck/node";
+
+CrossdeckContracts.all();                              // enforced contracts only
+CrossdeckContracts.allIncludingHistorical();           // + proposed + retired
+CrossdeckContracts.byId("idempotency-key-deterministic");
+CrossdeckContracts.byPillar("revenue");
+CrossdeckContracts.withStatus("proposed");
+CrossdeckContracts.findByTestName("rail namespacing prevents cross-rail collisions");
+CrossdeckContracts.sdkVersion;        // "1.5.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/node@1.5.0"
+```
+
+The `Contract` type is exported alongside; the binary-stability promise is documented in [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md).
+
+### `crossdeckServer.reportContractFailure(input)` — surface contract test failures
+
+When a contract test asserts and fails — in your CI, a dogfood run, or a customer integration test — fire a typed `crossdeck.contract_failed` event over the **Crossdeck reliability channel**. This is one-way operational telemetry to the Crossdeck operations team (Privacy Policy §6, "Flow B"); it never enters your `track()` pipeline, never shows in your dashboard, never bills against your event quota. The wire shape is schema-locked at [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json):
+
+```ts
+import { CrossdeckServer } from "@cross-deck/node";
+
+const cd = new CrossdeckServer({ secretKey: process.env.CROSSDECK_SECRET_KEY! });
+
+cd.reportContractFailure({
+  contractId: "idempotency-key-deterministic",
+  failureReason: "expected cross-SDK oracle to match canonical vector, got drift",
+  runContext: process.env.CI ? "ci" : "dogfood",
+  runId: process.env.GITHUB_RUN_ID ?? crypto.randomUUID(),
+  testRef: {
+    file: "tests/idempotency-key.test.ts",
+    name: "apple JWS produces the canonical pinned UUID across all 5 SDKs",
+  },
+});
+```
+
+No new endpoint, no special ingest path — the event lands in the same pipeline every other server-side `track()` call does. It surfaces immediately in the dashboard's live event feed, the breakdown chart (group by `contract_id`, `sdk_platform`), and any alert rule with `event = crossdeck.contract_failed`.
+
+Properties stamped on the wire:
+
+| Property | Source |
+|----------|--------|
+| `contract_id` | caller |
+| `sdk_version`, `sdk_platform` | auto-stamped (`@cross-deck/node` ships `sdk_platform: "node"`) |
+| `failure_reason`, `run_context`, `run_id` | caller |
+| `test_file`, `test_name` | set when `testRef` is provided |
+| `device_class` | optional, set by caller (categorical bucket — e.g. `"linux-server"`, `"container"`, `"lambda"`) |
+
+The wire shape is schema-locked at [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json); per-SDK assertion tests gate it on every release. Free-form `extra` keys are not accepted — adding a field requires an amendment to the schema-lock contract first.
+
+For per-test-framework hooks see [`contracts/README.md` § Reporting contract failures](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md#reporting-contract-failures-back-to-crossdeck).
+
 ## Node version
 
 Node 18+. Uses the platform `fetch` and `node:crypto` — zero runtime dependencies.

package/dist/auto-events/index.d.mts

@@ -1,4 +1,4 @@
-import { w as CrossdeckServer } from '../crossdeck-server-oAaKBnUU.mjs';
+import { p as CrossdeckServer } from '../crossdeck-server-DhnHvUhh.mjs';
 import 'node:events';
 
 /**

package/dist/auto-events/index.d.ts

@@ -1,4 +1,4 @@
-import { w as CrossdeckServer } from '../crossdeck-server-oAaKBnUU.js';
+import { p as CrossdeckServer } from '../crossdeck-server-DhnHvUhh.js';
 import 'node:events';
 
 /**

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

@@ -111,96 +111,6 @@ 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.
  *
@@ -499,10 +409,6 @@ 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
@@ -556,25 +462,6 @@ 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.
@@ -785,14 +672,6 @@ 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;
@@ -1283,10 +1162,6 @@ 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
@@ -1332,15 +1207,6 @@ 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 honest "no cold-start durability" warning when the runtime
@@ -1465,14 +1331,6 @@ 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
@@ -1683,36 +1541,11 @@ declare class CrossdeckServer extends EventEmitter {
     getGroups(): Record<string, GroupMembership>;
     diagnostics(): Diagnostics;
     /**
-     * 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.
+     * Tear down handlers and clear in-memory state. Tests + custom
+     * lifecycle callers only. Production code should rely on
+     * `flush-on-exit` instead.
      */
-    shutdownSync(reason?: "shutdown" | "dispose" | "asyncDispose"): void;
+    shutdown(reason?: "shutdown" | "dispose" | "asyncDispose"): void;
     /**
      * Convert a `CapturedError` into a `ServerEvent` and push through
      * `track()`. Goes through the same queue / enrichment / breadcrumb
@@ -1781,21 +1614,17 @@ declare class CrossdeckServer extends EventEmitter {
      *   // ... use server ...
      *   // at end of block, server[Symbol.dispose]() runs automatically
      *
-     * **`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` 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 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).
+     * 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({ ... });
      */
@@ -1881,4 +1710,4 @@ declare class CrossdeckServer extends EventEmitter {
     private normalizeIngestEvent;
 }
 
-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 };
+export { type StoredEntitlements 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, type ServerEvent as Z, type StackFrame 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 EntitlementStore as v, type EntitlementsListResponse as w, type EntitlementsListener as x, type Environment as y, type ErrorCaptureConfig as z };