@rapidmx/crm-plugin 0.1.0

package/dist/lib/webhooks/Webhooks.js

@@ -0,0 +1,132 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import * as crypto from "crypto";
+import { promises as dns } from "dns";
+import * as https from "https";
+import * as net from "net";
+/** How long a webhook request may take. */
+export const WEBHOOK_TIMEOUT_MS = 10000;
+/** The largest body a webhook posts. */
+export const MAX_PAYLOAD_BYTES = 256 * 1024;
+/** A new endpoint secret. */
+export function newWebhookSecret() {
+    return `whsec_${crypto.randomBytes(24).toString("base64url")}`;
+}
+/**
+ * The signature header of a webhook body: `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">` - the timestamp is signed too, so a
+ * receiver can refuse replays.
+ */
+export function signWebhook(secret, body, timestamp = Math.floor(Date.now() / 1000)) {
+    return `t=${timestamp},v1=${crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
+}
+/** An IPv4 address as a 32-bit number. */
+function ipv4Number(address) {
+    return address.split(".").reduce((value, part) => value * 256 + Number(part), 0);
+}
+const PRIVATE_V4 = [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+];
+/**
+ * Whether `address` (an IP) is on the public internet: not loopback, private, link-local, carrier-grade NAT, documentation,
+ * multicast or reserved - IPv4, IPv6, and IPv4 mapped into IPv6.
+ */
+export function isPublicAddress(address) {
+    if (net.isIPv4(address)) {
+        const value = ipv4Number(address);
+        return !PRIVATE_V4.some(([base, bits]) => Math.floor(value / 2 ** (32 - bits)) === Math.floor(ipv4Number(base) / 2 ** (32 - bits)));
+    }
+    if (!net.isIPv6(address)) {
+        return false;
+    }
+    const lower = address.toLowerCase();
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower);
+    if (mapped) {
+        return isPublicAddress(mapped[1]);
+    }
+    if (lower === "::" || lower === "::1") {
+        return false;
+    }
+    const first = parseInt(lower.split(":")[0] || "0", 16);
+    // fc00::/7 unique local, fe80::/10 link-local, ff00::/8 multicast, 2001:db8::/32 documentation.
+    return !((first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80 || (first & 0xff00) === 0xff00 || lower.startsWith("2001:db8:"));
+}
+/** Refuses (throws) a webhook address that isn't `https://` on a host name or public address. */
+export function checkWebhookUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("The address isn't a valid URL.");
+    }
+    if (url.protocol !== "https:") {
+        throw new Error("The address must start with https://.");
+    }
+    if (url.username || url.password) {
+        throw new Error("The address can't hold a user name or password.");
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (net.isIP(host) && !isPublicAddress(host)) {
+        throw new Error("The address must be on the public internet.");
+    }
+    if (/^(localhost|.*\.localhost|.*\.local|.*\.internal)$/i.test(host)) {
+        throw new Error("The address must be on the public internet.");
+    }
+    return url;
+}
+export const defaultLookup = async (hostname) => await dns.lookup(hostname, { all: true, verbatim: true });
+/**
+ * Posts `body` to `rawUrl`, signed with `secret`. The host is resolved first and every address it resolves to must be public; the
+ * request then goes to the first of those addresses (with the host name kept for TLS and `Host`), so a name can't be switched to an
+ * internal address between the check and the connection. Redirects aren't followed. Throws on a refused address, a network error or
+ * a timeout; answers the status otherwise (the caller decides what counts as delivered).
+ */
+export async function postWebhook(rawUrl, body, secret, options = {}) {
+    const { lookup = defaultLookup, timeoutMs = WEBHOOK_TIMEOUT_MS, request: send = https.request } = options;
+    const url = checkWebhookUrl(rawUrl);
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    const addresses = net.isIP(host) ? [{ address: host, family: net.isIP(host) }] : await lookup(host);
+    if (addresses.length === 0 || addresses.some((entry) => !isPublicAddress(entry.address))) {
+        throw new Error("The address resolves to a private network.");
+    }
+    const target = addresses[0];
+    return await new Promise((resolve, reject) => {
+        const request = send({
+            protocol: "https:",
+            hostname: host,
+            port: url.port || 443,
+            path: `${url.pathname}${url.search}`,
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "content-length": Buffer.byteLength(body),
+                "user-agent": "RapidMX-CRM-Webhooks/1",
+                "x-rapidmx-signature": signWebhook(secret, body),
+            },
+            timeout: timeoutMs,
+            lookup: (_hostname, _options, callback) => callback(null, target.address, target.family),
+        }, (response) => {
+            response.resume();
+            resolve({ status: response.statusCode ?? 0 });
+        });
+        request.on("timeout", () => request.destroy(new Error(`No answer within ${timeoutMs / 1000} seconds.`)));
+        request.on("error", reject);
+        request.end(body);
+    });
+}
+//# sourceMappingURL=Webhooks.js.map

package/dist/lib/webhooks/Webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Webhooks.js","sourceRoot":"","sources":["../../../src/webhooks/Webhooks.ts"],"names":[],"mappings":"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"}

package/dist/types/automation/Dates.d.ts

@@ -0,0 +1,42 @@
+/** The contact's own date fields a date trigger can use, besides custom date properties (`properties.<key>`). */
+export declare const DATE_TRIGGER_FIELDS: readonly string[];
+/** How far before (negative) or after the date a trigger may fire, in days. */
+export declare const MAX_DATE_OFFSET = 365;
+/** How a date trigger repeats. */
+export declare enum DateRepeat {
+    /** On the date's anniversary each year (birthdays, renewals, signup anniversaries). */
+    YEARLY = "yearly",
+    /** On the date itself, once. */
+    ONCE = "once"
+}
+/** A date trigger's settings, as checked. */
+export interface DateTrigger {
+    /** `dateCreated`, `lastEngagedAt` or `properties.<key>` of a date property. */
+    field: string;
+    /** Days after the date (negative: before). */
+    offsetDays: number;
+    repeat: DateRepeat;
+    /** The hour of the day (in the workspace's time zone) from which contacts are put in. */
+    hour: number;
+}
+/** A date trigger's settings from a trigger step's config, or a 400 naming `where`. */
+export declare function readDateTrigger(config: Record<string, unknown>, where: string): DateTrigger;
+/** `now`'s calendar day (`YYYY-MM-DD`) and hour in `timeZone` (UTC if it isn't one). */
+export declare function localTime(now: Date, timeZone: string): {
+    date: string;
+    hour: number;
+};
+/** The day `days` after (before, if negative) `date`, both `YYYY-MM-DD`. */
+export declare function addDays(date: string, days: number): string;
+/**
+ * Whether the day `target` is an anniversary of `date` (both `YYYY-MM-DD`): the same month and day in a later year. A 29 February
+ * comes round on 28 February in other years.
+ */
+export declare function isAnniversary(date: string, target: string): boolean;
+/**
+ * The calendar day of a date value: a custom date property holds a day (kept as UTC midnight), so its UTC day; the contact's own
+ * fields are moments, so their day in the workspace's time zone.
+ */
+export declare function dayOf(value: Date | string, field: string, timeZone: string): string;
+/** Whether a date value `day` (`YYYY-MM-DD`) makes a trigger fire on `today`. */
+export declare function dateFires(trigger: Pick<DateTrigger, "offsetDays" | "repeat">, day: string, today: string): boolean;

package/dist/types/automation/Engine.d.ts

@@ -0,0 +1,63 @@
+import { NotificationUtils } from "@rapidrest/service-core";
+import type { CrmModelClasses, CrmRepos } from "../models/CrmModelClasses.js";
+import { Automation, AutomationVersion, CrmContact, CrmEvent, Enrollment, OutboundSend } from "../models/types.js";
+import type { BaseContactRoute } from "../routes/BaseContactRoute.js";
+import { AutomationGraph, AutomationNode } from "./Graph.js";
+/** How many steps one run takes an enrollment through before handing it to the next run. */
+export declare const STEPS_PER_RUN = 25;
+/** How many steps an enrollment may take in all: a contact going round a loop this often has gone wrong. */
+export declare const MAX_STEPS = 1000;
+/** How many recent steps an enrollment keeps. */
+export declare const HISTORY_SIZE = 50;
+/** Whether `contact` matches the contact filter `filter` (checked in memory, as `compileFilter()` would in a query). */
+export declare function contactMatches(repos: CrmRepos, contact: CrmContact, filter: unknown): Promise<boolean>;
+/** Whether `event` starts an automation whose trigger step is `trigger` - before the trigger's contact filter, if it has one. */
+export declare function triggerMatches(trigger: AutomationNode, event: Pick<CrmEvent, "type" | "data">): boolean;
+/** A graph's trigger step. */
+export declare function triggerOf(graph: AutomationGraph): AutomationNode | undefined;
+/** What the engine needs from its job or route. */
+export interface EngineContext {
+    repos: CrmRepos;
+    classes: CrmModelClasses;
+    /** The backend's contact route, for changes that must run the route's own logic (tags, subscriptions, the timeline). */
+    contactRoute?: () => Promise<BaseContactRoute>;
+    notificationUtils?: NotificationUtils;
+    logger?: any;
+}
+/**
+ * Enrolls contacts in automations and takes them through their steps. Shared by the jobs (`AutomationTriggerJob`,
+ * `AutomationRunJob`) and the automation route (enrolling by hand).
+ */
+export declare class AutomationEngine {
+    private readonly context;
+    constructor(context: EngineContext);
+    private repo;
+    /**
+     * Puts `contactUid` into `automation`'s published version, at the step after its trigger - unless the automation's re-entry rule
+     * says no (`never`: they were ever in it; `after_exit`: they are in it now). Returns the enrollment, or `undefined`.
+     */
+    enroll(automation: Automation, version: AutomationVersion, contactUid: string, outcome: string): Promise<Enrollment | undefined>;
+    /**
+     * Takes a claimed enrollment through as many steps as it can now (at most `STEPS_PER_RUN`): up to a delay or a wait, or to the end.
+     * Returns the enrollment's changes, to save with its lease released.
+     */
+    advance(enrollment: Enrollment, automation: Automation, graph: AutomationGraph): Promise<Partial<Enrollment>>;
+    /**
+     * Resumes the enrollments of `event.contactUid` waiting for this event about this message, by their wait's `matched` way.
+     * Returns how many were resumed.
+     */
+    resumeWaiting(event: Pick<CrmEvent, "type" | "contactUid" | "data">): Promise<number>;
+    /** Runs one step. */
+    private execute;
+    /** The message this enrollment's `send_email` step `nodeId` queued, if it did. */
+    private sendOf;
+    /** Queues the step's email for the contact - once per enrollment and step, however often the step is run again. */
+    private queueEmail;
+    private contact;
+    /** Changes the contact through the contact route, so tags, the timeline and events follow as for any change. */
+    private updateContact;
+    private finished;
+    private timeline;
+}
+/** Whether what a wait waits for already happened to `send`. */
+export declare function happened(send: OutboundSend, event: string): boolean;

package/dist/types/automation/Events.d.ts

@@ -0,0 +1,43 @@
+import type { CrmModelClasses, CrmRepos } from "../models/CrmModelClasses.js";
+/** The events automations can start from or wait for. */
+export declare enum CrmEventType {
+    CONTACT_CREATED = "contact.created",
+    CONTACT_UPDATED = "contact.updated",
+    LIST_SUBSCRIBED = "list.subscribed",
+    LIST_UNSUBSCRIBED = "list.unsubscribed",
+    FORM_SUBMITTED = "form.submitted",
+    SEGMENT_ENTERED = "segment.entered",
+    SEGMENT_LEFT = "segment.left",
+    EMAIL_SENT = "email.sent",
+    EMAIL_OPENED = "email.opened",
+    EMAIL_CLICKED = "email.clicked",
+    EMAIL_REPLIED = "email.replied",
+    EMAIL_BOUNCED = "email.bounced",
+    EMAIL_UNSUBSCRIBED = "email.unsubscribed",
+    DEAL_CREATED = "deal.created",
+    DEAL_STAGE_CHANGED = "deal.stage_changed",
+    DEAL_WON = "deal.won",
+    DEAL_LOST = "deal.lost",
+    /** Something the workspace's own systems reported through the integration API (`data.name` says what). */
+    CUSTOM = "custom",
+    /**
+     * A contact reached a date (a birthday, a renewal, their signup anniversary): never an event of its own - `DateTriggerJob` puts
+     * contacts into automations with this trigger directly.
+     */
+    DATE_REACHED = "date.reached",
+    /** A member put the contact in (`POST /automations/:ws/:uid/enroll`, or another automation's `enroll` step). */
+    MANUAL = "manual"
+}
+/** One event, before it's stored. */
+export interface CrmEventInput {
+    workspaceUid: string;
+    type: CrmEventType;
+    contactUid: string;
+    /** What the triggers and waits match on: `listUid`, `formUid`, `segmentUid`, `sendUid`, `sourceUid`, `fields`... */
+    data?: Record<string, unknown>;
+}
+/**
+ * Records that something happened to a contact, for automations (`AutomationTriggerJob`). Never throws: an event that can't be
+ * recorded is logged, and whatever caused it still happens.
+ */
+export declare function recordCrmEvent(repos: CrmRepos, classes: CrmModelClasses, event: CrmEventInput, logger?: any): Promise<void>;

package/dist/types/automation/Graph.d.ts

@@ -0,0 +1,77 @@
+import { CrmEventType } from "./Events.js";
+/** What an automation step does. */
+export declare enum NodeType {
+    TRIGGER = "trigger",
+    DELAY = "delay",
+    WAIT = "wait",
+    CONDITION = "condition",
+    SPLIT = "split",
+    SEND_EMAIL = "send_email",
+    SET_FIELD = "set_field",
+    ADD_TAG = "add_tag",
+    REMOVE_TAG = "remove_tag",
+    SUBSCRIBE = "subscribe",
+    UNSUBSCRIBE = "unsubscribe",
+    CREATE_TASK = "create_task",
+    NOTIFY = "notify",
+    ENROLL = "enroll",
+    WEBHOOK = "webhook",
+    EXIT = "exit"
+}
+/** One step of an automation. `config` depends on `type` - see `NODE_SPECS`. */
+export interface AutomationNode {
+    id: string;
+    type: NodeType;
+    config: Record<string, unknown>;
+}
+/** A way from one step to the next: out of `from` by `port` (`next`, or a branch: `yes`/`no`, `a`/`b`, `matched`/`timeout`). */
+export interface AutomationEdge {
+    from: string;
+    to: string;
+    port: string;
+}
+export interface AutomationGraph {
+    nodes: AutomationNode[];
+    edges: AutomationEdge[];
+}
+/** The events a trigger can start from. */
+export declare const TRIGGER_EVENTS: readonly CrmEventType[];
+/** The events a wait can wait for: something done with a message an earlier step sent. */
+export declare const WAIT_EVENTS: readonly CrmEventType[];
+/** The contact fields a `set_field` step may set. */
+export declare const SETTABLE_FIELDS: readonly string[];
+/** Units of time a delay or a wait's timeout counts in, in milliseconds. */
+export declare const TIME_UNITS: Readonly<Record<string, number>>;
+/** The ports out of each node type. */
+export declare const PORTS: Readonly<Record<NodeType, readonly string[]>>;
+/** How big a graph may get. */
+export declare const MAX_NODES = 200;
+/**
+ * `raw` as an automation graph, checked for shape only - node ids, types, edges between existing nodes on the ports their type has,
+ * one edge per port - so a half-built draft can be saved. `validateForPublish()` checks the rest.
+ */
+export declare function validateGraph(raw: unknown): AutomationGraph;
+/** The node `port` of `nodeId` leads to, if any. */
+export declare function nextNode(graph: AutomationGraph, nodeId: string, port?: string): string | undefined;
+/** The references a published graph makes, for the caller to check exist in the workspace. */
+export interface GraphReferences {
+    templates: Set<string>;
+    senders: Set<string>;
+    lists: Set<string>;
+    forms: Set<string>;
+    segments: Set<string>;
+    automations: Set<string>;
+    members: Set<string>;
+    pipelines: Set<string>;
+    webhooks: Set<string>;
+    /** Custom contact properties date triggers start from (their keys), to check are date properties. */
+    dateProperties: Set<string>;
+    /** Contact filters (triggers, conditions), to validate against the workspace's fields. */
+    filters: unknown[];
+}
+/**
+ * Checks that `graph` can be published: one trigger that nothing leads back to, every step reachable from it, every step's settings
+ * complete, every wait waiting on a message an earlier step sends, and no loop that doesn't pass a delay or a wait (a contact would
+ * spin through it). Returns what the settings refer to, for the caller to check.
+ */
+export declare function validateForPublish(graph: AutomationGraph): GraphReferences;

package/dist/types/filters/Filter.d.ts

@@ -0,0 +1,83 @@
+import { type RepoUtils } from "@rapidrest/service-core";
+import { CrmObjectType, PropertyDefinition, PropertyType } from "../models/types.js";
+/**
+ * The comparisons a filter condition can make. `contains`/`notContains`/`startsWith` are case-insensitive text matches; `in`/`notIn`
+ * take a list; `between` takes `[low, high]` (inclusive); `isSet`/`isNotSet` take no value. On a multi-valued field (`tags`, a
+ * multi-select property) `eq` means "has this value", `ne` "doesn't have it", `in` "has any of these" and `notIn` "has none of them".
+ */
+export type FilterOp = "eq" | "ne" | "contains" | "notContains" | "startsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "notIn" | "isSet" | "isNotSet";
+/** One comparison of one field: a record field (`email`), a custom property (`properties.<key>`) or `tags`. */
+export interface FilterCondition {
+    field: string;
+    op: FilterOp;
+    value?: unknown;
+}
+/** Conditions and groups combined: every one of `and`, or any one of `or`. A group has exactly one of the two. */
+export interface FilterGroup {
+    and?: FilterNode[];
+    or?: FilterNode[];
+}
+export type FilterNode = FilterCondition | FilterGroup;
+/** The value types a filterable field can hold. */
+export type FilterValueType = "string" | "number" | "date" | "boolean";
+/** A field a filter may name, and how. */
+export interface FilterField {
+    type: FilterValueType;
+    /** Stored as `PropertyValue` rows (custom properties and tags) rather than on the record itself. */
+    stored: "record" | "values";
+    /** One row per value (`tags`, a multi-select property). */
+    multi?: boolean;
+    /** For a select or enum field: the values it may hold. */
+    options?: readonly string[];
+    /** The `PropertyValue.key` of a `values` field. */
+    key?: string;
+}
+/** How deep groups may nest, and how many conditions and groups one filter may have. */
+export declare const MAX_FILTER_DEPTH = 5;
+export declare const MAX_FILTER_NODES = 50;
+/** How many values an `in`/`notIn` list may have. */
+export declare const MAX_FILTER_LIST = 200;
+/** How many records a condition on a custom property or tag may match before the filter is refused as too broad. */
+export declare const MAX_VALUE_MATCHES = 20000;
+/** The `PropertyValue` column a value of `type` is stored in. */
+export declare function valueColumn(type: FilterValueType): "stringValue" | "numberValue" | "dateValue";
+/** The filter value type a custom property's values are compared as. */
+export declare function propertyValueType(type: PropertyType): FilterValueType;
+/**
+ * Every field a filter on `objectType` records may name: the record's own `fields`, `tags`, `lists` and `segments` for contacts (the
+ * uids of the lists they are subscribed to and the segments they are in), and `properties.<key>` for each of the workspace's custom property `definitions` of that type.
+ */
+export declare function filterFields(fields: Readonly<Record<string, FilterField>>, definitions: readonly Pick<PropertyDefinition, "key" | "type" | "options" | "objectType">[], objectType: CrmObjectType): Record<string, FilterField>;
+/**
+ * Checks `node` against `fields` and returns it normalized: every condition's value coerced to its field's type (dates as `Date`s,
+ * tags lowercased), and nothing but `field`/`op`/`value` and `and`/`or` kept. A malformed filter, an unknown field, a comparison
+ * the field's type doesn't allow, or one that's too big is a 400.
+ */
+export declare function validateFilter(node: unknown, fields: Readonly<Record<string, FilterField>>): FilterNode;
+/** What `compileFilter()` needs to resolve conditions on custom properties and tags, and on record text it can't negate directly. */
+export interface FilterCompileContext {
+    workspaceUid: string;
+    objectType: CrmObjectType;
+    /** The workspace's `PropertyValue`s. */
+    valueRepo: RepoUtils<any>;
+    /** The records being filtered - for `notContains` on a record's own text, which is compiled as "not one of those that contain". */
+    recordRepo: RepoUtils<any>;
+}
+/**
+ * Compiles a validated filter (`validateFilter()`) into a query `RepoUtils.find()`/`count()` runs on both Mongo and SQL: record fields
+ * become column comparisons combined with `$and`/`$or`. A condition on a custom property or tag is resolved first against the
+ * `PropertyValue` rows (with an index) to the uids of the records it matches, and becomes `uid in (...)`. A negated condition on
+ * one (`ne`, `notIn`, `isNotSet`) - and `notContains` on a record's own text, which SQL can't express - becomes `uid not in` the
+ * records matching its positive form, so a record with no value at all counts as "not equal".
+ *
+ * The result doesn't restrict the workspace - `workspaceQuery()` adds that.
+ */
+export declare function compileFilter(node: FilterNode, fields: Readonly<Record<string, FilterField>>, context: FilterCompileContext): Promise<Record<string, unknown>>;
+/** `filter` limited to `workspaceUid`'s records: `{ workspaceUid, $and: [filter] }`, or just the workspace with no filter. */
+export declare function workspaceQuery(workspaceUid: string, filter?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Whether `record` (with its custom property values and tags in `values`, keyed by `PropertyValue.key`) matches a validated filter -
+ * the same answer `compileFilter()`'s query gives, for checking one record without a query (automation conditions, segment
+ * membership). Text comparisons ignore case like the query's `like()` does; `eq` on text is exact, as it is in the query.
+ */
+export declare function evaluateFilter(node: FilterNode, fields: Readonly<Record<string, FilterField>>, record: Record<string, unknown>, values: Readonly<Record<string, readonly unknown[]>>): boolean;

package/dist/types/filters/fields.d.ts

@@ -0,0 +1,9 @@
+import { FilterField } from "./Filter.js";
+/** The fields of a `CrmContact` a filter may compare (besides `tags` and custom properties - see `filterFields()`). */
+export declare const CONTACT_FIELDS: Readonly<Record<string, FilterField>>;
+/** The fields of a `CrmCompany` a filter may compare (besides `tags` and custom properties). */
+export declare const COMPANY_FIELDS: Readonly<Record<string, FilterField>>;
+/** A contact's own fields, in the order exports list them. */
+export declare const CONTACT_EXPORT_FIELDS: readonly string[];
+/** A company's own fields, in the order exports list them. */
+export declare const COMPANY_EXPORT_FIELDS: readonly string[];

package/dist/types/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A customer relationship management platform for a `@rapidmx/restapi`-based mail server: shared workspaces of contacts and
+ * companies with custom properties, tags, notes, tasks, an activity timeline, filtered search and CSV import and export; mailing
+ * lists, subscriptions with double opt-in, suppressions, signup forms and a subscriber preference center; a template designer,
+ * campaigns with tracking and A/B tests, segments, lead scoring, automations, sales pipelines, reports, webhooks and an integration
+ * API.
+ *
+ * This module exports only the backend-agnostic surface: the entity interfaces, the filter engine, the utilities and the abstract
+ * routes and jobs. The concrete Mongo/SQL classes a server loads come from this package's `./mongo` and `./sql` entry points.
+ */
+export * from "./models/types.js";
+export * from "./models/CrmModelClasses.js";
+export * from "./filters/Filter.js";
+export * from "./filters/fields.js";
+export * from "./util/Csv.js";
+export * from "./util/Mailer.js";
+export * from "./util/Tokens.js";
+export * from "./util/Secrets.js";
+export * from "./util/ImportMapping.js";
+export * from "./util/PropertyValues.js";
+export * from "./util/Validation.js";
+export * from "./util/WorkspaceAccess.js";
+export * from "./routes/CrmRouteBase.js";
+export * from "./routes/BaseWorkspaceRoute.js";
+export * from "./routes/BaseWorkspaceRecordRoute.js";
+export * from "./routes/BaseTaggedRecordRoute.js";
+export * from "./routes/BaseContactRoute.js";
+export * from "./routes/BaseCompanyRoute.js";
+export * from "./routes/BasePropertyDefinitionRoute.js";
+export * from "./routes/BaseNoteRoute.js";
+export * from "./routes/BaseTaskRoute.js";
+export * from "./routes/BaseTimelineRoute.js";
+export * from "./routes/BaseImportRoute.js";
+export * from "./routes/BaseListRoute.js";
+export * from "./routes/BaseSubscriptionRoute.js";
+export * from "./routes/BaseSuppressionRoute.js";
+export * from "./routes/BaseFormRoute.js";
+export * from "./routes/BasePublicRoute.js";
+export * from "./routes/BaseTemplateRoute.js";
+export * from "./routes/BaseSavedBlockRoute.js";
+export * from "./routes/BaseCampaignRoute.js";
+export * from "./routes/BaseTrackingRoute.js";
+export * from "./routes/BaseSegmentRoute.js";
+export * from "./routes/BaseScoringRuleRoute.js";
+export * from "./routes/BaseAutomationRoute.js";
+export * from "./routes/BasePipelineRoute.js";
+export * from "./routes/BaseDealRoute.js";
+export * from "./routes/BaseAnalyticsRoute.js";
+export * from "./routes/BaseWebhookRoute.js";
+export * from "./routes/BaseApiKeyRoute.js";
+export * from "./routes/BaseIntegrationRoute.js";
+export * from "./routes/BaseCrmAdminRoute.js";
+export * from "./automation/Events.js";
+export * from "./automation/Graph.js";
+export * from "./automation/Engine.js";
+export * from "./automation/Dates.js";
+export * from "./segments/Segments.js";
+export * from "./scoring/Scoring.js";
+export * from "./sending/Audience.js";
+export * from "./sending/CampaignRenderer.js";
+export * from "./sending/Engagement.js";
+export * from "./sending/Stats.js";
+export * from "./sending/Tracking.js";
+export * from "./templates/Design.js";
+export * from "./templates/MergeContext.js";
+export * from "./templates/Render.js";
+export * from "./templates/Sanitize.js";
+export * from "./jobs/CrmImportJob.js";
+export * from "./jobs/CrmJobBase.js";
+export * from "./jobs/CampaignJob.js";
+export * from "./jobs/SendDispatchJob.js";
+export * from "./jobs/CrmMailEventJob.js";
+export * from "./jobs/SegmentRefreshJob.js";
+export * from "./jobs/ScoringJob.js";
+export * from "./jobs/AutomationTriggerJob.js";
+export * from "./jobs/AutomationRunJob.js";
+export * from "./jobs/TaskReminderJob.js";
+export * from "./jobs/WebhookDeliveryJob.js";
+export * from "./jobs/DateTriggerJob.js";
+export * from "./webhooks/Webhooks.js";
+export * from "./webhooks/Deliveries.js";

package/dist/types/jobs/AutomationRunJob.d.ts

@@ -0,0 +1,18 @@
+import { CrmJobBase } from "./CrmJobBase.js";
+/**
+ * Takes due enrollments through their automations (`AutomationEngine.advance()`): those whose delay is over, whose wait timed out,
+ * or that have steps left. One replica per enrollment: an enrollment is leased with a version-checked update, and its changes are
+ * saved with the lease released. A paused automation's enrollments wait, checked again every `paused_retry_seconds`; a deleted
+ * automation's are ended.
+ */
+export declare abstract class AutomationRunJob extends CrmJobBase {
+    protected abstract contactRouteClass: any;
+    protected scheduleExpr: string;
+    protected batchSize: number;
+    protected leaseSeconds: number;
+    protected pausedRetrySeconds: number;
+    private contactRoute?;
+    get schedule(): string | undefined;
+    run(): Promise<void>;
+    private findOne;
+}

package/dist/types/jobs/AutomationTriggerJob.d.ts

@@ -0,0 +1,23 @@
+import { AutomationEngine } from "../automation/Engine.js";
+import { CrmJobBase } from "./CrmJobBase.js";
+/**
+ * Hands each new `CrmEvent` to its workspace's automations, once (an event is claimed by stamping `dispatchedAt`, version-checked):
+ * - it **enrolls** the contact in every active automation whose trigger matches the event (and whose trigger filter, if any, the
+ * contact matches), as the automation's re-entry rule allows;
+ * - it **resumes** the contact's enrollments waiting for this event about this message (`AutomationEngine.resumeWaiting()`);
+ * - it **queues webhooks** for the workspace's enabled endpoints that take the event's type (`WebhookDeliveryJob` posts them).
+ *
+ * Dispatched events are deleted after `retention_days`.
+ */
+export declare abstract class AutomationTriggerJob extends CrmJobBase {
+    protected scheduleExpr: string;
+    protected batchSize: number;
+    protected retentionDays: number;
+    get schedule(): string | undefined;
+    /** The engine: enrolling and resuming waits change no contact, so it needs no contact route. */
+    protected engine(): AutomationEngine;
+    run(): Promise<void>;
+    private dispatch;
+    /** The workspace's active automations and their published versions. */
+    private liveAutomations;
+}

package/dist/types/jobs/CampaignJob.d.ts

@@ -0,0 +1,45 @@
+import { AbMetric, CampaignCounts } from "../models/types.js";
+import { CrmJobBase } from "./CrmJobBase.js";
+/**
+ * Moves campaigns along, on every replica but one campaign on one replica at a time (version-checked claims with a lease):
+ * 1. **Starts** scheduled campaigns once due (`preparing`).
+ * 2. **Prepares** them: reads the audience page by page (resumable from `audienceCursor`), creating one queued `OutboundSend` per
+ * contact - unique per campaign and contact - or a held one, for an A/B test's remainder. Then `sending`, or straight to `sent`
+ * when nobody was left to send to.
+ * 3. **Decides A/B tests** once `testHours` have passed since starting, by the best `metric` rate among the test messages sent, and
+ * releases the held messages as the winner.
+ * 4. **Drops** the unsent messages of cancelled campaigns.
+ * 5. **Finishes** campaigns with nothing left to send.
+ * 6. **Counts** the stats of campaigns going out or recently finished, at most every `stats_seconds`.
+ */
+export declare abstract class CampaignJob extends CrmJobBase {
+    protected scheduleExpr: string;
+    protected leaseSeconds: number;
+    /** How many audience pages one run prepares per campaign, so a run stays short. */
+    protected pagesPerRun: number;
+    /** How many subscriptions one audience page reads. */
+    protected audiencePageSize: number;
+    protected statsSeconds: number;
+    get schedule(): string | undefined;
+    run(): Promise<void>;
+    private campaigns;
+    /** `campaign` with `changes`, or `undefined` when someone changed it first (a member paused or cancelled it, another replica). */
+    private save;
+    private lease;
+    private startDue;
+    private prepare;
+    /** Reads one audience page into sends. Returns the campaign as saved, or `undefined` when it was changed behind the job's back. */
+    private preparePage;
+    /** Creates a send for each contact the campaign has none for yet. Returns how many were created. */
+    private createSends;
+    private decideTests;
+    private releaseHeld;
+    private dropCancelled;
+    /** Changes up to `MOVE_BATCH` of the campaign's sends in `from`. A send a replica holds a lease on is left for later. */
+    private moveSends;
+    private finishDone;
+    private countStats;
+    private stats;
+}
+/** The share of a variant's sent messages its metric happened to (0 with none sent). */
+export declare function metricRate(counts: CampaignCounts, metric: AbMetric): number;