@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/contact-custom-fields.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\n/**\n * Custom contact fields (AGL-2601): what a VALUE under a definition may be,\n * and the three doors a value comes in through.\n *\n * `crm.ts` declares the definition — `ContactFieldDefinition`, its key\n * grammar and its collection. This module is everything that happens between\n * a definition and a value: a form submission carrying a mapped field, an API\n * body carrying a `custom` map, and a publish that must not lose the mapping\n * an author drew. Each door coerces by the definition's TYPE, and the rule is\n * one function so a number typed into a form and a number sent over the API\n * cannot be stored as different things.\n *\n * Pure like the module it extends: no Firestore, no React. The bound on how\n * many definitions one org keeps is stated here because every reader of the\n * collection — the console hook, the submit route, the API — has to read it\n * whole, and a reader without a limit is a reader whose cost is somebody\n * else's decision.\n */\n\nimport {\n  type ContactCustomValue,\n  type ContactFieldDefinition,\n  type ContactFieldType,\n  type CrmFieldObject,\n  fieldDefinitionObject,\n} from './crm'\nimport type { FormFieldDecl } from './forms'\n\n/**\n * How many field definitions one organization may hold, and therefore the\n * `limit()` every reader of `orgs/{orgId}/contactFields` applies.\n *\n * The collection is read WHOLE — there is no index on it and the list is\n * sorted by `order` in memory — so this is the ceiling on that read. A\n * hundred is far past what a profile form can carry; an org that wants more\n * has outgrown a per-contact map and needs a dataset.\n */\nexport const CONTACT_FIELDS_MAX_PER_ORG = 100\n\n/** Every value type a definition may declare, in the order a picker lists them. */\nexport const CONTACT_FIELD_TYPES: readonly ContactFieldType[] = [\n  'text',\n  'number',\n  'date',\n  'select',\n  'checkbox',\n  'url',\n]\n\n/** How a field type reads on screen — typed so a type cannot ship unlabeled. */\nexport const CONTACT_FIELD_TYPE_LABELS: Record<ContactFieldType, string> = {\n  text: 'Text',\n  number: 'Number',\n  date: 'Date',\n  select: 'Choice',\n  checkbox: 'Checkbox',\n  url: 'Link',\n}\n\nexport function isContactFieldType(value: unknown): value is ContactFieldType {\n  return (\n    typeof value === 'string' &&\n    (CONTACT_FIELD_TYPES as readonly string[]).includes(value)\n  )\n}\n\n/** The longest string a text or link field stores. */\nconst CONTACT_TEXT_VALUE_MAX = 2000\n\n/**\n * Definitions in the order a form, a column set and an export show them.\n *\n * `order` first, then the key, so two definitions that were given the same\n * position — which a reorder in flight can produce for one write — still\n * come out in one stable order on every surface rather than flickering.\n */\nexport function sortContactFieldDefinitions<\n  T extends Pick<ContactFieldDefinition, 'order' | 'key'>,\n>(definitions: readonly T[]): T[] {\n  return [...definitions].sort(\n    (a, b) =>\n      (Number(a.order) || 0) - (Number(b.order) || 0) ||\n      a.key.localeCompare(b.key),\n  )\n}\n\n/**\n * The definitions that describe ONE object, in `order` (AGL-2661).\n *\n * Every reader of the collection gets it whole — it is one bounded read —\n * and narrows here, through the one reader of `object`, so a definition\n * written before the key existed lands on the contacts tab and nowhere\n * else. Keys are unique within what this returns, not across it.\n */\nexport function fieldDefinitionsForObject<\n  T extends Pick<ContactFieldDefinition, 'order' | 'key' | 'object'>,\n>(definitions: readonly T[], object: CrmFieldObject): T[] {\n  return sortContactFieldDefinitions(\n    definitions.filter((definition) => fieldDefinitionObject(definition) === object),\n  )\n}\n\n/** The definitions a value may still be WRITTEN under — sorted, not retired. */\nexport function activeContactFieldDefinitions<\n  T extends Pick<ContactFieldDefinition, 'order' | 'key' | 'retiredAt'>,\n>(definitions: readonly T[]): T[] {\n  return sortContactFieldDefinitions(\n    definitions.filter((definition) => !definition.retiredAt),\n  )\n}\n\n/** Checkbox values a browser form actually posts for a ticked box. */\nconst AFFIRMATIVE = new Set(['true', 'on', 'yes', '1', 'checked'])\n/** And what it posts, or what a client sends, for an unticked one. */\nconst NEGATIVE = new Set(['false', 'off', 'no', '0', 'unchecked'])\n\n/**\n * One raw value, as the definition's type stores it — or `undefined` when\n * nothing usable was given.\n *\n * `undefined` and `null` are different answers on purpose. `null` is the\n * explicit \"cleared\" that keeps the key present for a `where` clause to find;\n * it is what a console save or an API body writes when it MEANS to clear.\n * `undefined` is \"there is no value here\", which a form submission produces\n * for a field left blank — and a blank field on a form must not clear a\n * value the merchant set by hand, so the caller drops the key rather than\n * writing it.\n *\n *  - `text` and `url` store the trimmed string, capped. A link has to parse\n *    as an `http(s)` URL, because the column renders it as one and a bare\n *    word would be a broken anchor on every row.\n *  - `number` stores a finite number. A numeric STRING is accepted because a\n *    form posts every field as text, but anything that is not one number is\n *    dropped rather than stored as `NaN`, which Firestore would refuse.\n *  - `checkbox` stores a boolean, reading the strings a browser posts for a\n *    ticked or an unticked box.\n *  - `date` stores an ISO 8601 string, so a date filter compares as text and\n *    an export reads as a date, whichever locale typed it.\n *  - `select` stores one of the declared options, exactly, or nothing: a\n *    choice outside the list would be a value the picker could never show.\n */\nexport function coerceContactCustomValue(\n  definition: Pick<ContactFieldDefinition, 'type' | 'options'>,\n  raw: unknown,\n): ContactCustomValue | undefined {\n  if (raw === undefined || raw === null) return undefined\n  switch (definition.type) {\n    case 'text': {\n      const text = String(raw).trim().slice(0, CONTACT_TEXT_VALUE_MAX)\n      return text ? text : undefined\n    }\n    case 'url': {\n      const text = String(raw).trim().slice(0, CONTACT_TEXT_VALUE_MAX)\n      if (!text) return undefined\n      try {\n        const url = new URL(text)\n        return url.protocol === 'http:' || url.protocol === 'https:'\n          ? text\n          : undefined\n      } catch {\n        return undefined\n      }\n    }\n    case 'number': {\n      if (typeof raw === 'number') return Number.isFinite(raw) ? raw : undefined\n      if (typeof raw === 'boolean') return undefined\n      const text = String(raw).trim()\n      if (!text) return undefined\n      const parsed = Number(text)\n      return Number.isFinite(parsed) ? parsed : undefined\n    }\n    case 'checkbox': {\n      if (typeof raw === 'boolean') return raw\n      const text = String(raw).trim().toLowerCase()\n      if (AFFIRMATIVE.has(text)) return true\n      if (NEGATIVE.has(text)) return false\n      return undefined\n    }\n    case 'date': {\n      if (typeof raw === 'boolean') return undefined\n      const ms =\n        typeof raw === 'number'\n          ? raw\n          : raw instanceof Date\n            ? raw.getTime()\n            : Date.parse(String(raw).trim())\n      return Number.isFinite(ms) ? new Date(ms).toISOString() : undefined\n    }\n    case 'select': {\n      const text = String(raw).trim()\n      const options = Array.isArray(definition.options) ? definition.options : []\n      return text && options.includes(text) ? text : undefined\n    }\n    default:\n      return undefined\n  }\n}\n\n/**\n * What a form submission writes into the contact's `custom`: one entry per\n * declared field that names a contact field, coerced by that field's type.\n *\n * Only ACTIVE definitions receive a value — a mapping onto a retired field\n * is a mapping the author has not yet removed, and writing under a retired\n * key would put a value where no surface offers to show it. A field the\n * visitor left blank contributes nothing (see `coerceContactCustomValue`),\n * so a submission never clears a value a merchant set by hand.\n *\n * Two declared fields mapped onto one key is an authoring mistake this\n * function does not refuse; the FIRST declared field to yield a value wins,\n * in declaration order, so the answer is at least stable.\n */\nexport function collectMappedContactCustom(options: {\n  /** The submitted values, keyed by the declared `fieldName`. */\n  fields: Record<string, unknown>\n  /** The form's declaration, as stored on its document. */\n  decls: readonly FormFieldDecl[] | null | undefined\n  /** The org's definitions, retired ones included — they are filtered here. */\n  definitions: readonly ContactFieldDefinition[]\n}): Record<string, ContactCustomValue> {\n  const active = new Map(\n    activeContactFieldDefinitions(options.definitions).map((definition) => [\n      definition.key,\n      definition,\n    ]),\n  )\n  const custom: Record<string, ContactCustomValue> = {}\n  for (const decl of options.decls ?? []) {\n    const key = decl.contactFieldKey\n    if (!key || key in custom) continue\n    const definition = active.get(key)\n    if (!definition) continue\n    const value = coerceContactCustomValue(definition, options.fields[decl.fieldName])\n    if (value !== undefined) custom[key] = value\n  }\n  return custom\n}\n\n/**\n * The declaration a publish writes, with the mappings the author drew on the\n * previous one carried across.\n *\n * `formFieldDeclsFromNodes` reads a declaration off the DESIGN — the names,\n * types and options the nodes carry — and knows nothing about where a field\n * saves to, because that is edited on the form's own page rather than drawn\n * on the canvas. A publish that replaced the stored `fields` wholesale would\n * therefore drop every mapping on every publish, and the author would find\n * their profile fields silently empty after the next design change.\n *\n * Carried BY FIELD NAME, which is the submission key and the identity a\n * declared field has. A field renamed on the canvas is a new field and starts\n * unmapped; a field removed takes its mapping with it. Nothing else on the\n * previous declaration survives — the design is still the source of truth\n * for everything it draws.\n */\nexport function carryContactFieldMappings(\n  previous: readonly FormFieldDecl[] | null | undefined,\n  next: readonly FormFieldDecl[],\n): FormFieldDecl[] {\n  const carried = new Map<string, string>()\n  for (const decl of previous ?? []) {\n    if (decl?.fieldName && decl.contactFieldKey) {\n      carried.set(decl.fieldName, decl.contactFieldKey)\n    }\n  }\n  return next.map((decl) => {\n    const key = carried.get(decl.fieldName)\n    return key ? { ...decl, contactFieldKey: key } : decl\n  })\n}\n\n/**\n * The declaration with ONE field's destination changed: `key` maps it onto\n * that custom field, `null` unmaps it.\n *\n * Unmapping DELETES the property rather than setting it to `undefined`. The\n * declaration is written back to the form document as one array, and an\n * `undefined` inside an array is a value Firestore refuses outright — the\n * save would fail on the field the author just cleared, which is the one\n * they are least likely to suspect. Every other field, and every other\n * property of this one, comes through untouched: the design is still the\n * source of everything else on a declared field.\n */\nexport function withContactFieldMapping(\n  decls: readonly FormFieldDecl[],\n  fieldName: string,\n  key: string | null,\n): FormFieldDecl[] {\n  return decls.map((decl) => {\n    if (decl.fieldName !== fieldName) return decl\n    const next: FormFieldDecl = { ...decl }\n    delete next.contactFieldKey\n    return key ? { ...next, contactFieldKey: key } : next\n  })\n}\n\n/** What one coercion refusal tells an API caller, per type. */\nfunction customValueExpectation(\n  definition: Pick<ContactFieldDefinition, 'type' | 'options'>,\n): string {\n  switch (definition.type) {\n    case 'number':\n      return 'Must be a number'\n    case 'checkbox':\n      return 'Must be true or false'\n    case 'date':\n      return 'Must be an ISO 8601 date'\n    case 'url':\n      return 'Must be an http(s) URL'\n    case 'select':\n      return `Must be one of: ${(definition.options ?? []).join(', ')}`\n    default:\n      return 'Must be text'\n  }\n}\n\n/**\n * A `custom` map sent to the API, validated against the org's definitions.\n *\n * Unknown keys are REFUSED rather than dropped, following the contact\n * resource's own rule for its top-level keys: a silent drop reads as \"we\n * stored your value\" when nothing was stored, and an integration pushing a\n * field it spelled wrong would never learn. Each refusal is named\n * `custom.<key>` so a client can match it to the entry it sent.\n *\n * A retired field is refused too. Its values are still READ — an export has\n * to show what was written under it — but nothing writes under a key the\n * console no longer offers, or the field could never actually go away.\n *\n * `null` is accepted for every type and means \"clear\": the key stays present\n * with an explicit nothing, which is the shape the console writes and the\n * shape a `where` clause can find.\n */\nexport function readContactCustomInput(\n  raw: unknown,\n  definitions: readonly ContactFieldDefinition[],\n  /**\n   * The object the map is written on, for the refusals' wording — the\n   * caller has already narrowed `definitions` to it. Contacts when unsaid.\n   */\n  object: CrmFieldObject = 'contact',\n): { values: Record<string, ContactCustomValue> } | { errors: Record<string, string> } {\n  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {\n    return { errors: { custom: 'Must be an object of field values keyed by field key' } }\n  }\n  const byKey = new Map(\n    sortContactFieldDefinitions(definitions).map((definition) => [\n      definition.key,\n      definition,\n    ]),\n  )\n  const values: Record<string, ContactCustomValue> = {}\n  const errors: Record<string, string> = {}\n  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {\n    const definition = byKey.get(key)\n    if (!definition) {\n      errors[`custom.${key}`] = `No such ${object} field`\n      continue\n    }\n    if (definition.retiredAt) {\n      errors[`custom.${key}`] = `Retired ${object} field — restore it to write it`\n      continue\n    }\n    if (value === null) {\n      values[key] = null\n      continue\n    }\n    const coerced = coerceContactCustomValue(definition, value)\n    if (coerced === undefined) {\n      errors[`custom.${key}`] = customValueExpectation(definition)\n      continue\n    }\n    values[key] = coerced\n  }\n  return Object.keys(errors).length ? { errors } : { values }\n}\n\n/**\n * `readContactCustomInput` for ANY object (AGL-2661): the org's whole\n * definition list in, the ones describing `object` judged.\n *\n * The narrowing happens here rather than at every caller so a company\n * body cannot be validated against a contact field of the same key —\n * `region` on both is two fields, and a value sent to one must never be\n * read by the other's type. What comes back is exactly what the contact\n * reader answers: a map to store, or refusals named `custom.<key>`.\n */\nexport function readCrmCustomInput(\n  raw: unknown,\n  definitions: readonly ContactFieldDefinition[],\n  object: CrmFieldObject,\n): { values: Record<string, ContactCustomValue> } | { errors: Record<string, string> } {\n  return readContactCustomInput(raw, fieldDefinitionsForObject(definitions, object), object)\n}\n"],"names":["fieldDefinitionObject","CONTACT_FIELDS_MAX_PER_ORG","CONTACT_FIELD_TYPES","CONTACT_FIELD_TYPE_LABELS","text","number","date","select","checkbox","url","isContactFieldType","value","includes","CONTACT_TEXT_VALUE_MAX","sortContactFieldDefinitions","definitions","sort","a","b","Number","order","key","localeCompare","fieldDefinitionsForObject","object","filter","definition","activeContactFieldDefinitions","retiredAt","AFFIRMATIVE","Set","NEGATIVE","coerceContactCustomValue","raw","undefined","type","String","trim","slice","URL","protocol","isFinite","parsed","toLowerCase","has","ms","Date","getTime","parse","toISOString","options","Array","isArray","collectMappedContactCustom","active","Map","map","custom","decl","decls","contactFieldKey","get","fields","fieldName","carryContactFieldMappings","previous","next","carried","set","withContactFieldMapping","customValueExpectation","join","readContactCustomInput","errors","byKey","values","Object","entries","coerced","keys","length","readCrmCustomInput"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;CAiBC,GAED,SAKEA,qBAAqB,QAChB,WAAO;AAGd;;;;;;;;CAQC,GACD,OAAO,MAAMC,6BAA6B,IAAG;AAE7C,iFAAiF,GACjF,OAAO,MAAMC,sBAAmD;IAC9D;IACA;IACA;IACA;IACA;IACA;CACD,CAAA;AAED,8EAA8E,GAC9E,OAAO,MAAMC,4BAA8D;IACzEC,MAAM;IACNC,QAAQ;IACRC,MAAM;IACNC,QAAQ;IACRC,UAAU;IACVC,KAAK;AACP,EAAC;AAED,OAAO,SAASC,mBAAmBC,KAAc;IAC/C,OACE,OAAOA,UAAU,YACjB,AAACT,oBAA0CU,QAAQ,CAACD;AAExD;AAEA,oDAAoD,GACpD,MAAME,yBAAyB;AAE/B;;;;;;CAMC,GACD,OAAO,SAASC,4BAEdC,WAAyB;IACzB,OAAO;WAAIA;KAAY,CAACC,IAAI,CAC1B,CAACC,GAAGC,IACF,AAACC,CAAAA,OAAOF,EAAEG,KAAK,KAAK,CAAA,IAAMD,CAAAA,OAAOD,EAAEE,KAAK,KAAK,CAAA,KAC7CH,EAAEI,GAAG,CAACC,aAAa,CAACJ,EAAEG,GAAG;AAE/B;AAEA;;;;;;;CAOC,GACD,OAAO,SAASE,0BAEdR,WAAyB,EAAES,MAAsB;IACjD,OAAOV,4BACLC,YAAYU,MAAM,CAAC,CAACC,aAAe1B,sBAAsB0B,gBAAgBF;AAE7E;AAEA,8EAA8E,GAC9E,OAAO,SAASG,8BAEdZ,WAAyB;IACzB,OAAOD,4BACLC,YAAYU,MAAM,CAAC,CAACC,aAAe,CAACA,WAAWE,SAAS;AAE5D;AAEA,oEAAoE,GACpE,MAAMC,cAAc,IAAIC,IAAI;IAAC;IAAQ;IAAM;IAAO;IAAK;CAAU;AACjE,oEAAoE,GACpE,MAAMC,WAAW,IAAID,IAAI;IAAC;IAAS;IAAO;IAAM;IAAK;CAAY;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GACD,OAAO,SAASE,yBACdN,UAA4D,EAC5DO,GAAY;IAEZ,IAAIA,QAAQC,aAAaD,QAAQ,MAAM,OAAOC;IAC9C,OAAQR,WAAWS,IAAI;QACrB,KAAK;YAAQ;gBACX,MAAM/B,OAAOgC,OAAOH,KAAKI,IAAI,GAAGC,KAAK,CAAC,GAAGzB;gBACzC,OAAOT,OAAOA,OAAO8B;YACvB;QACA,KAAK;YAAO;gBACV,MAAM9B,OAAOgC,OAAOH,KAAKI,IAAI,GAAGC,KAAK,CAAC,GAAGzB;gBACzC,IAAI,CAACT,MAAM,OAAO8B;gBAClB,IAAI;oBACF,MAAMzB,MAAM,IAAI8B,IAAInC;oBACpB,OAAOK,IAAI+B,QAAQ,KAAK,WAAW/B,IAAI+B,QAAQ,KAAK,WAChDpC,OACA8B;gBACN,EAAE,eAAM;oBACN,OAAOA;gBACT;YACF;QACA,KAAK;YAAU;gBACb,IAAI,OAAOD,QAAQ,UAAU,OAAOd,OAAOsB,QAAQ,CAACR,OAAOA,MAAMC;gBACjE,IAAI,OAAOD,QAAQ,WAAW,OAAOC;gBACrC,MAAM9B,OAAOgC,OAAOH,KAAKI,IAAI;gBAC7B,IAAI,CAACjC,MAAM,OAAO8B;gBAClB,MAAMQ,SAASvB,OAAOf;gBACtB,OAAOe,OAAOsB,QAAQ,CAACC,UAAUA,SAASR;YAC5C;QACA,KAAK;YAAY;gBACf,IAAI,OAAOD,QAAQ,WAAW,OAAOA;gBACrC,MAAM7B,OAAOgC,OAAOH,KAAKI,IAAI,GAAGM,WAAW;gBAC3C,IAAId,YAAYe,GAAG,CAACxC,OAAO,OAAO;gBAClC,IAAI2B,SAASa,GAAG,CAACxC,OAAO,OAAO;gBAC/B,OAAO8B;YACT;QACA,KAAK;YAAQ;gBACX,IAAI,OAAOD,QAAQ,WAAW,OAAOC;gBACrC,MAAMW,KACJ,OAAOZ,QAAQ,WACXA,MACAA,eAAea,OACbb,IAAIc,OAAO,KACXD,KAAKE,KAAK,CAACZ,OAAOH,KAAKI,IAAI;gBACnC,OAAOlB,OAAOsB,QAAQ,CAACI,MAAM,IAAIC,KAAKD,IAAII,WAAW,KAAKf;YAC5D;QACA,KAAK;YAAU;gBACb,MAAM9B,OAAOgC,OAAOH,KAAKI,IAAI;gBAC7B,MAAMa,UAAUC,MAAMC,OAAO,CAAC1B,WAAWwB,OAAO,IAAIxB,WAAWwB,OAAO,GAAG,EAAE;gBAC3E,OAAO9C,QAAQ8C,QAAQtC,QAAQ,CAACR,QAAQA,OAAO8B;YACjD;QACA;YACE,OAAOA;IACX;AACF;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASmB,2BAA2BH,OAO1C;QAQoBA;IAPnB,MAAMI,SAAS,IAAIC,IACjB5B,8BAA8BuB,QAAQnC,WAAW,EAAEyC,GAAG,CAAC,CAAC9B,aAAe;YACrEA,WAAWL,GAAG;YACdK;SACD;IAEH,MAAM+B,SAA6C,CAAC;IACpD,KAAK,MAAMC,SAAQR,iBAAAA,QAAQS,KAAK,YAAbT,iBAAiB,EAAE,CAAE;QACtC,MAAM7B,MAAMqC,KAAKE,eAAe;QAChC,IAAI,CAACvC,OAAOA,OAAOoC,QAAQ;QAC3B,MAAM/B,aAAa4B,OAAOO,GAAG,CAACxC;QAC9B,IAAI,CAACK,YAAY;QACjB,MAAMf,QAAQqB,yBAAyBN,YAAYwB,QAAQY,MAAM,CAACJ,KAAKK,SAAS,CAAC;QACjF,IAAIpD,UAAUuB,WAAWuB,MAAM,CAACpC,IAAI,GAAGV;IACzC;IACA,OAAO8C;AACT;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASO,0BACdC,QAAqD,EACrDC,IAA8B;IAE9B,MAAMC,UAAU,IAAIZ;IACpB,KAAK,MAAMG,QAAQO,mBAAAA,WAAY,EAAE,CAAE;QACjC,IAAIP,CAAAA,wBAAAA,KAAMK,SAAS,KAAIL,KAAKE,eAAe,EAAE;YAC3CO,QAAQC,GAAG,CAACV,KAAKK,SAAS,EAAEL,KAAKE,eAAe;QAClD;IACF;IACA,OAAOM,KAAKV,GAAG,CAAC,CAACE;QACf,MAAMrC,MAAM8C,QAAQN,GAAG,CAACH,KAAKK,SAAS;QACtC,OAAO1C,MAAM,aAAKqC;YAAME,iBAAiBvC;aAAQqC;IACnD;AACF;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASW,wBACdV,KAA+B,EAC/BI,SAAiB,EACjB1C,GAAkB;IAElB,OAAOsC,MAAMH,GAAG,CAAC,CAACE;QAChB,IAAIA,KAAKK,SAAS,KAAKA,WAAW,OAAOL;QACzC,MAAMQ,OAAsB,aAAKR;QACjC,OAAOQ,KAAKN,eAAe;QAC3B,OAAOvC,MAAM,aAAK6C;YAAMN,iBAAiBvC;aAAQ6C;IACnD;AACF;AAEA,6DAA6D,GAC7D,SAASI,uBACP5C,UAA4D;IAE5D,OAAQA,WAAWS,IAAI;QACrB,KAAK;YACH,OAAO;QACT,KAAK;YACH,OAAO;QACT,KAAK;YACH,OAAO;QACT,KAAK;YACH,OAAO;QACT,KAAK;gBACwBT;YAA3B,OAAO,CAAC,gBAAgB,EAAE,EAACA,sBAAAA,WAAWwB,OAAO,YAAlBxB,sBAAsB,EAAE,EAAE6C,IAAI,CAAC,OAAO;QACnE;YACE,OAAO;IACX;AACF;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASC,uBACdvC,GAAY,EACZlB,WAA8C,EAC9C;;;GAGC,GACDS,SAAyB,SAAS;IAElC,IAAI,CAACS,OAAO,OAAOA,QAAQ,YAAYkB,MAAMC,OAAO,CAACnB,MAAM;QACzD,OAAO;YAAEwC,QAAQ;gBAAEhB,QAAQ;YAAuD;QAAE;IACtF;IACA,MAAMiB,QAAQ,IAAInB,IAChBzC,4BAA4BC,aAAayC,GAAG,CAAC,CAAC9B,aAAe;YAC3DA,WAAWL,GAAG;YACdK;SACD;IAEH,MAAMiD,SAA6C,CAAC;IACpD,MAAMF,SAAiC,CAAC;IACxC,KAAK,MAAM,CAACpD,KAAKV,MAAM,IAAIiE,OAAOC,OAAO,CAAC5C,KAAiC;QACzE,MAAMP,aAAagD,MAAMb,GAAG,CAACxC;QAC7B,IAAI,CAACK,YAAY;YACf+C,MAAM,CAAC,CAAC,OAAO,EAAEpD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAEG,OAAO,MAAM,CAAC;YACnD;QACF;QACA,IAAIE,WAAWE,SAAS,EAAE;YACxB6C,MAAM,CAAC,CAAC,OAAO,EAAEpD,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAEG,OAAO,+BAA+B,CAAC;YAC5E;QACF;QACA,IAAIb,UAAU,MAAM;YAClBgE,MAAM,CAACtD,IAAI,GAAG;YACd;QACF;QACA,MAAMyD,UAAU9C,yBAAyBN,YAAYf;QACrD,IAAImE,YAAY5C,WAAW;YACzBuC,MAAM,CAAC,CAAC,OAAO,EAAEpD,KAAK,CAAC,GAAGiD,uBAAuB5C;YACjD;QACF;QACAiD,MAAM,CAACtD,IAAI,GAAGyD;IAChB;IACA,OAAOF,OAAOG,IAAI,CAACN,QAAQO,MAAM,GAAG;QAAEP;IAAO,IAAI;QAAEE;IAAO;AAC5D;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASM,mBACdhD,GAAY,EACZlB,WAA8C,EAC9CS,MAAsB;IAEtB,OAAOgD,uBAAuBvC,KAAKV,0BAA0BR,aAAaS,SAASA;AACrF"}

package/src/lib/app-utils/contact-holder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @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 ConsentGroup } from './consent-groups';
+/**
+ * The holder of nothing: the group a contact is flattened through when no
+ * site has captured it and no facet exists — a row written by a path that
+ * predates attribution, read at the org level (AGL-2630).
+ *
+ * An empty `groupId` reads an empty facet (`readContactFacet` answers the
+ * empty facet for a key the map lacks) and REFUSES a write
+ * (`contactFacetPath` throws on an empty holder), which is the right pair:
+ * the row still shows its shared identity, and nothing edits a facet
+ * nobody holds. Exported so a surface can test for it rather than for an
+ * empty string.
+ */
+export declare const NO_HOLDER_GROUP: ConsentGroup;
+/**
+ * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
+ *
+ * Under a site there is one answer for every row — the site's own group,
+ * `consentGroupForHost` — and the reader never asks this. At the
+ * organization level there is no viewing site, and a contact captured by
+ * three sites has up to three facets; the org-wide member reading them all
+ * needs ONE to show the row's profile, owner and stage under, and to write
+ * an edit back to. This picks the person's PRIMARY holder: the first
+ * capturing site, in capture order, whose group actually holds a facet;
+ * then any facet at all, resolved back to its declared group or to the
+ * site whose id it is keyed by; then the first capturing site even with no
+ * facet yet (the facet is written on the first edit). A row nobody captured
+ * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
+ *
+ * Capture order rather than sorted order, deliberately: `capturedByHostIds`
+ * is maintained by `arrayUnion`, so its first entry is the site that met
+ * the person first, and that site's profile is the one a person reading
+ * across brands would expect to see. `contactCaptureHostIds` sorts the same
+ * array for RENDERING, where a stable order matters more than a first.
+ */
+export declare function contactPrimaryGroup(row: Record<string, unknown> | null | undefined, org: Record<string, unknown> | null | undefined): ConsentGroup;

package/src/lib/app-utils/contact-holder.js

@@ -0,0 +1,98 @@
+/**
+ * @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.
+ */ /**
+ * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).
+ *
+ * A contact document carries one facet per holder, and every field but the
+ * shared identity lives in one of them. A surface standing on a site reads
+ * that site's group; a surface standing at the organization — the org-level
+ * Contacts list, and the whole-collection export that writes the same file
+ * — has no site to read as and needs one answer per row.
+ *
+ * In the library rather than in the CRM plugin because both of those
+ * readers need it and one of them is an app: an app may not import a
+ * feature plugin (AGL-2662).
+ */ import { CONTACT_FACETS_FIELD } from "./contacts.js";
+import { CAPTURED_BY_HOST_FIELD } from "./marketing-consent.js";
+import { consentGroupForHost, readConsentGroups, soloConsentGroup } from "./consent-groups.js";
+/**
+ * The holder of nothing: the group a contact is flattened through when no
+ * site has captured it and no facet exists — a row written by a path that
+ * predates attribution, read at the org level (AGL-2630).
+ *
+ * An empty `groupId` reads an empty facet (`readContactFacet` answers the
+ * empty facet for a key the map lacks) and REFUSES a write
+ * (`contactFacetPath` throws on an empty holder), which is the right pair:
+ * the row still shows its shared identity, and nothing edits a facet
+ * nobody holds. Exported so a surface can test for it rather than for an
+ * empty string.
+ */ export const NO_HOLDER_GROUP = Object.freeze({
+    hostId: '',
+    groupId: '',
+    name: null,
+    hostIds: [],
+    declared: false
+});
+/**
+ * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
+ *
+ * Under a site there is one answer for every row — the site's own group,
+ * `consentGroupForHost` — and the reader never asks this. At the
+ * organization level there is no viewing site, and a contact captured by
+ * three sites has up to three facets; the org-wide member reading them all
+ * needs ONE to show the row's profile, owner and stage under, and to write
+ * an edit back to. This picks the person's PRIMARY holder: the first
+ * capturing site, in capture order, whose group actually holds a facet;
+ * then any facet at all, resolved back to its declared group or to the
+ * site whose id it is keyed by; then the first capturing site even with no
+ * facet yet (the facet is written on the first edit). A row nobody captured
+ * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
+ *
+ * Capture order rather than sorted order, deliberately: `capturedByHostIds`
+ * is maintained by `arrayUnion`, so its first entry is the site that met
+ * the person first, and that site's profile is the one a person reading
+ * across brands would expect to see. `contactCaptureHostIds` sorts the same
+ * array for RENDERING, where a stable order matters more than a first.
+ */ export function contactPrimaryGroup(row, org) {
+    const record = row != null ? row : {};
+    const facets = record[CONTACT_FACETS_FIELD];
+    const facetKeys = facets && typeof facets === 'object' && !Array.isArray(facets) ? Object.keys(facets) : [];
+    const raw = record[CAPTURED_BY_HOST_FIELD];
+    const captured = Array.isArray(raw) ? raw.map((id)=>String(id != null ? id : '').trim()).filter(Boolean) : [];
+    for (const hostId of captured){
+        const group = consentGroupForHost(org, hostId);
+        if (facetKeys.includes(group.groupId)) return group;
+    }
+    for (const key of facetKeys){
+        const declared = readConsentGroups(org)[key];
+        if (declared) {
+            return {
+                hostId: declared.hostIds[0],
+                groupId: key,
+                name: declared.name,
+                hostIds: [
+                    ...declared.hostIds
+                ],
+                declared: true
+            };
+        }
+        return soloConsentGroup(key);
+    }
+    if (captured.length) return consentGroupForHost(org, captured[0]);
+    return NO_HOLDER_GROUP;
+}
+
+//# sourceMappingURL=contact-holder.js.map

package/src/lib/app-utils/contact-holder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/contact-holder.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\n/**\n * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).\n *\n * A contact document carries one facet per holder, and every field but the\n * shared identity lives in one of them. A surface standing on a site reads\n * that site's group; a surface standing at the organization — the org-level\n * Contacts list, and the whole-collection export that writes the same file\n * — has no site to read as and needs one answer per row.\n *\n * In the library rather than in the CRM plugin because both of those\n * readers need it and one of them is an app: an app may not import a\n * feature plugin (AGL-2662).\n */\n\nimport { CONTACT_FACETS_FIELD } from './contacts'\nimport { CAPTURED_BY_HOST_FIELD } from './marketing-consent'\nimport {\n  type ConsentGroup,\n  consentGroupForHost,\n  readConsentGroups,\n  soloConsentGroup,\n} from './consent-groups'\n\n/**\n * The holder of nothing: the group a contact is flattened through when no\n * site has captured it and no facet exists — a row written by a path that\n * predates attribution, read at the org level (AGL-2630).\n *\n * An empty `groupId` reads an empty facet (`readContactFacet` answers the\n * empty facet for a key the map lacks) and REFUSES a write\n * (`contactFacetPath` throws on an empty holder), which is the right pair:\n * the row still shows its shared identity, and nothing edits a facet\n * nobody holds. Exported so a surface can test for it rather than for an\n * empty string.\n */\nexport const NO_HOLDER_GROUP: ConsentGroup = Object.freeze({\n  hostId: '',\n  groupId: '',\n  name: null,\n  hostIds: [],\n  declared: false,\n}) as ConsentGroup\n\n/**\n * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).\n *\n * Under a site there is one answer for every row — the site's own group,\n * `consentGroupForHost` — and the reader never asks this. At the\n * organization level there is no viewing site, and a contact captured by\n * three sites has up to three facets; the org-wide member reading them all\n * needs ONE to show the row's profile, owner and stage under, and to write\n * an edit back to. This picks the person's PRIMARY holder: the first\n * capturing site, in capture order, whose group actually holds a facet;\n * then any facet at all, resolved back to its declared group or to the\n * site whose id it is keyed by; then the first capturing site even with no\n * facet yet (the facet is written on the first edit). A row nobody captured\n * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.\n *\n * Capture order rather than sorted order, deliberately: `capturedByHostIds`\n * is maintained by `arrayUnion`, so its first entry is the site that met\n * the person first, and that site's profile is the one a person reading\n * across brands would expect to see. `contactCaptureHostIds` sorts the same\n * array for RENDERING, where a stable order matters more than a first.\n */\nexport function contactPrimaryGroup(\n  row: Record<string, unknown> | null | undefined,\n  org: Record<string, unknown> | null | undefined,\n): ConsentGroup {\n  const record = row ?? {}\n  const facets = record[CONTACT_FACETS_FIELD]\n  const facetKeys =\n    facets && typeof facets === 'object' && !Array.isArray(facets)\n      ? Object.keys(facets as Record<string, unknown>)\n      : []\n  const raw = record[CAPTURED_BY_HOST_FIELD]\n  const captured = Array.isArray(raw)\n    ? raw.map((id) => String(id ?? '').trim()).filter(Boolean)\n    : []\n  for (const hostId of captured) {\n    const group = consentGroupForHost(org, hostId)\n    if (facetKeys.includes(group.groupId)) return group\n  }\n  for (const key of facetKeys) {\n    const declared = readConsentGroups(org)[key]\n    if (declared) {\n      return {\n        hostId: declared.hostIds[0],\n        groupId: key,\n        name: declared.name,\n        hostIds: [...declared.hostIds],\n        declared: true,\n      }\n    }\n    return soloConsentGroup(key)\n  }\n  if (captured.length) return consentGroupForHost(org, captured[0])\n  return NO_HOLDER_GROUP\n}"],"names":["CONTACT_FACETS_FIELD","CAPTURED_BY_HOST_FIELD","consentGroupForHost","readConsentGroups","soloConsentGroup","NO_HOLDER_GROUP","Object","freeze","hostId","groupId","name","hostIds","declared","contactPrimaryGroup","row","org","record","facets","facetKeys","Array","isArray","keys","raw","captured","map","id","String","trim","filter","Boolean","group","includes","key","length"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;CAYC,GAED,SAASA,oBAAoB,QAAQ,gBAAY;AACjD,SAASC,sBAAsB,QAAQ,yBAAqB;AAC5D,SAEEC,mBAAmB,EACnBC,iBAAiB,EACjBC,gBAAgB,QACX,sBAAkB;AAEzB;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,kBAAgCC,OAAOC,MAAM,CAAC;IACzDC,QAAQ;IACRC,SAAS;IACTC,MAAM;IACNC,SAAS,EAAE;IACXC,UAAU;AACZ,GAAkB;AAElB;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC,oBACdC,GAA+C,EAC/CC,GAA+C;IAE/C,MAAMC,SAASF,cAAAA,MAAO,CAAC;IACvB,MAAMG,SAASD,MAAM,CAAChB,qBAAqB;IAC3C,MAAMkB,YACJD,UAAU,OAAOA,WAAW,YAAY,CAACE,MAAMC,OAAO,CAACH,UACnDX,OAAOe,IAAI,CAACJ,UACZ,EAAE;IACR,MAAMK,MAAMN,MAAM,CAACf,uBAAuB;IAC1C,MAAMsB,WAAWJ,MAAMC,OAAO,CAACE,OAC3BA,IAAIE,GAAG,CAAC,CAACC,KAAOC,OAAOD,aAAAA,KAAM,IAAIE,IAAI,IAAIC,MAAM,CAACC,WAChD,EAAE;IACN,KAAK,MAAMrB,UAAUe,SAAU;QAC7B,MAAMO,QAAQ5B,oBAAoBa,KAAKP;QACvC,IAAIU,UAAUa,QAAQ,CAACD,MAAMrB,OAAO,GAAG,OAAOqB;IAChD;IACA,KAAK,MAAME,OAAOd,UAAW;QAC3B,MAAMN,WAAWT,kBAAkBY,IAAI,CAACiB,IAAI;QAC5C,IAAIpB,UAAU;YACZ,OAAO;gBACLJ,QAAQI,SAASD,OAAO,CAAC,EAAE;gBAC3BF,SAASuB;gBACTtB,MAAME,SAASF,IAAI;gBACnBC,SAAS;uBAAIC,SAASD,OAAO;iBAAC;gBAC9BC,UAAU;YACZ;QACF;QACA,OAAOR,iBAAiB4B;IAC1B;IACA,IAAIT,SAASU,MAAM,EAAE,OAAO/B,oBAAoBa,KAAKQ,QAAQ,CAAC,EAAE;IAChE,OAAOlB;AACT"}

package/src/lib/app-utils/contact-merge.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @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.
+ */
+/**
+ * MERGING TWO CONTACT DOCUMENTS INTO ONE (AGL-2625) — the pure half.
+ *
+ * Contacts are keyed by email, so exact duplicates cannot exist; one human
+ * with `jane@acme.com` and `jane@gmail.com` is two documents, with tags,
+ * deals, tasks and a timeline split between them. A merge folds the second
+ * into the first: the SURVIVOR keeps its address as the identity, the MERGED
+ * record's address becomes an alternate on it, and every field is combined
+ * by one rule the dialog can show before the write happens.
+ *
+ * ## The rule
+ *
+ *  - A scalar — a name, a phone, a title, a stage, an owner — is the
+ *    survivor's where the survivor has one, and fills from the merged record
+ *    where the survivor is empty. Nothing the survivor holds is overwritten.
+ *  - A list — tags, campaign filings, the timeline, the sites that captured
+ *    the person, the forms, the companies — is the UNION, deduplicated and
+ *    bounded where the write paths bound it.
+ *  - A figure that counts something — orders, lifetime value, refunds — is
+ *    the SUM: two records of one person's purchases are one person's
+ *    purchases. A "first" is the earlier, a "last" is the later.
+ *  - Notes are appended, survivor first: a note is a list of sentences, and
+ *    dropping the merged record's would be the one silent loss in a merge
+ *    that is otherwise lossless.
+ *  - A recorded REFUSAL of marketing mail on either record stands on the
+ *    survivor. The merge asserts the two are one person, and that person
+ *    said no.
+ *
+ * Applied per holder: each group's facet on the merged record is folded
+ * into the same group's facet on the survivor, and a group only the merged
+ * record had comes across whole. No holder's records reach another holder's
+ * facet, which is the guarantee the facet shape exists for.
+ *
+ * ## Why this is a plan and not a write
+ *
+ * The console shows the two records side by side and says which value wins
+ * before anything is committed; the server performs the write. Both read
+ * this function, so the preview cannot show one outcome and the write land
+ * another. The plan is plain values — no sentinels — so it can be rendered,
+ * and it is shaped for a merge-`set`, which deep-merges the facet map one
+ * holder at a time and replaces an array whole: exactly the two behaviors
+ * the rule above needs.
+ */
+import { type ContactInteraction } from './contacts';
+export interface ContactMergePlan {
+    /**
+     * What the survivor becomes, as a merge-`set` payload: every derived
+     * field with its full value, and only the groups the merged record held
+     * under `facets`. Plain values throughout — the writer adds its own
+     * `updatedAt`.
+     */
+    survivor: Record<string, unknown>;
+    /** Every address the survivor answers to afterwards, primary first. */
+    emails: string[];
+    /** The merged record's addresses — what its leads and index entries are keyed by. */
+    mergedEmails: string[];
+    /**
+     * The companies that lose a contact: those BOTH records were filed under,
+     * which counted two people and now count one. A company only one record
+     * named keeps its count — the survivor still names it.
+     */
+    companyCounts: Array<{
+        companyId: string;
+        delta: -1;
+    }>;
+    /** The union of both records' scope tokens — who may read the survivor. */
+    visibleTo: string[];
+}
+type Doc = Record<string, unknown>;
+/**
+ * Both timelines as one: deduplicated by event, newest first, and capped
+ * the way every capture caps it — so a merge of two full timelines keeps
+ * the fifty most recent visits rather than growing the document past what
+ * a capture may write.
+ */
+export declare function mergeInteractions(survivor: readonly ContactInteraction[] | undefined, merged: readonly ContactInteraction[] | undefined): ContactInteraction[];
+/**
+ * One holder's facet after the merge.
+ *
+ * `survivor` is that holder's facet on the surviving record — possibly
+ * absent, when only the merged record was held by this group — and `merged`
+ * the same holder's facet on the record being folded in.
+ */
+export declare function mergeContactFacet(survivor: Doc | undefined, merged: Doc | undefined): Doc;
+/**
+ * The plan for folding `merged` into `survivor`.
+ *
+ * Both are the stored documents as read. The survivor's `email` is the
+ * identity that stands; the merged record's becomes an alternate.
+ */
+export declare function planContactMerge(survivor: Doc, merged: Doc): ContactMergePlan;
+/** Where a previewed value comes from. */
+export type ContactMergeSource = 'survivor' | 'merged' | 'both' | 'none';
+/** One line of the side-by-side the dialog shows. */
+export interface ContactMergePreviewRow {
+    key: string;
+    label: string;
+    /** The surviving record's value, as text. */
+    survivor: string;
+    /** The merged record's value, as text. */
+    merged: string;
+    /** What the survivor carries afterwards. */
+    result: string;
+    from: ContactMergeSource;
+}
+export interface ContactMergePreviewOptions {
+    /** The owner's display name for a uid; the uid itself when absent. */
+    memberName?: (uid: string) => string;
+}
+/**
+ * The merge as the viewing group would see it, field by field.
+ *
+ * Reads through ONE group's facet, the way the record page does, so a
+ * holder previewing a merge sees its own values and never another holder's.
+ * Every row carries the survivor's value, the merged record's, and the
+ * result the plan would write, so the dialog is a rendering and not a second
+ * opinion.
+ */
+export declare function contactMergePreview(survivor: Doc, merged: Doc, groupId: string, options?: ContactMergePreviewOptions): ContactMergePreviewRow[];
+export {};