conduyt 1.68.0 → 1.70.0

package/README.md

@@ -79,6 +79,8 @@ conduyt whatsapp templates              # approved / pending / rejected template
 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] [--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 messages minimum-grade   # the admin's Message check minimum grade to send (settings.messageCheck.minimumGrade): enabled, sms / email minimum (A-F, 0-100 or null), adminOverride; groundwork, stored but not enforced yet; owner / admin only (anyone else sees visible: false)
+conduyt messages set-minimum-grade [--sms A|B|C|D|F|0-100|none] [--email ...] [--admin-override on|off] [--enabled on|off]   # sends the whole block with the settings revision it read; --enabled on is refused 400 minimum_grade_not_available_yet; 403 forbidden for a non-owner / non-admin; all 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`)
@@ -129,6 +131,8 @@ out and named in `_omitted`. Every HTTP refusal takes this path (JSON calls, tex
 Error: Conduyt API 503: Contact merge in progress [Retry-After: 5s] {"code":"merge_in_progress"}
 ```
 
+The contact merge route (`POST /contacts/merge`, no command today) answers a retryable 503 with `Retry-After` and the code `merge_contacts_busy` (a contact stayed busy for the whole lock budget) or `merge_budget_exhausted` (the request's time budget ran out), nothing changed. A command that reaches it prints the refusal in this grammar, exits 1 and does not retry; run it again after the stated seconds.
+
 ## License
 
 MIT

package/dist/client.js

@@ -83,6 +83,58 @@ export function renderErrorDetails(body) {
         out._omitted = omitted;
     return JSON.stringify(out);
 }
+const RA_MAX_SECONDS = 2_147_483_647; // delay-seconds is unbounded 1*DIGIT: a longer value saturates here instead of becoming null
+const RA_MONTHS = { Jan: 0, Feb: 1, Mar: 2, Apr: 3, May: 4, Jun: 5, Jul: 6, Aug: 7, Sep: 8, Oct: 9, Nov: 10, Dec: 11 };
+const RA_MON = "Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec";
+const RA_IMF = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), (\\d{2}) (${RA_MON}) (\\d{4}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+const RA_850 = new RegExp(`^(?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday), (\\d{2})-(${RA_MON})-(\\d{2}) (\\d{2}):(\\d{2}):(\\d{2}) GMT$`);
+const RA_ASC = new RegExp(`^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun) (${RA_MON}) ([ \\d]\\d) (\\d{2}):(\\d{2}):(\\d{2}) (\\d{4})$`);
+/** A UTC timestamp for the parts, or NaN when any part is out of range (31 Feb, 25:00, ...). */
+function raUtc(y, mo, d, h, mi, s) {
+    if (y < 1900 || h > 23 || mi > 59 || s > 60)
+        return NaN; // RFC 5322: years below 1900 are not dates
+    const t = Date.UTC(y, mo, d, h, mi, Math.min(s, 59));
+    const back = new Date(t);
+    return back.getUTCFullYear() === y && back.getUTCMonth() === mo && back.getUTCDate() === d ? t : NaN;
+}
+/**
+ * The ONE Retry-After parser. RFC 9110: delay-seconds (digits; a value too long for a number saturates at 2^31-1) or an
+ * HTTP-date in one of the three §5.6.7 forms, parsed explicitly and always as UTC (never the host timezone): IMF-fixdate,
+ * RFC 850 (two-digit year: more than 50 years ahead of `nowMs` means the previous century) and asctime. A date becomes the
+ * remaining seconds, floored at 0. Absent, blank or anything else (ISO timestamps, other zones, "-3") is null.
+ */
+export function parseRetryAfter(raw, nowMs = Date.now()) {
+    if (raw === null || raw === undefined)
+        return null;
+    const v = raw.trim();
+    if (v === "")
+        return null;
+    if (/^\d+(\.\d+)?$/.test(v)) {
+        const n = Number(v);
+        return Number.isNaN(n) ? null : Math.min(n, RA_MAX_SECONDS);
+    }
+    let t = NaN;
+    let m;
+    if ((m = RA_IMF.exec(v)))
+        t = raUtc(Number(m[3]), RA_MONTHS[m[2]], Number(m[1]), Number(m[4]), Number(m[5]), Number(m[6]));
+    else if ((m = RA_850.exec(v))) {
+        const century = Math.floor(new Date(nowMs).getUTCFullYear() / 100) * 100;
+        const mo = RA_MONTHS[m[2]], d = Number(m[1]), h = Number(m[4]), mi = Number(m[5]), sec = Number(m[6]);
+        t = raUtc(century + Number(m[3]), mo, d, h, mi, sec);
+        // RFC 9110: a timestamp more than 50 years in the future (the same instant 50 calendar years on, UTC) is the previous century
+        // (the day is clamped to the month's last day: 29 Feb + 50 years is 28 Feb, never 1 Mar)
+        const n = new Date(nowMs);
+        const ly = n.getUTCFullYear() + 50, lm = n.getUTCMonth();
+        const limit = Date.UTC(ly, lm, Math.min(n.getUTCDate(), new Date(Date.UTC(ly, lm + 1, 0)).getUTCDate()), n.getUTCHours(), n.getUTCMinutes(), n.getUTCSeconds(), n.getUTCMilliseconds());
+        if (!Number.isNaN(t) && t > limit)
+            t = raUtc(century - 100 + Number(m[3]), mo, d, h, mi, sec);
+    }
+    else if ((m = RA_ASC.exec(v)))
+        t = raUtc(Number(m[6]), RA_MONTHS[m[1]], Number(m[2].trim()), Number(m[3]), Number(m[4]), Number(m[5]));
+    if (Number.isNaN(t))
+        return null;
+    return Math.max(0, Math.ceil((t - nowMs) / 1000));
+}
 /**
  * The ONE place an HTTP refusal becomes an Error (request, postText and stream all use it). Grammar (stable):
  * `Conduyt API <status>: <message>[ [Retry-After: <N>s]][ <details>]`; <details> is ONE JSON object and the FINAL token
@@ -90,9 +142,8 @@ export function renderErrorDetails(body) {
  */
 export function formatHttpError(res, text) {
     const json = text ? safeParse(text) : null;
-    const ra = res.headers.get("retry-after");
-    const raN = ra === null || ra.trim() === "" ? NaN : Number(ra);
-    const raTag = Number.isFinite(raN) && raN >= 0 ? ` [Retry-After: ${raN}s]` : "";
+    const raN = parseRetryAfter(res.headers.get("retry-after"));
+    const raTag = raN !== null ? ` [Retry-After: ${raN}s]` : "";
     const obj = json && typeof json === "object" && !Array.isArray(json) ? json : null;
     if (obj && typeof obj.error === "string" && obj.error) {
         const extras = renderErrorDetails(obj);

package/dist/index.js

@@ -3,8 +3,9 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { addPoolFilterSet, listPoolFilterSets, removePoolFilterSet, updatePoolFilterSet } from "./pool-filter-sets.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
+import { minimumGradeOf, minimumGradePatch, parseGradeFlag } from "./message-check-minimum.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";
@@ -41,7 +42,11 @@ const program = new Command();
 program
     .name("conduyt")
     .description("Command-line interface for Conduyt CRM — manage contacts, deals, pipelines, and run insight queries from your terminal.")
-    .version(readVersion());
+    .version(readVersion())
+    // Commander ends --help / --version / usage errors with process.exit() right after writing, and a piped stdout is not drained by
+    // then (`conduyt messages set-minimum-grade --help | cat` was cut at exactly 512 bytes). exitOverride is set BEFORE any subcommand
+    // is defined, so every command inherits it; main() below drains both streams and only then exits with Commander's own exit code.
+    .exitOverride();
 // ---- config ----
 const config = program.command("config").description("Manage CLI configuration");
 config
@@ -85,7 +90,7 @@ contacts
     .action(run(async (client, id) => client.get(`/api/v1/contacts/${encodeURIComponent(id)}`)));
 contacts
     .command("create")
-    .description("Create a contact")
+    .description("Create a contact. An impossible US/Canada number (area code or exchange starting 0 or 1) is refused 400 phone_invalid and nothing is saved; the refusal exits 1 with the status, message and code, sent once")
     .option("--first <name>", "first name")
     .option("--last <name>", "last name")
     .option("--email <email>", "email")
@@ -130,7 +135,7 @@ contacts
 }));
 contacts
     .command("update <id>")
-    .description("Update a contact (PATCH — only the fields you pass change)")
+    .description("Update a contact (PATCH — only the fields you pass change). An impossible US/Canada number (area code or exchange starting 0 or 1) is refused 400 phone_invalid; a country is never null or blank (400 country_invalid, via --json); each refusal exits 1 with the status, message and code, sent once")
     .option("--first <name>", "first name")
     .option("--last <name>", "last name")
     .option("--email <email>", "email")
@@ -1890,6 +1895,36 @@ messages
         throw new Error("The draft is required. Pass --body '<text>' or --body-file <path>.");
     return client.post("/api/v1/messages/check", body);
 }));
+const MINIMUM_GRADE_NOTE = "Groundwork only: the minimum is stored and read back but NOT enforced yet (Send stays enabled for everyone), and --enabled on is refused 400 minimum_grade_not_available_yet until the feature is switched on.";
+messages
+    .command("minimum-grade")
+    .description(`Show the admin's Message check minimum grade to send (GET /settings, settings.messageCheck.minimumGrade). Prints { minimumGrade: { enabled, channel: { sms, email }, adminOverride } | null, visible } (the standard envelope is unwrapped). enabled is the master switch (default off); channel.sms / channel.email the lowest acceptable result for that channel (a letter A-F, a score 0-100 or null = no minimum); adminOverride whether an owner or admin may send below it (default on). ${MINIMUM_GRADE_NOTE} Owner / admin only: for any other member the API leaves the block out, so minimumGrade is null and visible false (a redaction, not an unset minimum). Needs the settings scope.`)
+    .action(run(async (client) => {
+    const result = (await client.get("/api/v1/settings"));
+    const block = minimumGradeOf(result?.data);
+    return { data: { minimumGrade: block, visible: block !== null } };
+}));
+messages
+    .command("set-minimum-grade")
+    .description(`Change the Message check minimum grade to send (PATCH /settings). Pass only what changes: --sms / --email <A-F|0-100|none> (a letter, a whole score, or none for no minimum; E, fractions and scores over 100 are refused), --admin-override on|off, --enabled on|off. Sends the WHOLE block (the API replaces it) with the settings revision it read; a 409 re-reads once, then exits 1 with the current settings. ${MINIMUM_GRADE_NOTE} Owner / admin only. Every refusal exits 1 with the status, the API's message and its code, sent once and never retried: 403 forbidden ("Only an owner or admin can change the Message check minimum grade"), 400 minimum_grade_not_available_yet, 422 invalid_body. No new scope: the settings scope, settings:edit and the owner or admin role.`)
+    .option("--sms <grade>", "SMS minimum: A, B, C, D, F, a score 0-100, or none")
+    .option("--email <grade>", "email minimum: A, B, C, D, F, a score 0-100, or none")
+    .option("--admin-override <on|off>", "whether an owner or admin may send below the minimum (default on)")
+    .option("--enabled <on|off>", "master switch; on is refused 400 minimum_grade_not_available_yet until the feature is switched on")
+    .action(run(async (client, opts) => {
+    const change = {};
+    if (opts.sms !== undefined)
+        change.sms = parseGradeFlag(opts.sms, "--sms");
+    if (opts.email !== undefined)
+        change.email = parseGradeFlag(opts.email, "--email");
+    if (opts.adminOverride !== undefined)
+        change.adminOverride = onOffArg(opts.adminOverride, "--admin-override");
+    if (opts.enabled !== undefined)
+        change.enabled = onOffArg(opts.enabled, "--enabled");
+    if (Object.keys(change).length === 0)
+        throw new Error("nothing to change: pass at least one of --sms, --email, --admin-override, --enabled");
+    return patchGeneralSettingsMerged(client, (settings) => minimumGradePatch(settings, change));
+}));
 // ---- 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";
@@ -5296,7 +5331,16 @@ smartViews
         assertUuid(id, "smart view id");
     return client.patch("/api/v1/smart-views/reorder", { order: ids });
 }));
-program.parseAsync(process.argv).catch(fail);
+/** end the process only after stdout and stderr have flushed (a pipe is not drained at process.exit) */
+function exitAfterFlush(code) {
+    process.stdout.write("", () => process.stderr.write("", () => process.exit(code)));
+}
+program.parseAsync(process.argv).catch((err) => {
+    // help, version and usage errors: Commander already printed them; keep its exit code, but drain first
+    if (err instanceof CommanderError)
+        return exitAfterFlush(err.exitCode);
+    fail(err);
+});
 // helpers
 // Parse a --json / --stages style argument, throwing a clear CLI error (caught
 // by run() -> non-zero exit) rather than a stack trace on bad JSON.

package/dist/message-check-minimum.js

@@ -0,0 +1,43 @@
+/**
+ * Message check minimum grade, #134 groundwork (app 10-10, LIVE 9:19 AM): settings.messageCheck.minimumGrade, the admin's lowest
+ * acceptable Message check result per channel. Stored and read back, enforced nowhere yet; `enabled: true` is refused 400
+ * minimum_grade_not_available_yet. Owner / admin only: GET /settings leaves the block out for anyone else and PATCH answers 403.
+ * The validators mirror the API's messageCheckSettingsSchema (strict, whole block).
+ */
+export const GRADE_LETTERS = ["A", "B", "C", "D", "F"];
+export const DEFAULT_MINIMUM_GRADE = { enabled: false, channel: { sms: null, email: null }, adminOverride: true };
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** a letter A-F (any case), a whole score 0-100, or the literal "none" (null = no minimum); E, fractions and out-of-range scores are refused */
+export function parseGradeFlag(raw, flag) {
+    const v = raw.trim();
+    if (v.toLowerCase() === "none")
+        return null;
+    if (GRADE_LETTERS.includes(v.toUpperCase()))
+        return v.toUpperCase();
+    if (/^\d+$/.test(v) && Number(v) <= 100)
+        return Number(v);
+    throw new Error(`${flag} takes a letter A, B, C, D or F, a whole score 0-100, or none (got '${raw}').`);
+}
+/** the stored block with the defaults laid under it field by field; null when the API left the block out (the key's member is not an owner / admin) */
+export function minimumGradeOf(settings) {
+    const mc = settings?.messageCheck;
+    if (!isObj(mc))
+        return null;
+    const s = isObj(mc.minimumGrade) ? mc.minimumGrade : {};
+    const ch = isObj(s.channel) ? s.channel : {};
+    const val = (v) => (typeof v === "string" || typeof v === "number" ? v : null);
+    return { enabled: s.enabled === true, channel: { sms: val(ch.sms), email: val(ch.email) }, adminOverride: s.adminOverride === false ? false : true };
+}
+/** the PATCH body: the WHOLE block (the API replaces it) with only the given fields changed; a block the key cannot see gets the defaults laid under the change (the API then answers 403 forbidden) */
+export function minimumGradePatch(settings, change) {
+    const stored = minimumGradeOf(settings) ?? DEFAULT_MINIMUM_GRADE;
+    return {
+        messageCheck: {
+            minimumGrade: {
+                enabled: change.enabled ?? stored.enabled,
+                channel: { sms: change.sms === undefined ? stored.channel.sms : change.sms, email: change.email === undefined ? stored.channel.email : change.email },
+                adminOverride: change.adminOverride ?? stored.adminOverride,
+            },
+        },
+    };
+}

package/package.json

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