@cross-deck/node 1.3.1 → 1.5.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementStore, w as EntitlementsListResponse, x as EntitlementsListener, y as Environment, z as ErrorCaptureConfig, F as ErrorLevel, G as EventProperties, H as ForgetResult, I as GrantDuration, J as GrantEntitlementInput, K as GroupMembership, L as HeartbeatResponse, M as HttpRequestInfo, N as HttpResponseInfo, O as HttpRetriesConfig, P as IdentifyOptions, Q as IdentityHints, R as IngestOptions, S as IngestResponse, T as PublicEntitlement, U as PurchaseResult, V as RequestOptions, W as RevokeEntitlementInput, X as RuntimeHost, Y as RuntimeInfo, Z as ServerEvent, _ as StackFrame, $ as StoredEntitlements, a0 as SyncPurchaseInput, a1 as makeCrossdeckError } from './crossdeck-server-DhnHvUhh.mjs';
+export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as Contract, h as ContractAppliesTo, i as ContractFailureInput, j as ContractPillar, k as ContractStatus, l as ContractTestRef, m as CrossdeckAuthenticationError, n as CrossdeckConfigurationError, o as CrossdeckContracts, p as CrossdeckError, q as CrossdeckErrorPayload, r as CrossdeckErrorType, s as CrossdeckInternalError, t as CrossdeckNetworkError, u as CrossdeckPermissionError, v as CrossdeckRateLimitError, w as CrossdeckServer, x as CrossdeckServerOptions, y as CrossdeckValidationError, D as DEFAULT_BASE_URL, z as DEFAULT_TIMEOUT_MS, E as Diagnostics, F as EntitlementCacheOptions, G as EntitlementMutationResult, H as EntitlementStore, I as EntitlementsListResponse, J as EntitlementsListener, K as Environment, L as ErrorCaptureConfig, M as ErrorLevel, N as EventProperties, O as ForgetResult, P as GrantDuration, Q as GrantEntitlementInput, R as GroupMembership, S as HeartbeatResponse, T as HttpRequestInfo, U as HttpResponseInfo, V as HttpRetriesConfig, W as IdentifyOptions, X as IdentityHints, Y as IngestOptions, Z as IngestResponse, _ as PublicEntitlement, $ as PurchaseResult, a0 as RequestOptions, a1 as RevokeEntitlementInput, a2 as RuntimeHost, a3 as RuntimeInfo, a4 as ServerEvent, a5 as StackFrame, a6 as StoredEntitlements, a7 as SyncPurchaseInput, a8 as makeCrossdeckError } from './crossdeck-server-CY4PZk-j.mjs';
 import 'node:events';
 
 /**
@@ -17,7 +17,7 @@ import 'node:events';
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.3.1";
+declare const SDK_VERSION = "1.5.1";
 declare const SDK_NAME = "@cross-deck/node";
 
 /**
@@ -158,16 +158,34 @@ declare const _CROSSDECK_ERROR_CODES: readonly [{
     readonly resolution: "Increase flushOnExitTimeoutMs in CrossdeckServer options. Default is 2000ms; serverless runtimes typically allow 5-10s before SIGKILL. If events are dropping silently in production, raise this.";
     readonly retryable: false;
 }, {
-    readonly code: "webhook_invalid_signature";
+    readonly code: "webhook_signature_mismatch";
     readonly type: "authentication_error";
-    readonly description: "The webhook signature header did not verify against the supplied secret.";
-    readonly resolution: "Confirm the secret matches the one in your Crossdeck dashboard → Webhooks page. If the request is genuinely from Crossdeck, the secret is wrong, stale, or recently rotated.";
+    readonly description: "Webhook HMAC didn't verify against any configured secret (wrong-secret / stale rotation signal).";
+    readonly resolution: "Confirm the secret matches dashboard → Webhooks. If you rotated, include both the old and new secret as an array until receivers cut over.";
     readonly retryable: false;
 }, {
-    readonly code: "webhook_replay_window_exceeded";
+    readonly code: "webhook_timestamp_outside_tolerance";
     readonly type: "authentication_error";
-    readonly description: "The webhook timestamp is older than the replay-tolerance window (default 5 minutes).";
-    readonly 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.";
+    readonly description: "Webhook timestamp drift exceeds the configured replay-tolerance window (default 5 minutes; replay-attack signal).";
+    readonly resolution: "Verify NTP on the receiving host. A spike on this code warrants its own alert separate from signature_mismatch — replay attacks look like this.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_timestamp_missing";
+    readonly type: "authentication_error";
+    readonly description: "Webhook signature header is absent or has no `t=` timestamp segment — the timestamp gate cannot be verified.";
+    readonly 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.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_payload_not_json";
+    readonly type: "authentication_error";
+    readonly description: "Webhook signature verified but the body isn't valid JSON — payload tampered post-signing or source bug.";
+    readonly resolution: "Inspect the raw payload. If it's not JSON, either the request was modified in transit or the sender has a bug — file a support ticket with the raw body.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_invalid_tolerance";
+    readonly type: "configuration_error";
+    readonly description: "verifyWebhookSignature() called with a non-finite / negative / above-24h-cap replayToleranceMs (would silently disable replay protection).";
+    readonly 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.";
     readonly retryable: false;
 }, {
     readonly code: "webhook_missing_secret";
@@ -175,6 +193,84 @@ declare const _CROSSDECK_ERROR_CODES: readonly [{
     readonly description: "verifyWebhookSignature() was called without a signing secret.";
     readonly resolution: "Pass the secret from your Crossdeck dashboard → Webhooks page. Never hardcode in source — read from an env var.";
     readonly retryable: false;
+}, {
+    readonly code: "webhook_invalid_signature";
+    readonly type: "authentication_error";
+    readonly description: "DEPRECATED in v1.4.0 — split into webhook_signature_mismatch / webhook_timestamp_missing / webhook_timestamp_outside_tolerance / webhook_payload_not_json for alerting clarity.";
+    readonly resolution: "Migrate alert rules to the more specific v1.4.0 codes — they distinguish replay-attack signals from wrong-secret signals.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_replay_window_exceeded";
+    readonly type: "authentication_error";
+    readonly description: "DEPRECATED in v1.4.0 — renamed to webhook_timestamp_outside_tolerance.";
+    readonly resolution: "Update alerts to webhook_timestamp_outside_tolerance.";
+    readonly retryable: false;
+}, {
+    readonly code: "missing_api_key";
+    readonly type: "authentication_error";
+    readonly description: "No Authorization header (or Crossdeck-Api-Key header) on the request.";
+    readonly resolution: "Confirm the CrossdeckServer was constructed with a cd_sk_… secretKey. Re-check env vars in production deployments.";
+    readonly retryable: false;
+}, {
+    readonly code: "invalid_api_key";
+    readonly type: "authentication_error";
+    readonly description: "The secret key is malformed, unknown, or doesn't resolve to a project.";
+    readonly resolution: "Copy the key from Crossdeck dashboard → API keys. Server SDK requires cd_sk_test_ / cd_sk_live_ — client SDK keys (cd_pub_…) won't work on the Node SDK.";
+    readonly retryable: false;
+}, {
+    readonly code: "key_revoked";
+    readonly type: "authentication_error";
+    readonly description: "The secret key was revoked in the dashboard.";
+    readonly resolution: "Mint a fresh key in dashboard → API keys → Create new. The revoked key cannot be reactivated.";
+    readonly retryable: false;
+}, {
+    readonly code: "env_mismatch";
+    readonly type: "permission_error";
+    readonly description: "The key's env prefix doesn't match the resolved app's configured env.";
+    readonly resolution: "Use a cd_sk_live_ key with a production app, cd_sk_test_ with a sandbox app. Crossing breaks the env lock.";
+    readonly retryable: false;
+}, {
+    readonly code: "idempotency_key_in_use";
+    readonly type: "invalid_request_error";
+    readonly description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).";
+    readonly 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.";
+    readonly retryable: false;
+}, {
+    readonly code: "rate_limited";
+    readonly type: "rate_limit_error";
+    readonly description: "Request rate exceeded the project's per-second cap.";
+    readonly resolution: "Honour Retry-After (managed retries do this automatically). For custom paths, throttle to <100 req/s/key.";
+    readonly retryable: true;
+}, {
+    readonly code: "internal_error";
+    readonly type: "internal_error";
+    readonly description: "Server-side issue. Safe to retry with backoff.";
+    readonly resolution: "Managed retries handle this automatically. If a code path surfaces it to your code, contact support with the requestId.";
+    readonly retryable: true;
+}, {
+    readonly code: "google_not_supported";
+    readonly type: "invalid_request_error";
+    readonly description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.";
+    readonly resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The Android SDK auto-track path handles this transparently.";
+    readonly retryable: false;
+}, {
+    readonly code: "stripe_not_supported";
+    readonly type: "invalid_request_error";
+    readonly description: "POST /purchases/sync with rail=stripe is unsupported — Stripe webhooks deliver evidence server-side.";
+    readonly resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically.";
+    readonly retryable: false;
+}, {
+    readonly code: "missing_required_param";
+    readonly type: "invalid_request_error";
+    readonly description: "A required field is absent from the request body.";
+    readonly resolution: "The error.message identifies the missing field. Refer to the SDK's TypeScript types for canonical shapes.";
+    readonly retryable: false;
+}, {
+    readonly code: "invalid_param_value";
+    readonly type: "invalid_request_error";
+    readonly description: "A field is present but the value failed validation.";
+    readonly resolution: "Read error.message for the field + reason. SDK-managed call sites should never emit this — file a bug if you do.";
+    readonly retryable: false;
 }];
 /**
  * Literal union of every code documented in `CROSSDECK_ERROR_CODES`.
@@ -201,9 +297,22 @@ declare function getErrorCode(code: string): ErrorCodeEntry | undefined;
 /**
  * Webhook signature verification — Stripe pattern.
  *
- * Lets customers verify the events Crossdeck sends to THEM. Table-stakes
- * for any backend SDK (Stripe ships `Stripe.webhooks.constructEvent()`
- * from day one, Svix ships `Webhook.verify()` from day one).
+ * **[ROADMAP — v1.4.0 honesty note]:** Crossdeck does NOT yet send
+ * outbound webhooks. Outbound delivery (signer + worker + scheduler
+ * + dead-letter dashboard) is on the post-v1.5 roadmap. This
+ * verifier exists today so customer-side integration code can be
+ * written and tested against fixtures (use `signWebhookPayload`
+ * to produce signed bodies for your local tests), and so the
+ * verification contract surface is locked in BEFORE delivery
+ * ships — Phase 7.2 of the bank-grade reconciliation tightened
+ * the timestamp-validation footguns here precisely because the
+ * helper IS the contract surface for inbound validation,
+ * regardless of when first-party delivery lights up.
+ *
+ * Lets customers verify the events Crossdeck sends to THEM (when
+ * delivery ships). Table-stakes for any backend SDK (Stripe ships
+ * `Stripe.webhooks.constructEvent()` from day one, Svix ships
+ * `Webhook.verify()` from day one).
  *
  * Wire format:
  *   Header `Crossdeck-Signature: t=<unix-seconds>,v1=<hex>`
@@ -244,9 +353,21 @@ declare function getErrorCode(code: string): ErrorCodeEntry | undefined;
 interface VerifyWebhookOptions {
     /**
      * Maximum age of the webhook timestamp in milliseconds. Default
-     * 5 minutes (5 * 60 * 1000). Anything older than this is rejected
-     * as a replay. Pass 0 to disable the replay window (NOT recommended
-     * — accept the trade-off only if you have a separate replay defence).
+     * 5 minutes (`DEFAULT_REPLAY_TOLERANCE_MS`). Anything older than
+     * this is rejected as a replay.
+     *
+     * **v1.4.0 Phase 7.2 bank-grade contract:** the timestamp window
+     * is MANDATORY. Pre-v1.4.0 the helper accepted `tolerance: 0`
+     * (silently disables the check) and `tolerance: Infinity` /
+     * `null` / `NaN` (silently disables via `Math.abs(...) > Infinity
+     * = false`). Customers relying on replay protection silently
+     * lost it.
+     *
+     * The helper now rejects non-finite / negative / above-cap
+     * tolerances at the boundary with a typed
+     * `webhook_invalid_tolerance` error. Hard upper bound is 24h —
+     * sufficient for any plausible clock-skew scenario, prevents
+     * "Infinity by typo" from defeating replay protection.
      */
     replayToleranceMs?: number;
     /**
@@ -257,13 +378,21 @@ interface VerifyWebhookOptions {
 }
 /**
  * Verify a Crossdeck-signed webhook. Returns the parsed JSON payload
- * on success. Throws `CrossdeckError` on:
- *   - missing / malformed signature header (`webhook_invalid_signature`)
- *   - missing secret (`webhook_missing_secret`)
- *   - timestamp outside replay window (`webhook_replay_window_exceeded`)
- *   - HMAC mismatch (`webhook_invalid_signature`)
- *   - non-JSON payload (`webhook_invalid_signature` — same code because
- *     a tampered payload that breaks JSON parses as invalid)
+ * on success. Throws `CrossdeckError` with one of these
+ * distinguishable codes (v1.4.0 Phase 7.2 — pre-v1.4.0 conflated
+ * everything under `webhook_invalid_signature`; alerting can now
+ * separate replay-attack signals from wrong-secret signals):
+ *   - `webhook_missing_secret` — no secret configured.
+ *   - `webhook_invalid_tolerance` — caller passed Infinity / NaN /
+ *     negative / above-24h-cap `replayToleranceMs`.
+ *   - `webhook_timestamp_missing` — header absent or has no `t=`.
+ *   - `webhook_timestamp_outside_tolerance` — drift > tolerance
+ *     (replay-attack signal — split this from signature mismatch
+ *     in your alerting rules).
+ *   - `webhook_signature_mismatch` — HMAC didn't match any
+ *     configured secret (wrong-secret / rotation-drift signal).
+ *   - `webhook_payload_not_json` — signature verified but the body
+ *     isn't parseable JSON (tampered post-signing or source bug).
  *
  * `secret` accepts a single string or an array of strings (for
  * rotation). Any one match is sufficient.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementStore, w as EntitlementsListResponse, x as EntitlementsListener, y as Environment, z as ErrorCaptureConfig, F as ErrorLevel, G as EventProperties, H as ForgetResult, I as GrantDuration, J as GrantEntitlementInput, K as GroupMembership, L as HeartbeatResponse, M as HttpRequestInfo, N as HttpResponseInfo, O as HttpRetriesConfig, P as IdentifyOptions, Q as IdentityHints, R as IngestOptions, S as IngestResponse, T as PublicEntitlement, U as PurchaseResult, V as RequestOptions, W as RevokeEntitlementInput, X as RuntimeHost, Y as RuntimeInfo, Z as ServerEvent, _ as StackFrame, $ as StoredEntitlements, a0 as SyncPurchaseInput, a1 as makeCrossdeckError } from './crossdeck-server-DhnHvUhh.js';
+export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as Contract, h as ContractAppliesTo, i as ContractFailureInput, j as ContractPillar, k as ContractStatus, l as ContractTestRef, m as CrossdeckAuthenticationError, n as CrossdeckConfigurationError, o as CrossdeckContracts, p as CrossdeckError, q as CrossdeckErrorPayload, r as CrossdeckErrorType, s as CrossdeckInternalError, t as CrossdeckNetworkError, u as CrossdeckPermissionError, v as CrossdeckRateLimitError, w as CrossdeckServer, x as CrossdeckServerOptions, y as CrossdeckValidationError, D as DEFAULT_BASE_URL, z as DEFAULT_TIMEOUT_MS, E as Diagnostics, F as EntitlementCacheOptions, G as EntitlementMutationResult, H as EntitlementStore, I as EntitlementsListResponse, J as EntitlementsListener, K as Environment, L as ErrorCaptureConfig, M as ErrorLevel, N as EventProperties, O as ForgetResult, P as GrantDuration, Q as GrantEntitlementInput, R as GroupMembership, S as HeartbeatResponse, T as HttpRequestInfo, U as HttpResponseInfo, V as HttpRetriesConfig, W as IdentifyOptions, X as IdentityHints, Y as IngestOptions, Z as IngestResponse, _ as PublicEntitlement, $ as PurchaseResult, a0 as RequestOptions, a1 as RevokeEntitlementInput, a2 as RuntimeHost, a3 as RuntimeInfo, a4 as ServerEvent, a5 as StackFrame, a6 as StoredEntitlements, a7 as SyncPurchaseInput, a8 as makeCrossdeckError } from './crossdeck-server-CY4PZk-j.js';
 import 'node:events';
 
 /**
@@ -17,7 +17,7 @@ import 'node:events';
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.3.1";
+declare const SDK_VERSION = "1.5.1";
 declare const SDK_NAME = "@cross-deck/node";
 
 /**
@@ -158,16 +158,34 @@ declare const _CROSSDECK_ERROR_CODES: readonly [{
     readonly resolution: "Increase flushOnExitTimeoutMs in CrossdeckServer options. Default is 2000ms; serverless runtimes typically allow 5-10s before SIGKILL. If events are dropping silently in production, raise this.";
     readonly retryable: false;
 }, {
-    readonly code: "webhook_invalid_signature";
+    readonly code: "webhook_signature_mismatch";
     readonly type: "authentication_error";
-    readonly description: "The webhook signature header did not verify against the supplied secret.";
-    readonly resolution: "Confirm the secret matches the one in your Crossdeck dashboard → Webhooks page. If the request is genuinely from Crossdeck, the secret is wrong, stale, or recently rotated.";
+    readonly description: "Webhook HMAC didn't verify against any configured secret (wrong-secret / stale rotation signal).";
+    readonly resolution: "Confirm the secret matches dashboard → Webhooks. If you rotated, include both the old and new secret as an array until receivers cut over.";
     readonly retryable: false;
 }, {
-    readonly code: "webhook_replay_window_exceeded";
+    readonly code: "webhook_timestamp_outside_tolerance";
     readonly type: "authentication_error";
-    readonly description: "The webhook timestamp is older than the replay-tolerance window (default 5 minutes).";
-    readonly 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.";
+    readonly description: "Webhook timestamp drift exceeds the configured replay-tolerance window (default 5 minutes; replay-attack signal).";
+    readonly resolution: "Verify NTP on the receiving host. A spike on this code warrants its own alert separate from signature_mismatch — replay attacks look like this.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_timestamp_missing";
+    readonly type: "authentication_error";
+    readonly description: "Webhook signature header is absent or has no `t=` timestamp segment — the timestamp gate cannot be verified.";
+    readonly 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.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_payload_not_json";
+    readonly type: "authentication_error";
+    readonly description: "Webhook signature verified but the body isn't valid JSON — payload tampered post-signing or source bug.";
+    readonly resolution: "Inspect the raw payload. If it's not JSON, either the request was modified in transit or the sender has a bug — file a support ticket with the raw body.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_invalid_tolerance";
+    readonly type: "configuration_error";
+    readonly description: "verifyWebhookSignature() called with a non-finite / negative / above-24h-cap replayToleranceMs (would silently disable replay protection).";
+    readonly 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.";
     readonly retryable: false;
 }, {
     readonly code: "webhook_missing_secret";
@@ -175,6 +193,84 @@ declare const _CROSSDECK_ERROR_CODES: readonly [{
     readonly description: "verifyWebhookSignature() was called without a signing secret.";
     readonly resolution: "Pass the secret from your Crossdeck dashboard → Webhooks page. Never hardcode in source — read from an env var.";
     readonly retryable: false;
+}, {
+    readonly code: "webhook_invalid_signature";
+    readonly type: "authentication_error";
+    readonly description: "DEPRECATED in v1.4.0 — split into webhook_signature_mismatch / webhook_timestamp_missing / webhook_timestamp_outside_tolerance / webhook_payload_not_json for alerting clarity.";
+    readonly resolution: "Migrate alert rules to the more specific v1.4.0 codes — they distinguish replay-attack signals from wrong-secret signals.";
+    readonly retryable: false;
+}, {
+    readonly code: "webhook_replay_window_exceeded";
+    readonly type: "authentication_error";
+    readonly description: "DEPRECATED in v1.4.0 — renamed to webhook_timestamp_outside_tolerance.";
+    readonly resolution: "Update alerts to webhook_timestamp_outside_tolerance.";
+    readonly retryable: false;
+}, {
+    readonly code: "missing_api_key";
+    readonly type: "authentication_error";
+    readonly description: "No Authorization header (or Crossdeck-Api-Key header) on the request.";
+    readonly resolution: "Confirm the CrossdeckServer was constructed with a cd_sk_… secretKey. Re-check env vars in production deployments.";
+    readonly retryable: false;
+}, {
+    readonly code: "invalid_api_key";
+    readonly type: "authentication_error";
+    readonly description: "The secret key is malformed, unknown, or doesn't resolve to a project.";
+    readonly resolution: "Copy the key from Crossdeck dashboard → API keys. Server SDK requires cd_sk_test_ / cd_sk_live_ — client SDK keys (cd_pub_…) won't work on the Node SDK.";
+    readonly retryable: false;
+}, {
+    readonly code: "key_revoked";
+    readonly type: "authentication_error";
+    readonly description: "The secret key was revoked in the dashboard.";
+    readonly resolution: "Mint a fresh key in dashboard → API keys → Create new. The revoked key cannot be reactivated.";
+    readonly retryable: false;
+}, {
+    readonly code: "env_mismatch";
+    readonly type: "permission_error";
+    readonly description: "The key's env prefix doesn't match the resolved app's configured env.";
+    readonly resolution: "Use a cd_sk_live_ key with a production app, cd_sk_test_ with a sandbox app. Crossing breaks the env lock.";
+    readonly retryable: false;
+}, {
+    readonly code: "idempotency_key_in_use";
+    readonly type: "invalid_request_error";
+    readonly description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).";
+    readonly 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.";
+    readonly retryable: false;
+}, {
+    readonly code: "rate_limited";
+    readonly type: "rate_limit_error";
+    readonly description: "Request rate exceeded the project's per-second cap.";
+    readonly resolution: "Honour Retry-After (managed retries do this automatically). For custom paths, throttle to <100 req/s/key.";
+    readonly retryable: true;
+}, {
+    readonly code: "internal_error";
+    readonly type: "internal_error";
+    readonly description: "Server-side issue. Safe to retry with backoff.";
+    readonly resolution: "Managed retries handle this automatically. If a code path surfaces it to your code, contact support with the requestId.";
+    readonly retryable: true;
+}, {
+    readonly code: "google_not_supported";
+    readonly type: "invalid_request_error";
+    readonly description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.";
+    readonly resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The Android SDK auto-track path handles this transparently.";
+    readonly retryable: false;
+}, {
+    readonly code: "stripe_not_supported";
+    readonly type: "invalid_request_error";
+    readonly description: "POST /purchases/sync with rail=stripe is unsupported — Stripe webhooks deliver evidence server-side.";
+    readonly resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically.";
+    readonly retryable: false;
+}, {
+    readonly code: "missing_required_param";
+    readonly type: "invalid_request_error";
+    readonly description: "A required field is absent from the request body.";
+    readonly resolution: "The error.message identifies the missing field. Refer to the SDK's TypeScript types for canonical shapes.";
+    readonly retryable: false;
+}, {
+    readonly code: "invalid_param_value";
+    readonly type: "invalid_request_error";
+    readonly description: "A field is present but the value failed validation.";
+    readonly resolution: "Read error.message for the field + reason. SDK-managed call sites should never emit this — file a bug if you do.";
+    readonly retryable: false;
 }];
 /**
  * Literal union of every code documented in `CROSSDECK_ERROR_CODES`.
@@ -201,9 +297,22 @@ declare function getErrorCode(code: string): ErrorCodeEntry | undefined;
 /**
  * Webhook signature verification — Stripe pattern.
  *
- * Lets customers verify the events Crossdeck sends to THEM. Table-stakes
- * for any backend SDK (Stripe ships `Stripe.webhooks.constructEvent()`
- * from day one, Svix ships `Webhook.verify()` from day one).
+ * **[ROADMAP — v1.4.0 honesty note]:** Crossdeck does NOT yet send
+ * outbound webhooks. Outbound delivery (signer + worker + scheduler
+ * + dead-letter dashboard) is on the post-v1.5 roadmap. This
+ * verifier exists today so customer-side integration code can be
+ * written and tested against fixtures (use `signWebhookPayload`
+ * to produce signed bodies for your local tests), and so the
+ * verification contract surface is locked in BEFORE delivery
+ * ships — Phase 7.2 of the bank-grade reconciliation tightened
+ * the timestamp-validation footguns here precisely because the
+ * helper IS the contract surface for inbound validation,
+ * regardless of when first-party delivery lights up.
+ *
+ * Lets customers verify the events Crossdeck sends to THEM (when
+ * delivery ships). Table-stakes for any backend SDK (Stripe ships
+ * `Stripe.webhooks.constructEvent()` from day one, Svix ships
+ * `Webhook.verify()` from day one).
  *
  * Wire format:
  *   Header `Crossdeck-Signature: t=<unix-seconds>,v1=<hex>`
@@ -244,9 +353,21 @@ declare function getErrorCode(code: string): ErrorCodeEntry | undefined;
 interface VerifyWebhookOptions {
     /**
      * Maximum age of the webhook timestamp in milliseconds. Default
-     * 5 minutes (5 * 60 * 1000). Anything older than this is rejected
-     * as a replay. Pass 0 to disable the replay window (NOT recommended
-     * — accept the trade-off only if you have a separate replay defence).
+     * 5 minutes (`DEFAULT_REPLAY_TOLERANCE_MS`). Anything older than
+     * this is rejected as a replay.
+     *
+     * **v1.4.0 Phase 7.2 bank-grade contract:** the timestamp window
+     * is MANDATORY. Pre-v1.4.0 the helper accepted `tolerance: 0`
+     * (silently disables the check) and `tolerance: Infinity` /
+     * `null` / `NaN` (silently disables via `Math.abs(...) > Infinity
+     * = false`). Customers relying on replay protection silently
+     * lost it.
+     *
+     * The helper now rejects non-finite / negative / above-cap
+     * tolerances at the boundary with a typed
+     * `webhook_invalid_tolerance` error. Hard upper bound is 24h —
+     * sufficient for any plausible clock-skew scenario, prevents
+     * "Infinity by typo" from defeating replay protection.
      */
     replayToleranceMs?: number;
     /**
@@ -257,13 +378,21 @@ interface VerifyWebhookOptions {
 }
 /**
  * Verify a Crossdeck-signed webhook. Returns the parsed JSON payload
- * on success. Throws `CrossdeckError` on:
- *   - missing / malformed signature header (`webhook_invalid_signature`)
- *   - missing secret (`webhook_missing_secret`)
- *   - timestamp outside replay window (`webhook_replay_window_exceeded`)
- *   - HMAC mismatch (`webhook_invalid_signature`)
- *   - non-JSON payload (`webhook_invalid_signature` — same code because
- *     a tampered payload that breaks JSON parses as invalid)
+ * on success. Throws `CrossdeckError` with one of these
+ * distinguishable codes (v1.4.0 Phase 7.2 — pre-v1.4.0 conflated
+ * everything under `webhook_invalid_signature`; alerting can now
+ * separate replay-attack signals from wrong-secret signals):
+ *   - `webhook_missing_secret` — no secret configured.
+ *   - `webhook_invalid_tolerance` — caller passed Infinity / NaN /
+ *     negative / above-24h-cap `replayToleranceMs`.
+ *   - `webhook_timestamp_missing` — header absent or has no `t=`.
+ *   - `webhook_timestamp_outside_tolerance` — drift > tolerance
+ *     (replay-attack signal — split this from signature mismatch
+ *     in your alerting rules).
+ *   - `webhook_signature_mismatch` — HMAC didn't match any
+ *     configured secret (wrong-secret / rotation-drift signal).
+ *   - `webhook_payload_not_json` — signature verified but the body
+ *     isn't parseable JSON (tampered post-signing or source bug).
  *
  * `secret` accepts a single string or an array of strings (for
  * rotation). Any one match is sufficient.