conduyt 1.0.0 → 1.2.0

package/dist/index.js

@@ -1,13 +1,29 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
 import { Command } from "commander";
 import { ConduytClient, buildQuery } from "./client.js";
 import { saveConfig, resolveConfig, configPath } from "./config.js";
 import { print, fail } from "./output.js";
+// Derive the version from package.json at runtime so `--version` can never
+// drift from the published package (dist/index.js -> ../package.json). Read at
+// top level runs on every invocation, so fall back gracefully rather than
+// crashing the whole CLI if the file is somehow unreadable.
+function readVersion() {
+    try {
+        const raw = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8");
+        return JSON.parse(raw).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 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("1.0.0");
+    .version(readVersion());
 // ---- config ----
 const config = program.command("config").description("Manage CLI configuration");
 config
@@ -47,20 +63,244 @@ contacts
     .command("get <id>")
     .description("Get a single contact by id")
     .action(run(async (client, id) => client.get(`/api/v1/contacts/${encodeURIComponent(id)}`)));
+contacts
+    .command("create")
+    .description("Create a contact")
+    .option("--first <name>", "first name")
+    .option("--last <name>", "last name")
+    .option("--email <email>", "email")
+    .option("--phone <phone>", "phone")
+    .option("--company <company>", "company name (auto-creates/links a company)")
+    .option("--json <json>", "full JSON body, merged over the flags above (for any field)")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.first !== undefined)
+        body.firstName = opts.first;
+    if (opts.last !== undefined)
+        body.lastName = opts.last;
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.phone !== undefined)
+        body.phone = opts.phone;
+    if (opts.company !== undefined)
+        body.company = opts.company;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/contacts", body);
+}));
 // ---- deals ----
 const deals = program.command("deals").description("Manage deals");
 deals
     .command("list")
     .description("List deals")
-    .option("--limit <n>", "max results")
-    .option("--cursor <cursor>", "pagination cursor")
-    .option("--pipeline <id>", "filter by pipeline id")
-    .action(run(async (client, opts) => client.get(`/api/v1/deals${buildQuery({ limit: opts.limit, cursor: opts.cursor, pipelineId: opts.pipeline })}`)));
+    .option("--all", "fetch ALL matching deals across every page — use this for totals/P&L")
+    .option("--limit <n>", "results per page, 1-1000 (default 50)")
+    .option("--page <n>", "fetch a specific page (an explicit partial page is allowed)")
+    .option("--pipeline <id>", "filter by pipeline UUID")
+    .option("--pipeline-name <name>", "filter by pipeline name (resolved server-side; errors if not found — never returns the whole account)")
+    .option("--stage <id>", "filter by stage UUID")
+    .option("--stage-name <name>", "filter by stage name (requires --pipeline or --pipeline-name)")
+    .action(run(async (client, opts) => {
+    // A provided-but-blank filter must error, not silently become "no filter":
+    // buildQuery drops empty strings, so a blank flag would never reach the
+    // server to be rejected and would return the whole account. On a CLI a
+    // blank flag is always a mistake (an empty $VAR) — there is no "All"
+    // selection to express, you just omit the flag — so guard ALL filter
+    // flags, ids included.
+    for (const [flag, val] of [
+        ["--pipeline", opts.pipeline],
+        ["--pipeline-name", opts.pipelineName],
+        ["--stage", opts.stage],
+        ["--stage-name", opts.stageName],
+    ]) {
+        if (val !== undefined && val.trim() === "") {
+            throw new Error(`${flag} was provided but is blank. Omit it to skip the filter, or pass a real value.`);
+        }
+    }
+    const MAX_PER_PAGE = 1000; // matches the server's per_page cap
+    const parsePos = (v, name) => {
+        if (v === undefined)
+            return undefined;
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 1) {
+            throw new Error(`${name} must be a positive integer.`);
+        }
+        return n;
+    };
+    const limitN = parsePos(opts.limit, "--limit");
+    if (limitN !== undefined && limitN > MAX_PER_PAGE) {
+        throw new Error(`--limit cannot exceed ${MAX_PER_PAGE}. Use --all to fetch every page.`);
+    }
+    const pageN = parsePos(opts.page, "--page");
+    if (opts.all && pageN !== undefined) {
+        throw new Error("Use either --all or --page, not both.");
+    }
+    // Each filter routes to the canonical wire param the live contract
+    // advertises (deals paginates by per_page/page, NOT limit/cursor). An
+    // unknown/blank/conflicting name 400s server-side and surfaces as a CLI
+    // error — never a silent whole-account list.
+    const filterQ = {
+        pipeline: opts.pipeline,
+        pipeline_name: opts.pipelineName,
+        stage: opts.stage,
+        stage_name: opts.stageName,
+    };
+    // --all: auto-page through EVERY page and PROVE completeness, so totals/P&L
+    // are computed on the whole, consistent set — otherwise FAIL CLOSED. We
+    // de-dup by deal id (page/offset pagination can repeat a row if data shifts),
+    // require the server total to stay stable across pages, and require the final
+    // unique count to equal that total. A non-terminating server (ignoring page)
+    // hits a hard error, never a silent truncated/duplicated success.
+    if (opts.all) {
+        // --all must return a CONSISTENT, COMPLETE set for totals/P&L. The deals
+        // API paginates by page/offset with no snapshot/cursor, so stitching
+        // multiple pages over live data can silently mix snapshots (a deal leaves
+        // the filter as another enters, total unchanged). To avoid ANY such
+        // inconsistency we fetch in ONE atomic max-size page and FAIL CLOSED if
+        // the result does not fit — never assembling a multi-page set. (≤1000
+        // deals — typical pipelines, incl. this workflow — fetch fine.)
+        if (limitN !== undefined) {
+            throw new Error("--all controls paging itself; do not combine it with --limit.");
+        }
+        const res = (await client.get(`/api/v1/deals${buildQuery({ ...filterQ, per_page: String(MAX_PER_PAGE), page: "1" })}`));
+        const rows = res?.data?.data;
+        const total = res?.data?.meta?.total;
+        if (!Array.isArray(rows)) {
+            throw new Error("--all: unexpected response (data.data is not an array). Aborting.");
+        }
+        if (typeof total !== "number" || !Number.isInteger(total) || total < 0) {
+            throw new Error("--all cannot verify completeness: the deals endpoint returned no numeric meta.total. " +
+                "Refusing to emit a possibly-partial set.");
+        }
+        if (total > MAX_PER_PAGE) {
+            throw new Error(`--all: this filter matches ${total} deals — more than the ${MAX_PER_PAGE} that fit in one ` +
+                "consistent page. The deals API has no snapshot/cursor pagination, so a multi-page total " +
+                "could be inconsistent. Narrow the filter (e.g. --stage-name) or fetch specific --page ranges.");
+        }
+        // Validate ids; a REPEATED id means an internally-inconsistent response
+        // (two rows for one deal, possibly with conflicting amounts) — fail rather
+        // than let a Map overwrite hide it. Require row count AND unique count to
+        // both equal the total, so nothing is duplicated, dropped, or arbitrary.
+        const byId = new Map();
+        for (const d of rows) {
+            const id = d?.id;
+            if (typeof id !== "string" || id.trim() === "") {
+                throw new Error("--all: a deal row has a missing/invalid id — cannot de-duplicate safely. Aborting.");
+            }
+            if (byId.has(id)) {
+                throw new Error(`--all: the response contains a duplicate deal id (${id}) — inconsistent. Aborting.`);
+            }
+            byId.set(id, d);
+        }
+        if (rows.length !== total || byId.size !== total) {
+            throw new Error(`--all: page returned ${rows.length} rows (${byId.size} unique) but total=${total} — inconsistent. ` +
+                "Aborting — a partial or duplicated set would produce wrong totals/P&L.");
+        }
+        return { data: { data: [...byId.values()], meta: { total, fetched: byId.size } } };
+    }
+    // Single page.
+    const res = (await client.get(`/api/v1/deals${buildQuery({ ...filterQ, per_page: opts.limit, page: opts.page })}`));
+    const rows = res?.data?.data;
+    const total = res?.data?.meta?.total;
+    // HARD-FAIL on IMPLICIT truncation: if the caller did NOT request a specific
+    // page and this page is incomplete, exit non-zero instead of emitting a
+    // partial list that a script (piping stdout to jq, ignoring stderr) could
+    // compute a wrong P&L from. An explicit --page is an intentional partial.
+    if (pageN === undefined &&
+        Array.isArray(rows) &&
+        typeof total === "number" &&
+        rows.length < total) {
+        throw new Error(`Result truncated: page 1 has ${rows.length} of ${total} deals. ` +
+            `Use --all to fetch every deal (required for correct totals/P&L), ` +
+            `or --page <n> for a specific page.`);
+    }
+    return res;
+}));
+deals
+    .command("create")
+    .description("Create a deal (use `pipelines list` to get pipeline/stage ids)")
+    .option("--title <title>", "deal title")
+    .option("--pipeline <id>", "pipeline UUID")
+    .option("--stage <id>", "stage UUID")
+    .option("--value <n>", "deal value (number)")
+    .option("--currency <code>", "ISO currency, e.g. GBP")
+    .option("--contact <id>", "contact UUID to link")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.title !== undefined)
+        body.title = opts.title;
+    if (opts.pipeline !== undefined)
+        body.pipelineId = opts.pipeline;
+    if (opts.stage !== undefined)
+        body.stageId = opts.stage;
+    if (opts.value !== undefined) {
+        const trimmed = opts.value.trim();
+        const n = Number(trimmed);
+        // Reject blank/whitespace (Number("") is 0) and non-finite values
+        // (Infinity/overflow JSON-serialize to null) so we never POST a wrong
+        // monetary amount instead of failing.
+        if (trimmed === "" || !Number.isFinite(n)) {
+            throw new Error("--value must be a finite number.");
+        }
+        body.value = n;
+    }
+    if (opts.currency !== undefined)
+        body.currency = opts.currency;
+    if (opts.contact !== undefined)
+        body.contactId = opts.contact;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    assertFiniteValue(body.value);
+    return client.post("/api/v1/deals", body);
+}));
 // ---- pipelines ----
-program
+// Default action preserves the original published `conduyt pipelines` (list)
+// invocation now that pipelines is a group — without it, commander prints help
+// instead of listing and breaks existing users/scripts. `pipelines list` is an
+// explicit alias for the same GET.
+const pipelines = program
     .command("pipelines")
+    .description("Manage pipelines")
+    .action(run(async (client) => client.get("/api/v1/pipelines")));
+pipelines
+    .command("list")
     .description("List pipelines and their stages")
     .action(run(async (client) => client.get("/api/v1/pipelines")));
+pipelines
+    .command("create")
+    .description("Create a pipeline with stages")
+    .option("--name <name>", "pipeline name")
+    .option("--stages <json>", "JSON array of stages, e.g. '[{\"name\":\"Lead\"},{\"name\":\"Won\",\"isWon\":true}]'")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.name !== undefined)
+        body.name = opts.name;
+    if (opts.stages !== undefined) {
+        if (opts.stages.trim() === "")
+            throw new Error("--stages must be valid JSON (got an empty string).");
+        let st;
+        try {
+            st = JSON.parse(opts.stages);
+        }
+        catch {
+            throw new Error("--stages must be valid JSON.");
+        }
+        if (!Array.isArray(st))
+            throw new Error("--stages must be a JSON array of stage objects.");
+        if (st.length === 0)
+            throw new Error("--stages must be a non-empty array of stage objects.");
+        if (st.some((s) => s === null || typeof s !== "object" || Array.isArray(s))) {
+            throw new Error("--stages must be an array of stage objects, e.g. '[{\"name\":\"Lead\"},{\"name\":\"Won\",\"isWon\":true}]'.");
+        }
+        body.stages = st;
+    }
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    assertStagesShape(body.stages);
+    return client.post("/api/v1/pipelines", body);
+}));
 // ---- search ----
 program
     .command("search <query>")
@@ -84,25 +324,189 @@ program
     }
     return client.post("/api/v1/ai/insights", { type, ...extra });
 }));
+// ---- users (team members) ----
+const users = program.command("users").description("Manage team members");
+users
+    .command("list")
+    .description("List team members")
+    .action(run(async (client) => client.get("/api/v1/users")));
+users
+    .command("create")
+    .description("Create a team member directly (no email invite)")
+    .option("--first <name>", "first name")
+    .option("--last <name>", "last name")
+    .option("--email <email>", "email")
+    .option("--role <role>", "role, e.g. member, admin")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.first !== undefined)
+        body.firstName = opts.first;
+    if (opts.last !== undefined)
+        body.lastName = opts.last;
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.role !== undefined)
+        body.role = opts.role;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/users", body);
+}));
+users
+    .command("invite")
+    .description("Invite a team member by email")
+    .option("--email <email>", "email to invite")
+    .option("--role <role>", "role, e.g. member, admin")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.email !== undefined)
+        body.email = opts.email;
+    if (opts.role !== undefined)
+        body.role = opts.role;
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    return client.post("/api/v1/users/invite", body);
+}));
+// ---- custom fields ----
+const customFields = program.command("custom-fields").description("Manage custom fields");
+customFields
+    .command("create")
+    .description("Define a custom field on contacts/deals/companies")
+    .option("--entity <type>", "entityType: contact | deal | company")
+    .option("--key <fieldKey>", "field key (machine name)")
+    .option("--label <label>", "display label")
+    .option("--type <fieldType>", "fieldType: text|textarea|number|date|datetime|url|select|radio|multiselect|boolean|phone|email")
+    .option("--options <json>", "JSON array of options (for select/radio/multiselect)")
+    .option("--json <json>", "full JSON body, merged over the flags")
+    .action(run(async (client, opts) => {
+    const body = {};
+    if (opts.entity !== undefined)
+        body.entityType = opts.entity;
+    if (opts.key !== undefined)
+        body.fieldKey = opts.key;
+    if (opts.label !== undefined)
+        body.label = opts.label;
+    if (opts.type !== undefined)
+        body.fieldType = opts.type;
+    if (opts.options !== undefined) {
+        if (opts.options.trim() === "")
+            throw new Error("--options must be valid JSON (got an empty string).");
+        let o;
+        try {
+            o = JSON.parse(opts.options);
+        }
+        catch {
+            throw new Error("--options must be valid JSON.");
+        }
+        if (!Array.isArray(o)) {
+            throw new Error("--options must be a JSON array, e.g. '[\"Low\",\"High\"]' or '[{\"label\":\"Low\",\"value\":\"low\"}]'.");
+        }
+        if (o.length === 0)
+            throw new Error("--options must be a non-empty array.");
+        body.options = o;
+    }
+    if (opts.json !== undefined)
+        Object.assign(body, jsonArg(opts.json, "--json"));
+    assertOptionsShape(body.options);
+    return client.post("/api/v1/custom-fields", body);
+}));
 // ---- raw escape hatch ----
 program
     .command("api <method> <path>")
-    .description("Make a raw authenticated API request (escape hatch)")
+    .description("Make a raw authenticated API request (escape hatch). Path may be '/users', 'users', or '/api/v1/users' — it is routed to the API base, not the website root.")
     .option("--body <json>", "JSON request body")
     .action(run(async (client, method, path, opts) => {
     let body;
-    if (opts.body) {
+    if (opts.body !== undefined) {
+        // Fail closed: an empty/whitespace --body (e.g. a script expanding an
+        // unset var) must error, not silently send a payload-less mutating POST.
+        if (opts.body.trim() === "") {
+            throw new Error("--body must be valid JSON (got an empty string).");
+        }
         try {
             body = JSON.parse(opts.body);
         }
         catch {
-            fail("--body must be valid JSON");
+            throw new Error("--body must be valid JSON.");
+        }
+        if (body !== null && typeof body === "object") {
+            rejectProtoPollution(body, "--body");
         }
     }
-    return client.request(method.toUpperCase(), path, body);
+    // Normalize to an API path so the escape hatch hits the API, not the site
+    // root (the base URL is the bare host). Accept already-prefixed paths.
+    let p = path.startsWith("/") ? path : `/${path}`;
+    if (!/^\/api\//.test(p))
+        p = `/api/v1${p}`;
+    return client.request(method.toUpperCase(), p, body);
 }));
 program.parseAsync(process.argv).catch(fail);
 // 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.
+// Final-payload validators for CLI-owned shallow invariants. Run AFTER the
+// --json merge so a value supplied (or overridden) via --json is held to the
+// same rule as the dedicated flag — the escape valve can't smuggle a
+// known-invalid shape past validation to a mutating POST. The SERVER remains
+// the authority on deep field schemas; these only catch obviously-malformed
+// shapes for a fast, clear client-side failure.
+function assertStagesShape(v) {
+    if (v === undefined)
+        return;
+    if (!Array.isArray(v) ||
+        v.length === 0 ||
+        v.some((s) => s === null || typeof s !== "object" || Array.isArray(s))) {
+        throw new Error("stages must be a non-empty array of stage objects, e.g. '[{\"name\":\"Lead\"},{\"name\":\"Won\",\"isWon\":true}]'.");
+    }
+}
+function assertOptionsShape(v) {
+    if (v === undefined)
+        return;
+    if (!Array.isArray(v) || v.length === 0) {
+        throw new Error("options must be a non-empty JSON array, e.g. '[\"Low\",\"High\"]'.");
+    }
+}
+function assertFiniteValue(v) {
+    if (v === undefined)
+        return;
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new Error("value must be a finite number.");
+    }
+}
+// Reject prototype-polluting keys in untrusted JSON. JSON.parse creates an OWN
+// "__proto__" property, but Object.assign'ing it onto a {} body invokes the
+// setter and changes the body's PROTOTYPE — so a validator could read an
+// inherited value while JSON.stringify only serializes own props, desyncing
+// validation from what is actually POSTed. getOwnPropertyNames sees the parsed
+// own keys (including __proto__) regardless of the prototype chain.
+function rejectProtoPollution(obj, flag) {
+    for (const k of Object.getOwnPropertyNames(obj)) {
+        if (k === "__proto__" || k === "constructor" || k === "prototype") {
+            throw new Error(`${flag} may not contain a "${k}" key.`);
+        }
+    }
+}
+function jsonArg(raw, flag) {
+    if (raw.trim() === "") {
+        throw new Error(`${flag} must be valid JSON (got an empty string).`);
+    }
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${flag} must be valid JSON.`);
+    }
+    // Merge-style flags are Object.assign'd onto the request body, so an array or
+    // primitive would silently reshape/empty it (e.g. [] -> {}, [{x:1}] -> numeric
+    // keys). Require a plain JSON object. Raw array bodies go through `api`.
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(`${flag} must be a JSON object (not an array or primitive).`);
+    }
+    rejectProtoPollution(v, flag);
+    return v;
+}
 function run(handler) {
     return async (...args) => {
         try {

package/package.json

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