@cross-deck/node 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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).
 
+## [Unreleased]
+
+## [1.8.1] — 2026-06-21
+
+**Docs.** The README now opens with the Buckets preview — "where your reads go,
+before and after a fix" — so you can see what Crossdeck reports back before you
+read a line of API. No code change; SDK behaviour is identical to 1.8.0.
+
+## [1.8.0] — 2026-06-21
+
+**Self-defends against re-instantiation (Next.js / serverless).** Constructing
+`new CrossdeckServer()` at module top-level is the documented pattern, but
+frameworks like Next.js re-evaluate module scope (HMR, per-route isolation, chunk
+splitting), so it could run many times in one process — each time firing another
+boot heartbeat, starting another flush timer, stacking another set of process
+listeners (`beforeExit` / `SIGTERM` / `uncaughtException` / `unhandledRejection`),
+and re-wrapping global `fetch`. That produced a storm of duplicate phone-homes and
+an `EventEmitter` max-listeners warning. The SDK now guards against it — minor,
+backwards-compatible.
+
+**Fixed:**
+
+- **Singleton guard.** The constructor now returns the EXISTING instance for the
+  same credentials (secretKey + appId + baseUrl) instead of building a second one,
+  so re-evaluation never re-boots. Same defence Prisma / Firebase Admin ship for
+  the same reason. New `CrossdeckServer.clearSingletonCache()` static for tests /
+  bespoke hot-reload teardown.
+- **Idempotent `fetch` wrap.** The error-capture fetch wrapper tags itself and
+  skips wrapping an already-wrapped `fetch`, so a double-install can't
+  double-capture every request.
+
 ## [1.7.0] — 2026-06-11
 
 **PARK on version-rejection — events are held, never dropped.** A third

package/README.md

@@ -2,6 +2,10 @@
 
 The Crossdeck server SDK for Node.js — one install, three pillars: **errors**, **analytics**, **entitlements**.
 
+![Crossdeck Buckets — where your reads go, before and after a fix](assets/buckets-preview.svg)
+
+**This is what you get back.** Crossdeck shows you where your database reads actually go — and what a fix did to them, hour by hour, before and after you shipped it. Ship a change, and the dashboard above tells you whether the curve bent. It's live in every Crossdeck project. [See it on your own data →](https://cross-deck.com)
+
 ```bash
 npm install @cross-deck/node
 ```
@@ -42,6 +46,8 @@ if (crossdeck.isEntitled({ userId: "user_847" }, "pro")) {
 }
 ```
 
+Construct the client **once** at module scope and import it where you need it. This is safe even under frameworks that re-evaluate modules (Next.js HMR, per-route isolation, React Server Components): for a given secret key the SDK returns the same instance every time, so you never get a duplicate client. _(Single-instance guard added in 1.8.0.)_
+
 ## Three USPs, one SDK
 
 ### USP 1 — Errors
@@ -368,7 +374,7 @@ try {
 }
 ```
 
-Subclasses: `CrossdeckAuthenticationError`, `CrossdeckPermissionError`, `CrossdeckValidationError`, `CrossdeckRateLimitError`, `CrossdeckNetworkError`, `CrossdeckInternalError`, `CrossdeckConfigurationError`. All extend `CrossdeckError`. Constructed automatically by the SDK — you never need to instantiate them yourself.
+Subclasses: `CrossdeckAuthenticationError`, `CrossdeckPermissionError`, `CrossdeckValidationError`, `CrossdeckRateLimitError`, `CrossdeckNetworkError`, `CrossdeckInternalError`, `CrossdeckConfigurationError`. All extend `CrossdeckError`. The `version_error` type (code `sdk_version_unsupported`, HTTP 426) carries `minVersion`/`surface` and routes to PARK — see "Outdated-version PARK" above. Constructed automatically by the SDK — you never need to instantiate them yourself.
 
 `CrossdeckErrorCode` is the literal union of every documented code in `CROSSDECK_ERROR_CODES`. Use `isCrossdeckErrorCode` to narrow `string` to the union for type-safe comparisons (catches misspelled codes at compile time).
 
@@ -397,6 +403,12 @@ 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.
 
+### Outdated-version PARK (v1.7.0)
+
+If the server ever stops accepting this SDK version's event format, the rejection is machine-distinguishable — HTTP `426` with code `sdk_version_unsupported` — and the queue treats it as its own outcome, distinct from retry (transient) and drop (invalid): the events are **parked**. The queue holds them (FIFO-capped at 1,000), stops flushing a known-too-old payload, warns once on the console naming the exact version to update to, and fires the `onParked` callback + a typed `sdk.parked` debug event.
+
+**Honest bound:** the Node queue is in-memory, so a process restart *before* you upgrade clears the held events — an opt-in disk-backed queue is on the roadmap. After you deploy the upgraded SDK, held events deliver on the next flush. Web/RN/Swift hold theirs durably across restarts. Full story: [the durability contract](https://cross-deck.com/docs/sdk-event-durability/).
+
 **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
@@ -584,8 +596,8 @@ 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"
+CrossdeckContracts.sdkVersion;        // "1.7.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/node@1.7.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).

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

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

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

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

package/dist/{crossdeck-server-DYawt4eT.d.mts → crossdeck-server-DrLCOoeB.d.mts}

@@ -183,8 +183,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.6.0";
-    readonly bundledIn: "@cross-deck/node@1.6.0";
+    readonly sdkVersion: "1.8.1";
+    readonly bundledIn: "@cross-deck/node@1.8.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1385,6 +1385,14 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private didEmitShutdown;
     constructor(options: CrossdeckServerOptions);
+    /**
+     * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+     * for the same credentials (the Next.js / serverless re-instantiation guard in
+     * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+     * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+     * only — production code never needs it.
+     */
+    static clearSingletonCache(): void;
     /**
      * Emit the honest "no cold-start durability" warning when the runtime
      * is serverless AND no `entitlementStore` is wired. Local-only debug

package/dist/{crossdeck-server-DYawt4eT.d.ts → crossdeck-server-DrLCOoeB.d.ts}

@@ -183,8 +183,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.6.0";
-    readonly bundledIn: "@cross-deck/node@1.6.0";
+    readonly sdkVersion: "1.8.1";
+    readonly bundledIn: "@cross-deck/node@1.8.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1385,6 +1385,14 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private didEmitShutdown;
     constructor(options: CrossdeckServerOptions);
+    /**
+     * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+     * for the same credentials (the Next.js / serverless re-instantiation guard in
+     * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+     * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+     * only — production code never needs it.
+     */
+    static clearSingletonCache(): void;
     /**
      * Emit the honest "no cold-start durability" warning when the runtime
      * is serverless AND no `entitlementStore` is wired. Local-only debug

package/dist/index.cjs

@@ -387,7 +387,7 @@ function byteLength(s) {
 var https = __toESM(require("https"));
 
 // src/_version.ts
-var SDK_VERSION = "1.7.0";
+var SDK_VERSION = "1.8.1";
 var SDK_NAME = "@cross-deck/node";
 
 // src/_diagnostic-telemetry.ts
@@ -1433,6 +1433,7 @@ var ErrorTracker = class {
   installFetchWrap() {
     const origFetch = globalThis.fetch;
     if (typeof origFetch !== "function") return;
+    if (origFetch.__crossdeckWrapped__) return;
     const tracker = this;
     const wrapped = async (...args) => {
       const input = args[0];
@@ -1473,6 +1474,7 @@ var ErrorTracker = class {
         throw err;
       }
     };
+    wrapped.__crossdeckWrapped__ = true;
     globalThis.fetch = wrapped;
     this.cleanups.push(() => {
       if (globalThis.fetch === wrapped) globalThis.fetch = origFetch;
@@ -2678,6 +2680,9 @@ function safeJson(obj) {
 
 // src/crossdeck-server.ts
 var CrossdeckServer = class extends import_node_events.EventEmitter {
+  // `!` (definite assignment): these are assigned on the real construction path,
+  // but the singleton guard in the constructor can `return` an existing instance
+  // before reaching them — that early return is the only path that skips them.
   http;
   sdkVersion;
   baseUrl;
@@ -2773,6 +2778,13 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     this.appId = options.appId;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.env = inferEnvFromKey(options.secretKey);
+    const _store = globalThis;
+    const _singletonKey = `${options.secretKey}|${this.appId ?? ""}|${this.baseUrl}`;
+    _store.__crossdeckServers__ ??= /* @__PURE__ */ new Map();
+    const _existing = _store.__crossdeckServers__.get(_singletonKey);
+    if (_existing) {
+      return _existing;
+    }
     this.secretKeyPrefix = maskSecretKey(options.secretKey);
     this.scrubPii = options.scrubPii !== false;
     this.http = new HttpClient({
@@ -2914,6 +2926,17 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         this.emitBootTelemetryEvent();
       });
     }
+    _store.__crossdeckServers__.set(_singletonKey, this);
+  }
+  /**
+   * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+   * for the same credentials (the Next.js / serverless re-instantiation guard in
+   * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+   * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+   * only — production code never needs it.
+   */
+  static clearSingletonCache() {
+    globalThis.__crossdeckServers__?.clear();
   }
   /**
    * Emit the honest "no cold-start durability" warning when the runtime
@@ -4573,8 +4596,8 @@ function normaliseSecrets(input) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/node@1.6.0";
-var SDK_VERSION2 = "1.6.0";
+var BUNDLED_IN = "@cross-deck/node@1.8.1";
+var SDK_VERSION2 = "1.8.1";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -4696,7 +4719,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "documentation-honesty",
@@ -4728,7 +4751,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.1",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "error-envelope-shape",
@@ -4767,7 +4790,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "flush-interval-parity",
@@ -4812,7 +4835,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "idempotency-key-deterministic",
@@ -4917,7 +4940,63 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
+  },
+  {
+    "id": "invalid-input-rejected-natively",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "No public SDK API ever crashes the host app, and invalid input never reaches the wire. Invalid input (empty event name, empty userId, out-of-range config such as a non-positive breadcrumb capacity, NaN/Infinity/oversize/cyclic property values) is rejected at the call site WITHOUT a fatal trap. The signalling IDIOM is per-language and intentionally NOT uniform: Web, Node, and React Native THROW a typed CrossdeckError synchronously (code missing_event_name / missing_user_id / invalid_request_error) \u2014 a normal, catchable JavaScript convention where an uncaught throw logs and the app continues; Swift DROPS with a debug-log signal (track_dropped / identify_dropped) to match its non-throwing fire-and-forget surface, and exposes the throwing equivalent only via identifyAndWait(userId:). What is UNIFORM is the invariant, not the mechanism: every SDK rejects the same inputs, no public fire-and-forget API contains a fatalError / assertionFailure / precondition reachable from customer input, and no rejected input is enqueued or transmitted. Swift additionally proves this in BOTH debug and release configuration, because precondition fires under -O while assertionFailure does not. The bug class this contract closes was never the per-language difference \u2014 it was the UNDECLARED difference: each SDK's public API documentation must state its own semantics explicitly (TS docs: 'throws on empty name'; Swift docs: 'drops and logs').",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift"
+    ],
+    "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/swift/Sources/Crossdeck/Breadcrumbs.swift"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/crossdeck.test.ts",
+        "name": "track with empty name throws synchronously"
+      },
+      {
+        "file": "sdks/web/tests/crossdeck.test.ts",
+        "name": "rejects empty userId"
+      },
+      {
+        "file": "sdks/node/tests/crossdeck-server.test.ts",
+        "name": "track() throws CrossdeckError with code 'missing_event_name' when event name is empty"
+      },
+      {
+        "file": "sdks/react-native/tests/crossdeck.test.ts",
+        "name": "track('') throws CrossdeckError(missing_event_name) synchronously"
+      },
+      {
+        "file": "sdks/react-native/tests/crossdeck.test.ts",
+        "name": "identify('') rejects with CrossdeckError(missing_user_id)"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/CrossdeckPublicAPITests.swift",
+        "name": "test_track_dropsEmptyName"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/CrossdeckPublicAPITests.swift",
+        "name": "test_identifyAndWait_rejectsEmptyId"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/PublicAPIInputSafetyTests.swift",
+        "name": "test_start_withZeroBreadcrumbCapacity_doesNotTrap"
+      }
+    ],
+    "registeredAt": "2026-06-11",
+    "firstRegisteredIn": "swift trap-on-input class fix \u2014 first machine-tested Swift release",
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "node-pii-scrubber",
@@ -4956,7 +5035,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.1",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "node-shutdown-awaits-flush",
@@ -4989,7 +5068,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.4",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "sdk-error-codes-catalogue",
@@ -5034,7 +5113,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "sync-purchases-funnel-parity",
@@ -5067,7 +5146,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   },
   {
     "id": "verifier-timestamp-mandatory",
@@ -5121,7 +5200,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.2",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.1"
   }
 ]);