@snowcone-app/sdk 0.1.12 → 0.1.13

package/README.md

@@ -17,50 +17,25 @@ pnpm add @snowcone-app/sdk
 ## Quick Start
 
 ```typescript
-import { getProduct, listProducts, generateMockupUrl } from '@snowcone-app/sdk';
+import { getProduct, listProducts, getMockupUrl } from '@snowcone-app/sdk';
 
-// Fetch a product by ID
-const product = await getProduct('BEEB77');
-console.log(product.name); // "Bella + Canvas 3001 Unisex Jersey Short Sleeve Tee"
-
-// List all products
+// 1. Find a product (public catalog read — no key needed)
 const products = await listProducts({ limit: 10 });
-console.log(`Found ${products.length} products`);
-
-// Generate a mockup URL
-const mockupUrl = generateMockupUrl({
-  productId: 'BEEB77',
-  variantId: 'white-sm',
-  artworkUrl: 'https://example.com/artwork.png',
-  placement: 'Front',
-  alignment: 'center'
-});
-console.log(mockupUrl); // URL to mockup image
-```
-
-## Configuration
-
-Configure the SDK to point to your Merch endpoint:
-
-```typescript
-import { config } from '@snowcone-app/sdk';
-
-config({
-  endpoint: 'https://api.snowcone.app',
-  mockupUrl: 'https://i.snowcone.app',
-  accountId: 'your-account-id',
-  mode: 'live' // or 'mock' for development
+const product = await getProduct('BEEB77'); // by id or slug
+
+// 2. Build a mockup URL. A mockup is a PUBLIC image URL — getMockupUrl is a
+//    pure, synchronous builder (no await, no fetch, no secret). The result
+//    drops straight into an <img>. Code-first: productCode, then options.
+const url = getMockupUrl('hoodie-black', {
+  shop: shop.id,                       // your Shop ID (publishable, = shop.id)
+  asset: 'https://example.com/art.png' // your artwork
 });
+// <img src={url} />
 ```
 
-**Environment Variables (Next.js):**
-```bash
-NEXT_PUBLIC_MERCH_ENDPOINT=https://api.snowcone.app
-NEXT_PUBLIC_MERCH_MOCKUP_URL=https://i.snowcone.app
-NEXT_PUBLIC_MERCH_ACCOUNT_ID=your-account-id
-```
-
-The SDK automatically reads these environment variables if not configured explicitly.
+> The `key` is your **publishable** token — public and safe to expose (like
+> Cloudinary's cloud name). It defaults to your `shop.id`. See the security
+> ladder below if you want to lock things down.
 
 ## Core Functions
 
@@ -97,23 +72,95 @@ const products = await listProducts(options?: {
 }
 ```
 
-### Mockup Generation
+### Mockup URLs
+
+A mockup is a public image URL on `img.snowcone.app`:
+
+```
+https://img.snowcone.app/{productCode}?asset={assetUrl}&key={publishableKey}
+```
+
+You can hand-write it, or use **`getMockupUrl`** — a pure, synchronous,
+isomorphic builder (browser + server, no `await`). It never hand-rolls the query
+string; it delegates to `@snowcone-app/mockup-url`'s `buildPublicMockupUrl`
+(the single source of truth shared byte-for-byte with the edge resolver).
+
+```typescript
+import { getMockupUrl } from '@snowcone-app/sdk';
+
+// Code-first form: productCode, then options.
+const url = getMockupUrl(productCode: string, opts: {
+  shop: string;           // Required: your Shop ID (publishable, = shop.id)
+  asset?: string;         // Single default-placement image (get-started shorthand)
+  design?: Design;        // Multi-placement: { [placementKey]: Fill } — takes precedence over `asset`
+  options?: Record<string, string>; // Variant picks: { size: "m" } → opt.size=m
+  secret?: string;        // Optional: per-shop secret → appends an L3 &signature (server only)
+  base?: string;          // Optional: override the host (default img.snowcone.app)
+  width?: number;         // Optional: display width
+  view?: string;          // Optional: camera view / mockup scene (alias: `mockup`)
+  variant?: string;       // Optional: specific resolved variant (gvid)
+  placement?: string;     // Optional: specific print area (single-asset only)
+  aspect?: '16:9' | '2:3';// Optional: canvas aspect ratio
+}): string;
+```
+
+`Fill` (re-exported from the SDK) is what fills one placement:
 
 ```typescript
-import { generateMockupUrl } from '@snowcone-app/sdk';
-
-const url = generateMockupUrl({
-  productId: string;          // Required: Product ID
-  variantId?: string;         // Optional: Specific variant (color/size)
-  artworkUrl: string;         // Required: URL to artwork image
-  placement?: string;         // Optional: Print area (default: 'Front')
-  alignment?: ImageAlignment; // Optional: How to position artwork
-  mode?: 'mock' | 'live';     // Optional: Mock or live rendering
+type Fill =
+  | string                                       // image URL (shorthand for { src })
+  | { src: string; align?: ImageAlignment; tile?: 0.25 | 0.5 | 1 | 2 | 4 }
+  | { color: string };                           // a color placement (e.g. a cap's Crown)
+type Design = Record<string, Fill>;              // placement key → fill
+```
+
+#### Multi-placement + variant options
+
+```typescript
+// A front + back tee, size M.
+const url = getMockupUrl('KMYKUK', {
+  shop: shop.id,
+  options: { size: 'm' },
+  design: {
+    front: 'https://cdn.example.com/front.png',
+    back: { src: 'https://cdn.example.com/back.png', tile: 2, align: 'top' },
+  },
+});
+// → …/KMYKUK?shop=…&asset.back=…&tile.back=2&align.back=top&asset.front=…&opt.size=m
+
+// A cap with a printed front + chosen Crown/Strap colors (color placements).
+const cap = getMockupUrl('RQNU68', {
+  shop: shop.id,
+  design: { front: 'https://cdn.example.com/logo.png', crown: { color: '#001f3f' } },
 });
+// → …/RQNU68?shop=…&color.crown=%23001f3f&asset.front=…
+```
+
+> A **legacy positional form** `getMockupUrl(assetUrl, productCode, opts)` is also
+> accepted (it builds the same URL as `getMockupUrl(productCode, { asset, … })`).
+> Prefer the code-first form above for new code.
+
+### Security ladder
+
+The default is open and frictionless; climb only as far as you need:
 
-// ImageAlignment options:
-// 'center' | 'top' | 'bottom' | 'left' | 'right' |
-// 'far-left' | 'far-right' | 'far-top' | 'far-bottom'
+| Level | Control | Effect |
+|---|---|---|
+| **L0** (default) | none | public token, any domain, any asset |
+| **L1** | domain allowlist | token only renders from your domains |
+| **L2** | asset allowlist | restrict which asset sources composite |
+| **L3** | signed URLs | URL must carry a valid `&s` (HMAC of a per-shop secret) |
+
+For **L3**, pass `secret` (server-side only) and `getMockupUrl` appends the
+verified `&signature`:
+
+```typescript
+// On your server/BFF — the secret never ships to the browser.
+const url = getMockupUrl('hoodie-black', {
+  shop: shop.id,
+  asset: assetUrl,
+  secret: process.env.SNOWCONE_SHOP_SECRET,
+});
 ```
 
 ### React Hooks (Optional)
@@ -148,17 +195,6 @@ import type {
 } from '@snowcone-app/sdk';
 ```
 
-## Development Mode
-
-Use mock mode for development without API calls:
-
-```typescript
-config({ mode: 'mock' });
-
-// Returns mock product data
-const product = await getProduct('BEEB77');
-```
-
 ## API Reference
 
 See full API documentation at: [https://developers.snowcone.app/sdk](https://developers.snowcone.app/sdk)

package/dist/{chunk-UJFJ7REN.js → chunk-6MV7TDTM.js}

@@ -13,7 +13,9 @@ var RealtimeMockupService = class {
   logs = [];
   lastError = null;
   callbacks = {};
+  lastBlobSentAt = 0;
   canvasBlobs = /* @__PURE__ */ new Map();
+  canvasStates = /* @__PURE__ */ new Map();
   colors = /* @__PURE__ */ new Map();
   lastSendTime = {};
   throttleTimeouts = {};
@@ -23,11 +25,24 @@ var RealtimeMockupService = class {
   lastSentVersion = 0;
   // Track latest sent version per placement to detect stale responses
   latestSentVersionByPlacement = {};
+  // Track latest accepted (displayed) version per placement — only drop results
+  // older than what we've already shown, not older than what we've sent.
+  // This prevents the "version racing" problem during drag where sent versions
+  // advance faster than the server can render.
+  latestAcceptedVersionByPlacement = {};
   // Feature flag: server now supports version in blob message
   sendVersionInBlob = true;
+  // Session-grant auth: when set, connect() fetches a short-lived token, opens
+  // the WS with `?token=`, and renews ~15s before expiry via a `renew` message.
+  tokenProvider;
+  renewTimer = null;
   setCallbacks(callbacks) {
     this.callbacks = callbacks;
   }
+  /** Provide a grant fetcher to authorize the session (per-shop, renewable). */
+  setTokenProvider(fn) {
+    this.tokenProvider = fn;
+  }
   getState() {
     return {
       isConnected: this.ws?.readyState === WebSocket.OPEN,
@@ -50,9 +65,24 @@ var RealtimeMockupService = class {
     if (this.ws?.readyState === WebSocket.OPEN) {
       return;
     }
+    if (this.tokenProvider) {
+      this.tokenProvider().then((grant) => {
+        this.openSocket(grant.token);
+        this.scheduleRenew(grant.expiresAt);
+      }).catch((err) => {
+        this.addLog(`Failed to obtain realtime grant: ${err}`);
+        this.status = "Disconnected";
+      });
+      return;
+    }
+    this.openSocket();
+  }
+  openSocket(token) {
+    const url = token ? `${this.wsUrl}${this.wsUrl.includes("?") ? "&" : "?"}token=${encodeURIComponent(token)}` : this.wsUrl;
     this.addLog(`Connecting to ${this.wsUrl}...`);
-    this.ws = new WebSocket(this.wsUrl);
+    this.ws = new WebSocket(url);
     this.ws.onopen = () => {
+      console.log(`[WS] connection OPENED to ${this.wsUrl}`);
       this.addLog("WebSocket connection opened");
       this.status = "Connected";
     };
@@ -66,11 +96,13 @@ var RealtimeMockupService = class {
       }
     };
     this.ws.onclose = (event) => {
+      console.log(`[WS] connection CLOSED (code: ${event.code}, reason: "${event.reason}", wasClean: ${event.wasClean})`);
       this.addLog(`WebSocket connection closed (code: ${event.code})`);
       this.status = "Disconnected";
       this.sessionId = null;
       this.isConfigured = false;
       this.configSent = false;
+      this.clearRenew();
       this.callbacks.onDisconnected?.();
     };
     this.ws.onerror = (error) => {
@@ -78,6 +110,29 @@ var RealtimeMockupService = class {
       this.status = "Disconnected";
     };
   }
+  scheduleRenew(expiresAt) {
+    this.clearRenew();
+    if (!this.tokenProvider) return;
+    const ms = Math.max(1e3, expiresAt * 1e3 - Date.now() - 15e3);
+    this.renewTimer = setTimeout(() => void this.renew(), ms);
+  }
+  clearRenew() {
+    if (this.renewTimer) {
+      clearTimeout(this.renewTimer);
+      this.renewTimer = null;
+    }
+  }
+  async renew() {
+    if (!this.tokenProvider || this.ws?.readyState !== WebSocket.OPEN) return;
+    try {
+      const grant = await this.tokenProvider();
+      this.ws.send(JSON.stringify({ type: "renew", token: grant.token }));
+      this.addLog("\u{1F504} Renewed realtime session token", "sent");
+      this.scheduleRenew(grant.expiresAt);
+    } catch (err) {
+      this.addLog(`Failed to renew realtime grant: ${err}`);
+    }
+  }
   handleMessage(data) {
     switch (data.type) {
       case "connected":
@@ -129,15 +184,18 @@ var RealtimeMockupService = class {
         this.addLog("\u{1F3A8} Mockup rendering has started...");
         break;
       case "mockup_rendered":
+        console.log(`[WS] mockup_rendered received: mockupId=${data.mockupId} hasImageUrl=${!!data.imageUrl} v=${data.requestVersion} placement="${data.placement}" renderMs=${data.renderMs}`);
         if (data.imageUrl && data.mockupId) {
           const responseVersion = data.requestVersion;
           const responsePlacement = data.placement;
           if (responseVersion !== void 0 && responsePlacement) {
-            const latestVersion = this.latestSentVersionByPlacement[responsePlacement];
-            if (latestVersion !== void 0 && responseVersion < latestVersion) {
-              this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (latest sent: v${latestVersion})`);
+            const lastAccepted = this.latestAcceptedVersionByPlacement[responsePlacement];
+            if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
+              console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
+              this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (displayed: v${lastAccepted})`);
               break;
             }
+            this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
           }
           const mockupResult = {
             mockupId: data.mockupId,
@@ -145,7 +203,10 @@ var RealtimeMockupService = class {
             renderUrl: data.renderUrl || data.imageUrl,
             imageSize: data.imageSize || 0,
             requestVersion: responseVersion,
-            placement: responsePlacement
+            placement: responsePlacement,
+            renderMs: data.renderMs,
+            blobToRenderMs: data.blobToRenderMs,
+            canvasRenderTiming: data.canvasRenderTiming
           };
           const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
           if (existingIndex >= 0) {
@@ -164,14 +225,16 @@ var RealtimeMockupService = class {
         }
         break;
       case "all_mockups_rendered":
+        console.log(`[WS] all_mockups_rendered received: ${data.mockups?.length ?? 0} mockups`);
         if (data.mockups) {
           const freshMockups = data.mockups.filter((mockup) => {
             if (mockup.requestVersion !== void 0 && mockup.placement) {
-              const latestVersion = this.latestSentVersionByPlacement[mockup.placement];
-              if (latestVersion !== void 0 && mockup.requestVersion < latestVersion) {
-                this.addLog(`\u23ED\uFE0F Filtering stale mockup v${mockup.requestVersion} for "${mockup.placement}" (latest: v${latestVersion})`);
+              const lastAccepted = this.latestAcceptedVersionByPlacement[mockup.placement];
+              if (lastAccepted !== void 0 && mockup.requestVersion < lastAccepted) {
+                this.addLog(`\u23ED\uFE0F Filtering stale mockup v${mockup.requestVersion} for "${mockup.placement}" (displayed: v${lastAccepted})`);
                 return false;
               }
+              this.latestAcceptedVersionByPlacement[mockup.placement] = mockup.requestVersion;
             }
             return true;
           });
@@ -194,6 +257,7 @@ var RealtimeMockupService = class {
     }
   }
   disconnect() {
+    this.clearRenew();
     if (this.ws) {
       this.ws.close();
       this.ws = null;
@@ -228,6 +292,7 @@ var RealtimeMockupService = class {
         this.isConfigured = false;
         this.mockupResults = [];
         this.canvasBlobs.clear();
+        this.canvasStates.clear();
         this.colors.clear();
         this.lastSendTime = {};
         Object.values(this.throttleTimeouts).forEach((timeout) => clearTimeout(timeout));
@@ -235,6 +300,7 @@ var RealtimeMockupService = class {
         this.requestVersion = 0;
         this.lastSentVersion = 0;
         this.latestSentVersionByPlacement = {};
+        this.latestAcceptedVersionByPlacement = {};
         this.addLog("\u{1F9F9} Cleared all cached canvas/color data for new product");
       }
     }
@@ -270,6 +336,30 @@ var RealtimeMockupService = class {
     this.addLog(`\u{1F3AF} Updating mockupIds to: [${mockupIds.join(", ")}]`);
     return this.sendConfig(updatedConfig);
   }
+  /**
+   * Update render width without changing other config.
+   * Used for low-res preview during rapid edits (e.g., 600 while dragging, 1200 on release).
+   * Preserves blobs since product/variant don't change.
+   */
+  updateWidth(width) {
+    if (!this.config) {
+      this.addLog("Cannot update width: no config set");
+      return false;
+    }
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.addLog("Cannot update width: WebSocket not connected");
+      return false;
+    }
+    if (this.config.width === width) {
+      return false;
+    }
+    const updatedConfig = {
+      ...this.config,
+      width
+    };
+    this.addLog(`\u{1F4D0} Updating render width: ${this.config.width} \u2192 ${width}`);
+    return this.sendConfig(updatedConfig);
+  }
   /**
    * Update placementSettings without changing other config.
    * Used to override scaleMode when canvas editor is active.
@@ -292,6 +382,8 @@ var RealtimeMockupService = class {
   sendCanvasBlob(placement, blob, mockupCount = 1, baseThrottleMs = 1e3, notifyCallback = true) {
     this.canvasBlobs.set(placement, blob);
     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] sendCanvasBlob BLOCKED for "${placement}" (${blob.size}B): ${reason} (cached for later)`);
       return false;
     }
     if (baseThrottleMs <= 0) {
@@ -299,16 +391,25 @@ var RealtimeMockupService = class {
       this.lastSendTime[placement] = Date.now();
       return true;
     }
-    const throttleMs = baseThrottleMs * mockupCount;
-    const now = Date.now();
-    const lastSendTime = this.lastSendTime[placement] || 0;
-    const timeSinceLastSend = now - lastSendTime;
-    const hasNeverSent = lastSendTime === 0;
-    if (hasNeverSent || timeSinceLastSend >= throttleMs) {
-      this.sendBlobImmediately(placement, blob, notifyCallback);
-      this.lastSendTime[placement] = now;
-    } else if (!this.throttleTimeouts[placement]) {
-      const delayTime = throttleMs - timeSinceLastSend;
+    const debounceMs = baseThrottleMs * mockupCount;
+    const lastSendTime = this.lastSendTime[placement];
+    const timeSinceLastSend = lastSendTime ? Date.now() - lastSendTime : 0;
+    const isActiveInteraction = lastSendTime && timeSinceLastSend < debounceMs * 3;
+    if (isActiveInteraction && timeSinceLastSend >= debounceMs) {
+      if (this.throttleTimeouts[placement]) {
+        clearTimeout(this.throttleTimeouts[placement]);
+        delete this.throttleTimeouts[placement];
+      }
+      const latestBlob = this.canvasBlobs.get(placement);
+      if (latestBlob && this.ws?.readyState === WebSocket.OPEN && this.isConfigured) {
+        this.sendBlobImmediately(placement, latestBlob, notifyCallback);
+        this.lastSendTime[placement] = Date.now();
+      }
+    } else {
+      if (this.throttleTimeouts[placement]) {
+        clearTimeout(this.throttleTimeouts[placement]);
+      }
+      const delayTime = isActiveInteraction ? debounceMs - timeSinceLastSend : debounceMs;
       this.throttleTimeouts[placement] = setTimeout(() => {
         const latestBlob = this.canvasBlobs.get(placement);
         if (latestBlob && this.ws?.readyState === WebSocket.OPEN && this.isConfigured) {
@@ -320,6 +421,72 @@ var RealtimeMockupService = class {
     }
     return true;
   }
+  /**
+   * Send canvas state JSON for server-side rendering.
+   * Alternative to sendCanvasBlob — the server renders the PNG instead of the client.
+   */
+  sendCanvasState(placement, state, mockupCount = 1, baseThrottleMs = 1e3) {
+    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] sendCanvasState BLOCKED for "${placement}": ${reason}`);
+      return false;
+    }
+    this.canvasStates.set(placement, state);
+    if (baseThrottleMs <= 0) {
+      this.sendCanvasStateImmediately(placement, state);
+      this.lastSendTime[placement] = Date.now();
+      return true;
+    }
+    const debounceMs = baseThrottleMs * mockupCount;
+    const lastSendTime = this.lastSendTime[placement];
+    const timeSinceLastSend = lastSendTime ? Date.now() - lastSendTime : 0;
+    const isActiveInteraction = lastSendTime && timeSinceLastSend < debounceMs * 3;
+    if (isActiveInteraction && timeSinceLastSend >= debounceMs) {
+      if (this.throttleTimeouts[placement]) {
+        clearTimeout(this.throttleTimeouts[placement]);
+        delete this.throttleTimeouts[placement];
+      }
+      const latestState = this.canvasStates.get(placement);
+      if (latestState && this.ws?.readyState === WebSocket.OPEN && this.isConfigured) {
+        console.log(`[WS] sendCanvasState "${placement}": max-wait flush (${timeSinceLastSend}ms since last)`);
+        this.sendCanvasStateImmediately(placement, latestState);
+        this.lastSendTime[placement] = Date.now();
+      }
+    } else {
+      if (this.throttleTimeouts[placement]) {
+        clearTimeout(this.throttleTimeouts[placement]);
+      }
+      const delayTime = isActiveInteraction ? debounceMs - timeSinceLastSend : debounceMs;
+      this.throttleTimeouts[placement] = setTimeout(() => {
+        const latestState = this.canvasStates.get(placement);
+        if (latestState && this.ws?.readyState === WebSocket.OPEN && this.isConfigured) {
+          console.log(`[WS] sendCanvasState "${placement}": debounce firing (${debounceMs}ms)`);
+          this.sendCanvasStateImmediately(placement, latestState);
+          this.lastSendTime[placement] = Date.now();
+        }
+        delete this.throttleTimeouts[placement];
+      }, delayTime);
+    }
+    return true;
+  }
+  sendCanvasStateImmediately(placement, state) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      console.log(`[WS] sendCanvasStateImmediately ABORTED: ws not open`);
+      return;
+    }
+    this.lastSentVersion = ++this.requestVersion;
+    this.latestSentVersionByPlacement[placement] = this.lastSentVersion;
+    const message = JSON.stringify({
+      type: "canvas_state",
+      placement,
+      version: this.lastSentVersion,
+      state
+    });
+    this.ws.send(message);
+    this.lastBlobSentAt = Date.now();
+    this.addLog(`Sent canvas state for "${placement}" (${(message.length / 1024).toFixed(1)}KB, v${this.lastSentVersion})`, "sent");
+    this.callbacks.onBlobSent?.(placement);
+  }
   sendBlobImmediately(placement, blob, notifyCallback = true) {
     if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
     this.lastSentVersion = ++this.requestVersion;
@@ -345,6 +512,7 @@ ${versionToSend}
           combined.set(imageBytes, headerBytes.length);
         }
         this.ws.send(combined.buffer);
+        this.lastBlobSentAt = Date.now();
         this.addLog(`Sent canvas blob for placement "${placement}" (${imageBytes.length} bytes, v${versionToSend})`, "sent");
         if (notifyCallback) {
           this.callbacks.onBlobSent?.(placement);