@cross-deck/node 1.5.3 → 1.6.0

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).
 
+## [1.6.0] — 2026-06-10
+
+Event Envelope v1 conformance — server-enforced contract (spec
+`backend/docs/event-envelope-spec-v1.md`).
+
+**Added:**
+
+- **`envelopeVersion: 1`** (integer) on every batch POST body. Both the
+  queue-flush path (`EventQueue.flush()`) and the direct `ingest()` path
+  now emit this field. The server will reject payloads missing this field
+  once ingest enforcement lands.
+- **`seq`** (number) on every wire event — per-session monotonic sequence
+  number. Captured synchronously with the event's `timestamp` at
+  `track()` / enqueue time. Counter starts at 0 when the `CrossdeckServer`
+  instance is constructed (session start) and increments once per event.
+  Matches spec §3: monotonic within a session, never reset between
+  background/foreground (Node has no such lifecycle; the instance lifetime
+  IS the session).
+- **`context`** (object) on every wire event — standardized device/platform
+  context (spec §4), promoted out of `properties`. Common fields: `os`,
+  `osVersion`, `appVersion`, `sdkName`, `sdkVersion`, `locale`, `timezone`.
+  Node-specific: `nodeVersion`, `host`, `region` (the existing
+  `runtime.*` props, promoted).
+
+**Changed:**
+
+- `track()` no longer merges `runtime.*` keys into `properties`. Those
+  facts now live in the top-level `context` object on the wire event.
+  Super-properties registered via `server.register()` continue to appear
+  in `properties` unchanged (caller-supplied values are unaffected).
+
 ## [1.5.1] — 2026-05-27
 
 `crossdeck.contract_failed` is now single-fire to a dedicated

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

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

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

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

package/dist/contracts.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-05-27T15:20:14.974Z",
+  "generatedAt": "2026-06-10T12:59:27.493Z",
   "sdk": "@cross-deck/node",
-  "sdkVersion": "1.5.3",
-  "bundledIn": "@cross-deck/node@1.5.3",
+  "sdkVersion": "1.6.0",
+  "bundledIn": "@cross-deck/node@1.6.0",
   "count": 10,
   "contracts": [
     {
@@ -126,7 +126,7 @@
         "legal/security/index.html#diagnostic",
         "legal/sdk-data/index.html#b-diagnostic"
       ],
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "documentation-honesty",
@@ -158,7 +158,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.1",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "error-envelope-shape",
@@ -197,7 +197,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 8 (codifies existing contract)",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "flush-interval-parity",
@@ -242,7 +242,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.3",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "idempotency-key-deterministic",
@@ -347,7 +347,7 @@
       ],
       "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.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "node-pii-scrubber",
@@ -386,7 +386,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.1",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "node-shutdown-awaits-flush",
@@ -419,7 +419,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 5.4",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "sdk-error-codes-catalogue",
@@ -433,9 +433,14 @@
       "codeRef": [
         "sdks/web/src/error-codes.ts",
         "sdks/node/src/error-codes.ts",
+        "sdks/web/src/_contract-verifiers.ts",
         "backend/src/api/v1-errors.ts"
       ],
       "testRef": [
+        {
+          "file": "sdks/web/tests/contract-verifiers.test.ts",
+          "name": "sdk-error-codes-catalogue covers every backend wire code with remediation"
+        },
         {
           "file": "sdks/web/tests/error-codes-backfill.test.ts",
           "name": "includes backend code"
@@ -459,7 +464,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 6.2",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "sync-purchases-funnel-parity",
@@ -492,7 +497,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.5",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     },
     {
       "id": "verifier-timestamp-mandatory",
@@ -546,7 +551,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.2",
-      "bundledIn": "@cross-deck/node@1.5.3"
+      "bundledIn": "@cross-deck/node@1.6.0"
     }
   ]
 }

package/dist/{crossdeck-server-BFTTwCEP.d.mts → crossdeck-server-C1Ue0rv4.d.mts}

@@ -173,8 +173,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.5.3";
-    readonly bundledIn: "@cross-deck/node@1.5.3";
+    readonly sdkVersion: "1.6.0";
+    readonly bundledIn: "@cross-deck/node@1.6.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1312,6 +1312,8 @@ declare class CrossdeckServer extends EventEmitter {
     private readonly processAnonymousId;
     private readonly runtime;
     private readonly runtimeProperties;
+    /** Envelope v1 §4 context object — built once at SDK init, reused on every event. */
+    private readonly eventContext;
     private readonly breadcrumbs;
     private readonly eventQueue;
     private readonly errorTracker;
@@ -1329,6 +1331,23 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private readonly entitlementStore;
     private readonly debug;
+    /**
+     * Event Envelope v1 §3 — per-session monotonic sequence counter.
+     *
+     * Node has no mobile "session" lifecycle (no app launch / background /
+     * foreground). We model a session as the SDK instance lifetime: the
+     * counter starts at 0 on construction and increments once per
+     * `track()` call. `session.started` is the boot-telemetry event
+     * (the first `track()` called from `emitBootTelemetryEvent()`), so
+     * the seq will be 0 for that event, matching the spec's "reset to 0
+     * at session.started" clause — by construction, it's the zeroth event
+     * of this instance's lifecycle.
+     *
+     * The counter persists for the entire process lifetime of the SDK
+     * instance (spec §3 clause 1: background/foreground does not reset).
+     * A new `CrossdeckServer` construction is the only reset (new session).
+     */
+    private sessionSeq;
     /**
      * Alias map — `developerUserId` / `anonymousId` → canonical
      * `crossdeckCustomerId`. Populated by `getEntitlements()` so a

package/dist/{crossdeck-server-BFTTwCEP.d.ts → crossdeck-server-C1Ue0rv4.d.ts}

@@ -173,8 +173,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.5.3";
-    readonly bundledIn: "@cross-deck/node@1.5.3";
+    readonly sdkVersion: "1.6.0";
+    readonly bundledIn: "@cross-deck/node@1.6.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1312,6 +1312,8 @@ declare class CrossdeckServer extends EventEmitter {
     private readonly processAnonymousId;
     private readonly runtime;
     private readonly runtimeProperties;
+    /** Envelope v1 §4 context object — built once at SDK init, reused on every event. */
+    private readonly eventContext;
     private readonly breadcrumbs;
     private readonly eventQueue;
     private readonly errorTracker;
@@ -1329,6 +1331,23 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private readonly entitlementStore;
     private readonly debug;
+    /**
+     * Event Envelope v1 §3 — per-session monotonic sequence counter.
+     *
+     * Node has no mobile "session" lifecycle (no app launch / background /
+     * foreground). We model a session as the SDK instance lifetime: the
+     * counter starts at 0 on construction and increments once per
+     * `track()` call. `session.started` is the boot-telemetry event
+     * (the first `track()` called from `emitBootTelemetryEvent()`), so
+     * the seq will be 0 for that event, matching the spec's "reset to 0
+     * at session.started" clause — by construction, it's the zeroth event
+     * of this instance's lifecycle.
+     *
+     * The counter persists for the entire process lifetime of the SDK
+     * instance (spec §3 clause 1: background/foreground does not reset).
+     * A new `CrossdeckServer` construction is the only reset (new session).
+     */
+    private sessionSeq;
     /**
      * Alias map — `developerUserId` / `anonymousId` → canonical
      * `crossdeckCustomerId`. Populated by `getEntitlements()` so a

package/dist/index.cjs

@@ -378,7 +378,7 @@ function byteLength(s) {
 var https = __toESM(require("https"));
 
 // src/_version.ts
-var SDK_VERSION = "1.5.3";
+var SDK_VERSION = "1.6.0";
 var SDK_NAME = "@cross-deck/node";
 
 // src/_diagnostic-telemetry.ts
@@ -962,6 +962,11 @@ var EventQueue = class {
     try {
       const env = this.cfg.envelope();
       const body = {
+        // Event Envelope v1 §1 — schema/wire version the server uses to
+        // decide whether it can parse this payload. Integer 1; only bumped
+        // on a breaking wire change. Distinct from sdk.version (which
+        // answers "which build?") — two questions, two fields.
+        envelopeVersion: 1,
         events: batch,
         sdk: env.sdk
       };
@@ -1946,6 +1951,25 @@ function runtimeInfoToProperties(info) {
   if (info.appVersion) out.appVersion = info.appVersion;
   return out;
 }
+function buildEventContext(info, sdkName, sdkVersion) {
+  const ctx = {
+    // Common fields (spec §4, all platforms)
+    os: info.platform,
+    osVersion: info.platformRelease,
+    appVersion: info.appVersion ?? null,
+    sdkName,
+    sdkVersion,
+    // locale / timezone: Node has no process-level locale by default;
+    // surface them from the environment if available, otherwise null.
+    locale: typeof process !== "undefined" && process.env["LANG"] || null,
+    timezone: typeof Intl !== "undefined" && Intl.DateTimeFormat().resolvedOptions().timeZone || null,
+    // Node-specific runtime context (spec §4 Node section)
+    nodeVersion: info.nodeVersion,
+    host: info.host,
+    region: info.region ?? null
+  };
+  return ctx;
+}
 
 // src/flush-on-exit.ts
 var SIGNALS = ["SIGTERM", "SIGINT"];
@@ -2613,6 +2637,8 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
   processAnonymousId;
   runtime;
   runtimeProperties;
+  /** Envelope v1 §4 context object — built once at SDK init, reused on every event. */
+  eventContext;
   breadcrumbs;
   eventQueue;
   errorTracker;
@@ -2630,6 +2656,23 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
    */
   entitlementStore;
   debug;
+  /**
+   * Event Envelope v1 §3 — per-session monotonic sequence counter.
+   *
+   * Node has no mobile "session" lifecycle (no app launch / background /
+   * foreground). We model a session as the SDK instance lifetime: the
+   * counter starts at 0 on construction and increments once per
+   * `track()` call. `session.started` is the boot-telemetry event
+   * (the first `track()` called from `emitBootTelemetryEvent()`), so
+   * the seq will be 0 for that event, matching the spec's "reset to 0
+   * at session.started" clause — by construction, it's the zeroth event
+   * of this instance's lifecycle.
+   *
+   * The counter persists for the entire process lifetime of the SDK
+   * instance (spec §3 clause 1: background/foreground does not reset).
+   * A new `CrossdeckServer` construction is the only reset (new session).
+   */
+  sessionSeq = 0;
   /**
    * Alias map — `developerUserId` / `anonymousId` → canonical
    * `crossdeckCustomerId`. Populated by `getEntitlements()` so a
@@ -2689,6 +2732,7 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
       appVersion: options.appVersion
     });
     this.runtimeProperties = runtimeInfoToProperties(this.runtime);
+    this.eventContext = buildEventContext(this.runtime, SDK_NAME, this.sdkVersion);
     this.breadcrumbs = new BreadcrumbBuffer(options.breadcrumbsMaxSize ?? 50);
     this.superProps = new SuperPropertyStore();
     this.entitlementCache = new EntitlementCache({
@@ -3140,7 +3184,6 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
       }
     }
     const properties = {
-      ...this.runtimeProperties,
       ...this.superProps.getSuperProperties(),
       ...sanitized
     };
@@ -3149,10 +3192,14 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
       properties.$groups = groupIds;
     }
     const identity = this.resolveIdentity(event);
+    const seq = this.sessionSeq++;
+    const timestamp = event.timestamp ?? Date.now();
     const queued = {
       eventId: event.eventId ?? mintId("evt", 8),
       name: event.name,
-      timestamp: event.timestamp ?? Date.now(),
+      timestamp,
+      seq,
+      context: this.eventContext,
       properties,
       ...identity
     };
@@ -3191,6 +3238,8 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     }
     const normalized = events.map((event) => this.normalizeIngestEvent(event));
     const body = {
+      // Event Envelope v1 §1 — wire version (parity with the queue path).
+      envelopeVersion: 1,
       events: normalized,
       sdk: { name: SDK_NAME, version: this.sdkVersion },
       // Match the queue's batch envelope (see event-queue.ts) — backend
@@ -4449,8 +4498,8 @@ function normaliseSecrets(input) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/node@1.5.3";
-var SDK_VERSION2 = "1.5.3";
+var BUNDLED_IN = "@cross-deck/node@1.6.0";
+var SDK_VERSION2 = "1.6.0";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -4572,7 +4621,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/node@1.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "documentation-honesty",
@@ -4604,7 +4653,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "error-envelope-shape",
@@ -4643,7 +4692,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "flush-interval-parity",
@@ -4688,7 +4737,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "idempotency-key-deterministic",
@@ -4793,7 +4842,7 @@ 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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "node-pii-scrubber",
@@ -4832,7 +4881,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "node-shutdown-awaits-flush",
@@ -4865,7 +4914,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "sdk-error-codes-catalogue",
@@ -4879,9 +4928,14 @@ var BUNDLED_CONTRACTS = Object.freeze([
     "codeRef": [
       "sdks/web/src/error-codes.ts",
       "sdks/node/src/error-codes.ts",
+      "sdks/web/src/_contract-verifiers.ts",
       "backend/src/api/v1-errors.ts"
     ],
     "testRef": [
+      {
+        "file": "sdks/web/tests/contract-verifiers.test.ts",
+        "name": "sdk-error-codes-catalogue covers every backend wire code with remediation"
+      },
       {
         "file": "sdks/web/tests/error-codes-backfill.test.ts",
         "name": "includes backend code"
@@ -4905,7 +4959,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "sync-purchases-funnel-parity",
@@ -4938,7 +4992,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   },
   {
     "id": "verifier-timestamp-mandatory",
@@ -4992,7 +5046,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.5.3"
+    "bundledIn": "@cross-deck/node@1.6.0"
   }
 ]);