@snowcone-app/sdk 0.19.0 → 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 CHANGED
@@ -1,5 +1,26 @@
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
+
3
24
  ## 0.19.0
4
25
 
5
26
  ### Minor 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
  }
@@ -195,6 +220,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
195
220
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
196
221
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
197
222
  }
223
+ if (options.bg) {
224
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
225
+ }
198
226
  return `${base}${path}?${parts.join("&")}`;
199
227
  }
200
228
  var PUBLIC_PARAM_NAMES = [
@@ -207,6 +235,7 @@ var PUBLIC_PARAM_NAMES = [
207
235
  PARAMS.mockup,
208
236
  PARAMS.width,
209
237
  PARAMS.aspect,
238
+ PARAMS.bg,
210
239
  PARAMS.signature
211
240
  ];
212
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
  }
@@ -674,6 +699,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
674
699
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
675
700
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
676
701
  }
702
+ if (options.bg) {
703
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
704
+ }
677
705
  return `${base}${path}?${parts.join("&")}`;
678
706
  }
679
707
  var PUBLIC_PARAM_NAMES = [
@@ -686,6 +714,7 @@ var PUBLIC_PARAM_NAMES = [
686
714
  PARAMS.mockup,
687
715
  PARAMS.width,
688
716
  PARAMS.aspect,
717
+ PARAMS.bg,
689
718
  PARAMS.signature
690
719
  ];
691
720
  function canonicalForSig(url) {
@@ -960,6 +989,7 @@ function getMockupUrl(a, b, c) {
960
989
  ...opts.options ? { options: opts.options } : {},
961
990
  ...opts.width !== void 0 ? { width: opts.width } : {},
962
991
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
992
+ ...opts.bg !== void 0 ? { bg: opts.bg } : {},
963
993
  ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
964
994
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
965
995
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
package/dist/index.d.cts CHANGED
@@ -303,6 +303,15 @@ interface GetMockupUrlOptions {
303
303
  * dimensions; measure or crop client-side with `object-fit: cover`.
304
304
  */
305
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;
306
315
  }
307
316
  /**
308
317
  * Build the public mockup image URL. Pure + synchronous — drop the result
package/dist/index.d.ts CHANGED
@@ -303,6 +303,15 @@ interface GetMockupUrlOptions {
303
303
  * dimensions; measure or crop client-side with `object-fit: cover`.
304
304
  */
305
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;
306
315
  }
307
316
  /**
308
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-ZJW7HA5R.js";
14
+ } from "./chunk-IL3FXE2X.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -560,6 +560,7 @@ function getMockupUrl(a, b, c) {
560
560
  ...opts.options ? { options: opts.options } : {},
561
561
  ...opts.width !== void 0 ? { width: opts.width } : {},
562
562
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
563
+ ...opts.bg !== void 0 ? { bg: opts.bg } : {},
563
564
  ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
564
565
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
565
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
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-ZJW7HA5R.js";
4
+ } from "./chunk-IL3FXE2X.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.19.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.2.1"
88
+ "@snowcone-app/mockup-url": "0.3.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"