@aglyn/plugins-crm 1.0.0-beta.243 → 1.0.0-beta.246

package/src/lib/server/crm-setup-ai-capabilities.js

@@ -0,0 +1,198 @@
+/**
+ * @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 { CONTACT_FIELD_TYPES } from "@aglyn/aglyn/app-utils/contact-custom-fields";
+import { CRM_FIELD_OBJECTS } from "@aglyn/aglyn/app-utils/crm";
+import { registerPluginAiCapability } from "@aglyn/aglyn/plugin-manager/plugin-ai-capabilities";
+import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { CRM_FIELD_LABEL_MAX_LENGTH, CRM_FIELD_OPTION_MAX_LENGTH, CRM_FIELD_OPTIONS_MAX, CRM_FIELD_SETUP_RESOURCE, CRM_PIPELINE_SETUP_RESOURCE, CRM_SETUP_OPEN_STAGES_MAX, CRM_SETUP_STAGE_NAME_MAX } from "../model/crm-setup-content.js";
+import { PIPELINE_NAME_MAX } from "../model/deal-board-model.js";
+/**
+ * WHAT AN AI BUILD CAN SET UP IN THE CRM (AGL-3746): a deal pipeline with its
+ * stages, and a custom field on a contact, company, deal or lead.
+ *
+ * The capabilities the AI plugin's build planner offers for "set up a sales
+ * pipeline for my agency: Discovery, Proposal, Negotiation, Won/Lost" or
+ * "add a Budget field to deals". Each item is written by this plugin's
+ * `crm-pipeline` or `crm-field` writer, so every rule is the writer's and the
+ * console's: the `crm` plan feature, an owner, admin or editor with
+ * `data.manage`, the scope, `stagesProblem`, the field types and the org's
+ * 100-field ceiling. Both are saved live, as the console saves them (`live`):
+ * neither has a draft state. Matched by name, so asking again changes
+ * nothing twice.
+ *
+ * The arguments are flat, as the contract requires, and are the setup's own
+ * fields; the planner fills them, so no model runs (`estimateCredits` 0). No
+ * page block shows either, so neither changes what a visitor sees.
+ *
+ * A Salesforce "opportunity" is a deal here and an "account" a company; the
+ * descriptions say so, since a request may use either word.
+ */ /** The operations' names in a build plan. */ export const CRM_PIPELINE_AI_OP = 'crm-pipeline';
+export const CRM_FIELD_AI_OP = 'crm-field';
+/** How many of each one build may set up. */ export const CRM_PIPELINE_AI_MAX_PER_PLAN = 3;
+export const CRM_FIELD_AI_MAX_PER_PLAN = 12;
+/** The CRM is included from Starter (`crm`); Free has none of it. */ const CRM_FEATURE = 'crm';
+function pick(args, keys) {
+    return Object.fromEntries(keys.filter((key)=>args[key] !== undefined && args[key] !== '').map((key)=>[
+            key,
+            args[key]
+        ]));
+}
+/** The pipeline writer's content for an item: its arguments, as they are. Pure. */ export function crmPipelineSetupContentFromArgs(args) {
+    return pick(args, [
+        'name',
+        'renameFrom',
+        'stages',
+        'wonStage',
+        'lostStage',
+        'makeDefault'
+    ]);
+}
+/** The field writer's content for an item: its arguments, as they are. Pure. */ export function crmFieldSetupContentFromArgs(args) {
+    return pick(args, [
+        'object',
+        'label',
+        'type',
+        'options',
+        'required'
+    ]);
+}
+export const crmPipelineAiCapability = {
+    op: CRM_PIPELINE_AI_OP,
+    noun: 'sales pipeline',
+    where: 'CRM → Deals → Pipelines',
+    intents: [
+        'CRM deal pipelines and their stages — "set up a sales pipeline: Discovery, Proposal, Negotiation, Won/Lost", rename a pipeline, add or reorder stages, set a stage’s win probability, make a pipeline the default; a Salesforce opportunity pipeline is a deal pipeline'
+    ],
+    argsSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'The pipeline’s name, e.g. "Agency sales". An existing pipeline of this name (any case) is updated rather than duplicated; give "renameFrom" to rename one.',
+                maxLength: PIPELINE_NAME_MAX
+            },
+            renameFrom: {
+                type: 'string',
+                description: 'Only to rename: the current name of the pipeline that becomes "name".',
+                maxLength: PIPELINE_NAME_MAX
+            },
+            stages: {
+                type: 'array',
+                description: 'The OPEN stages a deal moves through, in order, each a name with an optional win probability in parentheses, e.g. "Discovery (20%)". Never Won or Lost: every pipeline already has one of each (name them in wonStage and lostStage). Leave out to keep the stages as they are (a new pipeline then gets the standard set). Stages already in the pipeline and not listed are kept.',
+                items: {
+                    type: 'string',
+                    maxLength: CRM_SETUP_STAGE_NAME_MAX + 8
+                },
+                maxItems: CRM_SETUP_OPEN_STAGES_MAX
+            },
+            wonStage: {
+                type: 'string',
+                description: 'What the closing Won stage is called, where the request names it, e.g. "Won". Leave out to keep "Closed Won".',
+                maxLength: CRM_SETUP_STAGE_NAME_MAX
+            },
+            lostStage: {
+                type: 'string',
+                description: 'What the closing Lost stage is called, where the request names it, e.g. "Lost". Leave out to keep "Closed Lost".',
+                maxLength: CRM_SETUP_STAGE_NAME_MAX
+            },
+            makeDefault: {
+                type: 'boolean',
+                description: 'true only when the request says new deals should land in this pipeline (its main or default pipeline).'
+            }
+        },
+        required: [
+            'name'
+        ],
+        additionalProperties: false
+    },
+    maxPerPlan: CRM_PIPELINE_AI_MAX_PER_PLAN,
+    freeAllowed: false,
+    feature: CRM_FEATURE,
+    draftResource: CRM_PIPELINE_SETUP_RESOURCE,
+    live: true,
+    // Written without a model: the planner already filled the arguments.
+    estimateCredits: ()=>0,
+    degrade: 'omit',
+    draftContent: (item)=>crmPipelineSetupContentFromArgs(item.args)
+};
+export const crmFieldAiCapability = {
+    op: CRM_FIELD_AI_OP,
+    noun: 'CRM custom field',
+    where: 'CRM → Fields',
+    intents: [
+        'CRM custom fields on contacts, companies (accounts), deals (opportunities) or leads — "add a Budget field to opportunities", "a Choice field for Industry on companies"; types text, number, date, choice, checkbox and link only'
+    ],
+    argsSchema: {
+        type: 'object',
+        properties: {
+            object: {
+                type: 'string',
+                description: 'The record it describes: contact; company (an account); deal (an opportunity); lead.',
+                enum: CRM_FIELD_OBJECTS
+            },
+            label: {
+                type: 'string',
+                description: 'The field’s name as people read it, e.g. "Budget". A field of this name on the same record (any case) is left as it is rather than duplicated.',
+                maxLength: CRM_FIELD_LABEL_MAX_LENGTH
+            },
+            type: {
+                type: 'string',
+                description: 'What it holds: text; number (also an amount of money or a percentage — there is no currency type); date; select (a Choice from listed options); checkbox (yes or no); url (a link).',
+                enum: CONTACT_FIELD_TYPES
+            },
+            options: {
+                type: 'array',
+                description: 'For select only: the choices, in order. A select field that exists gains the ones it lacks.',
+                items: {
+                    type: 'string',
+                    maxLength: CRM_FIELD_OPTION_MAX_LENGTH
+                },
+                maxItems: CRM_FIELD_OPTIONS_MAX
+            },
+            required: {
+                type: 'boolean',
+                description: 'true only when the request says the field must always be filled in.'
+            }
+        },
+        required: [
+            'object',
+            'label',
+            'type'
+        ],
+        additionalProperties: false
+    },
+    maxPerPlan: CRM_FIELD_AI_MAX_PER_PLAN,
+    freeAllowed: false,
+    feature: CRM_FEATURE,
+    draftResource: CRM_FIELD_SETUP_RESOURCE,
+    live: true,
+    estimateCredits: ()=>0,
+    degrade: 'omit',
+    draftContent: (item)=>crmFieldSetupContentFromArgs(item.args)
+};
+/**
+ * Registers both capabilities; the console-server declarations call it beside
+ * the writers, since only the console runs AI jobs (AGL-3026). Idempotent.
+ */ export function registerCrmSetupAiCapabilities() {
+    registerPluginAiCapability(crmPipelineAiCapability, {
+        pluginId: BUNDLE_ID
+    });
+    registerPluginAiCapability(crmFieldAiCapability, {
+        pluginId: BUNDLE_ID
+    });
+}
+
+//# sourceMappingURL=crm-setup-ai-capabilities.js.map

package/src/lib/server/crm-setup-ai-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/crm-setup-ai-capabilities.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 { CONTACT_FIELD_TYPES } from '@aglyn/aglyn/app-utils/contact-custom-fields'\nimport { CRM_FIELD_OBJECTS } from '@aglyn/aglyn/app-utils/crm'\nimport {\n  registerPluginAiCapability,\n  type PluginAiCapability,\n  type PluginAiCapabilityArgs,\n} from '@aglyn/aglyn/plugin-manager/plugin-ai-capabilities'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport {\n  CRM_FIELD_LABEL_MAX_LENGTH,\n  CRM_FIELD_OPTION_MAX_LENGTH,\n  CRM_FIELD_OPTIONS_MAX,\n  CRM_FIELD_SETUP_RESOURCE,\n  CRM_PIPELINE_SETUP_RESOURCE,\n  CRM_SETUP_OPEN_STAGES_MAX,\n  CRM_SETUP_STAGE_NAME_MAX,\n} from '../model/crm-setup-content'\nimport { PIPELINE_NAME_MAX } from '../model/deal-board-model'\n\n/**\n * WHAT AN AI BUILD CAN SET UP IN THE CRM (AGL-3746): a deal pipeline with its\n * stages, and a custom field on a contact, company, deal or lead.\n *\n * The capabilities the AI plugin's build planner offers for \"set up a sales\n * pipeline for my agency: Discovery, Proposal, Negotiation, Won/Lost\" or\n * \"add a Budget field to deals\". Each item is written by this plugin's\n * `crm-pipeline` or `crm-field` writer, so every rule is the writer's and the\n * console's: the `crm` plan feature, an owner, admin or editor with\n * `data.manage`, the scope, `stagesProblem`, the field types and the org's\n * 100-field ceiling. Both are saved live, as the console saves them (`live`):\n * neither has a draft state. Matched by name, so asking again changes\n * nothing twice.\n *\n * The arguments are flat, as the contract requires, and are the setup's own\n * fields; the planner fills them, so no model runs (`estimateCredits` 0). No\n * page block shows either, so neither changes what a visitor sees.\n *\n * A Salesforce \"opportunity\" is a deal here and an \"account\" a company; the\n * descriptions say so, since a request may use either word.\n */\n\n/** The operations' names in a build plan. */\nexport const CRM_PIPELINE_AI_OP = 'crm-pipeline'\nexport const CRM_FIELD_AI_OP = 'crm-field'\n\n/** How many of each one build may set up. */\nexport const CRM_PIPELINE_AI_MAX_PER_PLAN = 3\nexport const CRM_FIELD_AI_MAX_PER_PLAN = 12\n\n/** The CRM is included from Starter (`crm`); Free has none of it. */\nconst CRM_FEATURE = 'crm'\n\nfunction pick(args: PluginAiCapabilityArgs, keys: readonly string[]): Record<string, unknown> {\n  return Object.fromEntries(keys.filter((key) => args[key] !== undefined && args[key] !== '').map((key) => [key, args[key]]))\n}\n\n/** The pipeline writer's content for an item: its arguments, as they are. Pure. */\nexport function crmPipelineSetupContentFromArgs(args: PluginAiCapabilityArgs): Readonly<Record<string, unknown>> {\n  return pick(args, ['name', 'renameFrom', 'stages', 'wonStage', 'lostStage', 'makeDefault'])\n}\n\n/** The field writer's content for an item: its arguments, as they are. Pure. */\nexport function crmFieldSetupContentFromArgs(args: PluginAiCapabilityArgs): Readonly<Record<string, unknown>> {\n  return pick(args, ['object', 'label', 'type', 'options', 'required'])\n}\n\nexport const crmPipelineAiCapability: PluginAiCapability = {\n  op: CRM_PIPELINE_AI_OP,\n  noun: 'sales pipeline',\n  where: 'CRM → Deals → Pipelines',\n  intents: [\n    'CRM deal pipelines and their stages — \"set up a sales pipeline: Discovery, Proposal, Negotiation, Won/Lost\", rename a pipeline, add or reorder stages, set a stage’s win probability, make a pipeline the default; a Salesforce opportunity pipeline is a deal pipeline',\n  ],\n  argsSchema: {\n    type: 'object',\n    properties: {\n      name: {\n        type: 'string',\n        description:\n          'The pipeline’s name, e.g. \"Agency sales\". An existing pipeline of this name (any case) is updated rather than duplicated; give \"renameFrom\" to rename one.',\n        maxLength: PIPELINE_NAME_MAX,\n      },\n      renameFrom: {\n        type: 'string',\n        description: 'Only to rename: the current name of the pipeline that becomes \"name\".',\n        maxLength: PIPELINE_NAME_MAX,\n      },\n      stages: {\n        type: 'array',\n        description:\n          'The OPEN stages a deal moves through, in order, each a name with an optional win probability in parentheses, e.g. \"Discovery (20%)\". Never Won or Lost: every pipeline already has one of each (name them in wonStage and lostStage). Leave out to keep the stages as they are (a new pipeline then gets the standard set). Stages already in the pipeline and not listed are kept.',\n        items: { type: 'string', maxLength: CRM_SETUP_STAGE_NAME_MAX + 8 },\n        maxItems: CRM_SETUP_OPEN_STAGES_MAX,\n      },\n      wonStage: {\n        type: 'string',\n        description: 'What the closing Won stage is called, where the request names it, e.g. \"Won\". Leave out to keep \"Closed Won\".',\n        maxLength: CRM_SETUP_STAGE_NAME_MAX,\n      },\n      lostStage: {\n        type: 'string',\n        description: 'What the closing Lost stage is called, where the request names it, e.g. \"Lost\". Leave out to keep \"Closed Lost\".',\n        maxLength: CRM_SETUP_STAGE_NAME_MAX,\n      },\n      makeDefault: {\n        type: 'boolean',\n        description: 'true only when the request says new deals should land in this pipeline (its main or default pipeline).',\n      },\n    },\n    required: ['name'],\n    additionalProperties: false,\n  },\n  maxPerPlan: CRM_PIPELINE_AI_MAX_PER_PLAN,\n  freeAllowed: false,\n  feature: CRM_FEATURE,\n  draftResource: CRM_PIPELINE_SETUP_RESOURCE,\n  live: true,\n  // Written without a model: the planner already filled the arguments.\n  estimateCredits: () => 0,\n  degrade: 'omit',\n  draftContent: (item) => crmPipelineSetupContentFromArgs(item.args),\n}\n\nexport const crmFieldAiCapability: PluginAiCapability = {\n  op: CRM_FIELD_AI_OP,\n  noun: 'CRM custom field',\n  where: 'CRM → Fields',\n  intents: [\n    'CRM custom fields on contacts, companies (accounts), deals (opportunities) or leads — \"add a Budget field to opportunities\", \"a Choice field for Industry on companies\"; types text, number, date, choice, checkbox and link only',\n  ],\n  argsSchema: {\n    type: 'object',\n    properties: {\n      object: {\n        type: 'string',\n        description: 'The record it describes: contact; company (an account); deal (an opportunity); lead.',\n        enum: CRM_FIELD_OBJECTS,\n      },\n      label: {\n        type: 'string',\n        description:\n          'The field’s name as people read it, e.g. \"Budget\". A field of this name on the same record (any case) is left as it is rather than duplicated.',\n        maxLength: CRM_FIELD_LABEL_MAX_LENGTH,\n      },\n      type: {\n        type: 'string',\n        description:\n          'What it holds: text; number (also an amount of money or a percentage — there is no currency type); date; select (a Choice from listed options); checkbox (yes or no); url (a link).',\n        enum: CONTACT_FIELD_TYPES,\n      },\n      options: {\n        type: 'array',\n        description: 'For select only: the choices, in order. A select field that exists gains the ones it lacks.',\n        items: { type: 'string', maxLength: CRM_FIELD_OPTION_MAX_LENGTH },\n        maxItems: CRM_FIELD_OPTIONS_MAX,\n      },\n      required: {\n        type: 'boolean',\n        description: 'true only when the request says the field must always be filled in.',\n      },\n    },\n    required: ['object', 'label', 'type'],\n    additionalProperties: false,\n  },\n  maxPerPlan: CRM_FIELD_AI_MAX_PER_PLAN,\n  freeAllowed: false,\n  feature: CRM_FEATURE,\n  draftResource: CRM_FIELD_SETUP_RESOURCE,\n  live: true,\n  estimateCredits: () => 0,\n  degrade: 'omit',\n  draftContent: (item) => crmFieldSetupContentFromArgs(item.args),\n}\n\n/**\n * Registers both capabilities; the console-server declarations call it beside\n * the writers, since only the console runs AI jobs (AGL-3026). Idempotent.\n */\nexport function registerCrmSetupAiCapabilities(): void {\n  registerPluginAiCapability(crmPipelineAiCapability, { pluginId: BUNDLE_ID })\n  registerPluginAiCapability(crmFieldAiCapability, { pluginId: BUNDLE_ID })\n}\n"],"names":["CONTACT_FIELD_TYPES","CRM_FIELD_OBJECTS","registerPluginAiCapability","BUNDLE_ID","CRM_FIELD_LABEL_MAX_LENGTH","CRM_FIELD_OPTION_MAX_LENGTH","CRM_FIELD_OPTIONS_MAX","CRM_FIELD_SETUP_RESOURCE","CRM_PIPELINE_SETUP_RESOURCE","CRM_SETUP_OPEN_STAGES_MAX","CRM_SETUP_STAGE_NAME_MAX","PIPELINE_NAME_MAX","CRM_PIPELINE_AI_OP","CRM_FIELD_AI_OP","CRM_PIPELINE_AI_MAX_PER_PLAN","CRM_FIELD_AI_MAX_PER_PLAN","CRM_FEATURE","pick","args","keys","Object","fromEntries","filter","key","undefined","map","crmPipelineSetupContentFromArgs","crmFieldSetupContentFromArgs","crmPipelineAiCapability","op","noun","where","intents","argsSchema","type","properties","name","description","maxLength","renameFrom","stages","items","maxItems","wonStage","lostStage","makeDefault","required","additionalProperties","maxPerPlan","freeAllowed","feature","draftResource","live","estimateCredits","degrade","draftContent","item","crmFieldAiCapability","object","enum","label","options","registerCrmSetupAiCapabilities","pluginId"],"mappings":"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"}

package/src/lib/server/crm-setup-writers.server.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @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 { PluginResourceDraftWriter } from '@aglyn/aglyn/plugin-manager/plugin-resource-drafts';
+import { type CrmFieldDefinitionDoc } from '../model/crm-setup-content';
+import type { PipelineDoc } from '../model/deal-board-model';
+/**
+ * THE CRM'S SETUP WRITERS (AGL-3746): a deal pipeline and a custom field,
+ * saved for another plugin — Aglyn AI's build — under the CRM's rules.
+ *
+ * Registered on the core's resource-drafts seam as `crm-pipeline` and
+ * `crm-field`. Neither is a draft: a pipeline and a field have no draft
+ * state, and the console saves both live, so these do too, and their AI
+ * capabilities say so (`live`). What they write is exactly what the
+ * console's Pipelines dialog and Fields section write
+ * (`model/crm-setup-content.ts`), and they admit exactly whom the Firestore
+ * rules admit for those writes, since the Admin SDK passes the rules by:
+ *
+ *  - THE SITE is the org's, and THE PLAN carries the CRM (`crm`, Starter and
+ *    up — `orgCarriesCrmSuite`), refused in the suite gate's words;
+ *  - THE MEMBER is an owner, admin or editor (`canWriteOrgData`) whose org
+ *    access is not suspended, holding `data.manage`, the key the whole CRM
+ *    is gated on;
+ *  - THE SCOPE is one the member can create in (`canCreateScoped`): a
+ *    pipeline is stamped as the board's seed stamps it from this site
+ *    (`crmScopeTokens`), a field org-wide, which only an org-wide member
+ *    reaches.
+ *
+ * Idempotent: the job's attempt key is a new pipeline's or field's id, and
+ * an existing pipeline, stage or field is matched by name (see the model),
+ * so asking again changes nothing.
+ */
+type Firestore = FirebaseFirestore.Firestore;
+/** The refusals, in the console's and the routes' words. */
+export declare const CRM_SETUP_ROLE_REFUSAL = "Editing the CRM requires the editor role";
+export declare const CRM_SETUP_PERMISSION_REFUSAL = "Your organization role does not allow editing organization data";
+export declare const CRM_SETUP_SCOPE_REFUSAL = "Your access to this organization does not reach that site";
+export declare const CRM_SETUP_FIELD_SCOPE_REFUSAL = "Custom fields are organization-wide, and your access reaches only some sites";
+/** Who the member is in the org, as the writers ask. */
+export interface CrmSetupMember {
+    role: string;
+    canManageData: boolean;
+    /** The membership itself, for its reach and whether it is suspended. */
+    member: Readonly<Record<string, unknown>>;
+}
+/** The reads and writes the writers make, over the Admin SDK unless a spec hands in its own. */
+export interface CrmSetupStore {
+    /** The pipelines readable under these scope tokens. */
+    pipelines(orgId: string, readTokens: readonly string[]): Promise<PipelineDoc[]>;
+    pipeline(orgId: string, id: string): Promise<PipelineDoc | null>;
+    /** One batch: the new or changed pipeline, and the default flag off the others. */
+    savePipeline(orgId: string, write: {
+        id: string;
+        create?: Record<string, unknown>;
+        update?: Record<string, unknown>;
+        defaultsOff: string[];
+    }, now: Date): Promise<void>;
+    /** Every definition the org holds, retired ones included, to the ceiling and one past it. */
+    fields(orgId: string): Promise<CrmFieldDefinitionDoc[]>;
+    field(orgId: string, id: string): Promise<CrmFieldDefinitionDoc | null>;
+    createField(orgId: string, id: string, document: Record<string, unknown>): Promise<void>;
+    setFieldOptions(orgId: string, id: string, options: string[], now: Date): Promise<void>;
+}
+export interface CrmSetupWriterDeps {
+    store?: CrmSetupStore;
+    /** The org a site belongs to; the platform's lookup otherwise. */
+    orgIdForHost?: (hostId: string) => Promise<string | null>;
+    /** The member, or `null` when they are not one; the platform's otherwise. */
+    member?: (uid: string, orgId: string) => Promise<CrmSetupMember | null>;
+}
+/** The CRM's collections over the Admin SDK. */
+export declare function adminCrmSetupStore(firestore?: () => Firestore): CrmSetupStore;
+/** The `crm-pipeline` writer: creates or brings a pipeline to the ask. */
+export declare function createCrmPipelineSetupWriter(deps?: CrmSetupWriterDeps): PluginResourceDraftWriter;
+/** The `crm-field` writer: creates a custom field, or finds the one asked for. */
+export declare function createCrmFieldSetupWriter(deps?: CrmSetupWriterDeps): PluginResourceDraftWriter;
+export declare const crmPipelineSetupWriter: PluginResourceDraftWriter;
+export declare const crmFieldSetupWriter: PluginResourceDraftWriter;
+export {};

package/src/lib/server/crm-setup-writers.server.js

@@ -0,0 +1,315 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { consentGroupForHost } from "@aglyn/aglyn/app-utils/consent-groups";
+import { CONTACT_FIELDS_MAX_PER_ORG } from "@aglyn/aglyn/app-utils/contact-custom-fields";
+import { CRM_COLLECTIONS, crmReadTokens, crmScopeTokens } from "@aglyn/aglyn/app-utils/crm";
+import { memberCanSee } from "@aglyn/aglyn/app-utils/organizations";
+import { checkEntitlement } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { ORG_SCOPE_TOKEN } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { memberHasOrgPermission, resolveOrgIdForHost, resolveOrgMembership } from "@aglyn/tenant-data-admin/server/organizations";
+import { FieldPath } from "firebase-admin/firestore";
+import { checkCrmFieldSetup, checkCrmPipelineSetup, crmPipelineSetupFacts, planCrmFieldSetup, planCrmPipelineSetup, readCrmFieldSetup, readCrmPipelineSetup } from "../model/crm-setup-content.js";
+import { crmSuiteRefusalMessage } from "./suite-gate.js";
+/** The refusals, in the console's and the routes' words. */ export const CRM_SETUP_ROLE_REFUSAL = 'Editing the CRM requires the editor role';
+export const CRM_SETUP_PERMISSION_REFUSAL = 'Your organization role does not allow editing organization data';
+export const CRM_SETUP_SCOPE_REFUSAL = 'Your access to this organization does not reach that site';
+export const CRM_SETUP_FIELD_SCOPE_REFUSAL = 'Custom fields are organization-wide, and your access reaches only some sites';
+/** Roles allowed to write the CRM's setup — the rules' `canWriteOrgData()`. */ const WRITER_ROLES = new Set([
+    'owner',
+    'admin',
+    'editor'
+]);
+/** The most pipelines one site's read returns, as the board reads them. */ const PIPELINE_READ_LIMIT = 50;
+async function platformMember(uid, orgId) {
+    var _member_role;
+    const membership = await resolveOrgMembership(uid, orgId);
+    const member = membership == null ? void 0 : membership.member;
+    if (!member) return null;
+    return {
+        role: String((_member_role = member.role) != null ? _member_role : ''),
+        canManageData: await memberHasOrgPermission(orgId, member, 'data.manage'),
+        member: member
+    };
+}
+/** The CRM's collections over the Admin SDK. */ export function adminCrmSetupStore(firestore = ()=>firebaseAdmin.app().firestore()) {
+    const org = (orgId)=>firestore().collection('orgs').doc(orgId);
+    const pipelinesOf = (orgId)=>org(orgId).collection(CRM_COLLECTIONS.pipelines);
+    const fieldsOf = (orgId)=>org(orgId).collection(CRM_COLLECTIONS.contactFields);
+    const withId = (snap)=>_extends({}, snap.data(), {
+            $id: snap.id
+        });
+    return {
+        pipelines: async (orgId, readTokens)=>{
+            const snap = await pipelinesOf(orgId).where('visibleTo', 'array-contains-any', [
+                ...readTokens
+            ]).orderBy(FieldPath.documentId()).limit(PIPELINE_READ_LIMIT).get();
+            return snap.docs.map((one)=>withId(one));
+        },
+        pipeline: async (orgId, id)=>{
+            const snap = await pipelinesOf(orgId).doc(id).get();
+            return snap.exists ? withId(snap) : null;
+        },
+        savePipeline: async (orgId, write, now)=>{
+            const batch = firestore().batch();
+            const ref = pipelinesOf(orgId).doc(write.id);
+            if (write.create) batch.create(ref, write.create);
+            else if (write.update) batch.update(ref, _extends({}, write.update, {
+                updatedAt: now
+            }));
+            for (const id of write.defaultsOff){
+                batch.update(pipelinesOf(orgId).doc(id), {
+                    isDefault: false,
+                    updatedAt: now
+                });
+            }
+            await batch.commit();
+        },
+        fields: async (orgId)=>{
+            const snap = await fieldsOf(orgId).limit(CONTACT_FIELDS_MAX_PER_ORG + 1).get();
+            return snap.docs.map((one)=>withId(one));
+        },
+        field: async (orgId, id)=>{
+            const snap = await fieldsOf(orgId).doc(id).get();
+            return snap.exists ? withId(snap) : null;
+        },
+        createField: async (orgId, id, document)=>{
+            await fieldsOf(orgId).doc(id).create(document);
+        },
+        setFieldOptions: async (orgId, id, options, now)=>{
+            await fieldsOf(orgId).doc(id).update({
+                options,
+                updatedAt: now
+            });
+        }
+    };
+}
+/** The scope a pipeline made from this site is stamped with: the board seed's. */ function pipelineScope(context) {
+    var _context_org;
+    const org = (_context_org = context.org) != null ? _context_org : null;
+    return crmScopeTokens(org, consentGroupForHost(org, context.hostId));
+}
+/** What a pipeline's board at this site reads: the org's rows and the site group's. */ function pipelineReadTokens(context) {
+    var _context_org;
+    const org = (_context_org = context.org) != null ? _context_org : null;
+    return crmReadTokens(consentGroupForHost(org, context.hostId));
+}
+function pipelineRecord(pipeline) {
+    var _pipeline_name, _pipeline_stages;
+    return {
+        id: pipeline.$id,
+        name: String((_pipeline_name = pipeline.name) != null ? _pipeline_name : ''),
+        versionId: null,
+        facts: crmPipelineSetupFacts((_pipeline_stages = pipeline.stages) != null ? _pipeline_stages : [])
+    };
+}
+function fieldRecord(field) {
+    var _field_label, _field_object;
+    return {
+        id: field.$id,
+        name: String((_field_label = field.label) != null ? _field_label : ''),
+        versionId: null,
+        facts: _extends({
+            object: (_field_object = field.object) != null ? _field_object : 'contact',
+            key: field.key,
+            type: field.type
+        }, field.options ? {
+            options: field.options
+        } : {})
+    };
+}
+function createCrmSetupGate(deps) {
+    var _deps_orgIdForHost, _deps_member;
+    const orgIdForHost = (_deps_orgIdForHost = deps.orgIdForHost) != null ? _deps_orgIdForHost : (hostId)=>resolveOrgIdForHost(hostId);
+    const memberOf = (_deps_member = deps.member) != null ? _deps_member : platformMember;
+    /** Everything but the scope: the site is the org's, the plan, the member's role and permission. */ return async (context, scope, scopeRefusal)=>{
+        if (await orgIdForHost(context.hostId) !== context.orgId) return {
+            status: 404,
+            error: 'Unknown site'
+        };
+        if (!checkEntitlement(context.org, 'crm')) {
+            return {
+                status: 403,
+                error: crmSuiteRefusalMessage('Setting up the CRM')
+            };
+        }
+        const member = await memberOf(context.uid, context.orgId);
+        if (!member || !WRITER_ROLES.has(member.role) || member.member['orgSuspended'] === true) {
+            return {
+                status: 403,
+                error: CRM_SETUP_ROLE_REFUSAL
+            };
+        }
+        if (!member.canManageData) return {
+            status: 403,
+            error: CRM_SETUP_PERMISSION_REFUSAL
+        };
+        if (!memberCanSee(member.member, scope)) return {
+            status: 403,
+            error: scopeRefusal
+        };
+        return null;
+    };
+}
+/** The `crm-pipeline` writer: creates or brings a pipeline to the ask. */ export function createCrmPipelineSetupWriter(deps = {}) {
+    var _deps_store, _deps_orgIdForHost;
+    const store = (_deps_store = deps.store) != null ? _deps_store : adminCrmSetupStore();
+    const orgIdForHost = (_deps_orgIdForHost = deps.orgIdForHost) != null ? _deps_orgIdForHost : (hostId)=>resolveOrgIdForHost(hostId);
+    const gate = createCrmSetupGate(deps);
+    return {
+        refusal: (context)=>gate(context, pipelineScope(context), CRM_SETUP_SCOPE_REFUSAL),
+        check: (content)=>checkCrmPipelineSetup(content),
+        read: async ({ hostId, id })=>{
+            const orgId = await orgIdForHost(hostId);
+            const pipeline = orgId ? await store.pipeline(orgId, id) : null;
+            return pipeline ? pipelineRecord(pipeline) : null;
+        },
+        write: async (request)=>{
+            const read = readCrmPipelineSetup(request.content);
+            if (read.ok === false) return {
+                ok: false,
+                status: 400,
+                error: read.problems[0]
+            };
+            const visibleTo = pipelineScope(request);
+            const refused = await gate(request, visibleTo, CRM_SETUP_SCOPE_REFUSAL);
+            if (refused) return _extends({
+                ok: false
+            }, refused);
+            // Asked again under the same id: the pipeline it already made.
+            const made = await store.pipeline(request.orgId, request.id);
+            if (made) return _extends({
+                ok: true,
+                replayed: true
+            }, pipelineRecord(made));
+            const pipelines = await store.pipelines(request.orgId, pipelineReadTokens(request));
+            const plan = planCrmPipelineSetup(read.value, pipelines, {
+                visibleTo,
+                hostId: request.hostId,
+                uid: request.uid,
+                nowMs: request.now.getTime()
+            });
+            if (plan.kind === 'refuse') return {
+                ok: false,
+                status: 409,
+                error: plan.error
+            };
+            if (plan.kind === 'create') {
+                await store.savePipeline(request.orgId, {
+                    id: request.id,
+                    create: plan.document,
+                    defaultsOff: plan.defaultsOff
+                }, request.now);
+                return _extends({
+                    ok: true,
+                    replayed: false
+                }, pipelineRecord(_extends({}, plan.document, {
+                    $id: request.id
+                })));
+            }
+            const existing = pipelines.find((one)=>one.$id === plan.id);
+            const changed = Object.keys(plan.patch).length > 0 || plan.defaultsOff.length > 0;
+            if (changed) {
+                await store.savePipeline(request.orgId, {
+                    id: plan.id,
+                    update: plan.patch,
+                    defaultsOff: plan.defaultsOff
+                }, request.now);
+            }
+            return _extends({
+                ok: true,
+                replayed: !changed
+            }, pipelineRecord(_extends({}, existing, plan.patch)));
+        }
+    };
+}
+/** The `crm-field` writer: creates a custom field, or finds the one asked for. */ export function createCrmFieldSetupWriter(deps = {}) {
+    var _deps_store, _deps_orgIdForHost;
+    const store = (_deps_store = deps.store) != null ? _deps_store : adminCrmSetupStore();
+    const orgIdForHost = (_deps_orgIdForHost = deps.orgIdForHost) != null ? _deps_orgIdForHost : (hostId)=>resolveOrgIdForHost(hostId);
+    const gate = createCrmSetupGate(deps);
+    const scope = [
+        ORG_SCOPE_TOKEN
+    ];
+    return {
+        refusal: (context)=>gate(context, scope, CRM_SETUP_FIELD_SCOPE_REFUSAL),
+        check: (content)=>checkCrmFieldSetup(content),
+        read: async ({ hostId, id })=>{
+            const orgId = await orgIdForHost(hostId);
+            const field = orgId ? await store.field(orgId, id) : null;
+            return field ? fieldRecord(field) : null;
+        },
+        write: async (request)=>{
+            var _existing_options;
+            const read = readCrmFieldSetup(request.content);
+            if (read.ok === false) return {
+                ok: false,
+                status: 400,
+                error: read.problems[0]
+            };
+            const refused = await gate(request, scope, CRM_SETUP_FIELD_SCOPE_REFUSAL);
+            if (refused) return _extends({
+                ok: false
+            }, refused);
+            const made = await store.field(request.orgId, request.id);
+            if (made) return _extends({
+                ok: true,
+                replayed: true
+            }, fieldRecord(made));
+            const definitions = await store.fields(request.orgId);
+            const plan = planCrmFieldSetup(read.value, definitions, {
+                hostId: request.hostId,
+                now: request.now,
+                visibleTo: scope
+            });
+            if (plan.kind === 'refuse') return {
+                ok: false,
+                status: plan.status,
+                error: plan.error
+            };
+            if (plan.kind === 'create') {
+                await store.createField(request.orgId, request.id, plan.document);
+                return _extends({
+                    ok: true,
+                    replayed: false
+                }, fieldRecord(_extends({}, plan.document, {
+                    $id: request.id
+                })));
+            }
+            const existing = definitions.find((one)=>one.$id === plan.id);
+            if (!plan.options.length) return _extends({
+                ok: true,
+                replayed: true
+            }, fieldRecord(existing));
+            const options = [
+                ...(_existing_options = existing.options) != null ? _existing_options : [],
+                ...plan.options
+            ];
+            await store.setFieldOptions(request.orgId, plan.id, options, request.now);
+            return _extends({
+                ok: true,
+                replayed: false
+            }, fieldRecord(_extends({}, existing, {
+                options
+            })));
+        }
+    };
+}
+export const crmPipelineSetupWriter = createCrmPipelineSetupWriter();
+export const crmFieldSetupWriter = createCrmFieldSetupWriter();
+
+//# sourceMappingURL=crm-setup-writers.server.js.map