@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/shared/CUSTOM_OPERATIONS.md

@@ -0,0 +1,100 @@
+# Custom operations
+
+Shipped vertical code covers its advertised contract. A brief can also require an operation
+outside that contract: a member submission, a file derived in the browser, moderation, a
+custom business write, or a third-party service.
+
+## Decide the boundary first
+
+1. **Caller-permitted Wix operation** — add one function to the appropriate `src/wix/<vertical>/`
+   data layer. Use the documented SDK method; components call that function, never the SDK.
+2. **Privileged Wix operation** — on Wix-managed Astro, create a narrow `src/pages/api/` endpoint.
+   Authenticate/authorize the caller and validate the exact input before elevating the one SDK
+   call with `auth.elevate()`. On another stack, the equivalent belongs on a server using
+   server-only credentials. Never expose an elevated method or credential to the browser.
+3. **No documented Wix path** — simplify the feature to a supported design. Do not infer a
+   contract from generated types, SDK implementation files, or `node_modules`.
+
+## The research rule
+
+Read the relevant shipped playbook first. For anything it doesn't cover, use `wix-docs` to
+read the official method or feature guide, then implement that contract. One documentation
+lookup and one type check are enough before coding. Investigate further only after a concrete error.
+
+## User-created public content
+
+Use the CMS vertical when a visitor or member submits content that the app must later list or
+show publicly. Seed the collection with the appropriate permission preset and never trust the
+browser to choose an owner, collection, or privileged action.
+
+For a small browser-created artifact, the official Wix-managed Astro pattern is a validated
+server endpoint that writes the contribution with elevation. For binary media, first confirm
+the Media Files API's authorization requirements: generating a media upload URL requires
+Manage Media Manager permission, so it is not a browser-side member call. Validate identity,
+MIME type, size, and destination before any elevated call. The authoritative references are:
+
+- `wix-docs`: **Upload Images to CMS** for the secure CMS contribution flow.
+- `wix-docs`: **Generate File Upload URL** and **Upload API** for Media Manager files.
+
+Keep the endpoint specific to the allowed contribution. An endpoint that accepts arbitrary
+SDK method names, collection ids, or upload destinations is a privilege-escalation bug.
+
+## Optional Media Upload capability
+
+Use this only when a site actually needs a normal file upload (not a small canvas artifact
+stored as a CMS data URL). Put the policy in the site plan; the Fast deployer ships the shared
+client helper and Astro endpoint once, plus a generated read-only policy module:
+
+```json
+{
+  "capabilities": {
+    "mediaUpload": {
+      "policies": [{
+        "id": "gallery-artwork",
+        "accept": ["image/png", "image/jpeg"],
+        "maxBytes": 5242880,
+        "audience": "members"
+      }]
+    }
+  }
+}
+```
+
+`audience` is who may use the policy: `members` (the default) admits a logged-in member only —
+the endpoint reads the caller's own session server-side and answers 401 to anyone else, before
+anything is elevated; it needs the Wix Members Area app, which the members seed installs.
+`visitors` admits anyone, and is only for a policy the product means for the public (a form's
+file field on a free site). The generated policy lives at `src/wix/media-upload/policies.generated.ts`; do not hand-edit
+it. The shared browser helper is `src/wix/media-upload/client.ts`:
+
+```ts
+const media = await uploadMedia("gallery-artwork", pngBlob, "my-drawing.png");
+// media.id and media.url are the Wix Media reference to store in the intended CMS image field.
+```
+
+The browser can select only the **named policy** and the bytes. The deployed API route fixes
+the destination and elevates only `files.generateFileUploadUrl`. A vertical uses the same
+capability by putting its own policy in its plan. Do not copy, fork, or widen the endpoint in
+vertical code.
+
+## Optional Site Search capability
+
+A search box with suggestions and a `/search?q=` results page across the deployed verticals'
+products, services, posts and events, linking to this site's own routes. Put the entry in the site
+plan; the Fast deployer ships the data layer, stores, hooks, components and the search page once,
+plus a generated read-only config module:
+
+```json
+{
+  "capabilities": {
+    "siteSearch": { "install": true, "types": ["products", "services", "posts", "events"] }
+  }
+}
+```
+
+Every call is a visitor read — no endpoint, no elevation. What it needs from the site is one
+mutation the deploy does not make: the **Wix Site Search app** must be installed, or every search
+answers zero documents. `install: true` marks that for the seed step, which runs
+`node <SKILL_ROOT>/templates/shared/capabilities/site-search/seed/install.mjs` after the content
+seed; the install indexes the existing content within about half a minute. The playbook, the plan
+fields and the contracts are in `templates/shared/capabilities/site-search/INSTRUCTIONS.md`.

package/skills/wix-headless-templates/shared/DESIGN.md

@@ -0,0 +1,37 @@
+# Design floor — every vertical, every surface you author
+
+**A fallback, not an override.** These rules fill the gap when the user gave no design
+direction. The moment the brief specifies a palette, a mood, a reference — their intent wins.
+Two exceptions that hold regardless: the contrast floor (in `styles/global.css`, where you
+choose the tokens), and the anti-genericism intent — derive the look from *this* brand even
+when the user supplied the inputs.
+
+Token judgment (polarity, palette, contrast, type floors) lives in the `@theme` header in
+`styles/global.css` — you'll meet it when you set the tokens. This file governs the surfaces:
+
+- **Full-bleed, not boxed.** Don't wrap pages in a narrow centered shell (`max-w-4xl mx-auto`
+  around everything). Design for the viewport; use peripheral space intentionally.
+- **One primary CTA per page**, worded to the page's actual action — "Add to Cart",
+  "Book a Table", "Reserve Your Spot" — never "Submit" / "Click here" / "Learn more" as the
+  hero action.
+- **Icons render bare on the surface** — no circle/square/pill shell behind nav or card
+  glyphs.
+- **A card that shows a thing is a link to that thing.** A featured product, dish, service,
+  post or event on the home page leads to its own page, or to its place on the listing when the
+  vertical has no item pages (`/menu#item-<id>` for a dish). A card with a title, image and price
+  and nothing to click is a dead end, not a design choice.
+- **Corner shape is a token, never a class.** Shipped buttons, chips, labels and steppers read
+  `--radius-control`, which follows `--radius-md` until the brand says otherwise: `9999px` is
+  the pill, `0` is square. Cards and fields read `--radius-lg/md/sm`. Don't patch `rounded-*`
+  on shipped markup, and give your own controls `rounded-control` so they move with it. Only
+  genuine circles (avatars, swatches, dots) stay `rounded-full`.
+- **Error text reads `--color-destructive`** (`text-destructive`), never a Tailwind palette
+  colour. Set it with the palette so it keeps 4.5:1 on `--color-background`.
+- **No emojis** in UI copy, headings, or empty states (unless the brief itself asks for
+  them).
+- **Vary the look across projects.** Repeating the same palette/layout on unrelated brands is
+  a failure mode, not a shortcut — two sites with the same vertical and different briefs
+  should look nothing alike.
+
+This constrains the *how*, not the *what* — the brief and the vertical decide what the pages
+are; INSTRUCTIONS decides which surfaces exist.

package/skills/wix-headless-templates/shared/SUPPLIED-CONTENT.md

@@ -0,0 +1,27 @@
+# Supplied content — when the user brings their own
+
+When the brief supplies the content in any form — a CSV, JSON or spreadsheet, a list typed in the
+prompt, a PDF or an image of a price list or a menu, a folder of photos with a text file beside
+it, a link to a page that lists it — that source is the seed plan. The vertical's default count
+("start with 3", "a few posts") applies only to catalogs you draft yourself.
+
+Read it however it needs to be read: parse the file (a quoted comma inside a description is
+common), open the PDF, fetch the page, look at the images. Then map, don't author:
+
+- Every entry in the source becomes an entry in the plan. Names, titles, descriptions, prices,
+  dates verbatim; never rename, reprice, reword, reorder or add.
+- Column and field names vary; map by meaning to the fields the vertical's `SEED.md` plan
+  shape defines. Anything the plan has no field for is dropped — say which columns you dropped.
+- Their images only: an image URL column → the plan's image URL field, verified with `curl -sI`
+  → 200; a local file → the plan's image path field. An entry with no image is seeded without one
+  and listed in your summary. **Never an `imagePrompt` beside supplied content** — these are their
+  things, not a mood board.
+- Currency, time zone, address: only when the source or the brief states them. A price written
+  with its unit ("9 dollars", "$9", "€20") states the currency: it goes in the plan's `currency`.
+  When the source states none, the site's own currency applies: name it in the closing message
+  ("prices are in ILS, the site's default; say the word and I switch it") rather than quoting
+  prices in a currency you assumed.
+- Show the user the count you read next to the count you seeded, and the mapping you applied.
+
+The vertical's `SEED.md` says what an entry is for that vertical and which of its plan fields the
+usual columns land in.

package/skills/wix-headless-templates/shared/app/styles/global.css

@@ -0,0 +1,57 @@
+@import url('https://fonts.googleapis.com/css2?family=Wix+Madefor+Text:wght@400;500;600;700;800&display=swap');
+@import 'tailwindcss';
+
+/* ─── THE design system ─────────────────────────────────────────────────────────────────
+   Theme the entire store by editing THIS @theme block (same token family as the official
+   Wix headless templates). Every shipped component styles itself from these via Tailwind
+   utilities (bg-primary, text-muted-foreground, text-destructive, rounded-lg, …) — change a token, everything
+   follows. A dark theme is just flipped values (dark background/foreground, adjusted
+   secondary/border). Don't restyle shipped component markup; restyle the tokens.
+
+   Choosing values: argue polarity from the business — light is not "cheap" (wellness/food
+   usually read better light); never dark-by-default for "premium". Palette: one dominant +
+   accents from ADJACENT hues (~30° arc), 2-4 colors total. Every background/foreground pair
+   you set must hit WCAG 4.5:1 (3:1 for text ≥24px); body copy never below 16px/1.5. Derive
+   from THIS brand — a look repeated across projects is a failure, not a shortcut. The user's
+   explicit direction beats all of this except the contrast floor. */
+@theme {
+  --color-background: hsl(0 0% 100%);
+  --color-foreground: hsl(230 24% 14%);
+  --color-primary: hsl(230 24% 14%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(228 24% 96%);
+  --color-secondary-foreground: hsl(230 24% 14%);
+  --color-muted-foreground: hsl(228 8% 46%);
+  --color-border: hsl(220 14% 90%);
+  --color-destructive: hsl(0 72% 51%);
+
+  --radius-lg: 12px;
+  --radius-md: 8px;
+  --radius-sm: 6px;
+  /* Buttons, chips, labels, steppers and the progress bar. Follows --radius-md unless the brand
+     wants otherwise: 9999px is the pill, 0 is square. Genuine circles (swatches, avatars, dots)
+     stay rounded-full and do not read this. */
+  --radius-control: var(--radius-md);
+
+  --font-sans: 'Wix Madefor Text', system-ui, sans-serif;
+}
+
+@layer base {
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    font-feature-settings: 'cv02', 'cv03', 'cv04', 'cv11';
+  }
+}
+
+@layer utilities {
+  .eyebrow {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.1em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground);
+  }
+}

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

@@ -0,0 +1,16 @@
+// Wix connection config — written by the skill's deploy step (install/deploy.mjs).
+//
+// WIX_CLIENT_ID = null  → ambient auth (a Wix-managed Astro project: `@wix/astro` authenticates
+//                         every SDK call automatically; there is no client and nothing to set).
+// WIX_CLIENT_ID = "..." → manual visitor client (any other React setup): the public OAuth client id.
+//                         It is NOT a secret — it only mints anonymous visitor tokens — so
+//                         hardcoding and committing it is fine. deploy.mjs copies it from `.env.local`
+//                         (`WIX_CLIENT_ID`, what `wix env pull` writes): the CONTENT site's app — on a
+//                         migration preview the site being migrated, while wix.config.json names
+//                         only the deploy target.
+export const WIX_CLIENT_ID: string | null = null;
+
+// Kept for projects deployed before the Members vertical moved onto the shared seam; the shipped
+// members code no longer reads it (ambient Astro uses the built-in /api/auth routes, manual mode
+// uses the shared client above). deploy.mjs still fills it so older code keeps compiling.
+export const WIX_MEMBERS_CLIENT_ID: string | null = null;

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

@@ -0,0 +1,106 @@
+// Wix media resolution — define once, use on EVERY image render path. Copy as-is.
+//
+// SDK media fields come back either as an already-absolute https URL, or as a
+// `wix:image://v1/<hash>/<file>#originWidth=…` identifier that a browser cannot load
+// (ERR_UNKNOWN_URL_SCHEME). The wix:image:// form must go through the SDK media module;
+// never hand-build a static.wixstatic.com URL (wrong format → 403).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/media.md
+import { media } from "@wix/sdk";
+
+type MediaLike =
+  | string
+  | null
+  | undefined
+  | { image?: unknown; url?: string | null; id?: string | null };
+
+/** A bare Wix media file id (`e6a89e_06cf…~mv2.png`): what REST-shaped media objects carry as `url` and `id`. */
+const BARE_FILE_ID = /^[\w-]+~mv2\.[a-z0-9]+$/i;
+
+function rawOf(value: MediaLike): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (value.image != null && typeof value.image === "object") return rawOf(value.image as MediaLike); // { image: { id, url } }
+  return (typeof value.image === "string" ? value.image : null) ?? value.url ?? value.id ?? "";
+}
+
+/** Resolve any Wix media value to a browser-loadable URL ("" when absent). */
+export function imgSrc(value: MediaLike, width = 600, height = 600): string {
+  const v = rawOf(value);
+  if (!v) return "";
+  if (v.startsWith("wix:image://")) {
+    return media.getScaledToFillImageUrl(v, width, height, {});
+  }
+  // A bare file id (what REST-shaped media objects carry) or an absolute Wix media URL (bare, or
+  // already carrying a /v1/fill/ segment at some other size): re-issue it through the scaler at the
+  // requested size, so every image path lands on one shape.
+  const file = BARE_FILE_ID.test(v) ? v : v.match(/^https:\/\/static\.wixstatic\.com\/media\/([^/?#]+)/)?.[1];
+  if (file) return `https://static.wixstatic.com/media/${file}/v1/fill/w_${width},h_${height},al_c,q_90/${file}`;
+  return v;
+}
+
+/**
+ * Responsive candidates for `srcset`: the same image at several widths through Wix's scaler, so a
+ * card never downloads a hero-sized file. Pair with `sizes`:
+ *   <img src={imgSrc(m, 640, 640)} srcSet={imgSrcSet(m)} sizes="(min-width: 1024px) 25vw, 50vw"
+ *        width={640} height={640} loading="lazy" alt={…} />
+ * Accepts every form an image reaches you in: a raw `wix:image://` id, an ALREADY-RESOLVED Wix URL
+ * (what the DTOs carry — `imageUrl`, `gallery[]`; its `/v1/fill/w_…,h_…` segment is rewritten per
+ * width), or any other https URL (returned as the single candidate). `ratio` is height/width
+ * (1 = square). "" only when there is no image at all — still set `src` as well.
+ */
+export function imgSrcSet(value: MediaLike, widths: number[] = [320, 480, 640, 960], ratio = 1): string {
+  const raw = rawOf(value);
+  if (!raw) return "";
+  if (raw.startsWith("wix:image://") || BARE_FILE_ID.test(raw)) {
+    return widths.map((w) => `${imgSrc(value, w, Math.round(w * ratio))} ${w}w`).join(", ");
+  }
+  // A resolved Wix URL: …/v1/fill/w_800,h_800,al_c,… — swap the size for each width.
+  const FILL = /\/v1\/fill\/w_\d+,h_\d+/;
+  if (/static\.wixstatic\.com\//.test(raw) && FILL.test(raw)) {
+    return widths.map((w) => `${raw.replace(FILL, `/v1/fill/w_${w},h_${Math.round(w * ratio)}`)} ${w}w`).join(", ");
+  }
+  return raw; // one candidate, never an empty srcset for a real image
+}
+
+/**
+ * Everything an <img> needs for one Wix image, so a tile can never ship `srcSet` without `src`:
+ *   <img {...imgAttrs(p.imageUrl, "(min-width: 1024px) 25vw, 50vw")} alt={p.name} />
+ * `sizes` is the width the image renders at (a CSS length or media-query list); `ratio` is
+ * height/width. Returns an empty object when there is no image — render your placeholder then.
+ */
+export function imgAttrs(value: MediaLike, sizes: string, ratio = 1): { src: string; srcSet: string; sizes: string; loading: "lazy"; decoding: "async" } | Record<string, never> {
+  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:
+ *   <img {...imgAttrs(item.photo, "33vw", imgRatio(item.photo) ?? 1)} alt={…} />
+ */
+export function imgRatio(value: MediaLike): number | null {
+  const v = rawOf(value);
+  if (typeof v !== "string" || !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 identity of a media value BEFORE scaling — de-duplicate galleries on this, never on a
+ * resolved URL (two scaled URLs of one photo differ in their size parameters).
+ */
+export function mediaKey(value: MediaLike): 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/app/wix/money.ts

@@ -0,0 +1,24 @@
+// Money formatting for API amounts that carry no formatted string. Copy as-is.
+//
+// Catalog prices come with a ready `formattedAmount` — use that directly. But eCom Cart V2
+// amounts are ConvertedMoney `{ amount, convertedAmount }` with NO formatted string, and the
+// currency lives on the cart, not on the money object. Never hardcode "$" or assume USD.
+export interface ConvertedMoneyLike {
+  amount?: string | null;
+  convertedAmount?: string | null;
+}
+
+/** Format a ConvertedMoney in the given currency, using the visitor's locale. */
+export function formatMoney(
+  money: ConvertedMoneyLike | null | undefined,
+  currencyCode: string | null | undefined,
+): string {
+  const value = money?.convertedAmount ?? money?.amount;
+  if (value == null || value === "") return "";
+  const currency = currencyCode || "USD";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(Number(value));
+  } catch {
+    return `${value} ${currency}`;
+  }
+}

package/skills/wix-headless-templates/shared/app/wix/sdk.ts

@@ -0,0 +1,89 @@
+// The one auth seam for every Wix SDK call in this app. Copy as-is; do not rewrite.
+//
+// Two modes, switched by WIX_CLIENT_ID in ./config:
+//   null (ambient)  — a Wix-managed Astro project: `@wix/astro` authenticates raw SDK module
+//                     calls automatically, server-side AND in client islands. `wixModule()`
+//                     returns the module untouched.
+//   string (manual) — any other React setup (Vite SPA, non-Astro): one shared client is built
+//                     with OAuthStrategy, and `wixModule()` returns the module bound to it.
+//                     The strategy self-manages visitor tokens on every call (mints on first
+//                     use, renews on expiry) and persists them through the storage below.
+//
+// The visitor token IS the identity of the current cart / member session, so in manual mode
+// tokens persist to localStorage — never re-minted per load (a fresh anonymous mint is a NEW
+// visitor and silently empties the cart).
+// docs: https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md
+// docs: https://dev.wix.com/docs/go-headless/wix-managed-headless/authentication/about-the-astro-integration.md
+import { createClient, OAuthStrategy, EMPTY_TOKENS } from "@wix/sdk";
+import { fetchWithAuth as ambientFetch } from "@wix/sdk/context";
+import type { IOAuthStrategy, TokenStorage, Tokens } from "@wix/sdk";
+import { WIX_CLIENT_ID } from "./config";
+
+const STORAGE_KEY = `wix-session-${WIX_CLIENT_ID ?? "ambient"}`;
+
+function browserTokenStorage(): TokenStorage {
+  return {
+    getTokens(): Tokens {
+      if (typeof window !== "undefined") {
+        try {
+          const raw = window.localStorage.getItem(STORAGE_KEY);
+          if (raw) return JSON.parse(raw) as Tokens;
+        } catch {
+          /* disabled/corrupt storage — fall through to empty */
+        }
+      }
+      return EMPTY_TOKENS;
+    },
+    setTokens(tokens: Tokens): void {
+      if (typeof window === "undefined") return;
+      try {
+        window.localStorage.setItem(STORAGE_KEY, JSON.stringify(tokens));
+      } catch {
+        /* storage full/disabled — the session just won't survive a reload */
+      }
+    },
+  };
+}
+
+const client = WIX_CLIENT_ID
+  ? createClient({
+      auth: OAuthStrategy({
+        clientId: WIX_CLIENT_ID,
+        tokenStorage: browserTokenStorage(),
+      }),
+    })
+  : null;
+
+/**
+ * Bind an SDK module to this app's auth. Usage (identical in both modes):
+ *   import { productsV3 } from "@wix/stores";
+ *   const products = wixModule(productsV3);
+ *   await products.queryProducts(...)
+ */
+export function wixModule<T>(module: T): T {
+  // The cast bridges the SDK's internal Descriptors constraint; the in/out type is identical.
+  return client
+    ? (client.use(module as unknown as Record<string, unknown>) as unknown as T)
+    : module;
+}
+
+/**
+ * An authenticated fetch of a Wix REST endpoint under the SAME auth as the SDK modules (ambient
+ * on managed Astro, the shared client elsewhere) — for the few APIs whose generated SDK module is
+ * too heavy to bundle (the Forms schema module alone is 15 MB: server-side it pushes a Wix
+ * deploy past its size limit, client-side every visitor downloads it). Same visitor identity,
+ * same token, no second mint. `path` is the wixapis.com path; returns the raw Response.
+ */
+export function wixFetch(path: string, init?: RequestInit): Promise<Response> {
+  const url = path.startsWith("http") ? path : `https://www.wixapis.com${path}`;
+  return client ? client.fetchWithAuth(url, init) : ambientFetch(url, init);
+}
+
+/**
+ * The shared data client's manual-mode auth strategy, or null under ambient auth. The
+ * Members vertical deliberately owns a separate explicit client for its custom in-app login;
+ * app code reads that session through the members hooks instead.
+ */
+export function wixAuth(): IOAuthStrategy | null {
+  return client ? client.auth : null;
+}

package/skills/wix-headless-templates/shared/capabilities/media-upload/app/wix/media-upload/client.ts

@@ -0,0 +1,46 @@
+// Safe browser half of the optional Media Upload capability.
+// The browser supplies bytes only. It cannot choose a destination or elevate a Wix call:
+// the named policy is enforced by /api/wix/media-upload on the server.
+
+export type UploadedMedia = {
+  id: string;
+  url?: string;
+  uploadUrl: string;
+};
+
+type UploadPolicyRequest = {
+  policyId: string;
+  fileName: string;
+  mimeType: string;
+  sizeInBytes: number;
+};
+
+export async function uploadMedia(policyId: string, file: File | Blob, fileName?: string): Promise<UploadedMedia> {
+  const mimeType = file.type;
+  const request: UploadPolicyRequest = {
+    policyId,
+    fileName: fileName ?? (file instanceof File ? file.name : "upload"),
+    mimeType,
+    sizeInBytes: file.size,
+  };
+  const ticket = await fetch("/api/wix/media-upload", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+  });
+  if (!ticket.ok) throw new Error(`Upload could not be authorized (${ticket.status})`);
+  const { uploadUrl } = (await ticket.json()) as UploadedMedia;
+
+  const uploaded = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: file,
+  });
+  const payload = (await uploaded.json().catch(() => null)) as
+    | { file?: { id?: string; url?: string }; id?: string; url?: string }
+    | null;
+  const media = payload?.file ?? payload;
+  if (!uploaded.ok || !media?.id) throw new Error(`Upload failed (${uploaded.status})`);
+
+  return { id: media.id, url: media.url, uploadUrl };
+}

package/skills/wix-headless-templates/shared/capabilities/media-upload/app-astro/pages/api/wix/media-upload.ts

@@ -0,0 +1,69 @@
+import type { APIRoute } from "astro";
+import { auth } from "@wix/essentials";
+import { files } from "@wix/media";
+import { members } from "@wix/members";
+import { mediaUploadPolicies } from "../../../wix/media-upload/policies.generated";
+
+const elevatedGenerateUploadUrl = auth.elevate(files.generateFileUploadUrl);
+
+/**
+ * Who may use a policy. `members` (the default) admits a logged-in member only: the caller's own
+ * session is read server-side, so an anonymous visitor gets 401 before anything is elevated.
+ * `visitors` admits anyone — only for a policy the product means for the public (a form's file
+ * field on a free site). A members policy needs the Wix Members Area app (the members seed
+ * installs it): without it a logged-in member reads back as nobody.
+ */
+// Typed loosely on purpose: the generated file is `as const`, and a literal-typed `audience` would
+// make the comparison below a type error whenever every policy in it says the same thing.
+type Policy = { id: string; accept: readonly string[]; maxBytes: number; audience?: "members" | "visitors" };
+const policies: readonly Policy[] = mediaUploadPolicies;
+
+async function callerIsMember(): Promise<boolean> {
+  try {
+    const { member } = await members.getCurrentMember();
+    return Boolean(member?._id);
+  } catch {
+    return false;
+  }
+}
+
+type UploadRequest = {
+  policyId?: unknown;
+  fileName?: unknown;
+  mimeType?: unknown;
+  sizeInBytes?: unknown;
+};
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+
+export const POST: APIRoute = async ({ request }) => {
+  let body: UploadRequest;
+  try {
+    body = (await request.json()) as UploadRequest;
+  } catch {
+    return json({ error: "Expected JSON" }, 400);
+  }
+
+  if (
+    typeof body.policyId !== "string" ||
+    typeof body.fileName !== "string" ||
+    typeof body.mimeType !== "string" ||
+    typeof body.sizeInBytes !== "number" ||
+    !Number.isSafeInteger(body.sizeInBytes)
+  ) {
+    return json({ error: "Invalid upload request" }, 400);
+  }
+  const policy = policies.find((candidate) => candidate.id === body.policyId);
+  if (!policy) return json({ error: "Unknown upload policy" }, 404);
+  if (policy.audience !== "visitors" && !(await callerIsMember())) return json({ error: "Log in to upload" }, 401);
+  if (!policy.accept.includes(body.mimeType)) return json({ error: "File type is not allowed" }, 415);
+  if (body.sizeInBytes < 1 || body.sizeInBytes > policy.maxBytes) return json({ error: "File exceeds this policy's size limit" }, 413);
+
+  // Do not accept a folder id, labels, privacy setting, or any other destination choice from
+  // the browser. Add those as fixed policy fields only after the product actually needs them.
+  const result = await elevatedGenerateUploadUrl(body.mimeType, {
+    fileName: body.fileName.slice(0, 255),
+  });
+  return json({ uploadUrl: result.uploadUrl });
+};