@erdoai/cli 0.87.0 → 0.88.0

package/dist/index.js

@@ -1094,6 +1094,33 @@ var ErdoClient = class {
   // that was never live (an upload merged into an existing table); file_type may be
   // absent when the stored file's type was never recorded. Read one back by passing
   // its id as revision_id to fetchDatasetContents.
+  // ── leads ──────────────────────────────────────────────────────────────────
+  // Permanent lead identity. A lead is addressed by its canonical_lead_id or by
+  // the 22-character reference short enough for a link or an SMS; an id that has
+  // since been merged away resolves to the lead it became, so an id read off an
+  // old capture response keeps working.
+  getLead(datasetSlug, lead) {
+    return this.request(
+      "GET",
+      `/v1/datasets/${encodeURIComponent(datasetSlug)}/leads/${encodeURIComponent(lead)}`
+    );
+  }
+  // The captures the platform refused to resolve: two leads sharing a contact
+  // detail, or a submission whose email and phone point at different leads.
+  listLeadMergeCandidates(datasetSlug, limit) {
+    const qs = limit ? `?limit=${encodeURIComponent(String(limit))}` : "";
+    return this.request("GET", `/v1/datasets/${encodeURIComponent(datasetSlug)}/lead-candidates${qs}`);
+  }
+  // Not reversible in practice: the absorbed lead's row values are combined into
+  // the survivor's and its row is gone. It needs no idempotency key — the pair it
+  // joins identifies it, so a retry answers "already_merged".
+  mergeLeads(datasetSlug, survivor, input) {
+    return this.request(
+      "POST",
+      `/v1/datasets/${encodeURIComponent(datasetSlug)}/leads/${encodeURIComponent(survivor)}/merge`,
+      input
+    );
+  }
   listDatasetRevisions(slug) {
     return this.request("GET", `/v1/datasets/${encodeURIComponent(slug)}/revisions`);
   }
@@ -1750,6 +1777,16 @@ async function resolveSecretInput(options) {
   }
   return void 0;
 }
+async function promptLine(question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return "";
+  const readline2 = await import("readline/promises");
+  const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
 
 // src/integrations.ts
 function formatIntegrationListRow(i) {
@@ -6073,6 +6110,140 @@ filterCmd.command("list <slug>").description("List the default filters on a data
     fail(e);
   }
 });
+var leadsCmd = program.command("leads").description("Read leads in a lead dataset, and merge two that are the same person");
+leadsCmd.command("get <dataset> <lead>").description(
+  "Read one lead: its permanent canonical_lead_id, the email and phone evidence bound to it, its dataset row, the leads merged into it, and its capture history. <lead> is either the canonical_lead_id UUID or the 22-character lead reference, and an id that has since been merged away resolves to the lead it became \u2014 so an id read off an old capture response still works."
+).option("--json", "print the raw JSON result instead of a summary").action(async (dataset, lead, opts) => {
+  try {
+    const res = await new ErdoClient().getLead(dataset, lead);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    printLead(res.lead);
+  } catch (e) {
+    fail(e);
+  }
+});
+leadsCmd.command("candidates <dataset>").description(
+  "List the captures the platform refused to resolve \u2014 where two leads share a contact detail, or a submission's email and phone point at different leads. The platform records the candidates instead of guessing, and this is the queue a person drains with `leads merge`."
+).option("-l, --limit <n>", "maximum captures to return (default 50, maximum 200)", (v) => parseInt(v, 10)).option("--json", "print the raw JSON result instead of a table").action(async (dataset, opts) => {
+  try {
+    const res = await new ErdoClient().listLeadMergeCandidates(dataset, opts.limit);
+    if (opts.json) {
+      print(res);
+      return;
+    }
+    const candidates = res.candidates ?? [];
+    if (!res.lead_identity_enabled) {
+      console.log(
+        `${res.dataset_slug} does not have permanent lead identity, so nothing has been checked for duplicates. Migrate the dataset first.`
+      );
+      return;
+    }
+    if (candidates.length === 0) {
+      console.log(`${res.dataset_slug} has no unresolved lead captures.`);
+      return;
+    }
+    const rows = [];
+    for (const item of candidates) {
+      for (const candidate of item.candidates ?? []) {
+        rows.push([
+          item.capture.created_at,
+          item.capture.resolution,
+          candidate.canonical_lead_id,
+          (candidate.emails ?? []).join(" "),
+          (candidate.phones ?? []).join(" "),
+          candidate.merged_into ? `merged into ${candidate.merged_into}` : ""
+        ]);
+      }
+    }
+    printAlignedTable(["captured", "why", "lead", "emails", "phones", "settled"], rows);
+    console.log(
+      `
+Merge two of them with: erdo leads merge ${res.dataset_slug} <survivor> --absorb <lead>`
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+leadsCmd.command("merge <dataset> <survivor>").description(
+  "Merge two leads into one. The absorbed lead stops being its own lead: its contact evidence moves onto the survivor, and the two dataset rows become one row \u2014 a value the absorbed row carries fills a blank in the survivor's row, and never replaces one the survivor already holds unless you name the column with --overwrite-column. This cannot be undone: the absorbed row's values are combined away and only the pointer survives, so an id already handed out keeps resolving. Read both leads with `leads get` before running it."
+).requiredOption("--absorb <lead>", "the lead that stops being its own lead (UUID or lead reference)").option(
+  "--overwrite-column <name>",
+  "a column where the absorbed lead's value wins over one the survivor already holds; repeatable",
+  (value, previous) => [...previous, value],
+  []
+).option("-y, --yes", "skip the confirmation prompt").option("--json", "print the raw JSON result instead of a summary").action(
+  async (dataset, survivor, opts) => {
+    try {
+      if (!opts.yes) {
+        const answer = await promptLine(
+          `Merge ${opts.absorb} into ${survivor} in ${dataset}? The absorbed lead's row is combined away and this cannot be undone. Type "merge" to continue: `
+        );
+        if (answer.trim() !== "merge") {
+          console.error("Not merged.");
+          process.exit(1);
+        }
+      }
+      const res = await new ErdoClient().mergeLeads(dataset, survivor, {
+        absorb_lead_id: opts.absorb,
+        overwrite_columns: opts.overwriteColumn.length ? opts.overwriteColumn : void 0
+      });
+      if (opts.json) {
+        print(res);
+        return;
+      }
+      if (res.state === "already_merged") {
+        console.log(`Already one lead: ${res.absorbed_lead_id} resolves to ${res.lead.canonical_lead_id}.`);
+      } else {
+        console.log(
+          `Merged ${res.absorbed_lead_id} into ${res.lead.canonical_lead_id} \u2014 ${res.aliases_moved} contact ${res.aliases_moved === 1 ? "alias" : "aliases"} moved, ${res.rows_combined} ${res.rows_combined === 1 ? "row" : "rows"} combined.`
+        );
+      }
+      printLead(res.lead);
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+function printLead(lead) {
+  console.log(`lead       ${lead.canonical_lead_id}`);
+  console.log(`reference  ${lead.reference}`);
+  console.log(`dataset    ${lead.dataset_slug}`);
+  if (lead.requested_lead_id && lead.requested_lead_id !== lead.canonical_lead_id) {
+    console.log(`asked for  ${lead.requested_lead_id} (merged into this lead)`);
+  }
+  if (lead.merged_into) {
+    console.log(`merged into ${lead.merged_into}${lead.merged_at ? ` on ${lead.merged_at}` : ""}`);
+  }
+  if (lead.absorbed_lead_ids?.length) {
+    console.log(`absorbed   ${lead.absorbed_lead_ids.join(", ")}`);
+  }
+  if (lead.aliases?.length) {
+    console.log("\ncontact evidence");
+    printAlignedTable(
+      ["type", "value", "from"],
+      lead.aliases.map((a) => [a.type, a.value, a.provenance])
+    );
+  }
+  if (lead.captures?.length) {
+    console.log("\ncaptures");
+    printAlignedTable(
+      ["when", "producer", "resolution", "conversion"],
+      lead.captures.map((c) => [c.created_at, c.producer, c.resolution, c.conversion_status])
+    );
+  }
+  if (lead.row) {
+    console.log("\nrow");
+    printAlignedTable(
+      ["column", "value"],
+      Object.keys(lead.row).sort().map((column) => [column, lead.row?.[column] ?? ""])
+    );
+  } else {
+    console.log("\nThis lead holds no dataset row \u2014 its values were combined into the lead it was merged with.");
+  }
+}
 var integrationsCmd = program.command("integrations").description("Connect and inspect integrations");
 integrationsCmd.command("list").description("List connected integrations \u2014 app, status, auth type, name, then the connection's id (what --from-connection takes)").action(async () => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erdoai/cli",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {