@snowcone-app/sdk 0.1.14 → 0.2.0

package/dist/index.js

@@ -2,8 +2,9 @@ import {
   createDevFetcher
 } from "./chunk-7VO4EL2V.js";
 import {
+  REALTIME_WS_URL,
   RealtimeMockupService
-} from "./chunk-6MV7TDTM.js";
+} from "./chunk-D5ZRGKA5.js";
 
 // src/validation.ts
 import { z } from "zod";
@@ -4648,6 +4649,198 @@ function createSvelteComponent(descriptor, svelte) {
   };
 }
 
+// src/realtime/grant.ts
+var DEFAULT_GRANT_BASE = "https://api.snowcone.app";
+async function mintRealtimeGrant(opts) {
+  const f = opts.fetch ?? globalThis.fetch;
+  const res = await f(`${opts.base ?? DEFAULT_GRANT_BASE}/realtime/grant`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${opts.apiKey}`
+    },
+    body: JSON.stringify({ shop: opts.shop })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`realtime grant failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  return await res.json();
+}
+async function fetchRealtimeGrant(grantUrl, shop, fetchImpl) {
+  const f = fetchImpl ?? globalThis.fetch;
+  const res = await f(grantUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ shop })
+  });
+  if (!res.ok) throw new Error(`realtime grant failed: ${res.status}`);
+  return await res.json();
+}
+
+// src/realtime/session.ts
+var RenderSession = class {
+  svc;
+  opts;
+  product;
+  mockupCb = null;
+  errorCb = null;
+  ready = null;
+  constructor(opts) {
+    if (!opts.shop) throw new Error("RenderSession: `shop` is required");
+    if (!opts.getToken && !opts.grantUrl) {
+      throw new Error("RenderSession: provide `grantUrl` or `getToken` to authorize the session");
+    }
+    this.opts = opts;
+    this.product = opts.product ?? null;
+    this.svc = new RealtimeMockupService(opts.wsUrl ?? REALTIME_WS_URL);
+    const getToken = opts.getToken ?? (() => fetchRealtimeGrant(opts.grantUrl, opts.shop, opts.fetch));
+    this.svc.setTokenProvider(getToken);
+  }
+  /** Register a callback fired whenever rendered mockup URLs update. */
+  onMockups(cb) {
+    this.mockupCb = cb;
+    return this;
+  }
+  /** Register an error callback (server/transport errors). */
+  onError(cb) {
+    this.errorCb = cb;
+    return this;
+  }
+  /** Set or update the product. Sends config immediately if already connected. */
+  setProduct(product) {
+    this.product = product;
+    this.svc.sendConfig(this.toConfig(product));
+  }
+  /**
+   * Connect, authorize, and configure. Resolves once the session is ready to
+   * accept {@link RenderSession.renderState}. Idempotent.
+   */
+  connect() {
+    if (this.ready) return this.ready;
+    if (!this.product) {
+      return Promise.reject(
+        new Error("RenderSession: set a product (via options.product or setProduct) before connect()")
+      );
+    }
+    const product = this.product;
+    this.ready = new Promise((resolve, reject) => {
+      let settled = false;
+      this.svc.setCallbacks({
+        onConnected: () => {
+          this.svc.sendConfig(this.toConfig(product));
+        },
+        onConfigReceived: () => {
+          if (!settled) {
+            settled = true;
+            resolve();
+          }
+        },
+        onMockupRendered: () => {
+          this.mockupCb?.(this.svc.getState().mockupResults);
+        },
+        onAllMockupsRendered: (results) => {
+          this.mockupCb?.(results);
+        },
+        onError: (error) => {
+          this.errorCb?.(error);
+          if (!settled) {
+            settled = true;
+            reject(new Error(error));
+          }
+        }
+      });
+      this.svc.sendConfig(this.toConfig(product));
+      this.svc.connect();
+    });
+    return this.ready;
+  }
+  /**
+   * Render a canvas state for a placement. The server rasterizes it and fetches
+   * the assets referenced inside — no pixels are uploaded. Results arrive via
+   * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
+   * canvas edit); pass `throttleMs` to debounce during live dragging.
+   *
+   * `placement` is the print-area NAME (e.g. `'Front'`, the product's
+   * `placements[].label`) — a different id from the product's `mockupIds`, and it
+   * must match an artboard in `state`. The server renders only once it has a state
+   * for EVERY required placement, so on a multi-placement product call this once
+   * per placement; a missing one surfaces as an `incomplete_canvas_placements`
+   * error on {@link RenderSession.onError}.
+   *
+   * `state` is the flattened `serializeStateForServer()` shape — NOT the
+   * un-flattened shape `createDesignState` takes.
+   */
+  async renderState(placement, state, throttleMs = 0) {
+    await this.connect();
+    this.svc.sendCanvasState(placement, state, this.product?.mockupIds.length ?? 1, throttleMs);
+  }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). The server resolves
+   * the `stateId`, fetches the referenced assets, and renders — no pixels are
+   * uploaded and you don't need to hold the canvas JSON. Ideal for re-rendering
+   * a stored design (fulfillment, agents, server-to-server). Results arrive via
+   * {@link RenderSession.onMockups}.
+   */
+  async renderSavedState(placement, stateId) {
+    await this.connect();
+    this.svc.sendCanvasStateRef(placement, stateId);
+  }
+  /** Update only the mockup ids to render (reuses the current state). */
+  updateMockupIds(mockupIds) {
+    if (this.product) this.product = { ...this.product, mockupIds };
+    this.svc.updateMockupIds(mockupIds);
+  }
+  /** Current rendered results. */
+  getMockups() {
+    return this.svc.getState().mockupResults;
+  }
+  /** Close the WebSocket and stop auto-renew. */
+  close() {
+    this.svc.disconnect();
+    this.ready = null;
+  }
+  /** Escape hatch: the underlying low-level service. */
+  get service() {
+    return this.svc;
+  }
+  toConfig(product) {
+    return {
+      productId: product.productId,
+      mockupIds: product.mockupIds,
+      // shop comes from the grant token server-side; sent for completeness.
+      shop: this.opts.shop,
+      // WebSocketConfig requires these; the server treats empty variant as "none".
+      variantId: product.variantId ?? "",
+      width: product.width ?? 1e3,
+      ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
+    };
+  }
+};
+
+// src/realtime/design-state.ts
+var TRANSPARENT_1X1_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
+async function createDesignState(input) {
+  const f = input.fetch ?? globalThis.fetch;
+  const res = await f(`${input.base ?? DEFAULT_GRANT_BASE}/snowcone/design-states`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      productId: input.productId,
+      stateJson: JSON.stringify(input.state),
+      previewBase64: input.previewBase64 ?? TRANSPARENT_1X1_PNG
+    })
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`createDesignState failed: ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  const body = await res.json();
+  const ds = body?.designState;
+  if (!ds?.id) throw new Error("createDesignState: response missing designState.id");
+  return { stateId: ds.id, stateUrl: ds.stateUrl ?? "", previewUrl: ds.previewUrl ?? "" };
+}
+
 // src/index.ts
 function getFetcher(config) {
   return config?.fetcher || globalThis.fetch.bind(globalThis);
@@ -4734,6 +4927,7 @@ export {
   DEFAULT_ARTWORK_URL,
   DEFAULT_ASPECT_RATIO,
   DEFAULT_COLOR,
+  DEFAULT_GRANT_BASE,
   DEFAULT_MOCKUP_BASE,
   DEFAULT_PLACEMENT_DIMENSIONS,
   Elements,
@@ -4747,7 +4941,9 @@ export {
   ProductLoader,
   ProductProps,
   PropertyManager,
+  REALTIME_WS_URL,
   RealtimeMockupService,
+  RenderSession,
   StandardComponents,
   StandardEvents,
   StateManager,
@@ -4769,6 +4965,7 @@ export {
   createComponent,
   createContextProvider,
   createDesignForPlacements,
+  createDesignState,
   createDevFetcher,
   createErrorHandler,
   createEventManager,
@@ -4791,6 +4988,7 @@ export {
   describeProductPrice,
   describeProductTitle,
   extractProductId,
+  fetchRealtimeGrant,
   filterImagePlacements,
   findBestCombination,
   findClosestSnapPoint,
@@ -4814,6 +5012,7 @@ export {
   isValidAlignment,
   isValidTileCount,
   listProducts,
+  mintRealtimeGrant,
   mockupUrl,
   normalizeChoice,
   prepareOptionRenderData,

package/dist/react.cjs

@@ -30,9 +30,12 @@ module.exports = __toCommonJS(react_exports);
 // src/realtime/react.ts
 var import_react = require("react");
 
+// src/realtime/constants.ts
+var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
+
 // src/realtime/websocket.ts
 var RealtimeMockupService = class {
-  constructor(wsUrl = "wss://WS_URL_NOT_CONFIGURED.invalid/realtime") {
+  constructor(wsUrl = REALTIME_WS_URL) {
     this.wsUrl = wsUrl;
   }
   ws = null;
@@ -501,6 +504,32 @@ var RealtimeMockupService = class {
     }
     return true;
   }
+  /**
+   * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+   * instead of inline state; the server resolves it, fetches the referenced
+   * assets, and renders — nothing is uploaded and the client need not hold the
+   * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+   */
+  sendCanvasStateRef(placement, stateId) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
+      const reason = !this.ws ? "no WebSocket" : this.ws.readyState !== WebSocket.OPEN ? `ws.readyState=${this.ws.readyState}` : "not configured";
+      console.log(`[WS] sendCanvasStateRef BLOCKED for "${placement}": ${reason}`);
+      return false;
+    }
+    this.lastSentVersion = ++this.requestVersion;
+    this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const message = JSON.stringify({
+      type: "canvas_state",
+      placement,
+      version: this.lastSentVersion,
+      stateId
+    });
+    this.ws.send(message);
+    this.lastBlobSentAt = Date.now();
+    this.addLog(`Sent canvas stateId "${stateId}" for "${placement}" (v${this.lastSentVersion})`, "sent");
+    this.callbacks.onBlobSent?.(placement);
+    return true;
+  }
   sendCanvasStateImmediately(placement, state) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
       console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);

package/dist/react.d.cts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, u as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Dum3OooZ.cjs';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Poy8LZNA.cjs';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.d.ts

@@ -1,4 +1,4 @@
-import { M as MockupResult, W as WebSocketConfig, u as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Dum3OooZ.js';
+import { M as MockupResult, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-Poy8LZNA.js';
 
 interface UseRealtimeMockupOptions {
     wsUrl?: string;

package/dist/react.js

@@ -1,6 +1,6 @@
 import {
   RealtimeMockupService
-} from "./chunk-6MV7TDTM.js";
+} from "./chunk-D5ZRGKA5.js";
 
 // src/realtime/react.ts
 import { useCallback, useEffect, useRef, useState } from "react";

package/dist/{websocket-Dum3OooZ.d.cts → websocket-Poy8LZNA.d.cts}

@@ -356,6 +356,13 @@ declare class RealtimeMockupService {
      * Alternative to sendCanvasBlob — the server renders the PNG instead of the client.
      */
     sendCanvasState(placement: string, state: object, mockupCount?: number, baseThrottleMs?: number): boolean;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+     * instead of inline state; the server resolves it, fetches the referenced
+     * assets, and renders — nothing is uploaded and the client need not hold the
+     * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+     */
+    sendCanvasStateRef(placement: string, stateId: string): boolean;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**
@@ -385,4 +392,4 @@ declare class RealtimeMockupService {
     clearMockups(): void;
 }
 
-export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RealtimeMockupCallbacks as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type RealtimeMockupState as i, type RenderResult as j, type WebSocketMessage as k, adapterRegistry as l, computeDisabledChoices as m, createComponent as n, defineComponent as o, deriveDefaultSelection as p, findBestCombination as q, getPricePreview as r, isOptionAvailable as s, resolveBestCombination as t, type PlacementSettings as u };
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };

package/dist/{websocket-Dum3OooZ.d.ts → websocket-Poy8LZNA.d.ts}

@@ -356,6 +356,13 @@ declare class RealtimeMockupService {
      * Alternative to sendCanvasBlob — the server renders the PNG instead of the client.
      */
     sendCanvasState(placement: string, state: object, mockupCount?: number, baseThrottleMs?: number): boolean;
+    /**
+     * Render a SAVED canvas by reference (ADR-0079 Phase 4). Sends a `stateId`
+     * instead of inline state; the server resolves it, fetches the referenced
+     * assets, and renders — nothing is uploaded and the client need not hold the
+     * canvas JSON. One-shot (no throttle). Results arrive like any other render.
+     */
+    sendCanvasStateRef(placement: string, stateId: string): boolean;
     private sendCanvasStateImmediately;
     private sendBlobImmediately;
     /**
@@ -385,4 +392,4 @@ declare class RealtimeMockupService {
     clearMockups(): void;
 }
 
-export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RealtimeMockupCallbacks as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type RealtimeMockupState as i, type RenderResult as j, type WebSocketMessage as k, adapterRegistry as l, computeDisabledChoices as m, createComponent as n, defineComponent as o, deriveDefaultSelection as p, findBestCombination as q, getPricePreview as r, isOptionAvailable as s, resolveBestCombination as t, type PlacementSettings as u };
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snowcone-app/sdk",
-  "version": "0.1.14",
-  "description": "Merch Javascript SDK for product mockups and print-on-demand",
+  "version": "0.2.0",
+  "description": "Snowcone SDK for product mockups and print-on-demand",
   "keywords": [
     "merch",
     "mockup",
@@ -14,10 +14,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/snowcone-app/ui-components.git",
+    "url": "https://github.com/snowcone-app/snowcone-monorepo.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://snowcone.app",
+  "bugs": {
+    "url": "https://github.com/snowcone-app/snowcone-monorepo/issues"
+  },
+  "homepage": "https://developers.snowcone.app/sdk",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",