@aglyn/plugins-crm 1.0.0-beta.244 → 1.0.0-beta.247

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

@@ -0,0 +1,290 @@
+/**
+ * @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 { CRM_PICKLIST_VALUES_LISTS, CRM_PICKLIST_VALUES_SETUP_MAX, CRM_PICKLIST_VALUES_SETUP_RESOURCE } from "../model/crm-picklist-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';
+export const CRM_PICKLIST_VALUES_AI_OP = 'crm-picklist-values';
+/** 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;
+export const CRM_PICKLIST_VALUES_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',
+        'currency',
+        '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, link and currency (an amount of money: budget, deal size, revenue)'
+    ],
+    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 (a count or a percentage); currency (an amount of money — a budget, a price, revenue — with "currency"); 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
+            },
+            currency: {
+                type: 'string',
+                description: 'For currency only: the ISO 4217 code its amounts are in, e.g. "EUR", when the request names one. Leave out for US dollars.',
+                maxLength: 3
+            },
+            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)
+};
+/** The picklist values writer's content for an item: its arguments, as they are. Pure. */ export function crmPicklistValuesSetupContentFromArgs(args) {
+    return pick(args, [
+        'list',
+        'object',
+        'field',
+        'values',
+        'meaning',
+        'group'
+    ]);
+}
+/**
+ * VALUES ADDED TO A CRM PICKLIST (AGL-3756): "add Nurturing as a lead
+ * status", "add Trade show and Podcast as lead sources", "add Renewal as a
+ * deal type", "add Enterprise to the Tier choices on companies". Written by
+ * the `crm-picklist-values` writer, so the rules are the Fields page's: only
+ * adds, matched without capitals, never removes, renames, reorders or
+ * reactivates. Live, as the console's Add value is; 0 credits.
+ */ export const crmPicklistValuesAiCapability = {
+    op: CRM_PICKLIST_VALUES_AI_OP,
+    noun: 'CRM picklist values',
+    where: 'CRM → Fields',
+    intents: [
+        'add values to a CRM picklist — a lead status ("Contacted", meaning Working), a lead source (Inbound or Outbound), a deal (opportunity) type or contact role, a company (account) type, industry, rating or ownership, a salutation, a task status, priority, type or subject — or add choices to a custom Choice field; only adds, never removes or renames'
+    ],
+    argsSchema: {
+        type: 'object',
+        properties: {
+            list: {
+                type: 'string',
+                description: 'Which list: leadStatus, leadSource, opportunityType (a deal’s Type), opportunityContactRole, accountType (a company’s Type), industry, rating, ownership, salutation, taskStatus, taskPriority, taskType, taskSubject; or custom for a custom Choice field (then give object and field).',
+                enum: CRM_PICKLIST_VALUES_LISTS
+            },
+            object: {
+                type: 'string',
+                description: 'For custom only: the record the Choice field is on — contact; company; deal; lead.',
+                enum: CRM_FIELD_OBJECTS
+            },
+            field: {
+                type: 'string',
+                description: 'For custom only: the Choice field’s name, e.g. "Tier".',
+                maxLength: 80
+            },
+            values: {
+                type: 'array',
+                description: 'The values to add, in order, e.g. ["Trade show", "Podcast"]. A value the list already has (any capitals) is left as it is. Never values to remove or rename.',
+                items: {
+                    type: 'string',
+                    maxLength: 120
+                },
+                maxItems: CRM_PICKLIST_VALUES_SETUP_MAX
+            },
+            meaning: {
+                type: 'string',
+                description: 'Required for leadStatus, taskStatus, taskPriority and taskType: what every value in this item means. leadStatus: new, nurturing, working or unqualified (never qualified); taskStatus: open or done; taskPriority: low, normal or high; taskType: call, email, meeting or todo. Split values of different meanings into separate items.',
+                maxLength: 40
+            },
+            group: {
+                type: 'string',
+                description: 'For leadSource only: inbound (the lead came to them) or outbound (they went to the lead), when the request says or it is plain.',
+                enum: [
+                    'inbound',
+                    'outbound'
+                ]
+            }
+        },
+        required: [
+            'list',
+            'values'
+        ],
+        additionalProperties: false
+    },
+    maxPerPlan: CRM_PICKLIST_VALUES_AI_MAX_PER_PLAN,
+    freeAllowed: false,
+    feature: CRM_FEATURE,
+    draftResource: CRM_PICKLIST_VALUES_SETUP_RESOURCE,
+    live: true,
+    estimateCredits: ()=>0,
+    degrade: 'omit',
+    draftContent: (item)=>crmPicklistValuesSetupContentFromArgs(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
+    });
+    registerPluginAiCapability(crmPicklistValuesAiCapability, {
+        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 {\n  CRM_PICKLIST_VALUES_LISTS,\n  CRM_PICKLIST_VALUES_SETUP_MAX,\n  CRM_PICKLIST_VALUES_SETUP_RESOURCE,\n} from '../model/crm-picklist-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'\nexport const CRM_PICKLIST_VALUES_AI_OP = 'crm-picklist-values'\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\nexport const CRM_PICKLIST_VALUES_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', 'currency', '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, link and currency (an amount of money: budget, deal size, revenue)',\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 (a count or a percentage); currency (an amount of money — a budget, a price, revenue — with \"currency\"); 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      currency: {\n        type: 'string',\n        description:\n          'For currency only: the ISO 4217 code its amounts are in, e.g. \"EUR\", when the request names one. Leave out for US dollars.',\n        maxLength: 3,\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/** The picklist values writer's content for an item: its arguments, as they are. Pure. */\nexport function crmPicklistValuesSetupContentFromArgs(args: PluginAiCapabilityArgs): Readonly<Record<string, unknown>> {\n  return pick(args, ['list', 'object', 'field', 'values', 'meaning', 'group'])\n}\n\n/**\n * VALUES ADDED TO A CRM PICKLIST (AGL-3756): \"add Nurturing as a lead\n * status\", \"add Trade show and Podcast as lead sources\", \"add Renewal as a\n * deal type\", \"add Enterprise to the Tier choices on companies\". Written by\n * the `crm-picklist-values` writer, so the rules are the Fields page's: only\n * adds, matched without capitals, never removes, renames, reorders or\n * reactivates. Live, as the console's Add value is; 0 credits.\n */\nexport const crmPicklistValuesAiCapability: PluginAiCapability = {\n  op: CRM_PICKLIST_VALUES_AI_OP,\n  noun: 'CRM picklist values',\n  where: 'CRM → Fields',\n  intents: [\n    'add values to a CRM picklist — a lead status (\"Contacted\", meaning Working), a lead source (Inbound or Outbound), a deal (opportunity) type or contact role, a company (account) type, industry, rating or ownership, a salutation, a task status, priority, type or subject — or add choices to a custom Choice field; only adds, never removes or renames',\n  ],\n  argsSchema: {\n    type: 'object',\n    properties: {\n      list: {\n        type: 'string',\n        description:\n          'Which list: leadStatus, leadSource, opportunityType (a deal’s Type), opportunityContactRole, accountType (a company’s Type), industry, rating, ownership, salutation, taskStatus, taskPriority, taskType, taskSubject; or custom for a custom Choice field (then give object and field).',\n        enum: CRM_PICKLIST_VALUES_LISTS,\n      },\n      object: {\n        type: 'string',\n        description: 'For custom only: the record the Choice field is on — contact; company; deal; lead.',\n        enum: CRM_FIELD_OBJECTS,\n      },\n      field: {\n        type: 'string',\n        description: 'For custom only: the Choice field’s name, e.g. \"Tier\".',\n        maxLength: 80,\n      },\n      values: {\n        type: 'array',\n        description:\n          'The values to add, in order, e.g. [\"Trade show\", \"Podcast\"]. A value the list already has (any capitals) is left as it is. Never values to remove or rename.',\n        items: { type: 'string', maxLength: 120 },\n        maxItems: CRM_PICKLIST_VALUES_SETUP_MAX,\n      },\n      meaning: {\n        type: 'string',\n        description:\n          'Required for leadStatus, taskStatus, taskPriority and taskType: what every value in this item means. leadStatus: new, nurturing, working or unqualified (never qualified); taskStatus: open or done; taskPriority: low, normal or high; taskType: call, email, meeting or todo. Split values of different meanings into separate items.',\n        maxLength: 40,\n      },\n      group: {\n        type: 'string',\n        description: 'For leadSource only: inbound (the lead came to them) or outbound (they went to the lead), when the request says or it is plain.',\n        enum: ['inbound', 'outbound'],\n      },\n    },\n    required: ['list', 'values'],\n    additionalProperties: false,\n  },\n  maxPerPlan: CRM_PICKLIST_VALUES_AI_MAX_PER_PLAN,\n  freeAllowed: false,\n  feature: CRM_FEATURE,\n  draftResource: CRM_PICKLIST_VALUES_SETUP_RESOURCE,\n  live: true,\n  estimateCredits: () => 0,\n  degrade: 'omit',\n  draftContent: (item) => crmPicklistValuesSetupContentFromArgs(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  registerPluginAiCapability(crmPicklistValuesAiCapability, { 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","CRM_PICKLIST_VALUES_LISTS","CRM_PICKLIST_VALUES_SETUP_MAX","CRM_PICKLIST_VALUES_SETUP_RESOURCE","PIPELINE_NAME_MAX","CRM_PIPELINE_AI_OP","CRM_FIELD_AI_OP","CRM_PICKLIST_VALUES_AI_OP","CRM_PIPELINE_AI_MAX_PER_PLAN","CRM_FIELD_AI_MAX_PER_PLAN","CRM_PICKLIST_VALUES_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","currency","crmPicklistValuesSetupContentFromArgs","crmPicklistValuesAiCapability","list","field","values","meaning","group","registerCrmSetupAiCapabilities","pluginId"],"mappings":"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"}

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

@@ -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.
+ */
+import { type CrmPicklist, type CrmPicklistId, type CrmPicklistObject, type CrmPicklistTarget } from '@aglyn/aglyn/app-utils/crm';
+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";
+export declare const CRM_SETUP_PICKLIST_SCOPE_REFUSAL = "Picklists 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>;
+    /** A picklist's stored document, or `null` for an org that never stored one (AGL-3756). */
+    picklist(orgId: string, id: CrmPicklistId): Promise<Readonly<Record<string, unknown>> | null>;
+    /**
+     * Read a picklist and write it back in one transaction, as the console's
+     * route does, so a person editing the list at the same moment is not
+     * overwritten. `change` answers the list to write, or `null` for none.
+     */
+    changePicklist<T>(orgId: string, id: CrmPicklistId, change: (stored: Readonly<Record<string, unknown>> | null) => {
+        write: CrmPicklist | null;
+        result: T;
+    }, stamp: {
+        hostId: string;
+    }): Promise<T>;
+    /** A value's group onto every record of `object` holding `label` (a lead's `leadSourceDirection`). */
+    regroup(orgId: string, object: CrmPicklistObject, target: CrmPicklistTarget, label: string, group: string | null): Promise<number>;
+}
+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;
+/**
+ * The `crm-picklist-values` writer: adds values to a standard CRM picklist
+ * or a custom Choice field's choices, never removing, renaming, reordering
+ * or reactivating one. Gated as the Fields page is — the `crm` feature, an
+ * owner, admin or editor with `data.manage` — and org-wide, as every
+ * picklist and field document is. A lead source added where records
+ * already hold its label files them under its group (`leadSourceDirection`),
+ * as the console's route does (AGL-3577).
+ */
+export declare function createCrmPicklistValuesSetupWriter(deps?: CrmSetupWriterDeps): PluginResourceDraftWriter;
+export declare const crmPicklistValuesSetupWriter: PluginResourceDraftWriter;
+export {};