@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/server/record-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/record-timeline.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  registerPluginRecordTimelineWriter,\n  type PluginRecordActivityRequest,\n  type PluginRecordEntryContext,\n  type PluginRecordTaskRequest,\n  type PluginRecordTimelineWriter,\n  type PluginRecordWrite,\n} from '@aglyn/aglyn/plugin-manager/plugin-record-timeline'\nimport {\n  buildCrmCapturedEmailActivity,\n  checkEntitlement,\n  consentGroupForHost,\n  CRM_ACTIVITY_LOG_FULL_MESSAGE,\n  CRM_COLLECTIONS,\n  crmActivityLogHasRoom,\n  crmCapturedEmailKey,\n  crmScopeTokens,\n  crmTaskReminderAfterEdit,\n  isCrmActivityKind,\n  isCrmTaskKind,\n  type CrmActivity,\n  type CrmActivityLink,\n  type CrmTask,\n} from '@aglyn/aglyn/server'\nimport {\n  countCrmActivitiesForRecord,\n  createCrmEmailActivity,\n  crmActivityRef,\n  crmCapturedEmailActivityRef,\n  firebaseAdmin,\n  recomputeCrmNextTaskAt,\n} from '@aglyn/tenant-data-admin'\nimport { createHash } from 'crypto'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { CRM_SUITE_FEATURE } from './suite-gate'\n\n/**\n * THE CRM'S WRITER ON THE CORE'S RECORD-TIMELINE SEAM (AGL-2981).\n *\n * Another plugin files an activity or a task on a contact, company or deal —\n * an email a sequence sent, the reply it read, the call it asks for — and\n * this writes it as the CRM writes its own:\n *\n *  1. the workspace's plan carries the CRM (`features.crm`), as at every\n *     CRM door; a Free workspace keeps no records to file on;\n *  2. the entry carries the scope a record made on that site carries\n *     (`crmScopeTokens`), so exactly the people who see the record see it;\n *  3. an EMAIL is filed under the id the capture address files a copy of the\n *     same message by (`cap_` + the digest of its `Message-ID`), and written\n *     with `create()`: the send, a copy the rep forwarded to the capture\n *     address, and a second run of the caller are one row;\n *  4. anything else — a note, a task — is filed under the caller's own key,\n *     hashed with the caller's plugin id, and written once the same way;\n *  5. a record at its activity ceiling is refused with the sentence every\n *     CRM writer answers with, before anything is written.\n *\n * Each entry names the plugin that filed it (`sourcePluginId`), and a task's\n * `nextTaskAtMs` is recomputed on the records it names, as every server\n * writer of a task does.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\nexport interface CrmRecordTimelineDeps {\n  firestore(): Firestore\n}\n\n/** gRPC `ALREADY_EXISTS`, which `create()` rejects with when the document is there. */\nconst ALREADY_EXISTS = 6\n\n/** The longest task title the CRM keeps, as its own forms do. */\nconst TASK_TITLE_MAX = 200\n/** The longest note body or task note an entry filed here keeps. */\nconst NOTE_MAX = 2_000\n\nconst refuse = (status: 400 | 403 | 404 | 409, error: string): PluginRecordWrite => ({\n  ok: false,\n  status,\n  error,\n})\n\n/** The record fields of a link, only the ones it names. */\nfunction linkFields(link: PluginRecordEntryContext['link']): CrmActivityLink {\n  return {\n    ...(link?.contactId ? { contactId: String(link.contactId) } : {}),\n    ...(link?.companyId ? { companyId: String(link.companyId) } : {}),\n    ...(link?.dealId ? { dealId: String(link.dealId) } : {}),\n  }\n}\n\n/** The document id a caller's key files under: its own namespace, never a raw key. */\nfunction keyedId(sourcePluginId: string, key: string): string {\n  return `plg_${createHash('sha256').update(`${sourcePluginId}:${key}`).digest('hex').slice(0, 28)}`\n}\n\nexport function createCrmRecordTimelineWriter(deps: CrmRecordTimelineDeps): PluginRecordTimelineWriter {\n  /** The org, its plan, the link and the scope an entry is stamped with. */\n  async function admit(\n    context: PluginRecordEntryContext,\n  ): Promise<\n    | PluginRecordWrite\n    | { firestore: Firestore; orgRef: FirebaseFirestore.DocumentReference; link: CrmActivityLink; visibleTo: string[] }\n  > {\n    const orgId = String(context.orgId ?? '').trim()\n    const hostId = String(context.hostId ?? '').trim()\n    const link = linkFields(context.link)\n    if (!orgId || !hostId || !String(context.sourcePluginId ?? '').trim()) {\n      return refuse(400, 'An entry names its organization, its site and the plugin filing it.')\n    }\n    if (!link.contactId && !link.companyId && !link.dealId) {\n      return refuse(400, 'An entry is filed on a contact, a company or a deal.')\n    }\n    const firestore = deps.firestore()\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const snapshot = await orgRef.get()\n    if (!snapshot.exists) return refuse(404, 'That organization no longer exists.')\n    const org = (snapshot.data() ?? {}) as Record<string, unknown>\n    if (!checkEntitlement(org, CRM_SUITE_FEATURE)) {\n      return refuse(403, \"This workspace's plan doesn't include the CRM.\")\n    }\n    return {\n      firestore,\n      orgRef,\n      link,\n      visibleTo: crmScopeTokens(org, consentGroupForHost(org, hostId)),\n    }\n  }\n\n  /** Creates a keyed entry once: `created: false` for one already filed. */\n  async function createOnce(\n    ref: FirebaseFirestore.DocumentReference,\n    data: Record<string, unknown>,\n  ): Promise<boolean> {\n    try {\n      await ref.create({\n        ...data,\n        createdAt: FieldValue.serverTimestamp(),\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n      return true\n    } catch (error) {\n      if ((error as { code?: unknown })?.code === ALREADY_EXISTS) return false\n      throw error\n    }\n  }\n\n  return {\n    async logActivity(request: PluginRecordActivityRequest): Promise<PluginRecordWrite> {\n      if (!isCrmActivityKind(request.kind)) return refuse(400, `\"${String(request.kind)}\" isn't an activity.`)\n      const admitted = await admit(request)\n      if ('ok' in admitted) return admitted\n      const { firestore, orgRef, link, visibleTo } = admitted\n      const orgId = orgRef.id\n\n      let ref: FirebaseFirestore.DocumentReference\n      let activity: CrmActivity\n      if (request.kind === 'email') {\n        const email = request.email\n        const key = email ? crmCapturedEmailKey(email.messageId, null) : null\n        if (!email || !key) return refuse(400, 'An email is filed by its Message-ID.')\n        ref = crmCapturedEmailActivityRef(firestore, orgId, key)\n        activity = buildCrmCapturedEmailActivity({\n          direction: email.direction === 'inbound' ? 'inbound' : 'outbound',\n          subject: email.subject,\n          excerpt: request.body,\n          from: email.from,\n          to: email.to,\n          messageId: email.messageId,\n          inReplyTo: email.inReplyTo ?? null,\n          atMs: request.atMs,\n          byUid: String(request.byUid ?? ''),\n          byName: request.byName ?? null,\n          link,\n          hostId: request.hostId,\n          visibleTo,\n        })\n      } else {\n        const key = String(request.dedupeKey ?? '').trim()\n        if (!key) return refuse(400, 'An entry that is not an email names its own key.')\n        ref = crmActivityRef(firestore, orgId, keyedId(request.sourcePluginId, key))\n        const byName = String(request.byName ?? '').trim()\n        activity = {\n          kind: request.kind,\n          body: String(request.body ?? '').slice(0, NOTE_MAX),\n          atMs: request.atMs,\n          byUid: String(request.byUid ?? ''),\n          ...(byName ? { byName } : {}),\n          ...link,\n          hostId: request.hostId,\n          visibleTo,\n        }\n      }\n      // Filed before: answered off the one read, ahead of the ceiling's count.\n      if ((await ref.get()).exists) return { ok: true, id: ref.id, created: false }\n      if (!crmActivityLogHasRoom(await countCrmActivitiesForRecord(orgRef, link))) {\n        return refuse(409, CRM_ACTIVITY_LOG_FULL_MESSAGE)\n      }\n      const stamped = { ...activity, sourcePluginId: request.sourcePluginId }\n      const created =\n        request.kind === 'email'\n          ? (await createCrmEmailActivity(ref, stamped)) === 'created'\n          : await createOnce(ref, stamped as unknown as Record<string, unknown>)\n      return { ok: true, id: ref.id, created }\n    },\n\n    async createTask(request: PluginRecordTaskRequest): Promise<PluginRecordWrite> {\n      const title = String(request.title ?? '').replace(/\\s+/g, ' ').trim().slice(0, TASK_TITLE_MAX)\n      const key = String(request.dedupeKey ?? '').trim()\n      if (!title || !key) return refuse(400, 'A task has a title and the caller’s own key.')\n      if (!isCrmTaskKind(request.kind)) return refuse(400, `\"${String(request.kind)}\" isn't a task.`)\n      if (!Number.isFinite(request.dueAtMs)) return refuse(400, 'A task has a due time.')\n      const admitted = await admit(request)\n      if ('ok' in admitted) return admitted\n      const { firestore, orgRef, link, visibleTo } = admitted\n      const ref = orgRef.collection(CRM_COLLECTIONS.tasks).doc(keyedId(request.sourcePluginId, key))\n      const notes = String(request.notes ?? '').trim().slice(0, NOTE_MAX)\n      const assigneeUid = String(request.assigneeUid ?? '').trim()\n      const task: CrmTask = {\n        title,\n        ...(notes ? { notes } : {}),\n        kind: request.kind,\n        priority: 'normal',\n        status: 'open',\n        dueAtMs: request.dueAtMs,\n        // The reminder a person's task gets (AGL-2659): the due time.\n        remindAtMs: crmTaskReminderAfterEdit({ dueAtMs: request.dueAtMs, previous: null }),\n        ...(assigneeUid ? { assigneeUid } : {}),\n        createdByUid: String(request.createdByUid ?? ''),\n        sourcePluginId: request.sourcePluginId,\n        ...link,\n        hostId: request.hostId,\n        visibleTo,\n      }\n      const created = await createOnce(ref, task as unknown as Record<string, unknown>)\n      if (created) {\n        // The records the task names carry `nextTaskAtMs` (AGL-2661); a figure\n        // that could not move is the Fields section's recompute's.\n        await recomputeCrmNextTaskAt(firestore, orgRef.id, [link]).catch((error: unknown) => {\n          console.error('[crm] next activity could not be recomputed', orgRef.id, error)\n        })\n      }\n      return { ok: true, id: ref.id, created }\n    },\n  }\n}\n\n/** The platform's own dependencies. Specs build their own. */\nexport function defaultCrmRecordTimelineDeps(): CrmRecordTimelineDeps {\n  return { firestore: () => firebaseAdmin.app().firestore() }\n}\n\n/** Registers the CRM as the workspace's record system on the timeline seam. */\nexport function registerCrmRecordTimelineWriter(\n  deps: CrmRecordTimelineDeps = defaultCrmRecordTimelineDeps(),\n): void {\n  registerPluginRecordTimelineWriter(createCrmRecordTimelineWriter(deps), { pluginId: BUNDLE_ID })\n}\n"],"names":["registerPluginRecordTimelineWriter","buildCrmCapturedEmailActivity","checkEntitlement","consentGroupForHost","CRM_ACTIVITY_LOG_FULL_MESSAGE","CRM_COLLECTIONS","crmActivityLogHasRoom","crmCapturedEmailKey","crmScopeTokens","crmTaskReminderAfterEdit","isCrmActivityKind","isCrmTaskKind","countCrmActivitiesForRecord","createCrmEmailActivity","crmActivityRef","crmCapturedEmailActivityRef","firebaseAdmin","recomputeCrmNextTaskAt","createHash","FieldValue","BUNDLE_ID","CRM_SUITE_FEATURE","ALREADY_EXISTS","TASK_TITLE_MAX","NOTE_MAX","refuse","status","error","ok","linkFields","link","contactId","String","companyId","dealId","keyedId","sourcePluginId","key","update","digest","slice","createCrmRecordTimelineWriter","deps","admit","context","snapshot","orgId","trim","hostId","firestore","orgRef","collection","doc","get","exists","org","data","visibleTo","createOnce","ref","create","createdAt","serverTimestamp","updatedAt","code","logActivity","request","kind","admitted","id","activity","email","messageId","direction","subject","excerpt","body","from","to","inReplyTo","atMs","byUid","byName","dedupeKey","created","stamped","createTask","title","replace","Number","isFinite","dueAtMs","tasks","notes","assigneeUid","task","priority","remindAtMs","previous","createdByUid","catch","console","defaultCrmRecordTimelineDeps","app","registerCrmRecordTimelineWriter","pluginId"],"mappings":"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"}

package/src/lib/server/suite-gate.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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.
+ */
+/** The entitlement the suite is sold under — the REST refusal's `error.code`. */
+export declare const CRM_SUITE_FEATURE = "crm";
+/** The REST refusal's `error.type`, as a console route's `reason`. */
+export declare const CRM_SUITE_REFUSAL_REASON = "plan_required";
+/** What a route answers a workspace whose plan does not carry the suite. */
+export interface CrmSuiteRefusal {
+    status: 403;
+    body: {
+        error: string;
+        reason: typeof CRM_SUITE_REFUSAL_REASON;
+        code: typeof CRM_SUITE_FEATURE;
+    };
+}
+/**
+ * The refusal's sentence, for an act named as a phrase that takes "is" —
+ * "Importing a CSV file", "A CRM recipe".
+ */
+export declare function crmSuiteRefusalMessage(act: string): string;
+/**
+ * `null` when the org's plan carries the suite, else the refusal to send.
+ *
+ * Resolved through `checkEntitlement`, so a per-org
+ * `entitlements.features.crm` grant or revocation, and a paid plan whose
+ * subscription has died, answer here exactly as they answer everywhere else.
+ */
+export declare function crmSuiteRefusal(org: unknown, act: string): CrmSuiteRefusal | null;

package/src/lib/server/suite-gate.js

@@ -0,0 +1,87 @@
+/**
+ * @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.
+ */ /**
+ * THE CRM'S PLAN GATE, for the routes the console calls (AGL-2787, AGL-2851).
+ *
+ * The CRM is included from Starter: `features.crm` is false on Free, and a
+ * Free workspace has none of it — no section, no read and no write. Three
+ * other doors onto the CRM's records ask the same question: the shell draws
+ * every CRM section locked and refuses its body, the `/v1` dispatcher refuses
+ * the CRM's resources, and the Firestore rules refuse a client's CRM writes.
+ * These routes are the fourth door, and every `crm/*` read and write asks it.
+ * A lock drawn on a page is advice to a script holding a member's token, so
+ * the same question is asked where the read or the write happens.
+ *
+ * ## What is never asked
+ *
+ * Capture — a form, a sign-up, a booking, an order — does not come through
+ * these routes, and records what it records on every plan. The compliance
+ * doors are every plan's too: `crm/erase-person`, and the contacts and leads
+ * files of `/api/crm/export`, because exporting and erasing the people a
+ * workspace holds are obligations rather than CRM features.
+ *
+ * ## After authorization, never before
+ *
+ * Each route asks once it knows who is calling and has read the org to
+ * answer that — the order the shell refuses in. A reader who may not open a
+ * surface is not shown its upgrade path, and a caller with no standing in
+ * the workspace learns nothing about its plan.
+ *
+ * ## One refusal shape
+ *
+ * 403, as the REST refusal is, with its two machine-readable facts in the
+ * console routes' flat body: `reason: 'plan_required'` is the REST
+ * `error.type` and `code: 'crm'` its `error.code`. Beside them, a sentence
+ * the console relays unchanged, as it relays every route refusal. The plan
+ * it names comes from the plan tables, so it cannot name a tier that has
+ * stopped carrying the suite.
+ *
+ * ## Staff are refused too
+ *
+ * The plan is a fact about the workspace, not about the person asking. A
+ * support engineer acting inside a Free workspace would otherwise create
+ * suite records that the workspace then holds without the suite.
+ */ import { checkEntitlement, planLabelGrantingFeature } from "@aglyn/aglyn/server";
+/** The entitlement the suite is sold under — the REST refusal's `error.code`. */ export const CRM_SUITE_FEATURE = 'crm';
+/** The REST refusal's `error.type`, as a console route's `reason`. */ export const CRM_SUITE_REFUSAL_REASON = 'plan_required';
+/**
+ * The refusal's sentence, for an act named as a phrase that takes "is" —
+ * "Importing a CSV file", "A CRM recipe".
+ */ export function crmSuiteRefusalMessage(act) {
+    const plan = planLabelGrantingFeature(CRM_SUITE_FEATURE);
+    return `${act} is part of the CRM, which is not included in your current ` + 'plan. Manage your plan and add-ons from Billing.' + (plan ? ` Included from ${plan}.` : '');
+}
+/**
+ * `null` when the org's plan carries the suite, else the refusal to send.
+ *
+ * Resolved through `checkEntitlement`, so a per-org
+ * `entitlements.features.crm` grant or revocation, and a paid plan whose
+ * subscription has died, answer here exactly as they answer everywhere else.
+ */ export function crmSuiteRefusal(org, act) {
+    if (checkEntitlement(org, CRM_SUITE_FEATURE)) {
+        return null;
+    }
+    return {
+        status: 403,
+        body: {
+            error: crmSuiteRefusalMessage(act),
+            reason: CRM_SUITE_REFUSAL_REASON,
+            code: CRM_SUITE_FEATURE
+        }
+    };
+}
+
+//# sourceMappingURL=suite-gate.js.map

package/src/lib/server/suite-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/suite-gate.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 * THE CRM'S PLAN GATE, for the routes the console calls (AGL-2787, AGL-2851).\n *\n * The CRM is included from Starter: `features.crm` is false on Free, and a\n * Free workspace has none of it — no section, no read and no write. Three\n * other doors onto the CRM's records ask the same question: the shell draws\n * every CRM section locked and refuses its body, the `/v1` dispatcher refuses\n * the CRM's resources, and the Firestore rules refuse a client's CRM writes.\n * These routes are the fourth door, and every `crm/*` read and write asks it.\n * A lock drawn on a page is advice to a script holding a member's token, so\n * the same question is asked where the read or the write happens.\n *\n * ## What is never asked\n *\n * Capture — a form, a sign-up, a booking, an order — does not come through\n * these routes, and records what it records on every plan. The compliance\n * doors are every plan's too: `crm/erase-person`, and the contacts and leads\n * files of `/api/crm/export`, because exporting and erasing the people a\n * workspace holds are obligations rather than CRM features.\n *\n * ## After authorization, never before\n *\n * Each route asks once it knows who is calling and has read the org to\n * answer that — the order the shell refuses in. A reader who may not open a\n * surface is not shown its upgrade path, and a caller with no standing in\n * the workspace learns nothing about its plan.\n *\n * ## One refusal shape\n *\n * 403, as the REST refusal is, with its two machine-readable facts in the\n * console routes' flat body: `reason: 'plan_required'` is the REST\n * `error.type` and `code: 'crm'` its `error.code`. Beside them, a sentence\n * the console relays unchanged, as it relays every route refusal. The plan\n * it names comes from the plan tables, so it cannot name a tier that has\n * stopped carrying the suite.\n *\n * ## Staff are refused too\n *\n * The plan is a fact about the workspace, not about the person asking. A\n * support engineer acting inside a Free workspace would otherwise create\n * suite records that the workspace then holds without the suite.\n */\n\nimport { checkEntitlement, planLabelGrantingFeature } from '@aglyn/aglyn/server'\n\n/** The entitlement the suite is sold under — the REST refusal's `error.code`. */\nexport const CRM_SUITE_FEATURE = 'crm'\n\n/** The REST refusal's `error.type`, as a console route's `reason`. */\nexport const CRM_SUITE_REFUSAL_REASON = 'plan_required'\n\n/** What a route answers a workspace whose plan does not carry the suite. */\nexport interface CrmSuiteRefusal {\n  status: 403\n  body: {\n    error: string\n    reason: typeof CRM_SUITE_REFUSAL_REASON\n    code: typeof CRM_SUITE_FEATURE\n  }\n}\n\n/**\n * The refusal's sentence, for an act named as a phrase that takes \"is\" —\n * \"Importing a CSV file\", \"A CRM recipe\".\n */\nexport function crmSuiteRefusalMessage(act: string): string {\n  const plan = planLabelGrantingFeature(CRM_SUITE_FEATURE)\n  return (\n    `${act} is part of the CRM, which is not included in your current ` +\n    'plan. Manage your plan and add-ons from Billing.' +\n    (plan ? ` Included from ${plan}.` : '')\n  )\n}\n\n/**\n * `null` when the org's plan carries the suite, else the refusal to send.\n *\n * Resolved through `checkEntitlement`, so a per-org\n * `entitlements.features.crm` grant or revocation, and a paid plan whose\n * subscription has died, answer here exactly as they answer everywhere else.\n */\nexport function crmSuiteRefusal(org: unknown, act: string): CrmSuiteRefusal | null {\n  if (checkEntitlement(org as Parameters<typeof checkEntitlement>[0], CRM_SUITE_FEATURE)) {\n    return null\n  }\n  return {\n    status: 403,\n    body: {\n      error: crmSuiteRefusalMessage(act),\n      reason: CRM_SUITE_REFUSAL_REASON,\n      code: CRM_SUITE_FEATURE,\n    },\n  }\n}\n"],"names":["checkEntitlement","planLabelGrantingFeature","CRM_SUITE_FEATURE","CRM_SUITE_REFUSAL_REASON","crmSuiteRefusalMessage","act","plan","crmSuiteRefusal","org","status","body","error","reason","code"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GAED,SAASA,gBAAgB,EAAEC,wBAAwB,QAAQ,sBAAqB;AAEhF,+EAA+E,GAC/E,OAAO,MAAMC,oBAAoB,MAAK;AAEtC,oEAAoE,GACpE,OAAO,MAAMC,2BAA2B,gBAAe;AAYvD;;;CAGC,GACD,OAAO,SAASC,uBAAuBC,GAAW;IAChD,MAAMC,OAAOL,yBAAyBC;IACtC,OACE,GAAGG,IAAI,2DAA2D,CAAC,GACnE,qDACCC,CAAAA,OAAO,CAAC,eAAe,EAAEA,KAAK,CAAC,CAAC,GAAG,EAAC;AAEzC;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,gBAAgBC,GAAY,EAAEH,GAAW;IACvD,IAAIL,iBAAiBQ,KAA+CN,oBAAoB;QACtF,OAAO;IACT;IACA,OAAO;QACLO,QAAQ;QACRC,MAAM;YACJC,OAAOP,uBAAuBC;YAC9BO,QAAQT;YACRU,MAAMX;QACR;IACF;AACF"}

package/src/lib/server/task-routes.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @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 AglynOrgMember, type PluginApiHandler, type PluginApiRequest } from '@aglyn/aglyn/server';
+import { type CrmRouteScope } from './org-caller';
+/**
+ * The two things a task does that a browser must not do alone (AGL-2599).
+ *
+ * Every other task write is client-direct against the Firestore rules —
+ * reopening, deleting, the list's own reads. These two are routes because
+ * each has a side effect that lives outside the document:
+ *
+ * - SAVING a task assigned to somebody else NOTIFIES them, and a
+ *   notification is an Admin-SDK write into another person's inbox. Rather
+ *   than a client-direct write followed by a "please notify" call — two
+ *   operations that can disagree about whether the task exists — the route
+ *   persists the task itself and notifies from the same code path, so a
+ *   notification can never announce a task that failed to save. It also
+ *   stamps the scope, the provenance and the timestamps, which is one
+ *   creator computing `visibleTo` rather than two.
+ *
+ * - COMPLETING a task EMITS the `taskCompleted` host event, which is what a
+ *   workflow triggers on. A browser cannot run the workflow runner.
+ *
+ * Both authenticate the way the other console plugin routes do — the ID
+ * token in the `Authorization` header — and then ask the same two questions
+ * the rules ask of a `crmTasks` write: is this member allowed to write org
+ * data (`owner`/`admin`/`editor`, and `data.manage` resolved through their
+ * custom role), and can they reach THIS document's scope.
+ *
+ * ## The organization variant (AGL-2637)
+ *
+ * `{ orgId, … }` instead of a site: the org-level hub. The caller is
+ * authorized by the ORG — an org-wide member holding `data.manage`, the
+ * hub's own gate, never a site collaborator — and reaches every task the
+ * org holds, so no scope check is made against the document. A NEW task
+ * names the site it is filed from beside the org, or names none and is the
+ * organization's own: `hostId: null`, the org scope token alone. Completing
+ * emits on the task's OWN site, where its automations live; an
+ * organization task has none and emits nothing, as an uncaptured deal's
+ * stage change emits nothing.
+ *
+ * The org variant also takes a BATCH — `taskIds` to complete, `tasks` to
+ * save — so the org hub's bulk bar makes one request per action rather
+ * than one per task. Each task is answered on its own in `results`; the
+ * request as a whole is refused only for what refuses every task alike.
+ */
+export type Refusal = {
+    ok: false;
+    status: number;
+    body: {
+        error: string;
+        reason?: string;
+        code?: string;
+    };
+};
+export interface Writer {
+    ok: true;
+    uid: string;
+    staff: boolean;
+    orgId: string;
+    org: Record<string, unknown>;
+    /** The member document under a site; `null` at the org level, where the reach is the org's. */
+    member: Partial<AglynOrgMember> | null;
+    level: CrmRouteScope['level'];
+}
+export declare const refuse: (status: number, error: string) => Refusal;
+export interface CrmWriterOptions {
+    /**
+     * The act a plan without the CRM is refused for, named the way
+     * `crmSuiteRefusalMessage` takes it. `null` for a route that asks the plan
+     * itself, once it knows what the request writes, so the refusal can name
+     * that act — a contact update names the first field it carries. Tasks
+     * when unsaid.
+     */
+    suiteAct?: string | null;
+}
+/**
+ * Who is asking, and whether they may write this CRM at all.
+ *
+ * Under a site: the org resolved from the site and the rules' own role and
+ * permission questions. At the organization level: the org the body names,
+ * for an org-wide member with the permission. The scope question — may they
+ * reach THIS task — is asked by the caller against the document, because on
+ * a create the document does not exist yet and its scope is what the route
+ * is about to stamp.
+ */
+export declare function authorizeCrmWriter(req: PluginApiRequest, scope: CrmRouteScope, options?: CrmWriterOptions): Promise<Writer | Refusal>;
+/**
+ * The rules' `canReadScoped()`, for a document the route has in hand. An
+ * org-level writer was admitted as org-wide, and an org-wide member reads
+ * every row.
+ */
+export declare const canReach: (writer: Writer, visibleTo: unknown) => boolean;
+/**
+ * `POST crm/task-save` — create or update a task, and tell its assignee.
+ *
+ * Body: `{ hostId, taskId?, task: CrmTaskFields }` under a site;
+ * `{ orgId, hostId?, taskId?, task }` at the organization level; or the
+ * org-level batch `{ orgId, tasks: [{ taskId, task }] }`. Answers
+ * `{ ok, taskId, notified }`, or `{ ok, results }` for the batch.
+ *
+ * The NOTIFICATION fires when the saved assignee is somebody other than the
+ * person saving AND is not who the task was already assigned to. Assigning
+ * a task to yourself is a note to self; re-saving a task's title does not
+ * re-announce it to the person who already has it. The assignee must be a
+ * member of the org — a uid nobody can find in the roster is refused rather
+ * than written, because a notification to a stranger's inbox is the one
+ * thing this route must never do.
+ */
+export declare const crmTaskSaveHandler: PluginApiHandler;
+/**
+ * `POST crm/task-complete` — mark a task done and fire `taskCompleted`.
+ *
+ * Body: `{ hostId, taskId }` under a site, `{ orgId, taskId }` at the
+ * organization level, or the org-level batch `{ orgId, taskIds }`. Answers
+ * `{ ok, completedAtMs, alreadyDone? }`, or `{ ok, results }` for the batch.
+ */
+export declare const crmTaskCompleteHandler: PluginApiHandler;