@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 +12 -0
- package/README.md +2 -2
- package/dist/{chunk-XBDTD2I2.js → chunk-7DRH6S4D.js} +15 -2
- package/dist/index.cjs +25 -4
- package/dist/index.d.cts +30 -2
- package/dist/index.d.ts +30 -2
- package/dist/index.js +11 -3
- package/dist/server.cjs +12 -2
- package/dist/server.js +1 -1
- package/package.json +2 -2
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
|
|
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
|
|
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 }`.
|
|
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
|
|
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 }`.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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
|
|
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 }`.
|
|
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
|
|
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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/sdk",
|
|
3
|
-
"version": "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.
|
|
88
|
+
"@snowcone-app/mockup-url": "0.2.1"
|
|
89
89
|
},
|
|
90
90
|
"engines": {
|
|
91
91
|
"node": ">=18"
|