@snowcone-app/sdk 0.29.1 → 0.31.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.31.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#5607](https://github.com/snowcone-app/snowcone-monorepo/pull/5607) [`6477622`](https://github.com/snowcone-app/snowcone-monorepo/commit/6477622b9a429a09aec41881db1ac1dd0b73dad2) Thanks [@kevinsproles](https://github.com/kevinsproles)! - getMockupUrl: `aspect` takes every mockup shape (16:9, 2:3, 3:4, 4:5, 1:1, 1.91:1, 9:16, 21:9, app-header) and a new `preset` picks a platform's shape and width by name (`"tiktok"`, `"instagram-feed"`, `"pinterest"`, …). A mockup that doesn't hold a shape answers E_MOCKUP_SHAPE_UNAVAILABLE with the shapes it gives.
8
+
9
+ ## 0.30.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#2973](https://github.com/snowcone-app/snowcone-monorepo/pull/2973) [`6910bc9`](https://github.com/snowcone-app/snowcone-monorepo/commit/6910bc9c88dbdcc5974d45ee93d2b2e17fff3bcf) Thanks [@kevinsproles](https://github.com/kevinsproles)! - The SDK owns Snowcone's hostnames. New `SNOWCONE_HOSTS` export (`api`, `img`, `buy`, `search`, `cdn`, `sign`, `raws`, `docs`) and `SNOWCONE_REALTIME_WS_URL` — every default host in the SDK, MCP server, canvas, and ui now reads from this one registry, so a host move ships as a version bump instead of breaking integrations. For an endpoint the SDK doesn't wrap, build the URL from `SNOWCONE_HOSTS.api` rather than hardcoding `https://api.snowcone.app`.
14
+
3
15
  ## 0.29.1
4
16
 
5
17
  ### Patch Changes
package/README.md CHANGED
@@ -101,7 +101,7 @@ const url = getMockupUrl(productCode: string, opts: {
101
101
  design?: Design; // Multi-placement: { [placementKey]: Fill } — takes precedence over `asset`
102
102
  options?: Record<string, string>; // Variant picks: { size: "m" } → opt.size=m
103
103
  secret?: string; // Optional: per-shop secret → appends a signed &signature (server only)
104
- base?: string; // Optional: override the host (default img.snowcone.app)
104
+ base?: string; // Optional: override the host (default SNOWCONE_HOSTS.img — leave unset in prod)
105
105
  width?: number; // Optional: display width
106
106
  view?: string; // Optional: camera view / mockup scene (alias: `mockup`)
107
107
  variant?: string; // Optional: specific resolved variant (gvid)
@@ -228,6 +228,24 @@ React apps can use the lower-level `useRealtimeMockup({ getToken })` hook from
228
228
  `@snowcone-app/sdk/react` instead. Full walkthrough:
229
229
  [Realtime server-side render](https://developers.snowcone.app/realtime).
230
230
 
231
+ ## Hosts: let the SDK own them
232
+
233
+ Don't write `https://api.snowcone.app` (or any Snowcone host) into your code.
234
+ The helpers above pick the host; for an endpoint the SDK doesn't wrap, read it
235
+ from `SNOWCONE_HOSTS`:
236
+
237
+ ```typescript
238
+ import { SNOWCONE_HOSTS } from '@snowcone-app/sdk';
239
+
240
+ await fetch(`${SNOWCONE_HOSTS.api}/orders`, { method: 'POST', headers, body });
241
+ // roles: api, img, buy, search, cdn, sign, raws, docs
242
+ ```
243
+
244
+ Hostnames live in one place in this package. If one has to move, you upgrade
245
+ the SDK; nothing you wrote changes. Store inputs (product, asset, options), not
246
+ built URLs — `getMockupUrl` is pure and sync, so rebuild at render time.
247
+ More: [Keep hosts out of your code](https://developers.snowcone.app/sdk#hosts).
248
+
231
249
  ## TypeScript Support
232
250
 
233
251
  Full TypeScript definitions are included. Import types:
@@ -1,5 +1,9 @@
1
+ import {
2
+ SNOWCONE_REALTIME_WS_URL
3
+ } from "./chunk-O6I5SJT5.js";
4
+
1
5
  // src/realtime/constants.ts
2
- var REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
6
+ var REALTIME_WS_URL = SNOWCONE_REALTIME_WS_URL;
3
7
 
4
8
  // src/realtime/websocket.ts
5
9
  function pruneUndefined(obj) {
@@ -1,4 +1,29 @@
1
1
  // ../mockup-url/src/index.ts
2
+ var SNOWCONE_HOSTS = {
3
+ /** REST API: shops, orders, AI generation, realtime grants. */
4
+ api: "https://api.snowcone.app",
5
+ /** Public mockup-image resolver (`/{productCode}?shop=…&asset=…`). */
6
+ img: "https://img.snowcone.app",
7
+ /** Hosted buy page (same grammar as `img`, opens checkout). */
8
+ buy: "https://buy.snowcone.app",
9
+ /** Public product / designs catalog (Meilisearch-compatible). */
10
+ search: "https://search.snowcone.app",
11
+ /** Render CDN — signed render URLs and the realtime socket. */
12
+ cdn: "https://cdn.snowcone.app",
13
+ /** Legacy URL signer. */
14
+ sign: "https://s.snowcone.app",
15
+ /** Content-addressed artwork store (ingest handles). */
16
+ raws: "https://raws.snowcone.app",
17
+ /** Developer docs. */
18
+ docs: "https://developers.snowcone.app",
19
+ /** The storefront site; `/api/launch` says whether orders are open yet. */
20
+ site: "https://snowcone.app",
21
+ /** The hosted MCP endpoint; it also serves the photo upload page (`/upload/<token>`). */
22
+ mcp: "https://mcp.snowcone.app",
23
+ /** Where draft designs made for a search are stored (a draft's `image_url`). */
24
+ drafts: "https://agentdraft.storage.snowcone.app"
25
+ };
26
+ var SNOWCONE_REALTIME_WS_URL = `${SNOWCONE_HOSTS.cdn.replace(/^http/, "ws")}/realtime`;
2
27
  var PARAMS = {
3
28
  shop: "shop",
4
29
  asset: "asset",
@@ -48,6 +73,51 @@ var PARAMS = {
48
73
  seal: "seal"
49
74
  };
50
75
  var BG_TRANSPARENT = "transparent";
76
+ var MOCKUP_PRESETS = {
77
+ tiktok: { aspect: "9:16", width: 1200 },
78
+ // 1080x1920
79
+ "instagram-story": { aspect: "9:16", width: 1200 },
80
+ // 1080x1920 (and Reels)
81
+ "youtube-shorts": { aspect: "9:16", width: 1200 },
82
+ // 1080x1920
83
+ "instagram-feed": { aspect: "4:5", width: 1200 },
84
+ // 1080x1350
85
+ "instagram-square": { aspect: "1:1", width: 1200 },
86
+ // 1080x1080
87
+ "facebook-feed": { aspect: "4:5", width: 1200 },
88
+ // 1080x1350
89
+ "facebook-link": { aspect: "1.91:1", width: 1200 },
90
+ // 1200x628
91
+ "linkedin-link": { aspect: "1.91:1", width: 1200 },
92
+ // 1200x627
93
+ pinterest: { aspect: "2:3", width: 1e3 },
94
+ // 1000x1500
95
+ "youtube-thumbnail": { aspect: "16:9", width: 1400 },
96
+ // 1280x720
97
+ "x-post": { aspect: "16:9", width: 1600 },
98
+ // 1600x900
99
+ amazon: { aspect: "1:1", width: 2e3 },
100
+ // 2000x2000 main image
101
+ etsy: { aspect: "1:1", width: 2e3 },
102
+ // 2000x2000
103
+ shopify: { aspect: "1:1", width: 2e3 },
104
+ // 2048x2048 product image, nearest rung
105
+ "site-hero": { aspect: "16:9", width: 2500 },
106
+ // 2560x1440
107
+ "web-banner": { aspect: "21:9", width: 2500 },
108
+ // ultra-wide banner
109
+ "app-header": { aspect: "app-header", width: 1200 }
110
+ // the hero under a phone's status bar (8:9)
111
+ };
112
+ var MOCKUP_PRESET_NAMES = Object.keys(MOCKUP_PRESETS);
113
+ function resolvePreset(preset, aspect, width) {
114
+ const p = MOCKUP_PRESETS[preset];
115
+ if (!p) throw new Error(`[snowcone] E_PRESET_UNKNOWN: preset ${JSON.stringify(preset)}; the presets: ${MOCKUP_PRESET_NAMES.join(", ")}`);
116
+ if (aspect !== void 0 && aspect !== p.aspect) {
117
+ throw new Error(`[snowcone] E_PRESET_ASPECT_CONFLICT: preset "${preset}" is aspect ${p.aspect}, but aspect "${aspect}" was also given; drop one`);
118
+ }
119
+ return { aspect: p.aspect, width: width ?? p.width };
120
+ }
51
121
  function normalizeBgColor(raw) {
52
122
  const value = raw.trim().replace(/^#/, "").toLowerCase();
53
123
  if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
@@ -86,6 +156,7 @@ var ALLOWED_WIDTHS = [
86
156
  4e3
87
157
  ];
88
158
  var MAX_RENDER_URL_LENGTH = 12 * 1024;
159
+ var INGEST_HANDLE_BASE = `${SNOWCONE_HOSTS.raws}/art-ingest/`;
89
160
  function normalizeWidth(width) {
90
161
  for (let i = ALLOWED_WIDTHS.length - 1; i >= 0; i--) {
91
162
  if (ALLOWED_WIDTHS[i] <= width) return ALLOWED_WIDTHS[i];
@@ -170,7 +241,7 @@ var PARAM_PREFIX = {
170
241
  /** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
171
242
  pick: "pick."
172
243
  };
173
- var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
244
+ var DEFAULT_PUBLIC_BASE_URL = SNOWCONE_HOSTS.img;
174
245
  function buildPublicMockupUrl(options, cfg = {}) {
175
246
  const base = (cfg.baseUrl ?? DEFAULT_PUBLIC_BASE_URL).replace(/\/+$/, "");
176
247
  const path = `/${encodeURIComponent(options.productCode)}`;
@@ -221,9 +292,10 @@ function buildPublicMockupUrl(options, cfg = {}) {
221
292
  if (options.mockup !== void 0) {
222
293
  parts.push(`${PARAMS.mockup}=${enc(options.mockup)}`);
223
294
  }
224
- if (options.width !== void 0) parts.push(`${PARAMS.width}=${options.width}`);
225
- if (options.aspect !== void 0 && options.aspect !== "16:9") {
226
- parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
295
+ const shape = options.preset !== void 0 ? resolvePreset(options.preset, options.aspect, options.width) : { aspect: options.aspect, width: options.width };
296
+ if (shape.width !== void 0) parts.push(`${PARAMS.width}=${shape.width}`);
297
+ if (shape.aspect !== void 0 && shape.aspect !== "16:9") {
298
+ parts.push(`${PARAMS.aspect}=${enc(shape.aspect)}`);
227
299
  }
228
300
  if (options.bg) {
229
301
  parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
@@ -296,6 +368,8 @@ async function signDevSig(canonical, secret) {
296
368
  }
297
369
 
298
370
  export {
371
+ SNOWCONE_HOSTS,
372
+ SNOWCONE_REALTIME_WS_URL,
299
373
  normalizeWidth,
300
374
  normalizeDesignElements,
301
375
  buildMockupUrl,