@erdoai/cli 0.88.0 → 0.90.0

package/dist/index.js

@@ -489,10 +489,13 @@ var ErdoClient = class {
   // Phone conversation records: inbound calls to a voice agent's own number and
   // the outbound calls Erdo placed. Website chat widget conversations are a
   // different resource — they live under /v1/voice/widget-conversations.
+  // canonical_lead_id narrows to one lead's calls, by its UUID or its lead
+  // reference — the same filter every conversation list takes.
   listVoiceCalls(params) {
     const q = new URLSearchParams();
     if (params?.agent) q.set("agent", params.agent);
     if (params?.direction) q.set("direction", params.direction);
+    if (params?.canonical_lead_id) q.set("canonical_lead_id", params.canonical_lead_id);
     if (params?.limit !== void 0) q.set("limit", String(params.limit));
     if (params?.offset !== void 0) q.set("offset", String(params.offset));
     if (params?.cursor) q.set("cursor", params.cursor);
@@ -510,6 +513,7 @@ var ErdoClient = class {
     if (params?.widget) q.set("widget", params.widget);
     if (params?.since) q.set("since", params.since);
     if (params?.until) q.set("until", params.until);
+    if (params?.canonical_lead_id) q.set("canonical_lead_id", params.canonical_lead_id);
     if (params?.limit !== void 0) q.set("limit", String(params.limit));
     if (params?.offset !== void 0) q.set("offset", String(params.offset));
     if (params?.cursor) q.set("cursor", params.cursor);
@@ -536,6 +540,7 @@ var ErdoClient = class {
     const q = new URLSearchParams();
     if (params?.phone_number) q.set("phone_number", params.phone_number);
     if (params?.address) q.set("address", params.address);
+    if (params?.canonical_lead_id) q.set("canonical_lead_id", params.canonical_lead_id);
     if (params?.limit !== void 0) q.set("limit", String(params.limit));
     if (params?.cursor) q.set("cursor", params.cursor);
     const qs = q.toString();
@@ -1153,6 +1158,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(
@@ -5198,13 +5220,18 @@ function contactLabel(contact) {
 function leadStatusLabel(outcome) {
   return outcome ? outcome : "pending";
 }
+function leadReferenceLabel(reference) {
+  return reference ? reference : "-";
+}
+var LEAD_FILTER_HELP = "only this lead's conversations \u2014 its canonical lead id (UUID) or its 22-character lead reference";
 var voiceCallsCmd = voiceCmd.command("calls").description("Inbound and outbound phone call records");
-voiceCallsCmd.command("list").description("List the organization's phone calls, newest first").option("--agent <slug>", "only calls held by this voice agent, by slug").option("--direction <direction>", "only 'inbound' (calls to the agent's number) or 'outbound'").option("--limit <n>", "page size (default 25, max 100)").option("--offset <n>", "rows to skip").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
+voiceCallsCmd.command("list").description("List the organization's phone calls, newest first").option("--agent <slug>", "only calls held by this voice agent, by slug").option("--direction <direction>", "only 'inbound' (calls to the agent's number) or 'outbound'").option("--lead <lead>", LEAD_FILTER_HELP).option("--limit <n>", "page size (default 25, max 100)").option("--offset <n>", "rows to skip").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
   async (opts) => {
     try {
       const res = await new ErdoClient().listVoiceCalls({
         agent: opts.agent,
         direction: opts.direction,
+        canonical_lead_id: opts.lead,
         limit: opts.limit ? Number(opts.limit) : void 0,
         offset: opts.offset ? Number(opts.offset) : void 0,
         cursor: opts.cursor
@@ -5229,6 +5256,7 @@ voiceCallsCmd.command("list").description("List the organization's phone calls,
           "transcript",
           "contact",
           "lead",
+          "lead ref",
           "started",
           "summary"
         ],
@@ -5242,6 +5270,7 @@ voiceCallsCmd.command("list").description("List the organization's phone calls,
           call.has_transcript ? "yes" : "no",
           contactLabel(call.contact),
           leadStatusLabel(call.lead_status),
+          leadReferenceLabel(call.lead_reference),
           call.created_at,
           call.transcript_summary
         ])
@@ -5258,7 +5287,7 @@ voiceCallsCmd.command("list").description("List the organization's phone calls,
   }
 );
 voiceCallsCmd.command("get <callID>").description(
-  "Read one phone call in full: transcript, summary, per-turn LLM metrics, and the lead it produced (contact, lead_status, lead_saved_at)"
+  "Read one phone call in full: transcript, summary, per-turn LLM metrics, and the lead it produced (contact, lead_status, lead_saved_at, canonical_lead_id, lead_reference)"
 ).action(async (callID) => {
   try {
     print(await new ErdoClient().getVoiceCall(callID));
@@ -5267,13 +5296,14 @@ voiceCallsCmd.command("get <callID>").description(
   }
 });
 var widgetConversationsCmd = voiceCmd.command("widget-conversations").description("Website concierge widget conversations (text, voice and video sessions)");
-widgetConversationsCmd.command("list").description("List the organization's widget conversations, newest first").option("--widget <handle>", "only this widget's conversations \u2014 its name or public key (vw_...)").option("--since <rfc3339>", "only conversations that started at or after this time (inclusive)").option("--until <rfc3339>", "only conversations that started before this time (exclusive)").option("--limit <n>", "page size (default 25, max 100)").option("--offset <n>", "rows to skip").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
+widgetConversationsCmd.command("list").description("List the organization's widget conversations, newest first").option("--widget <handle>", "only this widget's conversations \u2014 its name or public key (vw_...)").option("--since <rfc3339>", "only conversations that started at or after this time (inclusive)").option("--until <rfc3339>", "only conversations that started before this time (exclusive)").option("--lead <lead>", LEAD_FILTER_HELP).option("--limit <n>", "page size (default 25, max 100)").option("--offset <n>", "rows to skip").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
   async (opts) => {
     try {
       const res = await new ErdoClient().listWidgetConversations({
         widget: opts.widget,
         since: opts.since,
         until: opts.until,
+        canonical_lead_id: opts.lead,
         limit: opts.limit ? Number(opts.limit) : void 0,
         offset: opts.offset ? Number(opts.offset) : void 0,
         cursor: opts.cursor
@@ -5296,6 +5326,7 @@ widgetConversationsCmd.command("list").description("List the organization's widg
           "transcript",
           "contact",
           "lead",
+          "lead ref",
           "started",
           "summary"
         ],
@@ -5307,6 +5338,7 @@ widgetConversationsCmd.command("list").description("List the organization's widg
           c.has_transcript ? "yes" : "no",
           contactLabel(c.contact),
           leadStatusLabel(c.lead_status),
+          leadReferenceLabel(c.lead_reference),
           c.created_at,
           c.transcript_summary
         ])
@@ -5325,7 +5357,7 @@ widgetConversationsCmd.command("list").description("List the organization's widg
   }
 );
 widgetConversationsCmd.command("get <sessionID>").description(
-  "Read one widget conversation in full: transcript, summary, topics, per-turn LLM metrics, and the lead it produced (contact, lead_status, lead_saved_at)"
+  "Read one widget conversation in full: transcript, summary, topics, per-turn LLM metrics, and the lead it produced (contact, lead_status, lead_saved_at, canonical_lead_id, lead_reference)"
 ).option("--widget <handle>", "the widget it belongs to \u2014 optional, the session id identifies it").action(async (sessionID, opts) => {
   try {
     print(await new ErdoClient().getWidgetConversation(sessionID, opts.widget));
@@ -5334,12 +5366,13 @@ widgetConversationsCmd.command("get <sessionID>").description(
   }
 });
 var voiceSMSCmd = voiceCmd.command("sms").description("Text conversations on a voice agent's own number");
-voiceSMSCmd.command("list").description("List the organization's SMS conversations, most recently active first").option("--phone-number <number>", "only conversations on this Erdo number (any format)").option("--address <number>", "only the conversation with this person (any format)").option("--limit <n>", "page size (default 25, max 100)").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
+voiceSMSCmd.command("list").description("List the organization's SMS conversations, most recently active first").option("--phone-number <number>", "only conversations on this Erdo number (any format)").option("--address <number>", "only the conversation with this person (any format)").option("--lead <lead>", LEAD_FILTER_HELP).option("--limit <n>", "page size (default 25, max 100)").option("--cursor <cursor>", "next_cursor from the preceding page (stable paging)").option("--json", "print the raw JSON result instead of a table").action(
   async (opts) => {
     try {
       const res = await new ErdoClient().listSMSConversations({
         phone_number: opts.phoneNumber,
         address: opts.address,
+        canonical_lead_id: opts.lead,
         limit: opts.limit ? Number(opts.limit) : void 0,
         cursor: opts.cursor
       });
@@ -5353,7 +5386,7 @@ voiceSMSCmd.command("list").description("List the organization's SMS conversatio
         return;
       }
       printAlignedTable(
-        ["session id", "phone", "address", "msgs", "last inbound", "last outbound", "summary"],
+        ["session id", "phone", "address", "msgs", "last inbound", "last outbound", "lead ref", "summary"],
         conversations.map((c) => [
           c.session_id,
           c.phone_number,
@@ -5363,6 +5396,7 @@ voiceSMSCmd.command("list").description("List the organization's SMS conversatio
           c.message_count,
           c.last_inbound_at ?? "",
           c.last_outbound_at ?? "",
+          leadReferenceLabel(c.lead_reference),
           c.summary
         ])
       );
@@ -5409,6 +5443,9 @@ voiceSMSCmd.command("get <sessionID>").description("Read one SMS conversation: i
         console.log(`
 contact: ${parts.join(" \xB7 ")}`);
       }
+      if (c.lead_reference) {
+        console.log(`lead: ${c.lead_reference} (${c.canonical_lead_id})`);
+      }
       const messages = res.messages ?? [];
       if (messages.length === 0) {
         console.log("\nNo texts have been recorded in this conversation yet.");
@@ -5653,6 +5690,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) => {
@@ -6230,8 +6310,20 @@ function printLead(lead) {
   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])
+      ["when", "producer", "pipeline", "resolution", "conversion"],
+      lead.captures.map((c) => [c.created_at, c.producer, c.pipeline_id ?? "", c.resolution, c.conversion_status])
+    );
+  }
+  if (lead.refused_captures?.length) {
+    console.log("\nrefused captures (this lead was one of the candidates)");
+    printAlignedTable(
+      ["when", "pipeline", "resolution", "candidates"],
+      lead.refused_captures.map((c) => [
+        c.created_at,
+        c.pipeline_id ?? "",
+        c.resolution,
+        (c.candidate_lead_ids ?? []).join(", ")
+      ])
     );
   }
   if (lead.row) {

package/package.json

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