@snowcone-app/sdk 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.3.1
+
+### Patch Changes
+
+- [#258](https://github.com/snowcone-app/snowcone-monorepo/pull/258) [`a6d53d8`](https://github.com/snowcone-app/snowcone-monorepo/commit/a6d53d82a18d6dbbb55be4525637cd8372aed760) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Move `zod` from `peerDependencies` to `dependencies`. The SDK uses zod internally (to validate catalog responses) and never asks the consumer to supply a zod schema across the API boundary, so it should bring its own zod rather than demand one as a peer. This removes the unmet-peer warning consumers saw on npm (which is on zod 4 while the SDK targets zod 3).
+
+## 0.3.0
+
+### Minor Changes
+
+- [#256](https://github.com/snowcone-app/snowcone-monorepo/pull/256) [`49f18e2`](https://github.com/snowcone-app/snowcone-monorepo/commit/49f18e221b49422e88f6aa6a06a1de153f170ff3) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Surface the renderer's required-placement contract on `getProduct()`. The catalog
+  product now carries a `requiredPlacements` array — `{ label, key?, type: "image" |
+"color", autoFilledByVariant }` — so a developer can read exactly which placements
+  `renderState` will demand (and which are auto-filled from `variantId`) instead of
+  reverse-engineering it from a runtime timeout error. Image placements also no longer
+  report `type: null`; they default to `"image"`.
+
+## 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

@@ -217,6 +217,18 @@ var CatalogProductSchema = import_zod.z.object({
       offsetY: import_zod.z.number().optional()
     })
   ).optional(),
+  // The renderer's required-placement contract, surfaced by the catalog so a
+  // dev reads exactly which placements renderState will demand. Image
+  // placements + variant-auto-filled color placements. Optional — older catalog
+  // docs predate it.
+  requiredPlacements: import_zod.z.array(
+    import_zod.z.object({
+      label: import_zod.z.string(),
+      key: import_zod.z.string().optional(),
+      type: import_zod.z.enum(["image", "color"]),
+      autoFilledByVariant: import_zod.z.boolean()
+    })
+  ).optional(),
   defaultGvid: import_zod.z.string().optional()
 });
 
@@ -5511,6 +5523,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -5518,6 +5531,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 +5540,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 +5585,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -5606,6 +5624,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 +5636,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 +5649,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

@@ -80,6 +80,21 @@ interface CatalogProduct$2 {
         offsetX?: number;
         offsetY?: number;
     }[];
+    /**
+     * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
+     */
+    requiredPlacements?: {
+        label: string;
+        /**
+         * URL-safe slug derived from `label`. Present for image placements.
+         */
+        key?: string;
+        type: 'image' | 'color';
+        /**
+         * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
+         */
+        autoFilledByVariant: boolean;
+    }[];
     defaultGvid?: string | null;
 }
 
@@ -2627,6 +2642,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 +2667,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 +2712,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

@@ -80,6 +80,21 @@ interface CatalogProduct$2 {
         offsetX?: number;
         offsetY?: number;
     }[];
+    /**
+     * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
+     */
+    requiredPlacements?: {
+        label: string;
+        /**
+         * URL-safe slug derived from `label`. Present for image placements.
+         */
+        key?: string;
+        type: 'image' | 'color';
+        /**
+         * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
+         */
+        autoFilledByVariant: boolean;
+    }[];
     defaultGvid?: string | null;
 }
 
@@ -2627,6 +2642,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 +2667,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 +2712,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

@@ -72,6 +72,18 @@ var CatalogProductSchema = z.object({
       offsetY: z.number().optional()
     })
   ).optional(),
+  // The renderer's required-placement contract, surfaced by the catalog so a
+  // dev reads exactly which placements renderState will demand. Image
+  // placements + variant-auto-filled color placements. Optional — older catalog
+  // docs predate it.
+  requiredPlacements: z.array(
+    z.object({
+      label: z.string(),
+      key: z.string().optional(),
+      type: z.enum(["image", "color"]),
+      autoFilledByVariant: z.boolean()
+    })
+  ).optional(),
   defaultGvid: z.string().optional()
 });
 
@@ -4678,6 +4690,7 @@ async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
 }
 
 // src/realtime/session.ts
+var DEFAULT_RENDER_TIMEOUT_MS = 3e4;
 var RenderSession = class {
   svc;
   opts;
@@ -4685,6 +4698,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 +4707,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 +4752,11 @@ var RenderSession = class {
           }
         },
         onMockupRendered: () => {
+          this.clearWatchdog();
           this.mockupCb?.(this.svc.getState().mockupResults);
         },
         onAllMockupsRendered: (results) => {
+          this.clearWatchdog();
           this.mockupCb?.(results);
         },
         onError: (error) => {
@@ -4773,6 +4791,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 +4803,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 +4816,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.3.1",
   "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",
@@ -56,7 +56,6 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "zod": "^3.0.0",
     "react": "^18 || ^19"
   },
   "peerDependenciesMeta": {
@@ -64,14 +63,15 @@
       "optional": true
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
   "devDependencies": {
     "@types/node": "^20.11.0",
     "@types/react": "^18.3.0",
     "tsup": "^8.1.0",
     "typescript": "^5.5.4",
     "vitest": "^2.0.5",
-    "zod": "^3.23.8",
     "@snowcone-app/mockup-url": "0.1.0"
   },
   "engines": {