@cross-deck/web 1.0.1 → 1.2.0

package/dist/index.d.ts

@@ -1,342 +1,54 @@
-/**
- * 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.init. Three fields are mandatory —
- * `appId`, `publicKey`, and `environment` — per NorthStar §11.1.
- *
- * The pair of (appId, environment) is what we put on the wire envelope
- * (NorthStar §13.1) so the backend can correlate events against the
- * specific app surface and refuse mismatched env declarations loudly.
- */
-interface CrossdeckOptions {
-    /**
-     * Your Crossdeck App ID (e.g. "app_web_xxx"). Required.
-     *
-     * Issued in the dashboard when you create an app. Goes on the wire
-     * envelope so the backend correlates events with the specific app
-     * surface — useful when one project has multiple apps (web + iOS +
-     * Android) sharing the same publishable key family.
-     */
-    appId: string;
-    /** Your Crossdeck publishable key (cd_pub_…). Required. */
-    publicKey: string;
-    /**
-     * Explicit environment declaration. Required.
-     *
-     * Must match the publishable key's prefix:
-     *   cd_pub_test_…  → "sandbox"
-     *   cd_pub_live_…  → "production"
-     *
-     * Mismatch is rejected at init time so a typo'd key can't silently
-     * route prod telemetry into sandbox dashboards.
-     */
-    environment: Environment;
-    /**
-     * 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;
-    /**
-     * Auto-tracking. Default: every flag is `true` in browsers, all
-     * silently no-op in Node.
-     *
-     * Pass `false` to disable everything, or a partial object to override
-     * individual flags:
-     *
-     *   Crossdeck.start({
-     *     publicKey: "...",
-     *     autoTrack: { pageViews: false }, // sessions + deviceInfo still on
-     *   });
-     */
-    autoTrack?: boolean | Partial<AutoTrackOptions>;
-    /**
-     * Your app's version (e.g. "1.2.3"). Auto-attached to every event as
-     * `properties.appVersion` when `autoTrack.deviceInfo` is enabled.
-     * Useful for slicing dashboards by build.
-     */
-    appVersion?: string;
-    /**
-     * Enable verbose diagnostic logging via the NorthStar §16 debug-signal
-     * vocabulary. Default: false. Equivalent to calling
-     * `Crossdeck.setDebugMode(true)` after init.
-     */
-    debug?: boolean;
-    /**
-     * Respect the browser's Do Not Track signal at init (v0.10.0+).
-     * Default `false`. When `true` AND the user has `navigator.doNotTrack === "1"`,
-     * the SDK boots with analytics / marketing / errors all denied —
-     * locked off even if the developer later calls `Crossdeck.consent({...})`.
-     * Industry has effectively deprecated DNT, but opt-in support is the
-     * polite default for privacy-first apps.
-     */
-    respectDnt?: boolean;
-    /**
-     * Scrub PII-shaped strings (email addresses, card numbers) from
-     * URL paths, event properties, and acquisition referrer before they
-     * leave the SDK. Default `true` — Stripe-grade. Disable only if your
-     * pipeline does its own PII redaction downstream and you need the
-     * raw strings.
-     */
-    scrubPii?: boolean;
-}
-/** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
-interface AutoTrackOptions {
-    /** Emit `session.started` / `session.ended` automatically. Default true (browser only). */
-    sessions: boolean;
-    /** Emit `page.viewed` on initial load + SPA navigation. Default true (browser only). */
-    pageViews: boolean;
-    /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
-    deviceInfo: boolean;
-    /**
-     * Click autocapture — fire `element.clicked` for every interactive
-     * click on the page. Default true. Mixpanel/Amplitude pattern. Powers
-     * Crossdeck's funnel-attribution USP ("clicked X then converted").
-     * Privacy: skips form inputs / password fields / [class~="cd-noTrack"]
-     * subtrees. Override on individual elements with data-cd-event="custom"
-     * or data-cd-prop-* for custom property tagging.
-     */
-    clicks: boolean;
-    /**
-     * Web Vitals capture (v0.9.0+) — emits `webvitals.lcp`, `webvitals.inp`,
-     * `webvitals.cls`, `webvitals.fcp`, `webvitals.ttfb` events using the
-     * browser's `PerformanceObserver`. Defaults to true in browsers,
-     * no-op everywhere else. Disable if you have a separate RUM provider
-     * (DataDog, Sentry Performance) and don't want duplicates.
-     */
-    webVitals: boolean;
-    /**
-     * Error capture (v1.0.0+) — installs window.onerror +
-     * window.onunhandledrejection listeners, wraps fetch + XHR to catch
-     * 5xx + network failures, ships each captured error as a Crossdeck
-     * event (kind: error.unhandled / error.unhandledrejection /
-     * error.handled / error.http / error.message). Errors gate on
-     * `consent.errors`. Rate-limited per-fingerprint so a runaway loop
-     * can't flood the queue; browser-extension noise filtered by
-     * default. Default true in browsers, no-op everywhere else.
-     */
-    errors: boolean;
-}
-/** 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 + profile traits passed to identify().
- *
- * `traits` is a free-form bag of profile data (name, plan, signupDate,
- * teamRole, etc.) that gets persisted on the Crossdeck customer record
- * and attached to every subsequent event of the identified user as
- * `$user.<key>` properties for dashboard filtering.
- *
- * Like event properties, traits are validated at the SDK boundary —
- * functions/symbols/undefined dropped, Date / BigInt / Error coerced,
- * strings > 1024 chars truncated. Caller's object is never mutated.
- */
-interface IdentifyOptions {
-    /** Optional email to attach to the customer record. */
-    email?: string;
-    /**
-     * Optional profile traits. Examples:
-     *   `{ name: "Wes", plan: "pro", signedUpAt: "2026-05-11" }`
-     *
-     * Treated like event properties — values are sanitised at the SDK
-     * boundary so a `{ avatar: <File>, callback: () => {} }` payload
-     * doesn't crash the alias request. Server-side, traits land on
-     * `customers/{cdcust}.traits` (additively — existing fields are
-     * preserved unless the new identify call overrides them).
-     */
-    traits?: Record<string, unknown>;
-}
-/**
- * Group context — Mixpanel-style. Identifies a customer's membership
- * in an organisational entity (org, account, team, workspace) so B2B
- * dashboards can answer "how is account X using my product".
- *
- * Attached to every event as `$groups.<type>` until cleared via
- * `Crossdeck.group(type, null)`. Multiple types can coexist (e.g.
- * `org` + `team`) — the SDK keeps a map keyed by type.
- */
-interface GroupTraits {
-    [key: string]: unknown;
-}
-/** 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;
-    /**
-     * Last `serverTime` value the SDK saw on a /sdk/heartbeat response,
-     * along with the local clock value AT that moment. Lets dashboards
-     * (and the developer, in debug mode) detect a wrong-system-clock
-     * problem before it corrupts a day of analytics. Null until the
-     * first heartbeat completes.
-     */
-    clock: {
-        /** Server's view of "now" from the last heartbeat (epoch ms). */
-        lastServerTime: number | null;
-        /** Client's `Date.now()` taken at the same moment as `lastServerTime`. */
-        lastClientTime: number | null;
-        /**
-         * `lastClientTime - lastServerTime` — positive means the client
-         * clock is AHEAD of the server. Outside ±5 minutes is suspicious
-         * and worth surfacing to the developer.
-         */
-        skewMs: number | null;
-    };
-    entitlements: {
-        count: number;
-        lastUpdated: number;
-        /**
-         * Cumulative count of listener invocations that threw. Swallowed
-         * inside the cache (a buggy consumer must not crash the SDK) but
-         * surfaced here so developers can spot broken subscribers.
-         */
-        listenerErrors: number;
-    };
-    events: {
-        buffered: number;
-        dropped: number;
-        inFlight: number;
-        lastFlushAt: number;
-        lastError: string | null;
-        /** Consecutive flush failures since the last success. */
-        consecutiveFailures: number;
-        /**
-         * When the next retry is scheduled (epoch ms), or null if the queue
-         * is idle / healthy.
-         */
-        nextRetryAt: number | null;
-    };
-}
+import { P as PublicEntitlement, C as CrossdeckOptions, I as IdentifyOptions, A as AliasResult, G as GroupTraits, E as EventProperties, a as PurchaseResult, H as HeartbeatResponse, D as Diagnostics, K as KeyValueStorage } from './types-BzoKor4z.js';
+export { b as AuditRail, c as AutoTrackOptions, d as EntitlementsListResponse, e as Environment, f as Platform } from './types-BzoKor4z.js';
 
 /**
- * Local cache of active entitlements so isEntitled() can answer
- * synchronously after the first read. Cache is updated:
- *   - On successful getEntitlements()
- *   - On successful purchase()
- *   - Manually via setFromList() (used by callers that batch updates)
- *
- * The cache holds only ACTIVE entitlements — inactive ones are excluded
- * by the backend before they hit us. isEntitled returns false for
- * anything not in the set.
+ * Durable last-known-good cache of the customer's entitlements.
+ *
+ * This cache is NOT a second source of truth. Crossdeck remains the
+ * only source; this is the SDK's local copy of what the server last
+ * told us — a cache that doesn't forget during a network partition.
+ *
+ * Durability contract (the RevenueCat model):
+ *   - Every successful server read is persisted to device storage
+ *     (localStorage, via the SDK's storage adapter).
+ *   - On SDK boot the cache hydrates from storage synchronously, so
+ *     isEntitled() answers correctly from the very first call — there
+ *     is no cold-start window where a returning Pro customer reads as
+ *     free.
+ *   - When the server is unreachable, the SDK keeps serving the last
+ *     entitlements it successfully fetched. A failed refresh never
+ *     reaches setFromList(), so it cannot clear the cache; only a
+ *     SUCCESSFUL fetch replaces it. An outage can never fail a paying
+ *     customer down to free.
+ *   - Staleness alone never returns false. Each entitlement is honoured
+ *     against its OWN validUntil instead — a time-based trial expiry
+ *     still applies even mid-partition, a still-valid Pro entitlement
+ *     rides the outage out.
+ *   - Staleness is VISIBLE, not silent. validUntil covers time-based
+ *     expiry; it does NOT cover an event-based revoke (chargeback,
+ *     refund, fraud) — that has no validUntil, so the cache would keep
+ *     serving a revoked customer through an outage. Serving them is the
+ *     right trade (don't lock real payers out), but unbounded-and-
+ *     invisible is the bug. So: once a refresh ATTEMPT fails (or the
+ *     data ages past staleAfterMs) the cache is marked stale —
+ *     isStale / freshness are surfaced in diagnostics(). It keeps
+ *     serving last-known-good; the staleness is just no longer hidden.
+ *
+ * The cache is wiped only on reset() (logout) and on an identity switch
+ * — never by a TTL.
  *
  * Reactive listener API
  * ---------------------
- * `subscribe(listener)` registers a callback that fires every time the
- * cache mutates (setFromList or clear). This is the foundation for the
- * `useEntitlement` React hook in `@cross-deck/web/react` and any other
- * framework binding consumers need: SwiftUI's `@Observable`, Vue's
- * `ref()`, Solid's signals, etc.
- *
- * Why we need it: isEntitled() is a sync cache read — but if a React
- * component calls it in a render path, React has no way to know when
- * the cache populates asynchronously after `getEntitlements()` lands.
- * Without a subscribe API the component shows the empty-cache result
- * forever (until something else triggers a re-render). With it, the
- * binding can re-render when the data actually arrives.
- *
- * Listener semantics:
- *   - Fired AFTER the cache has been mutated (listener sees fresh state)
- *   - Fire-and-forget: thrown errors in a listener don't crash the SDK
- *     (they're swallowed; the next listener still runs)
- *   - The unsubscribe function returned from subscribe() is idempotent
- *   - Listeners are NOT fired on subscribe — caller is expected to
- *     read current state synchronously from isEntitled()/list() if it
- *     wants the initial render to reflect cached data
- *
- * Thread / re-entrancy safety: this is a synchronous in-memory Set with
- * no I/O. The async paths that update it are serialised through the
- * SDK's request queue — callers won't see torn reads.
+ * `subscribe(listener)` registers a callback fired every time the cache
+ * mutates (setFromList or clear) — the foundation for the
+ * `useEntitlement` React hook and other framework bindings. Semantics:
+ *   - Fired AFTER the mutation, so the listener sees fresh state.
+ *   - Fire-and-forget: a throwing listener is swallowed (and counted)
+ *     so a buggy consumer can't crash the SDK or other listeners.
+ *   - Unsubscribe is idempotent.
+ *   - Listeners are NOT fired on subscribe — a caller that wants the
+ *     initial state reads isEntitled() / list() synchronously, which
+ *     work from boot thanks to hydration above.
  */
 
 type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
@@ -723,8 +435,12 @@ declare class CrossdeckClient {
      */
     getEntitlements(): Promise<PublicEntitlement[]>;
     /**
-     * Synchronous read from the local cache. Returns false if the cache
-     * has never been populated (call getEntitlements first to warm it).
+     * Synchronous read from the durable local cache — answers from
+     * last-known-good. The cache hydrates from device storage on boot and
+     * survives a Crossdeck outage, so a returning paying customer reads
+     * true even before the session's first network round-trip. Returns
+     * false only for a genuinely new install that has never completed a
+     * getEntitlements(), or for an entitlement past its own validUntil.
      */
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
@@ -955,7 +671,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**
@@ -1028,4 +744,4 @@ interface DeviceInfo {
     appVersion?: string;
 }
 
-export { type AliasResult, type AuditRail, type AutoTrackOptions, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type ErrorCodeEntry, type ErrorLevel, type EventProperties, type GroupTraits, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };
+export { AliasResult, type Breadcrumb, type BreadcrumbCategory, type BreadcrumbLevel, CROSSDECK_ERROR_CODES, type CapturedError, type ConsentState, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, Diagnostics, type ErrorCodeEntry, type ErrorLevel, EventProperties, GroupTraits, HeartbeatResponse, IdentifyOptions, KeyValueStorage, MemoryStorage, PublicEntitlement, PurchaseResult, SDK_NAME, SDK_VERSION, type StackFrame, getErrorCode };