Subchapter 41.133

Contact Extended Fields

Multilingual Restore

Verify Stores

Also bundled

App Page Routing Capabilities

162 more in the appendix

Contact Extended Fields

Number

41.133

Position

133 of 174

Type

JavaScript

Size

10 KB

Lines

194

Nearby

Source

lib/contact-extended-fields.js

JavaScript194 lines10 KB

1'use strict';
2
3const crypto = require('node:crypto');
4
5// The LEGACY Contacts V4 custom-field path, and only that path. A migration reaches it
6// only by routing a mapping explicitly to `contactWriteSurface: "contacts-v4"`; the default V5
7// contact goes through the Data Extension Schema helper (FQDN wix.contacts.*.contact) instead.
8// The two are never both attempted for one field, and a failure on one never falls back to the
9// other: their values live in different places (`info.extendedFields` vs
10// `extendedFields.namespaces`) and pair with different contact writers.
11//
12// API facts this relies on (docs re-read 2026-09-29):

contact-extended-fields.js on GitHub

// * Find Or Create Extended Field is POST /contacts/v4/extended-fields {displayName, dataType}.

// It matches an existing field BY DISPLAY NAME and returns `{ field, newField }`; the key is

// generated by Wix, so setup must persist the returned key rather than derive one.

// * Get Extended Field is GET /contacts/v4/extended-fields/{key} -- the read-back.

// * Keys cannot be changed once created; deleting a field removes its values from every contact.

// * Created fields land in the `custom` namespace. Documented types: Text, Number, Date, URL.

//

// This phase admits TEXT only, for the same reason the DES helper admits `string` only: the other

// types have not been verified end to end, and a guessed type is how an unsupported one reaches a

// live setup call.

const WIXAPIS = 'https://www.wixapis.com';

const EXTENDED_FIELDS_URL = `${WIXAPIS}/contacts/v4/extended-fields`;

const SCHEMA_KIND = 'crm-contact-extended-field';

const CONTACT_WRITE_SURFACE = 'contacts-v4';

const EXPECTED_NAMESPACE = 'custom';

const VERIFIED_CONTACT_DATA_TYPES = new Set(['TEXT']);

const DOCUMENTED_CONTACT_DATA_TYPES = new Set(['TEXT', 'NUMBER', 'DATE', 'URL']);

function fail(errors, code, detail) {

errors.push({ code, detail });

return errors;

}

function validateContactExtendedFieldRequirement(requirement) {

const errors = [];

if (!requirement || requirement.kind !== 'extendedFieldSchema') {

return { valid: false, errors: fail([], 'not-an-extended-field-requirement', 'requirement.kind must be "extendedFieldSchema"') };

}

if (requirement.schemaKind !== SCHEMA_KIND) {

fail(errors, 'unsupported-schema-kind', `this helper implements ${SCHEMA_KIND} only, not "${requirement.schemaKind}"`);

}

if (requirement.contactWriteSurface !== CONTACT_WRITE_SURFACE) {

// V4 is opt-in. Without the explicit surface this is a V5 requirement in the wrong shape.

fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} requires contactWriteSurface "${CONTACT_WRITE_SURFACE}", not "${requirement.contactWriteSurface}"`);

}

if (requirement.targetRef !== undefined && requirement.targetRef !== 'crm/contact') {

fail(errors, 'target-ref-mismatch', `a ${SCHEMA_KIND} requirement targets crm/contact, not "${requirement.targetRef}"`);

}

if (requirement.fqdn || requirement.namespace) {

// The DES fields on a V4 requirement mean someone mixed the two surfaces.

fail(errors, 'contact-surface-mismatch', `${SCHEMA_KIND} does not take fqdn/namespace; those belong to the contacts-v5 Data Extension Schema path`);

}

if (!Array.isArray(requirement.fields) || requirement.fields.length === 0) {

fail(errors, 'no-fields-declared', 'a requirement with no fields provisions nothing');

return { valid: false, errors };

}

const seen = new Set();

for (const field of requirement.fields) {

if (!field || typeof field !== 'object') {

fail(errors, 'field-not-an-object', 'a field intent must be an object');

continue;

}

if (!field.displayName || typeof field.displayName !== 'string' || !field.displayName.trim()) {

fail(errors, 'missing-display-name', 'a contacts-v4 field needs a displayName; Find Or Create matches by it');

} else {

// Find Or Create matches by display name, so two fields with one name would collapse into

// one key and one field's values would overwrite the other's.

const normalized = field.displayName.trim().toLowerCase();

if (seen.has(normalized)) fail(errors, 'duplicate-display-name', `displayName "${field.displayName}" is declared twice`);

seen.add(normalized);

}

if (!field.dataType) {

fail(errors, 'missing-data-type', `field "${field.displayName}" has no dataType`);

} else if (!DOCUMENTED_CONTACT_DATA_TYPES.has(field.dataType)) {

fail(errors, 'unsupported-contact-data-type', `dataType "${field.dataType}" is not a Wix contact field type`);

} else if (!VERIFIED_CONTACT_DATA_TYPES.has(field.dataType)) {

fail(errors, 'unverified-contact-data-type', `dataType "${field.dataType}" is not verified for this phase; only ${[...VERIFIED_CONTACT_DATA_TYPES].join(', ')} is`);

}

if (field.expectedNamespace !== undefined && field.expectedNamespace !== EXPECTED_NAMESPACE) {

fail(errors, 'unexpected-contact-namespace', `created contact fields land in "${EXPECTED_NAMESPACE}", not "${field.expectedNamespace}"`);

}

if (field.writePath && !/^info\.extendedFields\./.test(field.writePath)) {

fail(errors, 'write-path-mismatch', `a contacts-v4 value lands under info.extendedFields, not "${field.writePath}"`);

}

if (field.writePathTemplate !== undefined && field.writePathTemplate !== 'info.extendedFields.<verifiedKey>') {

fail(errors, 'write-path-mismatch', `writePathTemplate must be "info.extendedFields.<verifiedKey>", not "${field.writePathTemplate}"`);

}

return { valid: errors.length === 0, errors };

}

function buildFindOrCreateContactExtendedFieldRequest({ displayName, dataType = 'TEXT' } = {}) {

if (!displayName) throw new Error('buildFindOrCreateContactExtendedFieldRequest: displayName is required');

return { method: 'POST', url: EXTENDED_FIELDS_URL, body: { displayName, dataType } };

}

function buildGetContactExtendedFieldRequest({ key } = {}) {

if (!key) throw new Error('buildGetContactExtendedFieldRequest: key is required');

return { method: 'GET', url: `${EXTENDED_FIELDS_URL}/${encodeURIComponent(key)}` };

}

// Find Or Create and Get both answer `{ field: {...} }`. Accept a bare field too.

function normalizeContactExtendedFieldResult(response) {

const field = response && (response.field || (response.key ? response : null));

if (!field) return null;

return {

key: field.key || null,

namespace: field.namespace || null,

dataType: field.dataType || null,

displayName: field.displayName || null,

newField: response && typeof response.newField === 'boolean' ? response.newField : null,

};

}

// The identity a later run must see again. A receipt records it so a key that changed between

// runs is caught instead of silently splitting a field's values across two keys.

function contactFieldIdentity(field) {

return String(field.displayName || '').trim().toLowerCase();

}

// Checks one Find Or Create answer (or its read-back) against the intent and any key recorded by

// an earlier run. Returns null when it matches.

function describeContactFieldMismatch(intent, normalized, { priorKey = null } = {}) {

if (!normalized || !normalized.key) return 'the field was not returned';

const differences = [];

// Required, not merely "not wrong": a response that omits the namespace has not shown the key

// lives where the writer will put values, so it cannot pass verification.

if (normalized.namespace !== EXPECTED_NAMESPACE) {

differences.push(`namespace: expected "${EXPECTED_NAMESPACE}", got ${normalized.namespace ? `"${normalized.namespace}"` : 'none'}`);

}

if (normalized.dataType !== intent.dataType) {

// Find Or Create matched an existing field by name; it will not retype it for us.

differences.push(`dataType: expected ${intent.dataType}, got ${normalized.dataType}`);

}

if (normalized.displayName && contactFieldIdentity(normalized) !== contactFieldIdentity(intent)) {

differences.push(`displayName: expected "${intent.displayName}", got "${normalized.displayName}"`);

}

if (priorKey && normalized.key !== priorKey) {

differences.push(`key: an earlier setup verified "${priorKey}" but Wix now returns "${normalized.key}"; keys cannot change`);

}

return differences.length > 0 ? differences.join('; ') : null;

}

function contactFieldWritePath(key) {

return `info.extendedFields.${key}`;

}

// Same stamp idea as the DES helper, hashed over what a V4 consumer depends on.

function contactExtendedFieldContractVersion(requirement) {

if (!requirement || !Array.isArray(requirement.fields)) return null;

const material = [

SCHEMA_KIND,

requirement.contactWriteSurface || '',

...requirement.fields.map((field) => [contactFieldIdentity(field), field.dataType || ''].join(':')).sort(),

].join('|');

return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);

}

// Keys an earlier receipt verified, by display-name identity, so a re-run can enforce that they

// did not change.

function priorContactFieldKeys(setupVerification) {

const entries = !setupVerification ? []

: Array.isArray(setupVerification.verifications) ? setupVerification.verifications

: Array.isArray(setupVerification) ? setupVerification : [setupVerification];

const keys = new Map();

for (const entry of entries) {

if (!entry || entry.schemaKind !== SCHEMA_KIND) continue;

for (const verified of entry.verified || []) {

if (verified && verified.displayName && verified.key) keys.set(contactFieldIdentity(verified), verified.key);

}

return keys;

}

module.exports = {

EXTENDED_FIELDS_URL,

SCHEMA_KIND,

CONTACT_WRITE_SURFACE,

EXPECTED_NAMESPACE,

VERIFIED_CONTACT_DATA_TYPES,

DOCUMENTED_CONTACT_DATA_TYPES,

validateContactExtendedFieldRequirement,

buildFindOrCreateContactExtendedFieldRequest,

buildGetContactExtendedFieldRequest,

normalizeContactExtendedFieldResult,

describeContactFieldMismatch,

contactFieldIdentity,

contactFieldWritePath,

contactExtendedFieldContractVersion,

priorContactFieldKeys,

};