@cross-deck/web 0.1.0

package/dist/index.mjs

@@ -0,0 +1,622 @@
+// src/errors.ts
+var CrossdeckError = class _CrossdeckError extends Error {
+  constructor(payload) {
+    super(payload.message);
+    this.name = "CrossdeckError";
+    this.type = payload.type;
+    this.code = payload.code;
+    this.requestId = payload.requestId;
+    this.status = payload.status;
+    Object.setPrototypeOf(this, _CrossdeckError.prototype);
+  }
+};
+async function crossdeckErrorFromResponse(res) {
+  const requestId = res.headers.get("x-request-id") ?? void 0;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  const envelope = body?.error;
+  if (envelope && typeof envelope.type === "string" && typeof envelope.code === "string") {
+    return new CrossdeckError({
+      type: envelope.type,
+      code: envelope.code,
+      message: envelope.message ?? `HTTP ${res.status}`,
+      requestId: envelope.request_id ?? requestId,
+      status: res.status
+    });
+  }
+  return new CrossdeckError({
+    type: typeMapForStatus(res.status),
+    code: `http_${res.status}`,
+    message: `HTTP ${res.status} ${res.statusText || ""}`.trim(),
+    requestId,
+    status: res.status
+  });
+}
+function typeMapForStatus(status) {
+  if (status === 401) return "authentication_error";
+  if (status === 403) return "permission_error";
+  if (status === 429) return "rate_limit_error";
+  if (status >= 400 && status < 500) return "invalid_request_error";
+  return "internal_error";
+}
+
+// src/http.ts
+var SDK_NAME = "@cross-deck/web";
+var SDK_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Issue a request. `path` is relative to the configured baseUrl
+   * ("/entitlements", "/identity/alias", etc.).
+   *
+   * Throws CrossdeckError on:
+   *   - Network failure (`type: "network_error"`)
+   *   - Non-2xx response (typed from the body envelope)
+   *   - JSON parse failure on a 2xx (treated as `internal_error`)
+   */
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = {
+      Authorization: `Bearer ${this.config.publicKey}`,
+      "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
+      Accept: "application/json"
+    };
+    let bodyInit;
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      bodyInit = JSON.stringify(options.body);
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: bodyInit
+      });
+    } catch (err) {
+      throw new CrossdeckError({
+        type: "network_error",
+        code: "fetch_failed",
+        message: err instanceof Error ? err.message : "fetch failed"
+      });
+    }
+    if (!response.ok) {
+      throw await crossdeckErrorFromResponse(response);
+    }
+    if (response.status === 204) return void 0;
+    try {
+      return await response.json();
+    } catch (err) {
+      throw new CrossdeckError({
+        type: "internal_error",
+        code: "invalid_json_response",
+        message: "Server returned a 2xx with an unparseable body.",
+        requestId: response.headers.get("x-request-id") ?? void 0,
+        status: response.status
+      });
+    }
+  }
+  buildUrl(path, query) {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    let url = base + cleanPath;
+    if (query) {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(query)) {
+        if (typeof v === "string" && v.length > 0) params.append(k, v);
+      }
+      const qs = params.toString();
+      if (qs) url += (url.includes("?") ? "&" : "?") + qs;
+    }
+    return url;
+  }
+};
+
+// src/identity.ts
+var KEY_ANON = "anon_id";
+var KEY_CDCUST = "cdcust_id";
+var IdentityStore = class {
+  constructor(storage, prefix) {
+    this.storage = storage;
+    this.prefix = prefix;
+    const stored = {
+      anon: storage.getItem(prefix + KEY_ANON),
+      cdcust: storage.getItem(prefix + KEY_CDCUST)
+    };
+    this.state = {
+      anonymousId: stored.anon ?? this.mintAnonymousId(),
+      crossdeckCustomerId: stored.cdcust
+    };
+    if (!stored.anon) {
+      storage.setItem(prefix + KEY_ANON, this.state.anonymousId);
+    }
+  }
+  /** Return the persisted anonymous device ID (always set). */
+  get anonymousId() {
+    return this.state.anonymousId;
+  }
+  /** Return the resolved cross­deckCustomerId once we have one, else null. */
+  get crossdeckCustomerId() {
+    return this.state.crossdeckCustomerId;
+  }
+  /** Persist a newly-resolved Crossdeck customer ID. */
+  setCrossdeckCustomerId(value) {
+    this.state.crossdeckCustomerId = value;
+    this.storage.setItem(this.prefix + KEY_CDCUST, value);
+  }
+  /**
+   * Wipe persisted identity. Called by reset() — used when an end-user
+   * logs out. After reset the SDK mints a new anonymousId so the next
+   * pre-login session is a fresh customer in the identity graph.
+   */
+  reset() {
+    this.storage.removeItem(this.prefix + KEY_ANON);
+    this.storage.removeItem(this.prefix + KEY_CDCUST);
+    this.state = {
+      anonymousId: this.mintAnonymousId(),
+      crossdeckCustomerId: null
+    };
+    this.storage.setItem(this.prefix + KEY_ANON, this.state.anonymousId);
+  }
+  /**
+   * Generate an anonymousId. Crockford-ish base32 timestamp + random
+   * suffix. Same shape Stripe / Segment / others use — sortable, log-
+   * friendly, no PII.
+   */
+  mintAnonymousId() {
+    const ts = Date.now().toString(36);
+    const rand = randomChars(10);
+    return `anon_${ts}${rand}`;
+  }
+};
+function randomChars(count) {
+  const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+  const out = [];
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.getRandomValues) {
+    const buf = new Uint8Array(count);
+    cryptoApi.getRandomValues(buf);
+    for (let i = 0; i < count; i++) {
+      out.push(alphabet[buf[i] % alphabet.length] ?? "0");
+    }
+  } else {
+    for (let i = 0; i < count; i++) {
+      out.push(alphabet[Math.floor(Math.random() * alphabet.length)] ?? "0");
+    }
+  }
+  return out.join("");
+}
+
+// src/entitlement-cache.ts
+var EntitlementCache = class {
+  constructor() {
+    this.active = /* @__PURE__ */ new Set();
+    this.all = [];
+    this.lastUpdated = 0;
+  }
+  /** Sync read — true iff the entitlement key is currently active. */
+  isEntitled(key) {
+    return this.active.has(key);
+  }
+  /** Full snapshot for callers that need source / validUntil details. */
+  list() {
+    return this.all.slice();
+  }
+  /** When the cache was last refreshed. 0 means "never". */
+  get freshness() {
+    return this.lastUpdated;
+  }
+  /**
+   * Replace the cache with a fresh server response. The backend already
+   * filters to active + env-matching, so we don't re-filter — just trust
+   * what we got.
+   */
+  setFromList(entitlements) {
+    this.all = entitlements.slice();
+    this.active = new Set(entitlements.filter((e) => e.isActive).map((e) => e.key));
+    this.lastUpdated = Date.now();
+  }
+  /**
+   * Wipe — used on reset() (logout). The SDK forgets everything until
+   * the next identify + read.
+   */
+  clear() {
+    this.active.clear();
+    this.all = [];
+    this.lastUpdated = 0;
+  }
+};
+
+// src/event-queue.ts
+var HARD_BUFFER_CAP = 1e3;
+var EventQueue = class {
+  constructor(cfg) {
+    this.cfg = cfg;
+    this.buffer = [];
+    this.dropped = 0;
+    this.inFlight = 0;
+    this.lastFlushAt = 0;
+    this.lastError = null;
+    this.cancelTimer = null;
+  }
+  enqueue(event) {
+    this.buffer.push(event);
+    if (this.buffer.length > HARD_BUFFER_CAP) {
+      const overflow = this.buffer.length - HARD_BUFFER_CAP;
+      this.buffer.splice(0, overflow);
+      this.dropped += overflow;
+      this.cfg.onDrop?.(overflow);
+    }
+    if (this.buffer.length >= this.cfg.batchSize) {
+      void this.flush();
+    } else {
+      this.scheduleIdleFlush();
+    }
+  }
+  /**
+   * Flush the buffer to /v1/events. Resolves when the network call
+   * completes (success or failure). On failure, events stay in the
+   * buffer for the next flush attempt.
+   */
+  async flush() {
+    if (this.buffer.length === 0) return null;
+    this.cancelTimerIfSet();
+    const batch = this.buffer.splice(0);
+    this.inFlight += batch.length;
+    try {
+      const result = await this.cfg.http.request("POST", "/events", {
+        body: { events: batch }
+      });
+      this.lastFlushAt = Date.now();
+      this.lastError = null;
+      this.inFlight -= batch.length;
+      return result;
+    } catch (err) {
+      this.buffer.unshift(...batch);
+      this.inFlight -= batch.length;
+      this.lastError = err instanceof Error ? err.message : String(err);
+      this.scheduleIdleFlush();
+      return null;
+    }
+  }
+  /** Cancel any pending timer and clear in-memory state. */
+  reset() {
+    this.cancelTimerIfSet();
+    this.buffer = [];
+    this.dropped = 0;
+    this.inFlight = 0;
+    this.lastError = null;
+  }
+  getStats() {
+    return {
+      buffered: this.buffer.length,
+      dropped: this.dropped,
+      inFlight: this.inFlight,
+      lastFlushAt: this.lastFlushAt,
+      lastError: this.lastError
+    };
+  }
+  scheduleIdleFlush() {
+    this.cancelTimerIfSet();
+    const sched = this.cfg.scheduler ?? defaultScheduler;
+    this.cancelTimer = sched(() => {
+      void this.flush();
+    }, this.cfg.intervalMs);
+  }
+  cancelTimerIfSet() {
+    if (this.cancelTimer) {
+      this.cancelTimer();
+      this.cancelTimer = null;
+    }
+  }
+};
+function defaultScheduler(fn, ms) {
+  const id = setTimeout(fn, ms);
+  if (typeof id.unref === "function") {
+    try {
+      id.unref();
+    } catch {
+    }
+  }
+  return () => clearTimeout(id);
+}
+
+// src/storage.ts
+var MemoryStorage = class {
+  constructor() {
+    this.store = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.store.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.store.set(key, value);
+  }
+  removeItem(key) {
+    this.store.delete(key);
+  }
+};
+function detectDefaultStorage() {
+  try {
+    const ls = globalThis.localStorage;
+    if (ls) {
+      const probe = "__crossdeck_probe__";
+      ls.setItem(probe, "1");
+      ls.removeItem(probe);
+      return ls;
+    }
+  } catch {
+  }
+  return new MemoryStorage();
+}
+
+// src/crossdeck.ts
+var CrossdeckClient = class {
+  constructor() {
+    this.state = null;
+  }
+  /**
+   * 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) {
+    if (!options.publicKey || !options.publicKey.startsWith("cd_pub_")) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "invalid_public_key",
+        message: "Crossdeck.start requires a publishable key starting with cd_pub_."
+      });
+    }
+    const storage = options.storage ?? detectDefaultStorage();
+    const persistIdentity = options.persistIdentity ?? true;
+    const opts = {
+      publicKey: options.publicKey,
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      persistIdentity,
+      storagePrefix: options.storagePrefix ?? "crossdeck:",
+      autoHeartbeat: options.autoHeartbeat ?? true,
+      eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
+      sdkVersion: options.sdkVersion ?? SDK_VERSION
+    };
+    const http = new HttpClient({
+      publicKey: opts.publicKey,
+      baseUrl: opts.baseUrl,
+      sdkVersion: opts.sdkVersion
+    });
+    const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
+    const identity = new IdentityStore(effectiveStorage, opts.storagePrefix);
+    const entitlements = new EntitlementCache();
+    const events = new EventQueue({
+      http,
+      batchSize: opts.eventFlushBatchSize,
+      intervalMs: opts.eventFlushIntervalMs
+    });
+    this.state = {
+      http,
+      identity,
+      entitlements,
+      events,
+      options: opts,
+      developerUserId: null
+    };
+    if (opts.autoHeartbeat) {
+      void this.heartbeat().catch(() => void 0);
+    }
+  }
+  /**
+   * Link the anonymous device to a developer-supplied user ID. Cache
+   * the resolved Crossdeck customer for follow-up calls.
+   */
+  async identify(userId, _options) {
+    const s = this.requireStarted();
+    if (!userId) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_user_id",
+        message: "identify(userId) requires a non-empty userId."
+      });
+    }
+    const result = await s.http.request("POST", "/identity/alias", {
+      body: { userId, anonymousId: s.identity.anonymousId }
+    });
+    s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    s.developerUserId = userId;
+    return result;
+  }
+  /**
+   * Read the current customer's active entitlements from the server.
+   * Updates the local cache so subsequent isEntitled() calls answer
+   * synchronously.
+   */
+  async getEntitlements() {
+    const s = this.requireStarted();
+    const query = this.identityQueryParams();
+    const result = await s.http.request(
+      "GET",
+      "/entitlements",
+      { query }
+    );
+    if (result.crossdeckCustomerId) {
+      s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    }
+    s.entitlements.setFromList(result.data);
+    return result.data;
+  }
+  /**
+   * Synchronous read from the local cache. Returns false if the cache
+   * has never been populated (call getEntitlements first to warm it).
+   */
+  isEntitled(key) {
+    const s = this.requireStarted();
+    return s.entitlements.isEntitled(key);
+  }
+  /** Snapshot of the local entitlement cache. */
+  listEntitlements() {
+    const s = this.requireStarted();
+    return s.entitlements.list();
+  }
+  /**
+   * Queue a telemetry event. Returns immediately — the network round-
+   * trip happens in the background. To flush before the page unloads,
+   * call flushEvents().
+   */
+  track(name, properties) {
+    const s = this.requireStarted();
+    if (!name) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_event_name",
+        message: "track(name) requires a non-empty name."
+      });
+    }
+    const event = {
+      eventId: this.mintEventId(),
+      name,
+      timestamp: Date.now(),
+      properties: properties ?? {}
+    };
+    Object.assign(event, this.identityHintForEvent());
+    s.events.enqueue(event);
+  }
+  /** Force-flush queued events. Useful to call from page-unload handlers. */
+  async flushEvents() {
+    const s = this.requireStarted();
+    await s.events.flush();
+  }
+  /** Forward an Apple StoreKit 2 transaction for verification + projection. */
+  async purchaseApple(input) {
+    const s = this.requireStarted();
+    if (!input.signedTransactionInfo) {
+      throw new CrossdeckError({
+        type: "invalid_request_error",
+        code: "missing_signed_transaction_info",
+        message: "purchaseApple requires a signedTransactionInfo string from StoreKit 2."
+      });
+    }
+    const result = await s.http.request("POST", "/purchases", {
+      body: { rail: "apple", ...input }
+    });
+    s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
+    s.entitlements.setFromList(result.entitlements);
+    return result;
+  }
+  /**
+   * Send the boot heartbeat. Called automatically by start() unless
+   * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
+   */
+  async heartbeat() {
+    const s = this.requireStarted();
+    return await s.http.request("GET", "/sdk/heartbeat");
+  }
+  /**
+   * 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() {
+    if (!this.state) return;
+    this.state.identity.reset();
+    this.state.entitlements.clear();
+    this.state.events.reset();
+    this.state.developerUserId = null;
+  }
+  /**
+   * 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() {
+    if (!this.state) {
+      return {
+        started: false,
+        anonymousId: null,
+        crossdeckCustomerId: null,
+        developerUserId: null,
+        sdkVersion: null,
+        baseUrl: null,
+        entitlements: { count: 0, lastUpdated: 0 },
+        events: {
+          buffered: 0,
+          dropped: 0,
+          inFlight: 0,
+          lastFlushAt: 0,
+          lastError: null
+        }
+      };
+    }
+    const s = this.state;
+    return {
+      started: true,
+      anonymousId: s.identity.anonymousId,
+      crossdeckCustomerId: s.identity.crossdeckCustomerId,
+      developerUserId: s.developerUserId,
+      sdkVersion: s.options.sdkVersion,
+      baseUrl: s.options.baseUrl,
+      entitlements: {
+        count: s.entitlements.list().length,
+        lastUpdated: s.entitlements.freshness
+      },
+      events: s.events.getStats()
+    };
+  }
+  // ---------- private helpers ----------
+  requireStarted() {
+    if (!this.state) {
+      throw new CrossdeckError({
+        type: "configuration_error",
+        code: "not_started",
+        message: "Call Crossdeck.start({ publicKey }) before any other method."
+      });
+    }
+    return this.state;
+  }
+  /**
+   * Build the identity query for /v1/entitlements. Priority:
+   *   crossdeckCustomerId > developerUserId > anonymousId
+   * — matches the resolveCrossdeckCustomerId precedence on the server.
+   */
+  identityQueryParams() {
+    const s = this.requireStarted();
+    if (s.identity.crossdeckCustomerId) {
+      return { customerId: s.identity.crossdeckCustomerId };
+    }
+    if (s.developerUserId) return { userId: s.developerUserId };
+    return { anonymousId: s.identity.anonymousId };
+  }
+  /** Pick the right identity hint to embed on a queued event. */
+  identityHintForEvent() {
+    const s = this.requireStarted();
+    if (s.identity.crossdeckCustomerId) {
+      return { crossdeckCustomerId: s.identity.crossdeckCustomerId };
+    }
+    if (s.developerUserId) return { developerUserId: s.developerUserId };
+    return { anonymousId: s.identity.anonymousId };
+  }
+  mintEventId() {
+    const ts = Date.now().toString(36);
+    return `evt_${ts}${randomChars(8)}`;
+  }
+};
+var Crossdeck = new CrossdeckClient();
+export {
+  Crossdeck,
+  CrossdeckClient,
+  CrossdeckError,
+  DEFAULT_BASE_URL,
+  MemoryStorage,
+  SDK_NAME,
+  SDK_VERSION
+};
+//# sourceMappingURL=index.mjs.map