conduyt 1.5.0 → 1.8.0

package/README.md

@@ -39,6 +39,10 @@ conduyt search "acme corp"              # search across the CRM
 conduyt insights summary                # run an AI insight query
 conduyt privacy export <id>             # GDPR data-portability export (owner/admin)
 conduyt privacy forget <id> --confirm FORGET  # GDPR erasure — IRREVERSIBLE, owner only
+conduyt reply-capture status            # inbound reply capture: state, DNS records, provider health
+conduyt reply-capture setup             # create the receiving subdomain (--domain optional)
+conduyt reply-capture verify            # promote it to live once DNS is confirmed
+conduyt reply-capture remove --confirm REMOVE  # remove capture — replies to already-sent email are lost
 conduyt api GET /api/v1/companies       # raw authenticated request (escape hatch)
 conduyt config show                     # show resolved config (key masked)
 ```

package/dist/index.js

@@ -82,6 +82,8 @@ contacts
     .option("--email <email>", "email")
     .option("--phone <phone>", "phone")
     .option("--company <company>", "company name (auto-creates/links a company)")
+    .option("--source <source>", "lead source (first-write-wins acquisition truth)")
+    .option("--master-status <status>", "lead lifecycle status: open|won|lost|abandoned|disqualified or an account custom (terminal statuses silence all outbound automation)")
     .option("--json <json>", "full JSON body, merged over the flags above (for any field)")
     .action(run(async (client, opts) => {
     const body = {};
@@ -95,8 +97,23 @@ contacts
         body.phone = opts.phone;
     if (opts.company !== undefined)
         body.company = opts.company;
+    if (opts.source !== undefined) {
+        if (opts.source.trim() === "")
+            throw new Error("--source was provided but is blank. Omit it or pass a source.");
+        if (opts.source.length > 100)
+            throw new Error("--source must be at most 100 characters.");
+        body.source = opts.source;
+    }
+    if (opts.masterStatus !== undefined) {
+        if (opts.masterStatus.trim() === "")
+            throw new Error("--master-status was provided but is blank. Omit it or pass a status.");
+        if (opts.masterStatus.length > 40)
+            throw new Error("--master-status must be at most 40 characters.");
+        body.masterStatus = opts.masterStatus;
+    }
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
+    assertContactSource(body.source, { allowNull: false });
     return client.post("/api/v1/contacts", body);
 }));
 contacts
@@ -107,6 +124,8 @@ contacts
     .option("--email <email>", "email")
     .option("--phone <phone>", "phone")
     .option("--company <company>", "company name (auto-creates/links a company; pass '' to clear)")
+    .option("--source <source>", "correct the lead's first-touch source (normally set once at creation — update only to fix bad attribution; pass 'null' to clear)")
+    .option("--master-status <status>", "lead lifecycle status: open|won|lost|abandoned|disqualified or an account custom (terminal statuses silence all outbound automation)")
     .option("--json <json>", "full JSON body, merged over the flags above (for any field)")
     .action(run(async (client, id, opts) => {
     assertUuid(id, "contact id");
@@ -121,10 +140,28 @@ contacts
         body.phone = opts.phone;
     if (opts.company !== undefined)
         body.company = opts.company;
+    if (opts.source !== undefined) {
+        if (opts.source !== "null") {
+            if (opts.source.trim() === "") {
+                throw new Error("--source was provided but is blank. Omit it, or pass 'null' to clear the source.");
+            }
+            if (opts.source.length > 100)
+                throw new Error("--source must be at most 100 characters.");
+        }
+        body.source = opts.source === "null" ? null : opts.source;
+    }
+    if (opts.masterStatus !== undefined) {
+        if (opts.masterStatus.trim() === "")
+            throw new Error("--master-status was provided but is blank. Omit it or pass a status.");
+        if (opts.masterStatus.length > 40)
+            throw new Error("--master-status must be at most 40 characters.");
+        body.masterStatus = opts.masterStatus;
+    }
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
     if (Object.keys(body).length === 0)
         throw new Error("Nothing to update. Pass at least one field flag or --json.");
+    assertContactSource(body.source, { allowNull: true });
     return client.patch(`/api/v1/contacts/${encodeURIComponent(id)}`, body);
 }));
 contacts
@@ -271,6 +308,7 @@ deals
     .option("--value <n>", "deal value (number)")
     .option("--currency <code>", "ISO currency, e.g. GBP")
     .option("--contact <id>", "contact UUID to link")
+    .option("--source <source>", "attribution source for THIS deal (the trigger that produced it, e.g. sms-reply, booking:demo)")
     .option("--json <json>", "full JSON body, merged over the flags")
     .action(run(async (client, opts) => {
     const body = {};
@@ -295,6 +333,13 @@ deals
         body.currency = opts.currency;
     if (opts.contact !== undefined)
         body.contactId = opts.contact;
+    if (opts.source !== undefined) {
+        if (opts.source.trim() === "")
+            throw new Error("--source was provided but is blank. Omit it or pass a source.");
+        if (opts.source.length > 500)
+            throw new Error("--source must be at most 500 characters.");
+        body.source = opts.source;
+    }
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
     assertFiniteValue(body.value);
@@ -317,6 +362,7 @@ deals
     .option("--pipeline <id>", "move to this pipeline UUID")
     .option("--contact <id>", "primary contact UUID")
     .option("--status <status>", "explicit status (open|won|lost); overrides the status auto-derived from --stage")
+    .option("--source <source>", "attribution source for THIS deal (pass 'null' to clear it)")
     .option("--json <json>", "full JSON body, merged over the flags")
     .action(run(async (client, id, opts) => {
     assertUuid(id, "deal id");
@@ -339,6 +385,16 @@ deals
         body.contactId = opts.contact;
     if (opts.status !== undefined)
         body.status = opts.status;
+    if (opts.source !== undefined) {
+        // Mirror the API validator (blank rejected, 500-char cap) so the CLI
+        // fails locally rather than shipping a guaranteed 422.
+        if (opts.source.trim() === "") {
+            throw new Error("--source was provided but is blank. Omit it, or pass 'null' to clear the source.");
+        }
+        if (opts.source.length > 500)
+            throw new Error("--source must be at most 500 characters.");
+        body.source = opts.source === "null" ? null : opts.source;
+    }
     if (opts.stage !== undefined) {
         if (opts.stage.trim() === "")
             throw new Error("--stage was provided but is blank. Omit it or pass a stage name/UUID.");
@@ -1604,6 +1660,147 @@ program
         p = `/api/v1${p}`;
     return client.request(method.toUpperCase(), p, body);
 }));
+// ---- dialer ----
+const dialer = program.command("dialer").description("Dialer operations");
+dialer
+    .command("sync-local-presence")
+    .description("Reconcile the Local Presence pool from Twilio. Only adopts numbers whose Twilio FriendlyName contains a standalone 'LP' (or 'LocalPres'), that are voice-capable, and that are US +1 E.164 — first 50 sorted matches; pool entries that no longer match are REMOVED. Name the number in Twilio first, then sync. Requires settings:edit")
+    .action(run(async (client) => client.post("/api/v1/dialer/local-presence/sync", {})));
+// ---- reply capture (inbound email) ----
+// The receiving subdomain that makes replies to CRM email record and thread
+// against the contact. Same lifecycle as the sending domain: setup -> DNS ->
+// verify -> live, and the name MUST be a strict subdomain of the account's own
+// VERIFIED sending domain (that rule is the cross-tenant fence, not
+// formatting). Several non-2xx outcomes here are NORMAL, not retry loops:
+// 409 "already configured" (remove first), 409 "contact support to reconcile"
+// (an operator-repair state reachable only through a super-admin session
+// endpoint — an API key deliberately cannot fix it), 429 (per-account budget:
+// DNS takes minutes), and 503 (the shared provider allowance is busy with
+// customer sends — says nothing about the domain).
+const replyCapture = program
+    .command("reply-capture")
+    .description("Inbound reply capture: the receiving subdomain that threads email replies to contacts");
+replyCapture
+    .command("status")
+    .description("Show reply-capture state: configured/live, the capture domain and reply address, pending DNS records, and provider health. health='checking' means the provider is re-checking DNS and capture stays active; degraded=true means it can no longer receive and must be removed and set up again; needsSupport=true means an operator must reconcile it; cleanupPending=true means a previous removal did not finish at the provider — re-run `remove` to complete it. After a removal, draining=true (with drainEndsAt) means the drain window is open — a domain that was live at removal keeps receiving replies until it closes (one that was degraded has no such guarantee); parked=true means it is retired and inbound-inert. Either way that name is permanently unavailable — use suggestedDomain when setting up again")
+    .action(run(async (client) => client.get("/api/v1/email-domains/reply-capture")));
+replyCapture
+    .command("setup")
+    .description("Create the receiving subdomain at the email provider and return the DNS records to add. Requires a verified sending domain; the capture name must be a subdomain of it. Omit --domain to use the suggested reply.<sending-domain>. Add the records, then run `reply-capture verify`. A 409 can also mean the requested name belongs to a retired (drained/parked) domain — retired names are permanently unavailable, so use suggestedDomain from `reply-capture status` (e.g. reply2.<domain>) instead of retrying the old name")
+    .option("--domain <domain>", "capture subdomain, e.g. reply.acme.com (must be a subdomain of your verified sending domain)")
+    .action(run(async (client, opts) => {
+    const domain = opts.domain?.trim();
+    if (opts.domain !== undefined && !domain) {
+        fail("--domain must not be blank. Omit it entirely to use the suggested reply.<sending-domain>.");
+    }
+    // Sent only when supplied — an absent domain is how the API is told to
+    // use its suggestion.
+    return client.post("/api/v1/email-domains/reply-capture", domain ? { domain } : {});
+}));
+replyCapture
+    .command("verify")
+    .description("Check the pending capture domain's DNS and promote it to live once the provider confirms inbound receiving. verified=false with DNS record states is the expected answer while records propagate — poll sparingly, this is budgeted per account")
+    .action(run(async (client) => client.post("/api/v1/email-domains/reply-capture/verify", {})));
+replyCapture
+    .command("remove")
+    .description("Remove reply capture. Outcome depends on the domain's state. LIVE with a provider-backed setup: it DRAINS — the capture Reply-To stops on new email immediately, but the address keeps receiving for 30 days (drainEndsAt in the response) so late replies to already-sent emails still reach the contact's timeline; after that it parks, and the name is permanently retired (no account can ever set it up again — resuming capture means a NEW subdomain, see suggestedDomain on `reply-capture status`). LIVE legacy row with no stored provider id: removed immediately with NO drain — reply threading stops at once and the response says providerCleanup='manual' (an operator finishes the provider side); the name stays reusable. DEGRADED: drain lifecycle and permanent retirement, but receiving was already broken, so no 30-day delivery guarantee. PENDING setup, a domain the provider has already lost, or an interrupted-removal retry (cleanupPending): torn down immediately, the row is deleted, and the name stays reusable. Sending-domain removal stays blocked by every capture row except a released tombstone — pending/cleanup rows clear right here, but a draining/parked row keeps blocking until support releases it after the drain. Requires --confirm REMOVE")
+    // A VALUE, not a boolean flag: `--confirm false` on a boolean would read as
+    // true and delete anyway (same footgun the GDPR forget command guards).
+    .allowExcessArguments(false)
+    .option("--confirm <word>", "required — pass exactly REMOVE to authorize the removal (a provider-backed live/degraded name is permanently retired)")
+    .action(run(async (client, opts) => {
+    if (opts.confirm !== "REMOVE") {
+        fail("Refusing to remove: pass --confirm REMOVE to authorize this. Sending stops immediately, and a provider-backed live or degraded domain's name is permanently retired — there is no undo on the retirement (a legacy id-less live row instead stops threading at once).");
+    }
+    return client.del("/api/v1/email-domains/reply-capture");
+}));
+// ---- lifecycle (master lead status + intake deals) ----
+const lifecycle = program
+    .command("lifecycle")
+    .description("Lifecycle v2 settings: lead master statuses and automatic intake-deal creation");
+lifecycle
+    .command("settings")
+    .description("Show the Lifecycle v2 configuration: masterStatuses.effective (the five defaults plus the account's customs) and intakeDeals (null can mean not configured OR not visible to your key — the setting is admin-visible only)")
+    .action(run(async (client) => {
+    const DEFAULTS = ["open", "won", "lost", "abandoned", "disqualified"];
+    const result = (await client.get("/api/v1/settings"));
+    const raw = result?.data ?? {};
+    const customs = Array.isArray(raw.masterStatuses)
+        ? raw.masterStatuses.filter((x) => typeof x === "string")
+        : [];
+    const intakeDeals = raw.intakeDeals && typeof raw.intakeDeals === "object" ? raw.intakeDeals : null;
+    return {
+        data: {
+            masterStatuses: {
+                defaults: DEFAULTS,
+                customs,
+                effective: [...DEFAULTS, ...customs.filter((c) => !DEFAULTS.includes(c.toLowerCase()))],
+            },
+            intakeDeals,
+            ...(intakeDeals === null
+                ? {
+                    intakeDealsNote: "null = not configured, OR your key's role cannot read this admin-visible setting",
+                }
+                : {}),
+        },
+    };
+}));
+lifecycle
+    .command("set-intake-deals")
+    .description("Configure automatic deal creation on live intake (webhooks, public forms, public bookings). Even under --re-inbound always: bulk imports and staff/calendar/dialer-created appointments never mint, exact replays and same-source events within 10 min are skipped, and terminal-status contacts get no new deals")
+    .option("--enable", "turn intake deals ON")
+    .option("--disable", "turn intake deals OFF")
+    .option("--pipeline <id>", "pipeline UUID the intake deals land in")
+    .option("--stage <id>", "starting stage UUID within that pipeline")
+    .option("--re-inbound <policy>", "policy for existing contacts: always|if_no_open|never")
+    .action(run(async (client, opts) => {
+    if (opts.enable && opts.disable)
+        throw new Error("Pass either --enable or --disable, not both.");
+    if (opts.enable === undefined && opts.disable === undefined) {
+        throw new Error("Pass --enable or --disable.");
+    }
+    if (!opts.pipeline || !opts.stage) {
+        // The API requires the full object, so the CLI must too — a partial
+        // PATCH would 422 with a less obvious message.
+        throw new Error("--pipeline and --stage are required (see `conduyt pipelines list`).");
+    }
+    const body = {
+        enabled: Boolean(opts.enable),
+        pipelineId: opts.pipeline,
+        stageId: opts.stage,
+    };
+    if (opts.reInbound !== undefined) {
+        if (!["always", "if_no_open", "never"].includes(opts.reInbound)) {
+            throw new Error("--re-inbound must be one of: always, if_no_open, never.");
+        }
+        body.reInbound = opts.reInbound;
+    }
+    return client.patch("/api/v1/settings", { intakeDeals: body });
+}));
+lifecycle
+    .command("set-master-statuses [statuses...]")
+    .description("Set the account's CUSTOM lead lifecycle statuses (the five defaults always exist). Pass --clear with no names to remove all customs")
+    .option("--clear", "remove ALL custom statuses (restore defaults-only)")
+    .action(run(async (client, statuses, opts) => {
+    statuses = statuses ?? [];
+    if (statuses.length === 0 && !opts.clear) {
+        throw new Error("Pass at least one status name, or --clear to remove all customs.");
+    }
+    if (statuses.length > 0 && opts.clear) {
+        throw new Error("--clear cannot be combined with status names.");
+    }
+    // Mirror of the API validator: max 20 names, 1-40 chars, letters/
+    // numbers/spaces/-/_ only — fail fast locally instead of a late 422.
+    const clean = statuses.map((s) => s.trim());
+    if (clean.some((s) => !s))
+        throw new Error("Status names must not be blank.");
+    if (clean.length > 20)
+        throw new Error("At most 20 custom statuses.");
+    const bad = clean.find((s) => s.length > 40 || !/^[a-z0-9][a-z0-9 _-]*$/i.test(s));
+    if (bad)
+        throw new Error(`Invalid status name '${bad}' — 1-40 chars; letters, numbers, spaces, - and _ only.`);
+    return client.patch("/api/v1/settings", { masterStatuses: clean });
+}));
 program.parseAsync(process.argv).catch(fail);
 // helpers
 // Parse a --json / --stages style argument, throwing a clear CLI error (caught
@@ -1761,6 +1958,23 @@ function run(handler) {
         }
     };
 }
+// Contact source is the first-write-wins acquisition truth: a blank value
+// must never reach storage, whether it arrived via a flag or --json (the
+// merge runs last, so this validates the FINAL body).
+function assertContactSource(value, opts) {
+    if (value === undefined)
+        return;
+    if (value === null) {
+        if (opts.allowNull)
+            return;
+        throw new Error("source cannot be null on create — omit it instead.");
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error("source must be a non-blank string (or omitted).");
+    }
+    if (value.length > 100)
+        throw new Error("source must be at most 100 characters.");
+}
 function mask(key) {
     if (!key)
         return "(not set)";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "conduyt",
-  "version": "1.5.0",
-  "description": "Command-line interface for Conduyt CRM \u2014 manage contacts, deals, pipelines, and run insight queries from your terminal.",
+  "version": "1.8.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",
   "bin": {
@@ -18,8 +18,9 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "start": "tsx src/index.ts",
-    "prepublishOnly": "npm run build",
-    "test": "node --import tsx --test src/*.test.ts"
+    "prepublishOnly": "npm run check:version && npm run build && node --import tsx --experimental-test-module-mocks --test src/privacy-forget.test.ts src/contact-source-json.test.ts",
+    "test": "node --import tsx --test src/*.test.ts",
+    "check:version": "node -e \"const p=require('./package.json').version,l=require('./package-lock.json');if(l.version!==p||l.packages[''].version!==p){console.error('lockfile version != '+p);process.exit(1)}console.log('Version sync OK: '+p)\""
   },
   "keywords": [
     "conduyt",