conduyt 1.67.0 → 1.68.0

package/README.md

@@ -78,13 +78,26 @@ conduyt whatsapp connect <senderSid>    # connect a sender (verified with Twilio
 conduyt whatsapp templates              # approved / pending / rejected templates with their {{n}} placeholders
 conduyt dialer voice-drop --contact <id> [--recording "Missed you"] [--if-human play]   # a call that plays a Voicemail Drop recording to a machine
 conduyt messages send-sms --contact <id> --transport whatsapp --whatsapp-template HX… --whatsapp-variables '{"1":"Alex"}' --body "…"
-conduyt messages check --channel sms --body "…" [--context first|conversation] [--body-file draft.txt]   # grade a DRAFT before sending (score, grade, flagged words with safer alternatives, Unicode code-point offsets); educates, never blocks, nothing stored or sent; 20 per minute; 400 / 403 / 413 / 429 exit 1 with the code
+conduyt messages check --channel sms --body "…" [--context first|conversation] [--provider twilio] [--clean] [--body-file draft.txt]   # grade a DRAFT before sending (score, grade, flagged words with safer alternatives, Unicode code-point offsets); --provider twilio (texts only) words the notices in Twilio's wording, --clean adds the cleaner's proposal; educates, never blocks, nothing stored or sent; 20 per minute; 400 / 403 / 413 / 429 exit 1 with the code
+conduyt sms providers options   # the workspace's active SMS providers, redacted: [{ id, name, color }] (needs email_templates.view or settings.view)
+conduyt templates list [--channel email|sms] [--active true]   # email / SMS templates; each row carries bodyMode (blocks | html); the pasted html is not repeated in a list row
+conduyt templates get <id>   # one template with its full content (an HTML-mode template answers its pasted source in `html`)
+conduyt templates create --name "Promo" --channel email --subject "Hi" --body-mode html --html-file email.html   # pasted HTML (email only, 102,400 bytes at most); blocks: --body "…" [--body-html …]; 400 codes (html_too_large, html_script, html_conditional_comment, html_office_markup, html_duplicate_attribute, template_corrupt, …) exit 1 verbatim
+conduyt templates update <id> [--name …] [--body-mode html --html-file email.html] [--active false]   # partial update
+conduyt dialer history --q "refund" --recorded-only [--disposition X] [--user <id>] [--from D] [--to D] [--mine]   # QA search of the call log: per-row `match`, meta.incomplete (a lower-bound total when a number search is capped), stats; 200 per page
+conduyt dialer calls --status voicemail --q "+1555…"   # the recordings / voicemail list with the same search (100 per page)
+conduyt dialer recording download <callId> [--voicemail] [-o file] [--force]   # stream the call audio to a file (named by the API when no -o); never over an existing file without --force
 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 integrations calendly status   # the Calendly connection: event types, selection, live sync (on | pending | plan_refused), import progress, last booking / error (integrations scope; connecting is browser-only)
+conduyt integrations calendly import-progress [--connection-id <id>]   # the import alone: status, eventsSeen, imported, skipped, error
+conduyt integrations calendly event-types   # re-read the event types from Calendly (the picker list)
+conduyt integrations calendly set-event-types --uri https://api.calendly.com/event_types/<id> [--uri …] | --none   # ONLY these sync; the first save or an added type starts the silent import
+conduyt integrations calendly disconnect [--connection-id <id>]   # removes the webhook and the connection; appointments stay
 conduyt integrations wordpress-forms status   # is any intake address active, and how many ({ hasActive, activeCount }; count only, read-only, integrations scope)
 conduyt integrations wordpress-forms list    # WordPress form intake addresses: full URL of every active one, received counts
 conduyt integrations wordpress-forms create --name "Contact page" --default-tag "Website lead"   # prints the full URL

package/dist/calendly-status.js

@@ -0,0 +1,87 @@
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isInt = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+const strOrNull = (v) => v === null || typeof v === "string";
+/** the import's states (the connection row: idle | queued | running | done | failed); done and failed are terminal */
+export const CALENDLY_IMPORT_STATUSES = ["idle", "queued", "running", "done", "failed"];
+export const CALENDLY_LIVE_SYNC = ["on", "pending", "plan_refused"];
+function bad(path, why) {
+    throw new Error(`calendly status: the API answered something that is not the documented connection (${path}: ${why}); nothing was printed. This is a CLI/API version mismatch: update the CLI or report it.`);
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const isDate = (v) => typeof v === "string" && /^\d{4}-\d{2}-\d{2}T/.test(v) && !Number.isNaN(Date.parse(v));
+/** CalendlyEventType: { uri, name, active, kind, poolingType, schedulingUrl }, every key present */
+function checkEventType(t, path) {
+    if (!isObj(t))
+        bad(path, "expected an object");
+    for (const k of ["uri", "name"])
+        if (typeof t[k] !== "string" || t[k] === "")
+            bad(`${path}.${k}`, "required string is missing");
+    if (typeof t.active !== "boolean")
+        bad(`${path}.active`, "expected a boolean");
+    for (const k of ["kind", "poolingType", "schedulingUrl"])
+        if (!(k in t) || !strOrNull(t[k]))
+            bad(`${path}.${k}`, "expected a string or null");
+}
+function checkConnection(c, path) {
+    if (!isObj(c))
+        bad(path, "expected an object");
+    for (const k of ["id", "userId"])
+        if (typeof c[k] !== "string" || !UUID.test(c[k]))
+            bad(`${path}.${k}`, "expected a UUID");
+    if (typeof c.status !== "string" || c.status === "")
+        bad(`${path}.status`, "required string is missing");
+    if (!isDate(c.createdAt))
+        bad(`${path}.createdAt`, "expected an ISO date-time");
+    for (const k of ["calendlyEmail", "calendlyName", "planWarning", "lastError"])
+        if (!(k in c) || !strOrNull(c[k]))
+            bad(`${path}.${k}`, "expected a string or null");
+    for (const k of ["lastBookingAt", "lastErrorAt"])
+        if (!(k in c) || (c[k] !== null && !isDate(c[k])))
+            bad(`${path}.${k}`, "expected an ISO date-time or null");
+    if (!Array.isArray(c.eventTypes))
+        bad(`${path}.eventTypes`, "expected an array");
+    c.eventTypes.forEach((t, i) => checkEventType(t, `${path}.eventTypes[${i}]`));
+    if (!Array.isArray(c.selectedEventTypeUris) || !c.selectedEventTypeUris.every((u) => typeof u === "string"))
+        bad(`${path}.selectedEventTypeUris`, "expected an array of strings");
+    if (typeof c.selectionSaved !== "boolean")
+        bad(`${path}.selectionSaved`, "expected a boolean");
+    if (!CALENDLY_LIVE_SYNC.includes(c.liveSync))
+        bad(`${path}.liveSync`, `expected one of ${CALENDLY_LIVE_SYNC.join(", ")}`);
+    const imp = c.import;
+    if (!isObj(imp))
+        bad(`${path}.import`, "expected an object");
+    if (!CALENDLY_IMPORT_STATUSES.includes(imp.status))
+        bad(`${path}.import.status`, `expected one of ${CALENDLY_IMPORT_STATUSES.join(", ")}`);
+    for (const k of ["eventsSeen", "imported", "skipped"])
+        if (!isInt(imp[k]))
+            bad(`${path}.import.${k}`, "expected a non-negative integer");
+    for (const k of ["startedAt", "finishedAt"])
+        if (!(k in imp) || (imp[k] !== null && !isDate(imp[k])))
+            bad(`${path}.import.${k}`, "expected an ISO date-time or null");
+    if (!("error" in imp) || !strOrNull(imp.error))
+        bad(`${path}.import.error`, "expected a string or null");
+    return c;
+}
+/** validate the whole status answer; returns the envelope's data */
+export function calendlyStatus(res) {
+    if (!isObj(res) || !isObj(res.data))
+        bad("$", "expected { data: { ... } }");
+    const d = res.data;
+    if (typeof d.configured !== "boolean")
+        bad("configured", "expected a boolean");
+    if (typeof d.connected !== "boolean")
+        bad("connected", "expected a boolean");
+    for (const k of ["description", "importLine"])
+        if (typeof d[k] !== "string")
+            bad(k, "expected a string");
+    const connection = d.connection === null ? null : checkConnection(d.connection, "connection");
+    if (d.connected !== (connection !== null))
+        bad("connected", "disagrees with connection");
+    let connections;
+    if (d.connections !== undefined) {
+        if (!Array.isArray(d.connections))
+            bad("connections", "expected an array");
+        connections = d.connections.map((c, i) => checkConnection(c, `connections[${i}]`));
+    }
+    return { ...d, connection, connections };
+}

package/dist/cli-harness.js

@@ -0,0 +1,136 @@
+/** Test helper (not a test): run the real CLI against a local HTTP server, as the other command tests do. */
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const entry = join(dirname(fileURLToPath(import.meta.url)), "index.ts");
+/** The handshake never passes silently: a predicate that throws or never becomes true is recorded here and withServer fails the test with it. */
+export async function withServer(reply, fn) {
+    const seen = [];
+    const failures = [];
+    const server = createServer((req, res) => {
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", () => {
+            const s = { method: req.method, url: req.url, body, headers: req.headers };
+            seen.push(s);
+            const r = reply(s, seen.length);
+            res.statusCode = r.status;
+            if (r.raw === undefined)
+                res.setHeader("content-type", "application/json");
+            for (const [k, v] of Object.entries(r.headers ?? {}))
+                res.setHeader(k, v);
+            if (r.hold) {
+                res.setHeader("content-length", String(Buffer.byteLength(r.raw ?? "") + 1000));
+                res.write(r.raw ?? "");
+                return;
+            }
+            if (r.abort) {
+                res.setHeader("content-length", String(Buffer.byteLength(r.raw ?? "") + 1000));
+                res.write(r.raw ?? "");
+                const give = Date.now() + (r.abortWithin ?? 30000);
+                const cut = () => {
+                    let ready = false;
+                    if (!r.abortWhen)
+                        ready = true;
+                    else {
+                        try {
+                            ready = r.abortWhen();
+                        }
+                        catch (e) {
+                            failures.push(`abortWhen threw before the partial file was observed: ${e instanceof Error ? e.message : String(e)}`);
+                            res.socket?.destroy();
+                            return;
+                        }
+                    }
+                    if (ready)
+                        res.socket?.destroy();
+                    else if (Date.now() > give) {
+                        failures.push(`abortWhen never became true within ${r.abortWithin ?? 30000} ms: the stream was cut without the precondition (a non-empty partial file) being observed`);
+                        res.socket?.destroy();
+                    }
+                    else
+                        setTimeout(cut, 20);
+                };
+                setTimeout(cut, r.abortWhen ? 20 : 50);
+                return;
+            }
+            res.end(r.raw !== undefined ? r.raw : JSON.stringify(r.json));
+        });
+    });
+    const serverFailed = new Promise((_, reject) => server.on("error", (e) => reject(new Error(`test server error: ${e instanceof Error ? e.message : String(e)}`))));
+    serverFailed.catch(() => undefined);
+    await Promise.race([new Promise((r) => server.listen(0, "127.0.0.1", r)), serverFailed]);
+    try {
+        await Promise.race([fn(`http://127.0.0.1:${server.address().port}`, seen), serverFailed]);
+    }
+    finally {
+        // held-open responses must not keep the run alive: drop every connection, then wait for the server to be gone
+        server.closeAllConnections();
+        await new Promise((r) => server.close(() => r()));
+    }
+    if (failures.length)
+        throw new Error(`test handshake failed: ${failures.join("; ")}`);
+}
+/** The promise of a child's `close` (stdio finished, which can lag the process's exit); a spawn failure rejects with an attributed error. */
+export function closeOf(p, getErr = () => "") {
+    const done = new Promise((resolve, reject) => {
+        p.on("error", (e) => reject(new Error(`could not run the CLI child: ${e.message}`)));
+        p.on("close", (code, signal) => resolve({ code, signal, err: getErr() }));
+    });
+    done.catch(() => undefined);
+    return done;
+}
+/** start the CLI and hand back the child (to signal it) and its result */
+export function startCli(url, args, cwd) {
+    const p = spawn(process.execPath, ["--import", import.meta.resolve("tsx"), entry, ...args], {
+        env: { ...process.env, CONDUYT_API_URL: url, CONDUYT_API_KEY: "cdy_dummy_test_key" },
+        ...(cwd ? { cwd } : {}),
+    });
+    let err = "";
+    p.stderr.on("data", (c) => (err += c));
+    return { p, done: closeOf(p, () => err) };
+}
+/**
+ * Wait for a child to end within `ms`. `close` can lag the process's `exit`, and signalling an exited child can hit a reused PID, so
+ * after the deadline the child's exit state is re-checked: SIGKILL goes out ONLY if no exit was observed; if it had exited, the
+ * remaining wait is for its stdio to close (bounded, no further signal). A regression cannot hang the suite.
+ */
+export async function boundedExit(p, done, ms = 20000, closeMs = 10000) {
+    const wait = (t) => new Promise((r) => setTimeout(() => r("timeout"), t).unref());
+    const first = await Promise.race([done, wait(ms)]);
+    if (first !== "timeout")
+        return first;
+    const exited = p.exitCode !== null || p.signalCode !== null;
+    if (!exited)
+        p.kill("SIGKILL");
+    const second = await Promise.race([done, wait(closeMs)]);
+    if (second === "timeout")
+        throw new Error(exited ? `the CLI child exited but its stdio did not close within ${closeMs} ms (no signal was sent)` : `the CLI child did not exit within ${ms} ms and survived SIGKILL for ${closeMs} ms`);
+    if (exited)
+        return second; // it had already exited: only the close was late
+    throw new Error(`the CLI child did not exit within ${ms} ms after the signal; it was killed with SIGKILL (exit ${second.code}, signal ${second.signal}): ${second.err}`);
+}
+export function runCli(url, args, cwd) {
+    return new Promise((resolve) => {
+        const p = spawn(process.execPath, ["--import", import.meta.resolve("tsx"), entry, ...args], {
+            env: { ...process.env, CONDUYT_API_URL: url, CONDUYT_API_KEY: "cdy_dummy_test_key" },
+            ...(cwd ? { cwd } : {}),
+        });
+        let out = "", err = "";
+        p.stdout.on("data", (c) => (out += c));
+        p.stderr.on("data", (c) => (err += c));
+        p.on("error", (e) => resolve({ status: null, out, err: `${err}could not run the CLI child: ${e.message}` }));
+        p.on("close", (status) => resolve({ status, out, err }));
+    });
+}
+/** the final token of an error text is ONE valid JSON object */
+export function finalDetails(text) {
+    for (let i = text.indexOf("{"); i !== -1; i = text.indexOf("{", i + 1)) {
+        try {
+            return JSON.parse(text.slice(i).trim());
+        }
+        catch { /* next brace */ }
+    }
+    throw new Error(`no trailing JSON object in: ${text}`);
+}

package/dist/client.js

@@ -1,3 +1,9 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream, existsSync, linkSync, renameSync, unlinkSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 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) {
@@ -171,6 +177,74 @@ export class ConduytClient {
             throw formatHttpError(res, text);
         return { text, filename: res.headers.get("x-report-filename"), contentType: res.headers.get("content-type") };
     }
+    /**
+     * GET a binary body (call audio) and stream it to a file: nothing is held in memory. `outFile` null = name it from the response's
+     * Content-Disposition (the basename only), else `fallbackName`. The bytes go to a unique temporary file in the destination folder,
+     * are flushed to disk, and only then committed to the final name in one step: without `overwrite` the commit refuses (EEXIST) a file
+     * that appeared meanwhile and never replaces it; with `overwrite` the old file is replaced only after the whole download arrived.
+     * A refusal (any non-2xx) or a broken stream writes nothing at the final name and leaves no temporary file behind.
+     */
+    async download(path, opts) {
+        const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+        // a fast refusal before any bytes move; the commit below is the authority (a file can appear while the download runs)
+        if (opts.outFile !== null && !opts.overwrite && existsSync(opts.outFile))
+            throw new Error(`${opts.outFile} already exists; pass -o <another file> or --force to overwrite it.`);
+        const res = await fetch(url, { method: "GET", headers: { Authorization: `Bearer ${this.apiKey}` } });
+        if (!res.ok)
+            throw formatHttpError(res, await res.text());
+        if (!res.body)
+            throw new Error("Conduyt API: the response had no body.");
+        const target = opts.outFile ?? dispositionFilename(res.headers.get("content-disposition")) ?? opts.fallbackName;
+        if (!opts.overwrite && existsSync(target)) {
+            await res.body.cancel().catch(() => undefined);
+            throw new Error(`${target} already exists; pass -o <another file> or --force to overwrite it.`);
+        }
+        const tmp = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(6).toString("hex")}.part`);
+        let bytes = 0;
+        // An interrupt (Ctrl-C, kill) does not unwind the catch below: while the temporary file exists, SIGINT / SIGTERM remove it first, put the
+        // handlers back, and re-raise the signal so the process ends exactly as it would have (exit status 128 + signal). Partial call audio is
+        // sensitive and must not survive.
+        const onSignal = (sig) => {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* not created yet, or already gone */ }
+            process.removeListener("SIGINT", onInt);
+            process.removeListener("SIGTERM", onTerm);
+            process.kill(process.pid, sig);
+        };
+        const onInt = () => onSignal("SIGINT");
+        const onTerm = () => onSignal("SIGTERM");
+        process.on("SIGINT", onInt);
+        process.on("SIGTERM", onTerm);
+        try {
+            const counted = Readable.fromWeb(res.body);
+            counted.on("data", (c) => { bytes += c.length; });
+            await pipeline(counted, createWriteStream(tmp, { flags: "wx", mode: 0o600 }));
+            const fh = await open(tmp, "r+");
+            try {
+                await fh.sync();
+            }
+            finally {
+                await fh.close();
+            }
+            commitDownload(tmp, target, Boolean(opts.overwrite));
+        }
+        catch (err) {
+            try {
+                unlinkSync(tmp);
+            }
+            catch { /* no temporary file left to remove */ }
+            if (err instanceof Error && err.code === "EEXIST")
+                throw new Error(`${target} already exists; pass -o <another file> or --force to overwrite it. Nothing was written.`);
+            throw new Error(`Download failed before the file was complete (${err instanceof Error ? err.message : String(err)}); nothing was kept.`);
+        }
+        finally {
+            process.removeListener("SIGINT", onInt);
+            process.removeListener("SIGTERM", onTerm);
+        }
+        return { saved: target, bytes, contentType: res.headers.get("content-type") };
+    }
     // Stream `ai chat`'s text/event-stream response to stdout as clean answer
     // text. The server frames SSE records as `data: {"text":"..."}\n\n`, ends
     // with `data: [DONE]\n\n`, and reports in-stream failures as
@@ -248,6 +322,39 @@ export class ConduytClient {
             process.stdout.write("\n");
     }
 }
+/** The file name a Content-Disposition names (RFC 5987 filename* wins over filename), reduced to a basename so a header can never pick a directory. */
+export function dispositionFilename(header) {
+    if (!header)
+        return null;
+    let name = null;
+    const star = /filename\*\s*=\s*UTF-8''([^;]+)/i.exec(header);
+    if (star) {
+        try {
+            name = decodeURIComponent(star[1].trim());
+        }
+        catch {
+            name = null;
+        }
+    }
+    if (name === null) {
+        const plain = /filename\s*=\s*"((?:[^"\\]|\\.)*)"|filename\s*=\s*([^;]+)/i.exec(header);
+        if (plain)
+            name = (plain[1] ?? plain[2] ?? "").trim().replace(/\\(.)/g, "$1");
+    }
+    if (!name)
+        return null;
+    const base = basename(name.replace(/\\/g, "/"));
+    return base && base !== "." && base !== ".." ? base : null;
+}
+/** Move a finished temporary file onto its final name. No-clobber: a hard link fails with EEXIST when the name is taken, so an existing file is never touched; with `overwrite` the rename replaces it atomically. */
+export function commitDownload(tmp, target, overwrite) {
+    if (overwrite) {
+        renameSync(tmp, target);
+        return;
+    }
+    linkSync(tmp, target);
+    unlinkSync(tmp);
+}
 function safeParse(text) {
     try {
         return JSON.parse(text);

package/dist/dialer-pages.js

@@ -0,0 +1,102 @@
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isInt = (v) => typeof v === "number" && Number.isInteger(v);
+function bad(what, path, why) {
+    throw new Error(`${what}: the API answered something that is not the documented page (${path}: ${why}); nothing was printed. This is a CLI/API version mismatch: update the CLI or report it.`);
+}
+/** a field that may be absent: when present it must be one of the kinds */
+function optional(o, key, ok, kind, what, path) {
+    if (key in o && o[key] !== undefined && !ok(o[key]))
+        bad(what, `${path}.${key}`, `expected ${kind}`);
+}
+const str = (v) => typeof v === "string";
+const strOrNull = (v) => v === null || typeof v === "string";
+const intOrNull = (v) => v === null || isInt(v);
+const MATCH_FIELDS = ["name", "number", "agent", "transcript"];
+function checkMatch(m, what, path) {
+    if (m === null)
+        return;
+    if (!isObj(m))
+        bad(what, path, "expected an object or null");
+    if (typeof m.field !== "string" || !MATCH_FIELDS.includes(m.field))
+        bad(what, `${path}.field`, `expected one of ${MATCH_FIELDS.join(", ")}`);
+    optional(m, "snippet", str, "a string", what, path);
+    if ("ranges" in m && m.ranges !== undefined) {
+        if (!Array.isArray(m.ranges))
+            bad(what, `${path}.ranges`, "expected an array");
+        m.ranges.forEach((r, i) => {
+            if (!Array.isArray(r) || r.length !== 2 || !isInt(r[0]) || !isInt(r[1]) || r[0] < 0 || r[1] < 0)
+                bad(what, `${path}.ranges[${i}]`, "expected [start, end] non-negative integers");
+        });
+    }
+}
+function checkRow(row, what, path) {
+    if (!isObj(row))
+        bad(what, path, "expected an object");
+    for (const k of ["id", "direction", "fromNumber", "toNumber", "status", "createdAt"])
+        if (!str(row[k]))
+            bad(what, `${path}.${k}`, "required string is missing");
+    for (const k of ["hasRecording", "hasVoicemail"])
+        if (typeof row[k] !== "boolean")
+            bad(what, `${path}.${k}`, "required boolean is missing");
+    for (const k of ["contactId", "userId", "notes", "voicemailReadAt", "voicemailDeletedAt", "transcriptionText", "transcriptionUrl", "disposition", "destinationCallSid", "transferCallSid", "transferStatus", "transferTargetNumber", "conferenceSid", "startedAt", "endedAt"]) {
+        optional(row, k, strOrNull, "a string or null", what, path);
+    }
+    optional(row, "duration", intOrNull, "an integer or null", what, path);
+    optional(row, "dncOverride", (v) => typeof v === "boolean", "a boolean", what, path);
+    for (const k of ["contact", "user"])
+        optional(row, k, (v) => v === null || isObj(v), "an object or null", what, path);
+    if ("match" in row && row.match !== undefined)
+        checkMatch(row.match, what, `${path}.match`);
+}
+function checkRows(rows, what, path) {
+    if (!Array.isArray(rows))
+        bad(what, path, "expected an array");
+    rows.forEach((r, i) => checkRow(r, what, `${path}[${i}]`));
+}
+function checkIncomplete(meta, what) {
+    optional(meta, "incomplete", (v) => typeof v === "boolean", "a boolean", what, "meta");
+    optional(meta, "incompleteReason", (v) => v === "number_matches_capped", '"number_matches_capped"', what, "meta");
+    const has = (k) => k in meta && meta[k] !== undefined;
+    if (has("incompleteReason") && meta.incomplete !== true)
+        bad(what, "meta.incompleteReason", "present without incomplete: true");
+    if (meta.incomplete === true && !has("incompleteReason"))
+        bad(what, "meta.incompleteReason", "missing with incomplete: true");
+}
+/** GET /dialer/history: returns the page { data, meta, stats } */
+export function historyPage(res) {
+    const what = "dialer history";
+    if (!isObj(res) || !isObj(res.data))
+        bad(what, "$", "expected { data: { data, meta, stats } }");
+    const page = res.data;
+    checkRows(page.data, what, "data");
+    const meta = page.meta;
+    if (!isObj(meta))
+        bad(what, "meta", "expected an object");
+    for (const k of ["page", "per_page", "total"])
+        if (!isInt(meta[k]))
+            bad(what, `meta.${k}`, "required integer is missing");
+    checkIncomplete(meta, what);
+    const stats = page.stats;
+    if (!isObj(stats))
+        bad(what, "stats", "expected an object");
+    for (const k of ["total", "inbound", "outbound"])
+        if (!isInt(stats[k]))
+            bad(what, `stats.${k}`, "required integer is missing");
+    optional(stats, "avgTalkSeconds", isInt, "an integer", what, "stats");
+    return page;
+}
+/** GET /dialer/calls: returns the page { data, meta } */
+export function callsPage(res) {
+    const what = "dialer calls";
+    if (!isObj(res))
+        bad(what, "$", "expected { data, meta }");
+    checkRows(res.data, what, "data");
+    const meta = res.meta;
+    if (!isObj(meta))
+        bad(what, "meta", "expected an object");
+    for (const k of ["page", "perPage", "total", "totalPages"])
+        if (!isInt(meta[k]))
+            bad(what, `meta.${k}`, "required integer is missing");
+    checkIncomplete(meta, what);
+    return res;
+}

package/dist/index.js

@@ -9,6 +9,8 @@ import { splitList, stageRulePatch, validateCardFields, validateRuleChange } fro
 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";
+import { callsPage, historyPage } from "./dialer-pages.js";
+import { calendlyStatus } from "./calendly-status.js";
 /** the contact save revision bound (catalog: integer 0..2147483647) */
 const CONTACT_REVISION_MAX = 2147483647;
 // Exit cleanly when a downstream pipe closes early (e.g. `conduyt deals list |
@@ -1845,13 +1847,15 @@ messages
 }));
 messages
     .command("check")
-    .description("Grade a DRAFT text or email before sending (POST /messages/check): the same check the contact composers run as the rep types. Prints the route's data (the standard envelope is unwrapped): { score 0-100, grade A-F, verdict, vclass, hits, subjectHits, checks, sms (a text's chars / segments / unicode / perSeg; null for an email), context, notices (when present), engine { version, updatedAt } }. Each hit: { start, end, word, level (r likely blocked, a risky, y caution, n heads up), label, cat, why, alts (safer wording; some are advice rather than a swap), restricted (prohibited in US business texting: no rewording makes it deliverable), rule }. start / end are Unicode CODE-POINT offsets into the submitted text (the body for hits, the subject for subjectHits), end exclusive; an emoji counts as one, so [...text].slice(start, end) in JavaScript or text[start:end] in Python is the word (not a UTF-16 index). The check EDUCATES and never blocks: nothing is stored and nothing is sent; merge tokens such as {{contact.firstName}} are never flagged. --context template (default) grades a reusable message, first the first text to a contact, conversation a reply in an existing thread (the next engine release skips the opt-out and business-name checks for first / conversation; today every context scores the same); `contacts get <id>` carries hasOutboundSms to choose. Limits: body 10,000 characters, subject 300, request 48 KB; 20 checks per minute per account. Every refusal exits 1 with the status, the API's message and its code, sent once and never retried: 400 invalid_body, 403 forbidden (the key's member may view neither contacts nor email templates, or the key's scopes do not reach the route: needs the contacts, emails, sms or messages scope, a read-tier key too), 413 message_too_long / body_too_large, 429 rate_limited (Retry-After shown in the error text)")
+    .description("Grade a DRAFT text or email before sending (POST /messages/check): the same check the contact composers run as the rep types. Prints the route's data (the standard envelope is unwrapped): { score 0-100, grade A-F, verdict, vclass, hits, subjectHits, checks, sms (a text's chars / segments / unicode / perSeg; null for an email), context, notices (SMS; informational), breakdown (the score's bands, offsets in code points), unicodeCulprits (SMS; the characters that force Unicode), cleaned (only with --clean), engine { version, updatedAt } } (engine 2.1.2 today; any further field is additive). Each hit: { start, end, word, level (r likely blocked, a risky, y caution, n heads up), label, cat, why, alts (safer wording; some are advice rather than a swap), restricted (prohibited in US business texting: no rewording makes it deliverable), rule }. start / end are Unicode CODE-POINT offsets into the submitted text (the body for hits, the subject for subjectHits), end exclusive; an emoji counts as one, so [...text].slice(start, end) in JavaScript or text[start:end] in Python is the word (not a UTF-16 index). The check EDUCATES and never blocks: nothing is stored and nothing is sent; merge tokens such as {{contact.firstName}} are never flagged. --context template (default) grades a reusable message, first the first text to a contact, conversation a reply in an existing thread (the next engine release skips the opt-out and business-name checks for first / conversation; today every context scores the same); `contacts get <id>` carries hasOutboundSms to choose. --provider twilio (a text only) words the notices in Twilio's own wording, as the composers show them; an email with a provider, or any other value, is a 400 invalid_body (`sms providers options` lists the workspace's providers; only twilio is a check wording today). --clean adds `cleaned` { text, subject (email), changes, skipped } or null: the cleaner's PROPOSAL, never stored or applied. Limits: body 10,000 characters, subject 300, request 48 KB; 20 checks per minute per account. Every refusal exits 1 with the status, the API's message and its code, sent once and never retried: 400 invalid_body, 403 forbidden (the key's member may view neither contacts nor email templates, or the key's scopes do not reach the route: needs the contacts, emails, sms or messages scope, a read-tier key too), 413 message_too_long / body_too_large, 429 rate_limited (Retry-After shown in the error text)")
     .option("--channel <channel>", "sms | email (required)")
     .option("--subject <text>", "email only (300 characters at most); refused on a text")
     .option("--body <text>", "the draft text (10,000 characters at most)")
     .option("--body-file <path>", "read the draft text from a file (for long text; not with --body)")
     .option("--context <context>", "template (default) | first | conversation")
-    .option("--json <json>", "full JSON body { channel, subject?, body, context? }, merged over the flags")
+    .option("--provider <provider>", "twilio (a text only): word the notices in Twilio's wording; an email with a provider is a 400")
+    .option("--clean", "add `cleaned`: the cleaner's proposal for the text (never stored or applied)")
+    .option("--json <json>", "full JSON body { channel, subject?, body, context?, provider?, clean? }, merged over the flags")
     .action(run(async (client, opts) => {
     if (opts.body !== undefined && opts.bodyFile !== undefined)
         throw new Error("Pass either --body or --body-file, not both.");
@@ -1874,6 +1878,10 @@ messages
     }
     if (opts.context !== undefined)
         body.context = opts.context;
+    if (opts.provider !== undefined)
+        body.provider = opts.provider;
+    if (opts.clean)
+        body.clean = true;
     if (opts.json !== undefined)
         Object.assign(body, jsonArg(opts.json, "--json"));
     if (body.channel === undefined)
@@ -1882,6 +1890,109 @@ messages
         throw new Error("The draft is required. Pass --body '<text>' or --body-file <path>.");
     return client.post("/api/v1/messages/check", body);
 }));
+// ---- email / SMS templates (pasted-HTML email templates, #127, 2026-10-09) ----
+const templates = program.command("templates").description("Email and SMS templates (API key scope emails / templates; a member: email_templates.view / create / edit). Email templates are built in blocks or pasted as HTML (`--body-mode html --html-file page.html`)");
+const TEMPLATE_REFUSALS = "Every refusal exits 1 with the status, the API's message and its code, sent once and never retried: 400 invalid_body_mode (--body-mode is not blocks / html), html_without_html_mode (html needs --body-mode html), html_required (html mode with no html), html_too_large (html over 102,400 bytes), html_script (a <script> in the html), html_conditional_comment (an Outlook <!--[if ...]--> conditional comment), html_office_markup (Word / Office markup), html_duplicate_attribute (an element repeating an attribute), template_corrupt (an unreadable or doubled builder marker in bodyHtml), body_html_required (blocks mode with no --body-html), body_mode_conflict, template_meta_conflict";
+function templateBodyFlags(cmd) {
+    return cmd
+        .option("--subject <text>", "email subject line")
+        .option("--body <text>", "template body (plain text for SMS, text/HTML for email)")
+        .option("--body-file <path>", "read the body from a file (not with --body)")
+        .option("--body-html <html>", "email HTML body (sanitized server-side); with --body-mode blocks it is the builder's HTML")
+        .option("--body-mode <mode>", "blocks (default) | html (pasted HTML, email only; send --html or --html-file)")
+        .option("--html <html>", "the pasted email HTML (with --body-mode html; 102,400 bytes at most)")
+        .option("--html-file <path>", "read the pasted email HTML from a file (not with --html)")
+        .option("--category <category>", "category")
+        .option("--json <json>", "full JSON body, merged over the flags");
+}
+function readTextFile(path, flag) {
+    if (path.trim() === "")
+        throw new Error(`${flag} must be a path (got an empty string).`);
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        throw new Error(`${flag} could not be read: ${path}`);
+    }
+}
+/** the fields a template create / update sends: only what was given, nothing checked locally beyond the file reads (the API refuses with its codes) */
+function templateBody(opts) {
+    if (opts.body !== undefined && opts.bodyFile !== undefined)
+        throw new Error("Pass either --body or --body-file, not both.");
+    if (opts.html !== undefined && opts.htmlFile !== undefined)
+        throw new Error("Pass either --html or --html-file, not both.");
+    const body = {};
+    if (opts.subject !== undefined)
+        body.subject = opts.subject;
+    if (opts.body !== undefined)
+        body.body = opts.body;
+    if (opts.bodyFile !== undefined)
+        body.body = readTextFile(opts.bodyFile, "--body-file");
+    if (opts.bodyHtml !== undefined)
+        body.bodyHtml = opts.bodyHtml;
+    if (opts.bodyMode !== undefined)
+        body.bodyMode = opts.bodyMode;
+    if (opts.html !== undefined)
+        body.html = opts.html;
+    if (opts.htmlFile !== undefined)
+        body.html = readTextFile(opts.htmlFile, "--html-file");
+    if (opts.category !== undefined)
+        body.category = opts.category;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return body;
+}
+templates
+    .command("list")
+    .description("List email and SMS templates (GET /emails/templates). Each row carries `bodyMode` (blocks = built in the block builder, html = pasted HTML); the pasted `html` itself is NOT repeated in a list row (read it with `templates get`). Prints { data, meta }")
+    .option("--channel <channel>", "sms | email")
+    .option("--category <category>", "category")
+    .option("--active <bool>", "true | false")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page, default 50, max 200)")
+    .action(run(async (client, opts) => ({
+    data: await client.get(`/api/v1/emails/templates${buildQuery({ channel: opts.channel, category: opts.category, is_active: opts.active === undefined ? undefined : String(boolFlag(opts.active, "--active")), page: opts.page, per_page: opts.limit })}`),
+})));
+templates
+    .command("get <id>")
+    .description("Get one template with its full content (GET /emails/templates/{id}). An HTML-mode email template (`bodyMode: html`) answers its pasted source in `html`")
+    .action(run(async (client, id) => { assertUuid(id, "template id"); return client.get(`/api/v1/emails/templates/${encodeURIComponent(id.trim())}`); }));
+templateBodyFlags(templates
+    .command("create")
+    .description(`Create an email or SMS template (POST /emails/templates). Two shapes: BLOCKS (default; --body required, an email may add --body-html; --body-mode blocks REQUIRES --body-html) or PASTED HTML (email only: --body-mode html with --html / --html-file, 102,400 bytes at most; --body is then optional, the plain-text part defaults to the HTML's visible text). ${TEMPLATE_REFUSALS}`)
+    .requiredOption("--name <name>", "template name")
+    .option("--channel <channel>", "sms | email (required)")
+    .option("--inactive", "create it inactive (default active)")).action(run(async (client, opts) => {
+    const body = { name: opts.name, ...templateBody(opts) };
+    if (opts.channel !== undefined)
+        body.channel = opts.channel;
+    if (opts.inactive)
+        body.isActive = false;
+    if (body.channel === undefined)
+        throw new Error("--channel is required (sms | email).");
+    return client.post("/api/v1/emails/templates", body);
+}));
+templateBodyFlags(templates
+    .command("update <id>")
+    .description(`Update a template (PATCH /emails/templates/{id}; a partial update: send only what changes). To change a template's mode pass --body-mode (html with --html / --html-file, or blocks with --body-html); a stored HTML-mode template stays in HTML mode when only --body-html is sent, and switching back to blocks keeps the pasted HTML. ${TEMPLATE_REFUSALS}`)
+    .option("--name <name>", "new name")
+    .option("--active <bool>", "true | false")).action(run(async (client, id, opts) => {
+    assertUuid(id, "template id");
+    const body = templateBody(opts);
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.active !== undefined)
+        body.isActive = boolFlag(opts.active, "--active");
+    if (Object.keys(body).length === 0)
+        throw new Error("Nothing to change: pass at least one of --name, --subject, --body, --body-html, --body-mode, --html, --category, --active or --json.");
+    return client.patch(`/api/v1/emails/templates/${encodeURIComponent(id.trim())}`, body);
+}));
+const sms = program.command("sms").description("SMS providers");
+const smsProviders = sms.command("providers").description("The workspace's SMS providers");
+smsProviders
+    .command("options")
+    .description("The workspace's active SMS providers, redacted (GET /sms-providers/template-options): [{ id, name, color }] ordered by name, EVERY active provider (builtin included) and nothing else: no webhook URL, headers, field mapping, counts or credential. Use an id or name to bind a template to a provider. Read-only; API key scope emails, sms, messages or settings, and a member who may view email templates (email_templates.view) or settings (settings.view). A 403 exits 1 with the API's message")
+    .action(run(async (client) => client.get("/api/v1/sms-providers/template-options")));
 messages
     .command("conversations")
     .description("List conversation threads")
@@ -2937,6 +3048,62 @@ 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 })));
+// ---- Calendly (app 10-09): connect is browser-only (OAuth 2.0 + PKCE), so there is no `connect` here ----
+const calendly = integrations
+    .command("calendly")
+    .description("Calendly: a user's own connection syncs the chosen event types as appointments (API key scope integrations; the writes need a write or admin tier key and calendar.edit). Connecting is browser-only (OAuth 2.0 + PKCE): the user opens {app}/api/v1/integrations/calendly/oauth/install while signed in (Settings > Integrations > Calendly); API keys are refused there (scope integrations-oauth). Errors exit 1 with the server's message (404 not connected, 409 revoked: reconnect in the browser, 502 Calendly refused)");
+calendly
+    .command("status")
+    .description("The Calendly connection (GET /integrations/calendly/status): { configured, description, importLine, connected, connection (the key's member's own, or null), connections (an owner / admin key: every user's) }. A connection: id, userId, status, calendlyEmail, calendlyName, eventTypes, selectedEventTypeUris, selectionSaved (nothing syncs before a selection is saved), liveSync (on | pending | plan_refused with planWarning: the Calendly plan has no webhooks, so only the import runs), import { status (idle | queued | running | done | failed), eventsSeen, imported, skipped, startedAt, finishedAt, error }, lastBookingAt, lastError, lastErrorAt, createdAt. Tokens are never returned")
+    .action(run(async (client) => client.get("/api/v1/integrations/calendly/status")));
+calendly
+    .command("import-progress")
+    .description("The Calendly import's progress: prints the selected connection UNCHANGED, as the status route answers it (id, userId, status, calendlyEmail, calendlyName, eventTypes, selectedEventTypeUris, selectionSaved, liveSync, planWarning, import { status, eventsSeen, imported, skipped, startedAt, finishedAt, error }, lastBookingAt, lastError, lastErrorAt, createdAt). import.status is idle | queued | running | done | failed: poll until it is done or failed (import.error says why); idle = no selection saved yet. The import (upcoming events and the last 180 days, silent: no automations) starts with the first selection and when a selection adds a type. Without --connection-id: your own connection; with none connected, or an id that is not in the list the status route returns, it exits 1. The whole status answer is validated first: a malformed one exits 1 and prints nothing")
+    .option("--connection-id <id>", "an owner / admin may name another user's connection (from `status`)")
+    .action(run(async (client, opts) => {
+    if (opts.connectionId !== undefined)
+        assertUuid(opts.connectionId, "--connection-id");
+    const status = calendlyStatus(await client.get("/api/v1/integrations/calendly/status"));
+    const pool = [...(status.connection ? [status.connection] : []), ...(status.connections ?? [])];
+    const want = opts.connectionId?.trim().toLowerCase();
+    const conn = want ? pool.find((c) => String(c.id).toLowerCase() === want) : status.connection;
+    if (!conn)
+        throw new Error(want ? `No Calendly connection with id ${opts.connectionId} is visible to this key (see \`integrations calendly status\`).` : "Calendly is not connected for this key's member (connect in the browser; see `integrations calendly --help`).");
+    return { data: conn };
+}));
+calendly
+    .command("event-types")
+    .description("Re-read the user's event types from Calendly and show the connection (GET /integrations/calendly/event-types): the fresh eventTypes (the picker's list) and selectedEventTypeUris. Pick URIs from it for `set-event-types`")
+    .option("--connection-id <id>", "an owner / admin may name another user's connection")
+    .action(run(async (client, opts) => {
+    if (opts.connectionId !== undefined)
+        assertUuid(opts.connectionId, "--connection-id");
+    return client.get(`/api/v1/integrations/calendly/event-types${buildQuery({ connectionId: opts.connectionId?.trim() })}`);
+}));
+calendly
+    .command("set-event-types")
+    .description("Choose the Calendly event types that sync (PATCH /integrations/calendly/event-types { eventTypeUris, connectionId? }). ONLY these sync: a booking on any other type is ignored. Repeat --uri for each (https://api.calendly.com/event_types/<id>, at most 200, each one of the user's event types: `event-types` lists them); the list REPLACES the selection. --none stops syncing without disconnecting. The first save, or a save that adds a type, starts the import (upcoming events and the last 180 days, silently: no automations); follow it with `import-progress`. Prints { importQueued, connection }. Needs active billing")
+    .option("--uri <uri>", "a Calendly event type URI to sync (repeat for each)", (v, prev = []) => [...prev, v])
+    .option("--none", "an EMPTY selection: stop syncing without disconnecting")
+    .option("--connection-id <id>", "an owner / admin may name another user's connection")
+    .action(run(async (client, opts) => {
+    if (opts.none && opts.uri?.length)
+        throw new Error("Pass either --uri (one or more) or --none, not both.");
+    if (!opts.none && !opts.uri?.length)
+        throw new Error("Pass --uri <event type URI> (repeat for each), or --none to stop syncing.");
+    if (opts.connectionId !== undefined)
+        assertUuid(opts.connectionId, "--connection-id");
+    return client.patch("/api/v1/integrations/calendly/event-types", { eventTypeUris: opts.none ? [] : opts.uri, ...(opts.connectionId !== undefined ? { connectionId: opts.connectionId.trim() } : {}) });
+}));
+calendly
+    .command("disconnect")
+    .description("DISCONNECT Calendly (POST /integrations/calendly/disconnect { connectionId? }): removes the Calendly webhook subscription and the connection; it stops taking bookings at once. Appointments already in Conduyt stay. Reconnecting is a browser flow. Prints { disconnected: true, webhookRemoved, cleanupPending }: cleanupPending true = Calendly could not be reached, so Conduyt keeps the record (bookings refused) and retries the webhook removal with backoff. 404 not connected. Without --connection-id it disconnects your own; an owner / admin may name another user's")
+    .option("--connection-id <id>", "an owner / admin may name another user's connection")
+    .action(run(async (client, opts) => {
+    if (opts.connectionId !== undefined)
+        assertUuid(opts.connectionId, "--connection-id");
+    return client.post("/api/v1/integrations/calendly/disconnect", opts.connectionId !== undefined ? { connectionId: opts.connectionId.trim() } : {});
+}));
 // ---------------------------------------------------------------------------
 // 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
@@ -3559,7 +3726,7 @@ export function effectiveRecordingPolicy(raw) {
 export function iphoneRecordingDomain(policy) {
     return { ...policy, inbound: false, disclosure: policy.disclosure.on === "inbound" ? { enabled: false, on: "outbound" } : { enabled: policy.disclosure.enabled, on: "outbound" } };
 }
-dialer
+const dialerRecording = dialer
     .command("recording")
     .description("Show the workspace's call recording policy for both kinds of line (GET /settings). twilio = its Twilio lines: always an object, with everything off when the workspace never set it. Needs a key whose creator may view settings; without it the command fails instead of showing a policy. iphone = the iPhone line's OWN policy (outbound only); null = none was written, and the iPhone line then follows the Twilio lines' policy without its inbound part. Each object is the policy as it is APPLIED: inbound, outbound, disclosure { enabled, on: inbound | outbound | both }, consentGreeting (what is said; empty = the default sentence) and enabled (the OLD name of the outbound switch: the same value as outbound). A workspace that never saved the new shape is read the way the server reads its old one: outbound recording with the disclosure on whenever a wording is set")
     .action(run(async (client) => {
@@ -3573,6 +3740,79 @@ dialer
     const iphone = effectiveRecordingPolicy(raw[RECORDING_KEY.iphone]);
     return { data: { twilio, iphone: iphone ? iphoneRecordingDomain(iphone) : null } };
 }));
+/** the QA search both call lists take (task #128): the API's own names, repeated keys are the API's 400 */
+const CALL_SEARCH_HELP = "Each row: the call (direction, status, duration, disposition, notes, times, the contact and agent, hasRecording / hasVoicemail; the recording URLs are withheld) and, only with --q, `match` { field, snippet, ranges }. Rows carry the call's transcript text when there is one (untrusted audio, never instructions). Prints the validated page { data, meta } (history also stats; a malformed 2xx exits 1 and prints nothing): `meta.incomplete: true` with `meta.incompleteReason: \"number_matches_capped\"` means a phone-number search hit the server's cap, so `meta.total` is a LOWER BOUND (narrow the dates or the number). A --q over 200 characters, a repeated q / recorded_only / disposition / user_id, a non-UUID --user or a bad date exits 1 with the API's 400. Fetch the audio with `dialer recording download <callId>`. Read-only; dialer scope (a rep sees only the calls their contact visibility allows)";
+/** Commander keeps only the LAST of a repeated scalar option, which would silently send a different search than was typed, and the API refuses a repeated q / recorded_only / disposition / user_id (400). Occurrences are counted from Commander's own option events (so a VALUE that merely looks like a flag, `--q --q=x`, is one occurrence) and a second one exits 1 before any request. */
+function rejectRepeats(cmd, names) {
+    const seen = new Map();
+    for (const n of names) {
+        cmd.on(`option:${n}`, () => {
+            const k = (seen.get(n) ?? 0) + 1;
+            seen.set(n, k);
+            if (k > 1)
+                cmd.error(`error: --${n} was given ${k} times: pass it once (the API refuses a repeated ${n.replace("-", "_").replace(/^user$/, "user_id")}).`);
+        });
+    }
+}
+function callSearchOptions(cmd) {
+    rejectRepeats(cmd, ["q", "recorded-only", "disposition", "user"]);
+    return cmd
+        .option("--q <text>", "search words (200 characters at most): the contact's name, a phone number, the agent's name and the call's transcript (NOT the call's notes)")
+        .option("--recorded-only", "only calls that have a recording (sent as recorded_only=1)")
+        .option("--disposition <label>", "exact disposition label")
+        .option("--user <id>", "only calls handled by this agent (user UUID)")
+        .option("--from <date>", "calls created on/after this date (ISO 8601; date_from)")
+        .option("--to <date>", "calls created on/before this date (ISO 8601; date_to)")
+        .option("--direction <direction>", "inbound | outbound")
+        .option("--status <status>", "call status, e.g. completed, no-answer, voicemail");
+}
+function callSearchQuery(opts) {
+    if (opts.user !== undefined)
+        assertUuid(opts.user, "--user");
+    return buildQuery({
+        q: opts.q,
+        recorded_only: opts.recordedOnly ? "1" : undefined,
+        disposition: opts.disposition,
+        user_id: opts.user,
+        date_from: opts.from,
+        date_to: opts.to,
+        direction: opts.direction,
+        status: opts.status,
+        mine: opts.mine ? "true" : undefined,
+        page: opts.page,
+        per_page: opts.limit,
+    });
+}
+callSearchOptions(dialer
+    .command("history")
+    .description(`Search and filter the dialer's call log for QA (GET /dialer/history, newest first, up to 200 per page): find the recorded calls to review by words, number, disposition, agent and dates. ${CALL_SEARCH_HELP}. Also prints stats { total, inbound, outbound, avgTalkSeconds } for the whole visible log`))
+    .option("--mine", "only the key's own member's calls")
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page, default 50, max 200)")
+    .action(run(async (client, opts) => ({ data: historyPage(await client.get(`/api/v1/dialer/history${callSearchQuery(opts)}`)) })));
+callSearchOptions(dialer
+    .command("calls")
+    .description(`The dialer's recordings / voicemail list with the same QA search and filters (GET /dialer/calls, newest first, up to 100 per page; --status voicemail lists the live voicemails only). ${CALL_SEARCH_HELP}`))
+    .option("--page <n>", "page number")
+    .option("--limit <n>", "results per page (per_page, default 30, max 100)")
+    .action(run(async (client, opts) => ({ data: callsPage(await client.get(`/api/v1/dialer/calls${callSearchQuery(opts)}`)) })));
+dialerRecording
+    .command("download <callId>")
+    .description("Download a call's audio to a file (GET /dialer/call/{id}/media?type=recording&download=1): the SAME authorisation and stream as playing it, streamed to disk. Saved as -o <file>, else under the name the API gives it (<Contact or number>_<date>_<time>_<callId8>.mp3) in the current folder; never over an existing file unless --force. --voicemail downloads the voicemail instead (type=voicemail). Prints { saved, bytes, contentType }. A call with no media is a 404, a call you may not see is a 404, an unusable media host is a 422 (exit 1 with the API's message; nothing is written)")
+    .option("--voicemail", "the voicemail instead of the recording")
+    .option("-o, --out <file>", "save to this file")
+    .option("--force", "overwrite an existing file")
+    .action(run(async (client, callId, opts) => {
+    assertUuid(callId, "call id");
+    if (opts.out !== undefined && opts.out.trim() === "")
+        throw new Error("-o must be a file path (got an empty string).");
+    const id = callId.trim();
+    return client.download(`/api/v1/dialer/call/${encodeURIComponent(id)}/media${buildQuery({ type: opts.voicemail ? "voicemail" : "recording", download: "1" })}`, {
+        outFile: opts.out ?? null,
+        fallbackName: `${id.slice(0, 8)}.mp3`,
+        overwrite: Boolean(opts.force),
+    });
+}));
 dialer
     .command("set-recording")
     .description("Change the workspace's call recording policy (admin: settings scope). Send only what changes; the rest stays. The workspace is responsible for consent where it operates. Example: conduyt dialer set-recording --inbound on --outbound on --disclosure on --disclosure-on inbound")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "conduyt",
-  "version": "1.67.0",
+  "version": "1.68.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",