@aglyn/plugins-crm 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/server/api-v1/contacts-merge.js

@@ -0,0 +1,120 @@
+/**
+ * @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.
+ */ /**
+ * `POST /v1/contacts/{contactId}/merge` (AGL-2625) — fold another contact
+ * into this one.
+ *
+ * The contact in the path SURVIVES: it keeps its address as the identity,
+ * and the record named by `sourceContactId` is folded into it and deleted.
+ * `mergeContacts` (`../merge-contacts.ts`) is the whole of the work — the same
+ * function behind the console's `crm/contacts-merge` — so an integration
+ * and a person at the record page cannot merge two different ways.
+ *
+ * ## Idempotency
+ *
+ * Takes an `Idempotency-Key` with the delete's exact semantics, and for the
+ * delete's reason: a merge destroys a record, and a retry after a lost
+ * response must be able to tell "already merged" from "wrong id". Without a
+ * key, a second call finds no source contact and answers `404`, which is
+ * true and is the confusion the key removes.
+ *
+ * ## What it answers
+ *
+ * The surviving contact, read back the way `GET` reads it — the
+ * organization-wide profile, or one site's through `?consentSiteId=` —
+ * with its `alternateEmails` now carrying the merged address.
+ */ import { ApiErrors, apiJson } from "@aglyn/tenant-data-admin";
+import { apiKeyActorLabel } from "@aglyn/aglyn/app-utils/activity-presenter";
+import { claimWrite, readJsonBody } from "@aglyn/tenant-data-admin/server/api-v1-kit";
+import { mergeContacts } from "../merge-contacts.js";
+/** The key an integration names the record to fold in by. */ export const MERGE_SOURCE_FIELD = 'sourceContactId';
+export async function mergeContactRoute(request, ctx, survivorRef, view) {
+    const body = await readJsonBody(request);
+    const raw = body[MERGE_SOURCE_FIELD];
+    const sourceId = typeof raw === 'string' ? raw.trim() : '';
+    const fields = {};
+    if (raw === undefined) fields[MERGE_SOURCE_FIELD] = 'Required — the contact to merge into this one';
+    else if (!sourceId) fields[MERGE_SOURCE_FIELD] = 'Must be a contact id';
+    else if (sourceId === survivorRef.id) {
+        fields[MERGE_SOURCE_FIELD] = 'Must be a different contact from the one in the path';
+    }
+    for (const key of Object.keys(body)){
+        if (key !== MERGE_SOURCE_FIELD) fields[key] = 'Not accepted on a merge';
+    }
+    if (Object.keys(fields).length) {
+        return ApiErrors.badRequest({
+            message: 'Merge failed validation',
+            code: 'validation_failed',
+            fields,
+            headers: ctx.headers
+        });
+    }
+    const claimed = await claimWrite(ctx, '*', request.headers.get('Idempotency-Key'), 'contact-merges');
+    if ('replay' in claimed) return claimed.replay;
+    const { claim } = claimed;
+    try {
+        const result = await mergeContacts({
+            firestore: ctx.firestore,
+            orgRef: ctx.firestore.collection('orgs').doc(ctx.orgId),
+            survivorId: survivorRef.id,
+            mergedId: sourceId,
+            // A key has no uid; `'api'` is the attribution every API-created CRM
+            // record carries in `createdByUid`, and the note it leaves names the
+            // key when the organization named it.
+            actor: {
+                uid: 'api',
+                email: null,
+                apiKeyName: ctx.keyName
+            },
+            hostId: null,
+            actorName: ctx.keyName ? apiKeyActorLabel(ctx.keyName) : 'API'
+        });
+        if (result.ok === false) {
+            await claim.release();
+            if (result.reason === 'survivor-missing') {
+                return ApiErrors.notFound({
+                    message: 'No such contact',
+                    headers: ctx.headers
+                });
+            }
+            if (result.reason === 'merged-missing') {
+                return ApiErrors.notFound({
+                    message: 'No such contact to merge',
+                    code: 'source_not_found',
+                    headers: ctx.headers
+                });
+            }
+            return ApiErrors.badRequest({
+                message: 'Merge failed validation',
+                code: 'validation_failed',
+                fields: {
+                    [MERGE_SOURCE_FIELD]: 'Must be a different contact from the one in the path'
+                },
+                headers: ctx.headers
+            });
+        }
+        const answer = view(await survivorRef.get());
+        await claim.record(200, answer);
+        return apiJson(answer, {
+            headers: ctx.headers
+        });
+    } catch (error) {
+        await claim.release();
+        throw error;
+    }
+}
+
+//# sourceMappingURL=contacts-merge.js.map

package/src/lib/server/api-v1/contacts-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/plugins/crm/src/lib/server/api-v1/contacts-merge.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 * `POST /v1/contacts/{contactId}/merge` (AGL-2625) — fold another contact\n * into this one.\n *\n * The contact in the path SURVIVES: it keeps its address as the identity,\n * and the record named by `sourceContactId` is folded into it and deleted.\n * `mergeContacts` (`../merge-contacts.ts`) is the whole of the work — the same\n * function behind the console's `crm/contacts-merge` — so an integration\n * and a person at the record page cannot merge two different ways.\n *\n * ## Idempotency\n *\n * Takes an `Idempotency-Key` with the delete's exact semantics, and for the\n * delete's reason: a merge destroys a record, and a retry after a lost\n * response must be able to tell \"already merged\" from \"wrong id\". Without a\n * key, a second call finds no source contact and answers `404`, which is\n * true and is the confusion the key removes.\n *\n * ## What it answers\n *\n * The surviving contact, read back the way `GET` reads it — the\n * organization-wide profile, or one site's through `?consentSiteId=` —\n * with its `alternateEmails` now carrying the merged address.\n */\n\nimport { ApiErrors, apiJson } from '@aglyn/tenant-data-admin'\nimport { apiKeyActorLabel } from '@aglyn/aglyn/app-utils/activity-presenter'\nimport {\n  type ApiV1Context,\n  claimWrite,\n  readJsonBody,\n} from '@aglyn/tenant-data-admin/server/api-v1-kit'\nimport { mergeContacts } from '../merge-contacts'\n\n/** The key an integration names the record to fold in by. */\nexport const MERGE_SOURCE_FIELD = 'sourceContactId'\n\nexport async function mergeContactRoute(\n  request: Request,\n  ctx: ApiV1Context,\n  survivorRef: FirebaseFirestore.DocumentReference,\n  view: (snapshot: FirebaseFirestore.DocumentSnapshot) => unknown,\n): Promise<Response> {\n  const body = await readJsonBody(request)\n  const raw = body[MERGE_SOURCE_FIELD]\n  const sourceId = typeof raw === 'string' ? raw.trim() : ''\n  const fields: Record<string, string> = {}\n  if (raw === undefined) fields[MERGE_SOURCE_FIELD] = 'Required — the contact to merge into this one'\n  else if (!sourceId) fields[MERGE_SOURCE_FIELD] = 'Must be a contact id'\n  else if (sourceId === survivorRef.id) {\n    fields[MERGE_SOURCE_FIELD] = 'Must be a different contact from the one in the path'\n  }\n  for (const key of Object.keys(body)) {\n    if (key !== MERGE_SOURCE_FIELD) fields[key] = 'Not accepted on a merge'\n  }\n  if (Object.keys(fields).length) {\n    return ApiErrors.badRequest({\n      message: 'Merge failed validation',\n      code: 'validation_failed',\n      fields,\n      headers: ctx.headers,\n    })\n  }\n\n  const claimed = await claimWrite(\n    ctx,\n    '*',\n    request.headers.get('Idempotency-Key'),\n    'contact-merges',\n  )\n  if ('replay' in claimed) return claimed.replay\n  const { claim } = claimed\n\n  try {\n    const result = await mergeContacts({\n      firestore: ctx.firestore,\n      orgRef: ctx.firestore.collection('orgs').doc(ctx.orgId),\n      survivorId: survivorRef.id,\n      mergedId: sourceId,\n      // A key has no uid; `'api'` is the attribution every API-created CRM\n      // record carries in `createdByUid`, and the note it leaves names the\n      // key when the organization named it.\n      actor: { uid: 'api', email: null, apiKeyName: ctx.keyName },\n      hostId: null,\n      actorName: ctx.keyName ? apiKeyActorLabel(ctx.keyName) : 'API',\n    })\n    if (result.ok === false) {\n      await claim.release()\n      if (result.reason === 'survivor-missing') {\n        return ApiErrors.notFound({ message: 'No such contact', headers: ctx.headers })\n      }\n      if (result.reason === 'merged-missing') {\n        return ApiErrors.notFound({\n          message: 'No such contact to merge',\n          code: 'source_not_found',\n          headers: ctx.headers,\n        })\n      }\n      return ApiErrors.badRequest({\n        message: 'Merge failed validation',\n        code: 'validation_failed',\n        fields: { [MERGE_SOURCE_FIELD]: 'Must be a different contact from the one in the path' },\n        headers: ctx.headers,\n      })\n    }\n    const answer = view(await survivorRef.get())\n    await claim.record(200, answer)\n    return apiJson(answer, { headers: ctx.headers })\n  } catch (error) {\n    await claim.release()\n    throw error\n  }\n}\n"],"names":["ApiErrors","apiJson","apiKeyActorLabel","claimWrite","readJsonBody","mergeContacts","MERGE_SOURCE_FIELD","mergeContactRoute","request","ctx","survivorRef","view","body","raw","sourceId","trim","fields","undefined","id","key","Object","keys","length","badRequest","message","code","headers","claimed","get","replay","claim","result","firestore","orgRef","collection","doc","orgId","survivorId","mergedId","actor","uid","email","apiKeyName","keyName","hostId","actorName","ok","release","reason","notFound","answer","record","error"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED,SAASA,SAAS,EAAEC,OAAO,QAAQ,2BAA0B;AAC7D,SAASC,gBAAgB,QAAQ,4CAA2C;AAC5E,SAEEC,UAAU,EACVC,YAAY,QACP,6CAA4C;AACnD,SAASC,aAAa,QAAQ,uBAAmB;AAEjD,2DAA2D,GAC3D,OAAO,MAAMC,qBAAqB,kBAAiB;AAEnD,OAAO,eAAeC,kBACpBC,OAAgB,EAChBC,GAAiB,EACjBC,WAAgD,EAChDC,IAA+D;IAE/D,MAAMC,OAAO,MAAMR,aAAaI;IAChC,MAAMK,MAAMD,IAAI,CAACN,mBAAmB;IACpC,MAAMQ,WAAW,OAAOD,QAAQ,WAAWA,IAAIE,IAAI,KAAK;IACxD,MAAMC,SAAiC,CAAC;IACxC,IAAIH,QAAQI,WAAWD,MAAM,CAACV,mBAAmB,GAAG;SAC/C,IAAI,CAACQ,UAAUE,MAAM,CAACV,mBAAmB,GAAG;SAC5C,IAAIQ,aAAaJ,YAAYQ,EAAE,EAAE;QACpCF,MAAM,CAACV,mBAAmB,GAAG;IAC/B;IACA,KAAK,MAAMa,OAAOC,OAAOC,IAAI,CAACT,MAAO;QACnC,IAAIO,QAAQb,oBAAoBU,MAAM,CAACG,IAAI,GAAG;IAChD;IACA,IAAIC,OAAOC,IAAI,CAACL,QAAQM,MAAM,EAAE;QAC9B,OAAOtB,UAAUuB,UAAU,CAAC;YAC1BC,SAAS;YACTC,MAAM;YACNT;YACAU,SAASjB,IAAIiB,OAAO;QACtB;IACF;IAEA,MAAMC,UAAU,MAAMxB,WACpBM,KACA,KACAD,QAAQkB,OAAO,CAACE,GAAG,CAAC,oBACpB;IAEF,IAAI,YAAYD,SAAS,OAAOA,QAAQE,MAAM;IAC9C,MAAM,EAAEC,KAAK,EAAE,GAAGH;IAElB,IAAI;QACF,MAAMI,SAAS,MAAM1B,cAAc;YACjC2B,WAAWvB,IAAIuB,SAAS;YACxBC,QAAQxB,IAAIuB,SAAS,CAACE,UAAU,CAAC,QAAQC,GAAG,CAAC1B,IAAI2B,KAAK;YACtDC,YAAY3B,YAAYQ,EAAE;YAC1BoB,UAAUxB;YACV,qEAAqE;YACrE,qEAAqE;YACrE,sCAAsC;YACtCyB,OAAO;gBAAEC,KAAK;gBAAOC,OAAO;gBAAMC,YAAYjC,IAAIkC,OAAO;YAAC;YAC1DC,QAAQ;YACRC,WAAWpC,IAAIkC,OAAO,GAAGzC,iBAAiBO,IAAIkC,OAAO,IAAI;QAC3D;QACA,IAAIZ,OAAOe,EAAE,KAAK,OAAO;YACvB,MAAMhB,MAAMiB,OAAO;YACnB,IAAIhB,OAAOiB,MAAM,KAAK,oBAAoB;gBACxC,OAAOhD,UAAUiD,QAAQ,CAAC;oBAAEzB,SAAS;oBAAmBE,SAASjB,IAAIiB,OAAO;gBAAC;YAC/E;YACA,IAAIK,OAAOiB,MAAM,KAAK,kBAAkB;gBACtC,OAAOhD,UAAUiD,QAAQ,CAAC;oBACxBzB,SAAS;oBACTC,MAAM;oBACNC,SAASjB,IAAIiB,OAAO;gBACtB;YACF;YACA,OAAO1B,UAAUuB,UAAU,CAAC;gBAC1BC,SAAS;gBACTC,MAAM;gBACNT,QAAQ;oBAAE,CAACV,mBAAmB,EAAE;gBAAuD;gBACvFoB,SAASjB,IAAIiB,OAAO;YACtB;QACF;QACA,MAAMwB,SAASvC,KAAK,MAAMD,YAAYkB,GAAG;QACzC,MAAME,MAAMqB,MAAM,CAAC,KAAKD;QACxB,OAAOjD,QAAQiD,QAAQ;YAAExB,SAASjB,IAAIiB,OAAO;QAAC;IAChD,EAAE,OAAO0B,OAAO;QACd,MAAMtB,MAAMiB,OAAO;QACnB,MAAMK;IACR;AACF"}

package/src/lib/server/api-v1/contacts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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 ApiV1Context } from '@aglyn/tenant-data-admin/server/api-v1-kit';
+export declare function handleContacts(request: Request, ctx: ApiV1Context, segments: string[], url: URL): Promise<Response>;