Setting the file. One moment.
Wix Forms · Wix Vibe Headless · wix/skills · Skills Docs
ContentsBack to the top of the page 22.10
Post Detail
references/forms/app/rest/ wix-forms.js
JavaScript · 108 lines · 6 KB
14 * schema read (`GetForm`/`ListForms`) under the owner scope `SCOPE.FORMS.VIEW-FORM`. In practice
15 * they return 200 on an anonymous visitor token — Wix grants implicit visitor access so a published
16 * site can render its own forms. Trust the live 200, not the permission table. Do NOT add a backend,
17 * a connector token, or any elevated credential to make a form work.
18 *
19 * READING the schema is `lib/wix-form-schema-utils.js` (plain accessors over the raw fields) and checking
20 * values against it is `hooks/useWixForm.js`. This file stays the transport, plus the phone helpers
21 * both sides need — `normalizePhone` for the value that goes on the wire, `phoneExample` for the one
22 * shown to a visitor.
23 *
24 * Form object: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/form-object.md
25 * Form fields: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/about-form-fields.md
26 */
27
28 /** The Wix Forms app namespace. Every form this vertical touches lives here. */
29 export const FORMS_NAMESPACE = "wix.form_app.form" ;
30
31 /**
32 * Read one form schema by id. Returns the `Form` directly (the REST envelope's `form` is unwrapped
33 * for you), or throws — a 404 `FORM_NOT_FOUND` means the id is wrong or the form was deleted.
34 * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/get-form.md
35 *
36 * @param {string} formId The form's GUID (from the seed's `seeded.forms[].formId`).
37 * @returns {Promise<object>} The Form: `{ id, formFields[], steps[], … }`.
38 */
39 export async function getForm ( formId ) {
40 const res = await wixApiRequest ( `/form-schema-service/v4/forms/${ encodeURIComponent ( formId ) }` , {
41 method: "GET" ,
42 });
43 const form = res?.form;
44 if ( ! form) throw new Error ( `Form "${ formId }" not found.` );
45 return form;
46 }
47
48 /**
49 * List form schemas in the namespace. Use ONE call for several forms on a page rather than one
50 * `getForm` each; pass no `formIds` to discover every form the site has.
51 * Reference: https://dev.wix.com/docs/api-reference/crm/forms/form-schemas/list-forms.md
52 *
53 * ⚠️ Returns only ENABLED forms by default — a form the owner disabled silently vanishes from a
54 * discovery listing rather than erroring. That's usually right for a public site.
55 *
56 * @param {{ formIds?: string[], namespace?: string }} [options] `formIds` takes up to 100 ids.
57 * @returns {Promise<object[]>} Array of Form objects (the envelope's `forms`, unwrapped).
58 */
59 export async function listForms ({ formIds , namespace = FORMS_NAMESPACE } = {}) {
60 const res = await wixApiRequest ( "/form-schema-service/v4/forms" , {
61 method: "GET" ,
62 query: { namespace, ... (formIds?. length ? { formIds } : {}) },
63 });
64 return res?.forms ?? [];
65 }
66
67 /**
68 * Phone examples shown to visitors (placeholder + error copy). Every value is a regulator-RESERVED
69 * fictional number for that country, so no real subscriber is ever printed.
70 *
71 * ⚠️ Never hardcode a user-visible example to one locale — a `+44`- or US-shaped example on a site
72 * in another market is a locale bug. Add a market only after verifying its reserved range in the
73 * national numbering plan; never invent a number. Never SUBMIT one either: a reserved number is
74 * rejected (see `validateField` in `hooks/useWixForm.js`), so these are display-only.
75 */
76 export const PHONE_EXAMPLE = {
77 US: "+1 201 555 0123" , CA: "+1 416 555 0123" , // NANP 555-0100–0199 reserved for fiction
78 GB: "+44 7700 900123" , // Ofcom drama range 07700 900xxx
79 IE: "+353 20 910 0001" , // ComReg reserved 020 91x xxxx
80 AU: "+61 491 570 006" , // ACMA reserved mobile range
81 FR: "+33 1 99 00 00 01" , // ARCEP Île-de-France 01 99 00 xx xx reserved
82 DE: "+49 30 23125 000" , // BNetzA Berlin 030 23125 xxx reserved
83 SE: "+46 70 174 06 05" , // PTS reserved 070 174 06xx
84 KR: "+82 2 540 0000" , // Seoul 02-540-xxxx reserved
85 };
86
87 /**
88 * The site's country (ISO-3166 alpha-2), used for any locale-derived example. Set it once from the
89 * business you're building for — the browser's own locale is the VISITOR's, not the site's.
90 * @type {string}
91 */
92 export let SITE_COUNTRY = "US" ;
93 /** Set the site's country once at app start, e.g. `setSiteCountry("GB")`. */
94 export function setSiteCountry ( code ) {
95 if (code) SITE_COUNTRY = code. toUpperCase ();
96 }
97
98 /**
99 * The example phone number for a country (ISO-3166 alpha-2), falling back to the site's and then to
100 * the US. Pass a PHONE field's own country when it has one — `phoneCountryOf(field)` in
101 * `lib/wix-form-schema-utils.js` reads it — so the example shown is one that field would accept.
102 */
103 export function phoneExample ( country ) {
104 return PHONE_EXAMPLE [country ?? SITE_COUNTRY ] ?? PHONE_EXAMPLE [ SITE_COUNTRY ] ?? PHONE_EXAMPLE . US ;
105 }
106
107 /** Strip visitor-added formatting from a phone number — submit this, not the raw value. */
108 export const normalizePhone = ( v ) => String (v ?? "" ). replace ( / [\s()\-.] / g , "" );