@aglyn/tenant-data-admin 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/upsert-contact.d.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import { type ConsentGroup, type ContactFacet, type ContactInteraction, type ContactLifecycleStage, type ContactSource } from '@aglyn/aglyn/server';
-import { type ResolvedCampaignTouch } from './campaign-conversion-attribution';
+import { type PluginConversionTouch } from '@aglyn/aglyn/plugin-manager/plugin-conversion-credit';
 import { type MarketingConsentSource } from '@aglyn/aglyn/app-utils/marketing-consent';
 import { getOrgForHost } from './organizations';
 /**
@@ -53,7 +53,7 @@ export type UpsertHostContactVerdict = {
  * a field the facet grows is a field this option may carry the moment the
  * pick names it, and one it does not name is refused at compile time.
  */
-export type UpsertHostContactFacet = Partial<Pick<ContactFacet, 'phone' | 'jobTitle' | 'leadSource' | 'companyId' | 'companyName' | 'address' | 'ownerUid' | 'lifecycleStage' | 'custom'>>;
+export type UpsertHostContactFacet = Partial<Pick<ContactFacet, 'phone' | 'jobTitle' | 'leadSource' | 'companyId' | 'companyName' | 'address' | 'ownerUid' | 'lifecycleStage' | 'custom' | 'salutation' | 'firstName' | 'lastName' | 'department' | 'mobilePhone' | 'homePhone' | 'otherPhone' | 'fax' | 'birthdate' | 'assistantName' | 'assistantPhone' | 'otherAddress' | 'doNotCall'>>;
 /**
  * The profile fields a door may hand this function (AGL-2596): the parts of
  * a person's record that no capture surface collects — the console's create
@@ -82,7 +82,7 @@ export type ContactProfileInput = UpsertHostContactFacet;
  * Handed to {@link UpsertHostContactOptions.onCreated} once, on the create
  * branch only. The merge branch is a visit by somebody the org already held,
  * which is another interaction and not a new contact — the same line
- * `campaignTouch` draws for attribution. Scalars and one string array, so
+ * `conversionTouch` draws for attribution. Scalars and one string array, so
  * the runtime can flatten it into an event payload without inventing keys.
  */
 export interface HostContactCreated {
@@ -184,17 +184,19 @@ export interface UpsertHostContactOptions {
      *
      * Absent everywhere today, because no order document carries a currency and
      * every checkout door writes `currency: 'usd'` onto the Stripe line items.
-     * `attributeOrderToEmail` defaults it on that basis and says so. The field
+     * The plugin that credits orders defaults it on that basis and says so. The field
      * exists so a door that ever charges in something else can pass it, and the
      * campaign revenue report keeps it in its own bucket rather than adding it
      * to the dollars.
      */
     purchaseCurrency?: string;
     /**
-     * The campaign this person came from, already resolved by the door.
+     * Where this person arrived from, already resolved by the door through the
+     * plugin that credits outcomes (`plugin-conversion-credit`), and opaque
+     * here.
      *
      * ⛔ The ORDER path passes none, and must not start. An order already has
-     * its own join one branch below — `attributeOrderToEmail`, keyed on the
+     * its own credit one branch below — `creditOrderConversion`, keyed on the
      * order id — and a second record for the same sale would be the same money
      * counted twice under two rules. This is the door for the moments an order
      * does NOT cover: a form submission, a membership sign-up, a booking, a
@@ -203,11 +205,11 @@ export interface UpsertHostContactOptions {
      * Resolved rather than raw, for the reason `addHostLead` states: one
      * visitor action reaches several writers and the touch lookup is paid once.
      */
-    campaignTouch?: ResolvedCampaignTouch | null;
+    conversionTouch?: PluginConversionTouch | null;
     /**
      * The campaigns the CAPTURE SURFACE is filed under.
      *
-     * ⚠️ A different fact from {@link campaignTouch} beside it, and the two must
+     * ⚠️ A different fact from {@link conversionTouch} beside it, and the two must
      * never be folded together. A touch is where the visitor came FROM — an ad,
      * a link, a browser-supplied label resolved through an allowlist. This is
      * which campaigns the merchant put the form itself in, which is the
@@ -233,6 +235,13 @@ export interface UpsertHostContactOptions {
      * phone and nothing else does not blank the title somebody typed.
      */
     facet?: UpsertHostContactFacet;
+    /**
+     * Profile fields written only where THIS holder's facet has none
+     * (AGL-3493) — what a door learned in passing, like the phone a booking
+     * form asked for, which must not replace a number somebody typed on the
+     * record. A key {@link facet} also carries is `facet`'s to write.
+     */
+    facetFill?: Pick<UpsertHostContactFacet, 'phone'>;
     /**
      * The EARLIEST stage that describes what this capture was (AGL-2612).
      *

package/src/lib/server/upsert-contact.js

@@ -14,14 +14,13 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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 { CAPTURED_BY_HOST_FIELD, checkCrmRecordsQuota, consentGroupScope, CONTACT_FACETS_FIELD, CONTACT_FORM_IDS_CAP, CONTACT_FORM_IDS_FIELD, marketingConsentFieldsForGroup, mergeContactInteraction, normalizeContainerIds, readContactFacet, normalizeContactEmail, ORG_SCOPE_TOKEN } from "@aglyn/aglyn/server";
+ */ import { CAPTURED_BY_HOST_FIELD, checkCrmRecordsQuota, composeContactName, CONTACT_EXTRA_PHONE_FIELDS, consentGroupScope, CONTACT_FACETS_FIELD, CONTACT_FORM_IDS_CAP, CONTACT_FORM_IDS_FIELD, marketingConsentFieldsForGroup, mergeContactInteraction, normalizeContactBirthdate, normalizeContainerIds, readContactFacet, normalizeContactEmail, ORG_SCOPE_TOKEN } from "@aglyn/aglyn/server";
 import { FieldValue } from "firebase-admin/firestore";
 import { firebaseAdmin } from "./firebase-admin.js";
 import { countCrmRecords, restampCrmListFieldsAt } from "./crm-records.js";
-import { attributeOrderToEmail } from "./email-revenue-attribution.js";
 import { hostErasedEmails, hostRefusesCaptureForErasure } from "./email-suppression.js";
 import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
-import { attributeCampaignConversion } from "./campaign-conversion-attribution.js";
+import { creditConversion, creditOrderConversion } from "@aglyn/aglyn/plugin-manager/plugin-conversion-credit";
 import { nameSearchFields } from "@aglyn/aglyn/app-utils/name-search";
 import { consentGroupForGrant } from "@aglyn/aglyn/app-utils/consent-groups";
 import { declineMarketingConsentFields, MARKETING_CONSENT_SOURCE_FIELD } from "@aglyn/aglyn/app-utils/marketing-consent";
@@ -48,6 +47,44 @@ import { consentGroupForSite, getOrgForHost, orgDataCollectionForHost } from "./
  */ function storableProfile(input) {
     if (!input) return {};
     const out = {};
+    /*
+   * Salesforce's standard contact fields (AGL-3515), under the same rule as
+   * the rest: given keys only, each normalized, an unusable value dropped.
+   * The salutation is judged against the org's list by the door that took
+   * it and held here to the label's shape, like the lead source. Do not
+   * call is written only as `true`: a door may learn that a person asked
+   * not to be phoned, and no capture is the person taking it back.
+   */ if (typeof input.salutation === 'string') {
+        const salutation = input.salutation.trim().replace(/\s+/g, ' ').slice(0, 120);
+        if (salutation) out.salutation = salutation;
+    }
+    if (input.firstName !== undefined) {
+        const firstName = composeContactName(input.firstName, '');
+        if (firstName) out.firstName = firstName;
+    }
+    if (input.lastName !== undefined) {
+        const lastName = composeContactName('', input.lastName);
+        if (lastName) out.lastName = lastName;
+    }
+    for (const key of [
+        'department',
+        'assistantName'
+    ]){
+        if (typeof input[key] !== 'string') continue;
+        const value = input[key].trim().slice(0, 120);
+        if (value) out[key] = value;
+    }
+    for (const key of CONTACT_EXTRA_PHONE_FIELDS){
+        if (input[key] === undefined) continue;
+        const phone = normalizePhone(input[key]);
+        if (phone) out[key] = phone;
+    }
+    if (input.birthdate !== undefined) {
+        const birthdate = normalizeContactBirthdate(input.birthdate);
+        if (birthdate) out.birthdate = birthdate;
+    }
+    if (input.otherAddress !== undefined) out.otherAddress = normalizeAddress(input.otherAddress);
+    if (input.doNotCall === true) out.doNotCall = true;
     if (input.phone !== undefined) {
         const phone = normalizePhone(input.phone);
         if (phone) out.phone = phone;
@@ -96,6 +133,17 @@ import { consentGroupForSite, getOrgForHost, orgDataCollectionForHost } from "./
     }
     return out;
 }
+/**
+ * A door's {@link UpsertHostContactOptions.facetFill}, folded into the
+ * profile it is about to write: each field only where neither the door's
+ * own profile nor the holder's stored facet holds one.
+ */ function fillProfile(profile, fill, stored) {
+    var _ref;
+    const given = storableProfile(fill);
+    if (given.phone && !profile.phone && !String((_ref = stored == null ? void 0 : stored.phone) != null ? _ref : '').trim()) {
+        profile.phone = given.phone;
+    }
+}
 /**
  * The org's companies collection, beside its contacts one.
  *
@@ -148,7 +196,7 @@ export async function upsertHostContact(options) {
      * contact capture below it.
      *=========================================*/ if (options.source === 'order' && options.interaction.refId) {
             var _options_purchaseCents, _options_interaction_atMs1;
-            await attributeOrderToEmail(_extends({
+            await creditOrderConversion(_extends({
                 hostId: options.hostId,
                 orderId: String(options.interaction.refId),
                 email,
@@ -249,7 +297,7 @@ export async function upsertHostContact(options) {
      *=========================================*/ const prefetched = batch == null ? void 0 : batch.claim(email);
         const docSnapshot = prefetched !== undefined ? prefetched : await findContactByEmail(contactsRef, email);
         if (docSnapshot) {
-            var _facet_name, _profile_lifecycleStage, _ref5;
+            var _facet_name, _profile_firstName, _profile_lastName, _profile_lifecycleStage, _ref5;
             var _contactsRef_parent1;
             /*
        * MERGED INTO THIS GROUP'S FACET, not into the top of the document.
@@ -283,6 +331,15 @@ export async function upsertHostContact(options) {
        * named no stage and found none leaves the key absent, which reads as
        * "no stage" rather than as a stage somebody picked.
        */ const profile = storableProfile(options.facet);
+            fillProfile(profile, options.facetFill, facet);
+            /*
+       * THE NAME FOLLOWS THE FIRST AND LAST NAMES (AGL-3515): a door that
+       * carried either writes the holder's name as their composition, over
+       * the name the facet held — the parts are the newer, structured
+       * statement of the same thing. A door that carried neither leaves the
+       * name to the rule above, where the existing name wins.
+       */ const composedName = profile.firstName !== undefined || profile.lastName !== undefined ? composeContactName((_profile_firstName = profile.firstName) != null ? _profile_firstName : facet.firstName, (_profile_lastName = profile.lastName) != null ? _profile_lastName : facet.lastName) : '';
+            const facetName = composedName || merged.name;
             const advanced = advanceContactLifecycleStage((_profile_lifecycleStage = profile.lifecycleStage) != null ? _profile_lifecycleStage : facet.lifecycleStage, options.initialLifecycleStage);
             if (advanced) profile.lifecycleStage = advanced;
             /*
@@ -308,7 +365,7 @@ export async function upsertHostContact(options) {
        * merge-set, and the counts settle after it.
        */ const link = profile.companyId !== undefined ? planContactCompanyLink(readContactCompanyLink(docSnapshot.data(), group.groupId), profile.companyId) : null;
             const mirror = link ? contactCompanyMirrorValue(link) : undefined;
-            await docSnapshot.ref.set(_extends({}, merged.name ? nameSearchFields(merged.name) : {}, profile.phone ? {
+            await docSnapshot.ref.set(_extends({}, facetName ? nameSearchFields(facetName) : {}, profile.phone ? {
                 phone: profile.phone
             } : {}, profile.companyName ? {
                 companyName: profile.companyName
@@ -325,8 +382,8 @@ export async function upsertHostContact(options) {
                     [group.groupId]: _extends({
                         sources: merged.sources,
                         interactions: merged.interactions
-                    }, merged.name ? {
-                        name: merged.name
+                    }, facetName ? {
+                        name: facetName
                     } : {}, campaignIds.length ? {
                         campaignIds: FieldValue.arrayUnion(...campaignIds)
                     } : {}, tags.length ? {
@@ -437,9 +494,18 @@ export async function upsertHostContact(options) {
      * a door that named one writes. A `null` address is dropped rather than
      * written: there is nothing on a new document for it to clear.
      */ const profile = storableProfile(options.facet);
+        // A new person holds nothing yet, so the fill is written whole.
+        fillProfile(profile, options.facetFill, null);
         const advanced = advanceContactLifecycleStage(profile.lifecycleStage, options.initialLifecycleStage);
         if (advanced) profile.lifecycleStage = advanced;
         if (profile.address === null) delete profile.address;
+        if (profile.otherAddress === null) delete profile.otherAddress;
+        // The holder's name is the first and last names' when the door gave
+        // either (AGL-3515); the canonical name is the one the door gave, or
+        // that composition for a door that gave only the parts.
+        const composedName = composeContactName(profile.firstName, profile.lastName);
+        const canonicalName = (options.name || composedName).slice(0, 120);
+        const holderName = (composedName || options.name || '').slice(0, 120);
         const record = _extends({
             hostId: options.hostId,
             /*
@@ -474,7 +540,7 @@ export async function upsertHostContact(options) {
                 ORG_SCOPE_TOKEN
             ] : consentGroupScope(group),
             email
-        }, options.name ? nameSearchFields(options.name.slice(0, 120)) : {}, profile.phone ? {
+        }, canonicalName ? nameSearchFields(canonicalName) : {}, profile.phone ? {
             phone: profile.phone
         } : {}, profile.companyName ? {
             companyName: profile.companyName
@@ -497,8 +563,8 @@ export async function upsertHostContact(options) {
                     tags
                 }, campaignIds.length ? {
                     campaignIds
-                } : {}, customFacet, options.name ? {
-                    name: options.name.slice(0, 120)
+                } : {}, customFacet, holderName ? {
+                    name: holderName
                 } : {}, profile, options.purchaseCents ? {
                     ltvCents: options.purchaseCents,
                     ordersCount: 1,
@@ -542,12 +608,12 @@ export async function upsertHostContact(options) {
      * is the same rule `addHostLead` applies — an interaction appended to
      * somebody the site already held is another visit, not a new person, and
      * crediting it would let the most recent campaign re-earn the whole list.
-     */ if (options.campaignTouch) {
-            await attributeCampaignConversion({
+     */ if (options.conversionTouch) {
+            await creditConversion({
                 hostId: options.hostId,
                 kind: 'contact',
                 refId: created.id,
-                touch: options.campaignTouch,
+                touch: options.conversionTouch,
                 convertedAtMs: interaction.atMs
             });
         }
@@ -562,8 +628,8 @@ export async function upsertHostContact(options) {
                 contactId: created.id,
                 hostId: options.hostId,
                 email
-            }, options.name ? {
-                name: options.name.slice(0, 120)
+            }, holderName ? {
+                name: holderName
             } : {}, {
                 source: options.source,
                 campaignIds