@snowcone-app/sdk 0.15.0 → 0.16.1

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,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.16.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#731](https://github.com/snowcone-app/snowcone-monorepo/pull/731) [`89893bc`](https://github.com/snowcone-app/snowcone-monorepo/commit/89893bc6e492d152dbd42d4887b5cd5c4cd51eb8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - docs: describe the realtime render in interface terms — READMEs and JSDoc now say the server "renders" your design and fetches referenced assets, with internal service/pipeline references removed from published text
8
+
9
+ ## 0.16.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#662](https://github.com/snowcone-app/snowcone-monorepo/pull/662) [`755ad1d`](https://github.com/snowcone-app/snowcone-monorepo/commit/755ad1dc55449c4ec2b0da0158ff411913dce832) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Semantic visual search for the designs catalog: every design gets an AI-generated visual caption (indexed + searchable) and the index carries an embedder, so descriptive queries like "pink cowgirl boots on the moon" match designs regardless of publisher metadata. `searchDesigns` (SDK) and `snowcone_search_designs` (MCP) now send hybrid keyword+semantic search by default — tune with `semanticRatio` / `semantic_ratio` (0 = keyword-only).
14
+
3
15
  ## 0.15.0
4
16
 
5
17
  ### Minor Changes
package/README.md CHANGED
@@ -174,9 +174,9 @@ See [Public or signed](https://developers.snowcone.app/get-started) for the full
174
174
  `getMockupUrl` composites **one** artwork onto a product. For a full multi-layer
175
175
  design — the kind the Snowcone canvas editor produces — use a **`RenderSession`**:
176
176
  the browser sends a ~1 KB description of the canvas (or just a saved design's id)
177
- over a WebSocket, and the server rasterizes it and **fetches the referenced assets
177
+ over a WebSocket, and the server renders the mockup and **fetches the referenced assets
178
178
  itself**. No per-placement PNG is ever uploaded, so it's fast on thin/mobile
179
- clients. This is exactly how the Snowcone PDP renders mockups (see ADR-0079).
179
+ clients. This is exactly how the Snowcone PDP renders mockups.
180
180
 
181
181
  Authorize the session with a short-lived **grant**. Mint it server-side with a
182
182
  secret API key (`sk_…`, scope `mockups:realtime`) so the key never reaches the
@@ -13,6 +13,15 @@ var PARAMS = {
13
13
  */
14
14
  design: "design",
15
15
  placement: "placement",
16
+ /**
17
+ * Album page selector (ADR-0086 §5): `page=N` (positive integer) picks which
18
+ * page/spread of an album product a mockup renders. Only valid on products
19
+ * whose catalog entry carries an `album` block — the edge resolver maps page
20
+ * N onto the repeating page placement (`page_N` → the geometry of
21
+ * `album.pagePlacement`); the catalog never enumerates `page_1…page_100` and
22
+ * the render server is unchanged.
23
+ */
24
+ page: "page",
16
25
  variant: "variant",
17
26
  mockup: "mockup",
18
27
  width: "width",
@@ -22,10 +31,10 @@ var PARAMS = {
22
31
  maskOverrides: "maskOverrides",
23
32
  /**
24
33
  * Render-only option picks (the `affectsCombinations:false` attributes), as a
25
- * base64 JSON map `{ attributeName: choiceLabel }`. rendercenter already parses
34
+ * base64 JSON map `{ attributeName: choiceLabel }`. The render server already parses
26
35
  * this and resolves per-choice underlays from it; the builder emits it so the
27
36
  * edge resolver can forward render-only picks (e.g. a cap's Crown/Strap color)
28
- * without changing rendercenter's grammar.
37
+ * without changing the server grammar.
29
38
  */
30
39
  optionSelections: "optionSelections",
31
40
  signature: "signature",
@@ -164,6 +173,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
164
173
  if (options.placement !== void 0) {
165
174
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
166
175
  }
176
+ if (options.page !== void 0) {
177
+ parts.push(`${PARAMS.page}=${options.page}`);
178
+ }
167
179
  if (options.options) {
168
180
  for (const attr of Object.keys(options.options).sort()) {
169
181
  parts.push(`${PARAM_PREFIX.opt}${enc(attr)}=${enc(options.options[attr])}`);
@@ -186,6 +198,7 @@ var PUBLIC_PARAM_NAMES = [
186
198
  PARAMS.design,
187
199
  PARAMS.shop,
188
200
  PARAMS.placement,
201
+ PARAMS.page,
189
202
  PARAMS.variant,
190
203
  PARAMS.mockup,
191
204
  PARAMS.width,
package/dist/index.cjs CHANGED
@@ -492,6 +492,15 @@ var PARAMS = {
492
492
  */
493
493
  design: "design",
494
494
  placement: "placement",
495
+ /**
496
+ * Album page selector (ADR-0086 §5): `page=N` (positive integer) picks which
497
+ * page/spread of an album product a mockup renders. Only valid on products
498
+ * whose catalog entry carries an `album` block — the edge resolver maps page
499
+ * N onto the repeating page placement (`page_N` → the geometry of
500
+ * `album.pagePlacement`); the catalog never enumerates `page_1…page_100` and
501
+ * the render server is unchanged.
502
+ */
503
+ page: "page",
495
504
  variant: "variant",
496
505
  mockup: "mockup",
497
506
  width: "width",
@@ -501,10 +510,10 @@ var PARAMS = {
501
510
  maskOverrides: "maskOverrides",
502
511
  /**
503
512
  * Render-only option picks (the `affectsCombinations:false` attributes), as a
504
- * base64 JSON map `{ attributeName: choiceLabel }`. rendercenter already parses
513
+ * base64 JSON map `{ attributeName: choiceLabel }`. The render server already parses
505
514
  * this and resolves per-choice underlays from it; the builder emits it so the
506
515
  * edge resolver can forward render-only picks (e.g. a cap's Crown/Strap color)
507
- * without changing rendercenter's grammar.
516
+ * without changing the server grammar.
508
517
  */
509
518
  optionSelections: "optionSelections",
510
519
  signature: "signature",
@@ -643,6 +652,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
643
652
  if (options.placement !== void 0) {
644
653
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
645
654
  }
655
+ if (options.page !== void 0) {
656
+ parts.push(`${PARAMS.page}=${options.page}`);
657
+ }
646
658
  if (options.options) {
647
659
  for (const attr of Object.keys(options.options).sort()) {
648
660
  parts.push(`${PARAM_PREFIX.opt}${enc(attr)}=${enc(options.options[attr])}`);
@@ -665,6 +677,7 @@ var PUBLIC_PARAM_NAMES = [
665
677
  PARAMS.design,
666
678
  PARAMS.shop,
667
679
  PARAMS.placement,
680
+ PARAMS.page,
668
681
  PARAMS.variant,
669
682
  PARAMS.mockup,
670
683
  PARAMS.width,
@@ -5948,7 +5961,7 @@ var RenderSession = class {
5948
5961
  return this.ready;
5949
5962
  }
5950
5963
  /**
5951
- * Render a canvas state for a placement. The server rasterizes it and fetches
5964
+ * Render a canvas state for a placement. The server renders it and fetches
5952
5965
  * the assets referenced inside — no pixels are uploaded. Results arrive via
5953
5966
  * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
5954
5967
  * canvas edit); pass `throttleMs` to throttle during live dragging. The
@@ -6241,7 +6254,15 @@ async function searchDesigns(query = "", options) {
6241
6254
  q: query,
6242
6255
  limit: options?.limit || 50,
6243
6256
  ...options?.offset ? { offset: options.offset } : {},
6244
- ...options?.filter ? { filter: options.filter } : {}
6257
+ ...options?.filter ? { filter: options.filter } : {},
6258
+ // Hybrid semantic search over the AI visual captions (default on for
6259
+ // real queries; an empty q is a plain listing).
6260
+ ...query && (options?.semanticRatio ?? 0.5) > 0 ? {
6261
+ hybrid: {
6262
+ embedder: "default",
6263
+ semanticRatio: options?.semanticRatio ?? 0.5
6264
+ }
6265
+ } : {}
6245
6266
  })
6246
6267
  });
6247
6268
  if (!res.ok) throw new Error(`searchDesigns failed: ${res.status}`);
package/dist/index.d.cts CHANGED
@@ -96,6 +96,27 @@ interface CatalogProduct {
96
96
  autoFilledByVariant: boolean;
97
97
  }[];
98
98
  defaultGvid?: string | null;
99
+ /**
100
+ * ADR-0086: marks an album/book product whose single page placement repeats. Consumers (edge resolver, buy worker, supplier export) expand `page_1..page_N` on demand from `pageExtent` — catalog documents never enumerate pages. Additive: products without this block are unaffected.
101
+ */
102
+ album?: {
103
+ /**
104
+ * Wire `key` of the repeating page placement (e.g. "page"). Page N is addressed as `<pagePlacement>_N` and resolves to this placement's geometry.
105
+ */
106
+ pagePlacement: string;
107
+ /**
108
+ * Name of the `options.attributes` entry that carries the page count (e.g. "Pages"). An ordinary affectsCombinations axis — combinations stay Size × Pages rows.
109
+ */
110
+ pageAxis: string;
111
+ /**
112
+ * Buyable page counts: min..max in increments of step.
113
+ */
114
+ pageExtent: {
115
+ min: number;
116
+ max: number;
117
+ step: number;
118
+ };
119
+ };
99
120
  }
100
121
 
101
122
  /**
@@ -2650,7 +2671,7 @@ declare class SvelteAdapter implements FrameworkAdapter<ComponentProps> {
2650
2671
  declare function createSvelteComponent(descriptor: ComponentDescriptor, svelte: any): any;
2651
2672
 
2652
2673
  /**
2653
- * Production realtime render WebSocket endpoint (the rendercenter edge).
2674
+ * Production realtime render WebSocket endpoint (the realtime render edge).
2654
2675
  *
2655
2676
  * This is the value to connect to for server-side canvas rendering — open
2656
2677
  * `${REALTIME_WS_URL}?token=<grant>`. Replaces the old un-discoverable
@@ -3016,7 +3037,7 @@ declare class RenderSession {
3016
3037
  */
3017
3038
  connect(): Promise<void>;
3018
3039
  /**
3019
- * Render a canvas state for a placement. The server rasterizes it and fetches
3040
+ * Render a canvas state for a placement. The server renders it and fetches
3020
3041
  * the assets referenced inside — no pixels are uploaded. Results arrive via
3021
3042
  * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
3022
3043
  * canvas edit); pass `throttleMs` to throttle during live dragging. The
@@ -3238,6 +3259,13 @@ interface SearchDesignsOptions extends Partial<SdkConfig> {
3238
3259
  offset?: number;
3239
3260
  /** Meilisearch filter, e.g. "occasion = 'christmas' AND style = 'watercolor'". */
3240
3261
  filter?: string;
3262
+ /**
3263
+ * Hybrid (semantic + keyword) blend, 0..1. The index carries an embedder
3264
+ * over each design's AI visual caption, so descriptive queries ("pink
3265
+ * cowgirl boots on the moon") match designs whose metadata never said so.
3266
+ * Default 0.5 for non-empty queries; pass 0 for keyword-only.
3267
+ */
3268
+ semanticRatio?: number;
3241
3269
  }
3242
3270
  interface SnowconeClient {
3243
3271
  catalog: {
package/dist/index.d.ts CHANGED
@@ -96,6 +96,27 @@ interface CatalogProduct {
96
96
  autoFilledByVariant: boolean;
97
97
  }[];
98
98
  defaultGvid?: string | null;
99
+ /**
100
+ * ADR-0086: marks an album/book product whose single page placement repeats. Consumers (edge resolver, buy worker, supplier export) expand `page_1..page_N` on demand from `pageExtent` — catalog documents never enumerate pages. Additive: products without this block are unaffected.
101
+ */
102
+ album?: {
103
+ /**
104
+ * Wire `key` of the repeating page placement (e.g. "page"). Page N is addressed as `<pagePlacement>_N` and resolves to this placement's geometry.
105
+ */
106
+ pagePlacement: string;
107
+ /**
108
+ * Name of the `options.attributes` entry that carries the page count (e.g. "Pages"). An ordinary affectsCombinations axis — combinations stay Size × Pages rows.
109
+ */
110
+ pageAxis: string;
111
+ /**
112
+ * Buyable page counts: min..max in increments of step.
113
+ */
114
+ pageExtent: {
115
+ min: number;
116
+ max: number;
117
+ step: number;
118
+ };
119
+ };
99
120
  }
100
121
 
101
122
  /**
@@ -2650,7 +2671,7 @@ declare class SvelteAdapter implements FrameworkAdapter<ComponentProps> {
2650
2671
  declare function createSvelteComponent(descriptor: ComponentDescriptor, svelte: any): any;
2651
2672
 
2652
2673
  /**
2653
- * Production realtime render WebSocket endpoint (the rendercenter edge).
2674
+ * Production realtime render WebSocket endpoint (the realtime render edge).
2654
2675
  *
2655
2676
  * This is the value to connect to for server-side canvas rendering — open
2656
2677
  * `${REALTIME_WS_URL}?token=<grant>`. Replaces the old un-discoverable
@@ -3016,7 +3037,7 @@ declare class RenderSession {
3016
3037
  */
3017
3038
  connect(): Promise<void>;
3018
3039
  /**
3019
- * Render a canvas state for a placement. The server rasterizes it and fetches
3040
+ * Render a canvas state for a placement. The server renders it and fetches
3020
3041
  * the assets referenced inside — no pixels are uploaded. Results arrive via
3021
3042
  * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
3022
3043
  * canvas edit); pass `throttleMs` to throttle during live dragging. The
@@ -3238,6 +3259,13 @@ interface SearchDesignsOptions extends Partial<SdkConfig> {
3238
3259
  offset?: number;
3239
3260
  /** Meilisearch filter, e.g. "occasion = 'christmas' AND style = 'watercolor'". */
3240
3261
  filter?: string;
3262
+ /**
3263
+ * Hybrid (semantic + keyword) blend, 0..1. The index carries an embedder
3264
+ * over each design's AI visual caption, so descriptive queries ("pink
3265
+ * cowgirl boots on the moon") match designs whose metadata never said so.
3266
+ * Default 0.5 for non-empty queries; pass 0 for keyword-only.
3267
+ */
3268
+ semanticRatio?: number;
3241
3269
  }
3242
3270
  interface SnowconeClient {
3243
3271
  catalog: {
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-XBDTD2I2.js";
14
+ } from "./chunk-7DRH6S4D.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -4807,7 +4807,7 @@ var RenderSession = class {
4807
4807
  return this.ready;
4808
4808
  }
4809
4809
  /**
4810
- * Render a canvas state for a placement. The server rasterizes it and fetches
4810
+ * Render a canvas state for a placement. The server renders it and fetches
4811
4811
  * the assets referenced inside — no pixels are uploaded. Results arrive via
4812
4812
  * {@link RenderSession.onMockups}. Safe to call repeatedly (e.g. on every
4813
4813
  * canvas edit); pass `throttleMs` to throttle during live dragging. The
@@ -5100,7 +5100,15 @@ async function searchDesigns(query = "", options) {
5100
5100
  q: query,
5101
5101
  limit: options?.limit || 50,
5102
5102
  ...options?.offset ? { offset: options.offset } : {},
5103
- ...options?.filter ? { filter: options.filter } : {}
5103
+ ...options?.filter ? { filter: options.filter } : {},
5104
+ // Hybrid semantic search over the AI visual captions (default on for
5105
+ // real queries; an empty q is a plain listing).
5106
+ ...query && (options?.semanticRatio ?? 0.5) > 0 ? {
5107
+ hybrid: {
5108
+ embedder: "default",
5109
+ semanticRatio: options?.semanticRatio ?? 0.5
5110
+ }
5111
+ } : {}
5104
5112
  })
5105
5113
  });
5106
5114
  if (!res.ok) throw new Error(`searchDesigns failed: ${res.status}`);
package/dist/server.cjs CHANGED
@@ -44,6 +44,15 @@ var PARAMS = {
44
44
  */
45
45
  design: "design",
46
46
  placement: "placement",
47
+ /**
48
+ * Album page selector (ADR-0086 §5): `page=N` (positive integer) picks which
49
+ * page/spread of an album product a mockup renders. Only valid on products
50
+ * whose catalog entry carries an `album` block — the edge resolver maps page
51
+ * N onto the repeating page placement (`page_N` → the geometry of
52
+ * `album.pagePlacement`); the catalog never enumerates `page_1…page_100` and
53
+ * the render server is unchanged.
54
+ */
55
+ page: "page",
47
56
  variant: "variant",
48
57
  mockup: "mockup",
49
58
  width: "width",
@@ -53,10 +62,10 @@ var PARAMS = {
53
62
  maskOverrides: "maskOverrides",
54
63
  /**
55
64
  * Render-only option picks (the `affectsCombinations:false` attributes), as a
56
- * base64 JSON map `{ attributeName: choiceLabel }`. rendercenter already parses
65
+ * base64 JSON map `{ attributeName: choiceLabel }`. The render server already parses
57
66
  * this and resolves per-choice underlays from it; the builder emits it so the
58
67
  * edge resolver can forward render-only picks (e.g. a cap's Crown/Strap color)
59
- * without changing rendercenter's grammar.
68
+ * without changing the server grammar.
60
69
  */
61
70
  optionSelections: "optionSelections",
62
71
  signature: "signature",
@@ -67,6 +76,7 @@ var PUBLIC_PARAM_NAMES = [
67
76
  PARAMS.design,
68
77
  PARAMS.shop,
69
78
  PARAMS.placement,
79
+ PARAMS.page,
70
80
  PARAMS.variant,
71
81
  PARAMS.mockup,
72
82
  PARAMS.width,
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-XBDTD2I2.js";
4
+ } from "./chunk-7DRH6S4D.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.15.0",
3
+ "version": "0.16.1",
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.1.1"
88
+ "@snowcone-app/mockup-url": "0.2.1"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"