@rapidmx/crm-plugin 0.1.0

package/dist/types/mongo.d.ts

@@ -0,0 +1,75 @@
+/**
+ * This plugin's `./mongo` entry point: exactly the classes a server host loads for a Mongo deployment - the CRM models, the routes
+ * mounted under `/api/mail/crm`, and the background jobs. Anything else exported here would be registered (and a job started) by
+ * the host too, so the abstract routes and utilities stay in the package root.
+ */
+export { WorkspaceMongo } from "./models/mongo/WorkspaceMongo.js";
+export { WorkspaceMemberMongo } from "./models/mongo/WorkspaceMemberMongo.js";
+export { WorkspaceSenderMongo } from "./models/mongo/WorkspaceSenderMongo.js";
+export { CrmContactMongo } from "./models/mongo/CrmContactMongo.js";
+export { CrmCompanyMongo } from "./models/mongo/CrmCompanyMongo.js";
+export { PropertyDefinitionMongo } from "./models/mongo/PropertyDefinitionMongo.js";
+export { PropertyValueMongo } from "./models/mongo/PropertyValueMongo.js";
+export { CrmNoteMongo } from "./models/mongo/CrmNoteMongo.js";
+export { CrmTaskMongo } from "./models/mongo/CrmTaskMongo.js";
+export { TimelineEventMongo } from "./models/mongo/TimelineEventMongo.js";
+export { CrmImportMongo } from "./models/mongo/CrmImportMongo.js";
+export { MailingListMongo } from "./models/mongo/MailingListMongo.js";
+export { SubscriptionMongo } from "./models/mongo/SubscriptionMongo.js";
+export { SuppressionMongo } from "./models/mongo/SuppressionMongo.js";
+export { CrmFormMongo } from "./models/mongo/CrmFormMongo.js";
+export { CrmSettingMongo } from "./models/mongo/CrmSettingMongo.js";
+export { EmailTemplateMongo } from "./models/mongo/EmailTemplateMongo.js";
+export { SavedBlockMongo } from "./models/mongo/SavedBlockMongo.js";
+export { CampaignMongo } from "./models/mongo/CampaignMongo.js";
+export { OutboundSendMongo } from "./models/mongo/OutboundSendMongo.js";
+export { EngagementEventMongo } from "./models/mongo/EngagementEventMongo.js";
+export { SegmentMongo } from "./models/mongo/SegmentMongo.js";
+export { ScoringRuleMongo } from "./models/mongo/ScoringRuleMongo.js";
+export { AutomationMongo } from "./models/mongo/AutomationMongo.js";
+export { AutomationVersionMongo } from "./models/mongo/AutomationVersionMongo.js";
+export { EnrollmentMongo } from "./models/mongo/EnrollmentMongo.js";
+export { CrmEventMongo } from "./models/mongo/CrmEventMongo.js";
+export { PipelineMongo } from "./models/mongo/PipelineMongo.js";
+export { DealMongo } from "./models/mongo/DealMongo.js";
+export { WebhookEndpointMongo } from "./models/mongo/WebhookEndpointMongo.js";
+export { WebhookDeliveryMongo } from "./models/mongo/WebhookDeliveryMongo.js";
+export { ApiKeyMongo } from "./models/mongo/ApiKeyMongo.js";
+export { WorkspaceRouteMongo } from "./routes/mongo/WorkspaceRouteMongo.js";
+export { ContactRouteMongo } from "./routes/mongo/ContactRouteMongo.js";
+export { CompanyRouteMongo } from "./routes/mongo/CompanyRouteMongo.js";
+export { PropertyDefinitionRouteMongo } from "./routes/mongo/PropertyDefinitionRouteMongo.js";
+export { NoteRouteMongo } from "./routes/mongo/NoteRouteMongo.js";
+export { TaskRouteMongo } from "./routes/mongo/TaskRouteMongo.js";
+export { TimelineRouteMongo } from "./routes/mongo/TimelineRouteMongo.js";
+export { ImportRouteMongo } from "./routes/mongo/ImportRouteMongo.js";
+export { ListRouteMongo } from "./routes/mongo/ListRouteMongo.js";
+export { SubscriptionRouteMongo } from "./routes/mongo/SubscriptionRouteMongo.js";
+export { SuppressionRouteMongo } from "./routes/mongo/SuppressionRouteMongo.js";
+export { FormRouteMongo } from "./routes/mongo/FormRouteMongo.js";
+export { PublicRouteMongo } from "./routes/mongo/PublicRouteMongo.js";
+export { TemplateRouteMongo } from "./routes/mongo/TemplateRouteMongo.js";
+export { SavedBlockRouteMongo } from "./routes/mongo/SavedBlockRouteMongo.js";
+export { CampaignRouteMongo } from "./routes/mongo/CampaignRouteMongo.js";
+export { TrackingRouteMongo } from "./routes/mongo/TrackingRouteMongo.js";
+export { SegmentRouteMongo } from "./routes/mongo/SegmentRouteMongo.js";
+export { ScoringRuleRouteMongo } from "./routes/mongo/ScoringRuleRouteMongo.js";
+export { AutomationRouteMongo } from "./routes/mongo/AutomationRouteMongo.js";
+export { PipelineRouteMongo } from "./routes/mongo/PipelineRouteMongo.js";
+export { DealRouteMongo } from "./routes/mongo/DealRouteMongo.js";
+export { AnalyticsRouteMongo } from "./routes/mongo/AnalyticsRouteMongo.js";
+export { WebhookRouteMongo } from "./routes/mongo/WebhookRouteMongo.js";
+export { ApiKeyRouteMongo } from "./routes/mongo/ApiKeyRouteMongo.js";
+export { IntegrationRouteMongo } from "./routes/mongo/IntegrationRouteMongo.js";
+export { CrmAdminRouteMongo } from "./routes/mongo/CrmAdminRouteMongo.js";
+export { CrmImportJobMongo } from "./jobs/mongo/CrmImportJobMongo.js";
+export { CampaignJobMongo } from "./jobs/mongo/CampaignJobMongo.js";
+export { SendDispatchJobMongo } from "./jobs/mongo/SendDispatchJobMongo.js";
+export { CrmMailEventJobMongo } from "./jobs/mongo/CrmMailEventJobMongo.js";
+export { SegmentRefreshJobMongo } from "./jobs/mongo/SegmentRefreshJobMongo.js";
+export { ScoringJobMongo } from "./jobs/mongo/ScoringJobMongo.js";
+export { AutomationTriggerJobMongo } from "./jobs/mongo/AutomationTriggerJobMongo.js";
+export { AutomationRunJobMongo } from "./jobs/mongo/AutomationRunJobMongo.js";
+export { TaskReminderJobMongo } from "./jobs/mongo/TaskReminderJobMongo.js";
+export { WebhookDeliveryJobMongo } from "./jobs/mongo/WebhookDeliveryJobMongo.js";
+export { DateTriggerJobMongo } from "./jobs/mongo/DateTriggerJobMongo.js";

package/dist/types/purge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * This plugin's `./purge` entry point: the server runs `onPurge()` when the plugin is uninstalled *with its data*, once no server runs
+ * it any more and before it deletes the plugin's collections and tables (which it finds from the models).
+ *
+ * What those steps can't find is the uploaded import files (`CrmImport.blobKey`, kept in the server's `BlobStore` under
+ * `crm-imports/`): the store can't list keys, and the keys are only in the rows the server is about to delete. So this deletes each
+ * file by its recorded key first. If one can't be deleted it throws an `AbortPurgeError`, which stops the purge before the rows go -
+ * the keys are still there for a retry.
+ *
+ * Workspace ACLs (one per workspace, keyed by its uid, in the server's ACL store) are left to the server's own ACL cleanup.
+ */
+/** What the server hands `onPurge()` (structurally; a plugin imports nothing from the server). */
+export interface PurgeContext {
+    /** The collections and tables this plugin's models use. */
+    models: readonly {
+        className: string;
+        datastore: string;
+        kind: "mongo" | "sql";
+        name: string;
+    }[];
+    /** The server's connection for a datastore: a service-core `MongoConnection` or a TypeORM `DataSource`. */
+    connection(datastore: string): any;
+    /** The server's `BlobStore`. */
+    blobStore?: {
+        delete(key: string): Promise<void>;
+    };
+    logger?: {
+        info(message: string): void;
+    };
+}
+/** Deletes every import file this plugin stored in the server's `BlobStore`. */
+export declare function onPurge(ctx: PurgeContext): Promise<void>;

package/dist/types/routes/BaseAnalyticsRoute.d.ts

@@ -0,0 +1,87 @@
+import type { JWTUser } from "@rapidrest/core";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** The most rows one report reads of one kind, so a report on a busy workspace stays bounded. */
+export declare const MAX_REPORT_ROWS = 200000;
+/** One day of email numbers: how many messages each thing happened to, that day. */
+export interface EmailDay {
+    date: string;
+    sent: number;
+    opened: number;
+    clicked: number;
+    replied: number;
+    bounced: number;
+    unsubscribed: number;
+}
+export interface EmailReport {
+    days: EmailDay[];
+    /** Messages sent in the window, and how many of them each thing happened to. */
+    totals: {
+        sent: number;
+        opened: number;
+        clicked: number;
+        replied: number;
+        bounced: number;
+        unsubscribed: number;
+        complained: number;
+    };
+    /** The recipient domains messages went to most, with their open and click counts. */
+    domains: {
+        domain: string;
+        sent: number;
+        opened: number;
+        clicked: number;
+    }[];
+}
+export interface GrowthDay {
+    date: string;
+    contacts: number;
+    subscribed: number;
+    unsubscribed: number;
+}
+export interface GrowthReport {
+    days: GrowthDay[];
+    contacts: number;
+    lists: {
+        uid: string;
+        name: string;
+        subscribed: number;
+    }[];
+}
+export interface SalesDay {
+    date: string;
+    created: number;
+    wonAmount: number;
+    won: number;
+    lost: number;
+}
+export interface SalesReport {
+    days: SalesDay[];
+    open: {
+        count: number;
+        amount: number;
+    };
+    won: {
+        count: number;
+        amount: number;
+    };
+    lost: number;
+}
+/** Every day of the last `count` days, oldest first, ending today (UTC). */
+export declare function lastDays(count: number, now?: Date): string[];
+/**
+ * A workspace's reports (`/api/mail/crm/analytics`), each over the last `days` (1 to 365, 30 by default), by UTC day:
+ * - `GET /:workspaceUid/email` - messages sent, opened, clicked, replied to, bounced and unsubscribed from, per day and in all, and
+ * the recipient domains mailed most (`EmailReport`). Opens by machines don't count.
+ * - `GET /:workspaceUid/growth` - new contacts, subscribes and unsubscribes per day, and each list's subscribers now (`GrowthReport`).
+ * - `GET /:workspaceUid/sales?pipelineUid=` - deals created, won (and their value) and lost per day, and what is open (`SalesReport`).
+ *
+ * Reports read at most `MAX_REPORT_ROWS` rows of each kind.
+ */
+export declare abstract class BaseAnalyticsRoute extends CrmRouteBase {
+    private readDays;
+    /** Every row of `repo` matching `query`, in uid order, at most `MAX_REPORT_ROWS`. */
+    private all;
+    email(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<EmailReport>;
+    growth(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<GrowthReport>;
+    sales(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<SalesReport>;
+}

package/dist/types/routes/BaseApiKeyRoute.d.ts

@@ -0,0 +1,31 @@
+import type { JWTUser } from "@rapidrest/core";
+import { ApiKey, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many API keys one workspace may have. */
+export declare const MAX_API_KEYS = 20;
+/** A new API key: `crm_` and 32 random bytes, base64url. */
+export declare function newApiKey(): string;
+/** What an API key is stored as. */
+export declare function hashApiKey(key: string): string;
+/** An API key as the API shows it: never its hash. */
+export type ApiKeyView = Omit<ApiKey, "hash">;
+/**
+ * A workspace's integration API keys (`/api/mail/crm/api-keys`) - see `BaseWorkspaceRecordRoute` for the endpoints; they take
+ * `MANAGE`. A key is answered in full once, when it is created (`key`); only its SHA-256 is kept. A key can be renamed and its
+ * `scopes` changed; deleting it revokes it. See `BaseIntegrationRoute` for what keys call.
+ */
+export declare abstract class BaseApiKeyRoute extends BaseWorkspaceRecordRoute<ApiKey, ApiKeyView> {
+    protected readonly model: "apiKey";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly maxRecords: number;
+    /** The key of the create being handled, to answer it once. */
+    private issued?;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<ApiKey>>;
+    protected readUpdate(body: Record<string, unknown>): Promise<Partial<ApiKey>>;
+    private readScopes;
+    protected toViews(records: ApiKey[]): Promise<ApiKeyView[]>;
+    create(workspaceUid: string, body: unknown, user?: JWTUser): Promise<ApiKeyView & {
+        key?: string;
+    }>;
+}

package/dist/types/routes/BaseAutomationRoute.d.ts

@@ -0,0 +1,56 @@
+import type { JWTUser } from "@rapidrest/core";
+import { Automation, Enrollment, EnrollmentState } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, SearchResult, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many automations one workspace may have. */
+export declare const MAX_AUTOMATIONS = 200;
+/** How many contacts one request may enroll by hand. */
+export declare const MAX_MANUAL_ENROLL = 500;
+/** An enrollment as a list shows it: with its contact's address. */
+export interface EnrollmentView extends Enrollment {
+    email?: string;
+}
+/** An automation's numbers: enrollments by state, who is at each step now, and each email step's results. */
+export interface AutomationReport {
+    states: Record<EnrollmentState, number>;
+    nodes: Record<string, {
+        current: number;
+        sent?: number;
+        opened?: number;
+        clicked?: number;
+        replied?: number;
+    }>;
+}
+/**
+ * A workspace's automations (`/api/mail/crm/automations`) - see `BaseWorkspaceRecordRoute` for the endpoints; the draft `graph`,
+ * `reentry` and `goalFilter` change with `PUT` - plus:
+ * - `POST /:workspaceUid/:uid/publish` - checks the draft (`validateForPublish()` and that everything it names exists) and makes it
+ * the version new enrollments go through; the automation becomes active.
+ * - `POST /:workspaceUid/:uid/pause` and `.../resume`.
+ * - `POST /:workspaceUid/:uid/enroll` - `{ contactUids }`: puts contacts in by hand (an active automation, as its re-entry rule allows).
+ * - `GET /:workspaceUid/:uid/report` - `AutomationReport`.
+ * - `POST /:workspaceUid/:uid/enrollments` - `{ state?, contactUid?, limit?, page? }` to a page of enrollments.
+ * - `POST /:workspaceUid/:uid/enrollments/:enrollmentUid/exit` - takes one contact out.
+ */
+export declare abstract class BaseAutomationRoute extends BaseWorkspaceRecordRoute<Automation> {
+    protected readonly model: "automation";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Automation>>;
+    protected readUpdate(body: Record<string, unknown>, _existing: Automation, context: WriteContext): Promise<Partial<Automation>>;
+    private readContactFilter;
+    protected afterDelete(record: Automation): Promise<void>;
+    private requireAutomation;
+    /** Refuses (400) a published graph naming something the workspace doesn't have. */
+    private checkReferences;
+    publish(workspaceUid: string, uid: string, user?: JWTUser): Promise<Automation>;
+    pause(workspaceUid: string, uid: string, user?: JWTUser): Promise<Automation>;
+    resume(workspaceUid: string, uid: string, user?: JWTUser): Promise<Automation>;
+    enroll(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<{
+        enrolled: number;
+    }>;
+    report(workspaceUid: string, uid: string, user?: JWTUser): Promise<AutomationReport>;
+    enrollments(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<SearchResult<EnrollmentView>>;
+    exitEnrollment(workspaceUid: string, uid: string, enrollmentUid: string, user?: JWTUser): Promise<Enrollment>;
+    private transition;
+}

package/dist/types/routes/BaseCampaignRoute.d.ts

@@ -0,0 +1,66 @@
+import type { JWTUser } from "@rapidrest/core";
+import { Campaign, CampaignStats, OutboundSend } from "../models/types.js";
+import { LinkClicks } from "../sending/Stats.js";
+import { BaseWorkspaceRecordRoute, SearchResult, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many campaigns one workspace may have. */
+export declare const MAX_CAMPAIGNS = 5000;
+/** How many lists a campaign may go to, or exclude. */
+export declare const MAX_CAMPAIGN_LISTS = 20;
+/** The A/B variant ids, in order. */
+export declare const VARIANT_IDS: readonly string[];
+/** One thing standing in the way of sending a campaign. */
+export interface CampaignProblem {
+    field: string;
+    message: string;
+}
+/**
+ * A workspace's email campaigns (`/api/mail/crm/campaigns`) - see `BaseWorkspaceRecordRoute` for the endpoints - plus:
+ * - `GET /:workspaceUid/:uid/checklist` - what stands in the way of sending it (`CampaignProblem[]`, empty when nothing).
+ * - `POST /:workspaceUid/:uid/schedule` - `{ sendAt? }`: sends it at `sendAt`, or now. Refused while the checklist has problems.
+ * - `POST /:workspaceUid/:uid/unschedule` - back to a draft, before it starts.
+ * - `POST /:workspaceUid/:uid/pause`, `.../resume`, `.../cancel` - while it goes out. Cancelling drops what hasn't been sent.
+ * - `POST /:workspaceUid/:uid/duplicate` - a draft copy.
+ * - `POST /:workspaceUid/audience` - `{ listUids, excludeListUids? }` to `{ count, capped }`: how many contacts it would reach now.
+ * - `GET /:workspaceUid/:uid/report` - fresh stats and the links by clicks.
+ * - `POST /:workspaceUid/:uid/recipients` - `{ status?, engagement?, q?, limit?, page? }` to a page of its messages.
+ *
+ * Only a draft can be changed; the jobs (`CampaignJob`, `SendDispatchJob`) take it from `scheduled` on.
+ */
+export declare abstract class BaseCampaignRoute extends BaseWorkspaceRecordRoute<Campaign> {
+    protected readonly model: "campaign";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Campaign>>;
+    protected readUpdate(body: Record<string, unknown>, existing: Campaign, context: WriteContext): Promise<Partial<Campaign>>;
+    private readFields;
+    private readLists;
+    private readSegments;
+    private readAbTest;
+    private requireTemplate;
+    protected afterDelete(record: Campaign): Promise<void>;
+    protected beforeDelete(record: Campaign): Promise<void>;
+    /** The campaign, after checking the caller may do `action` on its workspace. */
+    private requireCampaign;
+    /** What stands in the way of sending `campaign`. */
+    problems(campaign: Campaign): Promise<CampaignProblem[]>;
+    checklist(workspaceUid: string, uid: string, user?: JWTUser): Promise<CampaignProblem[]>;
+    schedule(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<Campaign>;
+    unschedule(workspaceUid: string, uid: string, user?: JWTUser): Promise<Campaign>;
+    pause(workspaceUid: string, uid: string, user?: JWTUser): Promise<Campaign>;
+    resume(workspaceUid: string, uid: string, user?: JWTUser): Promise<Campaign>;
+    cancel(workspaceUid: string, uid: string, user?: JWTUser): Promise<Campaign>;
+    duplicate(workspaceUid: string, uid: string, user?: JWTUser): Promise<Campaign>;
+    audience(workspaceUid: string, body: unknown, user?: JWTUser): Promise<{
+        count: number;
+        capped: boolean;
+    }>;
+    report(workspaceUid: string, uid: string, user?: JWTUser): Promise<{
+        campaign: Campaign;
+        stats: CampaignStats;
+        links: LinkClicks[];
+    }>;
+    recipients(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<SearchResult<OutboundSend>>;
+    /** `campaign` with `changes`, saved (version-checked against the jobs) and pushed. */
+    private transition;
+}

package/dist/types/routes/BaseCompanyRoute.d.ts

@@ -0,0 +1,30 @@
+import { CrmCompany, CrmObjectType } from "../models/types.js";
+import { BaseTaggedRecordRoute } from "./BaseTaggedRecordRoute.js";
+import { WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many companies one workspace may have. */
+export declare const MAX_COMPANIES = 200000;
+/**
+ * A workspace's companies (`/api/mail/crm/companies`) - see `BaseWorkspaceRecordRoute` for the endpoints and `BaseTaggedRecordRoute`
+ * for tags, custom properties, filters, bulk actions and export. A company's `domain` is normalized (`acme.com` from
+ * `https://www.acme.com/about` or `jane@acme.com`); new contacts with an address at it are linked to it. Deleting a company unlinks
+ * its contacts.
+ */
+export declare abstract class BaseCompanyRoute extends BaseTaggedRecordRoute<CrmCompany> {
+    protected readonly model: "company";
+    protected readonly pushType: string;
+    protected readonly objectType: CrmObjectType;
+    protected readonly recordFields: Readonly<Record<string, import("../index.js").FilterField>>;
+    protected readonly textFields: readonly string[];
+    protected readonly exportFields: readonly string[];
+    protected readonly noun: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    readonly importFields: Readonly<Record<string, "text" | "number">>;
+    /** The workspace's company with the row's domain, or else (for a row with no domain) with its exact name. */
+    protected findExisting(workspaceUid: string, body: Record<string, unknown>): Promise<CrmCompany | undefined>;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<CrmCompany>>;
+    protected readUpdate(body: Record<string, unknown>, _existing: CrmCompany, context: WriteContext): Promise<Partial<CrmCompany>>;
+    private readFields;
+    /** Deleting companies unlinks their contacts too. */
+    protected deleteRelated(uids: string[], workspaceUid: string): Promise<void>;
+}

package/dist/types/routes/BaseContactRoute.d.ts

@@ -0,0 +1,42 @@
+import { CrmContact, CrmObjectType } from "../models/types.js";
+import { BaseTaggedRecordRoute } from "./BaseTaggedRecordRoute.js";
+import { WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many contacts one workspace may have. */
+export declare const MAX_CONTACTS = 1000000;
+/**
+ * A workspace's contacts (`/api/mail/crm/contacts`) - see `BaseWorkspaceRecordRoute` for the endpoints and `BaseTaggedRecordRoute`
+ * for tags, custom properties, filters, bulk actions and export.
+ *
+ * A contact is unique by email address within its workspace (409 on a duplicate). A new contact given no company is linked to the
+ * workspace's company whose `domain` matches its email address, when there is one. Deleting a contact erases what the CRM holds
+ * about the person (its values, notes and timeline).
+ */
+export declare abstract class BaseContactRoute extends BaseTaggedRecordRoute<CrmContact> {
+    protected readonly model: "contact";
+    protected readonly pushType: string;
+    protected readonly objectType: CrmObjectType;
+    protected readonly recordFields: Readonly<Record<string, import("../index.js").FilterField>>;
+    protected readonly textFields: readonly string[];
+    protected readonly exportFields: readonly string[];
+    protected readonly noun: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    readonly importFields: Readonly<Record<string, "text" | "number">>;
+    protected findExisting(workspaceUid: string, body: Record<string, unknown>): Promise<CrmContact | undefined>;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<CrmContact>>;
+    protected readUpdate(body: Record<string, unknown>, existing: CrmContact, context: WriteContext): Promise<Partial<CrmContact>>;
+    /** Every field but `email`, as given (`undefined` when absent, `null` to clear). */
+    private readFields;
+    /** Refuses (409) an email address another contact of the workspace already has. */
+    private requireUniqueEmail;
+    /** The uid of the workspace's company whose domain is `email`'s, when exactly one has it. */
+    private companyForEmail;
+    /**
+     * Deleting contacts deletes their subscriptions (their `lists` values go with the rest of their values), the messages sent to
+     * them and what came of those - nothing personal stays behind in campaign statistics - and their runs through automations.
+     */
+    protected deleteRelated(uids: string[], workspaceUid: string): Promise<void>;
+    /** Takes deleted contacts off the deals they were on. */
+    private removeFromDeals;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+}

package/dist/types/routes/BaseCrmAdminRoute.d.ts

@@ -0,0 +1,41 @@
+import type { JWTUser } from "@rapidrest/core";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** A workspace as the deployment's administrators see it. */
+export interface AdminWorkspace {
+    uid: string;
+    name: string;
+    dateCreated: string;
+    members: number;
+    contacts: number;
+    campaignsSent: number;
+    sendingDisabled: boolean;
+}
+/** The deployment's CRM numbers. */
+export interface AdminStats {
+    workspaces: number;
+    contacts: number;
+    /** Campaign and automation messages sent in the last 24 hours. */
+    sentLastDay: number;
+    /** Messages waiting to go out. */
+    queued: number;
+}
+/**
+ * The deployment administration of the CRM (`/api/mail/crm/admin`), for callers holding a trusted role (`trusted_roles`, `admin` by
+ * default) - they need no membership of any workspace, and see no workspace's contents:
+ * - `GET /stats` - `AdminStats`.
+ * - `GET /workspaces?limit=&page=` - every workspace with its size (`AdminWorkspace`), newest first (`limit` up to 100, 50 by default).
+ * - `PUT /workspaces/:workspaceUid` - `{ sendingDisabled }`: stops (or lets go again) a workspace's campaign and automation email,
+ * the abuse kill switch. Stopped messages stay queued.
+ */
+export declare abstract class BaseCrmAdminRoute extends CrmRouteBase {
+    private requireAdmin;
+    stats(user?: JWTUser): Promise<AdminStats>;
+    workspaces(query: Record<string, unknown> | undefined, user?: JWTUser): Promise<{
+        items: AdminWorkspace[];
+        total: number;
+    }>;
+    setWorkspace(workspaceUid: string, body: unknown, user?: JWTUser): Promise<{
+        uid: string;
+        sendingDisabled: boolean;
+    }>;
+}

package/dist/types/routes/BaseDealRoute.d.ts

@@ -0,0 +1,65 @@
+import type { JWTUser } from "@rapidrest/core";
+import { Deal } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many deals one workspace may have, and contacts one deal. */
+export declare const MAX_DEALS = 50000;
+export declare const MAX_DEAL_CONTACTS = 20;
+/** The `PropertyValue` key a deal's contacts are mirrored under (object type `deal`). */
+export declare const DEAL_CONTACTS_KEY = "contacts";
+/** One stage's numbers in a forecast. */
+export interface StageForecast {
+    stageId: string;
+    count: number;
+    amount: number;
+    /** `amount` times the stage's probability. */
+    weighted: number;
+}
+/** A pipeline's forecast: its open stages' numbers, and what was won and lost in the window. */
+export interface Forecast {
+    stages: StageForecast[];
+    open: {
+        count: number;
+        amount: number;
+        weighted: number;
+    };
+    won: {
+        count: number;
+        amount: number;
+    };
+    lost: {
+        count: number;
+        amount: number;
+    };
+    /** Won out of won and lost, in the window (0 to 1); none without either. */
+    winRate?: number;
+    /** The mean days from creating a deal to winning it, in the window. */
+    averageDaysToWin?: number;
+}
+/**
+ * A workspace's deals (`/api/mail/crm/deals`) - see `BaseWorkspaceRecordRoute` for the endpoints; `GET /:workspaceUid` takes
+ * `pipelineUid`, `stageId`, `status`, `ownerUserUid`, `companyUid` and `contactUid` - plus
+ * `GET /:workspaceUid/forecast?pipelineUid=&days=` (`Forecast`, over the last `days`, 90 by default).
+ *
+ * A deal's `status` follows its stage's kind; moving it records the move in `stageHistory`, `closedAt` when it is won or lost, and
+ * the move on its timeline and its contacts', and tells automations (`deal.stage_changed`, `deal.won`, `deal.lost`, per contact).
+ */
+export declare abstract class BaseDealRoute extends BaseWorkspaceRecordRoute<Deal> {
+    protected readonly model: "deal";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Deal>>;
+    protected readUpdate(body: Record<string, unknown>, existing: Deal, context: WriteContext): Promise<Partial<Deal>>;
+    /** The owner, contacts, company, expected close date and lost reason of a request. */
+    private readLinks;
+    private readCurrency;
+    private requirePipeline;
+    private requireStage;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+    /** `GET /:workspaceUid?contactUid=` - the deals of a contact, through the `contacts` values. */
+    list(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<Deal[]>;
+    /** Keeps the `contacts` values in step, and records a new deal or a move on the timelines and for automations. */
+    protected afterWrite(record: Deal, before: Deal | undefined, body: Record<string, unknown>, context: WriteContext): Promise<void>;
+    protected afterDelete(record: Deal): Promise<void>;
+    forecast(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<Forecast>;
+}

package/dist/types/routes/BaseFormRoute.d.ts

@@ -0,0 +1,25 @@
+import { CrmForm, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many fields a form may have, and how many lists it may subscribe to. */
+export declare const MAX_FORM_FIELDS = 30;
+export declare const MAX_FORM_LISTS = 20;
+/** The contact fields a form can ask for, besides custom properties (`properties.<key>`) - `company` is the company's name. */
+export declare const FORM_TARGETS: readonly string[];
+export declare const DEFAULT_SUCCESS_MESSAGE = "Thanks for signing up!";
+/**
+ * A workspace's signup forms (`/api/mail/crm/forms`) - see `BaseWorkspaceRecordRoute` for the endpoints. Changing forms takes `MANAGE`.
+ * A form always asks for an email address; its other fields fill contact fields or contact custom properties. Anyone may submit an
+ * enabled form through the public API (`BasePublicRoute`), at `<public_url>/f/<uid>`.
+ */
+export declare abstract class BaseFormRoute extends BaseWorkspaceRecordRoute<CrmForm> {
+    protected readonly model: "form";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly writeAction: WorkspaceAction;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<CrmForm>>;
+    protected readUpdate(body: Record<string, unknown>, existing: CrmForm, context: WriteContext): Promise<Partial<CrmForm>>;
+    private readFields;
+    /** A form's fields: each a known contact field or contact property, used once, with `email` among them. */
+    private readFormFields;
+    private readLists;
+}

package/dist/types/routes/BaseImportRoute.d.ts

@@ -0,0 +1,39 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpRequest } from "@rapidrest/service-core";
+import type { BlobStore } from "@rapidmx/restapi";
+import { CrmImport } from "../models/types.js";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** How many rows an import may have. */
+export declare const MAX_IMPORT_ROWS = 200000;
+/** An import as the API shows it on upload: the import, the targets its columns may map to, and its first rows. */
+export interface ImportUploadView {
+    import: CrmImport;
+    targets: string[];
+    preview: string[][];
+}
+/**
+ * CSV imports of contacts or companies (`/api/mail/crm/imports`), in two steps. First,
+ * `POST /:workspaceUid?objectType=contact&fileName=x.csv` with the file as the raw request body stores it, reads its header, and
+ * answers the import with a suggested column mapping, the fields its columns may map to, and a preview of its first rows. Then
+ * `POST /:workspaceUid/:uid/start` with `{ mapping, updateExisting?, tags? }` queues it for `CrmImportJob`, which imports it in the
+ * background (pushing progress on the workspace's channel as `CrmImport` updates).
+ *
+ * Plus `GET /:workspaceUid` (newest first), `GET /:workspaceUid/:uid`, and `DELETE /:workspaceUid/:uid` for one that isn't running.
+ * Every endpoint takes `WRITE` on the workspace.
+ */
+export declare abstract class BaseImportRoute extends CrmRouteBase {
+    protected blobStore?: BlobStore;
+    /** The largest CSV accepted, in bytes. */
+    protected maxBytes: number;
+    list(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<CrmImport[]>;
+    get(workspaceUid: string, uid: string, user?: JWTUser): Promise<CrmImport>;
+    upload(workspaceUid: string, query: Record<string, unknown> | undefined, req: HttpRequest, user?: JWTUser): Promise<ImportUploadView>;
+    start(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<CrmImport>;
+    remove(workspaceUid: string, uid: string, user?: JWTUser): Promise<void>;
+    /** The list a contact import subscribes its contacts to: a list of the workspace, or none. */
+    private readImportList;
+    private definitions;
+    private requireImport;
+    /** Deletes an import's file, logging rather than failing when it can't. */
+    private deleteBlob;
+}

package/dist/types/routes/BaseIntegrationRoute.d.ts

@@ -0,0 +1,46 @@
+import { HttpRequest, RateLimiter } from "@rapidrest/service-core";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** How many calls one key may make a minute. */
+export declare const API_KEY_RATE = 600;
+/**
+ * The API a workspace's own systems call (`/api/mail/crm/integrations/:workspaceUid/...`), with a workspace API key as
+ * `Authorization: Bearer crm_...` rather than a member's session - each endpoint needs its key's scope:
+ * - `POST /contacts` (`contacts`) - creates or updates the contact with `email`: `{ email, firstName?, lastName?, ..., tags?,
+ * properties? }` to `{ outcome, uid }`.
+ * - `POST /subscribe` (`subscriptions`) - `{ email, listUid, ...contact fields }`: subscribes the contact (creating it), consent
+ * vouched for by the caller.
+ * - `POST /unsubscribe` (`subscriptions`) - `{ email, listUid? }`: from one list, or from every list and all email.
+ * - `POST /events` (`events`) - `{ email, name, data? }`: records a `custom` event automations can start from (creating the contact).
+ * - `GET /lists` (any scope) - the workspace's lists.
+ *
+ * A missing, unknown or revoked key is a 401; one without the scope a 403. Each key may make `API_KEY_RATE` calls a minute.
+ */
+export declare abstract class BaseIntegrationRoute extends CrmRouteBase {
+    protected abstract contactRouteClass: any;
+    protected rateLimiter?: RateLimiter;
+    private contactRoute?;
+    private contacts;
+    /** The key of the request, if it is one of the workspace's, unrevoked and holding `scope` - else a 401 or 403. */
+    private requireKey;
+    /** Creates or updates the contact of a request's `email` and other contact fields. */
+    private upsertContact;
+    upsert(workspaceUid: string, body: unknown, req: HttpRequest): Promise<{
+        outcome: string;
+        uid: string;
+    }>;
+    subscribe(workspaceUid: string, body: unknown, req: HttpRequest): Promise<{
+        contactUid: string;
+        status: string;
+    }>;
+    unsubscribe(workspaceUid: string, body: unknown, req: HttpRequest): Promise<{
+        contactUid?: string;
+    }>;
+    event(workspaceUid: string, body: unknown, req: HttpRequest): Promise<{
+        contactUid: string;
+    }>;
+    lists(workspaceUid: string, req: HttpRequest): Promise<{
+        uid: string;
+        name: string;
+        publicName: string;
+    }[]>;
+}