@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 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 || product.productId;
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$2 {
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
- /** Display width override. */
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
- /** Mockup canvas aspect ratio. Default 16:9 (omitted from the URL). */
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$1): Record<string, OptionAttribute>;
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$1): Combination[];
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$1): string | undefined;
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$1): string;
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$2[];
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$2>;
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$2>;
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$2 as 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_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, 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 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, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
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$2 {
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
- /** Display width override. */
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
- /** Mockup canvas aspect ratio. Default 16:9 (omitted from the URL). */
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$1): Record<string, OptionAttribute>;
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$1): Combination[];
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$1): string | undefined;
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$1): string;
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$2[];
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$2>;
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$2>;
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$2 as 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_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, 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 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, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, isSelectionComplete, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
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 || product.productId;
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.9.1",
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.0"
88
+ "@snowcone-app/mockup-url": "0.1.1"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"