@snowcone-app/sdk 0.15.0 → 0.16.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.16.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#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).
8
+
3
9
  ## 0.15.0
4
10
 
5
11
  ### Minor Changes
@@ -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
+ * rendercenter is unchanged.
23
+ */
24
+ page: "page",
16
25
  variant: "variant",
17
26
  mockup: "mockup",
18
27
  width: "width",
@@ -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
+ * rendercenter is unchanged.
502
+ */
503
+ page: "page",
495
504
  variant: "variant",
496
505
  mockup: "mockup",
497
506
  width: "width",
@@ -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,
@@ -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
  /**
@@ -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
  /**
@@ -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-IUFDVHRZ.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -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
+ * rendercenter is unchanged.
54
+ */
55
+ page: "page",
47
56
  variant: "variant",
48
57
  mockup: "mockup",
49
58
  width: "width",
@@ -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-IUFDVHRZ.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.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.1.1"
88
+ "@snowcone-app/mockup-url": "0.2.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"