@snowcone-app/sdk 0.18.1 → 0.19.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,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.19.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#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.
8
+
3
9
  ## 0.18.1
4
10
 
5
11
  ### Patch Changes
@@ -147,28 +147,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
147
147
  const enc = encodeURIComponent;
148
148
  const parts = [];
149
149
  parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
150
- if (options.design) {
151
- for (const key of Object.keys(options.design).sort()) {
152
- const fill = options.design[key];
153
- const k = enc(key);
154
- if (typeof fill === "string") {
155
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
156
- } else if ("color" in fill) {
157
- parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
158
- } else {
159
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
160
- if (fill.tile !== void 0) {
161
- parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
162
- }
163
- if (fill.align !== void 0) {
164
- parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
150
+ if (options.designRef !== void 0) {
151
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
152
+ } else {
153
+ if (options.assetUrl !== void 0) {
154
+ parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
155
+ }
156
+ const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
157
+ if (overrides) {
158
+ for (const key of Object.keys(overrides).sort()) {
159
+ const fill = overrides[key];
160
+ const k = enc(key);
161
+ if (typeof fill === "string") {
162
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
163
+ } else if ("color" in fill) {
164
+ parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
165
+ } else {
166
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
167
+ if (fill.tile !== void 0) {
168
+ parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
169
+ }
170
+ if (fill.align !== void 0) {
171
+ parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
172
+ }
165
173
  }
166
174
  }
167
175
  }
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
176
  }
173
177
  if (options.placement !== void 0) {
174
178
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
package/dist/index.cjs CHANGED
@@ -626,28 +626,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
626
626
  const enc = encodeURIComponent;
627
627
  const parts = [];
628
628
  parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
629
- if (options.design) {
630
- for (const key of Object.keys(options.design).sort()) {
631
- const fill = options.design[key];
632
- const k = enc(key);
633
- if (typeof fill === "string") {
634
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
635
- } else if ("color" in fill) {
636
- parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
637
- } else {
638
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
639
- if (fill.tile !== void 0) {
640
- parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
641
- }
642
- if (fill.align !== void 0) {
643
- parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
629
+ if (options.designRef !== void 0) {
630
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
631
+ } else {
632
+ if (options.assetUrl !== void 0) {
633
+ parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
634
+ }
635
+ const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
636
+ if (overrides) {
637
+ for (const key of Object.keys(overrides).sort()) {
638
+ const fill = overrides[key];
639
+ const k = enc(key);
640
+ if (typeof fill === "string") {
641
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
642
+ } else if ("color" in fill) {
643
+ parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
644
+ } else {
645
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
646
+ if (fill.tile !== void 0) {
647
+ parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
648
+ }
649
+ if (fill.align !== void 0) {
650
+ parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
651
+ }
644
652
  }
645
653
  }
646
654
  }
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
655
  }
652
656
  if (options.placement !== void 0) {
653
657
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -946,7 +950,11 @@ function getMockupUrl(a, b, c) {
946
950
  {
947
951
  productCode,
948
952
  shop: opts.shop,
953
+ // ADR-0089 base+override: the `asset` base and the `design`/`placements`
954
+ // override map COMPOSE (the builder merges them). `placements` is the
955
+ // preferred override name; `design` is the legacy alias.
949
956
  ...opts.design ? { design: opts.design } : {},
957
+ ...opts.placements ? { placements: opts.placements } : {},
950
958
  ...assetUrl !== void 0 ? { assetUrl } : {},
951
959
  ...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
952
960
  ...opts.options ? { options: opts.options } : {},
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
- * Exactly one artwork source is expected for an image render: either a single
229
- * default-placement `asset`, OR a multi-placement `design` map. `design` takes
230
- * precedence if both are given.
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
- * Single default-placement image — the get-started shorthand. Emitted as the
241
- * readable `asset=` param. Ignored when {@link GetMockupUrlOptions.design} is
242
- * supplied.
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
- * Multi-placement design: a map of placement key → {@link Fill}. Emitted as
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. Takes precedence over `asset`.
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
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
- * Exactly one artwork source is expected for an image render: either a single
229
- * default-placement `asset`, OR a multi-placement `design` map. `design` takes
230
- * precedence if both are given.
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
- * Single default-placement image — the get-started shorthand. Emitted as the
241
- * readable `asset=` param. Ignored when {@link GetMockupUrlOptions.design} is
242
- * supplied.
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
- * Multi-placement design: a map of placement key → {@link Fill}. Emitted as
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. Takes precedence over `asset`.
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
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-7DRH6S4D.js";
14
+ } from "./chunk-ZJW7HA5R.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -550,7 +550,11 @@ 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 } : {},
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-7DRH6S4D.js";
4
+ } from "./chunk-ZJW7HA5R.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.18.1",
3
+ "version": "0.19.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",