conduyt 1.61.0 → 1.62.0

package/README.md

@@ -37,10 +37,20 @@ conduyt deals list --pipeline <id>      # list deals
 conduyt deals list --health-summary --pipeline <id>   # Pipeline health strip for the filtered set (totalOpenDeals, atRiskValue, checks[]); add --health-check stale --health-limit 20 for one check's deals, --health-cursor <nextCursor> to page, --health-rows-only for just the page
 conduyt deals health --pipeline <id> --check needs_action   # GET /deals/inspection: the six checks over open deals; --check adds its deals, --cursor/--offset pages
 conduyt deals card-fields set value,contact,custom:next_contact_at   # the kanban card fields (1-8, built-ins or custom:<fieldKey>); `card-fields get` reads them
-conduyt pipelines stage-rules set <pipelineId> <stageId> --required-fields contactId,custom:loan_amount --required-documents 2   # what a deal needs to enter the stage; other stages untouched; `stage-rules get [pipelineId] [stageId]` reads
+conduyt pipelines stage-rules set <pipelineId> <stageId> --required-fields contactId,custom:loan_amount --required-documents 2 [--lost-reason-allow-other true]   # what a deal needs to enter the stage; other stages untouched; `stage-rules get [pipelineId] [stageId]` reads
 conduyt deals bulk-update --file updates.json   # update up to 100 deals at once ([{id, stageId, value, ...}]); per-item results, exit 1 if any failed
-conduyt pipelines                       # list pipelines and stages
-conduyt pipelines update <id> --automation-only true   # only automations, API keys and owners / admins move or edit its cards (owner / admin key)
+conduyt pipelines                       # list pipelines and stages (each carries color, automationOnly, sortOrder)
+conduyt pipelines list --archived       # the archived pipelines (owner / admin key): name, archivedName, openDeals, stageCount
+conduyt pipelines archive <id> --move-open-deals-to <pipelineId|none> [--expected-settings-revision N]   # archive + move the open deals in one transaction; refusals print their code (stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived) and exit 1
+conduyt pipelines settings-revision   # the account settingsRevision to pass as --expected-settings-revision to archive / delete-stage (409 stale_settings_revision when settings changed since)
+conduyt pipelines restore <id>          # bring an archived pipeline back (last in the menu, never the default; 409 name_taken)
+conduyt pipelines reorder --order id1,id2 --expected-revision id1,id2   # board-menu order in one transaction (409 order_changed prints the current revision); `reorder-stages <pipelineId>` does the same for a pipeline's columns
+conduyt pipelines delete-stage <pipelineId> <stageId> [--move-to <stageId>] [--expected-settings-revision N]   # move the live deals to another stage and delete this one; a stale revision is 409 stale_settings_revision
+conduyt pipelines rot-days set <pipelineId> 21   # days without activity (1-90) before a deal reads "Stale in stage"; `rot-days get [pipelineId]` reads
+conduyt status-metadata list --stage-id <id>   # the status codes + buckets attached to stages; `get | create | update | delete | import` (update / delete take --expected-updated-at; 409 metadata_changed)
+conduyt status-metadata import --file rows.json --mode replace   # set-based import (max 1000; an item key outside stageId, code, bucket, lifecycleStage, dripEligible, dripTrackName, isTerminal, notes is refused before any request); per-item errors print and exit 1; `--mode replace` with no items is refused unless `--confirm-empty-replace` (it deletes every row). Timeouts: archive 75 s, import and the Mailchimp write / action commands 60 s; on a timeout the server may have applied it, so read the state first
+conduyt integrations mailchimp settings  # the Mailchimp audience sync (API key scope integrations); `set | audiences | push | retry-unsubscribes | reconcile-statuses [--restart] | confirm-reconciliation`. Connecting is browser-only (OAuth): do it in the app
+conduyt pipelines update <id> --automation-only true   # only automations, API keys and owners / admins move or edit its cards (owner / admin key); also --color <palette hex> and --sort-order
 conduyt search "acme corp"              # search across the CRM
 conduyt insights summary                # run an AI insight query
 conduyt insights saved_report --report "Lead Activity" --period last_7_days   # run any saved report as a tool

package/dist/board-settings.js

@@ -11,7 +11,7 @@ export const MAX_STAGE_REQUIRED_FIELDS = 25;
 export const MAX_STAGE_REQUIRED_DOCUMENTS = 20;
 export const MAX_LOST_REASON_OPTIONS = 50;
 const CUSTOM_FIELD_RE = /^custom:[a-zA-Z_][a-zA-Z0-9_]*$/;
-export const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions"];
+export const RULE_KEYS = ["requiredFields", "requiredDocuments", "lostReasonLabel", "lostReasonOptions", "lostReasonAllowOther"];
 const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
 /** "a,b,custom:x" → ["a","b","custom:x"]; blank items are dropped, an all-blank value is an empty list */
 export function splitList(raw) {
@@ -64,6 +64,11 @@ export function validateRuleChange(raw) {
                 throw new Error("lostReasonLabel must be 1-60 characters.");
             out[k] = t;
         }
+        else if (k === "lostReasonAllowOther") {
+            if (typeof v !== "boolean")
+                throw new Error("lostReasonAllowOther must be true or false.");
+            out[k] = v;
+        }
         else {
             if (!Array.isArray(v) || v.some((o) => typeof o !== "string"))
                 throw new Error("lostReasonOptions must be a list of strings.");

package/dist/client.js

@@ -1,4 +1,12 @@
 import { requireAuth } from "./config.js";
+/** A deadline hit (only when the call set one) is "the server may have applied it", for every method: read the state first. */
+function ambiguousTimeout(err, method, path, timeoutMs, what) {
+    const name = err?.name;
+    if (timeoutMs !== undefined && (name === "TimeoutError" || name === "AbortError")) {
+        return new Error(`Conduyt API timeout: ${what} within ${timeoutMs / 1000}s for ${method} ${path}. The server may have applied it: read the current state before repeating it.`);
+    }
+    return err;
+}
 export class ConduytClient {
     baseUrl;
     apiKey;
@@ -7,17 +15,34 @@ export class ConduytClient {
         this.baseUrl = cfg.apiUrl.replace(/\/+$/, "");
         this.apiKey = cfg.apiKey;
     }
-    async request(method, path, body) {
+    /** timeoutMs: a per-call deadline for the routes whose server budget is long (archive 75 s, Mailchimp admin and
+     *  status-metadata import 60 s). Without it the request has no client-side deadline. A call that hits it may still have
+     *  been applied by the server, and the error says so. */
+    async request(method, path, body, opts) {
         const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
-        const res = await fetch(url, {
-            method,
-            headers: {
-                Authorization: `Bearer ${this.apiKey}`,
-                "Content-Type": "application/json",
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-        });
-        const text = await res.text();
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                ...(opts?.timeoutMs !== undefined ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
+            });
+        }
+        catch (err) {
+            throw ambiguousTimeout(err, method, path, opts?.timeoutMs, "no answer");
+        }
+        // the headers can arrive and the body then stall until the deadline: the same ambiguity, not a raw TimeoutError
+        let text;
+        try {
+            text = await res.text();
+        }
+        catch (err) {
+            throw ambiguousTimeout(err, method, path, opts?.timeoutMs, "the response body did not finish");
+        }
         const json = text ? safeParse(text) : null;
         if (!res.ok) {
             // Preserve structured non-2xx bodies: several endpoints return the data
@@ -44,14 +69,14 @@ export class ConduytClient {
     get(path) {
         return this.request("GET", path);
     }
-    post(path, body) {
-        return this.request("POST", path, body);
+    post(path, body, opts) {
+        return this.request("POST", path, body, opts);
     }
     patch(path, body) {
         return this.request("PATCH", path, body);
     }
-    put(path, body) {
-        return this.request("PUT", path, body);
+    put(path, body, opts) {
+        return this.request("PUT", path, body, opts);
     }
     del(path) {
         return this.request("DELETE", path);

package/dist/index.js

@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
 import { Command } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
 import { splitList, stageRulePatch, validateCardFields, validateRuleChange } from "./board-settings.js";
+import { ARCHIVE_PIPELINE_TIMEOUT_MS, MAILCHIMP_ADMIN_TIMEOUT_MS, STATUS_METADATA_IMPORT_TIMEOUT_MS, PIPELINE_COLORS, boolFlag, intFlag, isoDate, lifecycleStage as lifecycleStageArg, MAX_PIPELINE_ROT_DAYS, MIN_PIPELINE_ROT_DAYS, pipelineColor, settingsRevision, slug as slugArg, uuid as uuidOf, uuidList, validateImportItems, validateStatusMetadataBody } from "./pipeline-settings.js";
 import { saveConfig, resolveConfig, configPath } from "./config.js";
 import { print, fail, unwrap } from "./output.js";
 // Exit cleanly when a downstream pipe closes early (e.g. `conduyt deals list |
@@ -758,18 +759,22 @@ const pipelines = program
     .action(run(async (client) => client.get("/api/v1/pipelines")));
 pipelines
     .command("list")
-    .description("List pipelines and their stages")
-    .action(run(async (client) => client.get("/api/v1/pipelines")));
+    .description("List pipelines and their stages (each pipeline carries color, automationOnly, sortOrder). --archived lists the ARCHIVED pipelines instead (owner / admin key): id, name (the pre-archive name), archivedName, color, archivedAt, openDeals, stageCount")
+    .option("--archived", "list the archived pipelines (GET /pipelines?archived=true) instead of the active ones")
+    .action(run(async (client, opts) => client.get(opts.archived ? "/api/v1/pipelines?archived=true" : "/api/v1/pipelines")));
 pipelines
     .command("create")
     .description("Create a pipeline with stages")
     .option("--name <name>", "pipeline name")
     .option("--stages <json>", "JSON array of stages, e.g. '[{\"name\":\"Lead\"},{\"name\":\"Won\",\"isWon\":true}]'")
+    .option("--color <hex>", `pipeline colour, one of the palette: ${PIPELINE_COLORS.join(" ")}`)
     .option("--json <json>", "full JSON body, merged over the flags")
     .action(run(async (client, opts) => {
     const body = {};
     if (opts.name !== undefined)
         body.name = opts.name;
+    if (opts.color !== undefined)
+        body.color = pipelineColor(opts.color);
     if (opts.stages !== undefined) {
         if (opts.stages.trim() === "")
             throw new Error("--stages must be valid JSON (got an empty string).");
@@ -803,6 +808,7 @@ pipelines
     .option("--is-default <bool>", "true|false: the account's default pipeline")
     .option("--automation-only <bool>", "true|false: only automations, API keys and owners / admins move or edit its cards")
     .option("--sort-order <n>", "position among the pipelines (integer)")
+    .option("--color <hex>", `pipeline colour, one of the palette: ${PIPELINE_COLORS.join(" ")}`)
     .option("--json <json>", "full JSON body, merged over the flags")
     .action(run(async (client, id, opts) => {
     assertUuid(id, "pipeline id");
@@ -841,6 +847,8 @@ pipelines
             throw new Error("--sort-order must be an integer.");
         body.sortOrder = n;
     }
+    if (opts.color !== undefined && unlessJson("color"))
+        body.color = pipelineColor(opts.color);
     Object.assign(body, fromJson);
     if (Object.keys(body).length === 0)
         throw new Error("Nothing to update. Pass at least one field flag or --json.");
@@ -853,7 +861,7 @@ const stageRules = pipelines
     .description("Per-stage rules (settings.pipelineStageRules): the fields and documents a deal needs before it may enter a stage");
 stageRules
     .command("get [pipelineId] [stageId]")
-    .description("Read the stage rules as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions } } }, for everything, one pipeline, or one stage")
+    .description("Read the stage rules as { pipelineId: { stageId: { requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther } } }, for everything, one pipeline, or one stage")
     .action(run(async (client, pipelineId, stageId) => {
     if (pipelineId !== undefined)
         assertUuid(pipelineId, "pipeline id");
@@ -876,7 +884,8 @@ stageRules
     .option("--required-documents <n>", "integer 0-20")
     .option("--lost-reason-label <text>", "label of the stage's lost-reason prompt (1-60 chars)")
     .option("--lost-reason-options <list>", "comma-separated dropdown options of the lost-reason prompt (max 50; empty clears)")
-    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions}), merged over the flags")
+    .option("--lost-reason-allow-other <bool>", "true|false: the rep may also pick \"Other\" and type the reason (stored as the reason text; takes effect while the stage has lost-reason options)")
+    .option("--json <json>", "the rule fields as a JSON object ({requiredFields, requiredDocuments, lostReasonLabel, lostReasonOptions, lostReasonAllowOther}), merged over the flags")
     .action(run(async (client, pipelineId, stageId, opts) => {
     assertUuid(pipelineId, "pipeline id");
     assertUuid(stageId, "stage id");
@@ -891,11 +900,13 @@ stageRules
         raw.lostReasonLabel = opts.lostReasonLabel;
     if (opts.lostReasonOptions !== undefined)
         raw.lostReasonOptions = splitList(opts.lostReasonOptions);
+    if (opts.lostReasonAllowOther !== undefined)
+        raw.lostReasonAllowOther = boolFlag(opts.lostReasonAllowOther, "--lost-reason-allow-other");
     if (opts.json !== undefined)
         Object.assign(raw, jsonArg(opts.json, "--json"));
     const change = validateRuleChange(raw);
     if (Object.keys(change).length === 0)
-        throw new Error("Nothing to set. Pass --required-fields, --required-documents, --lost-reason-label, --lost-reason-options or --json.");
+        throw new Error("Nothing to set. Pass --required-fields, --required-documents, --lost-reason-label, --lost-reason-options, --lost-reason-allow-other or --json.");
     return patchGeneralSettingsMerged(client, (settings) => stageRulePatch(settings, pipelineId, stageId, change));
 }));
 // (system stages 2026-09-24) tri-surface parity: the stage flags the API takes on PATCH /pipelines/:id/stages/:stageId,
@@ -951,6 +962,245 @@ pipelines
         throw new Error("Nothing to update. Pass at least one field flag or --json.");
     return client.patch(`/api/v1/pipelines/${encodeURIComponent(pipelineId)}/stages/${encodeURIComponent(stageId)}`, body);
 }));
+// (pipeline settings 10-08) archive / restore / reorder, stage delete with a move, the stale-in-stage days.
+pipelines
+    .command("archive <id>")
+    .description("Archive a pipeline (owner / admin key): renamed with the archived prefix, never deleted; its closed deals stay as history and `pipelines restore` brings it back. Every OPEN deal moves in the same transaction to --move-open-deals-to's first stage through the normal stage-entry rules; any refusal aborts all of it. Pass --move-open-deals-to none only when there are no open deals. Waits up to 75 s; if it times out the archive may have committed, so run `pipelines list` / `pipelines list --archived` before retrying. The default pipeline cannot be archived. Refusal codes are printed with the error and the command exits 1: stale_settings_revision, target_not_open, dpp_post_close, archive_too_large, target_archived, intake_target, pipeline_archived, open_deals, default_pipeline, stage_requirements, archive_raced, pipeline_automation_only. An already-archived pipeline answers { archived: true, alreadyArchived: true }")
+    .requiredOption("--move-open-deals-to <pipelineId|none>", "the active pipeline the open deals move to (its first stage must be open), or none when the pipeline has no open deals")
+    .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
+    .action(run(async (client, id, opts) => {
+    const pid = uuidOf(id, "pipeline id");
+    const target = opts.moveOpenDealsTo.trim().toLowerCase();
+    const moveOpenDealsTo = target === "none" ? null : uuidOf(opts.moveOpenDealsTo, "--move-open-deals-to");
+    const body = { moveOpenDealsTo };
+    if (opts.expectedSettingsRevision !== undefined)
+        body.expectedSettingsRevision = settingsRevision(opts.expectedSettingsRevision);
+    return client.post(`/api/v1/pipelines/${pid}/archive`, body, { timeoutMs: ARCHIVE_PIPELINE_TIMEOUT_MS });
+}));
+pipelines
+    .command("restore <id>")
+    .description("Restore an ARCHIVED pipeline (owner / admin key): it loses the archived prefix, goes last in the board menu and is never the default; its stages and closed deals come back with it. 404 when it is not an archived pipeline of this account; 409 name_taken when an active pipeline has its name (rename that one first); 403 PLAN_LIMIT_REACHED when the plan's pipeline limit is full")
+    .action(run(async (client, id) => client.post(`/api/v1/pipelines/${uuidOf(id, "pipeline id")}/restore`, {})));
+pipelines
+    .command("reorder")
+    .description("Set the board-menu order of the active pipelines in one transaction (owner / admin key). --order must list EVERY active pipeline exactly once; --expected-revision is the order you last read (the pipeline ids by position, comma-joined). 409 order_changed (with the current revision) when the order moved since; nothing is written. Prints { order, revision }")
+    .requiredOption("--order <ids>", "comma-separated pipeline ids in the new order")
+    .requiredOption("--expected-revision <revision>", "the current order: the pipeline ids by position, comma-joined")
+    .action(run(async (client, opts) => {
+    const order = uuidList(opts.order, "--order");
+    if (opts.expectedRevision.trim() === "")
+        throw new Error("--expected-revision must be the current order (the pipeline ids by position, comma-joined).");
+    return client.post("/api/v1/pipelines/reorder", { order, expectedRevision: opts.expectedRevision.trim().toLowerCase() });
+}));
+pipelines
+    .command("reorder-stages <pipelineId>")
+    .description("Set a pipeline's column order in one transaction (owner / admin key). --order must list EVERY stage of the pipeline exactly once and may not put a system holding stage first that was not first; --expected-revision is the stage ids by position, comma-joined. 409 order_changed (with the current revision) when it moved since, 409 pipeline_archived when the pipeline was archived meanwhile. Prints { order, revision }")
+    .requiredOption("--order <ids>", "comma-separated stage ids in the new order")
+    .requiredOption("--expected-revision <revision>", "the current order: the stage ids by position, comma-joined")
+    .action(run(async (client, pipelineId, opts) => {
+    const pid = uuidOf(pipelineId, "pipeline id");
+    const order = uuidList(opts.order, "--order");
+    if (opts.expectedRevision.trim() === "")
+        throw new Error("--expected-revision must be the current order (the stage ids by position, comma-joined).");
+    return client.post(`/api/v1/pipelines/${pid}/stages/reorder`, { order, expectedRevision: opts.expectedRevision.trim().toLowerCase() });
+}));
+pipelines
+    .command("delete-stage <pipelineId> <stageId>")
+    .description("Delete a stage (owner / admin key). Without --move-to the stage must have no deals; with it the live deals move to another stage of the SAME pipeline (same won / lost setting, not a system stage) and the stage is deleted in one transaction. A stage a soft-deleted deal still points at is refused. With --expected-settings-revision the answer is { id, deleted: true, settingsRevision }. Refusals exit 1 with the code printed: stale_settings_revision, pipeline_archived, intake_target (other 409s name the cause)")
+    .option("--move-to <stageId>", "another stage of the same pipeline the live deals move to")
+    .option("--expected-settings-revision <n>", "the settingsRevision from `pipelines settings-revision`; refused 409 stale_settings_revision when settings changed since")
+    .action(run(async (client, pipelineId, stageId, opts) => {
+    const qs = new URLSearchParams();
+    if (opts.moveTo !== undefined)
+        qs.set("move_to", uuidOf(opts.moveTo, "--move-to"));
+    if (opts.expectedSettingsRevision !== undefined)
+        qs.set("expected_settings_revision", settingsRevision(opts.expectedSettingsRevision));
+    const q = qs.toString();
+    const res = await client.del(`/api/v1/pipelines/${uuidOf(pipelineId, "pipeline id")}/stages/${uuidOf(stageId, "stage id")}${q ? `?${q}` : ""}`);
+    return res ?? { data: { deleted: true, id: stageId } };
+}));
+pipelines
+    .command("settings-revision")
+    .description("The account settingsRevision (plus the stored stage rules and rot days): pass it as --expected-settings-revision to `pipelines archive` / `pipelines delete-stage` so they are refused (409 stale_settings_revision) when settings changed after you read it. Read it right before the mutation")
+    .action(run(async (client) => {
+    const res = (await client.get("/api/v1/settings"));
+    const d = res?.data ?? {};
+    return { data: { settingsRevision: typeof d.settingsRevision === "string" ? d.settingsRevision : null, pipelineStageRules: d.pipelineStageRules ?? null, pipelineRotDays: d.pipelineRotDays ?? null } };
+}));
+// settings.pipelineRotDays: days without activity before a deal reads "Stale in stage" (per pipeline, 1-90)
+const rotDays = pipelines
+    .command("rot-days")
+    .description("Stale-in-stage threshold per pipeline (settings.pipelineRotDays): days without activity (1-90) before a deal reads \"Stale in stage\"");
+rotDays
+    .command("get [pipelineId]")
+    .description("Read the thresholds as { pipelineId: days }, for every pipeline that has one or just the one given")
+    .action(run(async (client, pipelineId) => {
+    const pid = pipelineId === undefined ? undefined : uuidOf(pipelineId, "pipeline id");
+    const res = (await client.get("/api/v1/settings"));
+    const all = res?.data?.pipelineRotDays && typeof res.data.pipelineRotDays === "object" ? res.data.pipelineRotDays : {};
+    return { data: { pipelineRotDays: pid === undefined ? all : all[pid] !== undefined ? { [pid]: all[pid] } : {} } };
+}));
+rotDays
+    .command("set <pipelineId> <days>")
+    .description(`Set one pipeline's threshold (admin key, settings:edit): an integer ${MIN_PIPELINE_ROT_DAYS}-${MAX_PIPELINE_ROT_DAYS}. Only that pipeline changes. The pipeline must be an ACTIVE pipeline of the account (422 for an unknown or archived one). Saved with the settings revision; a 409 is re-read and retried once`)
+    .action(run(async (client, pipelineId, days) => {
+    const pid = uuidOf(pipelineId, "pipeline id");
+    const n = intFlag(days, "days", MIN_PIPELINE_ROT_DAYS, MAX_PIPELINE_ROT_DAYS);
+    return patchGeneralSettingsMerged(client, () => ({ pipelineRotDays: { [pid]: n } }));
+}));
+// ---- status metadata (app 10-08): the status taxonomy rows attached to a pipeline stage ----
+const statusMetadata = program
+    .command("status-metadata")
+    .description("Status metadata: the status codes and buckets attached to pipeline stages (one row per stage and code). update / delete take --expected-updated-at (the row's updatedAt as read): 409 metadata_changed (with the current row) when it changed or moved since, 404 status_metadata_not_found");
+statusMetadata
+    .command("list")
+    .description("List the rows (settings:view); updatedAt is the version for --expected-updated-at")
+    .option("--stage-id <id>", "only this stage's rows")
+    .option("--bucket <bucket>", "only this bucket")
+    .option("--code <code>", "only this code")
+    .action(run(async (client, opts) => client.get(`/api/v1/status-metadata${buildQuery({ stageId: opts.stageId === undefined ? undefined : uuidOf(opts.stageId, "--stage-id"), bucket: opts.bucket, code: opts.code })}`)));
+statusMetadata
+    .command("get <id>")
+    .description("One row with its stage and drip track")
+    .action(run(async (client, id) => client.get(`/api/v1/status-metadata/${uuidOf(id, "id")}`)));
+/** the row fields shared by create and update; "null" clears a nullable one */
+function statusMetadataFields(opts) {
+    const body = {};
+    if (opts.stageId !== undefined)
+        body.stageId = uuidOf(opts.stageId, "--stage-id");
+    if (opts.code !== undefined)
+        body.code = slugArg(opts.code, "--code");
+    if (opts.bucket !== undefined)
+        body.bucket = slugArg(opts.bucket, "--bucket");
+    if (opts.lifecycleStage !== undefined)
+        body.lifecycleStage = opts.lifecycleStage === "null" ? null : lifecycleStageArg(opts.lifecycleStage);
+    if (opts.dripEligible !== undefined)
+        body.dripEligible = boolFlag(opts.dripEligible, "--drip-eligible");
+    if (opts.dripTrackId !== undefined)
+        body.dripTrackId = opts.dripTrackId === "null" ? null : uuidOf(opts.dripTrackId, "--drip-track-id");
+    if (opts.isTerminal !== undefined)
+        body.isTerminal = boolFlag(opts.isTerminal, "--is-terminal");
+    if (opts.notes !== undefined) {
+        if (opts.notes !== "null" && opts.notes.length > 5000)
+            throw new Error("--notes must be at most 5000 characters.");
+        body.notes = opts.notes === "null" ? null : opts.notes;
+    }
+    return body;
+}
+statusMetadata
+    .command("create")
+    .description("Create a row (settings:edit, active billing). --code and --bucket are lowercase slugs (letters, numbers, underscores, max 80); one row per stage and code (a duplicate is a 409)")
+    .requiredOption("--stage-id <id>", "pipeline stage the row attaches to")
+    .requiredOption("--code <slug>", "status code, e.g. appt_set")
+    .requiredOption("--bucket <slug>", "bucket, e.g. working")
+    .option("--lifecycle-stage <stage>", `one of ${["pre_sale", "sale", "underwriting", "active", "resolution", "terminal"].join(", ")}, or null`)
+    .option("--drip-eligible <bool>", "true|false")
+    .option("--drip-track-id <id>", "drip track id, or null")
+    .option("--is-terminal <bool>", "true|false")
+    .option("--notes <text>", "free text (max 5000), or null")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = statusMetadataFields(opts);
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    // flags + --json together, against the exact field list and types: the API ignores a misspelled key and applies the rest
+    return client.post("/api/v1/status-metadata", validateStatusMetadataBody(body, "create"));
+}));
+statusMetadata
+    .command("update <id>")
+    .description("Update a row (settings:edit, active billing): only the fields you pass change. --expected-updated-at refuses the update when the row was changed or moved since you read it (409 metadata_changed, the current row is in the error)")
+    .option("--expected-updated-at <iso>", "the row's updatedAt as you read it")
+    .option("--stage-id <id>", "move the row to another stage")
+    .option("--code <slug>", "status code")
+    .option("--bucket <slug>", "bucket")
+    .option("--lifecycle-stage <stage>", "lifecycle stage, or null")
+    .option("--drip-eligible <bool>", "true|false")
+    .option("--drip-track-id <id>", "drip track id, or null")
+    .option("--is-terminal <bool>", "true|false")
+    .option("--notes <text>", "free text (max 5000), or null")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, id, opts) => {
+    const rowId = uuidOf(id, "id");
+    const body = statusMetadataFields(opts);
+    if (opts.expectedUpdatedAt !== undefined)
+        body.expectedUpdatedAt = isoDate(opts.expectedUpdatedAt, "--expected-updated-at");
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    validateStatusMetadataBody(body, "update");
+    if (Object.keys(body).filter((k) => k !== "expectedUpdatedAt").length === 0)
+        throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    return client.patch(`/api/v1/status-metadata/${rowId}`, body);
+}));
+statusMetadata
+    .command("delete <id>")
+    .description("Delete a row (settings:edit, active billing). --expected-updated-at refuses the delete when the row changed or moved since you read it (409 metadata_changed)")
+    .option("--expected-updated-at <iso>", "the row's updatedAt as you read it")
+    .action(run(async (client, id, opts) => {
+    const rowId = uuidOf(id, "id");
+    const q = opts.expectedUpdatedAt === undefined ? "" : `?expected_updated_at=${encodeURIComponent(isoDate(opts.expectedUpdatedAt, "--expected-updated-at"))}`;
+    const res = await client.del(`/api/v1/status-metadata/${rowId}${q}`);
+    return res ?? { data: { deleted: true, id: rowId } };
+}));
+statusMetadata
+    .command("import")
+    .description(`Set-based import (owner / admin key, active billing; max 1000 items) from a JSON array of { stageId, code, bucket, lifecycleStage?, dripEligible?, dripTrackName?, isTerminal?, notes? } via --items or --file. merge (default) upserts the valid items and reports the rest in errors[]; replace replaces the rows of the ACTIVE pipelines and imports nothing if any item is invalid (rows of archived pipelines are kept). With --mode replace and NO items nothing is sent unless --confirm-empty-replace is given (it would delete every row). Prints { imported, skipped, errors } and exits 1 when errors is not empty (the full result is still printed). 409 pipeline_archived when an item names a stage of an archived pipeline`)
+    .option("--mode <mode>", "merge (default) | replace")
+    .option("--items <json>", "the items as a JSON array (or @file)")
+    .option("--file <path>", "read the items JSON array from a file")
+    .option("--confirm-empty-replace", "allow --mode replace with NO items, which deletes every status metadata row of the active pipelines")
+    .action(async (opts) => {
+    try {
+        if (opts.items !== undefined && opts.file !== undefined)
+            throw new Error("Pass either --items or --file, not both.");
+        if (opts.mode !== undefined && opts.mode !== "merge" && opts.mode !== "replace")
+            throw new Error("--mode must be merge or replace.");
+        let raw;
+        if (opts.file !== undefined) {
+            try {
+                raw = readFileSync(opts.file, "utf8");
+            }
+            catch {
+                throw new Error(`--file could not be read: ${opts.file}`);
+            }
+        }
+        else if (opts.items !== undefined) {
+            raw = opts.items.startsWith("@") ? readFileSync(opts.items.slice(1), "utf8") : opts.items;
+        }
+        else {
+            throw new Error("The items are required. Pass --items '<json array>' or --file <path>.");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("The items must be valid JSON.");
+        }
+        const items = validateImportItems(parsed);
+        // checked before any request; the flag is only a local confirmation and is never sent
+        if (opts.mode === "replace" && items.length === 0 && !opts.confirmEmptyReplace) {
+            throw new Error("replace with no items would delete every status metadata row; pass --confirm-empty-replace to do that on purpose");
+        }
+        const client = new ConduytClient();
+        const res = await client.post("/api/v1/status-metadata/import", { ...(opts.mode !== undefined ? { mode: opts.mode } : {}), items }, { timeoutMs: STATUS_METADATA_IMPORT_TIMEOUT_MS });
+        print(res);
+        // a 200 can still carry per-item errors (merge) or a refused replace (imported 0): that is a refusal, exit 1
+        const data = unwrap(res);
+        if (!data || typeof data !== "object" || typeof data.imported !== "number" || !Array.isArray(data.errors)) {
+            process.stderr.write("Error: Unexpected response shape from the API: expected { imported, skipped, errors }.\n");
+            process.exitCode = 1;
+        }
+        else if (data.errors.length > 0) {
+            for (const e of data.errors)
+                process.stderr.write(`Skipped ${String(e?.stageId ?? "?")}: ${String(e?.reason ?? "unknown reason")}\n`);
+            process.stderr.write(`Error: ${data.errors.length} item(s) were not imported (${data.imported} imported).\n`);
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        fail(err);
+    }
+});
 // ---- search ----
 program
     .command("search <query>")
@@ -2473,6 +2723,69 @@ wordpressForms
     .command("revoke <id>")
     .description("Revoke an intake address: submissions to it answer 404 from now on. The row is kept (status revoked) for history")
     .action(run(async (client, id) => client.del(`/api/v1/integrations/wordpress-forms/intakes/${uuidArg(id, "id")}`)));
+// Integrations -> Mailchimp (app 10-07/10-08, API key scope `integrations`): the audience sync. The OAuth connect and
+// callback are browser-only (connect Mailchimp in the app: Settings > Integrations), so there is no `connect` here.
+const mailchimp = integrations
+    .command("mailchimp")
+    .description("Mailchimp audience sync (API key scope integrations). Connecting is browser-only (OAuth): do it in the app, then configure it here. Errors exit 1 with the server's message and code (404 not connected, 409 revoked: reconnect in the app)");
+mailchimp
+    .command("settings")
+    .description("The Mailchimp connection: the audience, the source (one smart list or one tag), statusIfNew, unsubscribeSetsOptOut and the sync status (backfill progress, pending pushes, last pushed, last webhook, the last Mailchimp error, statusSweepBlocked). connected: false when there is none")
+    .action(run(async (client) => client.get("/api/v1/integrations/mailchimp/settings")));
+mailchimp
+    .command("set")
+    .description("Configure the sync (PUT; settings:edit, active billing): only the flags you pass change. A new audience gets Conduyt's webhook and starts the backfill; a new source starts the backfill. --source-type and --source-id go together")
+    .option("--list-id <id>", "Mailchimp audience id (see `audiences`)")
+    .option("--source-type <type>", "smart_list | tag")
+    .option("--source-id <id>", "the smart list or tag UUID")
+    .option("--status-if-new <status>", "subscribed (default) | pending (Mailchimp sends a confirmation email)")
+    .option("--unsubscribe-sets-opt-out <bool>", "true|false (default true): a Mailchimp unsubscribe also opts the contact out of Conduyt email")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.listId !== undefined) {
+        if (opts.listId.trim() === "")
+            throw new Error("--list-id was provided but is blank.");
+        body.listId = opts.listId.trim();
+    }
+    if ((opts.sourceType === undefined) !== (opts.sourceId === undefined))
+        throw new Error("--source-type and --source-id go together.");
+    if (opts.sourceType !== undefined) {
+        if (opts.sourceType !== "smart_list" && opts.sourceType !== "tag")
+            throw new Error('--source-type must be "smart_list" or "tag".');
+        body.source = { type: opts.sourceType, id: uuidOf(opts.sourceId, "--source-id") };
+    }
+    if (opts.statusIfNew !== undefined) {
+        if (opts.statusIfNew !== "subscribed" && opts.statusIfNew !== "pending")
+            throw new Error('--status-if-new must be "subscribed" or "pending".');
+        body.statusIfNew = opts.statusIfNew;
+    }
+    if (opts.unsubscribeSetsOptOut !== undefined)
+        body.unsubscribeSetsOptOut = boolFlag(opts.unsubscribeSetsOptOut, "--unsubscribe-sets-opt-out");
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to set. Pass --list-id, --source-type with --source-id, --status-if-new or --unsubscribe-sets-opt-out.");
+    return client.put("/api/v1/integrations/mailchimp/settings", body, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS });
+}));
+mailchimp
+    .command("audiences")
+    .description("The connected account's audiences: id, name, memberCount (use an id as --list-id)")
+    .action(run(async (client) => client.get("/api/v1/integrations/mailchimp/audiences")));
+mailchimp
+    .command("push")
+    .description("Run one sync pass now instead of waiting for the next minute (settings:edit, active billing): queue the contacts newly in the source, take a backfill step, send due pushes. Waits up to 60 s (if it times out the server may have applied it: read `settings`). Prints { ran, result, settings }; ran false means another pass holds the connection or Mailchimp asked to slow down")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/push", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("retry-unsubscribes")
+    .description("Try again, in one pass now, the unsubscribes Conduyt could not deliver to Mailchimp (also retried daily). Prints { ran, pending, delivered, undelivered, result, settings }; pending true = nothing was tried. One retry per account per 10 minutes: otherwise exit 1 with 429 retry_cooldown")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/unsubscribes/retry", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("reconcile-statuses")
+    .description("Full reconciliation when Conduyt's check of Mailchimp's unsubscribes is blocked (statusSweepBlocked in `settings`; owner / admin key): reads every member Mailchimp shows as unsubscribed or cleaned up to the blocked second and applies them (it only ever OPTS OUT), then records a report; it never resumes the check on its own, review the report and run `confirm-reconciliation`. Starts or resumes the run and runs one pass: repeat until done is true. --restart replaces a completed run's report with a new run; without it a completed run exits 1 with 409 reconciliation_completed")
+    .option("--restart", "replace a completed run's report with a new run")
+    .action(run(async (client, opts) => client.post("/api/v1/integrations/mailchimp/reconcile-statuses", opts.restart ? { restart: true } : {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
+mailchimp
+    .command("confirm-reconciliation")
+    .description("Confirm the completed reconciliation's report and resume the unsubscribe check after the blocked second (owner / admin key; audited with the report's counts). 409 when nothing is blocked, a reconciliation is still running, or none completed since the block began")
+    .action(run(async (client) => client.post("/api/v1/integrations/mailchimp/confirm-reconciliation", {}, { timeoutMs: MAILCHIMP_ADMIN_TIMEOUT_MS })));
 // ---------------------------------------------------------------------------
 // Sequences (one model for Email and SMS since 2026-09-30): steps send saved templates of the sequence's channel a
 // number of days apart inside a send window; a run stops on a reply, a booked meeting, an opt-out, a closed deal or a

package/dist/pipeline-settings.js

@@ -0,0 +1,155 @@
+/**
+ * Pipeline settings release (app 10-08), status metadata and Mailchimp: the validators the commands run before any
+ * request. They mirror the API (the source of truth) so a bad value fails locally with the same words; the API still
+ * re-checks everything and its refusal codes are printed with the error.
+ */
+export const PIPELINE_COLORS = ["#3845C9", "#43DFF6", "#2DD6B5", "#22C58B", "#9BD13B", "#F2B544", "#F07A2F", "#E6465A", "#FD88C0", "#956EFA"];
+export const LIFECYCLE_STAGES = ["pre_sale", "sale", "underwriting", "active", "resolution", "terminal"];
+export const MAX_STATUS_METADATA_IMPORT = 1000;
+/** per-call deadlines above the server budgets (archive tx 60 s; Mailchimp admin 60 s; import tx 20 s plus locks) */
+export const ARCHIVE_PIPELINE_TIMEOUT_MS = 75_000;
+export const MAILCHIMP_ADMIN_TIMEOUT_MS = 60_000;
+export const STATUS_METADATA_IMPORT_TIMEOUT_MS = 60_000;
+/** the exact fields an import item takes; anything else (a misspelled isTerminal, say) would be dropped by the API and stored as defaults */
+export const IMPORT_ITEM_KEYS = ["stageId", "code", "bucket", "lifecycleStage", "dripEligible", "dripTrackName", "isTerminal", "notes"];
+export const MIN_PIPELINE_ROT_DAYS = 1;
+export const MAX_PIPELINE_ROT_DAYS = 90;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SLUG_RE = /^[a-z0-9][a-z0-9_]{0,79}$/;
+const SETTINGS_REVISION_RE = /^\d+$/;
+export const isUuid = (v) => typeof v === "string" && UUID_RE.test(v.trim());
+export function uuid(raw, name) {
+    if (!isUuid(raw))
+        throw new Error(`${name} must be a UUID.`);
+    return raw.trim().toLowerCase();
+}
+/** true | false (any case) */
+export function boolFlag(raw, name) {
+    const v = raw.trim().toLowerCase();
+    if (v === "true")
+        return true;
+    if (v === "false")
+        return false;
+    throw new Error(`${name} must be true or false.`);
+}
+export function intFlag(raw, name, min, max) {
+    const t = raw.trim();
+    const n = Number(t);
+    if (t === "" || !Number.isInteger(n) || n < min || n > max)
+        throw new Error(`${name} must be an integer ${min}-${max}.`);
+    return n;
+}
+/** A pipeline colour is one of the 10 palette colours (case-insensitive); the API answers 400 for anything else. */
+export function pipelineColor(raw, name = "--color") {
+    const upper = raw.trim().toUpperCase();
+    const hit = PIPELINE_COLORS.find((c) => c === upper);
+    if (!hit)
+        throw new Error(`${name} must be one of the pipeline palette colours: ${PIPELINE_COLORS.join(", ")}.`);
+    return hit;
+}
+/** The settingsRevision a settings-backed write was read at: digits only (the API's pattern). */
+export function settingsRevision(raw, name = "--expected-settings-revision") {
+    const t = raw.trim();
+    if (!SETTINGS_REVISION_RE.test(t))
+        throw new Error(`${name} must be the settingsRevision you read (digits only).`);
+    return t;
+}
+/** An ISO date (the row's updatedAt as read); the API answers 400 for anything else. */
+export function isoDate(raw, name) {
+    const t = raw.trim();
+    if (t === "" || Number.isNaN(new Date(t).getTime()))
+        throw new Error(`${name} must be the updatedAt you read (an ISO date).`);
+    return t;
+}
+export function slug(raw, name) {
+    if (!SLUG_RE.test(raw))
+        throw new Error(`${name} must be a lowercase machine slug using letters, numbers and underscores (max 80).`);
+    return raw;
+}
+export function lifecycleStage(raw, name = "--lifecycle-stage") {
+    if (!LIFECYCLE_STAGES.includes(raw))
+        throw new Error(`${name} must be one of: ${LIFECYCLE_STAGES.join(", ")}.`);
+    return raw;
+}
+/** A comma-separated order list of UUIDs, no duplicates. */
+export function uuidList(raw, name) {
+    const ids = raw.split(",").map((s) => s.trim()).filter((s) => s !== "").map((s) => uuid(s, `${name} entry`));
+    if (ids.length === 0)
+        throw new Error(`${name} needs at least one id.`);
+    if (new Set(ids).size !== ids.length)
+        throw new Error(`${name} lists an id more than once.`);
+    return ids;
+}
+/** The fields of a status metadata row for create / update / get (a drip track is named by id); import names it by dripTrackName instead. */
+export const ROW_FIELD_KEYS = IMPORT_ITEM_KEYS.map((k) => (k === "dripTrackName" ? "dripTrackId" : k));
+/**
+ * THE one definition of a status metadata row's fields and types, shared by import items and the create / update bodies:
+ * unknown keys are refused naming the key (the API drops them and applies the rest of the call), and each present value is
+ * type-checked like the API does. `required`: stageId, code and bucket must be present. `trackKey` is the drip track field.
+ */
+function checkRowFields(o, at, allowed, required, trackKey, what) {
+    for (const k of Object.keys(o)) {
+        if (!allowed.includes(k))
+            throw new Error(`${at}: unknown field "${k}". ${what} takes ${allowed.join(", ")}; nothing was sent.`);
+    }
+    const has = (k) => o[k] !== undefined;
+    if (required || has("stageId")) {
+        if (typeof o.stageId !== "string" || !isUuid(o.stageId))
+            throw new Error(`${at}.stageId must be a UUID.`);
+    }
+    for (const k of ["code", "bucket"]) {
+        if (required || has(k)) {
+            if (typeof o[k] !== "string")
+                throw new Error(`${at}.${k} must be a slug.`);
+            slug(o[k], `${at}.${k}`);
+        }
+    }
+    if (has("lifecycleStage") && o.lifecycleStage !== null) {
+        if (typeof o.lifecycleStage !== "string")
+            throw new Error(`${at}.lifecycleStage must be one of: ${LIFECYCLE_STAGES.join(", ")}, or null.`);
+        lifecycleStage(o.lifecycleStage, `${at}.lifecycleStage`);
+    }
+    if (has("dripEligible") && typeof o.dripEligible !== "boolean")
+        throw new Error(`${at}.dripEligible must be a boolean.`);
+    if (has("isTerminal") && typeof o.isTerminal !== "boolean")
+        throw new Error(`${at}.isTerminal must be a boolean.`);
+    if (has(trackKey) && o[trackKey] !== null) {
+        const v = o[trackKey];
+        if (typeof v !== "string")
+            throw new Error(`${at}.${trackKey} must be ${trackKey === "dripTrackId" ? "a UUID" : "a slug"} or null.`);
+        if (trackKey === "dripTrackId") {
+            if (!isUuid(v))
+                throw new Error(`${at}.dripTrackId must be a UUID or null.`);
+        }
+        else
+            slug(v, `${at}.dripTrackName`);
+    }
+    if (has("notes") && o.notes !== null && (typeof o.notes !== "string" || o.notes.trim().length > 5000))
+        throw new Error(`${at}.notes must be text of at most 5000 characters.`);
+}
+/** One status metadata item, as the import route takes it. */
+export function validateImportItem(raw, index) {
+    const at = `items[${index}]`;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error(`${at} must be an object.`);
+    checkRowFields(raw, at, IMPORT_ITEM_KEYS, true, "dripTrackName", "An import item");
+    return raw;
+}
+/** The COMPLETE body of `status-metadata create` / `update` (flags + --json merged), checked before any request. */
+export function validateStatusMetadataBody(body, mode) {
+    const allowed = mode === "update" ? [...ROW_FIELD_KEYS, "expectedUpdatedAt"] : ROW_FIELD_KEYS;
+    checkRowFields(body, "body", allowed, mode === "create", "dripTrackId", mode === "create" ? "A status metadata row" : "A status metadata update");
+    if (body.expectedUpdatedAt !== undefined) {
+        if (typeof body.expectedUpdatedAt !== "string")
+            throw new Error("body.expectedUpdatedAt must be the updatedAt you read (an ISO date).");
+        isoDate(body.expectedUpdatedAt, "body.expectedUpdatedAt");
+    }
+    return body;
+}
+export function validateImportItems(raw) {
+    if (!Array.isArray(raw))
+        throw new Error("items must be a JSON array.");
+    if (raw.length > MAX_STATUS_METADATA_IMPORT)
+        throw new Error(`items takes at most ${MAX_STATUS_METADATA_IMPORT} entries (got ${raw.length}).`);
+    return raw.map((item, i) => validateImportItem(item, i));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.61.0",
+  "version": "1.62.0",
   "description": "Command-line interface for Conduyt CRM — manage contacts, deals, pipelines, and run insight queries from your terminal.",
   "type": "module",
   "main": "dist/index.js",