@cross-deck/web 1.6.4 → 1.7.0

package/dist/error-codes.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-06-01T09:52:17.794Z",
+  "generatedAt": "2026-06-10T12:59:26.148Z",
   "sdk": "@cross-deck/web",
   "codes": [
     {

package/dist/index.cjs

@@ -99,7 +99,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.6.4";
+var SDK_VERSION = "1.7.0";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -1015,9 +1015,13 @@ var EventQueue = class {
       const env = this.cfg.envelope();
       const result = await this.cfg.http.request("POST", "/events", {
         body: {
-          // NorthStar §13.1 batch envelope. The backend validates these
-          // against the API-key-resolved app and rejects mismatches
-          // loudly (env_mismatch).
+          // Event Envelope v1 batch envelope (backend/docs/
+          // event-envelope-spec-v1.md §1). `envelopeVersion` is the
+          // schema/wire version the server parses against ("can I parse
+          // this?") and is DISTINCT from `sdk.version` ("which build is in
+          // the wild?") — two questions, two fields, never conflated. The
+          // backend refuses payloads with a missing/unknown envelopeVersion.
+          envelopeVersion: 1,
           appId: env.appId,
           environment: env.environment,
           sdk: env.sdk,
@@ -1472,6 +1476,15 @@ var AutoTracker = class {
     this.cleanups = [];
     /** Last time we flushed lastActivityAt to storage (throttle gate). */
     this.lastPersistAt = 0;
+    /**
+     * Event Envelope v1 §3 — per-session monotonic sequence counter.
+     * The single owner of the seq counter lives here, alongside all other
+     * session state. Incremented atomically at track() time (via nextSeq()),
+     * reset to 0 whenever a new session boundary is crossed (startNewSession
+     * path + resetSession). Persists across background/foreground within a
+     * session — only a real session boundary (not a tab hide/show) resets it.
+     */
+    this._sessionSeq = 0;
     /**
      * Stable per-page-view identifier. Minted at every `page.viewed`
      * emission and attached to every subsequent event until the next
@@ -1556,6 +1569,20 @@ var AutoTracker = class {
   get currentAcquisition() {
     return this.session?.acquisition ?? EMPTY_ACQUISITION;
   }
+  /**
+   * Event Envelope v1 §3 — return the next seq value for the current session
+   * and advance the counter. Called SYNCHRONOUSLY at track() time, before any
+   * async dispatch, so the seq assignment order is deterministic (call order,
+   * not scheduler luck). The counter is reset to 0 at every session boundary;
+   * it is NOT reset by tab hide/show (spec §3 clause 1: backgrounding does not
+   * reset seq). When no session is active (Node, before init, after uninstall),
+   * returns 0 and leaves the counter unchanged — fallback, not an error.
+   */
+  nextSeq() {
+    const seq = this._sessionSeq;
+    this._sessionSeq += 1;
+    return seq;
+  }
   // ---------- sessions ----------
   installSessionTracking() {
     const now = Date.now();
@@ -1607,6 +1634,7 @@ var AutoTracker = class {
   }
   startNewSession() {
     const now = Date.now();
+    this._sessionSeq = 0;
     return {
       sessionId: mintSessionId(),
       startedAt: now,
@@ -2335,6 +2363,40 @@ function writeJson(storage, key, value) {
   }
 }
 
+// src/internal-opt-out.ts
+var INTERNAL_OPT_OUT_PROPERTY = "$crossdeck_internal";
+var STORAGE_KEY = "crossdeck.internalOptOut";
+function localStore() {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage : null;
+  } catch {
+    return null;
+  }
+}
+function processInternalOptOutUrl() {
+  try {
+    const search = typeof location !== "undefined" ? location.search : "";
+    const params = new URLSearchParams(search || "");
+    if (!params.has("crossdeck_internal")) return;
+    const store = localStore();
+    if (!store) return;
+    const v = params.get("crossdeck_internal");
+    if (v === "1" || v === "true") {
+      store.setItem(STORAGE_KEY, "1");
+    } else if (v === "0" || v === "false") {
+      store.removeItem(STORAGE_KEY);
+    }
+  } catch {
+  }
+}
+function isInternalOptOut() {
+  try {
+    return localStore()?.getItem(STORAGE_KEY) === "1";
+  } catch {
+    return false;
+  }
+}
+
 // src/web-vitals.ts
 var WebVitalsTracker = class {
   constructor(cfg, report) {
@@ -2865,15 +2927,6 @@ var VerifierReporter = class {
   constructor(ctx) {
     this.ctx = ctx;
     this.reentrancyDepth = 0;
-    /** The live verifier set — attached by the SDK right after init so the
-     * emit path can schema-lock its OWN outgoing telemetry against the real
-     * payload. Null until attached (boot-time reports still work without it). */
-    this.verifiers = null;
-  }
-  /** Hand the reporter the live verifier set so `reportFail` can run the
-   * `onReportContractFailure` hook on the exact payload it's about to emit. */
-  attachVerifiers(verifiers) {
-    this.verifiers = verifiers;
   }
   /**
    * Report a verifier result. Pass `operation` for hot-path results
@@ -2902,7 +2955,7 @@ var VerifierReporter = class {
     if (this.reentrancyDepth > 0) return;
     this.reentrancyDepth += 1;
     try {
-      const payload = {
+      this.ctx.emitTelemetry({
         contract_id: result.contractId,
         sdk_version: this.ctx.sdkVersion,
         sdk_platform: "web",
@@ -2910,13 +2963,7 @@ var VerifierReporter = class {
         run_context: this.ctx.runContext,
         run_id: this.ctx.runId,
         verification_phase: phase
-      };
-      if (this.verifiers) {
-        runOnReportContractFailure(this.verifiers, this, this.ctx, {
-          outgoingPayload: payload
-        });
-      }
-      this.ctx.emitTelemetry(payload);
+      });
     } finally {
       this.reentrancyDepth -= 1;
     }
@@ -3206,31 +3253,9 @@ var VERIFIER_FLUSH_INTERVAL_PARITY = {
       "eventFlushIntervalMs default = 2000ms (Web/Node/RN/Swift/Android parity)",
       nowMs() - t0
     );
-  },
-  // Hot-path hook — on every real track() we re-affirm the LIVE configured
-  // flush interval (carried on the observation), so the parity guarantee is
-  // verified against the running SDK in the customer flow, not just a
-  // canonical constant at boot. It can't change per-event, but observing it
-  // per-event is what makes the contract genuinely runtime-verified.
-  hooks: {
-    onTrack(obs) {
-      const t0 = nowMs();
-      const CANONICAL_DEFAULT_MS = 2e3;
-      const ms = obs.flushIntervalMs;
-      if (typeof ms !== "number" || ms < 100 || ms > 6e4) {
-        return fail(
-          "flush-interval-parity",
-          `live eventFlushIntervalMs=${ms} outside reasonable bounds [100, 60000]`,
-          nowMs() - t0
-        );
-      }
-      return pass(
-        "flush-interval-parity",
-        ms === CANONICAL_DEFAULT_MS ? "live eventFlushIntervalMs = 2000ms (canonical parity value)" : `live eventFlushIntervalMs = ${ms}ms (permitted override; canonical default 2000ms)`,
-        nowMs() - t0
-      );
-    }
   }
+  // No hot-path hook — the flush interval is set once at start() and
+  // never changes per-operation.
 };
 function buildFlushIntervalVerifier(configuredIntervalMs) {
   return {
@@ -3357,26 +3382,6 @@ var CONTRACT_FAILED_FORBIDDEN_FIELDS = [
   "referrer",
   "deviceId"
 ];
-function contractFailedSchemaViolation(keys) {
-  const allowed = /* @__PURE__ */ new Set([
-    ...CONTRACT_FAILED_REQUIRED_FIELDS,
-    ...CONTRACT_FAILED_OPTIONAL_FIELDS
-  ]);
-  const forbidden = new Set(CONTRACT_FAILED_FORBIDDEN_FIELDS);
-  for (const required of CONTRACT_FAILED_REQUIRED_FIELDS) {
-    if (!keys.includes(required)) return `missing required field: ${required}`;
-  }
-  for (const k of keys) {
-    if (forbidden.has(k)) return `forbidden field on wire: ${k}`;
-  }
-  for (const k of keys) {
-    if (!allowed.has(k)) {
-      return `unrecognised field on wire: ${k} (not in required \u222A optional)`;
-    }
-  }
-  return null;
-}
-var CONTRACT_FAILED_OK_EVIDENCE = `fields \u2286 required(${CONTRACT_FAILED_REQUIRED_FIELDS.length}) \u222A optional(${CONTRACT_FAILED_OPTIONAL_FIELDS.length}); ${CONTRACT_FAILED_FORBIDDEN_FIELDS.length} forbidden absent`;
 var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
   contractId: "contract-failed-payload-schema-lock",
   bootTest() {
@@ -3391,35 +3396,43 @@ var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
       verification_phase: "boot"
     };
     const keys = Object.keys(syntheticPayload);
-    const violation = contractFailedSchemaViolation(keys);
-    if (violation) {
-      return fail("contract-failed-payload-schema-lock", violation, nowMs() - t0);
+    const allowed = /* @__PURE__ */ new Set([
+      ...CONTRACT_FAILED_REQUIRED_FIELDS,
+      ...CONTRACT_FAILED_OPTIONAL_FIELDS
+    ]);
+    const forbidden = new Set(CONTRACT_FAILED_FORBIDDEN_FIELDS);
+    for (const required of CONTRACT_FAILED_REQUIRED_FIELDS) {
+      if (!keys.includes(required)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `missing required field: ${required}`,
+          nowMs() - t0
+        );
+      }
+    }
+    for (const k of keys) {
+      if (forbidden.has(k)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `forbidden field on wire: ${k}`,
+          nowMs() - t0
+        );
+      }
+    }
+    for (const k of keys) {
+      if (!allowed.has(k)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `unrecognised field on wire: ${k} (not in required \u222A optional)`,
+          nowMs() - t0
+        );
+      }
     }
     return pass(
       "contract-failed-payload-schema-lock",
-      `${keys.length} ${CONTRACT_FAILED_OK_EVIDENCE}`,
+      `${keys.length} fields \u2286 required(${CONTRACT_FAILED_REQUIRED_FIELDS.length}) \u222A optional(${CONTRACT_FAILED_OPTIONAL_FIELDS.length}); ${CONTRACT_FAILED_FORBIDDEN_FIELDS.length} forbidden absent`,
       nowMs() - t0
     );
-  },
-  // Hot-path hook — fires on the REAL reportFail emit (VerifierReporter,
-  // inside the re-entrancy guard) against the exact payload about to go on
-  // the wire. This is the assertion the guard at reportFail was built in
-  // anticipation of: every reliability-channel write is schema-locked in the
-  // field, against real data, not just the synthetic boot mirror.
-  hooks: {
-    onReportContractFailure(obs) {
-      const t0 = nowMs();
-      const keys = Object.keys(obs.outgoingPayload);
-      const violation = contractFailedSchemaViolation(keys);
-      if (violation) {
-        return fail("contract-failed-payload-schema-lock", violation, nowMs() - t0);
-      }
-      return pass(
-        "contract-failed-payload-schema-lock",
-        `${keys.length} ${CONTRACT_FAILED_OK_EVIDENCE}`,
-        nowMs() - t0
-      );
-    }
   }
 };
 var BACKEND_WIRE_CODES = Object.freeze([
@@ -3470,39 +3483,6 @@ var VERIFIER_SDK_ERROR_CODES_CATALOGUE = {
         nowMs() - t0
       );
     }
-  },
-  // Hot-path hook — when the SDK parses a real wire error, assert the code
-  // the customer actually hit carries usable remediation in the shipped
-  // catalogue. Scoped to BACKEND_WIRE_CODES (the contract's set); other
-  // codes are out of scope and pass. This turns the catalogue from a
-  // boot-only completeness claim into a per-error field assertion: a backend
-  // code that ships without remediation is caught the first time a customer
-  // hits it, not only if the off-by-default boot self-test ran.
-  hooks: {
-    onErrorParse(obs) {
-      const t0 = nowMs();
-      const code = obs.errorCode;
-      if (!code || !BACKEND_WIRE_CODES.includes(code)) {
-        return pass(
-          "sdk-error-codes-catalogue",
-          `wire code "${code || "(none)"}" is out of the backend-catalogue scope`,
-          nowMs() - t0
-        );
-      }
-      const entry = getErrorCode(code);
-      if (!entry || !entry.description || entry.description.trim().length === 0 || !entry.resolution || entry.resolution.trim().length === 0) {
-        return fail(
-          "sdk-error-codes-catalogue",
-          `backend wire code "${code}" hit in the field has no description+resolution in the shipped catalogue`,
-          nowMs() - t0
-        );
-      }
-      return pass(
-        "sdk-error-codes-catalogue",
-        `backend wire code "${code}" carries description + resolution`,
-        nowMs() - t0
-      );
-    }
   }
 };
 var STATIC_VERIFIERS = Object.freeze([
@@ -3626,24 +3606,6 @@ function runOnErrorParse(verifiers, reporter, ctx, obs) {
     reporter.report(result, "hot_path", "errorParse");
   }
 }
-function runOnReportContractFailure(verifiers, reporter, ctx, obs) {
-  if (ctx.disableContractAssertions) return;
-  for (const verifier of verifiers) {
-    const hook = verifier.hooks?.onReportContractFailure;
-    if (!hook) continue;
-    let result;
-    try {
-      result = hook(obs);
-    } catch (err) {
-      result = fail(
-        verifier.contractId,
-        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
-        0
-      );
-    }
-    reporter.report(result, "hot_path", "reportContractFailure");
-  }
-}
 function defaultDebugModeFlag() {
   try {
     if (typeof process !== "undefined" && process.env) {
@@ -3795,18 +3757,18 @@ function isInAppFrame(filename) {
   if (/\/crossdeck\.umd\.min\.js$/.test(filename)) return false;
   return true;
 }
-function fingerprintError(message, frames, location) {
+function fingerprintError(message, frames, location2) {
   const inAppFrames = frames.filter((f) => f.in_app).slice(0, 3);
   const parts = [
     (message || "").slice(0, 200),
     ...inAppFrames.map((f) => `${f.function}@${f.filename}:${f.lineno}`)
   ];
-  if (inAppFrames.length === 0 && location) {
+  if (inAppFrames.length === 0 && location2) {
     const loc = [
-      location.errorType ?? "",
-      location.filename ?? "",
-      location.lineno ?? "",
-      location.colno ?? ""
+      location2.errorType ?? "",
+      location2.filename ?? "",
+      location2.lineno ?? "",
+      location2.colno ?? ""
     ].join(":");
     if (loc !== ":::") parts.push(loc);
   }
@@ -4476,9 +4438,6 @@ var CrossdeckClient = class {
     this.verifiers = null;
     this.verifierReporter = null;
     this.verifierCtx = null;
-    // The live configured event-flush interval, surfaced to the track-path
-    // verifier so flush-interval-parity validates the real cadence per event.
-    this.flushIntervalMs = 2e3;
   }
   /**
    * Boot the SDK. Idempotent — calling init twice with the same options
@@ -4655,6 +4614,7 @@ var CrossdeckClient = class {
       persistIdentity ? effectiveStorage : new MemoryStorage(),
       opts.storagePrefix
     );
+    processInternalOptOutUrl();
     const consent = new ConsentManager({ respectDnt: options.respectDnt === true });
     if (consent.isDntDenied) {
       debug.emit(
@@ -4758,8 +4718,6 @@ var CrossdeckClient = class {
       this.verifierReporter = new VerifierReporter(this.verifierCtx);
       const flushVerifier = buildFlushIntervalVerifier(opts.eventFlushIntervalMs);
       this.verifiers = Object.freeze([...STATIC_VERIFIERS, flushVerifier]);
-      this.flushIntervalMs = opts.eventFlushIntervalMs;
-      this.verifierReporter.attachVerifiers(this.verifiers);
       if (localDevMode) {
         const verifyAtBootLocal = options.verifyContractsAtBoot ?? debugDefault;
         if (verifyAtBootLocal && this.verifierReporter) {
@@ -5310,8 +5268,27 @@ var CrossdeckClient = class {
         );
       }
     }
+    const seq = s.autoTracker?.nextSeq() ?? 0;
+    const occurrenceTimestamp = Date.now();
     s.autoTracker?.markActivity();
-    const enriched = { ...s.deviceInfo };
+    const wireContext = {};
+    const di = s.deviceInfo;
+    if (di.os) wireContext.os = di.os;
+    if (di.osVersion) wireContext.osVersion = di.osVersion;
+    const appVer = s.options.appVersion;
+    if (appVer) wireContext.appVersion = appVer;
+    wireContext.sdkName = SDK_NAME;
+    wireContext.sdkVersion = s.options.sdkVersion;
+    if (di.locale) wireContext.locale = di.locale;
+    if (di.timezone) wireContext.timezone = di.timezone;
+    if (di.browser) wireContext.browser = di.browser;
+    if (di.browserVersion) wireContext.browserVersion = di.browserVersion;
+    const enriched = {};
+    if (di.screenWidth !== void 0) enriched.screenWidth = di.screenWidth;
+    if (di.screenHeight !== void 0) enriched.screenHeight = di.screenHeight;
+    if (di.viewportWidth !== void 0) enriched.viewportWidth = di.viewportWidth;
+    if (di.viewportHeight !== void 0) enriched.viewportHeight = di.viewportHeight;
+    if (di.devicePixelRatio !== void 0) enriched.devicePixelRatio = di.devicePixelRatio;
     const sessionId = s.autoTracker?.currentSessionId;
     if (sessionId) enriched.sessionId = sessionId;
     const pageviewId = s.autoTracker?.currentPageviewId;
@@ -5334,17 +5311,24 @@ var CrossdeckClient = class {
       }
     }
     const supers = s.superProps.getSuperProperties();
-    Object.assign(enriched, supers);
+    for (const k of Object.keys(supers)) {
+      if (!(k in enriched)) enriched[k] = supers[k];
+    }
     const groupIds = s.superProps.getGroupIds();
     if (Object.keys(groupIds).length > 0) {
       enriched.$groups = groupIds;
     }
     Object.assign(enriched, validation.properties);
+    if (isInternalOptOut()) {
+      enriched[INTERNAL_OPT_OUT_PROPERTY] = true;
+    }
     const finalProperties = s.scrubPii ? scrubPiiFromProperties(enriched) : enriched;
     const event = {
       eventId: this.mintEventId(),
       name,
-      timestamp: Date.now(),
+      timestamp: occurrenceTimestamp,
+      seq,
+      context: wireContext,
       properties: finalProperties
     };
     Object.assign(event, this.identityHintForEvent());
@@ -5354,8 +5338,7 @@ var CrossdeckClient = class {
         callerProperties: validation.properties,
         superProperties: supers,
         deviceProperties: s.deviceInfo,
-        mergedProperties: enriched,
-        flushIntervalMs: this.flushIntervalMs
+        mergedProperties: enriched
       });
     }
     if (!isError && !isWebVital) {
@@ -5700,8 +5683,8 @@ function installUnloadFlush(onUnload) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/web@1.6.4";
-var SDK_VERSION2 = "1.6.4";
+var BUNDLED_IN = "@cross-deck/web@1.7.0";
+var SDK_VERSION2 = "1.7.0";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -5823,7 +5806,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -5863,7 +5846,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/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -5909,7 +5892,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -6015,7 +5998,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/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -6043,7 +6026,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": false
   },
   {
@@ -6123,7 +6106,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -6169,7 +6152,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -6211,7 +6194,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.2",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": true
   },
   {
@@ -6245,7 +6228,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/web@1.6.4",
+    "bundledIn": "@cross-deck/web@1.7.0",
     "runtimeVerified": false
   }
 ]);