@rapidmx/crm-plugin 0.1.0

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

@@ -0,0 +1,26 @@
+import { MailingList, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many lists one workspace may have. */
+export declare const MAX_LISTS = 500;
+/** A list as the API shows it: the list, and how many contacts are subscribed to it and waiting to confirm. */
+export interface MailingListView extends MailingList {
+    subscribedCount: number;
+    pendingCount: number;
+}
+/**
+ * A workspace's mailing lists (`/api/mail/crm/lists`) - see `BaseWorkspaceRecordRoute` for the endpoints. Creating, changing and
+ * deleting a list takes `MANAGE`. A list with double opt-in needs a sender for its confirmation emails. Deleting a list deletes its
+ * subscriptions.
+ */
+export declare abstract class BaseListRoute extends BaseWorkspaceRecordRoute<MailingList, MailingListView> {
+    protected readonly model: "mailingList";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<MailingList>>;
+    protected readUpdate(body: Record<string, unknown>, existing: MailingList, context: WriteContext): Promise<Partial<MailingList>>;
+    private readFields;
+    protected toViews(records: MailingList[]): Promise<MailingListView[]>;
+    protected afterDelete(record: MailingList, context: WriteContext): Promise<void>;
+}

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

@@ -0,0 +1,15 @@
+import { CrmNote } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/**
+ * Notes on contacts and companies (`/api/mail/crm/notes`) - see `BaseWorkspaceRecordRoute` for the endpoints. `GET /:workspaceUid`
+ * takes `subjectUid` to list one record's notes. A new note also goes on its record's timeline; deleting it takes it off.
+ */
+export declare abstract class BaseNoteRoute extends BaseWorkspaceRecordRoute<CrmNote> {
+    protected readonly model: "note";
+    protected readonly pushType: string;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<CrmNote>>;
+    protected readUpdate(body: Record<string, unknown>, existing: CrmNote): Promise<Partial<CrmNote>>;
+    protected afterWrite(record: CrmNote, before: CrmNote | undefined, _body: Record<string, unknown>, context: WriteContext): Promise<void>;
+    protected afterDelete(record: CrmNote, context: WriteContext): Promise<void>;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+}

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

@@ -0,0 +1,31 @@
+import type { JWTUser } from "@rapidrest/core";
+import { Pipeline, PipelineStage, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many pipelines one workspace may have, and stages one pipeline. */
+export declare const MAX_PIPELINES = 20;
+export declare const MAX_STAGES = 20;
+/** The stages a workspace's first pipeline starts with. */
+export declare function defaultStages(): PipelineStage[];
+/**
+ * A workspace's sales pipelines (`/api/mail/crm/pipelines`) - see `BaseWorkspaceRecordRoute` for the endpoints; changing them takes
+ * `MANAGE`. A workspace with none gets a default one ("Sales") the first time its pipelines are listed.
+ *
+ * A pipeline's `stages` are replaced as a whole: each keeps its `id` (a new one gets one), and a stage that still holds deals can't be
+ * removed. A pipeline needs a won and a lost stage, and one that holds deals can't be deleted. One pipeline is the default.
+ */
+export declare abstract class BasePipelineRoute extends BaseWorkspaceRecordRoute<Pipeline> {
+    protected readonly model: "pipeline";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Pipeline>>;
+    protected readUpdate(body: Record<string, unknown>, existing: Pipeline): Promise<Partial<Pipeline>>;
+    /** `raw` as a pipeline's stages: known ids kept, new ones given one; a won and a lost stage required. */
+    private readStages;
+    /** A new default takes over from the old one. */
+    protected afterWrite(record: Pipeline): Promise<void>;
+    protected beforeDelete(record: Pipeline): Promise<void>;
+    /** A workspace's pipelines, making it a default one ("Sales") if it has none. */
+    list(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<Pipeline[]>;
+}

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

@@ -0,0 +1,24 @@
+import { PropertyDefinition, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many options a select property may have, and how long one may be. */
+export declare const MAX_OPTIONS = 200;
+export declare const MAX_OPTION_LENGTH = 100;
+/** How many custom properties one workspace may define. */
+export declare const MAX_PROPERTY_DEFINITIONS = 500;
+/**
+ * A workspace's custom properties (`/api/mail/crm/properties`) - see `BaseWorkspaceRecordRoute` for the endpoints. Defining them takes
+ * `MANAGE` (a workspace admin). A property's `objectType`, `key` and `type` are fixed once created; its label, options, group and
+ * description can change. Deleting one deletes every value of it.
+ */
+export declare abstract class BasePropertyDefinitionRoute extends BaseWorkspaceRecordRoute<PropertyDefinition> {
+    protected readonly model: "propertyDefinition";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<PropertyDefinition>>;
+    protected readUpdate(body: Record<string, unknown>, existing: PropertyDefinition): Promise<Partial<PropertyDefinition>>;
+    /** The options of a select or multi-select property (required on create), each `{ value, label }` with unique values. */
+    private readOptions;
+    protected afterDelete(record: PropertyDefinition, context: WriteContext): Promise<void>;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+}

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

@@ -0,0 +1,129 @@
+import { HttpRequest, HttpResponse, RateLimiter } from "@rapidrest/service-core";
+import { type MailTransport } from "@rapidmx/restapi";
+import { FormField, PropertyType } from "../models/types.js";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** How long a double opt-in confirmation link works, in days. */
+export declare const CONFIRM_TOKEN_DAYS = 7;
+/** The name of a form's hidden trap field: people never fill it in, simple bots do. */
+export declare const HONEYPOT_FIELD = "website";
+/** A form as anyone may see it. */
+export interface PublicForm {
+    uid: string;
+    title: string;
+    description?: string;
+    fields: (FormField & {
+        type: "email" | "text" | PropertyType;
+        options?: {
+            value: string;
+            label: string;
+        }[];
+    })[];
+}
+/** What a form submission answers. */
+export interface FormResult {
+    /** `confirm`: an email asks the subscriber to confirm; `subscribed`: done. */
+    result: "confirm" | "subscribed";
+    message: string;
+    redirectUrl?: string;
+}
+/** A subscriber's preferences as the preference center shows them. */
+export interface PreferencesView {
+    workspaceName: string;
+    email: string;
+    /** The contact has unsubscribed from all email. */
+    unsubscribedAll: boolean;
+    lists: {
+        uid: string;
+        name: string;
+        description?: string;
+        subscribed: boolean;
+    }[];
+}
+/**
+ * The CRM's anonymous endpoints (`/api/mail/crm/public`), for the public pages and the links in emails. None takes a signed-in user;
+ * a form is found by its uid, everything else by a signed token (`util/Tokens.ts`) from an email, which names the workspace and the
+ * contact and can't be forged. Every endpoint is rate limited per client address, and answers 404 for anything it can't find or verify.
+ *
+ * - `GET /forms/:formUid`, `POST /forms/:formUid` - an enabled form, and submitting it: the address becomes (or fills in the blanks of)
+ * a contact and is subscribed to the form's lists - straight away, or pending until confirmed when the form has double opt-in, in
+ * which case a confirmation email is sent from the form's sender.
+ * - `POST /confirm/:token` - confirms the pending subscriptions a confirmation email was about.
+ * - `GET /preferences/:token`, `POST /preferences/:token` - the preference center: the lists a subscriber may join or leave, and
+ * unsubscribing from all email.
+ * - `POST /unsubscribe/:token` - one-click unsubscribe (RFC 8058: what a mail client posts for `List-Unsubscribe-Post`), from the
+ * token's list, or from all email when it names none.
+ */
+export declare abstract class BasePublicRoute extends CrmRouteBase {
+    /** The backend's concrete contact route, which writes contacts from forms exactly as the API does. */
+    protected abstract contactRouteClass: any;
+    protected mailTransport?: MailTransport;
+    protected rateLimiter?: RateLimiter;
+    protected trustedProxies: string[];
+    private contactRoute?;
+    getForm(formUid: string, req: HttpRequest): Promise<PublicForm>;
+    submitForm(formUid: string, body: unknown, req: HttpRequest): Promise<FormResult>;
+    confirm(token: string, req: HttpRequest): Promise<{
+        workspaceName: string;
+        lists: string[];
+    }>;
+    getPreferences(token: string, req: HttpRequest): Promise<PreferencesView>;
+    /**
+     * Changes a subscriber's preferences: `lists` maps list uids to whether to be subscribed (only lists the preference center shows -
+     * visible ones and those the contact is on), and `unsubscribeAll: true` unsubscribes from every list and all email.
+     * `unsubscribeAll: false` (or subscribing to a list) takes back an earlier "unsubscribe from all".
+     */
+    setPreferences(token: string, body: unknown, req: HttpRequest): Promise<PreferencesView>;
+    /**
+     * The landing page of an unsubscribe link, for a `GET` of the address a message's `List-Unsubscribe` header gives (mail clients
+     * `POST` it; a person following it gets the page with its button). Unsubscribes nothing itself.
+     */
+    unsubscribePage(token: string, res: HttpResponse): Promise<void>;
+    /**
+     * One-click unsubscribe, from the link's lists (every list and all email when it names none, or none of them exists any more).
+     * A link from a campaign message counts the unsubscribe in that campaign's statistics. Answers with a preferences token, so the
+     * landing page can offer the preference center.
+     */
+    unsubscribe(token: string, req: HttpRequest): Promise<{
+        workspaceName: string;
+        list?: string;
+        preferencesToken: string;
+    }>;
+    /** Records the unsubscribe on the outbound message the link came in, if it names one of the contact's. */
+    private countUnsubscribe;
+    /** Counts one request of `kind` against the caller's address. */
+    private limit;
+    /** The anonymous caller's address - `resolveClientIp()`, so a forged `X-Forwarded-For` from an untrusted peer is ignored. */
+    protected clientAddress(req: HttpRequest): string | undefined;
+    private contacts;
+    private requireForm;
+    private contactProperties;
+    /**
+     * The submitted value of each of the form's fields, checked: the email address, text fields as text, and each custom property as its
+     * type (a number, yes/no, a date, one option or several). A required field left empty, or a value that doesn't fit, is a 400.
+     */
+    private readFormValues;
+    /** A form's input for a custom property as the property's type. */
+    private propertyInput;
+    /**
+     * What a submission writes to its contact: every submitted field for a new contact (with the form's tags and source `form`); for an
+     * existing one only the fields and properties it doesn't have yet, so a form can't overwrite what a workspace knows about someone.
+     * A company name links the contact to that company (found by name, or created) when it has none.
+     */
+    private contactWrite;
+    /** The workspace's company named `name`, created when there is none. */
+    private companyByName;
+    /** Emails the subscriber a link confirming their pending subscriptions to `lists`, from the form's sender. Never throws. */
+    private sendConfirmation;
+    private countSubmission;
+    private findSubscription;
+    private findContact;
+    /** The token's payload, workspace and contact - or a 404 for a bad token or one whose workspace or contact is gone. */
+    private resolveToken;
+    private preferencesView;
+    /** Unsubscribes the contact from every list, and marks them as not wanting any marketing email. */
+    private unsubscribeAll;
+    /** Takes back a contact's "unsubscribe from all" once they subscribe again. A bounced or complaining address stays as it is. */
+    private reactivate;
+    /** Moves the contact's `emailStatus` to `to` when it is `from`, with a timeline entry. */
+    private setEmailStatus;
+}

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

@@ -0,0 +1,16 @@
+import { SavedBlock } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many saved blocks one workspace may have. */
+export declare const MAX_SAVED_BLOCK_RECORDS = 500;
+/**
+ * Blocks saved for reuse in a workspace's templates (`/api/mail/crm/saved-blocks`) - see `BaseWorkspaceRecordRoute` for the endpoints.
+ * The blocks are checked and sanitized like a template's; hand-written HTML only from a workspace admin.
+ */
+export declare abstract class BaseSavedBlockRoute extends BaseWorkspaceRecordRoute<SavedBlock> {
+    protected readonly model: "savedBlock";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<SavedBlock>>;
+    protected readUpdate(body: Record<string, unknown>, _existing: SavedBlock, context: WriteContext): Promise<Partial<SavedBlock>>;
+}

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

@@ -0,0 +1,33 @@
+import type { JWTUser } from "@rapidrest/core";
+import { ScoringRule, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many scoring rules one workspace may have. */
+export declare const MAX_SCORING_RULES = 50;
+/**
+ * A workspace's lead scoring rules (`/api/mail/crm/scoring-rules`) - see `BaseWorkspaceRecordRoute` for the endpoints; changing them
+ * takes `MANAGE` - plus `POST /:workspaceUid/recalculate`, which scores every contact now (`{ changed }`).
+ *
+ * A contact's `score` is the sum of the enabled rules' points: a **property** rule gives its points to the contacts its filter matches
+ * (the same filters as segments, but not naming segments), an **activity** rule gives its points for each time a contact did something
+ * - opened, clicked, replied, bounced, submitted a form, subscribed, unsubscribed - in its last `withinDays`, up to `maxPoints`.
+ * `ScoringJob` rescores a workspace soon after its rules change, and regularly after that (activity windows move).
+ */
+export declare abstract class BaseScoringRuleRoute extends BaseWorkspaceRecordRoute<ScoringRule> {
+    protected readonly model: "scoringRule";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<ScoringRule>>;
+    protected readUpdate(body: Record<string, unknown>, existing: ScoringRule, context: WriteContext): Promise<Partial<ScoringRule>>;
+    /** The fields of a rule of `kind` in `body`: all of them when `creating`, else those given. */
+    private readRule;
+    protected afterWrite(record: ScoringRule): Promise<void>;
+    protected afterDelete(record: ScoringRule): Promise<void>;
+    /** Marks the workspace's scores out of date and counts its rules, so `ScoringJob` rescores it (and to 0, with none left). */
+    private touchWorkspace;
+    private updateWorkspace;
+    recalculate(workspaceUid: string, user?: JWTUser): Promise<{
+        changed: number;
+    }>;
+}

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

@@ -0,0 +1,36 @@
+import type { JWTUser } from "@rapidrest/core";
+import { CrmContact, Segment } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many segments one workspace may have. */
+export declare const MAX_SEGMENTS = 200;
+/**
+ * A workspace's segments (`/api/mail/crm/segments`) - see `BaseWorkspaceRecordRoute` for the endpoints - plus:
+ * - `POST /:workspaceUid/preview` - `{ filter }` to `{ count, capped, contacts }`: how many contacts a filter matches now, and the
+ * first few, for the segment editor.
+ * - `POST /:workspaceUid/:uid/refresh` - works the members out again now (a static segment's only way to change).
+ *
+ * Members are worked out when a segment is created and whenever its filter or kind changes; `SegmentRefreshJob` keeps dynamic ones
+ * current after that. A segment's filter may not name segments.
+ */
+export declare abstract class BaseSegmentRoute extends BaseWorkspaceRecordRoute<Segment> {
+    protected readonly model: "segment";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Segment>>;
+    protected readUpdate(body: Record<string, unknown>, _existing: Segment, context: WriteContext): Promise<Partial<Segment>>;
+    /** A new segment, or one whose filter or kind changed, gets its members at once. */
+    protected afterWrite(record: Segment, before: Segment | undefined): Promise<Segment | void>;
+    protected afterDelete(record: Segment): Promise<void>;
+    /**
+     * Works `segment`'s members out and saves the counts. Returns the segment as saved. With `events`, who entered and left is
+     * recorded for automations - not on a segment's first working out, or everyone in it would count as just entered.
+     */
+    private refresh;
+    preview(workspaceUid: string, body: unknown, user?: JWTUser): Promise<{
+        count: number;
+        capped: boolean;
+        contacts: Pick<CrmContact, "uid" | "email" | "firstName" | "lastName">[];
+    }>;
+    refreshNow(workspaceUid: string, uid: string, user?: JWTUser): Promise<Segment>;
+}

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

@@ -0,0 +1,20 @@
+import { type JWTUser } from "@rapidrest/core";
+import { Subscription } from "../models/types.js";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** How many contacts one subscription request may change. */
+export declare const MAX_SUBSCRIPTION_BATCH = 500;
+/**
+ * Contacts' subscriptions to a workspace's lists (`/api/mail/crm/subscriptions`):
+ * - `GET /:workspaceUid` - subscriptions, newest first, narrowed by `listUid`, `contactUid` and `status`.
+ * - `POST /:workspaceUid` - `{ listUid, contactUids, status }` subscribes (`subscribed`) or unsubscribes (`unsubscribed`) up to
+ * `MAX_SUBSCRIPTION_BATCH` contacts at once, as a member (source `manual`). A member can't make a subscription pending: only a
+ * form's double opt-in does that.
+ *
+ * Reading takes `READ` on the workspace, changing `WRITE`.
+ */
+export declare abstract class BaseSubscriptionRoute extends CrmRouteBase {
+    list(workspaceUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<Subscription[]>;
+    change(workspaceUid: string, body: unknown, user?: JWTUser): Promise<{
+        changed: number;
+    }>;
+}

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

@@ -0,0 +1,17 @@
+import { Suppression, WorkspaceAction } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/**
+ * A workspace's suppression list (`/api/mail/crm/suppressions`) - see `BaseWorkspaceRecordRoute` for the endpoints: addresses no
+ * campaign or automation ever mails, whatever lists they are on. Bounces and spam complaints add to it on their own (Phase 4); a
+ * member with `MANAGE` adds and removes addresses by hand. `GET /:workspaceUid` takes `email` to look one address up. Only an
+ * entry's note can change.
+ */
+export declare abstract class BaseSuppressionRoute extends BaseWorkspaceRecordRoute<Suppression> {
+    protected readonly model: "suppression";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly sortFields: readonly string[];
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<Suppression>>;
+    protected readUpdate(body: Record<string, unknown>, existing: Suppression): Promise<Partial<Suppression>>;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+}

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

@@ -0,0 +1,85 @@
+import { type JWTUser } from "@rapidrest/core";
+import { HttpResponse } from "@rapidrest/service-core";
+import { FilterField } from "../filters/Filter.js";
+import { CrmObjectType, PropertyDefinition } from "../models/types.js";
+import { PropertyViewValue, StoredValue } from "../util/PropertyValues.js";
+import { BaseWorkspaceRecordRoute, WorkspaceRecord, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** A contact or company: a workspace record with tags and custom properties. */
+export interface TaggedRecord extends WorkspaceRecord {
+    tags: string[];
+    ownerUserUid?: string;
+}
+/** A contact or company as the API shows it: the record plus its custom property values. */
+export type TaggedRecordView<T> = T & {
+    properties: Record<string, PropertyViewValue>;
+};
+/** How many records one bulk request may change. */
+export declare const MAX_BULK = 500;
+/** How many records one export may hold, by default (`mail:crm:export:max_rows`). */
+export declare const MAX_EXPORT_ROWS = 50000;
+/** The bulk actions (`POST /:workspaceUid/bulk`). */
+export type BulkAction = "delete" | "addTags" | "removeTags" | "setOwner";
+/**
+ * What contacts and companies share on top of `BaseWorkspaceRecordRoute`: tags and custom properties on every write (a request's
+ * `tags` and `properties`, stored as `PropertyValue` rows - `util/PropertyValues.ts`), filtered search (`filter` compiled by
+ * `filters/Filter.ts`, and `q` for a quick text search), bulk actions, CSV export, and an activity timeline entry for every create
+ * and change. Deleting a record deletes its values, notes and timeline, and unlinks the tasks about it.
+ */
+export declare abstract class BaseTaggedRecordRoute<T extends TaggedRecord> extends BaseWorkspaceRecordRoute<T, TaggedRecordView<T>> {
+    /** The `CrmObjectType` of the records. */
+    protected abstract readonly objectType: CrmObjectType;
+    /** The record's own filterable fields (`CONTACT_FIELDS`/`COMPANY_FIELDS`). */
+    protected abstract readonly recordFields: Readonly<Record<string, FilterField>>;
+    /** The fields `q` searches, case-insensitively. */
+    protected abstract readonly textFields: readonly string[];
+    /** The record's own fields an export lists, in order. */
+    protected abstract readonly exportFields: readonly string[];
+    /** How a record is named on its timeline and in exports' file names. */
+    protected abstract readonly noun: string;
+    /** How many records one export may hold. */
+    protected maxExportRows: number;
+    /** How many records an export reads at a time. */
+    protected exportPageSize: number;
+    /** The record's own fields a CSV column may be imported into, and how its text is read (`number`: as a number). */
+    abstract readonly importFields: Readonly<Record<string, "text" | "number">>;
+    /** The workspace's record an imported row is the same as (by email for a contact, by domain or name for a company). */
+    protected abstract findExisting(workspaceUid: string, body: Record<string, unknown>): Promise<T | undefined>;
+    /**
+     * Creates or updates one record from an imported row (`body` in the shape of a create request, as `CrmImportJob` builds it), with
+     * the same checks and side effects as the API: a row the same as an existing record updates it when `updateExisting` is set -
+     * adding its tags to the record's rather than replacing them - and is skipped otherwise. A bad row throws its 400.
+     */
+    importRow(workspaceUid: string, userUid: string, body: Record<string, unknown>, updateExisting: boolean): Promise<{
+        outcome: "created" | "updated" | "skipped";
+        uid: string;
+    }>;
+    /** The workspace's custom property definitions for this record type. */
+    protected definitions(workspaceUid: string): Promise<PropertyDefinition[]>;
+    protected toViews(records: T[], workspaceUid: string): Promise<TaggedRecordView<T>[]>;
+    /** Checks a write's `properties` before the record is written, so a bad value fails the whole request. */
+    protected readPropertyWrites(body: Record<string, unknown>, workspaceUid: string): Promise<Map<string, StoredValue[]>>;
+    protected afterWrite(record: T, before: T | undefined, body: Record<string, unknown>, context: WriteContext): Promise<void>;
+    /**
+     * Changes `existing` as `PUT /:workspaceUid/:uid` with `body` would, on behalf of `actorUid` (empty for nobody in particular) - for
+     * automations, which change records outside any request. Returns the record as saved.
+     */
+    applyUpdate(workspaceUid: string, actorUid: string, existing: T, body: Record<string, unknown>): Promise<T>;
+    protected afterDelete(record: T, context: WriteContext): Promise<void>;
+    /** Deletes what belongs to the records `uids` - their values, notes and timeline - and unlinks the tasks about them. */
+    protected deleteRelated(uids: string[], workspaceUid: string): Promise<void>;
+    protected searchQuery(body: Record<string, unknown>, workspaceUid: string): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Applies one action to up to `MAX_BULK` records: `delete`, `addTags`/`removeTags` (`tags`), or `setOwner` (`ownerUserUid`, a
+     * member, or `null`). Records that aren't the workspace's are skipped. Answers how many were changed.
+     */
+    bulk(workspaceUid: string, body: unknown, user?: JWTUser): Promise<{
+        changed: number;
+    }>;
+    /** One record's bulk change, through the same `afterWrite()` a single update runs. */
+    private writeBulk;
+    /**
+     * The records matching a search (`filter`, `q`, `sort` - as `POST /:workspaceUid/search`) as a CSV file: the record's own fields,
+     * then `tags` (separated by `;`), then one column per custom property. At most `MAX_EXPORT_ROWS` rows.
+     */
+    export(workspaceUid: string, body: unknown, res: HttpResponse, user?: JWTUser): Promise<HttpResponse>;
+}

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

@@ -0,0 +1,18 @@
+import { CrmTask } from "../models/types.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/**
+ * A workspace's tasks (`/api/mail/crm/tasks`) - see `BaseWorkspaceRecordRoute` for the endpoints. `GET /:workspaceUid` takes `status`,
+ * `assigneeUserUid` and `subjectUid`. A task is assigned to a member (its creator unless it says otherwise) and may be about a
+ * contact or company, whose timeline then shows it being created and done. Marking a task `done` stamps `completedAt`; reopening it
+ * clears it.
+ */
+export declare abstract class BaseTaskRoute extends BaseWorkspaceRecordRoute<CrmTask> {
+    protected readonly model: "task";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<CrmTask>>;
+    protected readUpdate(body: Record<string, unknown>, existing: CrmTask, context: WriteContext): Promise<Partial<CrmTask>>;
+    private readFields;
+    protected afterWrite(record: CrmTask, before: CrmTask | undefined, _body: Record<string, unknown>, context: WriteContext): Promise<void>;
+    protected listQuery(query: Record<string, unknown>): Record<string, unknown>;
+}

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

@@ -0,0 +1,52 @@
+import { type JWTUser } from "@rapidrest/core";
+import { type MailTransport } from "@rapidmx/restapi";
+import { EmailTemplate } from "../models/types.js";
+import { DesignBlock } from "../templates/Design.js";
+import { RenderedEmail } from "../templates/Render.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many templates one workspace may have. */
+export declare const MAX_TEMPLATES = 1000;
+/** A template as the API shows it: the template, and whether its design lets readers unsubscribe (campaigns require it). */
+export interface EmailTemplateView extends EmailTemplate {
+    hasUnsubscribeLink: boolean;
+}
+/**
+ * A workspace's email templates (`/api/mail/crm/templates`) - see `BaseWorkspaceRecordRoute` for the endpoints - plus:
+ * - `POST /:workspaceUid/render` - `{ design, subject, preheader?, contactUid? }` to `{ subject, html, text }`: a preview of a design, saved
+ * or not, for one contact or a made-up reader.
+ * - `POST /:workspaceUid/:uid/test` - `{ to, senderUid, contactUid? }`: sends the template to one address of a mailbox the caller can
+ * read (so a test send can't mail strangers), subject prefixed "[Test]".
+ * - `POST /:workspaceUid/:uid/duplicate` - a copy named "Copy of ...".
+ * - `GET /:workspaceUid/merge-tags` - the merge tags a template can use, the workspace's custom properties included.
+ *
+ * A template's design is checked and sanitized on save (`templates/Design.ts`), compiled with MJML, and its merge tags are parsed, so a
+ * template that can't be sent is refused at once. Hand-written HTML blocks can only be added or changed by workspace admins.
+ */
+export declare abstract class BaseTemplateRoute extends BaseWorkspaceRecordRoute<EmailTemplate, EmailTemplateView> {
+    protected readonly model: "template";
+    protected readonly pushType: string;
+    protected readonly sortFields: readonly string[];
+    protected readonly maxRecords: number;
+    protected mailTransport?: MailTransport;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<EmailTemplate>>;
+    protected readUpdate(body: Record<string, unknown>, existing: EmailTemplate, context: WriteContext): Promise<Partial<EmailTemplate>>;
+    private readFields;
+    /** The design of a request, checked - hand-written HTML only from an admin, unless unchanged from `existing`. */
+    private readDesign;
+    /** Refuses a design MJML can't lay out, or a subject or design with a broken merge tag. */
+    private checkCompiles;
+    protected toViews(records: EmailTemplate[]): Promise<EmailTemplateView[]>;
+    mergeTags(workspaceUid: string, user?: JWTUser): Promise<{
+        tag: string;
+        label: string;
+    }[]>;
+    render(workspaceUid: string, body: unknown, user?: JWTUser): Promise<RenderedEmail>;
+    test(workspaceUid: string, uid: string, body: unknown, user?: JWTUser): Promise<{
+        sent: string;
+    }>;
+    duplicate(workspaceUid: string, uid: string, user?: JWTUser): Promise<EmailTemplateView>;
+}
+/** How long a saved block's name may be, and how many blocks it may hold. */
+export declare const MAX_SAVED_BLOCKS = 20;
+/** Reads the `blocks` of a saved block request, checked like a design's. */
+export declare function readSavedBlocks(raw: unknown, allowHtml: boolean): DesignBlock[];

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

@@ -0,0 +1,10 @@
+import { type JWTUser } from "@rapidrest/core";
+import { TimelineEvent } from "../models/types.js";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/**
+ * A contact's or company's activity timeline (`/api/mail/crm/timeline`): `GET /:workspaceUid/:subjectType/:subjectUid`, newest first,
+ * a page at a time (`limit`, `page`). Read-only: entries are added by the changes they record.
+ */
+export declare abstract class BaseTimelineRoute extends CrmRouteBase {
+    list(workspaceUid: string, subjectType: string, subjectUid: string, query: Record<string, unknown> | undefined, user?: JWTUser): Promise<TimelineEvent[]>;
+}

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

@@ -0,0 +1,21 @@
+import { HttpRequest, HttpResponse } from "@rapidrest/service-core";
+import { CrmRouteBase } from "./CrmRouteBase.js";
+/** How many opens, and clicks, of one message are recorded; beyond that they are served but not counted. */
+export declare const MAX_TRACKED_OPENS = 100;
+export declare const MAX_TRACKED_CLICKS = 500;
+/**
+ * The anonymous endpoints CRM email calls home through (`/api/mail/crm/t`):
+ * - `GET /o/:token` - the invisible image that records an open. Always answers with the image, whatever the token.
+ * - `GET /c/:token/:index?u=<url>&s=<signature>` - a tracked link: records the click and redirects to `u`. The signature
+ * (`clickPath()`) must match, so the redirect only ever goes where the email's link did - a forged or changed link is a 404.
+ *
+ * Opens and clicks from scanners and previewers are recorded as `machine` (`isMachine()`), which statistics leave out of opens.
+ */
+export declare abstract class BaseTrackingRoute extends CrmRouteBase {
+    open(token: string, req: HttpRequest, res: HttpResponse): Promise<void>;
+    click(token: string, index: string, query: Record<string, unknown> | undefined, req: HttpRequest, res: HttpResponse): Promise<void>;
+    private findSend;
+    /** Records an open or click. A failure is logged: the reader still gets the image or their link. */
+    private record;
+    private userAgent;
+}

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

@@ -0,0 +1,49 @@
+import type { JWTUser } from "@rapidrest/core";
+import { WebhookDelivery, WebhookEndpoint, WorkspaceAction } from "../models/types.js";
+import { WebhookPoster } from "../webhooks/Webhooks.js";
+import { BaseWorkspaceRecordRoute, WriteContext } from "./BaseWorkspaceRecordRoute.js";
+/** How many webhook endpoints one workspace may have. */
+export declare const MAX_WEBHOOKS = 20;
+/** The event types an endpoint may take, besides `*` (all). */
+export declare const WEBHOOK_EVENTS: readonly string[];
+/** An endpoint as the API shows it: its secret only as its last characters. */
+export interface WebhookEndpointView extends Omit<WebhookEndpoint, "secret"> {
+    secretHint: string;
+}
+/**
+ * A workspace's webhook endpoints (`/api/mail/crm/webhooks`) - see `BaseWorkspaceRecordRoute` for the endpoints; changing them takes
+ * `MANAGE` - plus:
+ * - `POST /:workspaceUid/:uid/secret` - makes a new signing secret and answers it (`{ secret }`), the only time it is shown in full
+ * besides creation (`POST` answers `secret` once).
+ * - `POST /:workspaceUid/:uid/test` - posts a `ping` now and answers `{ status }` or `{ error }`.
+ * - `GET /:workspaceUid/:uid/deliveries` - the 50 latest deliveries.
+ *
+ * Addresses must be `https://` on the public internet (checked again, by resolving the host, whenever something is sent). Switching
+ * an endpoint back on clears its failure count.
+ */
+export declare abstract class BaseWebhookRoute extends BaseWorkspaceRecordRoute<WebhookEndpoint, WebhookEndpointView> {
+    protected readonly model: "webhookEndpoint";
+    protected readonly pushType: string;
+    protected readonly writeAction: WorkspaceAction;
+    protected readonly maxRecords: number;
+    /** How a webhook is posted - a seam for tests. */
+    protected post: WebhookPoster;
+    protected readCreate(body: Record<string, unknown>, context: WriteContext): Promise<Partial<WebhookEndpoint>>;
+    protected readUpdate(body: Record<string, unknown>, existing: WebhookEndpoint): Promise<Partial<WebhookEndpoint>>;
+    private readUrl;
+    private readEvents;
+    protected toViews(records: WebhookEndpoint[]): Promise<WebhookEndpointView[]>;
+    /** A new endpoint's secret is answered once, with it. */
+    create(workspaceUid: string, body: unknown, user?: JWTUser): Promise<WebhookEndpointView & {
+        secret?: string;
+    }>;
+    rotateSecret(workspaceUid: string, uid: string, user?: JWTUser): Promise<{
+        secret: string;
+    }>;
+    test(workspaceUid: string, uid: string, user?: JWTUser): Promise<{
+        status?: number;
+        error?: string;
+    }>;
+    deliveries(workspaceUid: string, uid: string, user?: JWTUser): Promise<WebhookDelivery[]>;
+    protected afterDelete(record: WebhookEndpoint): Promise<void>;
+}