@wirecat/cli-core 0.590.0 → 0.591.0

package/dist/crm/cli/index.js

@@ -0,0 +1,300 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
+import { InvalidArgumentError } from "commander";
+import * as v from "valibot";
+import { answerEntity } from "../../cli/answer-entity.js";
+import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
+import { honoursDryRun } from "../../cli/dry-run-guard.js";
+import { FETCH, LOCAL_READ, NO_EFFECTS } from "../../cli/effects.js";
+import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
+import { queryTerms, termField, withQuery } from "../../cli/list-query.js";
+import { lineOf } from "../../cli/steps.js";
+import { CRM_KINDS } from "../../domain/crm.js";
+import { DEAL_KINDS, DEAL_STATUSES } from "../../domain/deals.js";
+import { count, text } from "../../entities/fields.js";
+import { crmStatus, syncCrm } from "../sync.js";
+import { addCrmSearchAll } from "./search-all.js";
+const MOST = 500;
+const DEAL_FIELDS = [
+    termField("status", "enum", "status:open", { values: DEAL_STATUSES }),
+    termField("stage", "kw", 'stage:"Quote sent"', { relation: "a stage's name, in any letter case" }),
+    termField("pipeline", "kw", "pipeline:Sales", { relation: "pipeline:<id>, or a name only one pipeline has" }),
+    termField("organization", "ref", 'organization:"organization:3"'),
+];
+/** What `deals list` and `leads list` narrow by, the same in memo and every CRM CLI (WC-OUT-11). */
+export const DEALS_QUERY = { entity: "deal", backend: "native", fields: DEAL_FIELDS };
+export const LEADS_QUERY = { entity: "lead", backend: "native", fields: DEAL_FIELDS };
+export const PIPELINES_QUERY = {
+    entity: "pipeline",
+    backend: "native",
+    fields: [termField("kind", "enum", "kind:lead", { values: DEAL_KINDS })],
+};
+export const STAGES_QUERY = {
+    entity: "stage",
+    backend: "native",
+    fields: [
+        termField("kind", "enum", "kind:deal", { values: DEAL_KINDS }),
+        termField("pipeline", "kw", "pipeline:Sales", { relation: "pipeline:<id>, or a name only one pipeline has" }),
+    ],
+};
+/** A CRM's users typed these; a list item names its own, as `events list` does. */
+const DEAL_UNTRUSTED = ["title", "summary", "stage", "pipeline_name", "organization.name", "people.name"];
+const PIPELINE_UNTRUSTED = ["name", "stages.name"];
+const STAGE_UNTRUSTED = ["name", "pipeline_name"];
+const crmSync = v.strictObject({
+    provider: text,
+    account: text,
+    pipelines: count,
+    synced: v.array(v.strictObject({
+        kind: v.picklist(CRM_KINDS),
+        round: v.picklist(["full", "changes"]),
+        reset: v.boolean(),
+        state: v.picklist(["partial", "complete"]),
+        saved: count,
+        removed: count,
+        unlisted: count,
+        pass: v.optional(v.picklist(["complete", "partial", "held"])),
+        error: v.optional(text),
+    })),
+    issues: v.array(v.strictObject({
+        kind: v.picklist(CRM_KINDS),
+        reason: text,
+        message: text,
+        external_id: v.optional(text),
+    })),
+    complete: v.boolean(),
+    state: v.picklist(["partial", "complete"]),
+    stopped: v.optional(v.picklist(["requests", "deadline", "cancelled"])),
+    progress: v.strictObject({ requests: count, saved: count, steps: count }),
+    hint: v.optional(text),
+});
+const crmSyncProgress = v.strictObject({
+    kind: v.picklist(CRM_KINDS),
+    round: v.nullable(v.picklist(["full", "changes"])),
+    id_pass: v.nullable(text),
+    stored: count,
+    job: text,
+    profile: text,
+    done: count,
+    total: v.nullable(count),
+    remaining: v.nullable(count),
+    state: v.picklist(["partial", "complete"]),
+    updated_at: v.nullable(text),
+    cursor_age_ms: v.nullable(count),
+    line: text,
+});
+const integer = (most) => (value) => {
+    if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
+        throw new InvalidArgumentError(`expected 1 to ${most}`);
+    return Number(value);
+};
+/** The words below the program, as `page.next` and `sync`'s next step run it again. */
+const pathOf = (command) => command.parent?.parent ? [...pathOf(command.parent), command.name()] : [command.name()];
+const marked = (items, untrusted) => items.map((item) => ({ ...snakeKeys(item), untrusted }));
+const addCrmCommandsDefinition = (program, options) => {
+    const now = () => options.now?.() ?? Date.now();
+    const within = async (command, work) => {
+        const run = await options.open(command, { readOnly: metaOf(command).effects?.local !== "write" });
+        let body;
+        try {
+            body = await work(run);
+        }
+        finally {
+            await run.close?.();
+        }
+        renderAnswer(command, outputFor(command), body);
+    };
+    const example = (command, ...lines) => annotate(command, { examples: lines.map((line) => `${options.app.command} work ${line}`) });
+    example(answerEntity(annotate(program.command("sync"), { effects: FETCH, offline: false, cooperative: true, partial: true }), "crm_sync", crmSync).description("bring the CRM's copy in the local store up to date: pipelines, companies, contacts, deals and leads that " +
+        "changed since the last sync, or everything with --rescan; a run stops before its deadline or --max-pages " +
+        "and the next one goes on from there"), "sync", "sync --rescan", "sync --max-pages 20")
+        .option("--rescan", "list everything again, every id too, dropping a round in progress")
+        .option("--max-pages <pages>", "at most this many requests to the CRM in this run", integer(100_000))
+        .action(async (opts, command) => {
+        const { signal } = environmentOf(command);
+        await within(command, async (run) => {
+            const report = await syncCrm(run.source(), run.store, run.account, {
+                now: now(),
+                budget: runBudgetOf(command, opts.maxPages),
+                ...(signal ? { signal } : {}),
+                ...(opts.rescan ? { rescan: true } : {}),
+            });
+            const failed = report.synced.filter((one) => one.error !== undefined);
+            const timeout = command.optsWithGlobals().timeout;
+            // The same command again, never --rescan: that would drop the round this run leaves in progress.
+            const stuck = report.state === "partial" && report.progress.steps === 0 && failed.length === 0;
+            const next = failed.length || (report.state === "partial" && !stuck)
+                ? [
+                    {
+                        kind: "command",
+                        step: "crm.sync",
+                        command: "sync",
+                        args: Object.fromEntries(Object.entries({ max_pages: opts.maxPages, timeout }).filter(([, value]) => value !== undefined)),
+                        why: failed.length
+                            ? "a kind failed to sync; running sync again retries it"
+                            : "the sync stopped before its end to answer in time; running it again goes on from there",
+                        safe_to_auto_execute: true,
+                    },
+                ]
+                : undefined;
+            const progressAt = lineOf(command, "store status");
+            const hint = failed.length
+                ? `${failed.map((one) => `${one.kind}: ${one.error}`).join("; ")} — run sync again to retry`
+                : stuck
+                    ? `this run moved nothing on: raise --timeout or --max-pages, then run sync again; see progress: ${progressAt}`
+                    : report.state === "partial"
+                        ? `run sync again to continue; see progress: ${progressAt}`
+                        : undefined;
+            const { hint: _hint, ...rest } = report;
+            // What the healthy kinds brought is saved and answered; each failure and each item not kept is an issue.
+            const issues = [
+                ...failed.map((one) => ({
+                    code: "provider_error",
+                    reason: "sync.partial",
+                    source: `crm:${one.kind}`,
+                })),
+                ...report.issues.map((one) => ({
+                    code: "validation_error",
+                    reason: one.reason,
+                    source: one.externalId === undefined ? `crm:${one.kind}` : `crm:${one.kind}/${one.externalId}`,
+                })),
+            ];
+            const partial = report.state === "partial" || issues.length > 0;
+            return itemOf(snakeKeys({ ...rest, ...(hint === undefined ? {} : { hint }) }), {
+                ...(partial ? { meta: { complete: false, ...(issues.length ? { issues } : {}) } } : {}),
+                ...(next ? { next } : {}),
+            });
+        });
+    });
+    const store = annotate(program.command("store").description("the local copy of the CRM"), { effects: NO_EFFECTS });
+    example(answerEntity(annotate(store.command("status"), { effects: LOCAL_READ }), "crm_sync_progress", crmSyncProgress).description("how far each kind's sync is: rows saved, partial or complete, when it last moved, how many are stored"), "store status --json").action(async (_opts, command) => {
+        await within(command, async (run) => {
+            const status = await crmStatus(run.store, run.account, { profile: run.profile, now: now() });
+            return listOf(pathOf(command).join(" "), {
+                items: status.items,
+                limit: status.limit,
+                has_more: false,
+                page: 1,
+            });
+        });
+    });
+    const items = (kind) => {
+        const plural = `${kind}s`;
+        const query = kind === "deal" ? DEALS_QUERY : LEADS_QUERY;
+        const group = annotate(program.command(plural), { effects: NO_EFFECTS }).description(kind === "deal"
+            ? "the CRM's deals as last synced: stage, status, amount and the people on them"
+            : "the CRM's leads as last synced");
+        example(withQuery(annotate(group.command("list"), { effects: LOCAL_READ, output: { entity: kind } }).description(`${plural} copied from the CRM, newest first; run sync to bring them up to date`), query)
+            .option("--limit <n>", `${plural} per page, 1–${MOST}`, integer(MOST), 50)
+            .option("--page <n>", "which page, starting at 1", integer(1_000_000), 1), `${plural} list status:open --json`, `${plural} list stage:"Quote sent"`).action(async (words, opts, command) => {
+            const terms = queryTerms(words, query, `${plural} list`);
+            await within(command, async (run) => {
+                const filter = {
+                    kind,
+                    account: run.account,
+                    ...(terms.has("status") ? { status: terms.get("status") } : {}),
+                    ...(terms.has("stage") ? { stage: terms.get("stage") } : {}),
+                    ...(terms.has("pipeline") ? { pipeline: terms.get("pipeline") } : {}),
+                    ...(terms.has("organization") ? { organization: terms.get("organization") } : {}),
+                };
+                const found = await run.store.deals.list({
+                    ...filter,
+                    limit: Math.min(opts.limit + 1, MOST),
+                    offset: (opts.page - 1) * opts.limit,
+                });
+                return listOf(pathOf(command).join(" "), {
+                    items: marked(found.slice(0, opts.limit), DEAL_UNTRUSTED),
+                    limit: opts.limit,
+                    page: opts.page,
+                    has_more: found.length > opts.limit,
+                    ...(words.length ? { args: { query: words } } : {}),
+                });
+            });
+        });
+        example(annotate(group.command("show"), { effects: LOCAL_READ, output: { entity: kind } })
+            .description(`one ${kind} with its pipeline, stage, status, amount and the people on it`)
+            .argument("<ref>", `${kind}:<id>, as a list shows it`), `${plural} show ${kind}:12`).action(async (reference, _opts, command) => {
+            await within(command, async (run) => {
+                const found = await ownCopy(run, kind, reference);
+                return itemOf({ ...snakeKeys(found), untrusted: DEAL_UNTRUSTED });
+            });
+        });
+    };
+    /** A row of this profile's account: another account's copy, or the owner's own, is not found here. */
+    const ownCopy = async (run, kind, reference) => {
+        if (!reference.startsWith(`${kind}:`))
+            throw new CliError("validation_error", `${kind}s show takes a ${kind}:<id> reference, as a list shows it`, {
+                reason: "ref.malformed",
+            });
+        const found = await run.store.deals.get(reference);
+        if (found.account?.provider !== run.account.provider || found.account.account !== run.account.account)
+            throw new CliError("not_found", `${reference} is not a copy from this profile's CRM account`);
+        return found;
+    };
+    items("deal");
+    if (options.leads !== false)
+        items("lead");
+    const pipelines = annotate(program.command("pipelines"), { effects: NO_EFFECTS }).description("the CRM's pipelines and their stages, as last synced");
+    example(withQuery(annotate(pipelines.command("list"), { effects: LOCAL_READ, output: { entity: "pipeline" } }).description("pipelines copied from the CRM, with their stages in order and how many are open in each"), PIPELINES_QUERY), "pipelines list --json", "pipelines list kind:lead").action(async (words, _opts, command) => {
+        const terms = queryTerms(words, PIPELINES_QUERY, "pipelines list");
+        await within(command, async (run) => {
+            const found = await run.store.deals.pipelines({
+                account: run.account,
+                ...(terms.has("kind") ? { kind: terms.get("kind") } : {}),
+            });
+            return listOf(pathOf(command).join(" "), {
+                items: marked(found, PIPELINE_UNTRUSTED),
+                limit: Math.max(1, found.length),
+                page: 1,
+                has_more: false,
+                ...(words.length ? { args: { query: words } } : {}),
+            });
+        });
+    });
+    example(annotate(pipelines.command("show"), { effects: LOCAL_READ, output: { entity: "pipeline" } })
+        .description("one pipeline with its funnel: how many reached each stage, how many went on, and the win rate")
+        .argument("<pipeline>", "pipeline:<id>, or a name only one of the CRM's pipelines has"), "pipelines show pipeline:3").action(async (reference, _opts, command) => {
+        await within(command, async (run) => {
+            const report = await run.store.deals.pipeline(reference, { account: run.account });
+            return itemOf({ ...snakeKeys(report), untrusted: PIPELINE_UNTRUSTED });
+        });
+    });
+    const stages = annotate(program.command("stages"), { effects: NO_EFFECTS }).description("the stages of the CRM's pipelines, as last synced");
+    example(withQuery(annotate(stages.command("list"), { effects: LOCAL_READ, output: { entity: "stage" } }).description("every stage of the CRM's pipelines in order, with its outcome and how many are open in it"), STAGES_QUERY), "stages list --json", "stages list kind:lead").action(async (words, _opts, command) => {
+        const terms = queryTerms(words, STAGES_QUERY, "stages list");
+        await within(command, async (run) => {
+            const kind = terms.has("kind") ? terms.get("kind") : undefined;
+            const all = await run.store.deals.pipelines({ account: run.account, ...(kind ? { kind } : {}) });
+            const chosen = terms.has("pipeline")
+                ? [
+                    await run.store.deals.pipeline(terms.get("pipeline"), {
+                        account: run.account,
+                        ...(kind ? { kind } : {}),
+                    }),
+                ]
+                : all;
+            const found = chosen.flatMap((pipeline) => pipeline.stages.map(({ name, position, outcome, externalId, open }) => ({
+                name,
+                position,
+                outcome,
+                externalId,
+                open,
+                pipeline: pipeline.ref,
+                pipelineName: pipeline.name,
+                kind: pipeline.kind,
+            })));
+            return listOf(pathOf(command).join(" "), {
+                items: marked(found, STAGE_UNTRUSTED),
+                limit: Math.max(1, found.length),
+                page: 1,
+                has_more: false,
+                ...(words.length ? { args: { query: words } } : {}),
+            });
+        });
+    });
+    const search = program.commands.find((one) => one.name() === "search") ??
+        annotate(program.command("search"), { effects: NO_EFFECTS }).description("search what the local store holds");
+    addCrmSearchAll(search, { within, app: options.app, example });
+};
+// honoursDryRun: a host program other than `run` would otherwise let a write through under --dry-run.
+export const addCrmCommands = honoursDryRun(sharedCommand(addCrmCommandsDefinition));

package/dist/crm/cli/search-all.d.ts

@@ -0,0 +1,12 @@
+import { Command } from "commander";
+import type { AppIdentity } from "../../ports/app.js";
+import type { CrmWithin } from "./index.js";
+/**
+ * `search all` in a CRM CLI: the shared search over the store, its own deals and leads beside the messages, notes and
+ * events other WireCat tools stored. A locked profile reads only its own account's deals.
+ */
+export declare const addCrmSearchAll: (searches: Command, { within, app, example, }: {
+    within: CrmWithin;
+    app: AppIdentity;
+    example: (command: Command, ...lines: string[]) => Command;
+}) => void;

package/dist/crm/cli/search-all.js

@@ -0,0 +1,63 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import { outputFor } from "../../cli/context.js";
+import { LOCAL_READ } from "../../cli/effects.js";
+import { historySkipsOf } from "../../cli/messenger/history-gaps.js";
+import { allAnswer, offsetOf, SOURCE_SEARCHED } from "../../cli/messenger/search-answers.js";
+import { searchAllOptions } from "../../cli/messenger/search-command.js";
+import { SAVE_HELP } from "../../meetings/index.js";
+import { meaningLane } from "../../services/messages-meaning.js";
+import { searchAllWithMeetings } from "../../services/search-all-meetings.js";
+/** What a CRM CLI's `search all` reads: its deals and leads first, then what the other tools stored. */
+const SEARCHED = ["crm", ...SOURCE_SEARCHED];
+const DEFAULT_LIMIT = 20;
+/**
+ * `search all` in a CRM CLI: the shared search over the store, its own deals and leads beside the messages, notes and
+ * events other WireCat tools stored. A locked profile reads only its own account's deals.
+ */
+export const addCrmSearchAll = (searches, { within, app, example, }) => {
+    const all = annotate(new Command("all"), { effects: LOCAL_READ, partial: true, output: { entity: "hit" } })
+        .summary("search stored deals and leads, messages, notes and calendar events")
+        .description("search the CRM's deals and leads by the words of their title, and messages, notes and calendar events other " +
+        "WireCat tools stored — best match first. Use it when you do not know where something was written")
+        .argument("<query...>", 'words and "phrases"; deals and leads match the words of their title')
+        .addHelpText("after", SAVE_HELP);
+    searches.addCommand(searchAllOptions(all, SEARCHED));
+    example(all, "search all Example LLC", "search all website --only crm --json");
+    all.action(async (words, _opts, leaf) => {
+        const opts = leaf.opts();
+        await within(leaf, async (run) => {
+            if (run.locked && opts.source !== undefined)
+                throw new CliError("permission_error", "this process is locked to one profile; search all reads its own CRM account only, without --source", { reason: "profile.locked" });
+            const limit = opts.limit ?? DEFAULT_LIMIT;
+            const offset = offsetOf(opts.page, limit);
+            const env = run.env ?? process.env;
+            const found = await searchAllWithMeetings(run.store, run.account, {
+                text: words.join(" "),
+                limit,
+                ...(offset === undefined ? {} : { offset }),
+                ...(opts.exact ? { exact: true } : {}),
+                ...(opts.timezone === undefined ? {} : { timezone: opts.timezone }),
+                env,
+                only: opts.only ?? SEARCHED,
+                ...(opts.source === undefined ? {} : { source: opts.source }),
+                ...(opts.maxMeetings === undefined ? {} : { maxMeetings: opts.maxMeetings }),
+                ...(run.locked ? { scope: { crm: [run.account] } } : {}),
+            }, { app }, undefined, meaningLane({ env, messenger: { app }, store: async () => run.store }));
+            const note = (text) => outputFor(leaf).renderer.note(text);
+            for (const { resource, source, reason } of found.skipped)
+                note(`${resource ?? source} not searched: ${reason}`);
+            if (!found.items.length)
+                note("nothing found in what the local store holds");
+            const skips = await historySkipsOf(run.store, found.accounts).catch(() => []);
+            const again = {
+                query: words.join(" "),
+                ...(opts.only === undefined ? {} : { only: opts.only.join(",") }),
+                ...(opts.source === undefined ? {} : { source: opts.source }),
+                ...(opts.exact ? { exact: true } : {}),
+            };
+            return allAnswer("search all", found, { limit, page: opts.page ?? 1, again }, opts.exact === true, skips);
+        });
+    });
+};

package/dist/crm/index.d.ts

@@ -0,0 +1,2 @@
+export type { CrmChanges, CrmIdPage, CrmPage, CrmSource, CrmSourceTraits } from "./source.js";
+export { type CrmCursor, type CrmSyncIssue, type CrmSyncOptions, type CrmSyncReport, type CrmSyncResult, crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";

package/dist/crm/index.js

@@ -0,0 +1 @@
+export { crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";

package/dist/crm/source.d.ts

@@ -0,0 +1,43 @@
+import type { CrmKind, CrmPipeline, CrmRecords } from "../domain/crm.js";
+import type { DealKind } from "../domain/deals.js";
+export interface CrmSourceTraits {
+    /** What this CRM has: one without leads leaves `lead` out. Contacts and companies come before the items on them. */
+    kinds: readonly CrmKind[];
+    /**
+     * `changes()` names what was deleted in `removed`, so the engine never lists every id to find them. A CRM that
+     * only lists what exists leaves this false and gives `ids()`.
+     */
+    removedInChanges: boolean;
+}
+export interface CrmPage<T> {
+    items: T[];
+    /** Ids the CRM says it deleted since the cursor; never one that only left a filter. */
+    removed?: string[];
+    /** More pages in this round. */
+    nextPage?: string;
+    /** On the last page: the cursor the next run reads changes after; `null` when the CRM keeps none. */
+    cursor?: string | null;
+}
+/** `reset`: the cursor is dead, and the CRM must be listed in full again. */
+export type CrmChanges<T> = CrmPage<T> | {
+    reset: true;
+};
+export interface CrmIdPage {
+    ids: string[];
+    nextPage?: string;
+}
+/** One CRM account, as an adapter reads it. The engine never sees a provider word. */
+export interface CrmSource {
+    /** The registry name: `bitrix24`, `pipedrive`, `hubspot`, `amocrm`. */
+    readonly provider: string;
+    readonly traits: CrmSourceTraits;
+    /** One kind's pipelines with their stages; a CRM whose leads have no pipelines answers one of its own making. */
+    pipelines(kind: DealKind): Promise<CrmPipeline[]>;
+    /**
+     * What changed since `cursor`, a page at a time; `cursor: null` lists everything. A CRM without a change feed
+     * reads by its own modified time, with an overlap, and gives that time back as the cursor.
+     */
+    changes<K extends CrmKind>(kind: K, cursor: string | null, page?: string): Promise<CrmChanges<CrmRecords[K]>>;
+    /** Every id the CRM holds of the kind, a page at a time: how deletions are found when `removedInChanges` is false. */
+    ids?(kind: CrmKind, page?: string): Promise<CrmIdPage>;
+}

package/dist/crm/source.js

@@ -0,0 +1 @@
+export {};

package/dist/crm/sync.d.ts

@@ -0,0 +1,121 @@
+import { type BudgetStop, type RunBudget } from "../background/budget.js";
+import { type CrmKind } from "../domain/crm.js";
+import type { CrmSkipped } from "../store/sqlite/crm.js";
+import type { MessageStore } from "../store/store.js";
+import type { AccountKey } from "../store/types.js";
+import type { CrmSource } from "./source.js";
+/** A round of changes that stopped before its last page: the next run goes on from its page with the same cursor. */
+interface PendingRound {
+    from: string | null;
+    page: string | null;
+    reset: boolean;
+}
+/** A list of every id that stopped before its end: the ids it has seen, and its next page. */
+interface PendingPass {
+    page: string | null;
+    startedAt: number;
+    seen: string[];
+}
+/** What the engine keeps per kind in `store.sync` under `crm:<kind>`. */
+export interface CrmCursor {
+    v: 1;
+    /** The CRM's cursor after the last finished round; `null` before the first. */
+    token: string | null;
+    round: PendingRound | null;
+    /** Rows saved by the round in progress, or by the last one. */
+    done: number;
+    updatedAt: number | null;
+    pass: PendingPass | null;
+    /** When the last complete id pass started; 0 before the first. */
+    passAt: number;
+}
+export declare const parseCrmCursor: (value: string | null | undefined) => CrmCursor | null;
+export declare const cursorName: (kind: CrmKind) => string;
+export interface CrmSyncOptions {
+    now?: number;
+    /** List everything again and every id, dropping a round in progress: `sync --rescan`. */
+    rescan?: boolean;
+    /** Asked before every request to the CRM; without one the run goes until every kind is done. */
+    budget?: RunBudget;
+    /** Checked after every request: a cancelled run stops and keeps what it saved. */
+    signal?: AbortSignal;
+    /** How long a complete id pass holds before the next one; a day when absent. */
+    passEvery?: number;
+}
+/** Something a run could not do that the owner should know: an item not kept, or a deletion held back. */
+export interface CrmSyncIssue {
+    kind: CrmKind;
+    reason: CrmSkipped["reason"] | "crm.unlisted-held";
+    message: string;
+    externalId?: string;
+}
+export interface CrmSyncResult {
+    kind: CrmKind;
+    /** `full`: everything was listed; `changes`: only what changed since the cursor. */
+    round: "full" | "changes";
+    /** The cursor was dead, so the round became a full one. */
+    reset: boolean;
+    state: "partial" | "complete";
+    saved: number;
+    /** Rows the CRM said it deleted, now marked deleted. */
+    removed: number;
+    /** Rows a complete id pass did not list, now marked deleted. */
+    unlisted: number;
+    /** `complete`: a full list of ids arrived; `partial`: it stopped and goes on next run; `held`: it would mark too many. */
+    pass?: "complete" | "partial" | "held";
+    /** Set when the kind failed; its cursor stays at its last saved page. */
+    error?: string;
+}
+export interface CrmSyncReport {
+    provider: string;
+    account: string;
+    /** Pipelines read this run, both kinds. */
+    pipelines: number;
+    synced: CrmSyncResult[];
+    issues: CrmSyncIssue[];
+    /** Every kind finished its round and none failed. */
+    complete: boolean;
+    state: "partial" | "complete";
+    stopped?: BudgetStop;
+    progress: {
+        /** Requests made to the CRM. */
+        requests: number;
+        saved: number;
+        /** Pages saved: 0 means this run moved nothing on. */
+        steps: number;
+    };
+    hint?: string;
+}
+/**
+ * Brings one CRM account's copy up to date: both kinds' pipelines, then contacts, companies, deals and leads, each
+ * from its cursor or listed in full, a page at a time, each page saved with the round's place in the cursor, so a
+ * run the budget stops, or one that fails, goes on from there. Deletions come from `changes()`, or from a list of
+ * every id that marks only after its last page arrived, and never more than half of a kind without `--rescan`.
+ */
+export declare const syncCrm: (source: CrmSource, store: MessageStore, account: AccountKey, options?: CrmSyncOptions) => Promise<CrmSyncReport>;
+/** Each kind's sync in the WC-LIFE-14 shape: `cursor_age_ms` growing on a `partial` one means nothing moves it. */
+export declare const crmStatus: (store: MessageStore, account: AccountKey, { profile, now, kinds }: {
+    profile: string;
+    now: number;
+    kinds?: readonly CrmKind[];
+}) => Promise<{
+    items: {
+        job: string;
+        profile: string;
+        done: number;
+        total: number | null;
+        remaining: number | null;
+        state: "partial" | "complete";
+        updated_at: string | null;
+        cursor_age_ms: number | null;
+        kind: "deal" | "lead" | "organization" | "person";
+        round: string | null;
+        id_pass: string | null;
+        stored: number;
+        line: string;
+    }[];
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}>;
+export {};