@cross-deck/web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crossdeck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @cross-deck/web
+
+The Crossdeck SDK for browsers and Node.js. One package, one mental model, every Crossdeck client API in five lines of setup.
+
+```bash
+npm install @cross-deck/web
+```
+
+## Quick start
+
+```ts
+import { Crossdeck } from "@cross-deck/web";
+
+// 1. Boot once at app start
+Crossdeck.start({ publicKey: "cd_pub_live_…" });
+
+// 2. After the user logs in, link the device to your user ID
+await Crossdeck.identify("user_847");
+
+// 3. Read entitlements (warms the local cache)
+await Crossdeck.getEntitlements();
+
+// 4. Sync access checks (microsecond reads from cache)
+if (Crossdeck.isEntitled("pro")) {
+  showProFeatures();
+}
+
+// 5. Telemetry — fire-and-forget, batched in the background
+Crossdeck.track("paywall_viewed", { variant: "v3" });
+```
+
+That's the full happy path.
+
+## What it does
+
+- **One identity for every device + user.** Pre-login events get an `anonymousId`. After login, `identify()` links them to your user ID through Crossdeck's identity graph. The SDK persists both so subsequent app launches resume where you left off.
+- **Synchronous entitlement reads.** `getEntitlements()` populates a local cache. `isEntitled("pro")` is a Set lookup — no network call, no waiting.
+- **Batched telemetry.** `track()` queues events in memory; the SDK flushes every 5 seconds (configurable) or when the buffer hits 20 events. Network failures re-queue the batch — events aren't lost on a flaky connection.
+- **Boot heartbeat.** On `start()` the SDK pings `/v1/sdk/heartbeat` so the dashboard's Apps page can show you "last seen" per install. Disable with `autoHeartbeat: false`.
+- **Stripe-style errors.** Every async method throws `CrossdeckError` with `type`, `code`, `requestId`, and `status` — same shape as Stripe's SDKs, so generic error handlers transfer.
+
+## API
+
+### `Crossdeck.start(options)`
+
+Boot the client. Idempotent — calling twice with the same options is fine.
+
+```ts
+Crossdeck.start({
+  publicKey: "cd_pub_live_…",         // required
+  baseUrl: "https://api.cross-deck.com/v1",  // override for self-host or emulator
+  autoHeartbeat: true,                // default; set false for high-frequency boots
+  eventFlushBatchSize: 20,            // default
+  eventFlushIntervalMs: 5_000,        // default
+  storage: customStorage,             // override the persistence adapter
+});
+```
+
+The publishable key is safe to ship in client code. Crossdeck enforces origin allowlists (web), bundle-ID binding (mobile), and rate limits at the edge — see [docs/api-keys](https://cross-deck.com/docs/api-keys/) for the full security model.
+
+### `await Crossdeck.identify(userId, options?)`
+
+Link the anonymous device to a developer-supplied user ID. Persists the resolved Crossdeck customer ID for follow-up reads. Returns the `AliasResult`:
+
+```ts
+{
+  object: "alias_result",
+  crossdeckCustomerId: "cdcust_…",
+  linked: [
+    { type: "developer", id: "user_847" },
+    { type: "anonymous", id: "anon_…" },
+  ],
+  mergePending: false,   // see "Merge candidates" below
+  env: "production",
+}
+```
+
+If `mergePending: true`, both identifiers already pointed at different customers. Crossdeck **never silently merges** — your dashboard's operations queue surfaces the merge for human confirmation.
+
+### `await Crossdeck.getEntitlements()`
+
+Fetch the current customer's active entitlements. Returns an array of `PublicEntitlement` and updates the local cache.
+
+```ts
+const ents = await Crossdeck.getEntitlements();
+// [{ object: "entitlement", key: "pro", isActive: true, validUntil: 1717891200, source: {...}, updatedAt: ... }]
+```
+
+### `Crossdeck.isEntitled(key) → boolean`
+
+Synchronous read from the local cache. Returns `false` until you've called `getEntitlements()` once (or `purchaseApple()` resolved). After that, it's a Set lookup — call as often as you want.
+
+### `Crossdeck.track(name, properties?)`
+
+Queue a telemetry event. Returns immediately. Events flush in batches; force a flush with `flushEvents()`:
+
+```ts
+Crossdeck.track("checkout_started", { product: "annual_pro" });
+// …later, e.g. before page unload:
+window.addEventListener("beforeunload", () => {
+  void Crossdeck.flushEvents();
+});
+```
+
+Event names match `[A-Za-z0-9_.\-:]+`, max 128 chars. Properties are JSON-serialisable, max 8 KB per event after JSON encoding.
+
+### `await Crossdeck.purchaseApple(input)`
+
+Forward a StoreKit 2 transaction directly to Crossdeck for verification — closes the purchase-to-entitled latency from seconds to milliseconds (faster than waiting for the App Store webhook).
+
+```ts
+await Crossdeck.purchaseApple({
+  signedTransactionInfo: transaction.jsonRepresentation,  // from StoreKit 2
+  signedRenewalInfo: subscription.signedRenewalInfo,      // optional
+  appAccountToken: "uuid-…",                              // optional
+});
+```
+
+Stripe and Google purchases are verified via webhooks (Stripe Connect platform endpoint, Google Play RTDN) — there's no SDK-side push for those.
+
+### `await Crossdeck.heartbeat()`
+
+Manually send a heartbeat. Called automatically by `start()` unless `autoHeartbeat: false`. Returns the readiness summary the dashboard uses to display SDK installation status.
+
+### `Crossdeck.reset()`
+
+Wipe persisted identity + entitlement cache + queued events. Call on logout. The next session generates a fresh `anonymousId` and starts a clean identity-graph entry.
+
+### `Crossdeck.flushEvents()`
+
+Force-flush the in-memory event queue. Useful before page unload or when shutting down a script.
+
+### `Crossdeck.diagnostics()`
+
+Diagnostic snapshot — useful for development consoles and bug reports:
+
+```ts
+{
+  started: true,
+  anonymousId: "anon_…",
+  crossdeckCustomerId: "cdcust_…" | null,
+  developerUserId: "user_…" | null,
+  sdkVersion: "0.1.0",
+  baseUrl: "https://api.cross-deck.com/v1",
+  entitlements: { count: 2, lastUpdated: 1717891200000 },
+  events: { buffered: 0, dropped: 0, inFlight: 0, lastFlushAt: 1717891200000, lastError: null },
+}
+```
+
+## Errors
+
+Every async method can throw `CrossdeckError`. Synchronous methods throw on configuration mistakes (calling before `start()`, invalid key prefix).
+
+```ts
+import { CrossdeckError } from "@cross-deck/web";
+
+try {
+  await Crossdeck.identify("user_847");
+} catch (err) {
+  if (err instanceof CrossdeckError) {
+    console.error(err.type, err.code, err.requestId);
+    if (err.code === "invalid_api_key") {
+      // ...
+    }
+  }
+}
+```
+
+Error fields:
+
+| Field | What it is |
+|---|---|
+| `type` | One of `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `internal_error`, `network_error`, `configuration_error`. Same vocabulary the backend uses. |
+| `code` | Specific machine-readable code, e.g. `invalid_api_key`, `origin_not_allowed`, `rate_limited`, `network_error`. |
+| `message` | Human-readable description. |
+| `requestId` | Server-issued ID. Echo it in support tickets — we'll have a one-line log entry that explains the decision. |
+| `status` | HTTP status code if the error came from an API response. |
+
+## Node usage
+
+The SDK works the same way in Node 18+:
+
+```ts
+import { Crossdeck, MemoryStorage } from "@cross-deck/web";
+
+Crossdeck.start({
+  publicKey: process.env.CROSSDECK_PUBLIC_KEY!,
+  storage: new MemoryStorage(),  // session-only, no localStorage
+  autoHeartbeat: false,           // skip the boot ping in scripts
+});
+```
+
+For server-side flows where you need to read any customer's state (not just the caller's), use the **secret key** path — that ships when the `/v1/server/*` endpoints land.
+
+## Security
+
+Publishable keys aren't secrets — they're identifiers, safe to ship in client code. See [`docs/api-keys`](https://cross-deck.com/docs/api-keys/) for the full security model: how keys are stored, how requests are verified, what's enforced where. Highlights:
+
+- **Origin allowlists** on web keys (configured in the Crossdeck dashboard) reject requests from unauthorised origins.
+- **Tenant isolation** — a leaked key can read its own project's customer data only, never another tenant's.
+- **Env partition** — a `cd_pub_live_…` key cannot read `cd_pub_test_…` data and vice versa.
+- **No raw payment credentials** ever pass through this SDK or sit in a Crossdeck database. Apple `.p8`s, Stripe secret keys, Google service-account JSON — all in Google Cloud Secret Manager, runtime-only access from the Crossdeck backend.
+
+## Versioning
+
+This package follows [semver](https://semver.org). The wire-format types (`PublicEntitlement`, `AliasResult`, etc.) are duplicated from the backend's `v1-types.ts` — they're the stable contract, not a shared module. Breaking changes to those types only ship in major versions.
+
+## License
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,306 @@
+/**
+ * Public types for @cross-deck/web. These mirror the wire format
+ * exposed by the v1 backend API. Keep them in lockstep with
+ * backend/src/api/v1-types.ts — same field names, same nullability.
+ */
+type Environment = "production" | "sandbox";
+type Platform = "ios" | "android" | "web";
+type AuditRail = "apple" | "stripe" | "google" | "manual";
+interface PublicEntitlement {
+    object: "entitlement";
+    key: string;
+    isActive: boolean;
+    validUntil?: number | null;
+    source: {
+        rail: AuditRail;
+        productId: string;
+        subscriptionId: string;
+    };
+    updatedAt: number;
+}
+interface EntitlementsListResponse {
+    object: "list";
+    data: PublicEntitlement[];
+    crossdeckCustomerId: string;
+    env: Environment;
+}
+interface AliasResult {
+    object: "alias_result";
+    crossdeckCustomerId: string;
+    linked: Array<{
+        type: "developer";
+        id: string;
+    } | {
+        type: "anonymous";
+        id: string;
+    }>;
+    mergePending: boolean;
+    env: Environment;
+}
+interface PurchaseResult {
+    object: "purchase_result";
+    crossdeckCustomerId: string;
+    env: Environment;
+    entitlements: PublicEntitlement[];
+}
+interface HeartbeatResponse {
+    object: "heartbeat";
+    ok: true;
+    projectId: string;
+    appId: string;
+    platform: Platform;
+    env: Environment;
+    serverTime: number;
+}
+/**
+ * Configuration for Crossdeck.start. Most fields have sensible defaults
+ * — only `publicKey` is mandatory.
+ */
+interface CrossdeckOptions {
+    /** Your Crossdeck publishable key (cd_pub_…). Required. */
+    publicKey: string;
+    /**
+     * Override the API base URL. Default is https://api.cross-deck.com/v1.
+     * Useful for self-hosted setups or pointing at the local emulator
+     * (e.g. http://localhost:5001/crossdeck-47d8f/us-east4/v1).
+     */
+    baseUrl?: string;
+    /**
+     * Persist anonymousId + crossdeckCustomerId across sessions.
+     * Default: true in the browser (localStorage), false in Node (in-memory only).
+     */
+    persistIdentity?: boolean;
+    /**
+     * Storage adapter. The SDK calls .getItem / .setItem / .removeItem.
+     * Defaults to globalThis.localStorage when present. Pass an in-memory
+     * adapter for Node runtimes where you want session-only persistence.
+     */
+    storage?: KeyValueStorage;
+    /** Storage key prefix for the SDK's persisted state. Default "crossdeck:". */
+    storagePrefix?: string;
+    /**
+     * Send a heartbeat to /v1/sdk/heartbeat on start(). Default true.
+     * Disable for high-frequency boot scenarios where the heartbeat is
+     * pure overhead.
+     */
+    autoHeartbeat?: boolean;
+    /** Maximum events buffered before forced flush. Default 20. */
+    eventFlushBatchSize?: number;
+    /** Idle ms after the last track() before flushing. Default 5000. */
+    eventFlushIntervalMs?: number;
+    /** Override the SDK version reported on heartbeats. Default: package version. */
+    sdkVersion?: string;
+}
+/** Minimal interface for any pluggable key-value persistence. */
+interface KeyValueStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Identity hint object passed to identify() — at least one field required. */
+interface IdentifyOptions {
+    /** Optional email to attach to the customer record. */
+    email?: string;
+}
+/** Properties payload for track(). Arbitrary key/value, JSON-serialisable, ≤ 8 KB. */
+type EventProperties = Record<string, unknown>;
+/**
+ * Diagnostic snapshot returned by Crossdeck.diagnostics(). Stable shape
+ * whether or not start() has been called — callers don't need to narrow
+ * on `started` to read `events` or `entitlements`. Pre-start values are
+ * sensible empties (zeros, nulls).
+ */
+interface Diagnostics {
+    started: boolean;
+    anonymousId: string | null;
+    crossdeckCustomerId: string | null;
+    developerUserId: string | null;
+    sdkVersion: string | null;
+    baseUrl: string | null;
+    entitlements: {
+        count: number;
+        lastUpdated: number;
+    };
+    events: {
+        buffered: number;
+        dropped: number;
+        inFlight: number;
+        lastFlushAt: number;
+        lastError: string | null;
+    };
+}
+
+/**
+ * Public API surface for @cross-deck/web.
+ *
+ * Usage (browser):
+ *
+ *   import { Crossdeck } from "@cross-deck/web";
+ *
+ *   Crossdeck.start({ publicKey: "cd_pub_live_…" });
+ *
+ *   await Crossdeck.identify("user_847");
+ *   const ents = await Crossdeck.getEntitlements();
+ *   if (Crossdeck.isEntitled("pro")) {
+ *     showPro();
+ *   }
+ *   Crossdeck.track("paywall_shown", { variant: "v3" });
+ *
+ *
+ * Usage (Node):
+ *
+ *   import { Crossdeck } from "@cross-deck/web";
+ *   import { MemoryStorage } from "@cross-deck/web";
+ *
+ *   Crossdeck.start({
+ *     publicKey: "cd_pub_test_…",
+ *     storage: new MemoryStorage(),  // session-only persistence
+ *     autoHeartbeat: false,           // skip the boot ping in scripts
+ *   });
+ */
+
+declare class CrossdeckClient {
+    private state;
+    /**
+     * Boot the SDK. Idempotent — calling start twice with the same options
+     * is a no-op; calling with different options replaces the previous
+     * configuration.
+     */
+    start(options: CrossdeckOptions): void;
+    /**
+     * Link the anonymous device to a developer-supplied user ID. Cache
+     * the resolved Crossdeck customer for follow-up calls.
+     */
+    identify(userId: string, _options?: IdentifyOptions): Promise<AliasResult>;
+    /**
+     * Read the current customer's active entitlements from the server.
+     * Updates the local cache so subsequent isEntitled() calls answer
+     * synchronously.
+     */
+    getEntitlements(): Promise<PublicEntitlement[]>;
+    /**
+     * Synchronous read from the local cache. Returns false if the cache
+     * has never been populated (call getEntitlements first to warm it).
+     */
+    isEntitled(key: string): boolean;
+    /** Snapshot of the local entitlement cache. */
+    listEntitlements(): PublicEntitlement[];
+    /**
+     * Queue a telemetry event. Returns immediately — the network round-
+     * trip happens in the background. To flush before the page unloads,
+     * call flushEvents().
+     */
+    track(name: string, properties?: EventProperties): void;
+    /** Force-flush queued events. Useful to call from page-unload handlers. */
+    flushEvents(): Promise<void>;
+    /** Forward an Apple StoreKit 2 transaction for verification + projection. */
+    purchaseApple(input: {
+        signedTransactionInfo: string;
+        signedRenewalInfo?: string;
+        appAccountToken?: string;
+    }): Promise<PurchaseResult>;
+    /**
+     * Send the boot heartbeat. Called automatically by start() unless
+     * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
+     */
+    heartbeat(): Promise<HeartbeatResponse>;
+    /**
+     * Wipe persisted identity + entitlement cache. Use on logout. The
+     * next pre-login session generates a fresh anonymousId and starts a
+     * new identity-graph entry.
+     */
+    reset(): void;
+    /**
+     * Diagnostic: current state + queue stats. Useful for the dashboard's
+     * heartbeat row and debugging in dev.
+     *
+     * Returns a stable shape regardless of whether start() has been called —
+     * callers don't need to narrow on `started` to access `events` or
+     * `entitlements`. Pre-start values are sensible empties.
+     */
+    diagnostics(): Diagnostics;
+    private requireStarted;
+    /**
+     * Build the identity query for /v1/entitlements. Priority:
+     *   crossdeckCustomerId > developerUserId > anonymousId
+     * — matches the resolveCrossdeckCustomerId precedence on the server.
+     */
+    private identityQueryParams;
+    /** Pick the right identity hint to embed on a queued event. */
+    private identityHintForEvent;
+    private mintEventId;
+}
+/**
+ * Default singleton — most consumers want one SDK instance per app.
+ * Creating extra instances is fine; just `new CrossdeckClient()`.
+ */
+declare const Crossdeck: CrossdeckClient;
+
+/**
+ * Stripe-style error wrapper for @cross-deck/web.
+ *
+ * Mirrors the wire shape returned by the v1 backend (see
+ * backend/src/api/v1-errors.ts) so SDK consumers can `catch`
+ * with consistent fields:
+ *
+ *   try {
+ *     await crossdeck.identify("user_847");
+ *   } catch (err) {
+ *     if (err instanceof CrossdeckError && err.code === "invalid_api_key") {
+ *       // ...
+ *     }
+ *   }
+ */
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+interface CrossdeckErrorPayload {
+    type: CrossdeckErrorType;
+    code: string;
+    message: string;
+    /** Server-issued request ID. Echoed in support tickets. */
+    requestId?: string;
+    /** HTTP status code if the error came from an API response. */
+    status?: number;
+}
+declare class CrossdeckError extends Error {
+    readonly type: CrossdeckErrorType;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly status?: number;
+    constructor(payload: CrossdeckErrorPayload);
+}
+
+/**
+ * Storage adapters for SDK-persisted state.
+ *
+ * Two flavours:
+ *   - browser localStorage (default in browsers)
+ *   - in-memory (default in Node, or as an explicit fallback)
+ *
+ * Detection is at construction time, not at every call — picking the
+ * adapter once means we don't hit `typeof window` checks on hot paths.
+ */
+
+/**
+ * In-memory storage. Cleared on process exit. Useful for Node runtimes
+ * where you want session-scoped identity that doesn't persist to disk.
+ */
+declare class MemoryStorage implements KeyValueStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+/**
+ * HTTP transport for the SDK. Single fetch wrapper used by every endpoint
+ * call. Adds the Bearer token and SDK version header, parses responses,
+ * normalises errors to CrossdeckError.
+ *
+ * Uses platform-native fetch (browser + Node 18+). No axios, no isomorphic-
+ * fetch shim, no transitive deps.
+ */
+declare const SDK_NAME = "@cross-deck/web";
+declare const SDK_VERSION = "0.1.0";
+declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+
+export { type AliasResult, type AuditRail, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };