@cross-deck/node 1.3.1 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,107 @@ 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
+strict tsc. The five `s.track("name", { props })` calls used the
+web/RN positional-args shape; Node SDK's track takes a single
+`ServerEvent` object. Switched to `s.track({ name, properties })`.
+Plus a non-null assertion on `sent[0].length` for
+`noUncheckedIndexedAccess`. v1.4.1 was tagged on the public
+crossdeck-node repo but its publish workflow aborted on these
+errors. v1.4.2 is the first 1.4.x line to land on the npm
+registry. **No SDK code changes vs v1.4.0 / v1.4.1**.
+
+## [1.4.1] — 2026-05-26
+
+Patch — add automated npm publish workflow to the public
+`crossdeck-node` repo so future `vX.Y.Z` tag pushes auto-publish
+to npm via OIDC Trusted Publishing (matches the existing
+`crossdeck-web` pattern). Also strips `test:e2e` from
+`prepublishOnly` — the publish workflow runs lint + unit tests +
+build which covers the release gate. No SDK code changes vs
+v1.4.0.
+
+**Operator note:** npmjs.com Trusted Publisher rule must be
+configured for `crossdeck-node` (owner: VistaApps-za,
+workflow: publish.yml) before the OIDC publish succeeds. First
+publish after this lands will fail with an auth error if the
+rule is missing — that's the prompt to configure it.
+
+## [1.4.0] — 2026-05-26
+
+**Bank-grade reconciliation release.** 6-pillar KPMG-style audit closed across SDK + backend. Every behavioural guarantee registered in the monorepo's `contracts/` directory with a CI-enforced audit job.
+
+### Added
+
+- **PII scrubber applied on `track()` enqueue path** — parity with Web/RN/Swift. Pre-1.4.0 Node was the ONLY SDK that skipped this, shipping payloads UNREDACTED. New `scrubPii?: boolean` option (default true); explicit false opt-out preserves raw payloads for regulator-required audit trails.
+- **Deterministic `Idempotency-Key` on `syncPurchases()`** — same JWS/purchaseToken → same key. New `options.idempotencyKey` override for outer orchestrators.
+- **`PurchaseResult.idempotent_replay?: boolean`** — true when the backend replayed a cached response.
+- **`purchase.completed` event on every successful `syncPurchases()`** — funnel parity with Swift/Android auto-track.
+- **Distinguishable webhook verifier error codes** — pre-1.4.0 collapsed everything into `webhook_invalid_signature`. New: `webhook_signature_mismatch` (wrong-secret signal), `webhook_timestamp_outside_tolerance` (replay-attack signal — alert separately), `webhook_timestamp_missing`, `webhook_payload_not_json`, `webhook_invalid_tolerance`. Legacy codes deprecated with migration notes.
+- **Webhook verifier rejects footgun tolerances** — `Infinity` / `NaN` / negative / above-24h-cap now throw `webhook_invalid_tolerance` instead of silently disabling replay protection.
+- **15 backend-emitted error codes** added to the `crossdeck-error-codes.json` catalogue with Stripe-style remediation guidance.
+
+### Changed (breaking)
+
+- **`shutdown()` signature changed from `(reason) => void` to `(reason) => Promise<void>`.** Awaits `flush()` before tearing down the queue. Pre-1.4.0 it called `eventQueue.reset()` synchronously — every event between the last flush and shutdown was silently dropped. New `shutdownSync()` for callers that genuinely cannot await (signal handlers); it logs `console.warn` with the dropped-event count if the buffer is non-empty.
+- **Default event-queue flush interval is now 2000ms** (was 1500ms) — cross-SDK parity.
+- **`[Symbol.dispose]` now warns when dropping queued events.** Use `await using` + `[Symbol.asyncDispose]` (or `await server.shutdown()`) for proper drainage.
+
 ## [1.3.1] — 2026-05-24
 
 Patch fix for the 1.3.0 dist-load contract. Mirrors the

package/README.md

@@ -397,6 +397,14 @@ new CrossdeckServer({
 
 POST methods (`track`/`ingest`/`syncPurchases`/`grantEntitlement`/`revokeEntitlement`) DO NOT auto-retry at the HTTP layer. Retries happen via the event queue with per-batch `Idempotency-Key` reuse — the server can dedupe replays.
 
+**v1.4.0 — `syncPurchases` deterministic key.** The Idempotency-Key
+on `syncPurchases` is derived from the request body (UUID-shaped
+SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Two retries
+of the same Apple transaction land on the same key, so the backend
+short-circuits with `idempotent_replay: true` instead of
+double-processing. Override via `options.idempotencyKey` only when
+an outer orchestrator needs a different idempotency window.
+
 ### AbortSignal — caller-controlled cancellation
 
 Every async method accepts a final `RequestOptions?` with `{ signal, timeoutMs }`:
@@ -414,6 +422,60 @@ try {
 }
 ```
 
+### PII scrubber (v1.4.0 — parity with Web/RN/Swift)
+
+Every `track()` payload runs through `scrubPiiFromProperties`
+before enqueue — email-shaped and card-number-shaped substrings
+are rewritten to `<email>` / `<card>` sentinels recursively
+across nested objects + arrays. **Default: on.** Pre-v1.4.0 the
+Node SDK was the only one that skipped this, shipping payloads
+UNREDACTED despite the README promising parity.
+
+Opt out only for regulator-required audit trails where the raw
+value must be preserved:
+
+```ts
+new CrossdeckServer({ secretKey, scrubPii: false });
+```
+
+**Blast radius:** every `track()` payload — event names with
+embedded emails, trait values, group memberships, error context
+blobs — ships verbatim to Crossdeck and downstream warehouses /
+analytics exports. Document the decision at the call site.
+
+### Shutdown — flush before exit (v1.4.0 contract)
+
+The server holds a buffered event queue. A clean teardown MUST
+flush the buffer before dropping it, otherwise events queued
+between the last flush and shutdown are silently lost.
+
+**Three teardown paths, three contracts:**
+
+| Method | Flushes? | Use when |
+| ------ | -------- | -------- |
+| `await server.shutdown()` | YES — awaits internal `flush()` then tears down | Default. Use this in graceful-shutdown handlers. |
+| `await using server = ...` + `[Symbol.asyncDispose]` | YES — equivalent to `await server.shutdown()` | TC39 explicit-resource-management blocks. |
+| `server.shutdownSync()` / `using` + `[Symbol.dispose]` | NO — drops the buffer | ONLY when the runtime cannot await (signal handlers, process.exit fallthrough). |
+
+```ts
+// Graceful shutdown (recommended)
+process.on("SIGTERM", async () => {
+  await server.shutdown();
+  process.exit(0);
+});
+
+// Explicit-resource-management (Node 20+ / TS 5.2+)
+{
+  await using server = new CrossdeckServer({ secretKey });
+  // ... use server ...
+} // [Symbol.asyncDispose] fires here, awaits flush
+```
+
+`shutdownSync()` (and the sync `[Symbol.dispose]` that wraps it)
+logs a `console.warn` with the dropped-event count whenever the
+buffer is non-empty at sync-teardown time — silent loss is
+incompatible with the bank-grade contract.
+
 ### EventEmitter — internal events
 
 `CrossdeckServer extends EventEmitter`. Subscribe to internal lifecycle events with typed listeners:
@@ -507,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 { p as CrossdeckServer } from '../crossdeck-server-DhnHvUhh.mjs';
+import { w as CrossdeckServer } from '../crossdeck-server-CY4PZk-j.mjs';
 import 'node:events';
 
 /**

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

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