@wix/agent-skills 1.26.0 → 1.27.0

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

@@ -0,0 +1,57 @@
+// Wix Forms schema reads — the only file that touches a raw Form on this transport. Returns flat
+// FormDto / FormFieldDto from ./types. The flattening rules live in ./forms-core (shared with the
+// REST twin in templates/forms/rest/); this file is the transport only. Copy as-is; extend by
+// adding functions.
+//
+// The reads go over `wixFetch` (the SDK's own authenticated fetch), NOT the `forms` module of
+// @wix/forms: that generated module is 15 MB. Bundled server-side it pushes a Wix deploy past its
+// size limit (HTTP 413 on release); bundled client-side every visitor downloads it. The
+// submissions module (./submissions.ts) is 100 KB and stays on the SDK.
+//
+// The visitor token is enough, and the spec says otherwise. Every schema read is listed under
+// the owner scope `SCOPE.FORMS.VIEW-FORM`, and returns 200 on an anonymous visitor: Wix grants
+// implicit visitor access so a published site can render its own forms. Do NOT add a backend, a
+// connector token, or auth.elevate to make a form load.
+//
+// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/get-form.md
+// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/forms/list-forms.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
+import { wixFetch } from "../sdk";
+import { imgSrc } from "../media";
+import { FORMS_NAMESPACE, applyRules, isClosed, otherText, otherValue, toForm, type Raw } from "./forms-core";
+import type { FormDto } from "./types";
+
+export { FORMS_NAMESPACE, applyRules, isClosed, otherText, otherValue };
+
+async function getJson(path: string): Promise<Raw> {
+  const res = await wixFetch(path);
+  if (!res.ok) throw new Error(`forms: GET ${path} failed (${res.status}).`);
+  return (await res.json()) as Raw;
+}
+
+/**
+ * Read one form by id. Throws when the id is wrong or the form was deleted — a form that
+ * cannot load is a setup problem, so fail loudly rather than rendering a hand-built fallback
+ * that would drop real enquiries silently. A form the owner switched OFF still loads, with
+ * `enabled: false` and the owner's `disabledMessage` — show that instead of the fields.
+ */
+export async function getForm(formId: string): Promise<FormDto> {
+  // GET /form-schema-service/v4/forms/{formId} → { form }; 404 FORM_NOT_FOUND on a wrong id.
+  const res = await getJson(`/form-schema-service/v4/forms/${encodeURIComponent(formId)}`);
+  if (!res?.form) throw new Error(`forms: form "${formId}" not found.`);
+  return toForm(res.form as Raw, imgSrc);
+}
+
+/**
+ * Every form on the site, in the Wix Forms namespace. Use ONE call for several forms on a page
+ * rather than a getForm each.
+ *
+ * Returns only ENABLED forms: the list call's `enabled` filter defaults to true
+ * (ListFormsOptions in the v4 typings), so a form the owner disabled vanishes from the listing
+ * rather than erroring. That is usually right for a public site; `getForm` still reads it.
+ */
+export async function listForms(): Promise<FormDto[]> {
+  // GET /form-schema-service/v4/forms?namespace=… → { forms }; the namespace is required (400 without).
+  const res = await getJson(`/form-schema-service/v4/forms?namespace=${encodeURIComponent(FORMS_NAMESPACE)}`);
+  return ((res?.forms ?? []) as Raw[]).map((raw) => toForm(raw, imgSrc));
+}

package/skills/wix-headless-templates/forms/app/wix/forms/submissions-core.ts

@@ -0,0 +1,423 @@
+// Submission rules — transport-agnostic, imported by BOTH transports: ./submissions.ts (the SDK)
+// and the REST twin in templates/forms/rest/submissions.ts. What a visitor's values become on
+// the wire, which statuses mean "created", how a rejection maps back onto controls, how an
+// attachment is uploaded, and how a paid submission hands off to checkout — all HERE, once. A
+// created submission may arrive wrapped (`{ submission }`, REST) or bare (SDK), with `_id` (SDK)
+// or `id` (REST); the mapper accepts both.
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
+import { humanizeSub, type Raw } from "./forms-core";
+import type { FormDto, FormFieldDto, FormValues, SubmissionDto, UploadedFile } from "./types";
+
+/**
+ * Statuses that mean the submission EXISTS — `CONFIRMED` is recorded, `PENDING` is created but
+ * not recorded yet, `PAYMENT_WAITING` is created on a form that also collects payment and now
+ * needs the visitor at checkout (`SubmissionDto.checkoutId`). Treating one as a failure invites
+ * the visitor to submit again, which costs the owner duplicate entries for a submission that
+ * already exists. `PAYMENT_CANCELED` also exists in the enum but is never what a create returns.
+ *
+ * An allowlist rather than a catch-all, so a status added to the enum later cannot silently
+ * render a thank-you for something that is not a submission.
+ */
+export const SUBMITTED_OK = new Set(["CONFIRMED", "PENDING", "PAYMENT_WAITING"]);
+
+/**
+ * Strip visitor-added formatting from a phone number — submit this, not the raw control text.
+ * Wix keeps digits and the leading + only (normalize-values.ts acceptPhoneValue).
+ */
+export const normalizePhone = (v: unknown): string => String(v ?? "").replace(/[^0-9+]/g, "");
+
+/**
+ * "example.com/page" → "https://example.com/page". Wix's own field prefixes a scheme on blur
+ * when the text looks like a domain; a value that already has one, or does not look like a
+ * host, is returned as typed.
+ */
+export function normalizeUrl(v: unknown): string {
+  const s = String(v ?? "").trim();
+  if (!s || /^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return s;
+  return /^[\w-]+(\.[\w-]+)+(\/|$|\?|#)/.test(s) ? `https://${s}` : s;
+}
+
+/** Wix's own email pattern (form-validator email-validation.ts): unicode-aware, a letter in the TLD. */
+const L = "\\u00A1-\\uD7FF\\uE000-\\uFFFF-a-zA-Z";
+const LD = `${L}0-9`;
+const SYM = "!#$%&'*+/=?^_`{|}~-";
+export const EMAIL_PATTERN = new RegExp(
+  `^(?:[${LD}${SYM}]+(?:\\.[${LD}${SYM}]+)*)@(?:[${LD}](?:[${LD}-]*[${LD}])?\\.)+(?:(?:[0-9]+[${L}][${LD}]*)|(?:[${L}][${LD}]{1,}))$`,
+);
+
+/** E.164 as the server checks it (ajv-custom-formats.ts): a leading +, then 2 to 15 digits. */
+export const PHONE_PATTERN = /^\+[1-9]\d{1,14}$/;
+
+/** Uploads a File and resolves to the value to submit for it. */
+export type UploadOne = (formId: string, file: File) => Promise<UploadedFile>;
+
+/**
+ * A browser leaves `type` empty for extensions it does not recognize; the generic type keeps
+ * the upload-URL call valid (Media Manager rejects a mime type that contradicts the extension).
+ */
+export const uploadMimeType = (file: File): string => file.type || "application/octet-stream";
+
+/** A value already produced by an upload (a retry after the server rejected some OTHER field). */
+export const isUploaded = (v: unknown): v is UploadedFile =>
+  typeof v === "object" && v !== null && typeof (v as Raw).fileId === "string" && typeof (v as Raw).displayName === "string";
+
+/**
+ * PUT the bytes to the generated upload URL and build the value to submit for the field.
+ *
+ * A WIX_FILE value is a list of `{ fileId, displayName, fileType, url }` — the three ids are
+ * required by the server's schema (predefined-schema-property-mapper.ts), `url` is what the
+ * owner's dashboard links. Wix's own runtime reads the PUT response's `file` (use-upload-file.tsx
+ * + headless file-upload-utils.ts) rather than submitting a bare URL. The PUT goes to a pre-signed
+ * host with plain `fetch`, never through the SDK or the REST client: adding the visitor's
+ * Authorization header to a pre-signed URL turns a working upload into a 400.
+ */
+export async function putUpload(uploadUrl: string, file: File, mimeType: string = uploadMimeType(file)): Promise<UploadedFile> {
+  const put = await fetch(`${uploadUrl}?filename=${encodeURIComponent(file.name)}`, {
+    method: "PUT",
+    headers: { "Content-Type": mimeType },
+    body: file,
+  });
+  if (!put.ok) {
+    // Media Manager's own codes land here: FILE_SIZE_OVER_LIMIT, UNSUPPORTED_FILE_FORMAT,
+    // MISMATCH_MIME_TYPE, ZERO_FILE_SIZE, SITE_QUOTA_EXCEEDED.
+    throw new Error(`forms: could not upload "${file.name}" (${put.status}). Check its size and type.`);
+  }
+  let uploaded: Raw = {};
+  try { uploaded = ((await put.json()) as Raw)?.file ?? {}; } catch { /* a body-less 200: the ids below still describe the file */ }
+  return {
+    // Wix's headless wrapper submits a placeholder id when it has none (react/Form.tsx), so the
+    // server accepts any string here; the real Media Manager id is used when the PUT returns it.
+    fileId: String(uploaded.id ?? uploaded.fileId ?? "uploaded"),
+    displayName: String(uploaded.displayName ?? file.name),
+    fileType: mimeType,
+    ...(uploaded.url ? { url: String(uploaded.url) } : {}),
+  };
+}
+
+/**
+ * Upload every File sitting in the form's values and return a copy with each file field
+ * replaced by its uploaded value(s). Values already holding uploaded entries (a retry after the
+ * server rejected some OTHER field) are kept as they are, so a retry never re-uploads. `uploadOne`
+ * is the transport's getMediaUploadUrl + putUpload.
+ */
+export async function uploadFilesWith(
+  uploadOne: UploadOne,
+  formId: string,
+  fields: FormFieldDto[],
+  values: FormValues,
+): Promise<FormValues> {
+  const next: FormValues = { ...values };
+  for (const field of fields) {
+    if (field.hidden || (field.control !== "file" && field.control !== "signature")) continue;
+    const picked = ([] as unknown[]).concat(values[field.target] ?? []);
+    const done: UploadedFile[] = [];
+    // Sequential on purpose: a visitor's uplink is the bottleneck, and a failed file should
+    // stop the submit rather than race more uploads it will throw away.
+    for (const item of picked) {
+      if (isUploaded(item)) done.push(item);
+      else if (typeof File !== "undefined" && item instanceof File) done.push(await uploadOne(formId, item));
+    }
+    next[field.target] = done;
+  }
+  return next;
+}
+
+/** `HH:mm` → `HH:mm:ss`, `YYYY-MM-DDTHH:mm` → `…:ss`: Wix always serializes seconds (time-input-field-headless.tsx, date-time-field-utils.ts). */
+export function withSeconds(value: string): string {
+  return /(^|T)\d{2}:\d{2}$/.test(value) ? `${value}:00` : value;
+}
+
+/**
+ * Turn the visitor's values into the map `createSubmission` expects, keyed by each field's
+ * `target` — the same key the controls are bound to, so the keys come out right by
+ * construction with no hand-maintained list to drift.
+ *
+ * Walks the FIELDS, not the values object: a stray key can never reach the API, and a field
+ * the owner just added shows up the moment the schema does. A field hidden right now (by the
+ * owner or by a rule) is left out, as Wix clears it.
+ *
+ * Value shapes: a flat value (text/choice/date), an ARRAY (multi-choice), an OBJECT (an
+ * address, keyed by subfield — the shape behind `address/city` error paths), a LIST OF FILE
+ * OBJECTS (attachments). An empty optional field is OMITTED rather than sent as "": the server
+ * validates what it is given. A required empty address is sent as `{}` so the server reports
+ * which subfields are missing (multiline-address-toolkit.ts normalizeEmptyValues).
+ */
+export function toSubmissionValues(fields: FormFieldDto[], values: FormValues): Record<string, unknown> {
+  const filled = (v: unknown) => v !== undefined && v !== null && String(v).trim() !== "";
+  const out: Record<string, unknown> = {};
+
+  for (const field of fields) {
+    if (field.hidden) continue;
+    const raw = values?.[field.target];
+
+    if (field.control === "address") {
+      const parts: Record<string, string> = {};
+      const held = (raw ?? {}) as Record<string, unknown>;
+      for (const { sub } of field.addressParts) {
+        if (filled(held[sub])) parts[sub] = String(held[sub]).trim();
+      }
+      if (Object.keys(parts).length || field.required) out[field.target] = parts;
+      continue;
+    }
+
+    if (field.control === "file" || field.control === "signature") {
+      // Whatever the upload produced. A stray File that never went through the upload is
+      // dropped rather than sent, since it would 400 the whole form.
+      const files = ([] as unknown[]).concat(raw ?? []).filter(isUploaded);
+      if (files.length) out[field.target] = files;
+      continue;
+    }
+
+    if (field.inputType === "ARRAY") {
+      const picked = (Array.isArray(raw) ? raw : []).filter(filled);
+      if (picked.length) out[field.target] = picked;
+      continue;
+    }
+
+    if (field.control === "checkbox") {
+      // A consent checkbox submits a boolean. Unchecked AND optional is omitted; unchecked and
+      // required fails validation before it gets here.
+      if (raw === true) out[field.target] = true;
+      continue;
+    }
+
+    if (!filled(raw)) continue;
+    const value = typeof raw === "string" ? raw.trim() : raw;
+    out[field.target] =
+      field.control === "number" || field.control === "rating" ? Number(value) :
+      field.control === "phone" ? normalizePhone(value) :
+      field.control === "url" ? normalizeUrl(value) :
+      field.control === "time" || field.control === "datetime" ? withSeconds(String(value)) :
+      value;
+  }
+  return out;
+}
+
+/**
+ * The created submission as a DTO. Accepts the REST envelope (`{ submission }`) and the SDK's bare
+ * entity; throws when nothing came back or the status is not one that means "created", so a
+ * caller never shows a thank-you for something that is not a submission. A paid form answers
+ * `PAYMENT_WAITING` with `orderDetails.checkoutId` — carried through for the checkout hand-off.
+ */
+export function toSubmission(created: Raw | null | undefined): SubmissionDto {
+  const submission: Raw | undefined = created?.submission ?? created;
+  const id: string | undefined = submission?._id ?? submission?.id;
+  if (!id) throw new Error("forms: submission failed (nothing returned).");
+  const status: string = submission?.status ?? "";
+  if (!SUBMITTED_OK.has(status)) {
+    throw new Error(
+      `forms: submission status is "${status}" — not one of the statuses that mean the submission ` +
+        `was created (${[...SUBMITTED_OK].join(", ")}), so do not show a success state.`,
+    );
+  }
+  const checkoutId: string | undefined = submission?.orderDetails?.checkoutId;
+  return { id, status, ...(checkoutId ? { checkoutId } : {}) };
+}
+
+/**
+ * The redirect-session request that turns a checkout id into the Wix-hosted checkout URL —
+ * the same call the storefront's cart uses. `origin` is the site's real https origin
+ * (window.location.origin) so the checkout can send the visitor back.
+ * POST /headless/v1/redirect-session  { ecomCheckout: { checkoutId }, callbacks }  → { redirectSession: { fullUrl } }
+ * docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+ */
+export function redirectSessionBody(checkoutId: string, origin: string): Record<string, unknown> {
+  return {
+    ecomCheckout: { checkoutId },
+    callbacks: origin ? { postFlowUrl: `${origin}/`, thankYouPageUrl: `${origin}/` } : {},
+  };
+}
+
+export function redirectSessionUrl(res: Raw | null | undefined): string {
+  const url: string | undefined = res?.redirectSession?.fullUrl;
+  if (!url) throw new Error("forms: checkout could not start (no redirect URL returned).");
+  return url;
+}
+
+/** The `details` block of a failed call, wherever the transport left it. */
+function detailsOf(err: unknown): Raw {
+  const e = err as Raw;
+  return e?.details ?? e?.body?.details ?? e?.response?.data?.details ?? {};
+}
+
+/** Every validation entry of a failed create, flattened out of `fieldViolations[].data.errors[]`. */
+function violationEntries(err: unknown): Raw[] {
+  const violations: Raw[] = detailsOf(err)?.validationError?.fieldViolations ?? [];
+  return violations.flatMap((v) => (v.data?.errors ?? [v]) as Raw[]);
+}
+
+/**
+ * Pull per-field violations out of a failed create, keyed by input NAME so each message lands
+ * on its own control. `errorPath` is the field's `target`, or a nested path like
+ * `address/subdivision` — exactly how the controls are named, so it maps straight across.
+ *
+ * The documented entries arrive under `details.validationError.fieldViolations[]`, each with
+ * its own nested `data.errors[]` — two levels deeper than the docs' shape. This flattens that.
+ * The SDK error and the REST client's WixApiError both carry that block as `details`. An entry
+ * flagged `useCustomErrorMessage` carries the owner's own wording — shown verbatim, as Wix does
+ * (use-submit/utils.ts getFieldCustomErrorMessages).
+ *
+ * Two rejections here are SEED bugs, not frontend bugs — fix them in `seed/SEED.md`, never
+ * by mangling the key or the value:
+ *   - UNKNOWN_VALUE_ERROR on a key that IS in the schema → the field was seeded with no
+ *     `validation` block, and that block is what registers the target as an accepted value.
+ *   - NOT_ALLOWED_VALUE_ERROR on a choice field → the seed's `options[].value` and its
+ *     validation enum disagree; the two declarations must match.
+ */
+export function submissionErrors(err: unknown, fields: FormFieldDto[]): Record<string, string> {
+  const byTarget = new Map(fields.map((f) => [f.target, f]));
+  const out: Record<string, string> = {};
+
+  for (const entry of violationEntries(err)) {
+    const path: string | undefined = entry?.errorPath;
+    if (!path) continue;
+    const field = byTarget.get(path.split("/")[0]);
+    if (!field) continue;
+    // Wix's own errorMessage is the validator's internal wording — debug only, unless the owner wrote it.
+    console.debug("forms: server violation", path, entry.errorType, entry.errorMessage);
+    out[path] = entry.useCustomErrorMessage && entry.errorMessage ? String(entry.errorMessage) : messageFor(entry.errorType, field, path);
+  }
+  return out;
+}
+
+/**
+ * The FORM-level message for a failed create that no single control owns: the form was
+ * switched off or hit its limit (DISABLED_FORM_ERROR, errorPath `form.properties.disabled`), an
+ * application error (`details.applicationError.code`: INVALID_CAPTCHA, FORM_NOT_FOUND,
+ * SITE_IS_A_TEMPLATE, FORM_RETRIEVAL_ERROR), or an owner-worded violation with no path. Null when
+ * the failure is something else — the caller shows its generic wording.
+ */
+export function formLevelError(err: unknown, form: FormDto | null): string | null {
+  const details = detailsOf(err);
+  const code: string | undefined = details?.applicationError?.code ?? (err as Raw)?.code;
+  switch (code) {
+    case "INVALID_CAPTCHA": return "The spam check did not pass. Please try again.";
+    case "FORM_NOT_FOUND": return "This form no longer exists.";
+    case "SITE_IS_A_TEMPLATE": return "This site is a template and does not accept submissions.";
+    case "FORM_RETRIEVAL_ERROR": return "The form could not be loaded. Please try again.";
+  }
+  for (const entry of violationEntries(err)) {
+    if (entry.errorType === "DISABLED_FORM_ERROR" || entry.errorPath === "form.properties.disabled") {
+      return form?.disabledMessage || "This form is no longer accepting submissions.";
+    }
+    if (entry.useCustomErrorMessage && !entry.errorPath && entry.errorMessage) return String(entry.errorMessage);
+  }
+  return null;
+}
+
+/** Wix's own "this is required" copy per field kind (form-fields messages_en.json). */
+export function requiredMessage(f: FormFieldDto): string {
+  switch (f.identifier) {
+    case "CONTACTS_FIRST_NAME": case "FULL_NAME_FIRST_NAME": return "Enter a first name.";
+    case "CONTACTS_LAST_NAME": case "FULL_NAME_LAST_NAME": return "Enter a last name.";
+    case "CONTACTS_COMPANY": return "Enter a company name.";
+    case "CONTACTS_POSITION": return "Enter a position or job title.";
+    case "CONTACTS_ADDRESS": return "Enter an address.";
+    case "VAT_ID": case "CONTACTS_TAX_ID": return "Enter a VAT ID number.";
+  }
+  switch (f.control) {
+    case "email": return "Enter an email address like example@mysite.com.";
+    case "phone": return "Enter a phone number.";
+    case "url": return "Enter a web URL like https://www.example.com.";
+    case "number": return "Enter a number.";
+    case "rating": return "Choose a star rating.";
+    case "date": case "datetime": return "Choose a date.";
+    case "time": return "Enter a time.";
+    case "select": case "radio": case "checkboxGroup": case "tags": return "Choose an option.";
+    case "checkbox": return "Check the box to continue.";
+    case "file": return "Upload a file.";
+    case "signature": return "Sign in the box above.";
+    case "address": return "Enter an address.";
+    default: return "Enter an answer.";
+  }
+}
+
+/** Wix's copy for an address subfield left empty (mla-* messages). */
+export function addressPartMessage(sub: string): string {
+  switch (sub) {
+    case "country": return "Choose a country/region.";
+    case "addressLine": return "Enter an address.";
+    case "addressLine2": return "Enter a second address line (e.g., apartment, suite, floor).";
+    case "city": return "Enter a city.";
+    case "postalCode": return "Enter a zip/postal code.";
+    case "subdivision": return "Choose an option.";
+    case "streetName": return "Enter a street name.";
+    case "streetNumber": return "Enter a house number.";
+    default: return "This field is required.";
+  }
+}
+
+const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+
+/**
+ * errorType → visitor-facing copy in Wix's own wording (messages_en.json), written from the
+ * field's schema. The same table the client check uses, so a server rejection reads like the
+ * inline one.
+ */
+export function messageFor(errorType: string, f: FormFieldDto, path: string = f.target): string {
+  const v = f.validation;
+  const sub = path.includes("/") ? path.split("/")[1] : undefined;
+  switch (errorType) {
+    case "REQUIRED_VALUE_ERROR": return sub ? addressPartMessage(sub) : requiredMessage(f);
+    case "MIN_LENGTH_ERROR": case "MAX_LENGTH_ERROR": case "CHARACTER_LENGTH_RANGE_ERROR": case "EXACT_CHARACTER_LENGTH_ERROR":
+      return lengthMessage(v.minLength, v.maxLength);
+    case "MIN_VALUE_ERROR": case "MAX_VALUE_ERROR": case "VALUE_RANGE_ERROR":
+      if (f.identifier === "CONTACTS_BIRTHDATE") return "Enter a date from January 1, 1900 to today.";
+      if (f.control === "date" || f.control === "datetime" || f.control === "time") return dateRangeMessage(v.minDate, v.maxDate);
+      return rangeMessage(v.minimum, v.maximum);
+    case "MULTIPLE_OF_VALUE_ERROR": case "DECIMAL_POINT_ERROR": return multipleOfMessage(v.multipleOf);
+    case "MIN_ITEMS_ERROR": case "MAX_ITEMS_ERROR": case "EXACT_ITEMS_NUMBER_ERROR": return itemsMessage(v.minItems, v.maxItems);
+    case "PATTERN_ERROR": case "INVALID_VALUE_FOR_PATTERN_ERROR":
+      return v.patternMessage ?? (sub === "postalCode" ? "Enter a valid zip/postal code." : "Enter a valid answer.");
+    case "NOT_ALLOWED_VALUE_ERROR":
+      if (f.control === "checkbox") return "Check the box to continue.";
+      if (f.control === "phone") return "Phone numbers with this country code aren’t accepted.";
+      return "The chosen value is not allowed.";
+    case "INVALID_PHONE_COUNTRY_CODE_ERROR": return "Enter a valid country code.";
+    case "INCOMPLETE_DATE_ERROR": return "Enter a month, day and year.";
+    case "FORMAT_ERROR":
+      return f.control === "email" || v.format === "EMAIL" ? "Enter an email address like example@mysite.com."
+        : f.control === "phone" || v.format === "PHONE" ? "Enter a valid phone number."
+        : f.control === "url" || v.format === "URL" ? "Enter a web URL like https://www.example.com."
+        : f.control === "time" ? "Enter hours and minutes."
+        : f.control === "date" || f.control === "datetime" ? "Enter a month, day and year."
+        : "Enter a valid answer.";
+    case "TYPE_ERROR": return "Enter a valid answer.";
+    // A key the server does not know for this field — for an address, a subfield the chosen
+    // country's template lacks. The store sends only the country's own parts, so this is rare.
+    case "UNKNOWN_VALUE_ERROR": return sub ? `${humanizeSub(sub)} isn't part of an address in this country.` : "This answer isn't accepted here.";
+    // The enum grows; an unmapped type degrades to safe copy rather than showing nothing.
+    default: return `Please check ${f.label}.`;
+  }
+}
+
+export function lengthMessage(min?: number, max?: number): string {
+  if (min && max) return min === max ? `Enter exactly ${plural(min, "character", "characters")}.` : `Enter between ${min} and ${max} characters.`;
+  if (min) return `Enter at least ${plural(min, "character", "characters")}.`;
+  return `Enter less than ${plural(max ?? 0, "character", "characters")}.`;
+}
+
+export function rangeMessage(min?: number, max?: number): string {
+  if (min != null && max != null) return `Enter a number from ${min} to ${max}.`;
+  if (min != null) return `Enter a number that is ${min} or more.`;
+  return `Enter a number that is ${max} or less.`;
+}
+
+export function dateRangeMessage(min?: string, max?: string): string {
+  const show = (s: string) => s.replace("T", " ");
+  if (min && max) return `Choose a date from ${show(min)} to ${show(max)}.`;
+  if (min) return `Choose a date from ${show(min)} on.`;
+  return `Choose a date up to ${show(max ?? "")}.`;
+}
+
+export function multipleOfMessage(step?: number): string {
+  const decimals = String(step ?? 1).split(".")[1]?.length ?? 0;
+  return decimals ? `Add ${decimals} number(s) after the decimal point.` : step && step !== 1 ? `Choose a multiple of ${step}.` : "Enter a whole number.";
+}
+
+export function itemsMessage(min?: number, max?: number): string {
+  if (min && max && min === max) return `Choose ${plural(min, "option", "options")}.`;
+  if (min && max) return `Choose between ${min} and ${max} options.`;
+  if (min) return `Choose at least ${plural(min, "option", "options")}.`;
+  return `Choose up to ${plural(max ?? 0, "option", "options")}.`;
+}

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

@@ -0,0 +1,95 @@
+// Wix Forms submissions (@wix/forms `submissions`) over the SDK — get an upload URL, create the
+// submission, start the checkout a paid form needs. The rules (value shapes, accepted statuses,
+// violation mapping, the upload PUT, the redirect-session body) live in ./submissions-core (shared
+// with the REST twin in templates/forms/rest/); this file is the transport only. Copy as-is; extend
+// by adding functions.
+//
+// The visitor token creates the submission, despite the spec. `CreateSubmission` is listed under
+// the owner scope `SCOPE.DC-FORMS.MANAGE-SUBMISSIONS` and returns 200 on an anonymous visitor: Wix
+// grants implicit visitor access so a published site can submit its own forms. Reaching for a
+// backend here is the most common wrong turn on this vertical.
+//
+// SUBMISSIONS ARE WRITE-ONLY FROM A VISITOR. Reading them back genuinely requires the owner
+// scope and 403s. The resolved create IS the confirmation — show a thank-you; the entry appears
+// in the owner's dashboard. A site that must LIST what visitors submitted needs `cms` instead.
+//
+// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/create-submission.md
+// docs: https://dev.wix.com/docs/sdk/business-solutions/forms/submissions/get-media-upload-url.md
+// docs: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
+// docs: https://dev.wix.com/docs/api-reference/business-management/headless/redirects/create-redirect-session.md
+import { submissions as submissionsModule } from "@wix/forms";
+import { wixFetch, wixModule } from "../sdk";
+import type { Raw } from "./forms-core";
+import {
+  SUBMITTED_OK,
+  formLevelError,
+  normalizePhone,
+  normalizeUrl,
+  putUpload,
+  redirectSessionBody,
+  redirectSessionUrl,
+  submissionErrors,
+  toSubmission,
+  toSubmissionValues,
+  uploadFilesWith,
+  uploadMimeType,
+} from "./submissions-core";
+import type { FormFieldDto, FormValues, SubmissionDto, UploadedFile } from "./types";
+
+export { SUBMITTED_OK, formLevelError, normalizePhone, normalizeUrl, submissionErrors, toSubmissionValues };
+
+const submissions = wixModule(submissionsModule);
+
+/** Upload one File and return the value to submit for its field ({ fileId, displayName, fileType, url }). */
+export async function uploadFile(formId: string, file: File): Promise<UploadedFile> {
+  const mimeType = uploadMimeType(file);
+  const res = (await submissions.getMediaUploadUrl(formId, file.name, mimeType)) as Raw;
+  const uploadUrl: string | undefined = res?.uploadUrl ?? res?.url;
+  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. This is the write — and the only confirmation there is.
+ *
+ * Let a rejection throw. `submissionErrors` turns it into per-control messages and
+ * `formLevelError` into the form-level one; a `.catch` that swallows it costs the visitor the
+ * reason their form would not send.
+ */
+export async function createSubmission(
+  formId: string,
+  values: Record<string, unknown>,
+  { captchaToken }: CreateSubmissionOptions = {},
+): Promise<SubmissionDto> {
+  const created = (await submissions.createSubmission(
+    { formId, submissions: values },
+    captchaToken ? { captchaToken } : {},
+  )) as Raw;
+  return toSubmission(created);
+}
+
+/**
+ * The Wix-hosted checkout for a `PAYMENT_WAITING` submission — navigate the FULL document to the
+ * URL. Call from the browser: the return origin must be the site's real https origin
+ * (window.location.origin), never a server-derived request origin. Over wixFetch rather than the
+ * @wix/redirects module so this vertical adds no dependency.
+ */
+export async function checkoutUrl(checkoutId: string, origin: string = typeof window !== "undefined" ? window.location.origin : ""): Promise<string> {
+  const res = await wixFetch("/headless/v1/redirect-session", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(redirectSessionBody(checkoutId, origin)),
+  });
+  if (!res.ok) throw new Error(`forms: checkout could not start (${res.status}).`);
+  return redirectSessionUrl((await res.json()) as Raw);
+}