@snowcone-app/sdk 0.9.1 → 0.11.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 +12 -0
- package/dist/index.cjs +96 -1
- package/dist/index.d.cts +136 -13
- package/dist/index.d.ts +136 -13
- package/dist/index.js +90 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.11.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#591](https://github.com/snowcone-app/snowcone-monorepo/pull/591) [`f15c421`](https://github.com/snowcone-app/snowcone-monorepo/commit/f15c421f11a793064fc5471f3286760f393ac4d7) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Upload grants (ADR-0084): `uploadAsset`, `mintUploadGrant`, and `fetchUploadGrant` extend the realtime grant pattern to user-image uploads, so a static page can accept a shopper's logo with no proxy backend. `uploadAsset(file, { shop })` mints a short-lived grant (keyless publishable path, or sk\_/`grantUrl` for the server-side path), uploads the image, and returns a URL on the shop's own storage origin — already inside the asset-origin allowlist, ready for `getMockupUrl`/`getBuyUrl`.
|
|
8
|
+
|
|
9
|
+
## 0.10.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- [#588](https://github.com/snowcone-app/snowcone-monorepo/pull/588) [`e1e9b7e`](https://github.com/snowcone-app/snowcone-monorepo/commit/e1e9b7e716d0d33c763e6a633ee540cd2aa24408) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Add `getBuyUrl` — the hosted-checkout twin of `getMockupUrl` (same options shape, `buy.snowcone.app` host) — and correct the `aspect`/`width` JSDoc: `aspect` is an opt-in center-crop (`2:3`); omitted (or `16:9`) means no crop, so the image keeps the scene's native shape, and `width` snaps down with a default of 1400. `CatalogProduct` from the data-transformation and product-context modules is now the real generated catalog type instead of `any`.
|
|
14
|
+
|
|
3
15
|
## 0.9.1
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
package/dist/index.cjs
CHANGED
|
@@ -37,10 +37,12 @@ __export(index_exports, {
|
|
|
37
37
|
ContextSynchronizer: () => ContextSynchronizer,
|
|
38
38
|
DEFAULT_ARTWORK_URL: () => DEFAULT_ARTWORK_URL,
|
|
39
39
|
DEFAULT_ASPECT_RATIO: () => DEFAULT_ASPECT_RATIO,
|
|
40
|
+
DEFAULT_BUY_BASE: () => DEFAULT_BUY_BASE,
|
|
40
41
|
DEFAULT_COLOR: () => DEFAULT_COLOR,
|
|
41
42
|
DEFAULT_GRANT_BASE: () => DEFAULT_GRANT_BASE,
|
|
42
43
|
DEFAULT_MOCKUP_BASE: () => DEFAULT_MOCKUP_BASE,
|
|
43
44
|
DEFAULT_PLACEMENT_DIMENSIONS: () => DEFAULT_PLACEMENT_DIMENSIONS,
|
|
45
|
+
DEFAULT_UPLOAD_BASE: () => DEFAULT_UPLOAD_BASE,
|
|
44
46
|
Elements: () => Elements,
|
|
45
47
|
ErrorManager: () => ErrorManager,
|
|
46
48
|
EventDelegator: () => EventDelegator,
|
|
@@ -102,12 +104,14 @@ __export(index_exports, {
|
|
|
102
104
|
describeProductTitle: () => describeProductTitle,
|
|
103
105
|
extractProductId: () => extractProductId,
|
|
104
106
|
fetchRealtimeGrant: () => fetchRealtimeGrant,
|
|
107
|
+
fetchUploadGrant: () => fetchUploadGrant,
|
|
105
108
|
filterImagePlacements: () => filterImagePlacements,
|
|
106
109
|
findBestCombination: () => findBestCombination,
|
|
107
110
|
findClosestSnapPoint: () => findClosestSnapPoint,
|
|
108
111
|
findVariantForSelection: () => findVariantForSelection,
|
|
109
112
|
formatPrice: () => formatPrice,
|
|
110
113
|
formatValidationErrors: () => formatValidationErrors,
|
|
114
|
+
getBuyUrl: () => getBuyUrl,
|
|
111
115
|
getDefaultVariantId: () => getDefaultVariantId,
|
|
112
116
|
getEffectiveAlignment: () => getEffectiveAlignment,
|
|
113
117
|
getIncompleteSelectionMessage: () => getIncompleteSelectionMessage,
|
|
@@ -126,6 +130,7 @@ __export(index_exports, {
|
|
|
126
130
|
isValidTileCount: () => isValidTileCount,
|
|
127
131
|
listProducts: () => listProducts,
|
|
128
132
|
mintRealtimeGrant: () => mintRealtimeGrant,
|
|
133
|
+
mintUploadGrant: () => mintUploadGrant,
|
|
129
134
|
mockupUrl: () => mockupUrl,
|
|
130
135
|
normalizeChoice: () => normalizeChoice,
|
|
131
136
|
prepareOptionRenderData: () => prepareOptionRenderData,
|
|
@@ -137,6 +142,7 @@ __export(index_exports, {
|
|
|
137
142
|
simulateCartOperation: () => simulateCartOperation,
|
|
138
143
|
toCombinations: () => toCombinations,
|
|
139
144
|
toOptionAttributes: () => toOptionAttributes,
|
|
145
|
+
uploadAsset: () => uploadAsset,
|
|
140
146
|
useVueAdapter: () => useFrameworkAdapter,
|
|
141
147
|
validateAlignment: () => validateAlignment,
|
|
142
148
|
validateDesignElement: () => validateDesignElement,
|
|
@@ -982,6 +988,13 @@ function getMockupUrl(a, b, c) {
|
|
|
982
988
|
const signature = hmacSha256Hex(opts.secret, canonicalForSig(url)).slice(0, 16);
|
|
983
989
|
return `${url}&signature=${signature}`;
|
|
984
990
|
}
|
|
991
|
+
var DEFAULT_BUY_BASE = "https://buy.snowcone.app";
|
|
992
|
+
function getBuyUrl(productCode, opts) {
|
|
993
|
+
return getMockupUrl(productCode, {
|
|
994
|
+
...opts,
|
|
995
|
+
base: opts.base ?? DEFAULT_BUY_BASE
|
|
996
|
+
});
|
|
997
|
+
}
|
|
985
998
|
|
|
986
999
|
// src/mockup/bffSigner.ts
|
|
987
1000
|
function bffSigner(endpoint = "/api/sign", opts) {
|
|
@@ -3014,7 +3027,7 @@ var ProductLoader = class {
|
|
|
3014
3027
|
const { items } = await this.fetcher.listProducts(options);
|
|
3015
3028
|
const product = items?.[0];
|
|
3016
3029
|
if (product) {
|
|
3017
|
-
const productId = product.id
|
|
3030
|
+
const productId = product.id;
|
|
3018
3031
|
if (productId) {
|
|
3019
3032
|
this.cache.set(productId, product);
|
|
3020
3033
|
}
|
|
@@ -6100,6 +6113,82 @@ async function createDesignState(input) {
|
|
|
6100
6113
|
return { stateId: ds.id, stateUrl: ds.stateUrl ?? "", previewUrl: ds.previewUrl ?? "" };
|
|
6101
6114
|
}
|
|
6102
6115
|
|
|
6116
|
+
// src/upload/grant.ts
|
|
6117
|
+
var DEFAULT_UPLOAD_BASE = "https://api.snowcone.app";
|
|
6118
|
+
async function mintUploadGrant(opts) {
|
|
6119
|
+
const f = opts.fetch ?? globalThis.fetch;
|
|
6120
|
+
const headers = { "Content-Type": "application/json" };
|
|
6121
|
+
if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
|
|
6122
|
+
const res = await f(`${opts.base ?? DEFAULT_UPLOAD_BASE}/uploads/grant`, {
|
|
6123
|
+
method: "POST",
|
|
6124
|
+
headers,
|
|
6125
|
+
body: JSON.stringify({ shop: opts.shop })
|
|
6126
|
+
});
|
|
6127
|
+
if (!res.ok) {
|
|
6128
|
+
const detail = await res.text().catch(() => "");
|
|
6129
|
+
throw new Error(`upload grant failed: ${res.status}${detail ? ` ${detail}` : ""}`);
|
|
6130
|
+
}
|
|
6131
|
+
return await res.json();
|
|
6132
|
+
}
|
|
6133
|
+
async function fetchUploadGrant(grantUrl, shop, fetchImpl) {
|
|
6134
|
+
const f = fetchImpl ?? globalThis.fetch;
|
|
6135
|
+
const res = await f(grantUrl, {
|
|
6136
|
+
method: "POST",
|
|
6137
|
+
headers: { "Content-Type": "application/json" },
|
|
6138
|
+
body: JSON.stringify({ shop })
|
|
6139
|
+
});
|
|
6140
|
+
if (!res.ok) throw new Error(`upload grant failed: ${res.status}`);
|
|
6141
|
+
return await res.json();
|
|
6142
|
+
}
|
|
6143
|
+
async function toImageDataUrl(image) {
|
|
6144
|
+
if (typeof image === "string") {
|
|
6145
|
+
if (/^data:image\/\w+;base64,/.test(image)) return image;
|
|
6146
|
+
throw new Error(
|
|
6147
|
+
"uploadAsset: a string image must be a data:image/\u2026;base64 URL (pass a Blob/File otherwise)"
|
|
6148
|
+
);
|
|
6149
|
+
}
|
|
6150
|
+
const bytes = new Uint8Array(await image.arrayBuffer());
|
|
6151
|
+
const type = image.type?.startsWith("image/") ? image.type : "image/png";
|
|
6152
|
+
const B = globalThis.Buffer;
|
|
6153
|
+
let base64;
|
|
6154
|
+
if (B) {
|
|
6155
|
+
base64 = B.from(bytes).toString("base64");
|
|
6156
|
+
} else {
|
|
6157
|
+
let bin = "";
|
|
6158
|
+
const CHUNK = 32768;
|
|
6159
|
+
for (let i = 0; i < bytes.length; i += CHUNK) {
|
|
6160
|
+
bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
|
|
6161
|
+
}
|
|
6162
|
+
base64 = btoa(bin);
|
|
6163
|
+
}
|
|
6164
|
+
return `data:${type};base64,${base64}`;
|
|
6165
|
+
}
|
|
6166
|
+
async function uploadAsset(image, opts) {
|
|
6167
|
+
const f = opts.fetch ?? globalThis.fetch;
|
|
6168
|
+
const base = opts.base ?? DEFAULT_UPLOAD_BASE;
|
|
6169
|
+
const base64Image = await toImageDataUrl(image);
|
|
6170
|
+
let token;
|
|
6171
|
+
if (opts.grant) {
|
|
6172
|
+
token = typeof opts.grant === "string" ? opts.grant : opts.grant.token;
|
|
6173
|
+
} else {
|
|
6174
|
+
if (!opts.shop) {
|
|
6175
|
+
throw new Error("uploadAsset: `shop` is required unless a `grant` is given");
|
|
6176
|
+
}
|
|
6177
|
+
const grant = opts.grantUrl ? await fetchUploadGrant(opts.grantUrl, opts.shop, f) : await mintUploadGrant({ apiKey: opts.apiKey, shop: opts.shop, base, fetch: f });
|
|
6178
|
+
token = grant.token;
|
|
6179
|
+
}
|
|
6180
|
+
const res = await f(`${base}/uploads/grant/base64`, {
|
|
6181
|
+
method: "POST",
|
|
6182
|
+
headers: { "Content-Type": "application/json" },
|
|
6183
|
+
body: JSON.stringify({ token, base64Image })
|
|
6184
|
+
});
|
|
6185
|
+
if (!res.ok) {
|
|
6186
|
+
const detail = await res.text().catch(() => "");
|
|
6187
|
+
throw new Error(`upload failed: ${res.status}${detail ? ` ${detail}` : ""}`);
|
|
6188
|
+
}
|
|
6189
|
+
return await res.json();
|
|
6190
|
+
}
|
|
6191
|
+
|
|
6103
6192
|
// src/index.ts
|
|
6104
6193
|
function getFetcher(config) {
|
|
6105
6194
|
return config?.fetcher || globalThis.fetch.bind(globalThis);
|
|
@@ -6191,10 +6280,12 @@ function createClient(config) {
|
|
|
6191
6280
|
ContextSynchronizer,
|
|
6192
6281
|
DEFAULT_ARTWORK_URL,
|
|
6193
6282
|
DEFAULT_ASPECT_RATIO,
|
|
6283
|
+
DEFAULT_BUY_BASE,
|
|
6194
6284
|
DEFAULT_COLOR,
|
|
6195
6285
|
DEFAULT_GRANT_BASE,
|
|
6196
6286
|
DEFAULT_MOCKUP_BASE,
|
|
6197
6287
|
DEFAULT_PLACEMENT_DIMENSIONS,
|
|
6288
|
+
DEFAULT_UPLOAD_BASE,
|
|
6198
6289
|
Elements,
|
|
6199
6290
|
ErrorManager,
|
|
6200
6291
|
EventDelegator,
|
|
@@ -6256,12 +6347,14 @@ function createClient(config) {
|
|
|
6256
6347
|
describeProductTitle,
|
|
6257
6348
|
extractProductId,
|
|
6258
6349
|
fetchRealtimeGrant,
|
|
6350
|
+
fetchUploadGrant,
|
|
6259
6351
|
filterImagePlacements,
|
|
6260
6352
|
findBestCombination,
|
|
6261
6353
|
findClosestSnapPoint,
|
|
6262
6354
|
findVariantForSelection,
|
|
6263
6355
|
formatPrice,
|
|
6264
6356
|
formatValidationErrors,
|
|
6357
|
+
getBuyUrl,
|
|
6265
6358
|
getDefaultVariantId,
|
|
6266
6359
|
getEffectiveAlignment,
|
|
6267
6360
|
getIncompleteSelectionMessage,
|
|
@@ -6280,6 +6373,7 @@ function createClient(config) {
|
|
|
6280
6373
|
isValidTileCount,
|
|
6281
6374
|
listProducts,
|
|
6282
6375
|
mintRealtimeGrant,
|
|
6376
|
+
mintUploadGrant,
|
|
6283
6377
|
mockupUrl,
|
|
6284
6378
|
normalizeChoice,
|
|
6285
6379
|
prepareOptionRenderData,
|
|
@@ -6291,6 +6385,7 @@ function createClient(config) {
|
|
|
6291
6385
|
simulateCartOperation,
|
|
6292
6386
|
toCombinations,
|
|
6293
6387
|
toOptionAttributes,
|
|
6388
|
+
uploadAsset,
|
|
6294
6389
|
useVueAdapter,
|
|
6295
6390
|
validateAlignment,
|
|
6296
6391
|
validateDesignElement,
|
package/dist/index.d.cts
CHANGED
|
@@ -3,7 +3,7 @@ import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-ur
|
|
|
3
3
|
import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-X4tcUm78.cjs';
|
|
4
4
|
export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-X4tcUm78.cjs';
|
|
5
5
|
|
|
6
|
-
interface CatalogProduct
|
|
6
|
+
interface CatalogProduct {
|
|
7
7
|
id: string;
|
|
8
8
|
name: string;
|
|
9
9
|
slug: string;
|
|
@@ -240,7 +240,12 @@ interface GetMockupUrlOptions {
|
|
|
240
240
|
secret?: string;
|
|
241
241
|
/** Override the public host. Default: `https://img.snowcone.app`. */
|
|
242
242
|
base?: string;
|
|
243
|
-
/**
|
|
243
|
+
/**
|
|
244
|
+
* Render width in px. Snaps DOWN to the nearest allowed size
|
|
245
|
+
* (400 600 800 1000 1200 1400 1600 1800 2000 2500 3000 4000); omitted →
|
|
246
|
+
* 1400. Height follows from the scene shape — see
|
|
247
|
+
* {@link GetMockupUrlOptions.aspect}.
|
|
248
|
+
*/
|
|
244
249
|
width?: number;
|
|
245
250
|
/** Camera view / mockup scene override (`view=<mockupId>`). Emitted as `mockup=`. */
|
|
246
251
|
view?: string;
|
|
@@ -250,7 +255,12 @@ interface GetMockupUrlOptions {
|
|
|
250
255
|
variant?: string;
|
|
251
256
|
/** Specific placement label override (only meaningful with a single `asset`). */
|
|
252
257
|
placement?: string;
|
|
253
|
-
/**
|
|
258
|
+
/**
|
|
259
|
+
* Center-crop of the mockup scene. `"2:3"` crops to portrait. `"16:9"` (or
|
|
260
|
+
* omitting it) applies NO crop: the image keeps the scene's native shape —
|
|
261
|
+
* 16:9 for most products, square for some — so don't assume the output
|
|
262
|
+
* dimensions; measure or crop client-side with `object-fit: cover`.
|
|
263
|
+
*/
|
|
254
264
|
aspect?: "16:9" | "2:3";
|
|
255
265
|
}
|
|
256
266
|
/**
|
|
@@ -271,6 +281,21 @@ interface GetMockupUrlOptions {
|
|
|
271
281
|
*/
|
|
272
282
|
declare function getMockupUrl(productCode: string, opts: GetMockupUrlOptions): string;
|
|
273
283
|
declare function getMockupUrl(assetUrl: string, productCode: string, opts: GetMockupUrlOptions): string;
|
|
284
|
+
/** Default public host for the hosted buy page. */
|
|
285
|
+
declare const DEFAULT_BUY_BASE = "https://buy.snowcone.app";
|
|
286
|
+
/**
|
|
287
|
+
* Build the hosted buy-page URL — the checkout counterpart of
|
|
288
|
+
* {@link getMockupUrl}. Same wire grammar, same options shape, different host:
|
|
289
|
+
* where the mockup URL renders the design as an image, this URL opens the
|
|
290
|
+
* Snowcone-hosted checkout with that exact design in the cart.
|
|
291
|
+
*
|
|
292
|
+
* const img = getMockupUrl("BEEB77", { shop, asset }); // the picture
|
|
293
|
+
* const buy = getBuyUrl("BEEB77", { shop, asset }); // the purchase
|
|
294
|
+
*
|
|
295
|
+
* Pure + synchronous, like `getMockupUrl` — drop the result into an
|
|
296
|
+
* `<a href>`. Pass `base` to override the host.
|
|
297
|
+
*/
|
|
298
|
+
declare function getBuyUrl(productCode: string, opts: GetMockupUrlOptions): string;
|
|
274
299
|
|
|
275
300
|
/**
|
|
276
301
|
* Client-side signer for `<Shop signMockupUrl={…}>` (signed / L3 shops).
|
|
@@ -920,32 +945,31 @@ declare function resolveMockupId(context: any, variantId: string, providedMockup
|
|
|
920
945
|
* Product data transformation utilities
|
|
921
946
|
* Converts catalog product data to component-friendly formats
|
|
922
947
|
*/
|
|
923
|
-
type CatalogProduct$1 = any;
|
|
924
948
|
|
|
925
949
|
/**
|
|
926
950
|
* Transforms product options attributes into the standard OptionAttribute format
|
|
927
951
|
* @param product - The catalog product from the API
|
|
928
952
|
* @returns Normalized option attributes with choice objects
|
|
929
953
|
*/
|
|
930
|
-
declare function toOptionAttributes(product?: CatalogProduct
|
|
954
|
+
declare function toOptionAttributes(product?: CatalogProduct): Record<string, OptionAttribute>;
|
|
931
955
|
/**
|
|
932
956
|
* Extracts combinations from product options
|
|
933
957
|
* @param product - The catalog product from the API
|
|
934
958
|
* @returns Array of valid combinations
|
|
935
959
|
*/
|
|
936
|
-
declare function toCombinations(product?: CatalogProduct
|
|
960
|
+
declare function toCombinations(product?: CatalogProduct): Combination[];
|
|
937
961
|
/**
|
|
938
962
|
* Extracts product ID from various possible locations in the product data
|
|
939
963
|
* @param product - The catalog product from the API
|
|
940
964
|
* @returns The product ID or undefined
|
|
941
965
|
*/
|
|
942
|
-
declare function extractProductId(product?: CatalogProduct
|
|
966
|
+
declare function extractProductId(product?: CatalogProduct): string | undefined;
|
|
943
967
|
/**
|
|
944
968
|
* Gets the default variant ID for a product
|
|
945
969
|
* @param product - The catalog product from the API
|
|
946
970
|
* @returns The default variant ID or 'default' as fallback
|
|
947
971
|
*/
|
|
948
|
-
declare function getDefaultVariantId(product?: CatalogProduct
|
|
972
|
+
declare function getDefaultVariantId(product?: CatalogProduct): string;
|
|
949
973
|
|
|
950
974
|
/**
|
|
951
975
|
* Product selection validation utilities
|
|
@@ -1433,7 +1457,6 @@ declare function createEventManager(element?: HTMLElement): ComponentEventManage
|
|
|
1433
1457
|
* Framework-agnostic product state and context handling
|
|
1434
1458
|
*/
|
|
1435
1459
|
|
|
1436
|
-
type CatalogProduct = any;
|
|
1437
1460
|
/**
|
|
1438
1461
|
* Product context interface
|
|
1439
1462
|
*/
|
|
@@ -3038,6 +3061,106 @@ interface CreatedDesignState {
|
|
|
3038
3061
|
*/
|
|
3039
3062
|
declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
|
|
3040
3063
|
|
|
3064
|
+
/**
|
|
3065
|
+
* Upload grant helpers — the realtime grant pattern (ADR-0079), extended to
|
|
3066
|
+
* asset uploads so the zero-backend story survives the first user-supplied
|
|
3067
|
+
* image. A static page can take a shopper's logo, upload it, and render it on
|
|
3068
|
+
* merchandise without any proxy server.
|
|
3069
|
+
*
|
|
3070
|
+
* A short-lived (5 min) grant token authorizes uploads into the shop's own
|
|
3071
|
+
* storage origin (`{shopId}.storage.snowcone.app`) — which is inside the
|
|
3072
|
+
* shop's asset-origin allowlist, so the returned URL drops straight into
|
|
3073
|
+
* `getMockupUrl` with zero further config. Three ways to get one, mirroring
|
|
3074
|
+
* the realtime grant exactly:
|
|
3075
|
+
*
|
|
3076
|
+
* - {@link mintUploadGrant} — SERVER-SIDE with a secret API key (sk_), or
|
|
3077
|
+
* keyless with just the publishable shop id.
|
|
3078
|
+
* - {@link fetchUploadGrant} — BROWSER, from your own proxy endpoint.
|
|
3079
|
+
* - {@link uploadAsset} — the one-call helper: resolves a grant however you
|
|
3080
|
+
* provide it, uploads the image, returns the hosted URL.
|
|
3081
|
+
*/
|
|
3082
|
+
/** A short-lived upload grant. */
|
|
3083
|
+
interface UploadGrant {
|
|
3084
|
+
/** Opaque token for `POST /uploads/grant/base64`. */
|
|
3085
|
+
token: string;
|
|
3086
|
+
/** Expiry, epoch seconds. Mint a fresh grant after this. */
|
|
3087
|
+
expiresAt: number;
|
|
3088
|
+
}
|
|
3089
|
+
/** Default backend base URL hosting `POST /uploads/grant`. */
|
|
3090
|
+
declare const DEFAULT_UPLOAD_BASE = "https://api.snowcone.app";
|
|
3091
|
+
/**
|
|
3092
|
+
* Mint an upload grant. Mirrors `mintRealtimeGrant`:
|
|
3093
|
+
*
|
|
3094
|
+
* Omit `apiKey` (or pass `undefined`/`null`/`''`) for the **keyless
|
|
3095
|
+
* publishable path** — the grant is authorized by the publishable `shop` id
|
|
3096
|
+
* alone (shops on the L3 signed-URLs rung must use a key or a signed grant
|
|
3097
|
+
* request instead). Pass a secret API key (sk_) with the `uploads:write`
|
|
3098
|
+
* scope to mint server-side; the key's organization must own the shop.
|
|
3099
|
+
*
|
|
3100
|
+
* @example
|
|
3101
|
+
* // keyless, straight from the browser — quick trials & sandbox shops:
|
|
3102
|
+
* const grant = await mintUploadGrant({ shop });
|
|
3103
|
+
*
|
|
3104
|
+
* @example
|
|
3105
|
+
* // your backend route: POST /api/upload/grant
|
|
3106
|
+
* const grant = await mintUploadGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
|
|
3107
|
+
* return Response.json(grant);
|
|
3108
|
+
*/
|
|
3109
|
+
declare function mintUploadGrant(opts: {
|
|
3110
|
+
/**
|
|
3111
|
+
* Secret API key (sk_) with the `uploads:write` scope. Omit (or pass
|
|
3112
|
+
* `undefined`/`null`/`''`) for the keyless publishable path.
|
|
3113
|
+
*/
|
|
3114
|
+
apiKey?: string | null;
|
|
3115
|
+
/** Target shop id (= shop.id). Uploads land in this shop's storage origin. */
|
|
3116
|
+
shop: string;
|
|
3117
|
+
/** Backend base URL. Defaults to {@link DEFAULT_UPLOAD_BASE}. */
|
|
3118
|
+
base?: string;
|
|
3119
|
+
/** Override fetch (e.g. in tests / non-global-fetch runtimes). */
|
|
3120
|
+
fetch?: typeof fetch;
|
|
3121
|
+
}): Promise<UploadGrant>;
|
|
3122
|
+
/**
|
|
3123
|
+
* BROWSER: fetch an upload grant from your own proxy endpoint, which calls
|
|
3124
|
+
* {@link mintUploadGrant} server-side (when you want the sk_ path without
|
|
3125
|
+
* shipping the key). The proxy receives `POST { shop }` and returns
|
|
3126
|
+
* `{ token, expiresAt }`.
|
|
3127
|
+
*/
|
|
3128
|
+
declare function fetchUploadGrant(grantUrl: string, shop: string, fetchImpl?: typeof fetch): Promise<UploadGrant>;
|
|
3129
|
+
/**
|
|
3130
|
+
* Upload an image and get back its hosted URL — ready to pass as `asset` to
|
|
3131
|
+
* `getMockupUrl` / `getBuyUrl` (it lands on the shop's own storage origin, so
|
|
3132
|
+
* it's already on the asset-origin allowlist).
|
|
3133
|
+
*
|
|
3134
|
+
* Provide auth in whichever shape fits:
|
|
3135
|
+
* - `{ shop }` alone — keyless publishable path (mints the grant for you),
|
|
3136
|
+
* - `{ shop, grantUrl }` — exchange via your own proxy endpoint,
|
|
3137
|
+
* - `{ shop, apiKey }` — server-side with an sk_ key,
|
|
3138
|
+
* - `{ grant }` — a grant you already hold (token reusable until it expires).
|
|
3139
|
+
*
|
|
3140
|
+
* @example
|
|
3141
|
+
* // a static page, no backend anywhere:
|
|
3142
|
+
* const { url } = await uploadAsset(fileInput.files[0], { shop });
|
|
3143
|
+
* img.src = getMockupUrl("BEEB77", { shop, asset: url });
|
|
3144
|
+
*/
|
|
3145
|
+
declare function uploadAsset(
|
|
3146
|
+
/** A `Blob`/`File`, or a `data:image/…;base64,` URL. */
|
|
3147
|
+
image: Blob | string, opts: {
|
|
3148
|
+
/** Target shop id. Required unless a pre-fetched `grant` is given. */
|
|
3149
|
+
shop?: string;
|
|
3150
|
+
/** A grant you already hold (or its raw token). Skips minting. */
|
|
3151
|
+
grant?: UploadGrant | string;
|
|
3152
|
+
/** Your own proxy endpoint that returns a grant (see {@link fetchUploadGrant}). */
|
|
3153
|
+
grantUrl?: string;
|
|
3154
|
+
/** Secret API key (sk_, scope `uploads:write`) for server-side minting. */
|
|
3155
|
+
apiKey?: string | null;
|
|
3156
|
+
/** Backend base URL. Defaults to {@link DEFAULT_UPLOAD_BASE}. */
|
|
3157
|
+
base?: string;
|
|
3158
|
+
/** Override fetch. */
|
|
3159
|
+
fetch?: typeof fetch;
|
|
3160
|
+
}): Promise<{
|
|
3161
|
+
url: string;
|
|
3162
|
+
}>;
|
|
3163
|
+
|
|
3041
3164
|
interface ProductPlacement {
|
|
3042
3165
|
label: string;
|
|
3043
3166
|
x: number;
|
|
@@ -3062,7 +3185,7 @@ interface ProductMockupData {
|
|
|
3062
3185
|
}
|
|
3063
3186
|
|
|
3064
3187
|
interface CatalogListResponse {
|
|
3065
|
-
items: CatalogProduct
|
|
3188
|
+
items: CatalogProduct[];
|
|
3066
3189
|
total: number;
|
|
3067
3190
|
}
|
|
3068
3191
|
|
|
@@ -3081,15 +3204,15 @@ interface SdkConfig {
|
|
|
3081
3204
|
interface SnowconeClient {
|
|
3082
3205
|
catalog: {
|
|
3083
3206
|
listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3084
|
-
getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct
|
|
3207
|
+
getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3085
3208
|
};
|
|
3086
3209
|
mockup: MockupService;
|
|
3087
3210
|
}
|
|
3088
3211
|
declare function listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3089
|
-
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct
|
|
3212
|
+
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3090
3213
|
/**
|
|
3091
3214
|
* Create a unified Snowcone client with catalog and mockup services
|
|
3092
3215
|
*/
|
|
3093
3216
|
declare function createClient(config: SdkConfig): SnowconeClient;
|
|
3094
3217
|
|
|
3095
|
-
export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct
|
|
3218
|
+
export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, DEFAULT_UPLOAD_BASE, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UploadGrant, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, fetchUploadGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mintUploadGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, uploadAsset, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
|
package/dist/index.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-ur
|
|
|
3
3
|
import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeMockupService } from './websocket-X4tcUm78.js';
|
|
4
4
|
export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-X4tcUm78.js';
|
|
5
5
|
|
|
6
|
-
interface CatalogProduct
|
|
6
|
+
interface CatalogProduct {
|
|
7
7
|
id: string;
|
|
8
8
|
name: string;
|
|
9
9
|
slug: string;
|
|
@@ -240,7 +240,12 @@ interface GetMockupUrlOptions {
|
|
|
240
240
|
secret?: string;
|
|
241
241
|
/** Override the public host. Default: `https://img.snowcone.app`. */
|
|
242
242
|
base?: string;
|
|
243
|
-
/**
|
|
243
|
+
/**
|
|
244
|
+
* Render width in px. Snaps DOWN to the nearest allowed size
|
|
245
|
+
* (400 600 800 1000 1200 1400 1600 1800 2000 2500 3000 4000); omitted →
|
|
246
|
+
* 1400. Height follows from the scene shape — see
|
|
247
|
+
* {@link GetMockupUrlOptions.aspect}.
|
|
248
|
+
*/
|
|
244
249
|
width?: number;
|
|
245
250
|
/** Camera view / mockup scene override (`view=<mockupId>`). Emitted as `mockup=`. */
|
|
246
251
|
view?: string;
|
|
@@ -250,7 +255,12 @@ interface GetMockupUrlOptions {
|
|
|
250
255
|
variant?: string;
|
|
251
256
|
/** Specific placement label override (only meaningful with a single `asset`). */
|
|
252
257
|
placement?: string;
|
|
253
|
-
/**
|
|
258
|
+
/**
|
|
259
|
+
* Center-crop of the mockup scene. `"2:3"` crops to portrait. `"16:9"` (or
|
|
260
|
+
* omitting it) applies NO crop: the image keeps the scene's native shape —
|
|
261
|
+
* 16:9 for most products, square for some — so don't assume the output
|
|
262
|
+
* dimensions; measure or crop client-side with `object-fit: cover`.
|
|
263
|
+
*/
|
|
254
264
|
aspect?: "16:9" | "2:3";
|
|
255
265
|
}
|
|
256
266
|
/**
|
|
@@ -271,6 +281,21 @@ interface GetMockupUrlOptions {
|
|
|
271
281
|
*/
|
|
272
282
|
declare function getMockupUrl(productCode: string, opts: GetMockupUrlOptions): string;
|
|
273
283
|
declare function getMockupUrl(assetUrl: string, productCode: string, opts: GetMockupUrlOptions): string;
|
|
284
|
+
/** Default public host for the hosted buy page. */
|
|
285
|
+
declare const DEFAULT_BUY_BASE = "https://buy.snowcone.app";
|
|
286
|
+
/**
|
|
287
|
+
* Build the hosted buy-page URL — the checkout counterpart of
|
|
288
|
+
* {@link getMockupUrl}. Same wire grammar, same options shape, different host:
|
|
289
|
+
* where the mockup URL renders the design as an image, this URL opens the
|
|
290
|
+
* Snowcone-hosted checkout with that exact design in the cart.
|
|
291
|
+
*
|
|
292
|
+
* const img = getMockupUrl("BEEB77", { shop, asset }); // the picture
|
|
293
|
+
* const buy = getBuyUrl("BEEB77", { shop, asset }); // the purchase
|
|
294
|
+
*
|
|
295
|
+
* Pure + synchronous, like `getMockupUrl` — drop the result into an
|
|
296
|
+
* `<a href>`. Pass `base` to override the host.
|
|
297
|
+
*/
|
|
298
|
+
declare function getBuyUrl(productCode: string, opts: GetMockupUrlOptions): string;
|
|
274
299
|
|
|
275
300
|
/**
|
|
276
301
|
* Client-side signer for `<Shop signMockupUrl={…}>` (signed / L3 shops).
|
|
@@ -920,32 +945,31 @@ declare function resolveMockupId(context: any, variantId: string, providedMockup
|
|
|
920
945
|
* Product data transformation utilities
|
|
921
946
|
* Converts catalog product data to component-friendly formats
|
|
922
947
|
*/
|
|
923
|
-
type CatalogProduct$1 = any;
|
|
924
948
|
|
|
925
949
|
/**
|
|
926
950
|
* Transforms product options attributes into the standard OptionAttribute format
|
|
927
951
|
* @param product - The catalog product from the API
|
|
928
952
|
* @returns Normalized option attributes with choice objects
|
|
929
953
|
*/
|
|
930
|
-
declare function toOptionAttributes(product?: CatalogProduct
|
|
954
|
+
declare function toOptionAttributes(product?: CatalogProduct): Record<string, OptionAttribute>;
|
|
931
955
|
/**
|
|
932
956
|
* Extracts combinations from product options
|
|
933
957
|
* @param product - The catalog product from the API
|
|
934
958
|
* @returns Array of valid combinations
|
|
935
959
|
*/
|
|
936
|
-
declare function toCombinations(product?: CatalogProduct
|
|
960
|
+
declare function toCombinations(product?: CatalogProduct): Combination[];
|
|
937
961
|
/**
|
|
938
962
|
* Extracts product ID from various possible locations in the product data
|
|
939
963
|
* @param product - The catalog product from the API
|
|
940
964
|
* @returns The product ID or undefined
|
|
941
965
|
*/
|
|
942
|
-
declare function extractProductId(product?: CatalogProduct
|
|
966
|
+
declare function extractProductId(product?: CatalogProduct): string | undefined;
|
|
943
967
|
/**
|
|
944
968
|
* Gets the default variant ID for a product
|
|
945
969
|
* @param product - The catalog product from the API
|
|
946
970
|
* @returns The default variant ID or 'default' as fallback
|
|
947
971
|
*/
|
|
948
|
-
declare function getDefaultVariantId(product?: CatalogProduct
|
|
972
|
+
declare function getDefaultVariantId(product?: CatalogProduct): string;
|
|
949
973
|
|
|
950
974
|
/**
|
|
951
975
|
* Product selection validation utilities
|
|
@@ -1433,7 +1457,6 @@ declare function createEventManager(element?: HTMLElement): ComponentEventManage
|
|
|
1433
1457
|
* Framework-agnostic product state and context handling
|
|
1434
1458
|
*/
|
|
1435
1459
|
|
|
1436
|
-
type CatalogProduct = any;
|
|
1437
1460
|
/**
|
|
1438
1461
|
* Product context interface
|
|
1439
1462
|
*/
|
|
@@ -3038,6 +3061,106 @@ interface CreatedDesignState {
|
|
|
3038
3061
|
*/
|
|
3039
3062
|
declare function createDesignState(input: CreateDesignStateInput): Promise<CreatedDesignState>;
|
|
3040
3063
|
|
|
3064
|
+
/**
|
|
3065
|
+
* Upload grant helpers — the realtime grant pattern (ADR-0079), extended to
|
|
3066
|
+
* asset uploads so the zero-backend story survives the first user-supplied
|
|
3067
|
+
* image. A static page can take a shopper's logo, upload it, and render it on
|
|
3068
|
+
* merchandise without any proxy server.
|
|
3069
|
+
*
|
|
3070
|
+
* A short-lived (5 min) grant token authorizes uploads into the shop's own
|
|
3071
|
+
* storage origin (`{shopId}.storage.snowcone.app`) — which is inside the
|
|
3072
|
+
* shop's asset-origin allowlist, so the returned URL drops straight into
|
|
3073
|
+
* `getMockupUrl` with zero further config. Three ways to get one, mirroring
|
|
3074
|
+
* the realtime grant exactly:
|
|
3075
|
+
*
|
|
3076
|
+
* - {@link mintUploadGrant} — SERVER-SIDE with a secret API key (sk_), or
|
|
3077
|
+
* keyless with just the publishable shop id.
|
|
3078
|
+
* - {@link fetchUploadGrant} — BROWSER, from your own proxy endpoint.
|
|
3079
|
+
* - {@link uploadAsset} — the one-call helper: resolves a grant however you
|
|
3080
|
+
* provide it, uploads the image, returns the hosted URL.
|
|
3081
|
+
*/
|
|
3082
|
+
/** A short-lived upload grant. */
|
|
3083
|
+
interface UploadGrant {
|
|
3084
|
+
/** Opaque token for `POST /uploads/grant/base64`. */
|
|
3085
|
+
token: string;
|
|
3086
|
+
/** Expiry, epoch seconds. Mint a fresh grant after this. */
|
|
3087
|
+
expiresAt: number;
|
|
3088
|
+
}
|
|
3089
|
+
/** Default backend base URL hosting `POST /uploads/grant`. */
|
|
3090
|
+
declare const DEFAULT_UPLOAD_BASE = "https://api.snowcone.app";
|
|
3091
|
+
/**
|
|
3092
|
+
* Mint an upload grant. Mirrors `mintRealtimeGrant`:
|
|
3093
|
+
*
|
|
3094
|
+
* Omit `apiKey` (or pass `undefined`/`null`/`''`) for the **keyless
|
|
3095
|
+
* publishable path** — the grant is authorized by the publishable `shop` id
|
|
3096
|
+
* alone (shops on the L3 signed-URLs rung must use a key or a signed grant
|
|
3097
|
+
* request instead). Pass a secret API key (sk_) with the `uploads:write`
|
|
3098
|
+
* scope to mint server-side; the key's organization must own the shop.
|
|
3099
|
+
*
|
|
3100
|
+
* @example
|
|
3101
|
+
* // keyless, straight from the browser — quick trials & sandbox shops:
|
|
3102
|
+
* const grant = await mintUploadGrant({ shop });
|
|
3103
|
+
*
|
|
3104
|
+
* @example
|
|
3105
|
+
* // your backend route: POST /api/upload/grant
|
|
3106
|
+
* const grant = await mintUploadGrant({ apiKey: process.env.SNOWCONE_API_KEY!, shop });
|
|
3107
|
+
* return Response.json(grant);
|
|
3108
|
+
*/
|
|
3109
|
+
declare function mintUploadGrant(opts: {
|
|
3110
|
+
/**
|
|
3111
|
+
* Secret API key (sk_) with the `uploads:write` scope. Omit (or pass
|
|
3112
|
+
* `undefined`/`null`/`''`) for the keyless publishable path.
|
|
3113
|
+
*/
|
|
3114
|
+
apiKey?: string | null;
|
|
3115
|
+
/** Target shop id (= shop.id). Uploads land in this shop's storage origin. */
|
|
3116
|
+
shop: string;
|
|
3117
|
+
/** Backend base URL. Defaults to {@link DEFAULT_UPLOAD_BASE}. */
|
|
3118
|
+
base?: string;
|
|
3119
|
+
/** Override fetch (e.g. in tests / non-global-fetch runtimes). */
|
|
3120
|
+
fetch?: typeof fetch;
|
|
3121
|
+
}): Promise<UploadGrant>;
|
|
3122
|
+
/**
|
|
3123
|
+
* BROWSER: fetch an upload grant from your own proxy endpoint, which calls
|
|
3124
|
+
* {@link mintUploadGrant} server-side (when you want the sk_ path without
|
|
3125
|
+
* shipping the key). The proxy receives `POST { shop }` and returns
|
|
3126
|
+
* `{ token, expiresAt }`.
|
|
3127
|
+
*/
|
|
3128
|
+
declare function fetchUploadGrant(grantUrl: string, shop: string, fetchImpl?: typeof fetch): Promise<UploadGrant>;
|
|
3129
|
+
/**
|
|
3130
|
+
* Upload an image and get back its hosted URL — ready to pass as `asset` to
|
|
3131
|
+
* `getMockupUrl` / `getBuyUrl` (it lands on the shop's own storage origin, so
|
|
3132
|
+
* it's already on the asset-origin allowlist).
|
|
3133
|
+
*
|
|
3134
|
+
* Provide auth in whichever shape fits:
|
|
3135
|
+
* - `{ shop }` alone — keyless publishable path (mints the grant for you),
|
|
3136
|
+
* - `{ shop, grantUrl }` — exchange via your own proxy endpoint,
|
|
3137
|
+
* - `{ shop, apiKey }` — server-side with an sk_ key,
|
|
3138
|
+
* - `{ grant }` — a grant you already hold (token reusable until it expires).
|
|
3139
|
+
*
|
|
3140
|
+
* @example
|
|
3141
|
+
* // a static page, no backend anywhere:
|
|
3142
|
+
* const { url } = await uploadAsset(fileInput.files[0], { shop });
|
|
3143
|
+
* img.src = getMockupUrl("BEEB77", { shop, asset: url });
|
|
3144
|
+
*/
|
|
3145
|
+
declare function uploadAsset(
|
|
3146
|
+
/** A `Blob`/`File`, or a `data:image/…;base64,` URL. */
|
|
3147
|
+
image: Blob | string, opts: {
|
|
3148
|
+
/** Target shop id. Required unless a pre-fetched `grant` is given. */
|
|
3149
|
+
shop?: string;
|
|
3150
|
+
/** A grant you already hold (or its raw token). Skips minting. */
|
|
3151
|
+
grant?: UploadGrant | string;
|
|
3152
|
+
/** Your own proxy endpoint that returns a grant (see {@link fetchUploadGrant}). */
|
|
3153
|
+
grantUrl?: string;
|
|
3154
|
+
/** Secret API key (sk_, scope `uploads:write`) for server-side minting. */
|
|
3155
|
+
apiKey?: string | null;
|
|
3156
|
+
/** Backend base URL. Defaults to {@link DEFAULT_UPLOAD_BASE}. */
|
|
3157
|
+
base?: string;
|
|
3158
|
+
/** Override fetch. */
|
|
3159
|
+
fetch?: typeof fetch;
|
|
3160
|
+
}): Promise<{
|
|
3161
|
+
url: string;
|
|
3162
|
+
}>;
|
|
3163
|
+
|
|
3041
3164
|
interface ProductPlacement {
|
|
3042
3165
|
label: string;
|
|
3043
3166
|
x: number;
|
|
@@ -3062,7 +3185,7 @@ interface ProductMockupData {
|
|
|
3062
3185
|
}
|
|
3063
3186
|
|
|
3064
3187
|
interface CatalogListResponse {
|
|
3065
|
-
items: CatalogProduct
|
|
3188
|
+
items: CatalogProduct[];
|
|
3066
3189
|
total: number;
|
|
3067
3190
|
}
|
|
3068
3191
|
|
|
@@ -3081,15 +3204,15 @@ interface SdkConfig {
|
|
|
3081
3204
|
interface SnowconeClient {
|
|
3082
3205
|
catalog: {
|
|
3083
3206
|
listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3084
|
-
getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct
|
|
3207
|
+
getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3085
3208
|
};
|
|
3086
3209
|
mockup: MockupService;
|
|
3087
3210
|
}
|
|
3088
3211
|
declare function listProducts(config?: Partial<SdkConfig>): Promise<CatalogListResponse>;
|
|
3089
|
-
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct
|
|
3212
|
+
declare function getProduct(idOrSlug: string, config?: Partial<SdkConfig>): Promise<CatalogProduct>;
|
|
3090
3213
|
/**
|
|
3091
3214
|
* Create a unified Snowcone client with catalog and mockup services
|
|
3092
3215
|
*/
|
|
3093
3216
|
declare function createClient(config: SdkConfig): SnowconeClient;
|
|
3094
3217
|
|
|
3095
|
-
export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct
|
|
3218
|
+
export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, DEFAULT_UPLOAD_BASE, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SignedUrlResponse, type SnowconeClient, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UploadGrant, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchRealtimeGrant, fetchUploadGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mintUploadGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, uploadAsset, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
|
package/dist/index.js
CHANGED
|
@@ -618,6 +618,13 @@ function getMockupUrl(a, b, c) {
|
|
|
618
618
|
const signature = hmacSha256Hex(opts.secret, canonicalForSig(url)).slice(0, 16);
|
|
619
619
|
return `${url}&signature=${signature}`;
|
|
620
620
|
}
|
|
621
|
+
var DEFAULT_BUY_BASE = "https://buy.snowcone.app";
|
|
622
|
+
function getBuyUrl(productCode, opts) {
|
|
623
|
+
return getMockupUrl(productCode, {
|
|
624
|
+
...opts,
|
|
625
|
+
base: opts.base ?? DEFAULT_BUY_BASE
|
|
626
|
+
});
|
|
627
|
+
}
|
|
621
628
|
|
|
622
629
|
// src/mockup/bffSigner.ts
|
|
623
630
|
function bffSigner(endpoint = "/api/sign", opts) {
|
|
@@ -2650,7 +2657,7 @@ var ProductLoader = class {
|
|
|
2650
2657
|
const { items } = await this.fetcher.listProducts(options);
|
|
2651
2658
|
const product = items?.[0];
|
|
2652
2659
|
if (product) {
|
|
2653
|
-
const productId = product.id
|
|
2660
|
+
const productId = product.id;
|
|
2654
2661
|
if (productId) {
|
|
2655
2662
|
this.cache.set(productId, product);
|
|
2656
2663
|
}
|
|
@@ -4974,6 +4981,82 @@ async function createDesignState(input) {
|
|
|
4974
4981
|
return { stateId: ds.id, stateUrl: ds.stateUrl ?? "", previewUrl: ds.previewUrl ?? "" };
|
|
4975
4982
|
}
|
|
4976
4983
|
|
|
4984
|
+
// src/upload/grant.ts
|
|
4985
|
+
var DEFAULT_UPLOAD_BASE = "https://api.snowcone.app";
|
|
4986
|
+
async function mintUploadGrant(opts) {
|
|
4987
|
+
const f = opts.fetch ?? globalThis.fetch;
|
|
4988
|
+
const headers = { "Content-Type": "application/json" };
|
|
4989
|
+
if (opts.apiKey) headers.Authorization = `Bearer ${opts.apiKey}`;
|
|
4990
|
+
const res = await f(`${opts.base ?? DEFAULT_UPLOAD_BASE}/uploads/grant`, {
|
|
4991
|
+
method: "POST",
|
|
4992
|
+
headers,
|
|
4993
|
+
body: JSON.stringify({ shop: opts.shop })
|
|
4994
|
+
});
|
|
4995
|
+
if (!res.ok) {
|
|
4996
|
+
const detail = await res.text().catch(() => "");
|
|
4997
|
+
throw new Error(`upload grant failed: ${res.status}${detail ? ` ${detail}` : ""}`);
|
|
4998
|
+
}
|
|
4999
|
+
return await res.json();
|
|
5000
|
+
}
|
|
5001
|
+
async function fetchUploadGrant(grantUrl, shop, fetchImpl) {
|
|
5002
|
+
const f = fetchImpl ?? globalThis.fetch;
|
|
5003
|
+
const res = await f(grantUrl, {
|
|
5004
|
+
method: "POST",
|
|
5005
|
+
headers: { "Content-Type": "application/json" },
|
|
5006
|
+
body: JSON.stringify({ shop })
|
|
5007
|
+
});
|
|
5008
|
+
if (!res.ok) throw new Error(`upload grant failed: ${res.status}`);
|
|
5009
|
+
return await res.json();
|
|
5010
|
+
}
|
|
5011
|
+
async function toImageDataUrl(image) {
|
|
5012
|
+
if (typeof image === "string") {
|
|
5013
|
+
if (/^data:image\/\w+;base64,/.test(image)) return image;
|
|
5014
|
+
throw new Error(
|
|
5015
|
+
"uploadAsset: a string image must be a data:image/\u2026;base64 URL (pass a Blob/File otherwise)"
|
|
5016
|
+
);
|
|
5017
|
+
}
|
|
5018
|
+
const bytes = new Uint8Array(await image.arrayBuffer());
|
|
5019
|
+
const type = image.type?.startsWith("image/") ? image.type : "image/png";
|
|
5020
|
+
const B = globalThis.Buffer;
|
|
5021
|
+
let base64;
|
|
5022
|
+
if (B) {
|
|
5023
|
+
base64 = B.from(bytes).toString("base64");
|
|
5024
|
+
} else {
|
|
5025
|
+
let bin = "";
|
|
5026
|
+
const CHUNK = 32768;
|
|
5027
|
+
for (let i = 0; i < bytes.length; i += CHUNK) {
|
|
5028
|
+
bin += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
|
|
5029
|
+
}
|
|
5030
|
+
base64 = btoa(bin);
|
|
5031
|
+
}
|
|
5032
|
+
return `data:${type};base64,${base64}`;
|
|
5033
|
+
}
|
|
5034
|
+
async function uploadAsset(image, opts) {
|
|
5035
|
+
const f = opts.fetch ?? globalThis.fetch;
|
|
5036
|
+
const base = opts.base ?? DEFAULT_UPLOAD_BASE;
|
|
5037
|
+
const base64Image = await toImageDataUrl(image);
|
|
5038
|
+
let token;
|
|
5039
|
+
if (opts.grant) {
|
|
5040
|
+
token = typeof opts.grant === "string" ? opts.grant : opts.grant.token;
|
|
5041
|
+
} else {
|
|
5042
|
+
if (!opts.shop) {
|
|
5043
|
+
throw new Error("uploadAsset: `shop` is required unless a `grant` is given");
|
|
5044
|
+
}
|
|
5045
|
+
const grant = opts.grantUrl ? await fetchUploadGrant(opts.grantUrl, opts.shop, f) : await mintUploadGrant({ apiKey: opts.apiKey, shop: opts.shop, base, fetch: f });
|
|
5046
|
+
token = grant.token;
|
|
5047
|
+
}
|
|
5048
|
+
const res = await f(`${base}/uploads/grant/base64`, {
|
|
5049
|
+
method: "POST",
|
|
5050
|
+
headers: { "Content-Type": "application/json" },
|
|
5051
|
+
body: JSON.stringify({ token, base64Image })
|
|
5052
|
+
});
|
|
5053
|
+
if (!res.ok) {
|
|
5054
|
+
const detail = await res.text().catch(() => "");
|
|
5055
|
+
throw new Error(`upload failed: ${res.status}${detail ? ` ${detail}` : ""}`);
|
|
5056
|
+
}
|
|
5057
|
+
return await res.json();
|
|
5058
|
+
}
|
|
5059
|
+
|
|
4977
5060
|
// src/index.ts
|
|
4978
5061
|
function getFetcher(config) {
|
|
4979
5062
|
return config?.fetcher || globalThis.fetch.bind(globalThis);
|
|
@@ -5064,10 +5147,12 @@ export {
|
|
|
5064
5147
|
ContextSynchronizer,
|
|
5065
5148
|
DEFAULT_ARTWORK_URL,
|
|
5066
5149
|
DEFAULT_ASPECT_RATIO,
|
|
5150
|
+
DEFAULT_BUY_BASE,
|
|
5067
5151
|
DEFAULT_COLOR,
|
|
5068
5152
|
DEFAULT_GRANT_BASE,
|
|
5069
5153
|
DEFAULT_MOCKUP_BASE,
|
|
5070
5154
|
DEFAULT_PLACEMENT_DIMENSIONS,
|
|
5155
|
+
DEFAULT_UPLOAD_BASE,
|
|
5071
5156
|
Elements,
|
|
5072
5157
|
ErrorManager,
|
|
5073
5158
|
EventDelegator,
|
|
@@ -5129,12 +5214,14 @@ export {
|
|
|
5129
5214
|
describeProductTitle,
|
|
5130
5215
|
extractProductId,
|
|
5131
5216
|
fetchRealtimeGrant,
|
|
5217
|
+
fetchUploadGrant,
|
|
5132
5218
|
filterImagePlacements,
|
|
5133
5219
|
findBestCombination,
|
|
5134
5220
|
findClosestSnapPoint,
|
|
5135
5221
|
findVariantForSelection,
|
|
5136
5222
|
formatPrice,
|
|
5137
5223
|
formatValidationErrors,
|
|
5224
|
+
getBuyUrl,
|
|
5138
5225
|
getDefaultVariantId,
|
|
5139
5226
|
getEffectiveAlignment,
|
|
5140
5227
|
getIncompleteSelectionMessage,
|
|
@@ -5153,6 +5240,7 @@ export {
|
|
|
5153
5240
|
isValidTileCount,
|
|
5154
5241
|
listProducts,
|
|
5155
5242
|
mintRealtimeGrant,
|
|
5243
|
+
mintUploadGrant,
|
|
5156
5244
|
mockupUrl,
|
|
5157
5245
|
normalizeChoice,
|
|
5158
5246
|
prepareOptionRenderData,
|
|
@@ -5164,6 +5252,7 @@ export {
|
|
|
5164
5252
|
simulateCartOperation,
|
|
5165
5253
|
toCombinations,
|
|
5166
5254
|
toOptionAttributes,
|
|
5255
|
+
uploadAsset,
|
|
5167
5256
|
useFrameworkAdapter as useVueAdapter,
|
|
5168
5257
|
validateAlignment,
|
|
5169
5258
|
validateDesignElement,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.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.
|
|
88
|
+
"@snowcone-app/mockup-url": "0.1.1"
|
|
89
89
|
},
|
|
90
90
|
"engines": {
|
|
91
91
|
"node": ">=18"
|