@cross-deck/node 1.2.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,156 @@ All notable changes to `@cross-deck/node` will be documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.2] — 2026-05-26
+
+Patch — fix `tests/shutdown-flush.test.ts` compile error under
+strict tsc. The five `s.track("name", { props })` calls used the
+web/RN positional-args shape; Node SDK's track takes a single
+`ServerEvent` object. Switched to `s.track({ name, properties })`.
+Plus a non-null assertion on `sent[0].length` for
+`noUncheckedIndexedAccess`. v1.4.1 was tagged on the public
+crossdeck-node repo but its publish workflow aborted on these
+errors. v1.4.2 is the first 1.4.x line to land on the npm
+registry. **No SDK code changes vs v1.4.0 / v1.4.1**.
+
+## [1.4.1] — 2026-05-26
+
+Patch — add automated npm publish workflow to the public
+`crossdeck-node` repo so future `vX.Y.Z` tag pushes auto-publish
+to npm via OIDC Trusted Publishing (matches the existing
+`crossdeck-web` pattern). Also strips `test:e2e` from
+`prepublishOnly` — the publish workflow runs lint + unit tests +
+build which covers the release gate. No SDK code changes vs
+v1.4.0.
+
+**Operator note:** npmjs.com Trusted Publisher rule must be
+configured for `crossdeck-node` (owner: VistaApps-za,
+workflow: publish.yml) before the OIDC publish succeeds. First
+publish after this lands will fail with an auth error if the
+rule is missing — that's the prompt to configure it.
+
+## [1.4.0] — 2026-05-26
+
+**Bank-grade reconciliation release.** 6-pillar KPMG-style audit closed across SDK + backend. Every behavioural guarantee registered in the monorepo's `contracts/` directory with a CI-enforced audit job.
+
+### Added
+
+- **PII scrubber applied on `track()` enqueue path** — parity with Web/RN/Swift. Pre-1.4.0 Node was the ONLY SDK that skipped this, shipping payloads UNREDACTED. New `scrubPii?: boolean` option (default true); explicit false opt-out preserves raw payloads for regulator-required audit trails.
+- **Deterministic `Idempotency-Key` on `syncPurchases()`** — same JWS/purchaseToken → same key. New `options.idempotencyKey` override for outer orchestrators.
+- **`PurchaseResult.idempotent_replay?: boolean`** — true when the backend replayed a cached response.
+- **`purchase.completed` event on every successful `syncPurchases()`** — funnel parity with Swift/Android auto-track.
+- **Distinguishable webhook verifier error codes** — pre-1.4.0 collapsed everything into `webhook_invalid_signature`. New: `webhook_signature_mismatch` (wrong-secret signal), `webhook_timestamp_outside_tolerance` (replay-attack signal — alert separately), `webhook_timestamp_missing`, `webhook_payload_not_json`, `webhook_invalid_tolerance`. Legacy codes deprecated with migration notes.
+- **Webhook verifier rejects footgun tolerances** — `Infinity` / `NaN` / negative / above-24h-cap now throw `webhook_invalid_tolerance` instead of silently disabling replay protection.
+- **15 backend-emitted error codes** added to the `crossdeck-error-codes.json` catalogue with Stripe-style remediation guidance.
+
+### Changed (breaking)
+
+- **`shutdown()` signature changed from `(reason) => void` to `(reason) => Promise<void>`.** Awaits `flush()` before tearing down the queue. Pre-1.4.0 it called `eventQueue.reset()` synchronously — every event between the last flush and shutdown was silently dropped. New `shutdownSync()` for callers that genuinely cannot await (signal handlers); it logs `console.warn` with the dropped-event count if the buffer is non-empty.
+- **Default event-queue flush interval is now 2000ms** (was 1500ms) — cross-SDK parity.
+- **`[Symbol.dispose]` now warns when dropping queued events.** Use `await using` + `[Symbol.asyncDispose]` (or `await server.shutdown()`) for proper drainage.
+
+## [1.3.1] — 2026-05-24
+
+Patch fix for the 1.3.0 dist-load contract. Mirrors the
+`@cross-deck/web@1.3.1` patch — `SDK_VERSION` is now sourced from a
+generated `src/_version.ts` file (produced by
+`scripts/sync-sdk-versions.mjs` from `package.json`) instead of a
+runtime `import { version } from "../package.json"` that needs a
+`with { type: "json" }` assertion to load as ESM. Wire contract is
+unchanged. 1.3.0 was never published to npm; 1.3.1 is the first
+1.3.x line to reach npm.
+
+## [1.3.0] — 2026-05-24
+
+KPMG bank-grade audit closure. Six review batches landed five SDK PRs
+and a backend wiring fix that closes every P0 plus 12 of 13 P1 findings.
+No public method renames; one internal contract change
+(`ErrorTracker.beforeSend` is now a getter) that also removes the
+`Object.defineProperty` workaround the node SDK shipped to compensate
+for the same broken contract on web. Behavioural changes to the queue
+and the PII scrub strictly improve correctness. The wire
+`Crossdeck-Sdk-Version` header now reads from `package.json` so it
+cannot drift from the published bundle.
+
+### Fixed (P0)
+
+- **PII scrub sentinel tokens aligned with the backend.** `[email]` /
+  `[card]` → `<email>` / `<card>`, matching `backend/src/api/lib/scrub.ts`.
+  The same event scrubbed by SDK + backend now carries the same
+  sentinel — dashboard aggregation works again.
+- **`setErrorBeforeSend` contract cleaned up.** The
+  `ErrorTracker.beforeSend` field is now a getter
+  (`() => fn | null`). Removed the `Object.defineProperty` hack on
+  `tracker.opts` that worked around the old captured-by-value bug —
+  cleaner contract, lockstep with web.
+- **Event queue drops 4xx batches.** Pre-fix every `catch` triggered
+  `scheduleRetry` with the same `Idempotency-Key`. A 401 (key revoked),
+  400/422 (malformed batch), 403 (permission), 404 (wrong baseUrl)
+  spun the retry timer indefinitely while the backlog grew silently.
+  New `isPermanent4xx()` helper hard-stops on any 4xx EXCEPT 408 / 429
+  (transient by spec). On permanent failure: drop the batch, increment
+  `dropped`, fire `onPermanentFailure(info)`, emit
+  `queue.permanent_failure` on the EventEmitter, log via
+  `console.error` regardless of debug mode.
+- **Error-capture self-skip derived from `baseUrl`.** Pre-fix hardcoded
+  to `api.cross-deck.com`; customers on staging / regional / self-hosted
+  base URLs recursed (5xx → captureHttp → enqueue → /events →
+  captureHttp → ∞). Now strict-hostname compare against `selfHostname`
+  extracted from constructor `baseUrl`. Closes the substring-match
+  bypass (`api.cross-deck.com.attacker.example` would have matched).
+
+### Added
+
+- **`onPermanentFailure` callback** on `EventQueueConfig`, surfaced
+  via `CrossdeckServer.on("queue.permanent_failure", …)` for host-app
+  paging.
+- **`sdk.flush_permanent_failure` debug signal** in the
+  `DebugSignal` vocabulary.
+
+### Changed
+
+- **`SDK_VERSION` is now imported from `package.json`.** The
+  `Crossdeck-Sdk-Version` header always matches the published bundle.
+  Single source of truth.
+- **Event ingest envelope now ships `environment`.** Pre-fix web sent
+  it and node didn't; backend `v1-events.ts` cross-checks it against
+  the API-key-derived env and rejects mismatches loudly
+  (`env_mismatch`). Defence-in-depth so a "live key, env: sandbox"
+  misconfig fails fast instead of polluting the wrong dashboard.
+- **`syncPurchases` body spread bug.** Pre-fix
+  `{ rail: input.rail ?? "apple", ...input }` — the `...input` ran
+  LAST and overrode the default when the caller passed
+  `rail: undefined` explicitly. Reversed: `{ ...input, rail }`.
+- **PII scrub regex uses `.replace()` unconditionally.** Dropped the
+  `.test()`-gating that carried `lastIndex` state between calls.
+- **`bootHeartbeat: false` no longer silences the
+  `sdk.no_durable_store` warning.** Pre-fix the warning lived inside
+  `emitBootTelemetry()` which sat inside the `bootHeartbeat` gate, so
+  the opt-out silenced the entire reason `entitlementStore` exists.
+  Split into two methods: `emitDurabilityWarning()` (local-only,
+  unconditional) and `emitBootTelemetryEvent()` (phone-home, still
+  gated).
+- **`isEntitled(string)` requires the `cdcust_` prefix** for canonical-
+  path resolution. Pre-fix any string with a cache entry resolved
+  through the canonical path — a small cross-tenant primitive if a
+  tenant's userId collided with another tenant's `crossdeckCustomerId`.
+  Non-prefixed strings now drop to alias lookup only.
+- **Self-skip applies to breadcrumbs too**, not just `captureHttp`.
+  Error reports no longer carry noisy `POST https://api.cross-deck.com/v1/events`
+  crumb entries.
+
+### Wiring (backend, paired)
+
+- **`v1-events` ingest now honours the per-project `piiAllowList`.**
+  The admin management surface (`v1-pii-allow-list.ts`) was persisted +
+  audit-logged but the hot ingest path never read it. The new
+  `backend/src/api/lib/pii-allow-list-cache.ts` (60s TTL,
+  single-flight) feeds the project's allow-list to `scrubProperties()`
+  on every batch. `HARD_LOCKED_PATTERNS` are always stripped from the
+  effective list regardless of what's in storage. (Backend-only —
+  listed here so server-SDK consumers know defence-in-depth is fully
+  closed.)
+
 ## [1.2.0] — 2026-05-18
 
 ### Added

package/README.md

@@ -397,6 +397,14 @@ new CrossdeckServer({
 
 POST methods (`track`/`ingest`/`syncPurchases`/`grantEntitlement`/`revokeEntitlement`) DO NOT auto-retry at the HTTP layer. Retries happen via the event queue with per-batch `Idempotency-Key` reuse — the server can dedupe replays.
 
+**v1.4.0 — `syncPurchases` deterministic key.** The Idempotency-Key
+on `syncPurchases` is derived from the request body (UUID-shaped
+SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Two retries
+of the same Apple transaction land on the same key, so the backend
+short-circuits with `idempotent_replay: true` instead of
+double-processing. Override via `options.idempotencyKey` only when
+an outer orchestrator needs a different idempotency window.
+
 ### AbortSignal — caller-controlled cancellation
 
 Every async method accepts a final `RequestOptions?` with `{ signal, timeoutMs }`:
@@ -414,6 +422,60 @@ try {
 }
 ```
 
+### PII scrubber (v1.4.0 — parity with Web/RN/Swift)
+
+Every `track()` payload runs through `scrubPiiFromProperties`
+before enqueue — email-shaped and card-number-shaped substrings
+are rewritten to `<email>` / `<card>` sentinels recursively
+across nested objects + arrays. **Default: on.** Pre-v1.4.0 the
+Node SDK was the only one that skipped this, shipping payloads
+UNREDACTED despite the README promising parity.
+
+Opt out only for regulator-required audit trails where the raw
+value must be preserved:
+
+```ts
+new CrossdeckServer({ secretKey, scrubPii: false });
+```
+
+**Blast radius:** every `track()` payload — event names with
+embedded emails, trait values, group memberships, error context
+blobs — ships verbatim to Crossdeck and downstream warehouses /
+analytics exports. Document the decision at the call site.
+
+### Shutdown — flush before exit (v1.4.0 contract)
+
+The server holds a buffered event queue. A clean teardown MUST
+flush the buffer before dropping it, otherwise events queued
+between the last flush and shutdown are silently lost.
+
+**Three teardown paths, three contracts:**
+
+| Method | Flushes? | Use when |
+| ------ | -------- | -------- |
+| `await server.shutdown()` | YES — awaits internal `flush()` then tears down | Default. Use this in graceful-shutdown handlers. |
+| `await using server = ...` + `[Symbol.asyncDispose]` | YES — equivalent to `await server.shutdown()` | TC39 explicit-resource-management blocks. |
+| `server.shutdownSync()` / `using` + `[Symbol.dispose]` | NO — drops the buffer | ONLY when the runtime cannot await (signal handlers, process.exit fallthrough). |
+
+```ts
+// Graceful shutdown (recommended)
+process.on("SIGTERM", async () => {
+  await server.shutdown();
+  process.exit(0);
+});
+
+// Explicit-resource-management (Node 20+ / TS 5.2+)
+{
+  await using server = new CrossdeckServer({ secretKey });
+  // ... use server ...
+} // [Symbol.asyncDispose] fires here, awaits flush
+```
+
+`shutdownSync()` (and the sync `[Symbol.dispose]` that wraps it)
+logs a `console.warn` with the dropped-event count whenever the
+buffer is non-empty at sync-teardown time — silent loss is
+incompatible with the bank-grade contract.
+
 ### EventEmitter — internal events
 
 `CrossdeckServer extends EventEmitter`. Subscribe to internal lifecycle events with typed listeners:

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

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

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

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