@snowcone-app/sdk 0.18.1 → 0.20.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 +27 -0
- package/README.md +3 -0
- package/dist/{chunk-7DRH6S4D.js → chunk-IL3FXE2X.js} +52 -19
- package/dist/index.cjs +57 -19
- package/dist/index.d.cts +30 -8
- package/dist/index.d.ts +30 -8
- package/dist/index.js +6 -1
- package/dist/server.cjs +8 -0
- package/dist/server.js +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.20.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#1003](https://github.com/snowcone-app/snowcone-monorepo/pull/1003) [`ada5ed2`](https://github.com/snowcone-app/snowcone-monorepo/commit/ada5ed200f219787bc97018e0c5811ea8e4c2fa1) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Background color joins the public mockup-URL grammar and the agent shop API.
|
|
8
|
+
- `bg=<6-hex>` is now a first-class public URL param (`buildPublicMockupUrl`,
|
|
9
|
+
`parsePublicUrl`, strict-param allowlist) — painted behind the mockup wherever
|
|
10
|
+
the scene is transparent. Precedence: per-URL `bg` > the shop's configured
|
|
11
|
+
default (`mockup_bg_color`) > transparent.
|
|
12
|
+
- SDK: `getMockupUrl(..., { bg })` emits the param (normalized 6-hex, `#`
|
|
13
|
+
optional).
|
|
14
|
+
- MCP: new `snowcone_set_mockup_background` tool sets/clears a sandbox shop's
|
|
15
|
+
default background; `snowcone_mint_shop` accepts `mockup_bg_color` at birth;
|
|
16
|
+
`snowcone_render_mockup` / `snowcone_buy_url` accept a per-render `bg`.
|
|
17
|
+
|
|
18
|
+
- [#1008](https://github.com/snowcone-app/snowcone-monorepo/pull/1008) [`f66c9c3`](https://github.com/snowcone-app/snowcone-monorepo/commit/f66c9c3b1ca2ab50bc390feb4a691cd95bb53abd) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `bg=transparent` — the per-render escape hatch from a shop's default mockup
|
|
19
|
+
background. The reserved token (exported as `BG_TRANSPARENT`, accepted by
|
|
20
|
+
`normalizeBgColor`) pins the raw transparent studio cutout for one render even
|
|
21
|
+
when the shop has `mockup_bg_color` set. Accepted by `getMockupUrl({ bg })`,
|
|
22
|
+
the MCP render/buy tools, and the public URL grammar.
|
|
23
|
+
|
|
24
|
+
## 0.19.0
|
|
25
|
+
|
|
26
|
+
### Minor Changes
|
|
27
|
+
|
|
28
|
+
- [#887](https://github.com/snowcone-app/snowcone-monorepo/pull/887) [`e731ea4`](https://github.com/snowcone-app/snowcone-monorepo/commit/e731ea4fb0c8f2c642c8d6e06bc3015f00391a30) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `getMockupUrl`/`getBuyUrl`: `asset` is now a base design that broadcasts to every product placement, and a new `placements` override map targets individual placements (ADR-0089). One image now appears on all placements by default; per-placement art is the advanced opt-in. The resolver-side broadcast is already live; this publishes the typed `placements` builder option to match.
|
|
29
|
+
|
|
3
30
|
## 0.18.1
|
|
4
31
|
|
|
5
32
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -107,6 +107,9 @@ const url = getMockupUrl(productCode: string, opts: {
|
|
|
107
107
|
variant?: string; // Optional: specific resolved variant (gvid)
|
|
108
108
|
placement?: string; // Optional: specific print area (single-asset only)
|
|
109
109
|
aspect?: '16:9' | '2:3';// Optional: canvas aspect ratio
|
|
110
|
+
bg?: string; // Optional: background color behind the mockup (6-hex, '#' optional).
|
|
111
|
+
// Visible only where the scene is transparent; omit to use the
|
|
112
|
+
// shop's configured default (mockup_bg_color), else transparent.
|
|
110
113
|
}): string;
|
|
111
114
|
```
|
|
112
115
|
|
|
@@ -27,6 +27,13 @@ var PARAMS = {
|
|
|
27
27
|
width: "width",
|
|
28
28
|
grain: "grain",
|
|
29
29
|
aspect: "aspect",
|
|
30
|
+
/**
|
|
31
|
+
* Background color (6-hex, no '#') painted behind the mockup — visible only
|
|
32
|
+
* where the mockup itself has transparency (studio-cutout shots) — or the
|
|
33
|
+
* reserved `transparent` token, which suppresses the shop default for this
|
|
34
|
+
* one render. Absent = the shop's configured default, else transparent.
|
|
35
|
+
*/
|
|
36
|
+
bg: "bg",
|
|
30
37
|
/** Live preview/calibration mask overrides (not cached). */
|
|
31
38
|
maskOverrides: "maskOverrides",
|
|
32
39
|
/**
|
|
@@ -40,6 +47,21 @@ var PARAMS = {
|
|
|
40
47
|
signature: "signature",
|
|
41
48
|
seal: "seal"
|
|
42
49
|
};
|
|
50
|
+
var BG_TRANSPARENT = "transparent";
|
|
51
|
+
function normalizeBgColor(raw) {
|
|
52
|
+
const value = raw.trim().replace(/^#/, "").toLowerCase();
|
|
53
|
+
if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
|
|
54
|
+
return /^[0-9a-f]{6}$/.test(value) ? value : null;
|
|
55
|
+
}
|
|
56
|
+
function requireBgColor(raw) {
|
|
57
|
+
const bg = normalizeBgColor(raw);
|
|
58
|
+
if (bg === null) {
|
|
59
|
+
throw new Error(
|
|
60
|
+
`[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
return bg;
|
|
64
|
+
}
|
|
43
65
|
function asSimpleAsset(design) {
|
|
44
66
|
if (design.length !== 1) return null;
|
|
45
67
|
const el = design[0];
|
|
@@ -124,6 +146,9 @@ function buildMockupUrl(options, cfg) {
|
|
|
124
146
|
if (options.effects?.grain) {
|
|
125
147
|
queryString += `&${PARAMS.grain}=${options.effects.grain}`;
|
|
126
148
|
}
|
|
149
|
+
if (options.bg) {
|
|
150
|
+
queryString += `&${PARAMS.bg}=${requireBgColor(options.bg)}`;
|
|
151
|
+
}
|
|
127
152
|
if (options.aspect && options.aspect !== "16:9") {
|
|
128
153
|
queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
|
|
129
154
|
}
|
|
@@ -147,28 +172,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
|
|
|
147
172
|
const enc = encodeURIComponent;
|
|
148
173
|
const parts = [];
|
|
149
174
|
parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
|
|
150
|
-
if (options.
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
if (
|
|
164
|
-
parts.push(`${PARAM_PREFIX.
|
|
175
|
+
if (options.designRef !== void 0) {
|
|
176
|
+
parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
|
|
177
|
+
} else {
|
|
178
|
+
if (options.assetUrl !== void 0) {
|
|
179
|
+
parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
|
|
180
|
+
}
|
|
181
|
+
const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
|
|
182
|
+
if (overrides) {
|
|
183
|
+
for (const key of Object.keys(overrides).sort()) {
|
|
184
|
+
const fill = overrides[key];
|
|
185
|
+
const k = enc(key);
|
|
186
|
+
if (typeof fill === "string") {
|
|
187
|
+
parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
|
|
188
|
+
} else if ("color" in fill) {
|
|
189
|
+
parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
|
|
190
|
+
} else {
|
|
191
|
+
parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
|
|
192
|
+
if (fill.tile !== void 0) {
|
|
193
|
+
parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
|
|
194
|
+
}
|
|
195
|
+
if (fill.align !== void 0) {
|
|
196
|
+
parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
|
|
197
|
+
}
|
|
165
198
|
}
|
|
166
199
|
}
|
|
167
200
|
}
|
|
168
|
-
} else if (options.assetUrl !== void 0) {
|
|
169
|
-
parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
|
|
170
|
-
} else if (options.designRef !== void 0) {
|
|
171
|
-
parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
|
|
172
201
|
}
|
|
173
202
|
if (options.placement !== void 0) {
|
|
174
203
|
parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
|
|
@@ -191,6 +220,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
|
|
|
191
220
|
if (options.aspect !== void 0 && options.aspect !== "16:9") {
|
|
192
221
|
parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
|
|
193
222
|
}
|
|
223
|
+
if (options.bg) {
|
|
224
|
+
parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
|
|
225
|
+
}
|
|
194
226
|
return `${base}${path}?${parts.join("&")}`;
|
|
195
227
|
}
|
|
196
228
|
var PUBLIC_PARAM_NAMES = [
|
|
@@ -203,6 +235,7 @@ var PUBLIC_PARAM_NAMES = [
|
|
|
203
235
|
PARAMS.mockup,
|
|
204
236
|
PARAMS.width,
|
|
205
237
|
PARAMS.aspect,
|
|
238
|
+
PARAMS.bg,
|
|
206
239
|
PARAMS.signature
|
|
207
240
|
];
|
|
208
241
|
function canonicalForSig(url) {
|
package/dist/index.cjs
CHANGED
|
@@ -506,6 +506,13 @@ var PARAMS = {
|
|
|
506
506
|
width: "width",
|
|
507
507
|
grain: "grain",
|
|
508
508
|
aspect: "aspect",
|
|
509
|
+
/**
|
|
510
|
+
* Background color (6-hex, no '#') painted behind the mockup — visible only
|
|
511
|
+
* where the mockup itself has transparency (studio-cutout shots) — or the
|
|
512
|
+
* reserved `transparent` token, which suppresses the shop default for this
|
|
513
|
+
* one render. Absent = the shop's configured default, else transparent.
|
|
514
|
+
*/
|
|
515
|
+
bg: "bg",
|
|
509
516
|
/** Live preview/calibration mask overrides (not cached). */
|
|
510
517
|
maskOverrides: "maskOverrides",
|
|
511
518
|
/**
|
|
@@ -519,6 +526,21 @@ var PARAMS = {
|
|
|
519
526
|
signature: "signature",
|
|
520
527
|
seal: "seal"
|
|
521
528
|
};
|
|
529
|
+
var BG_TRANSPARENT = "transparent";
|
|
530
|
+
function normalizeBgColor(raw) {
|
|
531
|
+
const value = raw.trim().replace(/^#/, "").toLowerCase();
|
|
532
|
+
if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
|
|
533
|
+
return /^[0-9a-f]{6}$/.test(value) ? value : null;
|
|
534
|
+
}
|
|
535
|
+
function requireBgColor(raw) {
|
|
536
|
+
const bg = normalizeBgColor(raw);
|
|
537
|
+
if (bg === null) {
|
|
538
|
+
throw new Error(
|
|
539
|
+
`[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
|
|
540
|
+
);
|
|
541
|
+
}
|
|
542
|
+
return bg;
|
|
543
|
+
}
|
|
522
544
|
function asSimpleAsset(design) {
|
|
523
545
|
if (design.length !== 1) return null;
|
|
524
546
|
const el = design[0];
|
|
@@ -603,6 +625,9 @@ function buildMockupUrl(options, cfg) {
|
|
|
603
625
|
if (options.effects?.grain) {
|
|
604
626
|
queryString += `&${PARAMS.grain}=${options.effects.grain}`;
|
|
605
627
|
}
|
|
628
|
+
if (options.bg) {
|
|
629
|
+
queryString += `&${PARAMS.bg}=${requireBgColor(options.bg)}`;
|
|
630
|
+
}
|
|
606
631
|
if (options.aspect && options.aspect !== "16:9") {
|
|
607
632
|
queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
|
|
608
633
|
}
|
|
@@ -626,28 +651,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
|
|
|
626
651
|
const enc = encodeURIComponent;
|
|
627
652
|
const parts = [];
|
|
628
653
|
parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
|
|
629
|
-
if (options.
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
if (
|
|
643
|
-
parts.push(`${PARAM_PREFIX.
|
|
654
|
+
if (options.designRef !== void 0) {
|
|
655
|
+
parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
|
|
656
|
+
} else {
|
|
657
|
+
if (options.assetUrl !== void 0) {
|
|
658
|
+
parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
|
|
659
|
+
}
|
|
660
|
+
const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
|
|
661
|
+
if (overrides) {
|
|
662
|
+
for (const key of Object.keys(overrides).sort()) {
|
|
663
|
+
const fill = overrides[key];
|
|
664
|
+
const k = enc(key);
|
|
665
|
+
if (typeof fill === "string") {
|
|
666
|
+
parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
|
|
667
|
+
} else if ("color" in fill) {
|
|
668
|
+
parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
|
|
669
|
+
} else {
|
|
670
|
+
parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
|
|
671
|
+
if (fill.tile !== void 0) {
|
|
672
|
+
parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
|
|
673
|
+
}
|
|
674
|
+
if (fill.align !== void 0) {
|
|
675
|
+
parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
|
|
676
|
+
}
|
|
644
677
|
}
|
|
645
678
|
}
|
|
646
679
|
}
|
|
647
|
-
} else if (options.assetUrl !== void 0) {
|
|
648
|
-
parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
|
|
649
|
-
} else if (options.designRef !== void 0) {
|
|
650
|
-
parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
|
|
651
680
|
}
|
|
652
681
|
if (options.placement !== void 0) {
|
|
653
682
|
parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
|
|
@@ -670,6 +699,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
|
|
|
670
699
|
if (options.aspect !== void 0 && options.aspect !== "16:9") {
|
|
671
700
|
parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
|
|
672
701
|
}
|
|
702
|
+
if (options.bg) {
|
|
703
|
+
parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
|
|
704
|
+
}
|
|
673
705
|
return `${base}${path}?${parts.join("&")}`;
|
|
674
706
|
}
|
|
675
707
|
var PUBLIC_PARAM_NAMES = [
|
|
@@ -682,6 +714,7 @@ var PUBLIC_PARAM_NAMES = [
|
|
|
682
714
|
PARAMS.mockup,
|
|
683
715
|
PARAMS.width,
|
|
684
716
|
PARAMS.aspect,
|
|
717
|
+
PARAMS.bg,
|
|
685
718
|
PARAMS.signature
|
|
686
719
|
];
|
|
687
720
|
function canonicalForSig(url) {
|
|
@@ -946,12 +979,17 @@ function getMockupUrl(a, b, c) {
|
|
|
946
979
|
{
|
|
947
980
|
productCode,
|
|
948
981
|
shop: opts.shop,
|
|
982
|
+
// ADR-0089 base+override: the `asset` base and the `design`/`placements`
|
|
983
|
+
// override map COMPOSE (the builder merges them). `placements` is the
|
|
984
|
+
// preferred override name; `design` is the legacy alias.
|
|
949
985
|
...opts.design ? { design: opts.design } : {},
|
|
986
|
+
...opts.placements ? { placements: opts.placements } : {},
|
|
950
987
|
...assetUrl !== void 0 ? { assetUrl } : {},
|
|
951
988
|
...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
|
|
952
989
|
...opts.options ? { options: opts.options } : {},
|
|
953
990
|
...opts.width !== void 0 ? { width: opts.width } : {},
|
|
954
991
|
...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
|
|
992
|
+
...opts.bg !== void 0 ? { bg: opts.bg } : {},
|
|
955
993
|
...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
|
|
956
994
|
...opts.variant !== void 0 ? { variant: opts.variant } : {},
|
|
957
995
|
...opts.placement !== void 0 ? { placement: opts.placement } : {}
|
package/dist/index.d.cts
CHANGED
|
@@ -225,9 +225,11 @@ type Design = PublicDesign;
|
|
|
225
225
|
/**
|
|
226
226
|
* Options for the code-first {@link getMockupUrl} form.
|
|
227
227
|
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
228
|
+
* Artwork follows the ADR-0089 base+override model: `asset` is the BASE every
|
|
229
|
+
* placement inherits, and `placements` (or its `design` alias) is a per-key
|
|
230
|
+
* OVERRIDE map. They COMPOSE — give just `asset` to broadcast one image
|
|
231
|
+
* everywhere, add `placements` to retarget specific placements, or give only
|
|
232
|
+
* `placements` to fill named placements and leave the rest blank.
|
|
231
233
|
*/
|
|
232
234
|
interface GetMockupUrlOptions {
|
|
233
235
|
/**
|
|
@@ -237,17 +239,28 @@ interface GetMockupUrlOptions {
|
|
|
237
239
|
*/
|
|
238
240
|
shop: string;
|
|
239
241
|
/**
|
|
240
|
-
*
|
|
241
|
-
* readable `asset=` param
|
|
242
|
-
*
|
|
242
|
+
* The BASE design — one image every placement inherits (ADR-0089). Emitted as
|
|
243
|
+
* the readable `asset=` param; the resolver broadcasts it across every
|
|
244
|
+
* placement. Composes with {@link GetMockupUrlOptions.placements} /
|
|
245
|
+
* {@link GetMockupUrlOptions.design} overrides (it is no longer ignored when
|
|
246
|
+
* those are present). `asset=default` is the reserved house-blank token.
|
|
243
247
|
*/
|
|
244
248
|
asset?: string;
|
|
245
249
|
/**
|
|
246
|
-
*
|
|
250
|
+
* Per-placement OVERRIDES: a map of placement key → {@link Fill}. Emitted as
|
|
247
251
|
* the dotted `asset.<key>` / `color.<key>` / `tile.<key>` / `align.<key>`
|
|
248
|
-
* params.
|
|
252
|
+
* params. Composes WITH `asset` (ADR-0089): the `asset` base seeds every
|
|
253
|
+
* placement; each entry here overrides that one placement. `placements` is the
|
|
254
|
+
* preferred name; `design` is the legacy alias (both merge, override wins).
|
|
249
255
|
*/
|
|
250
256
|
design?: Design;
|
|
257
|
+
/**
|
|
258
|
+
* Per-placement overrides — the named, ADR-0089 form of {@link
|
|
259
|
+
* GetMockupUrlOptions.design}. A map of placement key → {@link Fill} that
|
|
260
|
+
* overrides the `asset` base on just those placements; unlisted placements
|
|
261
|
+
* keep the base. Merges with `design` if both are supplied.
|
|
262
|
+
*/
|
|
263
|
+
placements?: Design;
|
|
251
264
|
/**
|
|
252
265
|
* Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
|
|
253
266
|
* public designs catalog (`searchDesigns`). Emitted as `design=` — the
|
|
@@ -290,6 +303,15 @@ interface GetMockupUrlOptions {
|
|
|
290
303
|
* dimensions; measure or crop client-side with `object-fit: cover`.
|
|
291
304
|
*/
|
|
292
305
|
aspect?: "16:9" | "2:3";
|
|
306
|
+
/**
|
|
307
|
+
* Background color painted behind the mockup (6-hex, `#` optional — e.g.
|
|
308
|
+
* `"f5f0ea"` or `"#F5F0EA"`), or `"transparent"` to force the raw cutout by
|
|
309
|
+
* suppressing the shop's default for this one render. Visible only where the
|
|
310
|
+
* mockup scene itself has transparency (studio-cutout shots). Omit to use
|
|
311
|
+
* the shop's configured default background (`mockup_bg_color` in shop
|
|
312
|
+
* settings), else transparent. Emitted as `&bg=`.
|
|
313
|
+
*/
|
|
314
|
+
bg?: string;
|
|
293
315
|
}
|
|
294
316
|
/**
|
|
295
317
|
* Build the public mockup image URL. Pure + synchronous — drop the result
|
package/dist/index.d.ts
CHANGED
|
@@ -225,9 +225,11 @@ type Design = PublicDesign;
|
|
|
225
225
|
/**
|
|
226
226
|
* Options for the code-first {@link getMockupUrl} form.
|
|
227
227
|
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
228
|
+
* Artwork follows the ADR-0089 base+override model: `asset` is the BASE every
|
|
229
|
+
* placement inherits, and `placements` (or its `design` alias) is a per-key
|
|
230
|
+
* OVERRIDE map. They COMPOSE — give just `asset` to broadcast one image
|
|
231
|
+
* everywhere, add `placements` to retarget specific placements, or give only
|
|
232
|
+
* `placements` to fill named placements and leave the rest blank.
|
|
231
233
|
*/
|
|
232
234
|
interface GetMockupUrlOptions {
|
|
233
235
|
/**
|
|
@@ -237,17 +239,28 @@ interface GetMockupUrlOptions {
|
|
|
237
239
|
*/
|
|
238
240
|
shop: string;
|
|
239
241
|
/**
|
|
240
|
-
*
|
|
241
|
-
* readable `asset=` param
|
|
242
|
-
*
|
|
242
|
+
* The BASE design — one image every placement inherits (ADR-0089). Emitted as
|
|
243
|
+
* the readable `asset=` param; the resolver broadcasts it across every
|
|
244
|
+
* placement. Composes with {@link GetMockupUrlOptions.placements} /
|
|
245
|
+
* {@link GetMockupUrlOptions.design} overrides (it is no longer ignored when
|
|
246
|
+
* those are present). `asset=default` is the reserved house-blank token.
|
|
243
247
|
*/
|
|
244
248
|
asset?: string;
|
|
245
249
|
/**
|
|
246
|
-
*
|
|
250
|
+
* Per-placement OVERRIDES: a map of placement key → {@link Fill}. Emitted as
|
|
247
251
|
* the dotted `asset.<key>` / `color.<key>` / `tile.<key>` / `align.<key>`
|
|
248
|
-
* params.
|
|
252
|
+
* params. Composes WITH `asset` (ADR-0089): the `asset` base seeds every
|
|
253
|
+
* placement; each entry here overrides that one placement. `placements` is the
|
|
254
|
+
* preferred name; `design` is the legacy alias (both merge, override wins).
|
|
249
255
|
*/
|
|
250
256
|
design?: Design;
|
|
257
|
+
/**
|
|
258
|
+
* Per-placement overrides — the named, ADR-0089 form of {@link
|
|
259
|
+
* GetMockupUrlOptions.design}. A map of placement key → {@link Fill} that
|
|
260
|
+
* overrides the `asset` base on just those placements; unlisted placements
|
|
261
|
+
* keep the base. Merges with `design` if both are supplied.
|
|
262
|
+
*/
|
|
263
|
+
placements?: Design;
|
|
251
264
|
/**
|
|
252
265
|
* Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
|
|
253
266
|
* public designs catalog (`searchDesigns`). Emitted as `design=` — the
|
|
@@ -290,6 +303,15 @@ interface GetMockupUrlOptions {
|
|
|
290
303
|
* dimensions; measure or crop client-side with `object-fit: cover`.
|
|
291
304
|
*/
|
|
292
305
|
aspect?: "16:9" | "2:3";
|
|
306
|
+
/**
|
|
307
|
+
* Background color painted behind the mockup (6-hex, `#` optional — e.g.
|
|
308
|
+
* `"f5f0ea"` or `"#F5F0EA"`), or `"transparent"` to force the raw cutout by
|
|
309
|
+
* suppressing the shop's default for this one render. Visible only where the
|
|
310
|
+
* mockup scene itself has transparency (studio-cutout shots). Omit to use
|
|
311
|
+
* the shop's configured default background (`mockup_bg_color` in shop
|
|
312
|
+
* settings), else transparent. Emitted as `&bg=`.
|
|
313
|
+
*/
|
|
314
|
+
bg?: string;
|
|
293
315
|
}
|
|
294
316
|
/**
|
|
295
317
|
* Build the public mockup image URL. Pure + synchronous — drop the result
|
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-IL3FXE2X.js";
|
|
15
15
|
|
|
16
16
|
// src/validation.ts
|
|
17
17
|
import { z } from "zod";
|
|
@@ -550,12 +550,17 @@ function getMockupUrl(a, b, c) {
|
|
|
550
550
|
{
|
|
551
551
|
productCode,
|
|
552
552
|
shop: opts.shop,
|
|
553
|
+
// ADR-0089 base+override: the `asset` base and the `design`/`placements`
|
|
554
|
+
// override map COMPOSE (the builder merges them). `placements` is the
|
|
555
|
+
// preferred override name; `design` is the legacy alias.
|
|
553
556
|
...opts.design ? { design: opts.design } : {},
|
|
557
|
+
...opts.placements ? { placements: opts.placements } : {},
|
|
554
558
|
...assetUrl !== void 0 ? { assetUrl } : {},
|
|
555
559
|
...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
|
|
556
560
|
...opts.options ? { options: opts.options } : {},
|
|
557
561
|
...opts.width !== void 0 ? { width: opts.width } : {},
|
|
558
562
|
...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
|
|
563
|
+
...opts.bg !== void 0 ? { bg: opts.bg } : {},
|
|
559
564
|
...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
|
|
560
565
|
...opts.variant !== void 0 ? { variant: opts.variant } : {},
|
|
561
566
|
...opts.placement !== void 0 ? { placement: opts.placement } : {}
|
package/dist/server.cjs
CHANGED
|
@@ -60,6 +60,13 @@ var PARAMS = {
|
|
|
60
60
|
width: "width",
|
|
61
61
|
grain: "grain",
|
|
62
62
|
aspect: "aspect",
|
|
63
|
+
/**
|
|
64
|
+
* Background color (6-hex, no '#') painted behind the mockup — visible only
|
|
65
|
+
* where the mockup itself has transparency (studio-cutout shots) — or the
|
|
66
|
+
* reserved `transparent` token, which suppresses the shop default for this
|
|
67
|
+
* one render. Absent = the shop's configured default, else transparent.
|
|
68
|
+
*/
|
|
69
|
+
bg: "bg",
|
|
63
70
|
/** Live preview/calibration mask overrides (not cached). */
|
|
64
71
|
maskOverrides: "maskOverrides",
|
|
65
72
|
/**
|
|
@@ -83,6 +90,7 @@ var PUBLIC_PARAM_NAMES = [
|
|
|
83
90
|
PARAMS.mockup,
|
|
84
91
|
PARAMS.width,
|
|
85
92
|
PARAMS.aspect,
|
|
93
|
+
PARAMS.bg,
|
|
86
94
|
PARAMS.signature
|
|
87
95
|
];
|
|
88
96
|
function canonicalForSig(url) {
|
package/dist/server.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"description": "Snowcone SDK for product mockups and print-on-demand",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"merch",
|
|
@@ -85,7 +85,7 @@
|
|
|
85
85
|
"tsup": "^8.1.0",
|
|
86
86
|
"typescript": "^5.5.4",
|
|
87
87
|
"vitest": "^2.0.5",
|
|
88
|
-
"@snowcone-app/mockup-url": "0.
|
|
88
|
+
"@snowcone-app/mockup-url": "0.3.0"
|
|
89
89
|
},
|
|
90
90
|
"engines": {
|
|
91
91
|
"node": ">=18"
|