@erdoai/cli 0.87.0 → 0.89.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`);
   }
@@ -1126,6 +1153,23 @@ var ErdoClient = class {
       `/v1/datasets/${encodeURIComponent(slug)}/refresh/run`
     );
   }
+  // --- lead identity ---
+  // Preview or perform a dataset's permanent-lead-identity migration: give every
+  // pipeline writer the producer contract, backfill the IDs, and publish the
+  // identity config in one transaction.
+  //
+  // apply:false mutates nothing and is the way to read readiness — `ready`, the
+  // `blockers` holding it up, and how many rows would be assigned an identity.
+  // apply:true needs an operation_key: replaying the same key settles an apply
+  // whose response was lost, while a different key against a migrated dataset is
+  // refused rather than migrating twice.
+  maintainLeadIdentity(slug, body) {
+    return this.request(
+      "POST",
+      `/v1/datasets/${encodeURIComponent(slug)}/lead-identity/maintain`,
+      body
+    );
+  }
   // --- bounded outreach ---
   putOutreachBatch(batch, body) {
     return this.request(
@@ -1750,6 +1794,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) {
@@ -5616,6 +5670,49 @@ datasetsCmd.command("set-purpose <slug> [purpose]").description(
     fail(e);
   }
 });
+var leadIdentityCmd = datasetsCmd.command("lead-identity").description(
+  "Permanent lead identity \u2014 one lead is one row, however many ways they got in touch. Migrating a dataset gives every row a canonical_lead_id, points every pipeline writer at it, and makes the resolver the only thing that decides whether a submission is a new lead or an existing one."
+);
+leadIdentityCmd.command("maintain <slug>").description(
+  "Preview or perform the migration for one dataset. Without --apply it mutates nothing and reports readiness: whether the dataset is ready, what blocks it, and how many rows would be assigned an identity. Run the preview first and read the blockers \u2014 apply refuses outright while any consumer is incompatible, unverifiable, queued or running, because the backfill rewrites the file every one of them reads."
+).option(
+  "--apply",
+  "perform the migration rather than preview it; requires --operation-key"
+).option(
+  "--operation-key <key>",
+  "the migration receipt. Replaying the same key settles an apply whose response was lost; a different key against an already-migrated dataset is refused rather than migrating it twice."
+).option("--email-column <column>", "the dataset's email column (detected when omitted)").option("--phone-column <column>", "the dataset's phone column (detected when omitted)").option(
+  "--conversion-id-column <column>",
+  "optional conversion id column; must differ from both contact columns"
+).option(
+  "--default-calling-code <code>",
+  "calling code a phone written in national form belongs to, so one number written two ways is one lead (default 1)"
+).action(
+  async (slug, opts) => {
+    try {
+      if (opts.apply && !opts.operationKey) {
+        fail(
+          new Error(
+            "--apply requires --operation-key so an uncertain retry can settle rather than migrating twice"
+          )
+        );
+        return;
+      }
+      print(
+        await new ErdoClient().maintainLeadIdentity(slug, {
+          apply: Boolean(opts.apply),
+          operation_key: opts.operationKey,
+          email_column: opts.emailColumn,
+          phone_column: opts.phoneColumn,
+          conversion_id_column: opts.conversionIdColumn,
+          default_calling_code: opts.defaultCallingCode
+        })
+      );
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
 datasetsCmd.command("query <slug> <question>").description(
   "Ask a natural-language question of a dataset \u2014 Erdo writes and runs the SQL, and answers with that SQL alongside the values. It runs an agent, so it is slower and two identical questions can produce two different queries: for a deterministic or scripted read, write the SQL yourself with `datasets fetch --sql`."
 ).action(async (slug, question) => {
@@ -6073,6 +6170,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.89.0",
   "description": "Erdo CLI — drive datasets, pages, and evals from the terminal or CI",
   "type": "module",
   "bin": {