@wix/agent-skills 1.35.1 → 1.36.1

package/skills/wix-vibe-headless/references/forms/app/rest/wix-forms-submissions.js

@@ -1,238 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-import { normalizePhone } from "./wix-forms.js";
-import { targetOf, inputTypeOf, isMulti, isFile, isAddress, addressPartsOf, validationOf } from "@/lib/wix-form-schema-utils";
-
-/**
- * Wix Forms — the SUBMISSION: turn the form's values into the shape the API expects, create the
- * submission, and map the server's per-field violations back onto controls. Same plain anonymous
- * visitor token as the schema read in `wix-forms.js` — no SDK, no backend, no elevate.
- *
- * ⚠️ CRITICAL — the visitor token creates the submission, despite the spec. `CreateSubmission` is
- * listed under the owner scope `SCOPE.DC-FORMS.MANAGE-SUBMISSIONS`, and in practice returns 200 on
- * an anonymous visitor token: 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 THE BROWSER. Reading them back
- * (`querySubmissionsByNamespace`, `getSubmission`, `countSubmission`) genuinely requires the owner
- * scope `WIX_FORMS.SUBMISSION_READ_ANY` and 403s for a visitor. The resolved `createSubmission`
- * promise IS the success signal — show a thank-you; the submission appears in the owner's dashboard.
- * A site that must LIST what visitors submitted needs the `cms` vertical instead.
- *
- * Submit values: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md
- * Upload URL:    https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md
- * Create:        https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md
- */
-
-/**
- * Submission statuses that mean the submission EXISTS — show the thank-you. `CONFIRMED` is recorded,
- * `PENDING` is created but not recorded yet, and `PAYMENT_WAITING` is created on a form that also
- * collects payment. See `createSubmission` for why this is an allowlist rather than a catch-all.
- */
-export const SUBMITTED_OK = new Set(["CONFIRMED", "PENDING", "PAYMENT_WAITING"]);
-
-/**
- * Get a signed URL to upload one file for a form submission — the FORMS-scoped wrapper around the
- * Media Manager's upload URL, so a visitor can attach a file without the Manage-Media credential a
- * direct `site-media` call would demand (that one 403s for a visitor; this one is listed under the
- * same `SCOPE.FORMS.VIEW-FORM` as the schema read).
- * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/get-media-upload-url.md
- *
- * @param {string} formId
- * @param {string} filename  Including the extension — Wix reads the type from it.
- * @param {string} mimeType  e.g. "image/png". A browser gives you `file.type`.
- * @returns {Promise<string>}  The signed upload URL.
- */
-export async function getMediaUploadUrl(formId, filename, mimeType) {
-  const res = await wixApiRequest("/form-submission-service/v4/submissions/media-upload-url", {
-    method: "POST",
-    body: { formId, filename, mimeType },
-  });
-  if (!res?.uploadUrl) throw new Error(`Could not get an upload URL for "${filename}".`);
-  return res.uploadUrl;
-}
-
-/**
- * Upload one `File` and return the value to submit for its field.
- *
- * ⚠️ The submission value IS the generated `uploadUrl` — not the CDN URL the upload responds with,
- * and not a file id. That's Wix's own contract (see the "media file" example on Create Submission
- * and the "Submit a form with media" sample flow): get the URL, PUT the bytes to it, then send that
- * same URL as the field's value.
- *
- * The PUT goes straight to Wix's upload host on a signed URL, so it uses plain `fetch` — NOT
- * `wixApiRequest`: adding the visitor's Authorization header to a pre-signed URL is what turns a
- * working upload into a 400.
- *
- * @param {string} formId
- * @param {File} file  From an `<input type="file">`.
- * @returns {Promise<string>}  The value to put in the submission for this field.
- */
-export async function uploadSubmissionFile(formId, file) {
-  // A browser leaves `type` empty for extensions it doesn't recognize; the generic type keeps the
-  // upload-URL call valid (Media Manager rejects a mime type that contradicts the extension).
-  const mimeType = file.type || "application/octet-stream";
-  const uploadUrl = await getMediaUploadUrl(formId, file.name, mimeType);
-  const res = await fetch(`${uploadUrl}?filename=${encodeURIComponent(file.name)}`, {
-    method: "PUT",
-    headers: { "Content-Type": mimeType },
-    body: file,
-  });
-  if (!res.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(`Could not upload "${file.name}" (${res.status}). Check its size and file type.`);
-  }
-  return uploadUrl;
-}
-
-/**
- * Upload every `File` sitting in the form's state and return a copy of `values` with each file
- * field replaced by its submitted value(s). Run this BEFORE `toSubmissionValues` — a `File` object
- * is not something the submission API accepts.
- *
- * @param {string} formId
- * @param {object[]} fields  The render model.
- * @param {Record<string, unknown>} values
- * @returns {Promise<Record<string, unknown>>}
- */
-export async function uploadFormFiles(formId, fields, values) {
-  const next = { ...values };
-  for (const field of fields) {
-    if (!isFile(field)) continue;
-    const target = targetOf(field);
-    const picked = [].concat(values[target] ?? []).filter((f) => f instanceof File);
-    const uploaded = [];
-    // Sequential on purpose: a visitor's uplink is the bottleneck, and a failed file should stop
-    // the submit rather than race three more uploads it will throw away.
-    for (const file of picked) uploaded.push(await uploadSubmissionFile(formId, file));
-    next[target] = uploaded;
-  }
-  return next;
-}
-
-/**
- * Turn the form's state into the `submissions` map `createSubmission` expects — keyed by each
- * field's `target`, which is 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 SCHEMA, not the state object: a stray key in `values` can never reach the API, and a
- * field the owner added shows up the moment the schema does.
- *
- * The three value shapes and their per-`inputType` rules
- * (https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/about-submission-values.md):
- *   • flat value  — text / dropdown / radio / date / time. NUMBER submits a number and PHONE the
- *                   normalized E.164 string, never the raw control text.
- *   • ARRAY       — a multi-choice field, holding the checked option values.
- *   • OBJECT      — an ADDRESS, keyed by subfield (`city`, `country`, …), which is also the shape
- *                   behind the server's nested `address/city` error paths.
- * An empty optional field is OMITTED rather than sent as "" — the server validates what it's given.
- *
- * @param {object[]} fields  The render model, from `hooks/useWixForm.js`.
- * @param {Record<string, unknown>} values  The form's state, keyed by `target`.
- * @returns {Record<string, unknown>}
- */
-export function toSubmissionValues(fields, values) {
-  const filled = (v) => v !== undefined && v !== null && String(v).trim() !== "";
-  const out = {};
-  for (const field of fields) {
-    const target = targetOf(field);
-    const raw = values?.[target];
-
-    if (isAddress(field)) {
-      const parts = {};
-      for (const { sub } of addressPartsOf(field)) {
-        if (filled(raw?.[sub])) parts[sub] = String(raw[sub]).trim();
-      }
-      if (Object.keys(parts).length) out[target] = parts;
-      continue;
-    }
-
-    if (isMulti(field)) {
-      const picked = (Array.isArray(raw) ? raw : []).filter(filled);
-      if (picked.length) out[target] = picked;
-      continue;
-    }
-
-    // A file field carries what `uploadFormFiles` produced — the upload URL(s). One file submits the
-    // bare string (the shape Wix's own example uses); several submit an array. A stray `File` that
-    // never went through the upload is dropped rather than sent, since it would 400 the whole form.
-    if (isFile(field)) {
-      const urls = [].concat(raw ?? []).filter((v) => typeof v === "string" && v);
-      if (urls.length) out[target] = urls.length === 1 ? urls[0] : urls;
-      continue;
-    }
-
-    if (!filled(raw)) continue;
-    const value = typeof raw === "string" ? raw.trim() : raw;
-    out[target] =
-      inputTypeOf(field) === "NUMBER" ? Number(value) :
-      validationOf(field).format === "PHONE" ? normalizePhone(value) : value;
-  }
-  return out;
-}
-
-/**
- * Create a submission. This is the write — and the ONLY confirmation you get, since a visitor can't
- * read submissions back.
- * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md
- *
- * ⚠️ EVERY status this resolves on is a created submission — `CONFIRMED` (recorded), `PENDING`
- * (created, not recorded yet) and `PAYMENT_WAITING` (created on a form that also collects payment).
- * Show the thank-you for all three. Treating one as a failure invites the visitor to submit again,
- * which costs the owner duplicate entries for a submission that already exists.
- *
- * `PAYMENT_WAITING` still leaves the visitor a payment step, but the SUBMIT succeeded — surface the
- * payment inside the success state, never as a failed submission. A form only reaches this status if
- * the UI rendered a PAYMENT field, so read the returned `status` when you build one.
- * Success stays an ALLOWLIST rather than a catch-all, so a status added to the enum later can't
- * silently render a thank-you for something that isn't a submission.
- *
- * ⚠️ REST returns `submission.id` — the SDK's normalized `_id` does not exist here.
- *
- * @param {string} formId
- * @param {Record<string, unknown>} values  Map of `target` → value, from `toSubmissionValues`.
- * @returns {Promise<{ id: string, status: string }>}
- */
-export async function createSubmission(formId, values) {
-  const res = await wixApiRequest("/form-submission-service/v4/submissions", {
-    method: "POST",
-    body: { submission: { formId, submissions: values } },
-  });
-  const submission = res?.submission;
-  if (!submission?.id) throw new Error("Submission failed (no submission returned).");
-  if (!SUBMITTED_OK.has(submission.status)) {
-    throw new Error(
-      `Submission status is "${submission.status}" — not one of the statuses that mean the ` +
-        `submission was created (${[...SUBMITTED_OK].join(", ")}), so don't show a success state. ` +
-        `Check the Submission status docs before adding it to SUBMITTED_OK.`,
-    );
-  }
-  return { id: submission.id, status: submission.status };
-}
-
-/**
- * Pull the per-field violations out of a failed `createSubmission`.
- *
- * The documented entries (`errorPath`, `errorType`, `errorMessage`, `params`) arrive under
- * `details.validationError.fieldViolations[]`, each with its own nested `data.errors[]` array —
- * two levels deeper than the docs' shape. This flattens that; turning a violation into words a
- * visitor should read is the UI's job (`mapSubmissionErrors` in `hooks/useWixForm.js`).
- *
- * `errorPath` is the field's `target`, or a nested path like `address/subdivision` or
- * `attachments/0/fileId` — which is exactly how the controls are named, so it maps straight across.
- *
- * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/introduction#validation-errors
- *
- * @param {Error & { body?: object }} err  From `createSubmission`; the REST body is on `err.body`.
- * @returns {{ errorPath: string, errorType: string, errorMessage?: string }[]}  Empty when the
- *   failure wasn't a validation error at all (a network drop, a 500).
- */
-export function submissionViolations(err) {
-  const violations =
-    err?.body?.details?.validationError?.fieldViolations ??
-    err?.details?.validationError?.fieldViolations ??
-    [];
-  return violations
-    .flatMap((violation) => violation.data?.errors ?? [violation])
-    .filter((entry) => entry?.errorPath);
-}

package/skills/wix-vibe-headless/references/forms/app/rest/wix-forms.js

@@ -1,108 +0,0 @@
-import { wixApiRequest } from "./wix-client.js";
-
-/**
- * Wix Forms — the form SCHEMA: read a form, on the plain anonymous visitor token this skill already
- * mints. No SDK, no backend, no elevate. **The write path lives next door in
- * `wix-forms-submissions.js`.**
- *
- * WHY THIS VERTICAL EXISTS: a visitor-fillable form is Wix Forms, not a CMS collection. The owner
- * edits fields in the Wix dashboard, submissions land in their Forms inbox with spam protection
- * and notifications, and the frontend re-renders from the live schema with no code change.
- * Use `cms` only for content the app itself stores and READS BACK (listings, galleries, "my items").
- *
- * ⚠️ CRITICAL — the visitor token is enough, and the docs say otherwise. The API spec lists every
- * schema read (`GetForm`/`ListForms`) under the owner scope `SCOPE.FORMS.VIEW-FORM`. In practice
- * they return 200 on an anonymous visitor token — Wix grants implicit visitor access so a published
- * site can render its own forms. Trust the live 200, not the permission table. Do NOT add a backend,
- * a connector token, or any elevated credential to make a form work.
- *
- * READING the schema is `lib/wix-form-schema-utils.js` (plain accessors over the raw fields) and checking
- * values against it is `hooks/useWixForm.js`. This file stays the transport, plus the phone helpers
- * both sides need — `normalizePhone` for the value that goes on the wire, `phoneExample` for the one
- * shown to a visitor.
- *
- * Form object: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object.md
- * Form fields: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
- */
-
-/** The Wix Forms app namespace. Every form this vertical touches lives here. */
-export const FORMS_NAMESPACE = "wix.form_app.form";
-
-/**
- * Read one form schema by id. Returns the `Form` directly (the REST envelope's `form` is unwrapped
- * for you), or throws — a 404 `FORM_NOT_FOUND` means the id is wrong or the form was deleted.
- * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form.md
- *
- * @param {string} formId  The form's GUID (from the seed's `seeded.forms[].formId`).
- * @returns {Promise<object>}  The Form: `{ id, formFields[], steps[], … }`.
- */
-export async function getForm(formId) {
-  const res = await wixApiRequest(`/form-schema-service/v4/forms/${encodeURIComponent(formId)}`, {
-    method: "GET",
-  });
-  const form = res?.form;
-  if (!form) throw new Error(`Form "${formId}" not found.`);
-  return form;
-}
-
-/**
- * List form schemas in the namespace. Use ONE call for several forms on a page rather than one
- * `getForm` each; pass no `formIds` to discover every form the site has.
- * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms.md
- *
- * ⚠️ Returns only ENABLED forms by default — a form the owner disabled silently vanishes from a
- * discovery listing rather than erroring. That's usually right for a public site.
- *
- * @param {{ formIds?: string[], namespace?: string }} [options]  `formIds` takes up to 100 ids.
- * @returns {Promise<object[]>}  Array of Form objects (the envelope's `forms`, unwrapped).
- */
-export async function listForms({ formIds, namespace = FORMS_NAMESPACE } = {}) {
-  const res = await wixApiRequest("/form-schema-service/v4/forms", {
-    method: "GET",
-    query: { namespace, ...(formIds?.length ? { formIds } : {}) },
-  });
-  return res?.forms ?? [];
-}
-
-/**
- * Phone examples shown to visitors (placeholder + error copy). Every value is a regulator-RESERVED
- * fictional number for that country, so no real subscriber is ever printed.
- *
- * ⚠️ Never hardcode a user-visible example to one locale — a `+44`- or US-shaped example on a site
- * in another market is a locale bug. Add a market only after verifying its reserved range in the
- * national numbering plan; never invent a number. Never SUBMIT one either: a reserved number is
- * rejected (see `validateField` in `hooks/useWixForm.js`), so these are display-only.
- */
-export const PHONE_EXAMPLE = {
-  US: "+1 201 555 0123", CA: "+1 416 555 0123", // NANP 555-0100–0199 reserved for fiction
-  GB: "+44 7700 900123",                        // Ofcom drama range 07700 900xxx
-  IE: "+353 20 910 0001",                       // ComReg reserved 020 91x xxxx
-  AU: "+61 491 570 006",                        // ACMA reserved mobile range
-  FR: "+33 1 99 00 00 01",                      // ARCEP Île-de-France 01 99 00 xx xx reserved
-  DE: "+49 30 23125 000",                       // BNetzA Berlin 030 23125 xxx reserved
-  SE: "+46 70 174 06 05",                       // PTS reserved 070 174 06xx
-  KR: "+82 2 540 0000",                         // Seoul 02-540-xxxx reserved
-};
-
-/**
- * The site's country (ISO-3166 alpha-2), used for any locale-derived example. Set it once from the
- * business you're building for — the browser's own locale is the VISITOR's, not the site's.
- * @type {string}
- */
-export let SITE_COUNTRY = "US";
-/** Set the site's country once at app start, e.g. `setSiteCountry("GB")`. */
-export function setSiteCountry(code) {
-  if (code) SITE_COUNTRY = code.toUpperCase();
-}
-
-/**
- * The example phone number for a country (ISO-3166 alpha-2), falling back to the site's and then to
- * the US. Pass a PHONE field's own country when it has one — `phoneCountryOf(field)` in
- * `lib/wix-form-schema-utils.js` reads it — so the example shown is one that field would accept.
- */
-export function phoneExample(country) {
-  return PHONE_EXAMPLE[country ?? SITE_COUNTRY] ?? PHONE_EXAMPLE[SITE_COUNTRY] ?? PHONE_EXAMPLE.US;
-}
-
-/** Strip visitor-added formatting from a phone number — submit this, not the raw value. */
-export const normalizePhone = (v) => String(v ?? "").replace(/[\s()\-.]/g, "");