@snowcone-app/sdk 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

package/dist/index.cjs

@@ -5511,6 +5511,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -5518,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) {
@@ -5525,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);
@@ -5569,9 +5573,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -5606,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
@@ -5617,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) {
@@ -5629,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

@@ -2627,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;
@@ -2635,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;
@@ -2678,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

@@ -2627,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;
@@ -2635,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;
@@ -2678,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

@@ -4678,6 +4678,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -4685,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) {
@@ -4692,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);
@@ -4736,9 +4740,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -4773,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
@@ -4784,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) {
@@ -4796,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.1",
+  "version": "0.2.2",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",