@wix/agent-skills 1.26.0 → 1.28.0

package/skills/wix-headless-templates/forms/project/src/wix/forms/types.ts

@@ -0,0 +1,284 @@
+// Forms DTOs — the serializable shapes every hook and page consumes. A form is schema-driven
+// (the owner picks the fields in their dashboard), so a FormDto is a LIST of fields rather
+// than a fixed interface: render by mapping `form.fields`, never by naming fields in code.
+//
+// Why a DTO at all, when the schema IS the model: the raw `Form` nests a field's settings two
+// levels deep under blocks named after its own enums
+// (`inputOptions.stringOptions.dropdownOptions.label`), carries Date objects and Ricos
+// rich-content labels that are not island-serializable, and spreads display ORDER across
+// `steps[].layout` rather than `formFields[]`. FormFieldDto is that resolved once, in the data
+// layer, into flat keys — the same rule every other vertical here follows.
+//
+// It is a FLATTENING, not a subset: every setting a renderer needs is carried through. When a
+// field kind needs something not listed here, add the key — never reach past the DTO into the
+// raw form.
+
+/** What the visitor types into. Drives which control your component renders. */
+export type FormControl =
+  | "text"
+  | "textarea"
+  | "password"
+  | "number"
+  | "rating"
+  | "email"
+  | "phone"
+  | "url"
+  | "date"
+  | "time"
+  | "datetime"
+  | "select"
+  | "radio"
+  | "checkbox"
+  | "checkboxGroup"
+  | "tags"
+  | "address"
+  | "file"
+  | "signature"
+  | "payment"
+  /** A bookings slot picker embedded in a form — needs the `bookings` vertical, not an <input>. */
+  | "appointment"
+  | "unknown";
+
+/** One choice in a select / radio / checkbox group. */
+export interface FormChoice {
+  value: string;
+  /** The owner's wording, falling back to `value` so a choice is never blank. */
+  label: string;
+  /** IMAGE_CHOICE only: the option's picture, already a browser-loadable URL. */
+  imageUrl?: string;
+}
+
+/** One subfield of an ADDRESS field — its own control, its own error key (`target/sub`). */
+export interface FormAddressPart {
+  /**
+   * `country`, `addressLine`, `streetName`, `streetNumber`, `city`, `subdivision`, `postalCode`, … —
+   * also the key inside the submitted object. WHICH subfields appear, and in what order, follows
+   * the chosen country (Wix's own per-country address templates: Israel has a street name and
+   * number and no subdivision, the United States one address line and a state), so re-read
+   * `addressParts` from the store after the country changes.
+   */
+  sub: string;
+  /** "Postal code", or the country's own word for its subdivision ("State", "Province", "Region"). */
+  label: string;
+  required: boolean;
+  /**
+   * `country`: ISO-2 codes to offer — the owner's `allowedCountries`, else every country.
+   * `subdivision`: the country's states / provinces / regions (value is the ISO 3166-2 code, "US-NY");
+   * absent when the country has none on record — render a text input then.
+   */
+  choices?: FormChoice[];
+}
+
+/** The owner's address settings, kept on the field so the parts can be recomputed for a country. */
+export interface AddressOverrides {
+  /** `validation.fields[sub].required` */
+  required: Record<string, boolean | undefined>;
+  /** `multilineAddressOptions.fieldSettings[sub].show` */
+  show: Record<string, boolean | undefined>;
+  /** `validation.allowedCountries`; empty means every country. */
+  allowedCountries: string[];
+}
+
+/** The schema's own rules, resolved onto the field. Undefined means the owner set no rule. */
+export interface FormValidation {
+  /** EMAIL | PHONE | URL | DATE | TIME | DATE_TIME — drives both the control type and the format check. */
+  format?: string;
+  minLength?: number;
+  maxLength?: number;
+  /** A regex SOURCE string, not a RegExp — compile it at the call site. */
+  pattern?: string;
+  /** The owner's wording for a `pattern` miss (`validationMessages.pattern`); fall back to yours. */
+  patternMessage?: string;
+  /** NUMBER / rating bounds. */
+  minimum?: number;
+  maximum?: number;
+  /** NUMBER step: 0.01 means two decimals; 1 means whole numbers. */
+  multipleOf?: number;
+  /** date / time / datetime bounds, already resolved to ISO (`$now+2d` becomes a real date at load). */
+  minDate?: string;
+  maxDate?: string;
+  /** WIX_FILE: how many files this field accepts (Wix caps it at 30). */
+  fileLimit?: number;
+  /** WIX_FILE: the owner's format families — VIDEO | IMAGE | AUDIO | DOCUMENT | ARCHIVE; empty = any. */
+  fileFormats?: string[];
+  /** WIX_FILE: those families as an `<input accept>` value; "" when any file goes. */
+  accept?: string;
+  /** Multi-choice bounds, when the owner set them. */
+  minItems?: number;
+  maxItems?: number;
+  /** A consent checkbox that must be ticked (`booleanOptions.validation.enum: [true]`). */
+  mustBeTrue?: boolean;
+  /** PHONE: ISO-2 country codes the number may belong to; empty = any. */
+  allowedCountryCodes?: string[];
+}
+
+/**
+ * One visible input, flattened. `target` is the field's immutable storage key — the input's
+ * `name`, the key in `values`, the key in the submission, and the root of the server's error
+ * paths. Everything is keyed by it, so nothing has to be matched by label or index.
+ */
+export interface FormFieldDto {
+  target: string;
+  /** The owner's label. Never empty — falls back to `target`. Always a string (a consent
+   *  checkbox labels itself with rich content upstream; that is flattened to its plain text). */
+  label: string;
+  /** false when the owner hid the label; keep it for assistive tech (aria-label), not on screen. */
+  showLabel: boolean;
+  control: FormControl;
+  required: boolean;
+  /** The visitor cannot change it; it submits its prefill. Render disabled, skip the required check. */
+  readOnly: boolean;
+  /** Hidden right now — by the owner, or by a rule reacting to the current values. Not rendered, not submitted. */
+  hidden: boolean;
+  /** The step this field is laid out on (`FormDto.steps[].id`). */
+  stepId: string;
+  placeholder?: string;
+  /** Help text shown under the control, when the owner wrote one. */
+  description?: string;
+  /** The owner's prefill: "" / [] / {} / false when unset, so the control is controlled from render one. */
+  defaultValue: string | number | boolean | string[] | Record<string, string>;
+  /** select / radio / checkboxGroup / tags — empty for every other control. After rules: the allowed subset. */
+  choices: FormChoice[];
+  /** A free-text "Other" entry the owner enabled on a choice field. Its submitted value is `otherValue(field, text)`. */
+  otherOption?: { label: string; placeholder?: string };
+  /**
+   * address only — empty for every other control. `country` is always first. The store recomputes
+   * these for the country the visitor picked (`FormState.form.fields`), so take them from there.
+   */
+  addressParts: FormAddressPart[];
+  /** address only: what the recomputation needs. Not for rendering. */
+  addressOverrides?: AddressOverrides;
+  validation: FormValidation;
+  /** phone only: the country whose example to show ("US", "GB", …). */
+  phoneCountry?: string;
+  /** file only: the owner's button wording, and the text shown once a file is picked. */
+  buttonText?: string;
+  explanationText?: string;
+  /**
+   * The field's kind as the owner picked it — TEXT_AREA, IMAGE_CHOICE, CONTACTS_EMAIL,
+   * CONTACTS_BIRTHDATE, CONTACTS_SUBSCRIBE, … Several kinds share one component (short and long
+   * answer are both TEXT_INPUT; image choice and multi choice are both CHECKBOX_GROUP), so this is
+   * what separates them when `control` cannot.
+   */
+  identifier: string;
+  /** The raw `inputType` / `componentType`, for the rare branch the flattening does not cover. */
+  inputType: string;
+  componentType: string;
+}
+
+/** One page of a multi-step form. A single-step form has exactly one. */
+export interface FormStep {
+  id: string;
+  /** The owner's step name, "" when unnamed. */
+  name: string;
+  /** The targets laid out on this step, in display order. */
+  targets: string[];
+}
+
+/**
+ * A condition as the owner built it in the Rules tab, normalized from both schema spellings.
+ * Operators are the v4 names: EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY, CONTAINS, NOT_CONTAINS,
+ * LESS_THAN, LESS_THAN_OR_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUALS, BEFORE, BEFORE_OR_EQUAL,
+ * AFTER, AFTER_OR_EQUAL, BETWEEN, ANY, ARRAY_EQUAL, ARRAY_NOT_EQUAL, CHECKED, NOT_CHECKED, IN,
+ * NOT_IN, IS_DATE_OLDER_THAN(_OR_EQUAL), IS_DATE_NEWER_THAN(_OR_EQUAL).
+ */
+export type RuleCondition =
+  | { and: RuleCondition[] }
+  | { or: RuleCondition[] }
+  | { target: string; operator: string; value?: unknown };
+
+/** What a rule changes on one field while its condition holds. */
+export interface RuleEffect {
+  target: string;
+  hidden?: boolean;
+  required?: boolean;
+  /** The choice values that stay selectable. */
+  allowedValues?: string[];
+}
+
+export interface FormRule {
+  id: string;
+  when: RuleCondition;
+  then: RuleEffect[];
+}
+
+/** What the owner chose to happen after a successful submit (dashboard: Submit settings). */
+export interface FormSuccess {
+  /** THANK_YOU_MESSAGE | REDIRECT | POPUP | NO_ACTION — NO_ACTION when the owner set nothing. */
+  action: string;
+  /** THANK_YOU_MESSAGE: the owner's text, paragraphs separated by "\n". */
+  message?: string;
+  /** THANK_YOU_MESSAGE: auto-hide the message after this many seconds and show the form again. */
+  durationSeconds?: number;
+  /** REDIRECT: the owner's URL (always https://). */
+  redirectUrl?: string;
+  /** REDIRECT: open in a new tab rather than replacing the page. */
+  newTab?: boolean;
+}
+
+/** One form, ready to render. */
+export interface FormDto {
+  id: string;
+  /** The owner's form name — an internal label, not necessarily page copy. */
+  name: string;
+  /** Every input, in the order the owner laid out (across steps, in step order). Hidden ones carry `hidden: true`. */
+  fields: FormFieldDto[];
+  /** The pages of the form, in order. One entry for a plain form. */
+  steps: FormStep[];
+  /** The owner's rules. The store applies them; a page never evaluates them itself. */
+  rules: FormRule[];
+  /** The owner's submit-button wording, or "" when they left the default. */
+  submitText: string;
+  /** Multi-step: the next / back button wording, "" when default. */
+  nextText: string;
+  previousText: string;
+  /** false when the owner switched the form off. Show `disabledMessage` instead of the form. */
+  enabled: boolean;
+  /** The owner's "form closed" text ("" when unset — write your own). */
+  disabledMessage: string;
+  /** The owner's submission limits. The form closes itself at `deadline`; the counts are enforced server-side. */
+  limits: { deadline?: string; maxSubmissions?: number; perVisitor?: number };
+  /** How the owner marks required fields: ASTERISK | TEXT ("Required") | NONE, and where. */
+  requiredIndicator: string;
+  requiredIndicatorBefore: boolean;
+  success: FormSuccess;
+}
+
+/** `target` → the visitor's current value. Arrays for multi-choice, objects for an address. */
+export type FormValues = Record<string, unknown>;
+
+/**
+ * `target` (or `target/sub`) → a visitor-facing message. The key is the control's `name`, so a
+ * message lands on its own control with no mapping table.
+ */
+export type FormErrors = Record<string, string>;
+
+/** An uploaded attachment as the submission carries it (the WIX_FILE value is a list of these). */
+export interface UploadedFile {
+  fileId: string;
+  displayName: string;
+  fileType: string;
+  url?: string;
+}
+
+/** A created submission. There is nothing to read back — this IS the confirmation. */
+export interface SubmissionDto {
+  id: string;
+  /** CONFIRMED | PENDING | PAYMENT_WAITING — all three mean the submission exists. */
+  status: string;
+  /** PAYMENT_WAITING only: the checkout the visitor must be sent to (`checkoutUrl(checkoutId)`). */
+  checkoutId?: string;
+}
+
+/** What a successful `submit()` resolves to — the owner's submit settings applied to this submission. */
+export interface SubmitOutcome {
+  submission: SubmissionDto;
+  /** CHECKOUT | THANK_YOU_MESSAGE | REDIRECT | POPUP | NO_ACTION. */
+  action: string;
+  /** THANK_YOU_MESSAGE: the owner's text; absent → your own thank-you. */
+  message?: string;
+  durationSeconds?: number;
+  /** CHECKOUT or REDIRECT: navigate the document here. */
+  url?: string;
+  newTab?: boolean;
+}

package/skills/wix-headless-templates/forms/project/src/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/forms/project/src/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/forms/project/src/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/forms/project/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/skills/wix-headless-templates/forms/rest/forms.ts

@@ -0,0 +1,37 @@
+// Form-schema reads over REST — the twin of app/wix/forms/forms.ts. Same exports, same FormDto; the
+// flattening rules come from forms-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 per
+// function. Both calls run with the visitor token — the schema read is listed under an owner scope
+// and still returns 200 to an anonymous visitor, so a published site can render its own forms.
+// Porting: keep the paths, keep the query, port the core once.
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms.md
+import { wixRequest } from "./client.js";
+import { imgSrc } from "./media.js";
+import { FORMS_NAMESPACE, applyRules, isClosed, otherText, otherValue, toForm, type Raw } from "./forms-core.js";
+import type { FormDto } from "./types.js";
+
+export { FORMS_NAMESPACE, applyRules, isClosed, otherText, otherValue };
+
+/**
+ * One form by id. Throws (a WixApiError, 404 FORM_NOT_FOUND) when the id is wrong or the form was
+ * deleted — a form that cannot load is a setup problem; never render a hand-built fallback. A form
+ * the owner switched OFF still loads, with `enabled: false` and the owner's `disabledMessage`.
+ * GET /form-schema-service/v4/forms/{formId}  → { form }
+ */
+export async function getForm(formId: string): Promise<FormDto> {
+  const res = await wixRequest<Raw>(`/form-schema-service/v4/forms/${encodeURIComponent(formId)}`, { method: "GET" });
+  if (!res?.form) throw new Error(`forms: form "${formId}" not found.`);
+  return toForm(res.form, imgSrc);
+}
+
+/**
+ * Every ENABLED form in the Wix Forms namespace (the list's `enabled` filter defaults to true, so
+ * a disabled form vanishes from the listing rather than erroring). `namespace` is required —
+ * without it the call is a 400.
+ * GET /form-schema-service/v4/forms?namespace=wix.form_app.form  → { forms, pagingMetadata }
+ */
+export async function listForms(): Promise<FormDto[]> {
+  const res = await wixRequest<Raw>("/form-schema-service/v4/forms", { method: "GET", query: { namespace: FORMS_NAMESPACE } });
+  return ((res?.forms ?? []) as Raw[]).map((raw) => toForm(raw, imgSrc));
+}

package/skills/wix-headless-templates/forms/rest/submissions.ts

@@ -0,0 +1,83 @@
+// Submissions over REST — the twin of app/wix/forms/submissions.ts. Same exports, same
+// SubmissionDto; the rules come from submissions-core (the SAME file the SDK transport uses,
+// deployed flat next to this one). Every call runs with the visitor token: `CreateSubmission` is
+// listed under an owner scope and still returns 200 to an anonymous visitor, so a published site
+// can submit its own forms. Submissions are write-only from a visitor — the resolved create IS
+// the confirmation. A rejection throws a WixApiError whose `details` block `submissionErrors` and
+// `formLevelError` map onto the page; let it throw.
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { wixRequest } from "./client.js";
+import type { Raw } from "./forms-core.js";
+import {
+  SUBMITTED_OK,
+  formLevelError,
+  normalizePhone,
+  normalizeUrl,
+  putUpload,
+  redirectSessionBody,
+  redirectSessionUrl,
+  submissionErrors,
+  toSubmission,
+  toSubmissionValues,
+  uploadFilesWith,
+  uploadMimeType,
+} from "./submissions-core.js";
+import type { FormFieldDto, FormValues, SubmissionDto, UploadedFile } from "./types.js";
+
+export { SUBMITTED_OK, formLevelError, normalizePhone, normalizeUrl, submissionErrors, toSubmissionValues };
+
+const SUBMISSIONS = "/form-submission-service/v4/submissions";
+
+/**
+ * Upload one File and return the value to submit for its field ({ fileId, displayName, fileType, url }).
+ * POST /form-submission-service/v4/submissions/media-upload-url  { formId, filename, mimeType }  → { uploadUrl }
+ * then PUT the bytes to that URL with plain fetch (submissions-core.putUpload) and read its `file` back.
+ */
+export async function uploadFile(formId: string, file: File): Promise<UploadedFile> {
+  const mimeType = uploadMimeType(file);
+  const res = await wixRequest<Raw>(`${SUBMISSIONS}/media-upload-url`, { body: { formId, filename: file.name, mimeType } });
+  const uploadUrl: string | undefined = res?.uploadUrl;
+  if (!uploadUrl) throw new Error(`forms: no upload URL for "${file.name}".`);
+  return putUpload(uploadUrl, file, mimeType);
+}
+
+/** Upload every File in the form's values; returns a copy with each file field holding its uploaded entries. */
+export async function uploadFiles(formId: string, fields: FormFieldDto[], values: FormValues): Promise<FormValues> {
+  return uploadFilesWith(uploadFile, formId, fields, values);
+}
+
+export interface CreateSubmissionOptions {
+  /** A captcha token when the site runs a captcha widget; the server answers INVALID_CAPTCHA when it wants one and got none. */
+  captchaToken?: string;
+}
+
+/**
+ * Create the submission — the write, and the only confirmation there is. `values` is
+ * toSubmissionValues(fields, values): every key a field `target`, every value in that field's
+ * shape. A 400 carries details.validationError.fieldViolations[].data.errors[] (errorPath,
+ * errorType, useCustomErrorMessage) or details.applicationError.code on the thrown WixApiError.
+ * POST /form-submission-service/v4/submissions  { submission: { formId, submissions }, captchaToken? }  → { submission: { id, status, orderDetails? } }
+ */
+export async function createSubmission(
+  formId: string,
+  values: Record<string, unknown>,
+  { captchaToken }: CreateSubmissionOptions = {},
+): Promise<SubmissionDto> {
+  const created = await wixRequest<Raw>(SUBMISSIONS, {
+    body: { submission: { formId, submissions: values }, ...(captchaToken ? { captchaToken } : {}) },
+  });
+  return toSubmission(created);
+}
+
+/**
+ * The Wix-hosted checkout for a `PAYMENT_WAITING` submission — navigate the FULL document to the
+ * URL. `origin` must be the site's real https origin (window.location.origin) as registered on
+ * the OAuth app, so the checkout can send the visitor back.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks: { postFlowUrl, thankYouPageUrl } }  → { redirectSession: { fullUrl } }
+ */
+export async function checkoutUrl(checkoutId: string, origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const res = await wixRequest<Raw>("/headless/v1/redirect-session", { body: redirectSessionBody(checkoutId, origin) });
+  return redirectSessionUrl(res);
+}