@snowcone-app/sdk 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.2
+
+### Patch Changes
+
+- [#239](https://github.com/snowcone-app/snowcone-monorepo/pull/239) [`0556a8f`](https://github.com/snowcone-app/snowcone-monorepo/commit/0556a8f1fbef862dadc50463657fb716517b3264) Thanks [@kevinsproles](https://github.com/kevinsproles)! - fix(realtime): `RenderSession` now surfaces a render timeout via `onError`
+
+  A render that produces no mockup used to hang forever with no signal — the
+  classic trigger is a product with a color/variant axis where `variantId` is
+  omitted, so the server waits for a color blob that never arrives and never
+  errors. `RenderSession` now arms a per-render watchdog: if no mockup arrives in
+  time it reports an actionable timeout (with the `variantId` hint) through the
+  same `onError` channel as other errors, instead of silently hanging.
+
+  Configurable via the new `renderTimeoutMs` option (default `30000`; set to `0`
+  to disable). A successful mockup cancels the watchdog, each new render re-arms
+  it, and `close()` clears any pending timer. `renderState` still resolves on
+  send — the watchdog is a side-channel and throttle behavior is unchanged.
+
+## 0.2.1
+
+### Patch Changes
+
+- [#233](https://github.com/snowcone-app/snowcone-monorepo/pull/233) [`8b08283`](https://github.com/snowcone-app/snowcone-monorepo/commit/8b0828340ea0d2852655bffe8436f0cb71bde3aa) Thanks [@kevinsproles](https://github.com/kevinsproles)! - fix(realtime): `mintRealtimeGrant` now honors the keyless publishable path
+
+  Omitting `apiKey` (or passing `undefined`/`null`/`''`) no longer sends a
+  broken `Authorization: Bearer undefined` header that 401s. The header is now
+  sent only when a key is actually provided, so `mintRealtimeGrant({ shop })`
+  uses the publishable shop-id path exactly as documented. `apiKey` is now typed
+  as optional.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -5486,12 +5486,11 @@ ${versionToSend}
 var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
 async function mintRealtimeGrant(opts) {
   const f = opts.fetch ?? globalThis.fetch;
+  const headers = { "Content-Type": "application/json" };
+  if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
   const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${opts.apiKey}`
-    },
+    headers,
     body: JSON.stringify({ shop: opts.shop })
   });
   if (!res.ok) {
@@ -5512,6 +5511,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -5519,6 +5519,8 @@ var RenderSession = class {
   mockupCb = null;
   errorCb = null;
   ready = null;
+  renderTimeoutMs;
+  watchdog = null;
   constructor(opts) {
     if (!opts.shop) throw new Error("RenderSession: `shop` is required");
     if (!opts.getToken && !opts.grantUrl) {
@@ -5526,6 +5528,7 @@ var RenderSession = class {
     }
     this.opts = opts;
     this.product = opts.product ?? null;
+    this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
     this.svc = new RealtimeMockupService(opts.wsUrl ?? REALTIME_WS_URL);
     const getToken = opts.getToken ?? (() => fetchRealtimeGrant(opts.grantUrl, opts.shop, opts.fetch));
     this.svc.setTokenProvider(getToken);
@@ -5570,9 +5573,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -5607,6 +5612,7 @@ var RenderSession = class {
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
+    this.armWatchdog();
   }
   /**
    * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
@@ -5618,6 +5624,7 @@ var RenderSession = class {
   async renderSavedState(placement, stateId) {
     await this.connect();
     this.svc.sendCanvasStateRef(placement, stateId);
+    this.armWatchdog();
   }
   /** Update only the mockup ids to render (reuses the current state). */
   updateMockupIds(mockupIds) {
@@ -5630,9 +5637,33 @@ var RenderSession = class {
   }
   /** Close the WebSocket and stop auto-renew. */
   close() {
+    this.clearWatchdog();
     this.svc.disconnect();
     this.ready = null;
   }
+  /**
+   * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
+   * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
+   * arrives, it surfaces a timeout via the error callback — the same channel as
+   * server/transport errors — with a hint at the most common cause.
+   */
+  armWatchdog() {
+    this.clearWatchdog();
+    if (this.renderTimeoutMs <= 0) return;
+    this.watchdog = setTimeout(() => {
+      this.watchdog = null;
+      this.errorCb?.(
+        `realtime render timed out after ${this.renderTimeoutMs}ms with no mockup \u2014 a product with a color/variant axis needs \`variantId\` in the product config (see RenderProduct.variantId)`
+      );
+    }, this.renderTimeoutMs);
+  }
+  /** Cancel the pending render watchdog, if any. */
+  clearWatchdog() {
+    if (this.watchdog) {
+      clearTimeout(this.watchdog);
+      this.watchdog = null;
+    }
+  }
   /** Escape hatch: the underlying low-level service. */
   get service() {
     return this.svc;

package/dist/index.d.cts

@@ -2518,14 +2518,26 @@ declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
  * own the target `shop`. Returns a 60s grant your browser code opens the WS
  * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
  *
+ * Omit `apiKey` (or pass `undefined`/`null`/`''`) to use the **keyless
+ * publishable path**: no `Authorization` header is sent and the grant is
+ * authorized by the publishable `shop` id alone. Passing a key uses the
+ * secret (sk_) path.
+ *
  * @example
  * // your backend route: POST /api/realtime/grant
  * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
  * return Response.json(grant);
+ *
+ * @example
+ * // keyless publishable path — quick trials, no API key:
+ * const grant = await mintRealtimeGrant({ shop });
  */
 declare function mintRealtimeGrant(opts: {
-    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
-    apiKey: string;
+    /**
+     * Secret API key (sk_) with the `mockups:realtime` or `mockups` scope.
+     * Omit (or pass `undefined`/`null`/`''`) for the keyless publishable path.
+     */
+    apiKey?: string | null;
     /** Target shop id (= shop.id). Must belong to the key's organization. */
     shop: string;
     /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
@@ -2615,6 +2627,23 @@ interface RenderSessionOptions {
     getToken?: () => Promise<RealtimeGrant>;
     /** Override fetch (used with `grantUrl`). */
     fetch?: typeof fetch;
+    /**
+     * Watchdog for silent render hangs. After a render is dispatched (via
+     * {@link RenderSession.renderState} or {@link RenderSession.renderSavedState}),
+     * if NO mockup arrives within this many milliseconds the session surfaces a
+     * timeout through {@link RenderSession.onError} — turning an otherwise-silent
+     * infinite hang into an actionable error.
+     *
+     * The classic trigger is a product with a color/variant axis where
+     * {@link RenderProduct.variantId} is omitted: the server waits for a color
+     * blob that never arrives, so it neither renders nor errors. The watchdog
+     * makes that visible.
+     *
+     * Defaults to `30000` (30s). A value of `0` (or negative) DISABLES the
+     * watchdog entirely. A successful mockup always cancels the pending watchdog,
+     * and each new render re-arms it.
+     */
+    renderTimeoutMs?: number;
 }
 declare class RenderSession {
     private readonly svc;
@@ -2623,6 +2652,8 @@ declare class RenderSession {
     private mockupCb;
     private errorCb;
     private ready;
+    private readonly renderTimeoutMs;
+    private watchdog;
     constructor(opts: RenderSessionOptions);
     /** Register a callback fired whenever rendered mockup URLs update. */
     onMockups(cb: (results: MockupResult[]) => void): this;
@@ -2666,6 +2697,15 @@ declare class RenderSession {
     getMockups(): MockupResult[];
     /** Close the WebSocket and stop auto-renew. */
     close(): void;
+    /**
+     * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
+     * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
+     * arrives, it surfaces a timeout via the error callback — the same channel as
+     * server/transport errors — with a hint at the most common cause.
+     */
+    private armWatchdog;
+    /** Cancel the pending render watchdog, if any. */
+    private clearWatchdog;
     /** Escape hatch: the underlying low-level service. */
     get service(): RealtimeMockupService;
     private toConfig;

package/dist/index.d.ts

@@ -2518,14 +2518,26 @@ declare const DEFAULT_GRANT_BASE = "https://api.snowcone.app";
  * own the target `shop`. Returns a 60s grant your browser code opens the WS
  * with (hand it down via your own endpoint + {@link fetchRealtimeGrant}).
  *
+ * Omit `apiKey` (or pass `undefined`/`null`/`''`) to use the **keyless
+ * publishable path**: no `Authorization` header is sent and the grant is
+ * authorized by the publishable `shop` id alone. Passing a key uses the
+ * secret (sk_) path.
+ *
  * @example
  * // your backend route: POST /api/realtime/grant
  * const grant = await mintRealtimeGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
  * return Response.json(grant);
+ *
+ * @example
+ * // keyless publishable path — quick trials, no API key:
+ * const grant = await mintRealtimeGrant({ shop });
  */
 declare function mintRealtimeGrant(opts: {
-    /** Secret API key (sk_) with the `mockups:realtime` or `mockups` scope. */
-    apiKey: string;
+    /**
+     * Secret API key (sk_) with the `mockups:realtime` or `mockups` scope.
+     * Omit (or pass `undefined`/`null`/`''`) for the keyless publishable path.
+     */
+    apiKey?: string | null;
     /** Target shop id (= shop.id). Must belong to the key's organization. */
     shop: string;
     /** Backend base URL. Defaults to {@link DEFAULT_GRANT_BASE}. */
@@ -2615,6 +2627,23 @@ interface RenderSessionOptions {
     getToken?: () => Promise<RealtimeGrant>;
     /** Override fetch (used with `grantUrl`). */
     fetch?: typeof fetch;
+    /**
+     * Watchdog for silent render hangs. After a render is dispatched (via
+     * {@link RenderSession.renderState} or {@link RenderSession.renderSavedState}),
+     * if NO mockup arrives within this many milliseconds the session surfaces a
+     * timeout through {@link RenderSession.onError} — turning an otherwise-silent
+     * infinite hang into an actionable error.
+     *
+     * The classic trigger is a product with a color/variant axis where
+     * {@link RenderProduct.variantId} is omitted: the server waits for a color
+     * blob that never arrives, so it neither renders nor errors. The watchdog
+     * makes that visible.
+     *
+     * Defaults to `30000` (30s). A value of `0` (or negative) DISABLES the
+     * watchdog entirely. A successful mockup always cancels the pending watchdog,
+     * and each new render re-arms it.
+     */
+    renderTimeoutMs?: number;
 }
 declare class RenderSession {
     private readonly svc;
@@ -2623,6 +2652,8 @@ declare class RenderSession {
     private mockupCb;
     private errorCb;
     private ready;
+    private readonly renderTimeoutMs;
+    private watchdog;
     constructor(opts: RenderSessionOptions);
     /** Register a callback fired whenever rendered mockup URLs update. */
     onMockups(cb: (results: MockupResult[]) => void): this;
@@ -2666,6 +2697,15 @@ declare class RenderSession {
     getMockups(): MockupResult[];
     /** Close the WebSocket and stop auto-renew. */
     close(): void;
+    /**
+     * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
+     * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
+     * arrives, it surfaces a timeout via the error callback — the same channel as
+     * server/transport errors — with a hint at the most common cause.
+     */
+    private armWatchdog;
+    /** Cancel the pending render watchdog, if any. */
+    private clearWatchdog;
     /** Escape hatch: the underlying low-level service. */
     get service(): RealtimeMockupService;
     private toConfig;

package/dist/index.js

@@ -4653,12 +4653,11 @@ function createSvelteComponent(descriptor, svelte) {
 var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
 async function mintRealtimeGrant(opts) {
   const f = opts.fetch ?? globalThis.fetch;
+  const headers = { "Content-Type": "application/json" };
+  if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
   const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
     method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${opts.apiKey}`
-    },
+    headers,
     body: JSON.stringify({ shop: opts.shop })
   });
   if (!res.ok) {
@@ -4679,6 +4678,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -4686,6 +4686,8 @@ var RenderSession = class {
   mockupCb = null;
   errorCb = null;
   ready = null;
+  renderTimeoutMs;
+  watchdog = null;
   constructor(opts) {
     if (!opts.shop) throw new Error("RenderSession: `shop` is required");
     if (!opts.getToken && !opts.grantUrl) {
@@ -4693,6 +4695,7 @@ var RenderSession = class {
     }
     this.opts = opts;
     this.product = opts.product ?? null;
+    this.renderTimeoutMs = opts.renderTimeoutMs ?? DEFAULT_RENDER_TIMEOUT_MS;
     this.svc = new RealtimeMockupService(opts.wsUrl ?? REALTIME_WS_URL);
     const getToken = opts.getToken ?? (() => fetchRealtimeGrant(opts.grantUrl, opts.shop, opts.fetch));
     this.svc.setTokenProvider(getToken);
@@ -4737,9 +4740,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -4774,6 +4779,7 @@ var RenderSession = class {
   async renderState(placement, state, throttleMs = 0) {
     await this.connect();
     this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
+    this.armWatchdog();
   }
   /**
    * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
@@ -4785,6 +4791,7 @@ var RenderSession = class {
   async renderSavedState(placement, stateId) {
     await this.connect();
     this.svc.sendCanvasStateRef(placement, stateId);
+    this.armWatchdog();
   }
   /** Update only the mockup ids to render (reuses the current state). */
   updateMockupIds(mockupIds) {
@@ -4797,9 +4804,33 @@ var RenderSession = class {
   }
   /** Close the WebSocket and stop auto-renew. */
   close() {
+    this.clearWatchdog();
     this.svc.disconnect();
     this.ready = null;
   }
+  /**
+   * (Re)arm the render watchdog. Clears any prior timer and, unless disabled
+   * (`renderTimeoutMs <= 0`), starts a fresh one. If it fires before a mockup
+   * arrives, it surfaces a timeout via the error callback — the same channel as
+   * server/transport errors — with a hint at the most common cause.
+   */
+  armWatchdog() {
+    this.clearWatchdog();
+    if (this.renderTimeoutMs <= 0) return;
+    this.watchdog = setTimeout(() => {
+      this.watchdog = null;
+      this.errorCb?.(
+        `realtime render timed out after ${this.renderTimeoutMs}ms with no mockup \u2014 a product with a color/variant axis needs \`variantId\` in the product config (see RenderProduct.variantId)`
+      );
+    }, this.renderTimeoutMs);
+  }
+  /** Cancel the pending render watchdog, if any. */
+  clearWatchdog() {
+    if (this.watchdog) {
+      clearTimeout(this.watchdog);
+      this.watchdog = null;
+    }
+  }
   /** Escape hatch: the underlying low-level service. */
   get service() {
     return this.svc;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",