@cross-deck/node 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.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:

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-oAaKBnUU.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-oAaKBnUU.js';
 import 'node:events';
 
 /**

package/dist/contracts.json

@@ -0,0 +1,430 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "generatedAt": "2026-05-26T13:04:47.333Z",
+  "sdk": "@cross-deck/node",
+  "sdkVersion": "1.5.0",
+  "bundledIn": "@cross-deck/node@1.5.0",
+  "count": 9,
+  "contracts": [
+    {
+      "id": "documentation-honesty",
+      "pillar": "webhooks",
+      "status": "enforced",
+      "claim": "Customer-facing documentation honestly tags outbound webhook delivery as ROADMAP (no signer, no worker, no scheduler in backend/src yet). The Node verifier helper exists today for fixture authoring + locking the validation contract surface BEFORE delivery ships — its jsdoc carries an explicit `[ROADMAP]` disclaimer so a developer reading the source doesn't assume Crossdeck sends webhooks today. The rail-webhooks doc no longer claims state surfaces 'through the dashboard, SDKs, and outbound webhooks' — outbound is gated to the explicit roadmap section.",
+      "appliesTo": [
+        "node",
+        "backend"
+      ],
+      "codeRef": [
+        "sdks/node/src/webhooks.ts",
+        "docs/rail-webhooks/index.html",
+        "docs/webhooks-receive/index.html"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/node/src/webhooks.ts",
+          "name": "[ROADMAP — v1.4.0 honesty note]"
+        },
+        {
+          "file": "docs/rail-webhooks/index.html",
+          "name": "Outbound push-to-your-backend webhooks are <strong>roadmap</strong>"
+        },
+        {
+          "file": "docs/webhooks-receive/index.html",
+          "name": "This feature is on the roadmap"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.1",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "error-envelope-shape",
+      "pillar": "errors",
+      "status": "enforced",
+      "claim": "Every v1 REST endpoint returns errors in a Stripe-shape envelope: `{ error: { type, code, message, request_id } }` where `type` is one of authentication_error / permission_error / invalid_request_error / rate_limit_error / internal_error (the wire vocabulary in backend/src/api/v1-errors.ts ApiErrorType). HTTP status parity: invalid_request_error → 400, authentication_error → 401, permission_error → 403, rate_limit_error → 429, internal_error → 500. SDK-side clients parse this shape via `crossdeckErrorFromResponse` (Web/Node/RN) / `crossdeckErrorFrom(response:)` (Swift) / `crossdeckErrorFromResponse` (Android) and surface the request_id verbatim so support traces are end-to-end joinable. Firebase callable endpoints (managed-keys / dashboard auth) use the Firebase HttpsError envelope instead — this contract applies to REST /v1/* only.",
+      "appliesTo": [
+        "web",
+        "node",
+        "react-native",
+        "swift",
+        "android",
+        "backend"
+      ],
+      "codeRef": [
+        "backend/src/api/v1-errors.ts",
+        "sdks/web/src/errors.ts",
+        "sdks/node/src/errors.ts",
+        "sdks/react-native/src/errors.ts",
+        "sdks/swift/Sources/Crossdeck/Errors.swift",
+        "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Errors.kt"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+          "name": "test_errorEnvelope_fallsBackOnGarbageBody"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+          "name": "test_errorEnvelope_reads_XRequestId_fallback"
+        },
+        {
+          "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ErrorTypeWireVocabTest.kt",
+          "name": "backend 500 response parses to INTERNAL_ERROR"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 8 (codifies existing contract)",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "flush-interval-parity",
+      "pillar": "analytics",
+      "status": "enforced",
+      "claim": "Every Crossdeck SDK defaults its event-queue flush interval to 2000ms — the Stripe-adjacent industry norm. Pre-v1.4.0 the defaults disagreed (Web/Node 1500ms; RN/Swift/Android 5000ms), so cross-platform funnels saw events landing at different cadences. Per-instance override stays — call sites can still tune it freely.",
+      "appliesTo": [
+        "web",
+        "node",
+        "react-native",
+        "swift",
+        "android"
+      ],
+      "codeRef": [
+        "sdks/web/src/crossdeck.ts",
+        "sdks/node/src/crossdeck-server.ts",
+        "sdks/react-native/src/crossdeck.ts",
+        "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+        "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+          "name": "flushIntervalMs: Int = 2_000"
+        },
+        {
+          "file": "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt",
+          "name": "flushIntervalMs: Long = 2_000L"
+        },
+        {
+          "file": "sdks/web/src/crossdeck.ts",
+          "name": "options.eventFlushIntervalMs ?? 2000"
+        },
+        {
+          "file": "sdks/node/src/crossdeck-server.ts",
+          "name": "options.eventFlushIntervalMs ?? 2000"
+        },
+        {
+          "file": "sdks/react-native/src/crossdeck.ts",
+          "name": "options.eventFlushIntervalMs ?? 2000"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.3",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "idempotency-key-deterministic",
+      "pillar": "revenue",
+      "status": "enforced",
+      "claim": "syncPurchases() on every SDK derives a deterministic Idempotency-Key from the request body (UUID-shaped SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Same input -> same key. Backend short-circuits same-key-same-body retries by returning the cached response (status + body) with `idempotent_replay: true` flag in the body AND `Idempotent-Replayed: true` response header. Same-key-different-body returns 400 `idempotency_key_in_use`. 24-hour TTL matches Stripe. Cache only stores 2xx responses — 4xx/5xx pass through so callers can fix bugs and retry. Helper returns nil/throws on missing identifier (no silent random fallback). Cross-SDK parity is CI-pinned: deriveForPurchase('apple', 'eyJ.jws.sig') MUST equal 'a66b1640-efaf-bb4d-1261-6650033bf111' on every SDK.",
+      "appliesTo": [
+        "web",
+        "node",
+        "react-native",
+        "swift",
+        "android",
+        "backend"
+      ],
+      "codeRef": [
+        "sdks/web/src/idempotency-key.ts",
+        "sdks/web/src/crossdeck.ts",
+        "sdks/react-native/src/idempotency-key.ts",
+        "sdks/react-native/src/crossdeck.ts",
+        "sdks/node/src/idempotency-key.ts",
+        "sdks/node/src/crossdeck-server.ts",
+        "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+        "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+        "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+        "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt",
+        "backend/src/lib/idempotency-response-cache.ts",
+        "backend/src/api/v1-purchases.ts"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/web/tests/idempotency-key.test.ts",
+          "name": "cross-SDK oracle — apple JWS pins canonical vector"
+        },
+        {
+          "file": "sdks/web/tests/idempotency-key.test.ts",
+          "name": "is deterministic: same body twice -> identical key"
+        },
+        {
+          "file": "sdks/web/tests/idempotency-key.test.ts",
+          "name": "same identifier under different rails -> different keys"
+        },
+        {
+          "file": "sdks/web/tests/idempotency-key.test.ts",
+          "name": "never silently falls back to a random key on missing identifier"
+        },
+        {
+          "file": "sdks/react-native/tests/idempotency-key.test.ts",
+          "name": "is deterministic"
+        },
+        {
+          "file": "sdks/react-native/tests/idempotency-key.test.ts",
+          "name": "cross-SDK oracle — apple JWS pins canonical vector"
+        },
+        {
+          "file": "sdks/node/tests/idempotency-key.test.ts",
+          "name": "is deterministic"
+        },
+        {
+          "file": "sdks/node/tests/idempotency-key.test.ts",
+          "name": "rail namespacing prevents cross-rail collisions"
+        },
+        {
+          "file": "sdks/node/tests/idempotency-key.test.ts",
+          "name": "apple JWS produces the canonical pinned UUID across all 5 SDKs"
+        },
+        {
+          "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+          "name": "is deterministic for the same input"
+        },
+        {
+          "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+          "name": "injects idempotent_replay: true into a JSON object body"
+        },
+        {
+          "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+          "name": "matches Stripe's 24-hour idempotency window"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+          "name": "test_crossSdkOracle_appleJWS"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+          "name": "test_railNamespacing_preventsCrossRailCollisions"
+        },
+        {
+          "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+          "name": "test_missingIdentifier_returnsNil"
+        },
+        {
+          "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+          "name": "cross-SDK oracle for apple JWS"
+        },
+        {
+          "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+          "name": "rail namespacing prevents cross-rail collisions"
+        },
+        {
+          "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+          "name": "missing identifier returns null - never silent random fallback"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 2.2.a + 2.2.b + 2.2.c",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "node-pii-scrubber",
+      "pillar": "analytics",
+      "status": "enforced",
+      "claim": "Node SDK's track() applies scrubPiiFromProperties on the enqueue path — parity with Web/RN/Swift. Pre-v1.4.0 the Node SDK was the ONLY one that skipped this, shipping every track() payload UNREDACTED despite the README promising parity. CrossdeckServerOptions.scrubPii defaults to true; explicit false opts out for regulator-required audit trails with a documented blast-radius warning.",
+      "appliesTo": [
+        "node"
+      ],
+      "codeRef": [
+        "sdks/node/src/crossdeck-server.ts",
+        "sdks/node/src/types.ts",
+        "sdks/node/src/consent.ts"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/node/tests/track-pii-scrub.test.ts",
+          "name": "by default redacts email-shaped values to <email>"
+        },
+        {
+          "file": "sdks/node/tests/track-pii-scrub.test.ts",
+          "name": "redacts card-number-shaped values to <card>"
+        },
+        {
+          "file": "sdks/node/tests/track-pii-scrub.test.ts",
+          "name": "walks nested maps + arrays"
+        },
+        {
+          "file": "sdks/node/tests/track-pii-scrub.test.ts",
+          "name": "scrubPii: false preserves the raw payload (opt-out)"
+        },
+        {
+          "file": "sdks/node/tests/track-pii-scrub.test.ts",
+          "name": "scrubPii: true is the default when option is omitted"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.1",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "node-shutdown-awaits-flush",
+      "pillar": "lifecycle",
+      "status": "enforced",
+      "claim": "Node SDK's async shutdown() awaits the internal flush() before tearing down the queue. A queue with pending events at sync-shutdown time (shutdownSync() or [Symbol.dispose]) logs a console.warn with the dropped-event count — silent loss is incompatible with the bank-grade contract. [Symbol.asyncDispose] is equivalent to await server.shutdown().",
+      "appliesTo": [
+        "node"
+      ],
+      "codeRef": [
+        "sdks/node/src/crossdeck-server.ts"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/node/tests/shutdown-flush.test.ts",
+          "name": "async shutdown() flushes queued events before clearing"
+        },
+        {
+          "file": "sdks/node/tests/shutdown-flush.test.ts",
+          "name": "async shutdown() proceeds with teardown even if flush fails"
+        },
+        {
+          "file": "sdks/node/tests/shutdown-flush.test.ts",
+          "name": "sync shutdownSync() warns when the buffer has events at teardown"
+        },
+        {
+          "file": "sdks/node/tests/shutdown-flush.test.ts",
+          "name": "[Symbol.asyncDispose] equals await server.shutdown()"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 5.4",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "sdk-error-codes-catalogue",
+      "pillar": "errors",
+      "status": "enforced",
+      "claim": "Web + Node SDK error-codes catalogues include EVERY backend-emitted ApiErrorCode with a description + resolution. Pre-v1.4.0 the catalogues documented codes the SDK threw ITSELF but ZERO backend codes — a developer hitting `invalid_api_key` / `origin_not_allowed` / `bundle_id_not_allowed` / `env_mismatch` / `idempotency_key_in_use` etc. got `undefined` from getErrorCode() and had to hunt for guidance. v1.4.0 backfills the catalogue from backend/src/api/v1-errors.ts so every wire code has a canonical 'what does this mean / what should I do' answer Stripe-style.",
+      "appliesTo": [
+        "web",
+        "node"
+      ],
+      "codeRef": [
+        "sdks/web/src/error-codes.ts",
+        "sdks/node/src/error-codes.ts",
+        "backend/src/api/v1-errors.ts"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/web/tests/error-codes-backfill.test.ts",
+          "name": "includes backend code"
+        },
+        {
+          "file": "sdks/web/tests/error-codes-backfill.test.ts",
+          "name": "invalid_api_key resolution points at the dashboard"
+        },
+        {
+          "file": "sdks/web/tests/error-codes-backfill.test.ts",
+          "name": "idempotency_key_in_use resolution mentions Stripe-grade contract"
+        },
+        {
+          "file": "sdks/web/tests/error-codes-backfill.test.ts",
+          "name": "identity-lock codes carry permission_error type"
+        },
+        {
+          "file": "sdks/web/tests/error-codes-backfill.test.ts",
+          "name": "no entry has an empty description or resolution"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 6.2",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "sync-purchases-funnel-parity",
+      "pillar": "analytics",
+      "status": "enforced",
+      "claim": "Manual syncPurchases() emits a `purchase.completed` analytics event on success across ALL SDKs (Web / Node / RN / Swift / Android). Pre-v1.4.0 only Swift/Android auto-track emitted it — Web/Node/RN manual calls + Swift/Android manual calls fired ZERO analytics. Schema mirrors the auto-track event name + rail/productId/subscriptionId so cross-platform funnels reconcile on every payment path. When the backend short-circuits via the v1.4.0 idempotency cache, the event also carries `idempotent_replay: true`.",
+      "appliesTo": [
+        "web",
+        "node",
+        "react-native",
+        "swift",
+        "android"
+      ],
+      "codeRef": [
+        "sdks/web/src/crossdeck.ts",
+        "sdks/node/src/crossdeck-server.ts",
+        "sdks/react-native/src/crossdeck.ts",
+        "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+        "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+          "name": "emits purchase.completed after a successful sync"
+        },
+        {
+          "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+          "name": "carries idempotent_replay=true when backend replied from cache"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.5",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    },
+    {
+      "id": "verifier-timestamp-mandatory",
+      "pillar": "webhooks",
+      "status": "enforced",
+      "claim": "Node verifyWebhookSignature() enforces a MANDATORY timestamp window. Pre-v1.4.0 the helper silently disabled replay protection on tolerance=0 (`if (tolerance > 0)` skipped the check) and on Infinity/NaN/null (`Math.abs(...) > Infinity = false`). v1.4.0 rejects non-finite / negative / above-24h-cap tolerances at the boundary with typed `webhook_invalid_tolerance` and always runs the drift check. Verification failures are surfaced via distinguishable codes: `webhook_signature_mismatch` (wrong-secret signal), `webhook_timestamp_outside_tolerance` (replay-attack signal — alert separately), `webhook_timestamp_missing` (header absent/malformed), `webhook_payload_not_json` (tampered post-signing), `webhook_missing_secret`, `webhook_invalid_tolerance` — replaces the pre-1.4.0 single `webhook_invalid_signature` catch-all.",
+      "appliesTo": [
+        "node"
+      ],
+      "codeRef": [
+        "sdks/node/src/webhooks.ts",
+        "sdks/node/src/error-codes.ts"
+      ],
+      "testRef": [
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "tolerance of 0 still enforces the replay window (v1.4.0 — cannot disable)"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "rejects Infinity tolerance (would silently disable replay protection)"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "rejects NaN tolerance"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "rejects negative tolerance"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "rejects tolerance above the 24h cap"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "rejects non-number tolerance (null / string)"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "accepts tolerance exactly at the 24h cap"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "malformed header (no t= or no v1=) throws webhook_timestamp_missing"
+        },
+        {
+          "file": "sdks/node/tests/webhooks.test.ts",
+          "name": "valid signature but non-JSON payload throws webhook_payload_not_json"
+        }
+      ],
+      "registeredAt": "2026-05-26",
+      "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.2",
+      "bundledIn": "@cross-deck/node@1.5.0"
+    }
+  ]
+}