@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/shared/capabilities/site-search/rest/search.ts

@@ -0,0 +1,82 @@
+// Site Search reads over REST — the twin of app/wix/site-search/search.ts. Same exports, same DTOs;
+// the bodies and mappers come from search-core (the SAME file the SDK transport uses, deployed flat
+// next to this one by deploy.mjs --stack static), so this file is only the transport: one fetch with
+// a literal body per function. Every call here answers a visitor token (observed live). Porting:
+// keep the paths, keep the bodies, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/business-management/site-search/wix-site-search/search.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { siteSearchPlan } from "./site-search-config.generated.js";
+import {
+  GROUP_LIMIT,
+  MIN_SUGGEST_CHARS,
+  MAX_SUGGEST_QUERY,
+  SUGGEST_LIMIT,
+  clampQuery,
+  federatedBody,
+  productsOf,
+  resolveConfig,
+  searchBody,
+  storeFrontById,
+  suggestBody,
+  toPage,
+  toSearchAll,
+  toSuggestGroups,
+  type Raw,
+} from "./search-core.js";
+import type { SearchAllResult, SearchOptions, SearchPage, SiteSearchConfig, SuggestGroup } from "./types.js";
+
+/** The plan's siteSearch entry resolved — types in order, routes, labels. */
+export const config: SiteSearchConfig = resolveConfig(siteSearchPlan);
+
+// The store-front pass only adds product slugs and media; when it fails the products render unlinked.
+async function storeFrontPass(run: () => Promise<Raw>): Promise<Raw | null> {
+  try {
+    return await run();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every configured type at once, `limit` hits per type. Products are fetched twice (default format
+ * for title and highlights, store-front for the slug) and joined on id.
+ * POST /sitesearch/v1/search/federated  { query, documentTypes, limit, fuzzy, highlight, properties? }
+ * → { results: [{ documentType, documents, total }] }
+ */
+export async function searchAll(q: string, { limit = GROUP_LIMIT }: { limit?: number } = {}): Promise<SearchAllResult> {
+  const query = clampQuery(q);
+  if (!query) return { groups: [], indexed: null };
+  const wantsProducts = config.types.includes("products");
+  const [res, sf] = await Promise.all([
+    wixRequest<Raw>("/sitesearch/v1/search/federated", { body: federatedBody(query, config, { limit }) }),
+    wantsProducts ? storeFrontPass(() => wixRequest<Raw>("/sitesearch/v1/search/federated", { body: federatedBody(query, config, { limit, types: ["products"], storeFront: true }) })) : null,
+  ]);
+  return toSearchAll(res?.results, config, imgSrc, storeFrontById(productsOf(sf?.results)));
+}
+
+/**
+ * One type with paging, ordering, filter and facets.
+ * POST /sitesearch/v1/search  { query, documentType, paging: { limit, offset }, ordering?, filter?, facets?, fuzzy, highlight }
+ * → { documents, nextPage: { total, skip, limit }, facets }
+ */
+export async function searchType(o: SearchOptions): Promise<SearchPage> {
+  const query = clampQuery(o.q);
+  if (!query) return toPage(null, o, config, imgSrc);
+  const [res, sf] = await Promise.all([
+    wixRequest<Raw>("/sitesearch/v1/search", { body: searchBody({ ...o, q: query }, config) }),
+    o.type === "products" ? storeFrontPass(() => wixRequest<Raw>("/sitesearch/v1/search", { body: searchBody({ ...o, q: query }, config, { storeFront: true }) })) : null,
+  ]);
+  return toPage(res, { ...o, q: query }, config, imgSrc, storeFrontById(sf?.documents));
+}
+
+/**
+ * Suggestions for a partial phrase (3 to 50 chars; fewer → [] without a request), `limit` per type.
+ * POST /sitesearch/v1/suggest/federated  { query, documentTypes, limit }  → { results: [{ documentType, documents }] }
+ */
+export async function suggest(q: string, { limit = SUGGEST_LIMIT }: { limit?: number } = {}): Promise<SuggestGroup[]> {
+  const query = clampQuery(q, MAX_SUGGEST_QUERY);
+  if (query.length < MIN_SUGGEST_CHARS) return [];
+  const res = await wixRequest<Raw>("/sitesearch/v1/suggest/federated", { body: suggestBody(query, config, limit) });
+  return toSuggestGroups(res?.results, config, imgSrc);
+}

package/skills/wix-headless-templates/shared/capabilities/site-search/seed/install.mjs

@@ -0,0 +1,43 @@
+// Install the Wix Site Search app on the project's site — the one site mutation the site-search
+// capability needs, and the one thing its deploy does not do. A BUILD-TIME script, never shipped.
+// Run from the project root (where wix.config.json lives), AFTER the content seed:
+//
+//   node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs [--site <siteId>]
+//
+// The site is --site, else wix.config.json's siteId. The token is minted by the Wix CLI inside this
+// process and never written anywhere. Prints ONE JSON object: { siteId, appId, installed: "now" |
+// "already", indexing }. The install back-fills the site's existing products, services, posts and
+// events; results appear about half a minute later — smoke-test with the deployed data layer
+// (searchAll("<a seeded title word>")) and expect a non-empty group before wiring the UI. Zero
+// documents after a minute means the app is not installed or the content is not visible to the
+// index (hidden products, drafts), not that the query is wrong.
+import { execFileSync } from "node:child_process";
+import { seedSiteId } from "../../../seed/site-context.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { installSiteSearch } from "../../../seed/site.mjs";
+
+function flag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : null;
+}
+
+// --site, else the project's content site (wix.config.json, or the site being migrated on a
+// migration preview — where installing an app is a write into the live original: the guard applies).
+let siteId = flag("site");
+if (!siteId && existsSync("wix.config.json")) siteId = seedSiteId({ argv: process.argv });
+if (!siteId) {
+  console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
+  process.exit(1);
+}
+const token = execFileSync("npx", ["-y", "@wix/cli@1.1.257", "token", "--site", siteId], { encoding: "utf8" }).trim();
+if (!token) {
+  console.log(JSON.stringify({ error: "the Wix CLI returned no token — run `npx @wix/cli@1.1.257 login` first" }));
+  process.exit(1);
+}
+try {
+  const r = await installSiteSearch({ token, siteId });
+  console.log(JSON.stringify({ siteId, ...r, indexing: r.installed === "now" ? "existing content is being indexed; expect results within about half a minute" : "already indexed" }));
+} catch (e) {
+  console.log(JSON.stringify({ siteId, error: String(e.message).slice(0, 400) }));
+  process.exit(1);
+}

package/skills/wix-headless-templates/shared/rest/client.ts

@@ -0,0 +1,155 @@
+// The one auth seam for every Wix REST call — the twin of app/wix/sdk.ts, over fetch. No
+// dependencies. deploy.mjs --stack static copies it flat into js/wix/ next to the core files and
+// strips it to JS (comments kept); a port to another language reads it as the specification.
+// Imports carry the .js suffix so the stripped output runs as browser ESM unchanged.
+//
+// WIX_CLIENT_ID is the public OAuth client id (`appId` in wix.config.json). It is NOT a secret — it
+// only mints anonymous VISITOR tokens — so it is fine in page source. deploy.mjs writes ./config.
+//
+// THE TOKEN IS THE CART. A visitor token is the shopper's identity: their cart lives on it. Mint
+// once per shopper, persist it, refresh it — never mint per request (a fresh token is a new visitor
+// with an empty cart). Where it persists depends on where this code runs:
+//   browser — localStorage, keyed by client id so two sites on one origin don't share a token
+//             (what this file does).
+//   server (a Python/PHP/Go port) — the SHOPPER'S SESSION, one token set per shopper. Never one
+//             process-wide token for everyone: that is one shared cart for all visitors.
+//             This is the only part of a port that isn't line-for-line.
+// docs: https://dev.wix.com/docs/go-headless/coding/authentication/visitors.md
+import { WIX_CLIENT_ID } from "./config.js";
+
+export const WIX_API_BASE = "https://www.wixapis.com";
+const TOKEN_URL = `${WIX_API_BASE}/oauth2/token`;
+const STORAGE_KEY = `wix-visitor-${WIX_CLIENT_ID}`;
+
+export interface Tokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch ms. */
+  expiresAt: number;
+  /** Whose tokens: absent or "visitor" for an anonymous visitor, "member" after a login (a vertical's rest/auth.ts). */
+  role?: "visitor" | "member";
+}
+
+/** Swap this for a server-session-backed store in a port; the browser default is localStorage. */
+export interface TokenStore {
+  load(): Tokens | null;
+  save(tokens: Tokens): void;
+}
+
+let memory: Tokens | null = null;
+export const browserTokenStore: TokenStore = {
+  load() {
+    if (memory) return memory;
+    if (typeof localStorage === "undefined") return null;
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY);
+      if (raw) memory = JSON.parse(raw) as Tokens;
+    } catch {
+      /* disabled or corrupt storage — mint a fresh visitor */
+    }
+    return memory;
+  },
+  save(tokens) {
+    memory = tokens;
+    if (typeof localStorage === "undefined") return;
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+    } catch {
+      /* storage full or disabled — the session just won't survive a reload */
+    }
+  },
+};
+let store: TokenStore = browserTokenStore;
+/** A port calls this once with its session-backed store. */
+export function useTokenStore(s: TokenStore): void {
+  store = s;
+}
+
+// POST /oauth2/token — grantType "anonymous" mints a visitor; "refresh_token" renews and KEEPS the
+// identity (a member refresh token yields member tokens); "authorization_code" + codeVerifier turns
+// a login's authorization code into MEMBER tokens (a vertical's rest/auth.ts). `role` records which.
+export async function mintTokens(body: Record<string, string>, role: Tokens["role"] = "visitor"): Promise<Tokens> {
+  const res = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ clientId: WIX_CLIENT_ID, ...body }),
+  });
+  if (!res.ok) throw new Error(`Wix auth failed (${res.status}).`);
+  const data = await res.json();
+  return { accessToken: data.access_token, refreshToken: data.refresh_token, expiresAt: Date.now() + data.expires_in * 1000, role };
+}
+
+/** The persisted token set as it is (possibly expired), or null before the first mint. */
+export function loadTokens(): Tokens | null {
+  return store.load();
+}
+
+/** Adopt a token set — a member's after login. Every call from here on runs as that identity. */
+export function setTokens(tokens: Tokens): void {
+  store.save(tokens);
+}
+
+/** Drop the current identity (logout): the next call mints a fresh anonymous visitor. */
+export function clearTokens(): void {
+  store.save({ accessToken: "", refreshToken: "", expiresAt: 0 });
+}
+
+/** A valid access token: cached, refreshed when expired, minted on first use. */
+export async function accessToken(): Promise<string> {
+  const t = store.load();
+  if (t && t.expiresAt - 60_000 > Date.now()) return t.accessToken;
+  let fresh: Tokens | undefined;
+  if (t?.refreshToken) {
+    try {
+      fresh = await mintTokens({ grantType: "refresh_token", refreshToken: t.refreshToken }, t.role ?? "visitor");
+    } catch {
+      /* fall through to a new visitor */
+    }
+  }
+  fresh ??= await mintTokens({ grantType: "anonymous" });
+  store.save(fresh);
+  return fresh.accessToken;
+}
+
+export class WixApiError extends Error {
+  /** The response's `details` as Wix sent it (applicationError, validationError) — for callers that map codes. */
+  public details?: Record<string, any>;
+  constructor(message: string, public status: number, public code?: string, details?: Record<string, any>) {
+    super(message);
+    this.details = details;
+  }
+}
+
+/**
+ * Every Wix call goes through here. `path` is relative to WIX_API_BASE; `query` becomes the query
+ * string (an array repeats the key: fields=A&fields=B). Throws WixApiError on a non-2xx, including
+ * 404 — callers that treat 404 as "not found" catch it. The header carries the RAW access token,
+ * no "Bearer " prefix.
+ */
+export async function wixRequest<T = any>(
+  path: string,
+  { method = "POST", body, query }: { method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; body?: unknown; query?: Record<string, string | readonly string[]> } = {},
+): Promise<T> {
+  const url = new URL(path, WIX_API_BASE);
+  for (const [k, v] of Object.entries(query ?? {})) {
+    for (const item of Array.isArray(v) ? v : [v as string]) url.searchParams.append(k, String(item));
+  }
+  const res = await fetch(url, {
+    method,
+    headers: { Authorization: await accessToken(), "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  if (!res.ok) {
+    let message = "", code: string | undefined, details: Record<string, any> | undefined;
+    try {
+      const j = await res.json();
+      message = j?.message ?? "";
+      code = j?.details?.applicationError?.code;
+      details = j?.details;
+    } catch {
+      /* no JSON body */
+    }
+    throw new WixApiError(message || `${method} ${url.pathname} failed (${res.status}).`, res.status, code, details);
+  }
+  return (res.status === 204 ? null : await res.json()) as T;
+}

package/skills/wix-headless-templates/shared/rest/config.ts

@@ -0,0 +1,4 @@
+// Written by install/deploy.mjs --stack static from .env.local's WIX_CLIENT_ID (what `wix env pull`
+// writes; on a migration preview the site being migrated), else wix.config.json, or --client-id.
+// The public OAuth client id — not a secret: it only mints anonymous visitor tokens.
+export const WIX_CLIENT_ID: string = "";

package/skills/wix-headless-templates/shared/rest/media.ts

@@ -0,0 +1,92 @@
+// Wix media → browser-loadable URLs — the twin of app/wix/media.ts, without the SDK.
+//
+// A media value arrives as an absolute https://static.wixstatic.com/... URL, a raw
+// `wix:image://v1/<file>/<name>#originWidth=W&originHeight=H` identifier a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME), or, over REST, an object whose `url` (and `id`) is the BARE file id
+// `e6a89e_…~mv2.png` (Services V2 media, verified live) which a browser resolves as a relative path
+// and 404s. Both raw forms are scaled through this ONE URL shape; any other hand-built form 403s:
+//   https://static.wixstatic.com/media/<file>/v1/fill/w_<W>,h_<H>,al_c,q_90/<file>
+const STATIC = "https://static.wixstatic.com/media";
+const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+/** A bare Wix media file id: no scheme, no path, an extension — `e6a89e_06cf…~mv2.png`, `11062b_27ca…~mv2.jpg`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+export type MediaLike = string | null | undefined | { image?: unknown; url?: string | null; id?: string | null };
+
+function rawOf(value: unknown): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  const o = value as { image?: unknown; url?: string | null; id?: string | null };
+  if (o.image != null && typeof o.image === "object") return rawOf(o.image); // { image: { id, url } }
+  return (typeof o.image === "string" ? o.image : null) ?? o.url ?? o.id ?? "";
+}
+
+/** The file id behind any raw form (a wix:image id, a bare file id, a static.wixstatic.com URL); "" otherwise. */
+function fileOf(v: string): string {
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  if (BARE_FILE_ID.test(v)) return v;
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : "";
+}
+
+/** Resolve any Wix media value to a URL sized w×h ("" when absent). */
+export function imgSrc(value: unknown, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // A wix:image id, a bare file id, or an absolute Wix media URL (bare, or already scaled to some
+  // other size): every one re-issued through the scaler at the requested size, one shape.
+  const file = fileOf(v);
+  if (file) return `${STATIC}/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/** srcset candidates at several widths; `ratio` is height/width. "" only when there is no image. */
+export function imgSrcSet(value: unknown, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://") || BARE_FILE_ID.test(v)) return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  if (v.includes("static.wixstatic.com/") && FILL.test(v)) {
+    return widths.map((w) => `${v.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return v;
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcset` without `src`.
+ * Attribute names as HTML spells them — spread into a template or apply with setAttribute:
+ *   `<img ${attrs(imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw"))} alt="…">`
+ * `sizes` is the width the image renders at; `ratio` is height/width. {} when there is no image.
+ */
+export function imgAttrs(value: unknown, sizes: string, ratio = 1): Record<string, string> {
+  const src = imgSrc(value, 640, Math.round(640 * ratio));
+  if (!src) return {};
+  return { src, srcset: imgSrcSet(value, undefined, ratio), sizes, loading: "lazy", decoding: "async" };
+}
+
+/**
+ * Height/width of a Wix image when the value carries its size: a raw
+ * `wix:image://…#originWidth=W&originHeight=H` id (the natural size) or a resolved `/v1/fill/w_W,h_H/`
+ * URL (the size it was scaled to). null when neither is present. Pass it as `ratio` to keep a
+ * srcset at the image's own aspect instead of the square default:
+ *   imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)
+ */
+export function imgRatio(value: unknown): number | null {
+  const v = rawOf(value);
+  if (!v) return null;
+  const size = v.startsWith("wix:image://")
+    ? [v.match(/[#&]originWidth=(\d+)/)?.[1], v.match(/[#&]originHeight=(\d+)/)?.[1]]
+    : (v.match(/\/v1\/fill\/w_(\d+),h_(\d+)/)?.slice(1) ?? []);
+  const w = Number(size[0]);
+  const h = Number(size[1]);
+  return w > 0 && h > 0 ? h / w : null;
+}
+
+/** The media identity before scaling — de-duplicate galleries on this, never on a resolved URL. */
+export function mediaKey(value: unknown): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  // The file id, whichever form the value takes — a raw id and a resolved URL of one photo share it.
+  if (v.startsWith("wix:image://")) return v.slice("wix:image://v1/".length).split("/")[0].split("#")[0];
+  const m = v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/);
+  return m ? m[1] : v;
+}

package/skills/wix-headless-templates/shared/seed/images.mjs

@@ -0,0 +1,183 @@
+// Shared seed util: entity images by URL or by AI GENERATION (Wix AI / Runware via the
+// wixapis proxy). BUILD-TIME only — imported by the vertical seed scripts, never shipped.
+//
+// The contract every seed relies on:
+//   - RESILIENT: nothing here ever throws out of resolveItemImages — a failed image resolves
+//     to null and the entity stays text-only; the seed's exit code never depends on images.
+//   - PARALLEL: all images resolve in one concurrent wave (each generation is its own
+//     single-task request — the google model 504s when one body bundles ≥3 tasks).
+//   - PASS-2: seeds create entities first, then attach what this returns — an image is never
+//     a precondition for an entity.
+//
+// Generation costs 1 Wix AI credit per image, billed to the account behind the site.
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, extname } from "node:path";
+import { createHash } from "node:crypto";
+
+const API = "https://www.wixapis.com";
+// Order = cheap-and-permissive first (runware ~0.009 credits/img, ~5s, loosest content
+// filter), then google (best fidelity, ~0.14, ~25s; rejects steps/CFGScale and free-form
+// sizes), then bfl (strictest filter — refuses trademark-ish prompts). A refusal or failure
+// falls through to the next model.
+const MODELS = ["runware:400@1", "google:4@2", "bfl:5@1"];
+/** Allowed dimensions: 1024×1024 (square — entities), 1376×768 (16:9 hero), 1200×896 (4:3). */
+export const IMAGE_SIZES = { square: [1024, 1024], hero: [1376, 768], editorial: [1200, 896] };
+
+async function req(ctx, path, body, timeoutMs = 45_000) {
+  const res = await fetch(API + path, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${ctx.token}`,
+      "wix-site-id": ctx.siteId,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(`POST ${path} -> ${res.status}: ${JSON.stringify(json).slice(0, 300)}`);
+  return json;
+}
+
+/**
+ * Generate one image; returns its short-lived URL (import it immediately). Tries each model
+ * once — a per-model failure (bad params, 5xx, credit exhaustion, timeout) falls through to
+ * the next; throws only after all models failed.
+ * docs: no public reference page for /runwareschemaless/v1/request; the request shape is the one below, verified live
+ */
+export async function generateImage(ctx, prompt, { width = 1024, height = 1024 } = {}) {
+  let lastErr;
+  for (const model of MODELS) {
+    try {
+      const r = await req(ctx, "/runwareschemaless/v1/request", [
+        {
+          taskType: "imageInference",
+          taskUUID: randomUUID(), // must be a real UUIDv4 — slugs 400
+          outputType: "URL",
+          outputFormat: "PNG",
+          positivePrompt: prompt,
+          width,
+          height,
+          model,
+          numberResults: 1,
+        },
+      ]);
+      const url = r?.data?.[0]?.imageURL;
+      if (url) return url;
+      lastErr = new Error(`no imageURL in response: ${JSON.stringify(r).slice(0, 200)}`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  throw lastErr;
+}
+
+const MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".avif": "image/avif" };
+
+/**
+ * Upload a LOCAL file (a path on this machine — the user's own asset) into Wix Media;
+ * returns { id, url } (permanent). Two steps per the Upload API: generate-upload-url, then
+ * PUT the bytes to it — the PUT response carries the file descriptor.
+ * docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md
+ */
+export async function uploadImage(ctx, path, displayName) {
+  const ext = extname(path).toLowerCase();
+  const mimeType = MIME[ext];
+  if (!mimeType) throw new Error(`unsupported image extension: ${path}`);
+  const bytes = readFileSync(path); // throws loud on a wrong path (caught per-item by resolveItemImages)
+  // fileName's extension MUST match the real file type — a mismatch (slug.png for a .jpg) is
+  // rejected; keep the caller's display name, swap in the file's own extension.
+  const fileName = (displayName ?? basename(path)).replace(/\.[a-z0-9]+$/i, "") + ext;
+  const { uploadUrl } = await req(ctx, "/site-media/v1/files/generate-upload-url", {
+    mimeType,
+    fileName,
+  });
+  const res = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: bytes,
+    signal: AbortSignal.timeout(120_000),
+  });
+  const json = await res.json().catch(() => ({}));
+  const f = json.file || json;
+  if (!res.ok || !f?.id) throw new Error(`upload failed (${res.status}): ${JSON.stringify(json).slice(0, 200)}`);
+  return { id: f.id, url: f.url };
+}
+
+/** Import an external/generated URL into Wix Media; returns { id, url } (permanent). */
+// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/import-file.md
+/**
+ * A file this seed already put in the Media Manager under this display name, or null. The seed
+ * names a file after its product/choice AND a hash of its source, so a re-run finds the same
+ * file instead of importing (or generating, a credit each) again — and the product gallery can
+ * recognise it by name instead of growing a duplicate per run.
+ */
+// docs: https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/search-files.md
+async function findExisting(ctx, displayName) {
+  try {
+    const r = await req(ctx, "/site-media/v1/files/search", { search: displayName, rootFolder: "MEDIA_ROOT", mediaTypes: ["IMAGE"], paging: { limit: 20 } });
+    const f = (r.files ?? []).find((x) => x.displayName === displayName && x.url && x.operationStatus !== "FAILED");
+    return f ? { id: f.id, url: f.url, reused: true } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Short stable fingerprint of an image's source (url, prompt + size, or file bytes). */
+function sourceHash(s) {
+  const h = createHash("sha1");
+  if (s.path) {
+    try { h.update(readFileSync(s.path)); } catch { h.update(String(s.path)); }
+  } else h.update(s.url ?? `${s.prompt}|${s.width ?? ""}x${s.height ?? ""}`);
+  return h.digest("hex").slice(0, 8);
+}
+
+/** `<name>-<hash>.<ext>`: the display name the seed gives a file, stable across runs. */
+function stableName(s) {
+  const given = s.displayName ?? (s.path ? basename(s.path) : "image.png");
+  const ext = (given.match(/\.[a-z0-9]+$/i) ?? [".png"])[0];
+  return `${given.replace(/\.[a-z0-9]+$/i, "")}-${sourceHash(s)}${ext}`;
+}
+
+export async function importImage(ctx, url, displayName = "image.png") {
+  const r = await req(ctx, "/site-media/v1/files/import", { url, mimeType: "image/png", displayName });
+  const f = r.file || r;
+  if (!f?.id) throw new Error(`import-file returned no file id: ${JSON.stringify(r).slice(0, 200)}`);
+  return { id: f.id, url: f.url };
+}
+
+/**
+ * THE seed entry point. Resolves a batch of image specs to Wix Media files in ONE parallel
+ * wave. Each spec: { path } (LOCAL file — the user's own asset, uploaded) OR { url }
+ * (verified external URL — imported) OR { prompt } (generated, ~1 credit) — plus optional
+ * displayName, width, height. Returns an array aligned with the input: { id, url } per
+ * success, null per failure or empty spec. Never throws.
+ */
+export async function resolveItemImages(ctx, specs, { perImageBudgetMs = 120_000 } = {}) {
+  // unref: the budget timer must never keep the seed process alive after the work is done —
+  // a lingering timer delays the seed's exit (and the run's .seed-exit marker) by the budget.
+  const deadline = new Promise((r) => {
+    const t = setTimeout(() => r(null), perImageBudgetMs);
+    t.unref?.();
+  });
+  const results = await Promise.allSettled(
+    (specs ?? []).map(async (s) => {
+      if (!s || (!s.path && !s.url && !s.prompt)) return null;
+      const resolve = (async () => {
+        const name = stableName(s);
+        // uploadImage swaps in the file's own extension; look for what it will actually be named
+        const uploadedName = s.path ? name.replace(/\.[a-z0-9]+$/i, "") + extname(s.path).toLowerCase() : name;
+        const existing = await findExisting(ctx, s.path ? uploadedName : name);
+        if (existing) return existing;
+        if (s.path) return uploadImage(ctx, s.path, name);
+        const source = s.url ?? (await generateImage(ctx, s.prompt, { width: s.width, height: s.height }));
+        return importImage(ctx, source, name);
+      })();
+      // Hard per-image budget: even a pathological multi-model hang costs the seed at most
+      // perImageBudgetMs of wall clock (the wave is parallel, so it's paid once, not per item).
+      return Promise.race([resolve, deadline]);
+    }),
+  );
+  return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+}

package/skills/wix-headless-templates/shared/seed/read-site.mjs

@@ -0,0 +1,97 @@
+// The shared runner behind every vertical's `seed/read-site.mjs` — the build-time read of what a
+// site holds, so the agent sizes the content without composing a single Wix request.
+//
+//   node <SKILL_ROOT>/templates/<vertical>/seed/read-site.mjs [--site <siteId>] [--limit <n>]
+//
+// The site is `--site`, else the project's content site (./wix.config.json, or the parent named in
+// .env.local on a migration preview). The token is minted by the Wix CLI
+// inside this process and never written anywhere. Output is ONE JSON object on stdout:
+//   { vertical, siteId, installed, ...what the vertical reads..., calls: [{ method, path, status, docs }] }
+// `calls` lists every request made, with the method's documentation URL — open one of those (the
+// URL plus `.md` is the full page) when the brief needs more than the summary shows. A failed call
+// is reported in `calls` with its status and message; the reader continues and marks the field null.
+import { existsSync } from "node:fs";
+import { contentSiteId } from "./site-context.mjs";
+import { wixToken } from "./wix-cli.mjs";
+
+const API = "https://www.wixapis.com";
+const DOCS_INSTALLED_APPS = "https://dev.wix.com/docs/api-reference/business-management/app-installation/app-installation/get-installed-apps";
+
+function flag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith("--") ? process.argv[i + 1] : null;
+}
+
+export function siteIdFromArgsOrConfig() {
+  const fromFlag = flag("site");
+  if (fromFlag) return fromFlag;
+  // The CONTENT site: the config's site, or the parent of a migration preview (site-context.mjs).
+  return existsSync("wix.config.json") ? contentSiteId() : null;
+}
+
+export function makeApi(siteId) {
+  const token = wixToken(siteId);
+  const calls = [];
+  async function call({ method = "POST", path, body, docs }) {
+    const entry = { method, path: path.split("?")[0], docs };
+    calls.push(entry);
+    const res = await fetch(API + path, {
+      method,
+      headers: { Authorization: token, "wix-site-id": siteId, "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await res.text();
+    entry.status = res.status;
+    if (!res.ok) {
+      entry.error = text.slice(0, 200) || "(empty body)";
+      const e = new Error(`${method} ${entry.path} → ${res.status}: ${entry.error}`);
+      e.status = res.status;
+      throw e;
+    }
+    try { return text ? JSON.parse(text) : {}; } catch { return {}; }
+  }
+  // Same call, but a failure becomes null and stays in `calls` — for reads whose absence is data.
+  async function tryCall(opts) {
+    try { return await call(opts); } catch { return null; }
+  }
+  async function installed(appId) {
+    const r = await tryCall({ method: "GET", path: "/apps-installer-service/v1/app-instances", docs: DOCS_INSTALLED_APPS });
+    if (!r) return null;
+    return (r.appInstances ?? []).some((a) => a.appDefId === appId || a.appId === appId);
+  }
+  return { call, tryCall, installed, calls };
+}
+
+export const limit = () => Number(flag("limit") ?? 12);
+
+// read(api, { limit }) returns the vertical's summary; the runner adds the envelope and prints.
+export async function runReader({ vertical, appId, read }) {
+  const siteId = siteIdFromArgsOrConfig();
+  if (!siteId) {
+    console.log(JSON.stringify({ error: "no site: pass --site <siteId> or run in a folder with wix.config.json" }));
+    process.exit(1);
+  }
+  const api = makeApi(siteId);
+  const out = { vertical, siteId, scope: null };
+  out.installed = appId ? await api.installed(appId) : undefined;
+  let data = {};
+  if (out.installed === false) {
+    out.scope = `${vertical}: the app is not installed on this site — nothing to read; the vertical's seed installs it`;
+  } else {
+    try { data = await read(api, { limit: limit() }); }
+    catch (e) { out.error = String(e.message).slice(0, 300); }
+  }
+  // What this output is and is not: a SIZING. Every list is a sample page; the counts are the site.
+  const partial = Object.entries(data)
+    .filter(([k, v]) => Array.isArray(v) && typeof data[`${k.replace(/s$/, "")}Count`] === "number" && data[`${k.replace(/s$/, "")}Count`] > v.length)
+    .map(([k, v]) => `${k}: ${v.length} of ${data[`${k.replace(/s$/, "")}Count`]} shown`);
+  if (!out.scope) {
+    out.scope = "A sizing, not the content. Lists are one page (--limit, max 100); counts are the whole site. " +
+      (partial.length ? `Partial here: ${partial.join("; ")}. ` : "") +
+      "The pages read everything live through the deployed data layer. To read more or filter, page the same call: its method and documentation URL are in `calls`.";
+  }
+  Object.assign(out, data);
+  out.calls = api.calls;
+  out.docs = [...new Set(api.calls.map((c) => c.docs).filter(Boolean))];
+  console.log(JSON.stringify(out, null, 2));
+}