@aglyn/plugins-crm 1.0.0-beta.221 → 1.0.0-beta.223

package/src/lib/server/api-v1/crm-deals.js

@@ -56,11 +56,36 @@ import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_wi
  * the client; the last sum stays until it is retyped. Changing the currency
  * of a deal with lines needs the lines resent in that currency, because
  * their sum is one number in one unit.
- */ import { CRM_COLLECTIONS, CRM_MEDIA_IDS_MAX, createResourceUid, crmNewRecordListFields, dealStageById, lineItemsTotalCents, normalizeCrmMediaIds, readDealLineItems } from "@aglyn/aglyn/server";
+ *
+ * ## Salesforce's Opportunity fields (AGL-3516)
+ *
+ * `type` and `leadSource` are judged against the org's `opportunityType`
+ * and `leadSource` picklists, as every door judges them: an active value
+ * is stored as the list spells it, a deal's own current value is kept, and
+ * anything else is a `400` naming the values allowed. A create with no
+ * `type` takes the list's default; `leadSource` is never defaulted.
+ * `forecastCategory` is one of a FIXED set. Every stage move stamps the new
+ * stage's `forecastCategory` and clears the `probability` override — a
+ * body that sets either beside the move wins. `campaignId` names one of the
+ * org's live campaigns.
+ *
+ * ## Contact roles (AGL-3521)
+ *
+ * `contactRoles` is the whole list of the deal's contacts — `{ contactId,
+ * role, primary }` — replaced as sent. Each contact must exist, none twice,
+ * at most one Primary, and each `role` is judged against the org's
+ * `opportunityContactRole` list (a contact's current role kept). The
+ * Primary IS `contactId`: a body that sends both must agree, and a body
+ * that sends `contactId` alone makes that contact Primary — added with no
+ * role when the deal did not name them — so an integration written before
+ * roles keeps meaning what it meant.
+ */ import { CRM_COLLECTIONS, CRM_MEDIA_IDS_MAX, createResourceUid, CRM_FORECAST_CATEGORIES, crmListFieldsTouched, crmNewRecordListFields, DEAL_CONTACT_ROLES_MAX, DEAL_NEXT_STEP_MAX, dealContactRoleFields, dealContactRolesOf, dealContactRolesWithPrimary, dealPrimaryContactId, dealStageById, judgeDealContactRoles, dealStageMoveFields, lineItemsTotalCents, normalizeCrmMediaIds, readDealLineItems } from "@aglyn/aglyn/server";
 import { apiJson, ApiErrors, restampCrmListFieldsAt } from "@aglyn/tenant-data-admin";
-import { Timestamp } from "firebase-admin/firestore";
+import { FieldValue, Timestamp } from "firebase-admin/firestore";
 import { claimWrite, readJsonBody, requireScope } from "@aglyn/tenant-data-admin/server/api-v1-kit";
+import { readOrgContainers } from "@aglyn/tenant-data-admin/server/org-containers";
 import { floorContactLifecycleStage } from "../contact-lifecycle-floor.js";
+import { readCrmPicklist, resolveCrmPicklistWrite } from "../read-picklist.js";
 import { orderedStages, resolvePipeline } from "./crm-pipelines.js";
 import { CRM_TEXT_MAX, CRM_TITLE_MAX, createPayload, crmCollection, crmCreateStamp, crmCustomUpdate, crmCustomView, crmRecordsBandRefusal, crmRefErrors, crmTimes, crmValidationFailed, isoFromMs, listCrm, memberError, parseIsoInstant, readChoice, readCrmCustomBody, readCrmSite, readEqualityFilters, readOptionalText, readRefId, refuseUnknownKeys, updatePayload } from "./crm-shared.js";
 const DEAL_STATUSES = [
@@ -79,7 +104,7 @@ const DEAL_STATUSES = [
     };
 }
 /** The deal object as published. Every writable field appears here. */ function dealView(doc) {
-    var _doc_data, _data_title, _data_pipelineId, _data_stageId, _data_status, _data_currency, _data_ownerUid, _data_contactId, _data_companyId, _data_lostReason, _data_notes, _data_hostId;
+    var _doc_data, _data_title, _data_pipelineId, _data_stageId, _data_status, _data_currency, _data_ownerUid, _data_contactId, _data_companyId, _data_lostReason, _data_notes, _data_type, _data_leadSource, _data_nextStep, _data_forecastCategory, _data_campaignId, _data_hostId;
     const data = (_doc_data = doc.data()) != null ? _doc_data : {};
     return _extends({
         id: doc.id,
@@ -98,9 +123,26 @@ const DEAL_STATUSES = [
         stageChangedAt: isoFromMs(data.stageChangedAtMs),
         ownerUid: (_data_ownerUid = data.ownerUid) != null ? _data_ownerUid : null,
         contactId: (_data_contactId = data.contactId) != null ? _data_contactId : null,
+        // Every contact on the deal and the part each plays (AGL-3521); the
+        // Primary is `contactId`.
+        contactRoles: dealContactRolesOf(data).map((row)=>{
+            var _row_role;
+            return {
+                contactId: row.contactId,
+                role: (_row_role = row.role) != null ? _row_role : null,
+                primary: row.primary
+            };
+        }),
         companyId: (_data_companyId = data.companyId) != null ? _data_companyId : null,
         lostReason: (_data_lostReason = data.lostReason) != null ? _data_lostReason : null,
         notes: (_data_notes = data.notes) != null ? _data_notes : null,
+        // Salesforce's Opportunity fields (AGL-3516).
+        type: (_data_type = data.type) != null ? _data_type : null,
+        leadSource: (_data_leadSource = data.leadSource) != null ? _data_leadSource : null,
+        nextStep: (_data_nextStep = data.nextStep) != null ? _data_nextStep : null,
+        probability: typeof data.probability === 'number' ? data.probability : null,
+        forecastCategory: (_data_forecastCategory = data.forecastCategory) != null ? _data_forecastCategory : null,
+        campaignId: (_data_campaignId = data.campaignId) != null ? _data_campaignId : null,
         // The org's deal custom fields, keyed by field key (AGL-2661).
         custom: crmCustomView(data),
         // When the earliest open task against the deal is due — see
@@ -124,8 +166,80 @@ const DEAL_WRITABLE = new Set([
     'lostReason',
     'notes',
     'custom',
-    'mediaIds'
+    'mediaIds',
+    'type',
+    'leadSource',
+    'nextStep',
+    'probability',
+    'forecastCategory',
+    'campaignId',
+    'contactRoles'
+]);
+/** The keys one contact role takes. */ const CONTACT_ROLE_KEYS = new Set([
+    'contactId',
+    'role',
+    'primary'
 ]);
+/**
+ * `contactRoles` as sent, shape-checked: a list of at most
+ * {@link DEAL_CONTACT_ROLES_MAX} entries, each naming a contact once, and
+ * at most one of them Primary. `null` is the empty list.
+ */ function readContactRolesBody(raw, errors) {
+    if (raw === undefined) return undefined;
+    if (raw === null) return [];
+    if (!Array.isArray(raw)) {
+        errors.contactRoles = 'Must be a list of { contactId, role, primary }';
+        return undefined;
+    }
+    if (raw.length > DEAL_CONTACT_ROLES_MAX) {
+        errors.contactRoles = `At most ${DEAL_CONTACT_ROLES_MAX} contacts per deal`;
+        return undefined;
+    }
+    const seen = new Set();
+    let primaries = 0;
+    for (const [at, entry] of raw.entries()){
+        const row = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : null;
+        const contactId = typeof (row == null ? void 0 : row['contactId']) === 'string' ? row['contactId'].trim() : '';
+        const unknownKey = row ? Object.keys(row).find((key)=>!CONTACT_ROLE_KEYS.has(key)) : undefined;
+        if (!row || unknownKey) {
+            errors.contactRoles = unknownKey ? `Entry ${at}: unknown field ${unknownKey}` : `Entry ${at}: must be { contactId, role, primary }`;
+            return undefined;
+        }
+        if (!contactId || contactId.length > 200 || contactId.includes('/')) {
+            errors.contactRoles = `Entry ${at}: contactId must be a contact id`;
+            return undefined;
+        }
+        if (seen.has(contactId)) {
+            errors.contactRoles = `Entry ${at}: ${contactId} is on the list twice`;
+            return undefined;
+        }
+        seen.add(contactId);
+        if (row['role'] !== undefined && row['role'] !== null && typeof row['role'] !== 'string') {
+            errors.contactRoles = `Entry ${at}: role must be a contact role, or null`;
+            return undefined;
+        }
+        if (row['primary'] !== undefined && typeof row['primary'] !== 'boolean') {
+            errors.contactRoles = `Entry ${at}: primary must be true or false`;
+            return undefined;
+        }
+        if (row['primary'] === true) primaries += 1;
+    }
+    if (primaries > 1) {
+        errors.contactRoles = 'At most one contact may be Primary';
+        return undefined;
+    }
+    return raw.map((entry)=>{
+        const row = entry;
+        const role = typeof row['role'] === 'string' ? row['role'].trim() : '';
+        return _extends({
+            contactId: String(row['contactId']).trim()
+        }, role ? {
+            role
+        } : {}, {
+            primary: row['primary'] === true
+        });
+    });
+}
 /**
  * The writable half of a deal, validated. `pipelineId` is accepted on a
  * create only: a deal's stages are its pipeline's, and moving one between
@@ -219,6 +333,36 @@ const DEAL_WRITABLE = new Set([
     if (lostReason !== undefined) values.lostReason = lostReason;
     const notes = readOptionalText(body, 'notes', CRM_TEXT_MAX, errors);
     if (notes !== undefined) values.notes = notes;
+    for (const key of [
+        'type',
+        'leadSource'
+    ]){
+        const label = readOptionalText(body, key, CRM_TITLE_MAX, errors);
+        if (label !== undefined) values[key] = label;
+    }
+    const nextStep = readOptionalText(body, 'nextStep', DEAL_NEXT_STEP_MAX, errors);
+    if (nextStep !== undefined) values.nextStep = nextStep;
+    if (body.probability !== undefined) {
+        if (body.probability === null) {
+            values.probability = null;
+        } else if (typeof body.probability !== 'number' || !Number.isInteger(body.probability) || body.probability < 0 || body.probability > 100) {
+            errors.probability = 'Must be a whole number from 0 to 100, or null for the stage’s';
+        } else {
+            values.probability = body.probability;
+        }
+    }
+    const forecastCategory = readChoice(body, 'forecastCategory', CRM_FORECAST_CATEGORIES, errors);
+    if (forecastCategory) values.forecastCategory = forecastCategory;
+    const campaignId = readRefId(body, 'campaignId', errors);
+    if (campaignId !== undefined) values.campaignId = campaignId;
+    const contactRoles = readContactRolesBody(body.contactRoles, errors);
+    if (contactRoles !== undefined) {
+        values.contactRoles = contactRoles;
+        // The Primary IS `contactId`, so a body naming both says one thing twice.
+        if (values.contactId !== undefined && values.contactId !== dealPrimaryContactId(contactRoles)) {
+            errors.contactId = 'Must name the Primary in contactRoles, or be left out';
+        }
+    }
     // `custom` is shape-checked here and judged against the org's
     // definitions by the writers, which is where the read is paid.
     if (body.custom !== undefined) {
@@ -320,24 +464,116 @@ const DEAL_WRITABLE = new Set([
         console.error('[api-v1] deals: the customer floor failed', contactId, error);
     }
 }
-/** The fields a stage move writes, beside the stage itself. */ function stageMove(stage, nowMs) {
-    return {
+/**
+ * The fields a stage move writes, beside the stage itself — and the new
+ * stage's forecast category with the probability override cleared
+ * (`dealStageMoveFields`, AGL-3516).
+ */ function stageMove(stage, nowMs) {
+    return _extends({
         stageId: stage.id,
         status: stage.kind,
         stageChangedAtMs: nowMs,
         closedAtMs: stage.kind === 'open' ? null : nowMs
-    };
+    }, dealStageMoveFields(stage));
 }
-/** The membership and reference checks a deal write makes, merged. */ async function dealRefErrors(ctx, values) {
-    var _values_contactId, _values_companyId;
-    const [owner, refs] = await Promise.all([
+/**
+ * The membership and reference checks a deal write makes, merged. A
+ * campaign is checked against the org's live campaigns, except the one the
+ * deal already names, which it keeps even once the campaign is retired.
+ */ async function dealRefErrors(ctx, values, stored) {
+    var _values_campaignId, _values_contactId, _values_companyId;
+    const campaignId = (_values_campaignId = values.campaignId) != null ? _values_campaignId : undefined;
+    const [owner, refs, campaign, roles] = await Promise.all([
         memberError(ctx, 'ownerUid', values.ownerUid),
         crmRefErrors(ctx, {
             contactId: (_values_contactId = values.contactId) != null ? _values_contactId : undefined,
             companyId: (_values_companyId = values.companyId) != null ? _values_companyId : undefined
-        })
+        }),
+        campaignId && campaignId !== (stored == null ? void 0 : stored.campaignId) ? readOrgContainers(ctx.firestore, 'campaign', ctx.orgId, [
+            campaignId
+        ]).then(([record])=>(record == null ? void 0 : record.live) ? {} : {
+                campaignId: 'No such campaign in this organization'
+            }) : Promise.resolve({}),
+        contactRoleRefErrors(ctx, values.contactRoles, stored)
     ]);
-    return _extends({}, owner, refs);
+    return _extends({}, owner, refs, campaign, roles);
+}
+/**
+ * Every contact a sent `contactRoles` adds to the deal must exist; one the
+ * deal already names is kept as it is, as a campaign is.
+ */ async function contactRoleRefErrors(ctx, roles, stored) {
+    const held = new Set(stored ? dealContactRolesOf(stored).map((row)=>row.contactId) : []);
+    const added = (roles != null ? roles : []).map((row)=>row.contactId).filter((id)=>!held.has(id));
+    if (!added.length) return {};
+    const contacts = ctx.firestore.collection('orgs').doc(ctx.orgId).collection('contacts');
+    const snapshots = await ctx.firestore.getAll(...added.map((id)=>contacts.doc(id)));
+    const missing = snapshots.find((snapshot)=>!snapshot.exists);
+    return missing ? {
+        contactRoles: `No such contact in this organization: ${missing.id}`
+    } : {};
+}
+/**
+ * What a write stores for the deal's contacts (AGL-3521): `contactRoles`
+ * judged and `contactId` beside its Primary when the body sent the list;
+ * when it sent `contactId` alone, the stored roles with that contact as the
+ * Primary. Nothing, when it sent neither.
+ */ async function dealContactRoleWrites(ctx, values, stored) {
+    const current = stored ? dealContactRolesOf(stored) : [];
+    if (values.contactRoles !== undefined) {
+        const judged = judgeDealContactRoles(await readCrmPicklist(ctx.firestore, ctx.orgId, 'opportunityContactRole'), values.contactRoles, current);
+        if (judged.ok === false) return {
+            errors: {
+                contactRoles: judged.error
+            }
+        };
+        return {
+            values: dealContactRoleFields(judged.roles)
+        };
+    }
+    if (values.contactId !== undefined) {
+        return {
+            values: dealContactRoleFields(dealContactRolesWithPrimary(current, values.contactId))
+        };
+    }
+    return {
+        values: {}
+    };
+}
+/**
+ * `type` and `leadSource` as the deal will store them, judged against the
+ * org's lists (AGL-3510's `resolveCrmPicklistWrite`): the values to write,
+ * or the refusals by field. Only a list the write touches is read — and the
+ * type list on every create, for its default.
+ */ async function dealPicklistWrites(ctx, values, stored) {
+    const created = stored === null;
+    const fields = [
+        {
+            key: 'type',
+            id: 'opportunityType',
+            defaulted: created
+        },
+        {
+            key: 'leadSource',
+            id: 'leadSource',
+            defaulted: false
+        }
+    ];
+    const written = {};
+    const errors = {};
+    for (const { key, id, defaulted } of fields){
+        if (values[key] === undefined && !defaulted) continue;
+        const judged = resolveCrmPicklistWrite(id, await readCrmPicklist(ctx.firestore, ctx.orgId, id), values[key], {
+            current: stored == null ? void 0 : stored[key],
+            created: defaulted
+        });
+        if (judged.ok === false) errors[key] = judged.error;
+        else if (judged.write !== undefined) written[key] = judged.write;
+    }
+    return Object.keys(errors).length ? {
+        errors
+    } : {
+        values: written
+    };
 }
 /**
  * `POST /v1/deals`. The pipeline is resolved AFTER the claim because
@@ -357,18 +593,25 @@ const DEAL_WRITABLE = new Set([
     const custom = await readCrmCustomBody(ctx, body, 'deal');
     if (custom && 'errors' in custom) return crmValidationFailed(ctx, 'deal', custom.errors);
     const customValues = custom && 'values' in custom ? custom.values : {};
+    // And against the org's picklists (AGL-3516), above the claim too.
+    const picklists = await dealPicklistWrites(ctx, parsed.values, null);
+    if ('errors' in picklists) return crmValidationFailed(ctx, 'deal', picklists.errors);
+    const roles = await dealContactRoleWrites(ctx, parsed.values, null);
+    if ('errors' in roles) return crmValidationFailed(ctx, 'deal', roles.errors);
     const collection = crmCollection(ctx, CRM_COLLECTIONS.deals);
     const claimed = await claimWrite(ctx, '*', request.headers.get('Idempotency-Key'), 'deals');
     if ('replay' in claimed) return claimed.replay;
     const { claim } = claimed;
     try {
         var _placed_stage;
-        const _parsed_values = parsed.values, { title, pipelineId, stageId, status, lineItems } = _parsed_values, rest = _object_without_properties_loose(_parsed_values, [
+        const _parsed_values = parsed.values, { title, pipelineId, stageId, status, lineItems, probability, forecastCategory } = _parsed_values, rest = _object_without_properties_loose(_parsed_values, [
             "title",
             "pipelineId",
             "stageId",
             "status",
-            "lineItems"
+            "lineItems",
+            "probability",
+            "forecastCategory"
         ]);
         const placedLines = placeLineItems({
             lineItems,
@@ -415,15 +658,20 @@ const DEAL_WRITABLE = new Set([
             title,
             titleLower: (title != null ? title : '').toLowerCase(),
             pipelineId: resolved.id
-        }, createPayload(_extends({}, rest, placedLines.fields, stageMove(stage, stamp.createdAt.toMillis()))), Object.keys(customValues).length ? {
+        }, createPayload(_extends({}, rest, picklists.values, roles.values, placedLines.fields, stageMove(stage, stamp.createdAt.toMillis()), probability !== undefined ? {
+            probability
+        } : {}, forecastCategory ? {
+            forecastCategory
+        } : {})), Object.keys(customValues).length ? {
             custom: createPayload(customValues)
         } : {}, stamp);
         // What the console's Deals list searches and filters by (AGL-3321).
         await collection.doc(id).create(_extends({}, record, crmNewRecordListFields('deals', record)));
         // A deal created won is a won deal: its contact is a customer from birth.
         if (stage.kind === 'won') {
+            var _roles_values_contactId;
             await floorWonDealContact(ctx, {
-                contactId: rest.contactId,
+                contactId: (_roles_values_contactId = roles.values.contactId) != null ? _roles_values_contactId : rest.contactId,
                 hostId: site.siteId
             });
         }
@@ -439,7 +687,7 @@ const DEAL_WRITABLE = new Set([
     }
 }
 /** `PATCH /v1/deals/{id}`. */ async function updateDeal(request, ctx, ref) {
-    var _stored_currency;
+    var _stored_currency, _stored_contactId;
     const body = await readJsonBody(request);
     const parsed = readDealInput(body, {
         partial: true
@@ -452,17 +700,23 @@ const DEAL_WRITABLE = new Set([
             headers: ctx.headers
         });
     }
-    const refErrors = await dealRefErrors(ctx, parsed.values);
+    const stored = snap.data();
+    const refErrors = await dealRefErrors(ctx, parsed.values, stored);
     if (Object.keys(refErrors).length) return crmValidationFailed(ctx, 'deal', refErrors);
     const custom = await readCrmCustomBody(ctx, body, 'deal');
     if (custom && 'errors' in custom) return crmValidationFailed(ctx, 'deal', custom.errors);
-    const _parsed_values = parsed.values, { title, stageId, status, lineItems } = _parsed_values, rest = _object_without_properties_loose(_parsed_values, [
+    const picklists = await dealPicklistWrites(ctx, parsed.values, stored);
+    if ('errors' in picklists) return crmValidationFailed(ctx, 'deal', picklists.errors);
+    const roles = await dealContactRoleWrites(ctx, parsed.values, stored);
+    if ('errors' in roles) return crmValidationFailed(ctx, 'deal', roles.errors);
+    const _parsed_values = parsed.values, { title, stageId, status, lineItems, probability, forecastCategory } = _parsed_values, rest = _object_without_properties_loose(_parsed_values, [
         "title",
         "stageId",
         "status",
-        "lineItems"
+        "lineItems",
+        "probability",
+        "forecastCategory"
     ]);
-    const stored = snap.data();
     const storedLines = Array.isArray(stored.lineItems) && stored.lineItems.length > 0;
     const keepsLines = storedLines && lineItems === undefined;
     if (keepsLines && rest.amountCents !== undefined) {
@@ -483,7 +737,9 @@ const DEAL_WRITABLE = new Set([
     const update = _extends({}, title !== undefined ? {
         title,
         titleLower: title.toLowerCase()
-    } : {}, updatePayload(_extends({}, rest, placedLines.fields)), custom && 'values' in custom ? crmCustomUpdate(custom.values) : {});
+    } : {}, updatePayload(_extends({}, rest, picklists.values, roles.values, placedLines.fields)), custom && 'values' in custom ? crmCustomUpdate(custom.values) : {}, roles.values.contactId !== undefined && roles.values.contactId !== ((_stored_contactId = stored.contactId) != null ? _stored_contactId : null) ? {
+        contactName: FieldValue.delete()
+    } : {});
     // The write's one instant: `updatedAt`, and the stage move if there is one,
     // so a deal closed at T reads updated at T.
     const now = Timestamp.now();
@@ -510,16 +766,21 @@ const DEAL_WRITABLE = new Set([
             won = placed.stage.kind === 'won' && current.status !== 'won';
         }
     }
+    // What the body set beside a stage move wins over what the stage stamps
+    // (AGL-3516); without a move, they are plain edits. `null` clears the
+    // override back to the stage's.
+    if (probability !== undefined) update['probability'] = probability;
+    if (forecastCategory) update['forecastCategory'] = forecastCategory;
     if (Object.keys(update).length > 0) {
         await ref.update(_extends({}, update, {
             updatedAt: now
         }));
-        // What the console's Deals list searches (AGL-3321).
-        if ('title' in update) await restampCrmListFieldsAt(ref, 'deals');
+        // What the console's Deals list searches and filters by (AGL-3321, AGL-3516).
+        if (crmListFieldsTouched('deals', update)) await restampCrmListFieldsAt(ref, 'deals');
     }
     if (won) {
         await floorWonDealContact(ctx, {
-            contactId: rest.contactId !== undefined ? rest.contactId : stored.contactId,
+            contactId: roles.values.contactId !== undefined ? roles.values.contactId : stored.contactId,
             hostId: stored.hostId
         });
     }
@@ -572,7 +833,11 @@ const DEAL_WRITABLE = new Set([
         'companyId',
         'pipelineId',
         'ownerUid',
-        'status'
+        'status',
+        'type',
+        'leadSource',
+        'forecastCategory',
+        'campaignId'
     ]);
     return listCrm(ctx, collection, url, filters, dealView);
 }