@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/console-widget-slot-context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ComponentType } from 'react';
+/**
+ * The console shell's widget zone renderer, for a zone a PLUGIN hosts.
+ *
+ * A zone the shell draws is a `PluginWidgetSlot` on a console page, and the
+ * slot is where the gates live: the plugins enabled for the workspace, the
+ * entitlement a widget needs and the permission its reader must hold. A
+ * plugin's own surface — a dialog, a hub card — cannot import that
+ * component, because an app is not a dependency a plugin may take, and a
+ * plugin that listed widgets itself would render them past every gate. So
+ * the shell hands its renderer down through this context, and a plugin that
+ * hosts a zone draws whatever the context gives it: the same component, the
+ * same gates, the zone name and the props the zone documents.
+ *
+ * Outside the console shell — a spec, a tenant page, a surface mounted by
+ * something else — the context holds `null`, and a hosted zone renders
+ * nothing. That is the right reading: with no shell there is no workspace to
+ * gate on.
+ *
+ * A client-only context like the others in `contexts.ts`: it calls
+ * `createContext` at module scope, so it is reachable from the full
+ * `@aglyn/aglyn` barrel and never from `@aglyn/aglyn/server` (AGL-405).
+ */
+/** Renders every permitted widget registered for `slot`, passing the rest as props. */
+export type ConsoleWidgetSlotRenderer = ComponentType<{
+    slot: string;
+} & Record<string, unknown>>;
+export declare const ConsoleWidgetSlotContext: import("react").Context<ConsoleWidgetSlotRenderer>;
+/** The shell's zone renderer, or `null` outside the console shell. */
+export declare function useConsoleWidgetSlot(): ConsoleWidgetSlotRenderer | null;

package/src/lib/app-utils/console-widget-slot-context.js

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createContext, useContext } from "react";
+export const ConsoleWidgetSlotContext = createContext(null);
+ConsoleWidgetSlotContext.displayName = 'ConsoleWidgetSlotContext';
+/** The shell's zone renderer, or `null` outside the console shell. */ export function useConsoleWidgetSlot() {
+    return useContext(ConsoleWidgetSlotContext);
+}
+
+//# sourceMappingURL=console-widget-slot-context.js.map

package/src/lib/app-utils/console-widget-slot-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/console-widget-slot-context.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createContext, useContext, type ComponentType } from 'react'\n\n/**\n * The console shell's widget zone renderer, for a zone a PLUGIN hosts.\n *\n * A zone the shell draws is a `PluginWidgetSlot` on a console page, and the\n * slot is where the gates live: the plugins enabled for the workspace, the\n * entitlement a widget needs and the permission its reader must hold. A\n * plugin's own surface — a dialog, a hub card — cannot import that\n * component, because an app is not a dependency a plugin may take, and a\n * plugin that listed widgets itself would render them past every gate. So\n * the shell hands its renderer down through this context, and a plugin that\n * hosts a zone draws whatever the context gives it: the same component, the\n * same gates, the zone name and the props the zone documents.\n *\n * Outside the console shell — a spec, a tenant page, a surface mounted by\n * something else — the context holds `null`, and a hosted zone renders\n * nothing. That is the right reading: with no shell there is no workspace to\n * gate on.\n *\n * A client-only context like the others in `contexts.ts`: it calls\n * `createContext` at module scope, so it is reachable from the full\n * `@aglyn/aglyn` barrel and never from `@aglyn/aglyn/server` (AGL-405).\n */\n\n/** Renders every permitted widget registered for `slot`, passing the rest as props. */\nexport type ConsoleWidgetSlotRenderer = ComponentType<{ slot: string } & Record<string, unknown>>\n\nexport const ConsoleWidgetSlotContext = createContext<ConsoleWidgetSlotRenderer | null>(null)\nConsoleWidgetSlotContext.displayName = 'ConsoleWidgetSlotContext'\n\n/** The shell's zone renderer, or `null` outside the console shell. */\nexport function useConsoleWidgetSlot(): ConsoleWidgetSlotRenderer | null {\n  return useContext(ConsoleWidgetSlotContext)\n}\n"],"names":["createContext","useContext","ConsoleWidgetSlotContext","displayName","useConsoleWidgetSlot"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,aAAa,EAAEC,UAAU,QAA4B,QAAO;AA4BrE,OAAO,MAAMC,2BAA2BF,cAAgD,MAAK;AAC7FE,yBAAyBC,WAAW,GAAG;AAEvC,oEAAoE,GACpE,OAAO,SAASC;IACd,OAAOH,WAAWC;AACpB"}

package/src/lib/app-utils/contact-custom-fields.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Custom contact fields (AGL-2601): what a VALUE under a definition may be,
+ * and the three doors a value comes in through.
+ *
+ * `crm.ts` declares the definition — `ContactFieldDefinition`, its key
+ * grammar and its collection. This module is everything that happens between
+ * a definition and a value: a form submission carrying a mapped field, an API
+ * body carrying a `custom` map, and a publish that must not lose the mapping
+ * an author drew. Each door coerces by the definition's TYPE, and the rule is
+ * one function so a number typed into a form and a number sent over the API
+ * cannot be stored as different things.
+ *
+ * Pure like the module it extends: no Firestore, no React. The bound on how
+ * many definitions one org keeps is stated here because every reader of the
+ * collection — the console hook, the submit route, the API — has to read it
+ * whole, and a reader without a limit is a reader whose cost is somebody
+ * else's decision.
+ */
+import { type ContactCustomValue, type ContactFieldDefinition, type ContactFieldType, type CrmFieldObject } from './crm';
+import type { FormFieldDecl } from './forms';
+/**
+ * How many field definitions one organization may hold, and therefore the
+ * `limit()` every reader of `orgs/{orgId}/contactFields` applies.
+ *
+ * The collection is read WHOLE — there is no index on it and the list is
+ * sorted by `order` in memory — so this is the ceiling on that read. A
+ * hundred is far past what a profile form can carry; an org that wants more
+ * has outgrown a per-contact map and needs a dataset.
+ */
+export declare const CONTACT_FIELDS_MAX_PER_ORG = 100;
+/** Every value type a definition may declare, in the order a picker lists them. */
+export declare const CONTACT_FIELD_TYPES: readonly ContactFieldType[];
+/** How a field type reads on screen — typed so a type cannot ship unlabeled. */
+export declare const CONTACT_FIELD_TYPE_LABELS: Record<ContactFieldType, string>;
+export declare function isContactFieldType(value: unknown): value is ContactFieldType;
+/**
+ * Definitions in the order a form, a column set and an export show them.
+ *
+ * `order` first, then the key, so two definitions that were given the same
+ * position — which a reorder in flight can produce for one write — still
+ * come out in one stable order on every surface rather than flickering.
+ */
+export declare function sortContactFieldDefinitions<T extends Pick<ContactFieldDefinition, 'order' | 'key'>>(definitions: readonly T[]): T[];
+/**
+ * The definitions that describe ONE object, in `order` (AGL-2661).
+ *
+ * Every reader of the collection gets it whole — it is one bounded read —
+ * and narrows here, through the one reader of `object`, so a definition
+ * written before the key existed lands on the contacts tab and nowhere
+ * else. Keys are unique within what this returns, not across it.
+ */
+export declare function fieldDefinitionsForObject<T extends Pick<ContactFieldDefinition, 'order' | 'key' | 'object'>>(definitions: readonly T[], object: CrmFieldObject): T[];
+/** The definitions a value may still be WRITTEN under — sorted, not retired. */
+export declare function activeContactFieldDefinitions<T extends Pick<ContactFieldDefinition, 'order' | 'key' | 'retiredAt'>>(definitions: readonly T[]): T[];
+/**
+ * One raw value, as the definition's type stores it — or `undefined` when
+ * nothing usable was given.
+ *
+ * `undefined` and `null` are different answers on purpose. `null` is the
+ * explicit "cleared" that keeps the key present for a `where` clause to find;
+ * it is what a console save or an API body writes when it MEANS to clear.
+ * `undefined` is "there is no value here", which a form submission produces
+ * for a field left blank — and a blank field on a form must not clear a
+ * value the merchant set by hand, so the caller drops the key rather than
+ * writing it.
+ *
+ *  - `text` and `url` store the trimmed string, capped. A link has to parse
+ *    as an `http(s)` URL, because the column renders it as one and a bare
+ *    word would be a broken anchor on every row.
+ *  - `number` stores a finite number. A numeric STRING is accepted because a
+ *    form posts every field as text, but anything that is not one number is
+ *    dropped rather than stored as `NaN`, which Firestore would refuse.
+ *  - `checkbox` stores a boolean, reading the strings a browser posts for a
+ *    ticked or an unticked box.
+ *  - `date` stores an ISO 8601 string, so a date filter compares as text and
+ *    an export reads as a date, whichever locale typed it.
+ *  - `select` stores one of the declared options, exactly, or nothing: a
+ *    choice outside the list would be a value the picker could never show.
+ */
+export declare function coerceContactCustomValue(definition: Pick<ContactFieldDefinition, 'type' | 'options'>, raw: unknown): ContactCustomValue | undefined;
+/**
+ * What a form submission writes into the contact's `custom`: one entry per
+ * declared field that names a contact field, coerced by that field's type.
+ *
+ * Only ACTIVE definitions receive a value — a mapping onto a retired field
+ * is a mapping the author has not yet removed, and writing under a retired
+ * key would put a value where no surface offers to show it. A field the
+ * visitor left blank contributes nothing (see `coerceContactCustomValue`),
+ * so a submission never clears a value a merchant set by hand.
+ *
+ * Two declared fields mapped onto one key is an authoring mistake this
+ * function does not refuse; the FIRST declared field to yield a value wins,
+ * in declaration order, so the answer is at least stable.
+ */
+export declare function collectMappedContactCustom(options: {
+    /** The submitted values, keyed by the declared `fieldName`. */
+    fields: Record<string, unknown>;
+    /** The form's declaration, as stored on its document. */
+    decls: readonly FormFieldDecl[] | null | undefined;
+    /** The org's definitions, retired ones included — they are filtered here. */
+    definitions: readonly ContactFieldDefinition[];
+}): Record<string, ContactCustomValue>;
+/**
+ * The declaration a publish writes, with the mappings the author drew on the
+ * previous one carried across.
+ *
+ * `formFieldDeclsFromNodes` reads a declaration off the DESIGN — the names,
+ * types and options the nodes carry — and knows nothing about where a field
+ * saves to, because that is edited on the form's own page rather than drawn
+ * on the canvas. A publish that replaced the stored `fields` wholesale would
+ * therefore drop every mapping on every publish, and the author would find
+ * their profile fields silently empty after the next design change.
+ *
+ * Carried BY FIELD NAME, which is the submission key and the identity a
+ * declared field has. A field renamed on the canvas is a new field and starts
+ * unmapped; a field removed takes its mapping with it. Nothing else on the
+ * previous declaration survives — the design is still the source of truth
+ * for everything it draws.
+ */
+export declare function carryContactFieldMappings(previous: readonly FormFieldDecl[] | null | undefined, next: readonly FormFieldDecl[]): FormFieldDecl[];
+/**
+ * The declaration with ONE field's destination changed: `key` maps it onto
+ * that custom field, `null` unmaps it.
+ *
+ * Unmapping DELETES the property rather than setting it to `undefined`. The
+ * declaration is written back to the form document as one array, and an
+ * `undefined` inside an array is a value Firestore refuses outright — the
+ * save would fail on the field the author just cleared, which is the one
+ * they are least likely to suspect. Every other field, and every other
+ * property of this one, comes through untouched: the design is still the
+ * source of everything else on a declared field.
+ */
+export declare function withContactFieldMapping(decls: readonly FormFieldDecl[], fieldName: string, key: string | null): FormFieldDecl[];
+/**
+ * A `custom` map sent to the API, validated against the org's definitions.
+ *
+ * Unknown keys are REFUSED rather than dropped, following the contact
+ * resource's own rule for its top-level keys: a silent drop reads as "we
+ * stored your value" when nothing was stored, and an integration pushing a
+ * field it spelled wrong would never learn. Each refusal is named
+ * `custom.<key>` so a client can match it to the entry it sent.
+ *
+ * A retired field is refused too. Its values are still READ — an export has
+ * to show what was written under it — but nothing writes under a key the
+ * console no longer offers, or the field could never actually go away.
+ *
+ * `null` is accepted for every type and means "clear": the key stays present
+ * with an explicit nothing, which is the shape the console writes and the
+ * shape a `where` clause can find.
+ */
+export declare function readContactCustomInput(raw: unknown, definitions: readonly ContactFieldDefinition[], 
+/**
+ * The object the map is written on, for the refusals' wording — the
+ * caller has already narrowed `definitions` to it. Contacts when unsaid.
+ */
+object?: CrmFieldObject): {
+    values: Record<string, ContactCustomValue>;
+} | {
+    errors: Record<string, string>;
+};
+/**
+ * `readContactCustomInput` for ANY object (AGL-2661): the org's whole
+ * definition list in, the ones describing `object` judged.
+ *
+ * The narrowing happens here rather than at every caller so a company
+ * body cannot be validated against a contact field of the same key —
+ * `region` on both is two fields, and a value sent to one must never be
+ * read by the other's type. What comes back is exactly what the contact
+ * reader answers: a map to store, or refusals named `custom.<key>`.
+ */
+export declare function readCrmCustomInput(raw: unknown, definitions: readonly ContactFieldDefinition[], object: CrmFieldObject): {
+    values: Record<string, ContactCustomValue>;
+} | {
+    errors: Record<string, string>;
+};

package/src/lib/app-utils/contact-custom-fields.js

@@ -0,0 +1,349 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Custom contact fields (AGL-2601): what a VALUE under a definition may be,
+ * and the three doors a value comes in through.
+ *
+ * `crm.ts` declares the definition — `ContactFieldDefinition`, its key
+ * grammar and its collection. This module is everything that happens between
+ * a definition and a value: a form submission carrying a mapped field, an API
+ * body carrying a `custom` map, and a publish that must not lose the mapping
+ * an author drew. Each door coerces by the definition's TYPE, and the rule is
+ * one function so a number typed into a form and a number sent over the API
+ * cannot be stored as different things.
+ *
+ * Pure like the module it extends: no Firestore, no React. The bound on how
+ * many definitions one org keeps is stated here because every reader of the
+ * collection — the console hook, the submit route, the API — has to read it
+ * whole, and a reader without a limit is a reader whose cost is somebody
+ * else's decision.
+ */ import { fieldDefinitionObject } from "./crm.js";
+/**
+ * How many field definitions one organization may hold, and therefore the
+ * `limit()` every reader of `orgs/{orgId}/contactFields` applies.
+ *
+ * The collection is read WHOLE — there is no index on it and the list is
+ * sorted by `order` in memory — so this is the ceiling on that read. A
+ * hundred is far past what a profile form can carry; an org that wants more
+ * has outgrown a per-contact map and needs a dataset.
+ */ export const CONTACT_FIELDS_MAX_PER_ORG = 100;
+/** Every value type a definition may declare, in the order a picker lists them. */ export const CONTACT_FIELD_TYPES = [
+    'text',
+    'number',
+    'date',
+    'select',
+    'checkbox',
+    'url'
+];
+/** How a field type reads on screen — typed so a type cannot ship unlabeled. */ export const CONTACT_FIELD_TYPE_LABELS = {
+    text: 'Text',
+    number: 'Number',
+    date: 'Date',
+    select: 'Choice',
+    checkbox: 'Checkbox',
+    url: 'Link'
+};
+export function isContactFieldType(value) {
+    return typeof value === 'string' && CONTACT_FIELD_TYPES.includes(value);
+}
+/** The longest string a text or link field stores. */ const CONTACT_TEXT_VALUE_MAX = 2000;
+/**
+ * Definitions in the order a form, a column set and an export show them.
+ *
+ * `order` first, then the key, so two definitions that were given the same
+ * position — which a reorder in flight can produce for one write — still
+ * come out in one stable order on every surface rather than flickering.
+ */ export function sortContactFieldDefinitions(definitions) {
+    return [
+        ...definitions
+    ].sort((a, b)=>(Number(a.order) || 0) - (Number(b.order) || 0) || a.key.localeCompare(b.key));
+}
+/**
+ * The definitions that describe ONE object, in `order` (AGL-2661).
+ *
+ * Every reader of the collection gets it whole — it is one bounded read —
+ * and narrows here, through the one reader of `object`, so a definition
+ * written before the key existed lands on the contacts tab and nowhere
+ * else. Keys are unique within what this returns, not across it.
+ */ export function fieldDefinitionsForObject(definitions, object) {
+    return sortContactFieldDefinitions(definitions.filter((definition)=>fieldDefinitionObject(definition) === object));
+}
+/** The definitions a value may still be WRITTEN under — sorted, not retired. */ export function activeContactFieldDefinitions(definitions) {
+    return sortContactFieldDefinitions(definitions.filter((definition)=>!definition.retiredAt));
+}
+/** Checkbox values a browser form actually posts for a ticked box. */ const AFFIRMATIVE = new Set([
+    'true',
+    'on',
+    'yes',
+    '1',
+    'checked'
+]);
+/** And what it posts, or what a client sends, for an unticked one. */ const NEGATIVE = new Set([
+    'false',
+    'off',
+    'no',
+    '0',
+    'unchecked'
+]);
+/**
+ * One raw value, as the definition's type stores it — or `undefined` when
+ * nothing usable was given.
+ *
+ * `undefined` and `null` are different answers on purpose. `null` is the
+ * explicit "cleared" that keeps the key present for a `where` clause to find;
+ * it is what a console save or an API body writes when it MEANS to clear.
+ * `undefined` is "there is no value here", which a form submission produces
+ * for a field left blank — and a blank field on a form must not clear a
+ * value the merchant set by hand, so the caller drops the key rather than
+ * writing it.
+ *
+ *  - `text` and `url` store the trimmed string, capped. A link has to parse
+ *    as an `http(s)` URL, because the column renders it as one and a bare
+ *    word would be a broken anchor on every row.
+ *  - `number` stores a finite number. A numeric STRING is accepted because a
+ *    form posts every field as text, but anything that is not one number is
+ *    dropped rather than stored as `NaN`, which Firestore would refuse.
+ *  - `checkbox` stores a boolean, reading the strings a browser posts for a
+ *    ticked or an unticked box.
+ *  - `date` stores an ISO 8601 string, so a date filter compares as text and
+ *    an export reads as a date, whichever locale typed it.
+ *  - `select` stores one of the declared options, exactly, or nothing: a
+ *    choice outside the list would be a value the picker could never show.
+ */ export function coerceContactCustomValue(definition, raw) {
+    if (raw === undefined || raw === null) return undefined;
+    switch(definition.type){
+        case 'text':
+            {
+                const text = String(raw).trim().slice(0, CONTACT_TEXT_VALUE_MAX);
+                return text ? text : undefined;
+            }
+        case 'url':
+            {
+                const text = String(raw).trim().slice(0, CONTACT_TEXT_VALUE_MAX);
+                if (!text) return undefined;
+                try {
+                    const url = new URL(text);
+                    return url.protocol === 'http:' || url.protocol === 'https:' ? text : undefined;
+                } catch (unused) {
+                    return undefined;
+                }
+            }
+        case 'number':
+            {
+                if (typeof raw === 'number') return Number.isFinite(raw) ? raw : undefined;
+                if (typeof raw === 'boolean') return undefined;
+                const text = String(raw).trim();
+                if (!text) return undefined;
+                const parsed = Number(text);
+                return Number.isFinite(parsed) ? parsed : undefined;
+            }
+        case 'checkbox':
+            {
+                if (typeof raw === 'boolean') return raw;
+                const text = String(raw).trim().toLowerCase();
+                if (AFFIRMATIVE.has(text)) return true;
+                if (NEGATIVE.has(text)) return false;
+                return undefined;
+            }
+        case 'date':
+            {
+                if (typeof raw === 'boolean') return undefined;
+                const ms = typeof raw === 'number' ? raw : raw instanceof Date ? raw.getTime() : Date.parse(String(raw).trim());
+                return Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+            }
+        case 'select':
+            {
+                const text = String(raw).trim();
+                const options = Array.isArray(definition.options) ? definition.options : [];
+                return text && options.includes(text) ? text : undefined;
+            }
+        default:
+            return undefined;
+    }
+}
+/**
+ * What a form submission writes into the contact's `custom`: one entry per
+ * declared field that names a contact field, coerced by that field's type.
+ *
+ * Only ACTIVE definitions receive a value — a mapping onto a retired field
+ * is a mapping the author has not yet removed, and writing under a retired
+ * key would put a value where no surface offers to show it. A field the
+ * visitor left blank contributes nothing (see `coerceContactCustomValue`),
+ * so a submission never clears a value a merchant set by hand.
+ *
+ * Two declared fields mapped onto one key is an authoring mistake this
+ * function does not refuse; the FIRST declared field to yield a value wins,
+ * in declaration order, so the answer is at least stable.
+ */ export function collectMappedContactCustom(options) {
+    var _options_decls;
+    const active = new Map(activeContactFieldDefinitions(options.definitions).map((definition)=>[
+            definition.key,
+            definition
+        ]));
+    const custom = {};
+    for (const decl of (_options_decls = options.decls) != null ? _options_decls : []){
+        const key = decl.contactFieldKey;
+        if (!key || key in custom) continue;
+        const definition = active.get(key);
+        if (!definition) continue;
+        const value = coerceContactCustomValue(definition, options.fields[decl.fieldName]);
+        if (value !== undefined) custom[key] = value;
+    }
+    return custom;
+}
+/**
+ * The declaration a publish writes, with the mappings the author drew on the
+ * previous one carried across.
+ *
+ * `formFieldDeclsFromNodes` reads a declaration off the DESIGN — the names,
+ * types and options the nodes carry — and knows nothing about where a field
+ * saves to, because that is edited on the form's own page rather than drawn
+ * on the canvas. A publish that replaced the stored `fields` wholesale would
+ * therefore drop every mapping on every publish, and the author would find
+ * their profile fields silently empty after the next design change.
+ *
+ * Carried BY FIELD NAME, which is the submission key and the identity a
+ * declared field has. A field renamed on the canvas is a new field and starts
+ * unmapped; a field removed takes its mapping with it. Nothing else on the
+ * previous declaration survives — the design is still the source of truth
+ * for everything it draws.
+ */ export function carryContactFieldMappings(previous, next) {
+    const carried = new Map();
+    for (const decl of previous != null ? previous : []){
+        if ((decl == null ? void 0 : decl.fieldName) && decl.contactFieldKey) {
+            carried.set(decl.fieldName, decl.contactFieldKey);
+        }
+    }
+    return next.map((decl)=>{
+        const key = carried.get(decl.fieldName);
+        return key ? _extends({}, decl, {
+            contactFieldKey: key
+        }) : decl;
+    });
+}
+/**
+ * The declaration with ONE field's destination changed: `key` maps it onto
+ * that custom field, `null` unmaps it.
+ *
+ * Unmapping DELETES the property rather than setting it to `undefined`. The
+ * declaration is written back to the form document as one array, and an
+ * `undefined` inside an array is a value Firestore refuses outright — the
+ * save would fail on the field the author just cleared, which is the one
+ * they are least likely to suspect. Every other field, and every other
+ * property of this one, comes through untouched: the design is still the
+ * source of everything else on a declared field.
+ */ export function withContactFieldMapping(decls, fieldName, key) {
+    return decls.map((decl)=>{
+        if (decl.fieldName !== fieldName) return decl;
+        const next = _extends({}, decl);
+        delete next.contactFieldKey;
+        return key ? _extends({}, next, {
+            contactFieldKey: key
+        }) : next;
+    });
+}
+/** What one coercion refusal tells an API caller, per type. */ function customValueExpectation(definition) {
+    switch(definition.type){
+        case 'number':
+            return 'Must be a number';
+        case 'checkbox':
+            return 'Must be true or false';
+        case 'date':
+            return 'Must be an ISO 8601 date';
+        case 'url':
+            return 'Must be an http(s) URL';
+        case 'select':
+            var _definition_options;
+            return `Must be one of: ${((_definition_options = definition.options) != null ? _definition_options : []).join(', ')}`;
+        default:
+            return 'Must be text';
+    }
+}
+/**
+ * A `custom` map sent to the API, validated against the org's definitions.
+ *
+ * Unknown keys are REFUSED rather than dropped, following the contact
+ * resource's own rule for its top-level keys: a silent drop reads as "we
+ * stored your value" when nothing was stored, and an integration pushing a
+ * field it spelled wrong would never learn. Each refusal is named
+ * `custom.<key>` so a client can match it to the entry it sent.
+ *
+ * A retired field is refused too. Its values are still READ — an export has
+ * to show what was written under it — but nothing writes under a key the
+ * console no longer offers, or the field could never actually go away.
+ *
+ * `null` is accepted for every type and means "clear": the key stays present
+ * with an explicit nothing, which is the shape the console writes and the
+ * shape a `where` clause can find.
+ */ export function readContactCustomInput(raw, definitions, /**
+   * The object the map is written on, for the refusals' wording — the
+   * caller has already narrowed `definitions` to it. Contacts when unsaid.
+   */ object = 'contact') {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {
+            errors: {
+                custom: 'Must be an object of field values keyed by field key'
+            }
+        };
+    }
+    const byKey = new Map(sortContactFieldDefinitions(definitions).map((definition)=>[
+            definition.key,
+            definition
+        ]));
+    const values = {};
+    const errors = {};
+    for (const [key, value] of Object.entries(raw)){
+        const definition = byKey.get(key);
+        if (!definition) {
+            errors[`custom.${key}`] = `No such ${object} field`;
+            continue;
+        }
+        if (definition.retiredAt) {
+            errors[`custom.${key}`] = `Retired ${object} field — restore it to write it`;
+            continue;
+        }
+        if (value === null) {
+            values[key] = null;
+            continue;
+        }
+        const coerced = coerceContactCustomValue(definition, value);
+        if (coerced === undefined) {
+            errors[`custom.${key}`] = customValueExpectation(definition);
+            continue;
+        }
+        values[key] = coerced;
+    }
+    return Object.keys(errors).length ? {
+        errors
+    } : {
+        values
+    };
+}
+/**
+ * `readContactCustomInput` for ANY object (AGL-2661): the org's whole
+ * definition list in, the ones describing `object` judged.
+ *
+ * The narrowing happens here rather than at every caller so a company
+ * body cannot be validated against a contact field of the same key —
+ * `region` on both is two fields, and a value sent to one must never be
+ * read by the other's type. What comes back is exactly what the contact
+ * reader answers: a map to store, or refusals named `custom.<key>`.
+ */ export function readCrmCustomInput(raw, definitions, object) {
+    return readContactCustomInput(raw, fieldDefinitionsForObject(definitions, object), object);
+}
+
+//# sourceMappingURL=contact-custom-fields.js.map