@snowcone-app/sdk 0.13.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 +16 -0
- package/dist/{chunk-Z5M4JEZU.js → chunk-XBDTD2I2.js} +12 -0
- package/dist/index.cjs +124 -0
- package/dist/index.d.cts +102 -6
- package/dist/index.d.ts +102 -6
- package/dist/index.js +109 -1
- package/dist/server.cjs +10 -0
- package/dist/server.js +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
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
|
+
|
|
13
|
+
## 0.14.0
|
|
14
|
+
|
|
15
|
+
### Minor Changes
|
|
16
|
+
|
|
17
|
+
- [#646](https://github.com/snowcone-app/snowcone-monorepo/pull/646) [`e2c6f42`](https://github.com/snowcone-app/snowcone-monorepo/commit/e2c6f424c74eaf60402ce55bac7b081fe5e0ed18) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Designs catalog now indexes every published marketplace design, not just first-party-curated picks. The design doc's `firstParty: true` field is replaced by a `curated: boolean` filterable facet (`curated = true` selects Snowcone-curated designs); `curated` is also added to the index's filterable attributes.
|
|
18
|
+
|
|
3
19
|
## 0.13.0
|
|
4
20
|
|
|
5
21
|
### 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
|
|
@@ -3129,7 +3223,8 @@ interface CatalogDesign {
|
|
|
3129
3223
|
license?: {
|
|
3130
3224
|
remixable?: boolean;
|
|
3131
3225
|
};
|
|
3132
|
-
|
|
3226
|
+
/** First-party curation flag — filterable facet (`curated = true`). */
|
|
3227
|
+
curated?: boolean;
|
|
3133
3228
|
/** RESERVED — always null today; future structured slot metadata. */
|
|
3134
3229
|
slots?: unknown;
|
|
3135
3230
|
[key: string]: unknown;
|
|
@@ -3157,10 +3252,11 @@ interface SnowconeClient {
|
|
|
3157
3252
|
declare function listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3158
3253
|
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3159
3254
|
/**
|
|
3160
|
-
* Search the public
|
|
3161
|
-
*
|
|
3162
|
-
*
|
|
3163
|
-
* @snowcone-app/mockup-url's
|
|
3255
|
+
* Search the public designs catalog (every published marketplace design;
|
|
3256
|
+
* filter `curated = true` for first-party-curated picks) so an integration
|
|
3257
|
+
* never starts from a blank canvas. Returns mockup-URL components per
|
|
3258
|
+
* design — feed `assets` (or `asset`) into @snowcone-app/mockup-url's
|
|
3259
|
+
* builder or the canvas/embed primitives.
|
|
3164
3260
|
*/
|
|
3165
3261
|
declare function searchDesigns(query?: string, options?: SearchDesignsOptions): Promise<DesignsSearchResponse>;
|
|
3166
3262
|
/**
|
|
@@ -3168,4 +3264,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
|
|
|
3168
3264
|
*/
|
|
3169
3265
|
declare function createClient(config: SdkConfig): SnowconeClient;
|
|
3170
3266
|
|
|
3171
|
-
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
|
|
@@ -3129,7 +3223,8 @@ interface CatalogDesign {
|
|
|
3129
3223
|
license?: {
|
|
3130
3224
|
remixable?: boolean;
|
|
3131
3225
|
};
|
|
3132
|
-
|
|
3226
|
+
/** First-party curation flag — filterable facet (`curated = true`). */
|
|
3227
|
+
curated?: boolean;
|
|
3133
3228
|
/** RESERVED — always null today; future structured slot metadata. */
|
|
3134
3229
|
slots?: unknown;
|
|
3135
3230
|
[key: string]: unknown;
|
|
@@ -3157,10 +3252,11 @@ interface SnowconeClient {
|
|
|
3157
3252
|
declare function listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3158
3253
|
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3159
3254
|
/**
|
|
3160
|
-
* Search the public
|
|
3161
|
-
*
|
|
3162
|
-
*
|
|
3163
|
-
* @snowcone-app/mockup-url's
|
|
3255
|
+
* Search the public designs catalog (every published marketplace design;
|
|
3256
|
+
* filter `curated = true` for first-party-curated picks) so an integration
|
|
3257
|
+
* never starts from a blank canvas. Returns mockup-URL components per
|
|
3258
|
+
* design — feed `assets` (or `asset`) into @snowcone-app/mockup-url's
|
|
3259
|
+
* builder or the canvas/embed primitives.
|
|
3164
3260
|
*/
|
|
3165
3261
|
declare function searchDesigns(query?: string, options?: SearchDesignsOptions): Promise<DesignsSearchResponse>;
|
|
3166
3262
|
/**
|
|
@@ -3168,4 +3264,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
|
|
|
3168
3264
|
*/
|
|
3169
3265
|
declare function createClient(config: SdkConfig): SnowconeClient;
|
|
3170
3266
|
|
|
3171
|
-
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-
|
|
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