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

package/src/lib/model/record-facts.d.ts

@@ -14,35 +14,45 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type ConsentGroup, type ContactFieldDefinition, type ContactInteraction, type CrmActivity, type CrmCompany, type CrmDeal, type CrmPipeline, type CrmTask } from '@aglyn/aglyn/server';
+import { type AglynPostalAddress, type ConsentGroup, type ContactFieldDefinition, type ContactInteraction, type CrmActivity, type CrmCompany, type CrmDeal, type CrmFieldObject, type CrmPicklist, type CrmPipeline, type CrmTask } from '@aglyn/aglyn/server';
 /**
  * WHAT THE CRM TELLS ANOTHER PLUGIN ABOUT ONE OF ITS RECORDS (AGL-2917).
  *
  * The facts a reader on the core's record-facts seam reports: one contact,
  * company, deal or lead as a person on the team sees it, and the fields a
  * spreadsheet import may fill. The server half reads the documents and
- * applies who may see them (`server/record-facts.ts`); this half decides
- * which of their fields leave the CRM at all, so the list below is the whole
- * of what a caller — an assistant summarizing a record, an automation
- * deciding on one — can pass on.
+ * applies who may see them (`server/record-facts.ts`); this half shapes
+ * them, so the list below is the whole of what a caller — an assistant
+ * summarizing a record, an automation deciding on one — can pass on.
  *
- * ## What never leaves
+ * ## The whole record (AGL-3520)
  *
- * No email address, phone number or postal address of anyone; no marketing
- * consent; no custom field VALUE; no team member's name or id; no document
- * id of any record; no file; no order or payment detail beyond a count. A
- * logged email carries its subject and a cut of its body, never the address
- * it went to or came from. An import catalog carries field keys, labels and
- * types, never a row of the file.
+ * These builders answer only for an organization with
+ * `release_crm_assist_whole_record` on; with it off, the readers answer
+ * `record-facts-disclosed.ts`, the fields the published pages promise.
+ * A record is reported as the CRM shows it: every standard field —
+ * Salesforce's included — with its email addresses, phone numbers, postal
+ * addresses, birthdate, assistant and reports-to; the labels of its
+ * picklists as the record holds them; its custom field values under their
+ * labels; its marketing consent; its notes, newest timeline entries and
+ * open tasks and deals. Text a person wrote is reported as written.
  *
- * Every text a person wrote into a record — a name, a job title, a tag, notes,
- * a logged activity, a capture's summary, a task's or a deal's title, a
- * reason — is reported as written, except that an email address or a phone
- * number inside it is replaced by a placeholder first ({@link crmFactProse}):
- * an import that put an address in the name column leaves no address behind.
- * What the workspace configured — pipeline, stage and field names — and a
- * company's domain are reported as they are. A postal address typed into a
- * note is not recognized and leaves as typed.
+ * ## What still never leaves
+ *
+ * No authentication token, no account identifier and no internal record
+ * id. A related record — the company a person works for, the contact a deal
+ * is with, the person someone reports to, a parent company, a campaign — is
+ * named by its name; a team member by their display name. The one id a
+ * caller is handed is a pipeline stage's, which a stage proposal must name.
+ * An import catalog carries field keys, labels and types, never a row of
+ * the file.
+ *
+ * ## Bounded
+ *
+ * Every list and every long text is cut — notes to
+ * {@link CRM_FACTS_NOTES_MAX}, a timeline entry to {@link CRM_FACTS_TEXT_MAX},
+ * at most {@link CRM_FACTS_CUSTOM_FIELDS_MAX} custom fields — so a record
+ * holding everything still fits the request a caller builds from it.
  *
  * ## Stable bytes
  *
@@ -72,22 +82,29 @@ export declare const CRM_FACTS_TASKS_MAX = 8;
 export declare const CRM_FACTS_DEALS_MAX = 5;
 /** Tags reported for a record. */
 export declare const CRM_FACTS_TAGS_MAX = 10;
-/** How much of a logged activity's text, or a platform capture's summary, is reported. */
+/** How much of a logged activity's text, a capture's summary, a task's notes or a custom value is reported. */
 export declare const CRM_FACTS_TEXT_MAX = 280;
 /** How much of a record's notes is reported. */
 export declare const CRM_FACTS_NOTES_MAX = 600;
 /** How long a name, a title or a subject may run. */
 export declare const CRM_FACTS_LABEL_MAX = 120;
-/** Custom fields an import catalog reports. */
+/** Custom fields an import catalog, or a record, reports. */
 export declare const CRM_FACTS_CUSTOM_FIELDS_MAX = 40;
+/** Products a deal's facts list. */
+export declare const CRM_FACTS_PRODUCTS_MAX = 20;
+/** Email addresses and campaigns a record's facts list. */
+export declare const CRM_FACTS_LIST_MAX = 10;
 /** One thing that happened, as a record's timeline reports it. */
 export interface CrmTimelineFact {
     /** The UTC day it happened, `YYYY-MM-DD`. */
     on: string;
     /** What happened: a logged kind (Call, Email) or the capture it came through (Form, Booking). */
     kind: string;
-    /** `outbound` or `inbound` for an email; absent otherwise. */
+    /** `outbound` or `inbound` for an email; also `internal` for a call (AGL-3517); absent otherwise. */
     direction?: string;
+    /** Who an email came from and went to, as the activity recorded them (AGL-3520). */
+    from?: string;
+    to?: string;
     subject?: string;
     text?: string;
     outcome?: string;
@@ -97,11 +114,19 @@ export interface CrmTimelineFact {
 /** One task still to do. */
 export interface CrmTaskFact {
     title: string;
+    /** The org's Type label when the task holds one, else its kind's name (AGL-3517). */
     kind: string;
+    /** The meaning — `high`, `normal` or `low` — whatever the org calls it. */
     priority: string;
+    /** The org's Status label ("In Progress"), when the task holds one (AGL-3517). */
+    status?: string;
     /** The UTC day it is due, or `null` for a task with no due date. */
     due: string | null;
     overdue: boolean;
+    /** Who it is assigned to, by name (AGL-3520). */
+    assignee?: string;
+    /** What the task says beyond its title (AGL-3520). */
+    notes?: string;
 }
 /** One deal, as a contact's or a company's facts report it. */
 export interface CrmDealFact {
@@ -111,12 +136,48 @@ export interface CrmDealFact {
     amount: string | null;
     expectedClose: string | null;
 }
+/** One custom field's value, under the label the org gave the field (AGL-3520). */
+export interface CrmCustomFact {
+    label: string;
+    value: string;
+}
+/** One product on a deal (AGL-3520). */
+export interface CrmProductFact {
+    name: string;
+    quantity: number;
+    unitAmount: string | null;
+}
 export interface CrmContactFacts {
     record: 'contact';
     name: string;
+    salutation: string;
+    firstName: string;
+    lastName: string;
+    /** Every address the person is reached at: the canonical one first (AGL-3520). */
+    emails: string[];
+    phone: string;
+    mobilePhone: string;
+    homePhone: string;
+    otherPhone: string;
+    fax: string;
     jobTitle: string;
+    department: string;
+    /** A `YYYY-MM-DD` day, or `''`. */
+    birthdate: string;
+    assistant: string;
+    assistantPhone: string;
+    /** The name of the contact the person reports to (AGL-3515). */
+    reportsTo: string;
+    mailingAddress: string;
+    otherAddress: string;
+    /** They asked not to be phoned — a fact an assistant drafting a next step must respect. */
+    doNotCall: boolean;
     company: string;
     lifecycleStage: string;
+    leadSource: string;
+    owner: string;
+    /** Whether the person agreed to marketing email from this site, and since when. */
+    marketingConsent: string;
     tags: string[];
     /** The captures that met the person: Form, Booking, Customer. */
     sources: string[];
@@ -124,6 +185,7 @@ export interface CrmContactFacts {
     lastPurchase: string | null;
     since: string | null;
     lastEmailEngagement: string | null;
+    custom: CrmCustomFact[];
     notes: string;
     timeline: CrmTimelineFact[];
     openTasks: CrmTaskFact[];
@@ -133,10 +195,30 @@ export interface CrmCompanyFacts {
     record: 'company';
     name: string;
     domain: string;
+    website: string;
+    phone: string;
+    fax: string;
     industry: string;
+    /** Salesforce's Account fields (AGL-3514). */
+    type: string;
+    rating: string;
+    ownership: string;
+    accountSource: string;
+    employees: number | null;
+    annualRevenue: string | null;
+    accountNumber: string;
+    site: string;
+    tickerSymbol: string;
+    sicCode: string;
+    billingAddress: string;
+    shippingAddress: string;
+    /** The name of the company this one sits under. */
+    parentCompany: string;
+    owner: string;
     tags: string[];
     people: number;
     since: string | null;
+    custom: CrmCustomFact[];
     notes: string;
     timeline: CrmTimelineFact[];
     openTasks: CrmTaskFact[];
@@ -147,7 +229,21 @@ export interface CrmStageFact {
     id: string;
     name: string;
     kind: 'open' | 'won' | 'lost';
+    /** Chance of closing from the stage, 0–100 (AGL-3516). */
+    probability: number;
+    /** The forecast category a deal takes in the stage, as its label. */
+    forecastCategory: string;
 }
+/** One contact on a deal, as the facts name them (AGL-3521). */
+export interface CrmContactRoleFact {
+    /** The person's name, or `''` where it could not be read. */
+    name: string;
+    /** The role's label, or `''` for none. */
+    role: string;
+    primary: boolean;
+}
+/** The contacts a deal's facts name — the committee, not the whole list. */
+export declare const CRM_FACTS_CONTACT_ROLES_MAX = 10;
 export interface CrmDealFacts {
     record: 'deal';
     title: string;
@@ -160,11 +256,28 @@ export interface CrmDealFacts {
     expectedClose: string | null;
     inStageSince: string | null;
     lostReason: string;
+    type: string;
+    leadSource: string;
+    nextStep: string;
+    /** The deal's own odds when it overrides the stage's, else the stage's; `null` for neither. */
+    probability: number | null;
+    /** The forecast category's label. */
+    forecastCategory: string;
+    /** The campaign the deal is credited to, by name (AGL-3520). */
+    campaign: string;
     /** The name of the person the deal is with, as the deal copied it. */
     contact: string;
+    /**
+     * Every contact on the deal and the part each plays (AGL-3521), the
+     * Primary first — named as the reader resolved them, at most
+     * {@link CRM_FACTS_CONTACT_ROLES_MAX}.
+     */
+    contactRoles: CrmContactRoleFact[];
     company: string;
-    products: number;
+    owner: string;
+    products: CrmProductFact[];
     since: string | null;
+    custom: CrmCustomFact[];
     notes: string;
     timeline: CrmTimelineFact[];
     openTasks: CrmTaskFact[];
@@ -172,7 +285,30 @@ export interface CrmDealFacts {
 export interface CrmLeadFacts {
     record: 'lead';
     name: string;
+    salutation: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    mobilePhone: string;
+    fax: string;
+    website: string;
+    address: string;
+    company: string;
+    jobTitle: string;
+    leadSource: string;
+    industry: string;
+    rating: string;
+    employees: number | null;
+    annualRevenue: string | null;
+    /** They asked not to be phoned — a fact an assistant drafting a next step must respect. */
+    doNotCall: boolean;
     status: string;
+    owner: string;
+    /** The campaigns the lead is filed under, by name. */
+    campaigns: string[];
+    marketingConsent: string;
+    tags: string[];
     /** Where the lead was captured: Form, Booking, Sign-up, Import. */
     sources: string[];
     captures: number;
@@ -181,8 +317,10 @@ export interface CrmLeadFacts {
     assigned: boolean;
     converted: boolean;
     unqualifiedReason: string;
+    custom: CrmCustomFact[];
     notes: string;
     timeline: CrmTimelineFact[];
+    openTasks: CrmTaskFact[];
 }
 export type CrmRecordFacts = CrmContactFacts | CrmCompanyFacts | CrmDealFacts | CrmLeadFacts;
 /** What a column of a file may hold, as an import field expects it. */
@@ -200,6 +338,18 @@ export interface CrmImportFacts {
     collection: CrmImportFactsCollection;
     fields: CrmImportFieldFact[];
 }
+/**
+ * What the server half resolves for a builder, because a fact names a
+ * related record or a person and the builder reads no document: a team
+ * member's display name, the record's custom field definitions, and the
+ * names of the records it points at.
+ */
+export interface CrmFactsNames {
+    /** A team member's display name for a uid; `''` when the roster has none. */
+    member?: (uid: string) => string;
+    /** The org's custom field definitions, every object's; each builder takes its own. */
+    customFields?: ReadonlyArray<Partial<ContactFieldDefinition>>;
+}
 /** A value as trimmed, single-spaced text of at most `max` characters. */
 export declare function crmFactText(value: unknown, max: number): string;
 /** Epoch millis, a `Date` or a stored timestamp, as epoch millis; `null` for anything else. */
@@ -208,17 +358,16 @@ export declare function crmFactMillis(value: unknown): number | null;
 export declare function crmFactDay(value: unknown): string | null;
 /** An amount as a currency code and a fixed-point figure: `USD 1250.00`. */
 export declare function crmFactMoney(cents: unknown, currency: unknown): string | null;
-export declare const CRM_FACTS_EMAIL_PLACEHOLDER = "[email address]";
-export declare const CRM_FACTS_PHONE_PLACEHOLDER = "[phone number]";
+/** A postal address on one line, its parts in the order an envelope writes them; `''` for none. */
+export declare function crmFactAddress(address: Partial<AglynPostalAddress> | null | undefined): string;
+/** A marketing basis as a sentence's worth: opted in (and since when), declined, or nothing recorded. */
+export declare function crmFactConsent(record: Record<string, unknown>, group: ConsentGroup | null | undefined): string;
 /**
- * Free text the team wrote, as {@link crmFactText} reports it, with every
- * email address, and every run of ten digits or more that is not a list of
- * days, replaced by a placeholder. The fields that hold an address or a number
- * are never reported, and this keeps one typed into a note from leaving
- * either. Replaced before the cut, so a cut never halves an address into
- * something unrecognized.
+ * A record's custom values under their fields' labels, in the fields'
+ * order — the active fields of `object` first, then a value whose field was
+ * retired or never defined, under its key.
  */
-export declare function crmFactProse(value: unknown, max: number): string;
+export declare function crmCustomFacts(custom: unknown, object: CrmFieldObject, definitions?: ReadonlyArray<Partial<ContactFieldDefinition>>): CrmCustomFact[];
 /** A logged activity as a timeline entry. */
 export declare function crmActivityFact(activity: Partial<CrmActivity>): CrmTimelineFact | null;
 /** A capture the platform recorded on a contact, as a timeline entry. */
@@ -233,7 +382,7 @@ export declare function crmTimelineFacts(entries: ReadonlyArray<{
     fact: CrmTimelineFact | null;
 }>): CrmTimelineFact[];
 /** The open tasks among `tasks`, soonest due first, undated last. */
-export declare function crmOpenTaskFacts(tasks: ReadonlyArray<Partial<CrmTask>>, nowMs: number): CrmTaskFact[];
+export declare function crmOpenTaskFacts(tasks: ReadonlyArray<Partial<CrmTask>>, nowMs: number, names?: CrmFactsNames): CrmTaskFact[];
 /** One deal, with its stage named by the pipeline it is in. */
 export declare function crmDealFact(deal: Partial<CrmDeal>, pipeline: CrmPipeline | null | undefined): CrmDealFact;
 /** Deals, open ones first, then most recently updated. */
@@ -247,6 +396,9 @@ export interface ContactFactsInput {
     deals: ReadonlyArray<Partial<CrmDeal>>;
     pipelines: ReadonlyMap<string, CrmPipeline>;
     nowMs: number;
+    names?: CrmFactsNames;
+    /** The name of the contact the holder's reports-to names, when the reader could see it. */
+    reportsToName?: string;
 }
 export declare function contactFacts(input: ContactFactsInput): CrmContactFacts;
 export interface CompanyFactsInput {
@@ -256,6 +408,9 @@ export interface CompanyFactsInput {
     deals: ReadonlyArray<Partial<CrmDeal>>;
     pipelines: ReadonlyMap<string, CrmPipeline>;
     nowMs: number;
+    names?: CrmFactsNames;
+    /** The parent company's name, when the reader could see it. */
+    parentCompanyName?: string;
 }
 export declare function companyFacts(input: CompanyFactsInput): CrmCompanyFacts;
 export interface DealFactsInput {
@@ -263,15 +418,41 @@ export interface DealFactsInput {
         contactName?: unknown;
         companyName?: unknown;
     };
+    /** The names of the deal's contacts, by id, as the reader may see them (AGL-3521). */
+    contactNames?: ReadonlyMap<string, string>;
     pipeline: CrmPipeline | null;
     activities: ReadonlyArray<Partial<CrmActivity>>;
     tasks: ReadonlyArray<Partial<CrmTask>>;
     nowMs: number;
+    names?: CrmFactsNames;
+    /** The name of the campaign the deal is credited to, when the reader could see it. */
+    campaignName?: string;
 }
 export declare function dealFacts(input: DealFactsInput): CrmDealFacts;
+/**
+ * A deal's contact roles as facts (AGL-3521): the Primary first, each by the
+ * name the reader resolved — a contact the reader may not see, or could
+ * not read, is left out rather than named by id.
+ */
+export declare function dealContactRoleFacts(deal: {
+    contactId?: unknown;
+    contactRoles?: unknown;
+}, names?: ReadonlyMap<string, string>): CrmContactRoleFact[];
+/** What a lead's capture surfaces are called, the lead history card's words. */
+export declare function leadSourceFact(source: string): string;
 export interface LeadFactsInput {
     lead: Record<string, unknown>;
     activities: ReadonlyArray<Partial<CrmActivity>>;
+    /** The tasks filed against the lead (AGL-3520); none when the reader read none. */
+    tasks?: ReadonlyArray<Partial<CrmTask>>;
+    nowMs?: number;
+    /** The org's Lead status list, whose label the status fact reads (AGL-3512); the standard ones without it. */
+    leadStatuses?: CrmPicklist;
+    /** The site's consent group, which the lead's marketing consent is read under. */
+    group?: ConsentGroup | null;
+    names?: CrmFactsNames;
+    /** The names of the campaigns the lead is filed under, as the reader resolved them. */
+    campaignNames?: readonly string[];
 }
 export declare function leadFacts(input: LeadFactsInput): CrmLeadFacts;
 /**