@snowcone-app/sdk 0.14.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.15.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#652](https://github.com/snowcone-app/snowcone-monorepo/pull/652) [`3f9175f`](https://github.com/snowcone-app/snowcone-monorepo/commit/3f9175fb1986642c94757f6b0f1b586c196f0ac6) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Render catalog designs by reference (ADR-0086): new `design=<pairingId|slug>` wire param. `getMockupUrl` accepts `designRef`, and the MCP `snowcone_search_designs` tool now returns `design=` reference URLs instead of re-assembling raw asset components. Catalog design renders are free — they never count against the shop's usage budget.
8
+
9
+ ### Patch Changes
10
+
11
+ - [#651](https://github.com/snowcone-app/snowcone-monorepo/pull/651) [`925a52d`](https://github.com/snowcone-app/snowcone-monorepo/commit/925a52dccbe7c094bce5965c8e388c56a62a4e60) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `fetchMockupImage(url)` — fetch a rendered mockup URL and prove it's a real image, absorbing the mint→edge KV propagation lag: bounded ~10s retry on "Unknown shop" for freshly minted shops, then a loud structured throw naming the propagation cause (`SnowconeSdkError` `SHOP_NOT_PROPAGATED`); allowlist denials surface as `ASSET_FORBIDDEN` with the failed assets named, other failures as `RENDER_FAILED` (agent-DX decision F2).
12
+
3
13
  ## 0.14.0
4
14
 
5
15
  ### Minor Changes
@@ -3,6 +3,15 @@ var PARAMS = {
3
3
  shop: "shop",
4
4
  asset: "asset",
5
5
  assets: "assets",
6
+ /**
7
+ * Render a catalog design by reference (ADR-0086): `design=<pairingId|slug>`.
8
+ * The resolver looks the design up in the public `snowcone-designs` index
9
+ * (membership = license) and injects its asset components server-side, so no
10
+ * raw asset URL crosses the wire and no origin allowlisting is involved.
11
+ * Catalog renders are FREE — mutually exclusive with `asset`/`asset.<key>`/
12
+ * `color.<key>` (free = the design as published).
13
+ */
14
+ design: "design",
6
15
  placement: "placement",
7
16
  variant: "variant",
8
17
  mockup: "mockup",
@@ -149,6 +158,8 @@ function buildPublicMockupUrl(options, cfg = {}) {
149
158
  }
150
159
  } else if (options.assetUrl !== void 0) {
151
160
  parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
161
+ } else if (options.designRef !== void 0) {
162
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
152
163
  }
153
164
  if (options.placement !== void 0) {
154
165
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -172,6 +183,7 @@ function buildPublicMockupUrl(options, cfg = {}) {
172
183
  }
173
184
  var PUBLIC_PARAM_NAMES = [
174
185
  PARAMS.asset,
186
+ PARAMS.design,
175
187
  PARAMS.shop,
176
188
  PARAMS.placement,
177
189
  PARAMS.variant,
package/dist/index.cjs CHANGED
@@ -56,6 +56,7 @@ __export(index_exports, {
56
56
  REALTIME_WS_URL: () => REALTIME_WS_URL,
57
57
  RealtimeMockupService: () => RealtimeMockupService,
58
58
  RenderSession: () => RenderSession,
59
+ SnowconeSdkError: () => SnowconeSdkError,
59
60
  StandardComponents: () => StandardComponents,
60
61
  StandardEvents: () => StandardEvents,
61
62
  StateManager: () => StateManager,
@@ -102,6 +103,7 @@ __export(index_exports, {
102
103
  describeProductPrice: () => describeProductPrice,
103
104
  describeProductTitle: () => describeProductTitle,
104
105
  extractProductId: () => extractProductId,
106
+ fetchMockupImage: () => fetchMockupImage,
105
107
  fetchRealtimeGrant: () => fetchRealtimeGrant,
106
108
  filterImagePlacements: () => filterImagePlacements,
107
109
  findBestCombination: () => findBestCombination,
@@ -122,8 +124,10 @@ __export(index_exports, {
122
124
  getSnapPoints: () => getSnapPoints,
123
125
  getVariant: () => getVariant,
124
126
  handleOptionChange: () => handleOptionChange,
127
+ imageKindOf: () => imageKindOf,
125
128
  isOptionAvailable: () => isOptionAvailable,
126
129
  isSelectionComplete: () => isSelectionComplete,
130
+ isSnowconeSdkError: () => isSnowconeSdkError,
127
131
  isValidAlignment: () => isValidAlignment,
128
132
  isValidTileCount: () => isValidTileCount,
129
133
  listProducts: () => listProducts,
@@ -478,6 +482,15 @@ var PARAMS = {
478
482
  shop: "shop",
479
483
  asset: "asset",
480
484
  assets: "assets",
485
+ /**
486
+ * Render a catalog design by reference (ADR-0086): `design=<pairingId|slug>`.
487
+ * The resolver looks the design up in the public `snowcone-designs` index
488
+ * (membership = license) and injects its asset components server-side, so no
489
+ * raw asset URL crosses the wire and no origin allowlisting is involved.
490
+ * Catalog renders are FREE — mutually exclusive with `asset`/`asset.<key>`/
491
+ * `color.<key>` (free = the design as published).
492
+ */
493
+ design: "design",
481
494
  placement: "placement",
482
495
  variant: "variant",
483
496
  mockup: "mockup",
@@ -624,6 +637,8 @@ function buildPublicMockupUrl(options, cfg = {}) {
624
637
  }
625
638
  } else if (options.assetUrl !== void 0) {
626
639
  parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
640
+ } else if (options.designRef !== void 0) {
641
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
627
642
  }
628
643
  if (options.placement !== void 0) {
629
644
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -647,6 +662,7 @@ function buildPublicMockupUrl(options, cfg = {}) {
647
662
  }
648
663
  var PUBLIC_PARAM_NAMES = [
649
664
  PARAMS.asset,
665
+ PARAMS.design,
650
666
  PARAMS.shop,
651
667
  PARAMS.placement,
652
668
  PARAMS.variant,
@@ -919,6 +935,7 @@ function getMockupUrl(a, b, c) {
919
935
  shop: opts.shop,
920
936
  ...opts.design ? { design: opts.design } : {},
921
937
  ...assetUrl !== void 0 ? { assetUrl } : {},
938
+ ...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
922
939
  ...opts.options ? { options: opts.options } : {},
923
940
  ...opts.width !== void 0 ? { width: opts.width } : {},
924
941
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
@@ -2414,6 +2431,109 @@ async function retryOperation(operation, options = {}) {
2414
2431
  throw lastError;
2415
2432
  }
2416
2433
 
2434
+ // src/error/structured.ts
2435
+ var SnowconeSdkError = class extends Error {
2436
+ code;
2437
+ data;
2438
+ constructor(code, message, data = {}) {
2439
+ super(`${code}: ${message}`);
2440
+ this.name = "SnowconeSdkError";
2441
+ this.code = code;
2442
+ this.data = { code, ...data };
2443
+ }
2444
+ };
2445
+ function isSnowconeSdkError(err) {
2446
+ return err instanceof Error && err.name === "SnowconeSdkError" && "code" in err;
2447
+ }
2448
+
2449
+ // src/mockup/fetchMockupImage.ts
2450
+ function imageKindOf(b) {
2451
+ if (b[0] === 137 && b[1] === 80) return "PNG";
2452
+ if (b[0] === 255 && b[1] === 216) return "JPEG";
2453
+ if (b[0] === 71 && b[1] === 73 && b[2] === 70) return "GIF";
2454
+ if (b[0] === 82 && b[1] === 73 && b[2] === 70 && b[3] === 70) return "WebP";
2455
+ if (b.length >= 12 && String.fromCharCode(b[4], b[5], b[6], b[7]) === "ftyp") return "AVIF";
2456
+ return void 0;
2457
+ }
2458
+ var DEFAULT_RETRY_DELAYS_MS = [500, 1e3, 2e3, 2e3, 2e3, 2e3];
2459
+ function parseFailure(status, bytes) {
2460
+ const text = new TextDecoder().decode(bytes).slice(0, 1e3);
2461
+ let error = `HTTP ${status}`;
2462
+ let failedAssets = [];
2463
+ try {
2464
+ const j = JSON.parse(text);
2465
+ error = String(j.error ?? j.message ?? (text || error));
2466
+ if (Array.isArray(j.failedAssets)) failedAssets = j.failedAssets;
2467
+ } catch {
2468
+ if (text) error = text;
2469
+ }
2470
+ return { status, error, failedAssets, bodyText: text };
2471
+ }
2472
+ function isUnknownShop(f) {
2473
+ return /unknown shop/i.test(f.error);
2474
+ }
2475
+ function isAssetForbidden(f) {
2476
+ if (f.failedAssets.some((a) => a.status === 403 || /blocked|forbidden|allowlist|not allowed/i.test(`${a.reason ?? ""} ${a.code ?? ""}`))) {
2477
+ return true;
2478
+ }
2479
+ return /host blocked|allowlist|not an allowed|forbidden/i.test(f.error);
2480
+ }
2481
+ async function fetchMockupImage(url, opts = {}) {
2482
+ const f = opts.fetchImpl ?? globalThis.fetch;
2483
+ const retryWindowMs = opts.retryWindowMs ?? 1e4;
2484
+ const delays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
2485
+ const timeoutMs = opts.timeoutMs ?? 2e4;
2486
+ const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
2487
+ let waited = 0;
2488
+ let attempt = 0;
2489
+ let last = null;
2490
+ for (; ; ) {
2491
+ const controller = new AbortController();
2492
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
2493
+ let failure;
2494
+ try {
2495
+ const res = await f(url, { signal: controller.signal });
2496
+ const bytes = new Uint8Array(await res.arrayBuffer());
2497
+ const kind = imageKindOf(bytes);
2498
+ if (res.ok && kind) {
2499
+ return { status: res.status, kind, bytes };
2500
+ }
2501
+ failure = parseFailure(res.status, bytes);
2502
+ } catch (err) {
2503
+ const message = err instanceof Error ? err.message : String(err);
2504
+ failure = { status: 0, error: `network error fetching ${url}: ${message}`, failedAssets: [], bodyText: "" };
2505
+ } finally {
2506
+ clearTimeout(timer);
2507
+ }
2508
+ last = failure;
2509
+ if (isAssetForbidden(failure)) {
2510
+ throw new SnowconeSdkError(
2511
+ "ASSET_FORBIDDEN",
2512
+ `the shop's asset-origin allowlist denied an asset in this design: ${failure.error}. Add the asset's origin to the shop's allowed asset origins (or host the asset on the shop's storage origin) and retry \u2014 the URL and your code are otherwise fine.`,
2513
+ { url, status: failure.status, failedAssets: failure.failedAssets }
2514
+ );
2515
+ }
2516
+ const nextDelay = delays[Math.min(attempt, delays.length - 1)] ?? 2e3;
2517
+ const canRetry = isUnknownShop(failure) && waited + nextDelay <= retryWindowMs;
2518
+ if (!canRetry) break;
2519
+ await sleep(nextDelay);
2520
+ waited += nextDelay;
2521
+ attempt += 1;
2522
+ }
2523
+ if (last && isUnknownShop(last)) {
2524
+ throw new SnowconeSdkError(
2525
+ "SHOP_NOT_PROPAGATED",
2526
+ `the render edge still answers "Unknown shop" after ${Math.round(retryWindowMs / 1e3)}s of retries. For a freshly minted shop this is edge KV propagation lag (normally ~1\u20133s) \u2014 your code is not the problem. If this shop is NOT freshly minted, the shop id is wrong: confirm the publishable shop id (shop.id) you passed.`,
2527
+ { url, status: last.status, retriedMs: waited, cause: "kv-propagation" }
2528
+ );
2529
+ }
2530
+ throw new SnowconeSdkError(
2531
+ "RENDER_FAILED",
2532
+ `mockup URL did not render an image: ${last?.error ?? "unknown error"}`,
2533
+ { url, status: last?.status ?? 0, error: last?.error, failedAssets: last?.failedAssets ?? [] }
2534
+ );
2535
+ }
2536
+
2417
2537
  // src/context/synchronization.ts
2418
2538
  var ContextSynchronizer = class {
2419
2539
  constructor(options = {}) {
@@ -6181,6 +6301,7 @@ function createClient(config) {
6181
6301
  REALTIME_WS_URL,
6182
6302
  RealtimeMockupService,
6183
6303
  RenderSession,
6304
+ SnowconeSdkError,
6184
6305
  StandardComponents,
6185
6306
  StandardEvents,
6186
6307
  StateManager,
@@ -6227,6 +6348,7 @@ function createClient(config) {
6227
6348
  describeProductPrice,
6228
6349
  describeProductTitle,
6229
6350
  extractProductId,
6351
+ fetchMockupImage,
6230
6352
  fetchRealtimeGrant,
6231
6353
  filterImagePlacements,
6232
6354
  findBestCombination,
@@ -6247,8 +6369,10 @@ function createClient(config) {
6247
6369
  getSnapPoints,
6248
6370
  getVariant,
6249
6371
  handleOptionChange,
6372
+ imageKindOf,
6250
6373
  isOptionAvailable,
6251
6374
  isSelectionComplete,
6375
+ isSnowconeSdkError,
6252
6376
  isValidAlignment,
6253
6377
  isValidTileCount,
6254
6378
  listProducts,
package/dist/index.d.cts CHANGED
@@ -227,6 +227,13 @@ interface GetMockupUrlOptions {
227
227
  * params. Takes precedence over `asset`.
228
228
  */
229
229
  design?: Design;
230
+ /**
231
+ * Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
232
+ * public designs catalog (`searchDesigns`). Emitted as `design=` — the
233
+ * resolver injects the published components server-side and the render is
234
+ * FREE (no usage charge). Mutually exclusive with `asset`/`design`.
235
+ */
236
+ designRef?: string;
230
237
  /**
231
238
  * Variant option picks: attribute name → choice label (e.g. `{ size: "m" }`).
232
239
  * Emitted as `opt.<attr>`. Matched case-insensitively by the resolver.
@@ -1194,6 +1201,93 @@ declare function retryOperation<T>(operation: () => Promise<T>, options?: {
1194
1201
  onRetry?: (attempt: number, error: Error) => void;
1195
1202
  }): Promise<T>;
1196
1203
 
1204
+ /**
1205
+ * Structured SDK errors (agent-DX decision E3, ADR-0085 plan): every public
1206
+ * throw carries a STABLE `code` plus machine-readable `data`, with the human
1207
+ * message rendered from them. Tests (and agents) assert on `code` + `data`
1208
+ * fields — never on prose substrings.
1209
+ */
1210
+ type SnowconeSdkErrorCode =
1211
+ /** Freshly minted shop not yet visible at the render edge (KV lag). */
1212
+ 'SHOP_NOT_PROPAGATED'
1213
+ /** The shop's asset-origin allowlist denied an asset in the design. */
1214
+ | 'ASSET_FORBIDDEN'
1215
+ /** Any other render failure (server reason in `data.error`). */
1216
+ | 'RENDER_FAILED';
1217
+ declare class SnowconeSdkError extends Error {
1218
+ readonly code: SnowconeSdkErrorCode;
1219
+ readonly data: Record<string, unknown>;
1220
+ constructor(code: SnowconeSdkErrorCode, message: string, data?: Record<string, unknown>);
1221
+ }
1222
+ declare function isSnowconeSdkError(err: unknown): err is SnowconeSdkError;
1223
+
1224
+ /**
1225
+ * Fetch a rendered mockup URL and prove it is a real image — with the
1226
+ * mint→edge propagation lag absorbed (agent-DX decision F2, ADR-0085 plan).
1227
+ *
1228
+ * THE TRAP THIS KILLS: a freshly minted (sandbox) shop takes a few seconds to
1229
+ * propagate to the render edge's KV store. A render request in that window
1230
+ * 404s `"Unknown shop"` — on CORRECT code. Agents (and humans) then debug the
1231
+ * integration instead of waiting. This helper retries that one failure mode
1232
+ * inside a bounded window (~10s by default) and, if the shop still isn't
1233
+ * visible, throws a LOUD structured error naming the propagation cause — so
1234
+ * nobody ever bisects working code over KV lag.
1235
+ *
1236
+ * Every other failure (asset blocked by the shop's asset-origin allowlist,
1237
+ * product not found, non-image response) throws immediately with a stable
1238
+ * `code` + `data` (no retry — they are deterministic).
1239
+ */
1240
+ /** Identify common raster formats by magic bytes; undefined if not an image. */
1241
+ declare function imageKindOf(b: Uint8Array): string | undefined;
1242
+ /** One failed asset, as reported by the render edge (`failedAssets[]`). */
1243
+ interface FailedAsset {
1244
+ url?: string;
1245
+ reason?: string;
1246
+ code?: string;
1247
+ status?: number;
1248
+ }
1249
+ interface MockupImage {
1250
+ /** Always 200-family when this resolves. */
1251
+ status: number;
1252
+ /** 'PNG' | 'JPEG' | 'WebP' | 'AVIF' | 'GIF'. */
1253
+ kind: string;
1254
+ /** The raw encoded image. */
1255
+ bytes: Uint8Array;
1256
+ }
1257
+ interface FetchMockupImageOptions {
1258
+ /**
1259
+ * Total window to keep retrying `"Unknown shop"` (the mint→edge KV
1260
+ * propagation lag) before throwing `SHOP_NOT_PROPAGATED`. Default 10_000ms.
1261
+ * Set 0 to disable the retry entirely.
1262
+ */
1263
+ retryWindowMs?: number;
1264
+ /**
1265
+ * Backoff schedule inside the window (ms between attempts). Exposed mostly
1266
+ * for tests; the default ramps 500 → 2000ms.
1267
+ */
1268
+ retryDelaysMs?: number[];
1269
+ /** Per-attempt fetch timeout. Default 20_000ms. */
1270
+ timeoutMs?: number;
1271
+ /** Override fetch (tests / non-global-fetch runtimes). */
1272
+ fetchImpl?: typeof fetch;
1273
+ /** Override sleeping between retries (tests). */
1274
+ sleep?: (ms: number) => Promise<void>;
1275
+ }
1276
+ /**
1277
+ * Fetch `url` until it yields a real raster image.
1278
+ *
1279
+ * Resolves with the image bytes on success. Throws {@link SnowconeSdkError}:
1280
+ *
1281
+ * - `SHOP_NOT_PROPAGATED` — the edge still answers `"Unknown shop"` after the
1282
+ * retry window. For a freshly minted shop this is KV propagation lag, not a
1283
+ * bug in your code; the message says exactly that.
1284
+ * - `ASSET_FORBIDDEN` — the shop's asset-origin allowlist denied an asset
1285
+ * referenced by the design (`data.failedAssets` names which, and why).
1286
+ * - `RENDER_FAILED` — any other non-image response (`data.error` carries the
1287
+ * server's reason, e.g. "Product not found").
1288
+ */
1289
+ declare function fetchMockupImage(url: string, opts?: FetchMockupImageOptions): Promise<MockupImage>;
1290
+
1197
1291
  /**
1198
1292
  * Context synchronization utilities for managing state updates
1199
1293
  * across React and Web Component implementations
@@ -3170,4 +3264,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3170
3264
  */
3171
3265
  declare function createClient(config: SdkConfig): SnowconeClient;
3172
3266
 
3173
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3267
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
package/dist/index.d.ts CHANGED
@@ -227,6 +227,13 @@ interface GetMockupUrlOptions {
227
227
  * params. Takes precedence over `asset`.
228
228
  */
229
229
  design?: Design;
230
+ /**
231
+ * Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
232
+ * public designs catalog (`searchDesigns`). Emitted as `design=` — the
233
+ * resolver injects the published components server-side and the render is
234
+ * FREE (no usage charge). Mutually exclusive with `asset`/`design`.
235
+ */
236
+ designRef?: string;
230
237
  /**
231
238
  * Variant option picks: attribute name → choice label (e.g. `{ size: "m" }`).
232
239
  * Emitted as `opt.<attr>`. Matched case-insensitively by the resolver.
@@ -1194,6 +1201,93 @@ declare function retryOperation<T>(operation: () => Promise<T>, options?: {
1194
1201
  onRetry?: (attempt: number, error: Error) => void;
1195
1202
  }): Promise<T>;
1196
1203
 
1204
+ /**
1205
+ * Structured SDK errors (agent-DX decision E3, ADR-0085 plan): every public
1206
+ * throw carries a STABLE `code` plus machine-readable `data`, with the human
1207
+ * message rendered from them. Tests (and agents) assert on `code` + `data`
1208
+ * fields — never on prose substrings.
1209
+ */
1210
+ type SnowconeSdkErrorCode =
1211
+ /** Freshly minted shop not yet visible at the render edge (KV lag). */
1212
+ 'SHOP_NOT_PROPAGATED'
1213
+ /** The shop's asset-origin allowlist denied an asset in the design. */
1214
+ | 'ASSET_FORBIDDEN'
1215
+ /** Any other render failure (server reason in `data.error`). */
1216
+ | 'RENDER_FAILED';
1217
+ declare class SnowconeSdkError extends Error {
1218
+ readonly code: SnowconeSdkErrorCode;
1219
+ readonly data: Record<string, unknown>;
1220
+ constructor(code: SnowconeSdkErrorCode, message: string, data?: Record<string, unknown>);
1221
+ }
1222
+ declare function isSnowconeSdkError(err: unknown): err is SnowconeSdkError;
1223
+
1224
+ /**
1225
+ * Fetch a rendered mockup URL and prove it is a real image — with the
1226
+ * mint→edge propagation lag absorbed (agent-DX decision F2, ADR-0085 plan).
1227
+ *
1228
+ * THE TRAP THIS KILLS: a freshly minted (sandbox) shop takes a few seconds to
1229
+ * propagate to the render edge's KV store. A render request in that window
1230
+ * 404s `"Unknown shop"` — on CORRECT code. Agents (and humans) then debug the
1231
+ * integration instead of waiting. This helper retries that one failure mode
1232
+ * inside a bounded window (~10s by default) and, if the shop still isn't
1233
+ * visible, throws a LOUD structured error naming the propagation cause — so
1234
+ * nobody ever bisects working code over KV lag.
1235
+ *
1236
+ * Every other failure (asset blocked by the shop's asset-origin allowlist,
1237
+ * product not found, non-image response) throws immediately with a stable
1238
+ * `code` + `data` (no retry — they are deterministic).
1239
+ */
1240
+ /** Identify common raster formats by magic bytes; undefined if not an image. */
1241
+ declare function imageKindOf(b: Uint8Array): string | undefined;
1242
+ /** One failed asset, as reported by the render edge (`failedAssets[]`). */
1243
+ interface FailedAsset {
1244
+ url?: string;
1245
+ reason?: string;
1246
+ code?: string;
1247
+ status?: number;
1248
+ }
1249
+ interface MockupImage {
1250
+ /** Always 200-family when this resolves. */
1251
+ status: number;
1252
+ /** 'PNG' | 'JPEG' | 'WebP' | 'AVIF' | 'GIF'. */
1253
+ kind: string;
1254
+ /** The raw encoded image. */
1255
+ bytes: Uint8Array;
1256
+ }
1257
+ interface FetchMockupImageOptions {
1258
+ /**
1259
+ * Total window to keep retrying `"Unknown shop"` (the mint→edge KV
1260
+ * propagation lag) before throwing `SHOP_NOT_PROPAGATED`. Default 10_000ms.
1261
+ * Set 0 to disable the retry entirely.
1262
+ */
1263
+ retryWindowMs?: number;
1264
+ /**
1265
+ * Backoff schedule inside the window (ms between attempts). Exposed mostly
1266
+ * for tests; the default ramps 500 → 2000ms.
1267
+ */
1268
+ retryDelaysMs?: number[];
1269
+ /** Per-attempt fetch timeout. Default 20_000ms. */
1270
+ timeoutMs?: number;
1271
+ /** Override fetch (tests / non-global-fetch runtimes). */
1272
+ fetchImpl?: typeof fetch;
1273
+ /** Override sleeping between retries (tests). */
1274
+ sleep?: (ms: number) => Promise<void>;
1275
+ }
1276
+ /**
1277
+ * Fetch `url` until it yields a real raster image.
1278
+ *
1279
+ * Resolves with the image bytes on success. Throws {@link SnowconeSdkError}:
1280
+ *
1281
+ * - `SHOP_NOT_PROPAGATED` — the edge still answers `"Unknown shop"` after the
1282
+ * retry window. For a freshly minted shop this is KV propagation lag, not a
1283
+ * bug in your code; the message says exactly that.
1284
+ * - `ASSET_FORBIDDEN` — the shop's asset-origin allowlist denied an asset
1285
+ * referenced by the design (`data.failedAssets` names which, and why).
1286
+ * - `RENDER_FAILED` — any other non-image response (`data.error` carries the
1287
+ * server's reason, e.g. "Product not found").
1288
+ */
1289
+ declare function fetchMockupImage(url: string, opts?: FetchMockupImageOptions): Promise<MockupImage>;
1290
+
1197
1291
  /**
1198
1292
  * Context synchronization utilities for managing state updates
1199
1293
  * across React and Web Component implementations
@@ -3170,4 +3264,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3170
3264
  */
3171
3265
  declare function createClient(config: SdkConfig): SnowconeClient;
3172
3266
 
3173
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3267
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-Z5M4JEZU.js";
14
+ } from "./chunk-XBDTD2I2.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -552,6 +552,7 @@ function getMockupUrl(a, b, c) {
552
552
  shop: opts.shop,
553
553
  ...opts.design ? { design: opts.design } : {},
554
554
  ...assetUrl !== void 0 ? { assetUrl } : {},
555
+ ...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
555
556
  ...opts.options ? { options: opts.options } : {},
556
557
  ...opts.width !== void 0 ? { width: opts.width } : {},
557
558
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
@@ -2047,6 +2048,109 @@ async function retryOperation(operation, options = {}) {
2047
2048
  throw lastError;
2048
2049
  }
2049
2050
 
2051
+ // src/error/structured.ts
2052
+ var SnowconeSdkError = class extends Error {
2053
+ code;
2054
+ data;
2055
+ constructor(code, message, data = {}) {
2056
+ super(`${code}: ${message}`);
2057
+ this.name = "SnowconeSdkError";
2058
+ this.code = code;
2059
+ this.data = { code, ...data };
2060
+ }
2061
+ };
2062
+ function isSnowconeSdkError(err) {
2063
+ return err instanceof Error && err.name === "SnowconeSdkError" && "code" in err;
2064
+ }
2065
+
2066
+ // src/mockup/fetchMockupImage.ts
2067
+ function imageKindOf(b) {
2068
+ if (b[0] === 137 && b[1] === 80) return "PNG";
2069
+ if (b[0] === 255 && b[1] === 216) return "JPEG";
2070
+ if (b[0] === 71 && b[1] === 73 && b[2] === 70) return "GIF";
2071
+ if (b[0] === 82 && b[1] === 73 && b[2] === 70 && b[3] === 70) return "WebP";
2072
+ if (b.length >= 12 && String.fromCharCode(b[4], b[5], b[6], b[7]) === "ftyp") return "AVIF";
2073
+ return void 0;
2074
+ }
2075
+ var DEFAULT_RETRY_DELAYS_MS = [500, 1e3, 2e3, 2e3, 2e3, 2e3];
2076
+ function parseFailure(status, bytes) {
2077
+ const text = new TextDecoder().decode(bytes).slice(0, 1e3);
2078
+ let error = `HTTP ${status}`;
2079
+ let failedAssets = [];
2080
+ try {
2081
+ const j = JSON.parse(text);
2082
+ error = String(j.error ?? j.message ?? (text || error));
2083
+ if (Array.isArray(j.failedAssets)) failedAssets = j.failedAssets;
2084
+ } catch {
2085
+ if (text) error = text;
2086
+ }
2087
+ return { status, error, failedAssets, bodyText: text };
2088
+ }
2089
+ function isUnknownShop(f) {
2090
+ return /unknown shop/i.test(f.error);
2091
+ }
2092
+ function isAssetForbidden(f) {
2093
+ if (f.failedAssets.some((a) => a.status === 403 || /blocked|forbidden|allowlist|not allowed/i.test(`${a.reason ?? ""} ${a.code ?? ""}`))) {
2094
+ return true;
2095
+ }
2096
+ return /host blocked|allowlist|not an allowed|forbidden/i.test(f.error);
2097
+ }
2098
+ async function fetchMockupImage(url, opts = {}) {
2099
+ const f = opts.fetchImpl ?? globalThis.fetch;
2100
+ const retryWindowMs = opts.retryWindowMs ?? 1e4;
2101
+ const delays = opts.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
2102
+ const timeoutMs = opts.timeoutMs ?? 2e4;
2103
+ const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
2104
+ let waited = 0;
2105
+ let attempt = 0;
2106
+ let last = null;
2107
+ for (; ; ) {
2108
+ const controller = new AbortController();
2109
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
2110
+ let failure;
2111
+ try {
2112
+ const res = await f(url, { signal: controller.signal });
2113
+ const bytes = new Uint8Array(await res.arrayBuffer());
2114
+ const kind = imageKindOf(bytes);
2115
+ if (res.ok && kind) {
2116
+ return { status: res.status, kind, bytes };
2117
+ }
2118
+ failure = parseFailure(res.status, bytes);
2119
+ } catch (err) {
2120
+ const message = err instanceof Error ? err.message : String(err);
2121
+ failure = { status: 0, error: `network error fetching ${url}: ${message}`, failedAssets: [], bodyText: "" };
2122
+ } finally {
2123
+ clearTimeout(timer);
2124
+ }
2125
+ last = failure;
2126
+ if (isAssetForbidden(failure)) {
2127
+ throw new SnowconeSdkError(
2128
+ "ASSET_FORBIDDEN",
2129
+ `the shop's asset-origin allowlist denied an asset in this design: ${failure.error}. Add the asset's origin to the shop's allowed asset origins (or host the asset on the shop's storage origin) and retry \u2014 the URL and your code are otherwise fine.`,
2130
+ { url, status: failure.status, failedAssets: failure.failedAssets }
2131
+ );
2132
+ }
2133
+ const nextDelay = delays[Math.min(attempt, delays.length - 1)] ?? 2e3;
2134
+ const canRetry = isUnknownShop(failure) && waited + nextDelay <= retryWindowMs;
2135
+ if (!canRetry) break;
2136
+ await sleep(nextDelay);
2137
+ waited += nextDelay;
2138
+ attempt += 1;
2139
+ }
2140
+ if (last && isUnknownShop(last)) {
2141
+ throw new SnowconeSdkError(
2142
+ "SHOP_NOT_PROPAGATED",
2143
+ `the render edge still answers "Unknown shop" after ${Math.round(retryWindowMs / 1e3)}s of retries. For a freshly minted shop this is edge KV propagation lag (normally ~1\u20133s) \u2014 your code is not the problem. If this shop is NOT freshly minted, the shop id is wrong: confirm the publishable shop id (shop.id) you passed.`,
2144
+ { url, status: last.status, retriedMs: waited, cause: "kv-propagation" }
2145
+ );
2146
+ }
2147
+ throw new SnowconeSdkError(
2148
+ "RENDER_FAILED",
2149
+ `mockup URL did not render an image: ${last?.error ?? "unknown error"}`,
2150
+ { url, status: last?.status ?? 0, error: last?.error, failedAssets: last?.failedAssets ?? [] }
2151
+ );
2152
+ }
2153
+
2050
2154
  // src/context/synchronization.ts
2051
2155
  var ContextSynchronizer = class {
2052
2156
  constructor(options = {}) {
@@ -5055,6 +5159,7 @@ export {
5055
5159
  REALTIME_WS_URL,
5056
5160
  RealtimeMockupService,
5057
5161
  RenderSession,
5162
+ SnowconeSdkError,
5058
5163
  StandardComponents,
5059
5164
  StandardEvents,
5060
5165
  StateManager,
@@ -5101,6 +5206,7 @@ export {
5101
5206
  describeProductPrice,
5102
5207
  describeProductTitle,
5103
5208
  extractProductId,
5209
+ fetchMockupImage,
5104
5210
  fetchRealtimeGrant,
5105
5211
  filterImagePlacements,
5106
5212
  findBestCombination,
@@ -5121,8 +5227,10 @@ export {
5121
5227
  getSnapPoints,
5122
5228
  getVariant,
5123
5229
  handleOptionChange,
5230
+ imageKindOf,
5124
5231
  isOptionAvailable,
5125
5232
  isSelectionComplete,
5233
+ isSnowconeSdkError,
5126
5234
  isValidAlignment,
5127
5235
  isValidTileCount,
5128
5236
  listProducts,
package/dist/server.cjs CHANGED
@@ -34,6 +34,15 @@ var PARAMS = {
34
34
  shop: "shop",
35
35
  asset: "asset",
36
36
  assets: "assets",
37
+ /**
38
+ * Render a catalog design by reference (ADR-0086): `design=<pairingId|slug>`.
39
+ * The resolver looks the design up in the public `snowcone-designs` index
40
+ * (membership = license) and injects its asset components server-side, so no
41
+ * raw asset URL crosses the wire and no origin allowlisting is involved.
42
+ * Catalog renders are FREE — mutually exclusive with `asset`/`asset.<key>`/
43
+ * `color.<key>` (free = the design as published).
44
+ */
45
+ design: "design",
37
46
  placement: "placement",
38
47
  variant: "variant",
39
48
  mockup: "mockup",
@@ -55,6 +64,7 @@ var PARAMS = {
55
64
  };
56
65
  var PUBLIC_PARAM_NAMES = [
57
66
  PARAMS.asset,
67
+ PARAMS.design,
58
68
  PARAMS.shop,
59
69
  PARAMS.placement,
60
70
  PARAMS.variant,
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-Z5M4JEZU.js";
4
+ } from "./chunk-XBDTD2I2.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",