@cross-deck/node 1.3.1 → 1.5.0

package/dist/index.mjs

@@ -317,7 +317,7 @@ function byteLength(s) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.3.1";
+var SDK_VERSION = "1.4.2";
 var SDK_NAME = "@cross-deck/node";
 
 // src/http.ts
@@ -2349,6 +2349,63 @@ var EntitlementCache = class {
   }
 };
 
+// src/consent.ts
+var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+var CARD_PATTERN = /\b\d(?:[ -]?\d){12,18}\b/g;
+var REPLACEMENT_EMAIL = "<email>";
+var REPLACEMENT_CARD = "<card>";
+function scrubPii(value) {
+  if (!value) return value;
+  return value.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL).replace(CARD_PATTERN, REPLACEMENT_CARD);
+}
+function scrubPiiFromProperties(properties) {
+  const out = {};
+  for (const k of Object.keys(properties)) {
+    out[k] = scrubValue(properties[k]);
+  }
+  return out;
+}
+function scrubValue(v) {
+  if (typeof v === "string") return scrubPii(v);
+  if (Array.isArray(v)) return v.map(scrubValue);
+  if (v && typeof v === "object" && v.constructor === Object) {
+    return scrubPiiFromProperties(v);
+  }
+  return v;
+}
+
+// src/idempotency-key.ts
+import { createHash } from "crypto";
+function formatAsUuid(hex) {
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join("-");
+}
+function sha256Hex(input) {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+function deriveIdempotencyKeyForPurchase(body) {
+  let identifier;
+  if (body.rail === "apple") {
+    identifier = body.signedTransactionInfo ?? "";
+  } else if (body.rail === "google") {
+    identifier = body.purchaseToken ?? "";
+  } else {
+    identifier = "";
+  }
+  if (!identifier) {
+    throw new Error(
+      `deriveIdempotencyKeyForPurchase: no stable identifier in body (rail=${body.rail}). Apple needs signedTransactionInfo; Google needs purchaseToken.`
+    );
+  }
+  const namespaced = `crossdeck:purchases/sync:${body.rail}:${identifier}`;
+  return formatAsUuid(sha256Hex(namespaced));
+}
+
 // src/debug.ts
 var SENSITIVE_KEY_PATTERNS = [
   /^email$/i,
@@ -2408,6 +2465,10 @@ var CrossdeckServer = class extends EventEmitter {
   baseUrl;
   appId;
   env;
+  /** PII scrubber toggle. Default true — parity with Web/RN/Swift.
+   * Pre-v1.4.0 the Node SDK shipped track() payloads UNREDACTED,
+   * a privacy contract drift versus the README. */
+  scrubPii;
   secretKeyPrefix;
   /**
    * Process-stable pseudo-anonymous ID. Used as the default identity
@@ -2453,6 +2514,15 @@ var CrossdeckServer = class extends EventEmitter {
   errorContext = {};
   errorTags = {};
   errorBeforeSend = null;
+  /**
+   * Dedup gate for `sdk.shutdown`. Both `shutdown()` (async) and
+   * `shutdownSync()` need to emit so direct callers of EITHER see
+   * the event (the async path's listener guarantees pre-launch
+   * tests, the sync path covers `Symbol.dispose` + tests that call
+   * `shutdownSync()` directly). Without this flag, `shutdown()`'s
+   * tail call into `shutdownSync()` would emit twice.
+   */
+  didEmitShutdown = false;
   constructor(options) {
     super();
     if (!options.secretKey || !options.secretKey.startsWith("cd_sk_")) {
@@ -2467,6 +2537,7 @@ var CrossdeckServer = class extends EventEmitter {
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.env = inferEnvFromKey(options.secretKey);
     this.secretKeyPrefix = maskSecretKey(options.secretKey);
+    this.scrubPii = options.scrubPii !== false;
     this.http = new HttpClient({
       secretKey: options.secretKey,
       baseUrl: this.baseUrl,
@@ -2506,7 +2577,9 @@ var CrossdeckServer = class extends EventEmitter {
     this.eventQueue = new EventQueue({
       http: this.http,
       batchSize: options.eventFlushBatchSize ?? 20,
-      intervalMs: options.eventFlushIntervalMs ?? 1500,
+      // v1.4.0 Phase 3.3 — flush interval default parity at 2000ms
+      // across every SDK. Per-instance override stays.
+      intervalMs: options.eventFlushIntervalMs ?? 2e3,
       envelope: () => ({
         appId: this.appId,
         // Ship env on every batch so the backend can cross-check
@@ -2885,6 +2958,38 @@ var CrossdeckServer = class extends EventEmitter {
    *     `uncaughtException` has no per-request context; without the
    *     auto-fill, the event would be rejected at queue enqueue.
    */
+  /**
+   * Emit `crossdeck.contract_failed` with the canonical property
+   * shape. Same wire shape every Crossdeck SDK uses for contract
+   * verification telemetry — see `contracts/README.md` for the
+   * full pattern. No new endpoint, no special path; goes through
+   * the standard server-side `track()` pipeline.
+   */
+  reportContractFailure(input) {
+    const props = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "node",
+      failure_reason: input.failureReason,
+      run_context: input.runContext,
+      run_id: input.runId
+    };
+    if (input.testRef) {
+      props.test_file = input.testRef.file;
+      props.test_name = input.testRef.name;
+    }
+    if (input.extra) {
+      for (const [k, v] of Object.entries(input.extra)) {
+        if (props[k] === void 0) props[k] = v;
+      }
+    }
+    this.track({
+      name: "crossdeck.contract_failed",
+      properties: props
+      // No identity hint — these events are about the SDK / dogfood
+      // run itself, not a specific end-user.
+    });
+  }
   track(event) {
     if (!event.name) {
       throw new CrossdeckError({
@@ -2893,7 +2998,8 @@ var CrossdeckServer = class extends EventEmitter {
         message: "track(event) requires a non-empty event.name."
       });
     }
-    const sanitized = sanitizePropertyBag(event.properties, "event properties") ?? {};
+    const validated = sanitizePropertyBag(event.properties, "event properties") ?? {};
+    const sanitized = this.scrubPii ? scrubPiiFromProperties(validated) : validated;
     if (this.debug.enabled) {
       const flagged = findSensitivePropertyKeys(sanitized);
       if (flagged.length > 0) {
@@ -3029,11 +3135,25 @@ var CrossdeckServer = class extends EventEmitter {
       });
     }
     const rail = input.rail ?? "apple";
-    return this.http.request("POST", "/purchases/sync", {
-      body: { ...input, rail },
+    const body = { ...input, rail };
+    const idempotencyKey = options?.idempotencyKey ?? deriveIdempotencyKeyForPurchase(body);
+    const result = await this.http.request("POST", "/purchases/sync", {
+      body,
+      idempotencyKey,
       signal: options?.signal,
       timeoutMs: options?.timeoutMs
     });
+    try {
+      const sourceProductId = result.entitlements[0]?.source.productId;
+      const sourceSubscriptionId = result.entitlements[0]?.source.subscriptionId;
+      const props = { rail };
+      if (sourceProductId) props.productId = sourceProductId;
+      if (sourceSubscriptionId) props.subscriptionId = sourceSubscriptionId;
+      if (result.idempotent_replay) props.idempotent_replay = true;
+      this.track({ name: "purchase.completed", properties: props });
+    } catch {
+    }
+    return result;
   }
   // ============================================================
   // Manual entitlement controls + audit — direct HTTP
@@ -3325,12 +3445,56 @@ var CrossdeckServer = class extends EventEmitter {
     };
   }
   /**
-   * Tear down handlers and clear in-memory state. Tests + custom
-   * lifecycle callers only. Production code should rely on
-   * `flush-on-exit` instead.
+   * Tear down handlers and clear in-memory state.
+   *
+   * **v1.4.0 bank-grade contract:** `shutdown()` AWAITS `flush()`
+   * before dropping the queue, so callers don't silently lose
+   * every queued event on a clean shutdown. The pre-v1.4.0
+   * behaviour (sync `eventQueue.reset()` with no flush) was the
+   * default for both `shutdown()` and `[Symbol.dispose]`; only
+   * `await using` + `[Symbol.asyncDispose]` flushed correctly.
+   *
+   * Production servers should still prefer `await server.flush()`
+   * (visible) followed by `server.shutdown()` so the flush
+   * outcome is observable — `shutdown()`'s internal flush swallows
+   * errors as a best-effort drain.
+   *
+   * Use [[shutdownSync]] only when the runtime cannot await
+   * (e.g. inside `Symbol.dispose` — see below).
    */
-  shutdown(reason = "shutdown") {
-    this.emit("sdk.shutdown", { reason });
+  async shutdown(reason = "shutdown") {
+    if (!this.didEmitShutdown) {
+      this.emit("sdk.shutdown", { reason });
+      this.didEmitShutdown = true;
+    }
+    try {
+      await this.flush();
+    } catch {
+    }
+    this.shutdownSync(reason);
+  }
+  /**
+   * Synchronous teardown — drops the in-memory queue WITHOUT
+   * flushing, then clears all in-memory state. Used by
+   * `[Symbol.dispose]` (which has no await) and tests that need
+   * an unconditional sync wipe. Production code should use
+   * [[shutdown]] (async) instead so queued events are flushed.
+   *
+   * A queue with items at sync-shutdown logs a warning recommending
+   * `[Symbol.asyncDispose]` or `await server.shutdown()` — silent
+   * loss is incompatible with the bank-grade contract.
+   */
+  shutdownSync(reason = "shutdown") {
+    if (!this.didEmitShutdown) {
+      this.emit("sdk.shutdown", { reason });
+      this.didEmitShutdown = true;
+    }
+    const queuedCount = this.eventQueue.getStats().buffered;
+    if (queuedCount > 0 && reason !== "asyncDispose") {
+      console.warn(
+        `[crossdeck] shutdownSync() dropped ${queuedCount} queued event(s) without flushing. Use \`await server.shutdown()\` or \`await using server = ...\` with \`[Symbol.asyncDispose]\` to drain the buffer before teardown.`
+      );
+    }
     this.errorTracker?.uninstall();
     this.flushOnExit?.uninstall();
     this.eventQueue.reset();
@@ -3444,28 +3608,28 @@ var CrossdeckServer = class extends EventEmitter {
    *   // ... use server ...
    *   // at end of block, server[Symbol.dispose]() runs automatically
    *
-   * `Symbol.dispose` is synchronous so we can't await `flush()` here
-   * — for that, use `await using` + `[Symbol.asyncDispose]()`. This
-   * sync variant just calls `shutdown()` (handler cleanup +
-   * in-memory state wipe).
+   * **`Symbol.dispose` is synchronous so it CANNOT await the queue
+   * flush.** A queue with pending events at sync-dispose time will
+   * be DROPPED — `shutdownSync` warns to the console when this
+   * happens. For the common case of "drain the queue before
+   * exit", switch to `await using` + `[Symbol.asyncDispose]` (or
+   * call `await server.shutdown()` explicitly before the variable
+   * goes out of scope).
    */
   [Symbol.dispose]() {
-    this.shutdown("dispose");
+    this.shutdownSync("dispose");
   }
   /**
    * Async disposal hook — runs when an `await using` declaration
-   * exits scope. Awaits `flush()` THEN runs `shutdown()`. Use this
-   * variant when the caller needs the queue drained before exit
-   * (the common case for serverless handlers).
+   * exits scope. Awaits the bank-grade `shutdown()` which flushes
+   * the queue THEN tears down. Use this variant for any code path
+   * that owns queued events at exit (serverless handlers,
+   * background workers, end-of-request hooks).
    *
    *   await using server = new CrossdeckServer({ ... });
    */
   async [Symbol.asyncDispose]() {
-    try {
-      await this.flush();
-    } catch {
-    }
-    this.shutdown("asyncDispose");
+    await this.shutdown("asyncDispose");
   }
   // ============================================================
   reportCapturedError(captured) {
@@ -3885,18 +4049,43 @@ var _CROSSDECK_ERROR_CODES = Object.freeze([
     retryable: false
   },
   // ----- Webhook verification (Node-specific) -----
+  // v1.4.0 Phase 7.2 — distinguishable codes. Pre-v1.4.0 the
+  // helper used webhook_invalid_signature for nearly every failure
+  // mode so a customer couldn't separate replay-attack signals
+  // from wrong-secret signals in alerting.
   {
-    code: "webhook_invalid_signature",
+    code: "webhook_signature_mismatch",
     type: "authentication_error",
-    description: "The webhook signature header did not verify against the supplied secret.",
-    resolution: "Confirm the secret matches the one in your Crossdeck dashboard \u2192 Webhooks page. If the request is genuinely from Crossdeck, the secret is wrong, stale, or recently rotated.",
+    description: "Webhook HMAC didn't verify against any configured secret (wrong-secret / stale rotation signal).",
+    resolution: "Confirm the secret matches dashboard \u2192 Webhooks. If you rotated, include both the old and new secret as an array until receivers cut over.",
     retryable: false
   },
   {
-    code: "webhook_replay_window_exceeded",
+    code: "webhook_timestamp_outside_tolerance",
+    type: "authentication_error",
+    description: "Webhook timestamp drift exceeds the configured replay-tolerance window (default 5 minutes; replay-attack signal).",
+    resolution: "Verify NTP on the receiving host. A spike on this code warrants its own alert separate from signature_mismatch \u2014 replay attacks look like this.",
+    retryable: false
+  },
+  {
+    code: "webhook_timestamp_missing",
+    type: "authentication_error",
+    description: "Webhook signature header is absent or has no `t=` timestamp segment \u2014 the timestamp gate cannot be verified.",
+    resolution: "Confirm the request actually came from Crossdeck (signature headers are always present on real deliveries). A missing header is either a misconfigured intermediary or a forged request.",
+    retryable: false
+  },
+  {
+    code: "webhook_payload_not_json",
     type: "authentication_error",
-    description: "The webhook timestamp is older than the replay-tolerance window (default 5 minutes).",
-    resolution: "The webhook is either replayed or your receiving clock is wildly skewed. Verify NTP on the receiving host. Increase replayToleranceMs only if you accept the replay-attack risk.",
+    description: "Webhook signature verified but the body isn't valid JSON \u2014 payload tampered post-signing or source bug.",
+    resolution: "Inspect the raw payload. If it's not JSON, either the request was modified in transit or the sender has a bug \u2014 file a support ticket with the raw body.",
+    retryable: false
+  },
+  {
+    code: "webhook_invalid_tolerance",
+    type: "configuration_error",
+    description: "verifyWebhookSignature() called with a non-finite / negative / above-24h-cap replayToleranceMs (would silently disable replay protection).",
+    resolution: "Pass a finite number between 0 and 86_400_000ms (24h). Default (5 minutes) is correct for almost every scenario. Pre-v1.4.0 accepted Infinity/NaN and silently dropped the check.",
     retryable: false
   },
   {
@@ -3905,6 +4094,101 @@ var _CROSSDECK_ERROR_CODES = Object.freeze([
     description: "verifyWebhookSignature() was called without a signing secret.",
     resolution: "Pass the secret from your Crossdeck dashboard \u2192 Webhooks page. Never hardcode in source \u2014 read from an env var.",
     retryable: false
+  },
+  {
+    code: "webhook_invalid_signature",
+    type: "authentication_error",
+    description: "DEPRECATED in v1.4.0 \u2014 split into webhook_signature_mismatch / webhook_timestamp_missing / webhook_timestamp_outside_tolerance / webhook_payload_not_json for alerting clarity.",
+    resolution: "Migrate alert rules to the more specific v1.4.0 codes \u2014 they distinguish replay-attack signals from wrong-secret signals.",
+    retryable: false
+  },
+  {
+    code: "webhook_replay_window_exceeded",
+    type: "authentication_error",
+    description: "DEPRECATED in v1.4.0 \u2014 renamed to webhook_timestamp_outside_tolerance.",
+    resolution: "Update alerts to webhook_timestamp_outside_tolerance.",
+    retryable: false
+  },
+  // ----- Backend-emitted codes (v1.4.0 Phase 6.2 backfill) -----
+  // Mirror of backend/src/api/v1-errors.ts ApiErrorCode. Same set
+  // as the Web SDK ships — keep these synchronised so a developer
+  // hitting any code via either SDK gets the same remediation.
+  {
+    code: "missing_api_key",
+    type: "authentication_error",
+    description: "No Authorization header (or Crossdeck-Api-Key header) on the request.",
+    resolution: "Confirm the CrossdeckServer was constructed with a cd_sk_\u2026 secretKey. Re-check env vars in production deployments.",
+    retryable: false
+  },
+  {
+    code: "invalid_api_key",
+    type: "authentication_error",
+    description: "The secret key is malformed, unknown, or doesn't resolve to a project.",
+    resolution: "Copy the key from Crossdeck dashboard \u2192 API keys. Server SDK requires cd_sk_test_ / cd_sk_live_ \u2014 client SDK keys (cd_pub_\u2026) won't work on the Node SDK.",
+    retryable: false
+  },
+  {
+    code: "key_revoked",
+    type: "authentication_error",
+    description: "The secret key was revoked in the dashboard.",
+    resolution: "Mint a fresh key in dashboard \u2192 API keys \u2192 Create new. The revoked key cannot be reactivated.",
+    retryable: false
+  },
+  {
+    code: "env_mismatch",
+    type: "permission_error",
+    description: "The key's env prefix doesn't match the resolved app's configured env.",
+    resolution: "Use a cd_sk_live_ key with a production app, cd_sk_test_ with a sandbox app. Crossing breaks the env lock.",
+    retryable: false
+  },
+  {
+    code: "idempotency_key_in_use",
+    type: "invalid_request_error",
+    description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).",
+    resolution: "Server SDK derives keys deterministically from the body since v1.4.0; this should only fire if you passed options.idempotencyKey explicitly. Use a fresh key per logical operation.",
+    retryable: false
+  },
+  {
+    code: "rate_limited",
+    type: "rate_limit_error",
+    description: "Request rate exceeded the project's per-second cap.",
+    resolution: "Honour Retry-After (managed retries do this automatically). For custom paths, throttle to <100 req/s/key.",
+    retryable: true
+  },
+  {
+    code: "internal_error",
+    type: "internal_error",
+    description: "Server-side issue. Safe to retry with backoff.",
+    resolution: "Managed retries handle this automatically. If a code path surfaces it to your code, contact support with the requestId.",
+    retryable: true
+  },
+  {
+    code: "google_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.",
+    resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The Android SDK auto-track path handles this transparently.",
+    retryable: false
+  },
+  {
+    code: "stripe_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=stripe is unsupported \u2014 Stripe webhooks deliver evidence server-side.",
+    resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically.",
+    retryable: false
+  },
+  {
+    code: "missing_required_param",
+    type: "invalid_request_error",
+    description: "A required field is absent from the request body.",
+    resolution: "The error.message identifies the missing field. Refer to the SDK's TypeScript types for canonical shapes.",
+    retryable: false
+  },
+  {
+    code: "invalid_param_value",
+    type: "invalid_request_error",
+    description: "A field is present but the value failed validation.",
+    resolution: "Read error.message for the field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
+    retryable: false
   }
 ]);
 function isCrossdeckErrorCode(code) {
@@ -3918,6 +4202,7 @@ function getErrorCode(code) {
 // src/webhooks.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var DEFAULT_REPLAY_TOLERANCE_MS = 5 * 60 * 1e3;
+var MAX_REPLAY_TOLERANCE_MS = 24 * 60 * 60 * 1e3;
 function verifyWebhookSignature(payload, signatureHeader, secret, options = {}) {
   const secrets = normaliseSecrets(secret);
   if (secrets.length === 0) {
@@ -3927,34 +4212,56 @@ function verifyWebhookSignature(payload, signatureHeader, secret, options = {})
       message: "verifyWebhookSignature requires a non-empty secret. Read it from process.env.CROSSDECK_WEBHOOK_SECRET \u2014 never hardcode in source."
     });
   }
+  const requestedTolerance = options.replayToleranceMs;
+  let tolerance;
+  if (requestedTolerance === void 0) {
+    tolerance = DEFAULT_REPLAY_TOLERANCE_MS;
+  } else if (typeof requestedTolerance !== "number" || !Number.isFinite(requestedTolerance)) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must be a finite non-negative number \u2264 ${MAX_REPLAY_TOLERANCE_MS} (24h). Got: ${String(requestedTolerance)}. Pre-v1.4.0 accepted Infinity/NaN/null and silently disabled replay protection \u2014 v1.4.0 rejects loudly.`
+    });
+  } else if (requestedTolerance < 0) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must be \u2265 0. Got ${requestedTolerance}.`
+    });
+  } else if (requestedTolerance > MAX_REPLAY_TOLERANCE_MS) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must not exceed ${MAX_REPLAY_TOLERANCE_MS}ms (24h). Got ${requestedTolerance}ms \u2014 a window that wide defeats replay protection.`
+    });
+  } else {
+    tolerance = requestedTolerance;
+  }
   const header = normaliseHeader(signatureHeader);
   const parsed = parseSignatureHeader(header);
   if (!parsed) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
-      message: "Webhook signature header is missing or malformed. Expected 'Crossdeck-Signature: t=<unix>,v1=<hex>'."
+      code: "webhook_timestamp_missing",
+      message: "Webhook signature header is missing, malformed, or has no `t=` timestamp segment. Expected 'Crossdeck-Signature: t=<unix>,v1=<hex>'."
     });
   }
-  const tolerance = options.replayToleranceMs ?? DEFAULT_REPLAY_TOLERANCE_MS;
-  if (tolerance > 0) {
-    const now = (options.now ?? Date.now)();
-    const timestampMs = parsed.timestampSec * 1e3;
-    const drift = Math.abs(now - timestampMs);
-    if (drift > tolerance) {
-      throw new CrossdeckError({
-        type: "authentication_error",
-        code: "webhook_replay_window_exceeded",
-        message: `Webhook timestamp is ${drift}ms outside the ${tolerance}ms replay-tolerance window. Either the request is replayed or the receiving clock is skewed \u2014 verify NTP on the host.`
-      });
-    }
+  const now = (options.now ?? Date.now)();
+  const timestampMs = parsed.timestampSec * 1e3;
+  const drift = Math.abs(now - timestampMs);
+  if (drift > tolerance) {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_timestamp_outside_tolerance",
+      message: `Webhook timestamp is ${drift}ms outside the ${tolerance}ms replay-tolerance window. Either the request is replayed or the receiving clock is skewed \u2014 verify NTP on the host.`
+    });
   }
   const signedPayload = `${parsed.timestampSec}.${payload}`;
   const expectedBuf = Buffer.from(parsed.signature, "hex");
   if (expectedBuf.length === 0) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
+      code: "webhook_signature_mismatch",
       message: "Webhook signature is not a valid hex string."
     });
   }
@@ -3965,8 +4272,8 @@ function verifyWebhookSignature(payload, signatureHeader, secret, options = {})
   if (!anyMatch) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
-      message: "Webhook signature did not verify. Confirm the secret matches your Crossdeck dashboard \u2192 Webhooks page (and that you're not on a stale rotation)."
+      code: "webhook_signature_mismatch",
+      message: "Webhook signature did not verify against any configured secret. Confirm the secret matches your Crossdeck dashboard \u2192 Webhooks page (and that you're not on a stale rotation)."
     });
   }
   try {
@@ -3974,7 +4281,7 @@ function verifyWebhookSignature(payload, signatureHeader, secret, options = {})
   } catch {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
+      code: "webhook_payload_not_json",
       message: "Webhook signature verified but the payload is not valid JSON. Either the payload was tampered with after signing, or the webhook source is misconfigured."
     });
   }
@@ -4012,35 +4319,471 @@ function normaliseSecrets(input) {
   return arr.filter((s) => typeof s === "string" && s.length > 0);
 }
 
-// src/consent.ts
-var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
-var CARD_PATTERN = /\b\d(?:[ -]?\d){12,18}\b/g;
-var REPLACEMENT_EMAIL = "<email>";
-var REPLACEMENT_CARD = "<card>";
-function scrubPii(value) {
-  if (!value) return value;
-  return value.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL).replace(CARD_PATTERN, REPLACEMENT_CARD);
-}
-function scrubPiiFromProperties(properties) {
-  const out = {};
-  for (const k of Object.keys(properties)) {
-    out[k] = scrubValue(properties[k]);
+// src/_contracts-bundled.ts
+var BUNDLED_IN = "@cross-deck/node@1.5.0";
+var SDK_VERSION2 = "1.5.0";
+var BUNDLED_CONTRACTS = Object.freeze([
+  {
+    "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 \u2014 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' \u2014 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 \u2014 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 \u2014 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 \u2192 400, authentication_error \u2192 401, permission_error \u2192 403, rate_limit_error \u2192 429, internal_error \u2192 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 alert separately), `webhook_timestamp_missing` (header absent/malformed), `webhook_payload_not_json` (tampered post-signing), `webhook_missing_secret`, `webhook_invalid_tolerance` \u2014 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 \u2014 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 \u2014 phase 7.2",
+    "bundledIn": "@cross-deck/node@1.5.0"
   }
-  return out;
-}
-function scrubValue(v) {
-  if (typeof v === "string") return scrubPii(v);
-  if (Array.isArray(v)) return v.map(scrubValue);
-  if (v && typeof v === "object" && v.constructor === Object) {
-    return scrubPiiFromProperties(v);
+]);
+
+// src/contracts.ts
+var CrossdeckContracts = {
+  all() {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === "enforced");
+  },
+  allIncludingHistorical() {
+    return BUNDLED_CONTRACTS;
+  },
+  byId(id) {
+    return BUNDLED_CONTRACTS.find((c) => c.id === id);
+  },
+  byPillar(pillar) {
+    return BUNDLED_CONTRACTS.filter(
+      (c) => c.pillar === pillar && c.status === "enforced"
+    );
+  },
+  withStatus(status) {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === status);
+  },
+  sdkVersion: SDK_VERSION2,
+  bundledIn: BUNDLED_IN,
+  /**
+   * Resolve a failing test back to the contract it exercises.
+   * Used by test-framework hooks to find the contract id of a
+   * failed contract test so `reportContractFailure(...)` can stamp
+   * the right `contract_id` on the emitted event.
+   */
+  findByTestName(name) {
+    return BUNDLED_CONTRACTS.find(
+      (c) => c.testRef.some((ref) => ref.name === name)
+    );
   }
-  return v;
-}
+};
 export {
   CROSSDECK_API_VERSION,
   CROSSDECK_ERROR_CODES,
   CrossdeckAuthenticationError,
   CrossdeckConfigurationError,
+  CrossdeckContracts,
   CrossdeckError,
   CrossdeckInternalError,
   CrossdeckNetworkError,