@dench.com/cli 3.10.2 → 3.11.0

package/app-sdk.d.ts

@@ -751,6 +751,13 @@ export interface ApiRequests {
     limit?: number;
     enrichment?: "all" | "enriched" | "in_progress" | "no_contacts" | "failed" | "not_enriched";
   };
+  /** Buy contact details for 1–100 saved profiles and save them to the list. Skips fields already found, looked up empty, or in flight. Requires a signed-in member or their personal agent. — `dench lists enrich` — POST /api/v1/lists/{artifactId}/enrich */
+  "lists.enrich": {
+    artifactId: string;
+    rows: Record<string, unknown>[];
+    /** email is work email. */
+    fields: Array<"email" | "phone" | "personal_email">;
+  };
   /** Explicitly import selected saved profiles, optionally filtered by enrichment, with a configured Lead status. Reuses CRM records; never sends outreach or triggers conversion. — `dench artifacts import` — POST /api/v1/lists/{artifactId}/import */
   "lists.import": {
     artifactId: string;
@@ -4268,6 +4275,7 @@ export interface ApiResponses {
   }>;
   "lists.list": unknown;
   "lists.rows": unknown;
+  "lists.enrich": unknown;
   "lists.import": unknown;
   "lists.get": unknown;
   "lists.save": {
@@ -9551,6 +9559,8 @@ export type DenchApiTree = {
   lists: {
     /** Delete a saved search / list, its exported CSV/JSONL files, and any linked watch. (`dench lists delete`) */
     delete(args: Req<"lists.delete">): Promise<Res<"lists.delete">>;
+    /** Buy contact details for 1–100 saved profiles and save them to the list. Skips fields already found, looked up empty, or in flight. Requires a signed-in member or their personal agent. (`dench lists enrich`) */
+    enrich(args: Req<"lists.enrich">): Promise<Res<"lists.enrich">>;
     /** Get one saved search / list by artifact id. (`dench lists show`) */
     get(args: Req<"lists.get">): Promise<Res<"lists.get">>;
     /** Explicitly import selected saved profiles, optionally filtered by enrichment, with a configured Lead status. Reuses CRM records; never sends outreach or triggers conversion. (`dench artifacts import`) */

package/leads.ts

@@ -61,6 +61,9 @@ const api = {
   listRows: makeFunctionReference<"action">(
     "functions/workspaceArtifacts:listRows",
   ),
+  enrichSelected: makeFunctionReference<"action">(
+    "functions/workspaceArtifacts:enrichSelected",
+  ),
   get: makeFunctionReference<"query">("functions/workspaceArtifacts:get"),
   reviews: makeFunctionReference<"query">("functions/prospectReviews:list"),
   assess: makeFunctionReference<"mutation">("functions/prospectReviews:assess"),
@@ -80,6 +83,74 @@ const ENRICHMENT_FILTERS = [
   "failed",
   "not_enriched",
 ];
+function rowIndexesFlag(args: string[]): number[] | undefined {
+  const rowsFlag = getFlag(args, "--rows");
+  return rowsFlag === undefined
+    ? undefined
+    : rowsFlag.split(",").map((value) => {
+        if (!/^\d+$/.test(value.trim()))
+          throw new FindCliError(
+            "--rows must be comma-separated original zero-based row indices",
+          );
+        const index = Number(value);
+        if (!Number.isSafeInteger(index))
+          throw new FindCliError("Invalid row index");
+        return index;
+      });
+}
+
+const CONTACT_FIELDS = ["email", "phone", "personal_email"] as const;
+type ContactField = (typeof CONTACT_FIELDS)[number];
+/** One enrichSelected call accepts at most this many profiles. */
+const ENRICH_BATCH = 100;
+const ENRICH_WAIT_POLL_MS = 10_000;
+/** Stays under the sandbox's 300s default foreground bash budget. */
+const ENRICH_WAIT_DEFAULT_SECONDS = 240;
+
+type SavedRowEntry = { index: number; row: unknown };
+
+/** Page a saved list by original index until isDone. */
+async function savedListEntries(
+  ctx: FindCliContext,
+  artifactId: string,
+  enrichment: string,
+): Promise<SavedRowEntry[]> {
+  const entries: SavedRowEntry[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = (await callAction(ctx, api.listRows, {
+      artifactId,
+      limit: 100,
+      enrichment,
+      ...(cursor ? { cursor } : {}),
+    })) as {
+      page: SavedRowEntry[];
+      isDone: boolean;
+      continueCursor: string | null;
+    };
+    entries.push(...page.page);
+    cursor = page.isDone ? null : page.continueCursor;
+  } while (cursor);
+  return entries;
+}
+
+async function enrichmentCounts(
+  ctx: FindCliContext,
+  artifactId: string,
+  selected: ReadonlySet<number>,
+) {
+  const counts: Record<string, number> = {};
+  for (const state of ["in_progress", "enriched", "no_contacts", "failed"]) {
+    const rows = await savedListEntries(ctx, artifactId, state);
+    counts[state] = rows.filter((entry) => selected.has(entry.index)).length;
+  }
+  return counts;
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function enrichmentFlag(args: string[]): string | undefined {
   const value = getFlag(args, "--enrichment");
   if (value !== undefined && !ENRICHMENT_FILTERS.includes(value))
@@ -659,6 +730,7 @@ Usage:
   dench lists save --title "Target accounts" --companies-file <companies.json> [--json]
   dench lists save --title "Open roles" --jobs-file <jobs.json> [--json]
   dench lists rows <id> [--enrichment all|enriched|in_progress|no_contacts|failed|not_enriched] [--limit 100] [--cursor <cursor>] [--json]
+  dench lists enrich <id> [--fields email,phone,personal_email] [--rows 0,4,9] [--wait [--timeout 240]] [--json]
   dench lists rename <id> "New name" [--json]
   dench lists update <id> [--title "New name"] [--filters-json '{"titles":["CTO"]}'] [--json]
   dench lists delete <id> [--json]
@@ -668,6 +740,10 @@ People lists are not CRM Leads. Searching and saving do not reveal new contact d
 there is no mandatory per-profile ICP decision. Import only on explicit request, with the
 requested configured CRM status. Follow pagination until isDone, even across
 empty filtered pages. --rows uses original zero-based indices from lists rows.
+Enrich buys contact details (default: work email) for every row, or only --rows, and
+saves them to the list. It costs credits, so run it only when the user asks for contacts.
+Found, empty and in-flight lookups are never bought twice, so rerunning is safe. --wait
+polls until lookups finish (default 240s) and prints status counts.
   dench lists reviews <id> [--limit 100] [--cursor <cursor>] [--json]
   dench lists assess <id> --row-json '<profile>' --fit likely_fit|unlikely_fit|unknown --score 0-100 --reason '<short ICP reason>' [--json]
   dench lists assess <id> --assessments-file <assessments.json> [--json]
@@ -927,6 +1003,102 @@ export async function runListsCommand(opts: {
     );
     return true;
   }
+  if (verb === "enrich") {
+    const artifactId = shift(args, "list id");
+    const fieldsRaw = getFlag(args, "--fields") ?? "email";
+    const fields = [
+      ...new Set(fieldsRaw.split(",").map((field) => field.trim())),
+    ];
+    if (
+      !fields.length ||
+      fields.some((field) => !CONTACT_FIELDS.includes(field as ContactField))
+    )
+      throw new FindCliError(
+        `--fields must be a comma-separated subset of ${CONTACT_FIELDS.join(",")}`,
+      );
+    const rowIndexes = rowIndexesFlag(args);
+    const wait = hasFlag(args, "--wait");
+    const timeoutRaw = getFlag(args, "--timeout");
+    const timeoutSeconds =
+      timeoutRaw === undefined
+        ? ENRICH_WAIT_DEFAULT_SECONDS
+        : Number(timeoutRaw);
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1)
+      throw new FindCliError("--timeout must be a positive number of seconds");
+    if (timeoutRaw !== undefined && !wait)
+      throw new FindCliError("--timeout only applies with --wait");
+    assertNoUnknownFlags(args, "lists enrich");
+
+    // The server skips fields already found, looked up empty, or in flight,
+    // so sending every selected row never buys the same contact twice.
+    let entries = await savedListEntries(ctx, artifactId, "all");
+    if (rowIndexes) {
+      const byIndex = new Map(entries.map((entry) => [entry.index, entry]));
+      const missing = rowIndexes.filter((index) => !byIndex.has(index));
+      if (missing.length)
+        throw new FindCliError(
+          `Row ${missing.join(", ")} is not in this list. Use original indices from dench lists rows.`,
+        );
+      entries = [...new Set(rowIndexes)].map(
+        (index) => byIndex.get(index) as SavedRowEntry,
+      );
+    }
+    if (!entries.length) throw new FindCliError("This list has no rows.");
+    let queued = 0;
+    let reused = 0;
+    for (let start = 0; start < entries.length; start += ENRICH_BATCH) {
+      const batch = entries.slice(start, start + ENRICH_BATCH);
+      try {
+        const result = (await callAction(ctx, api.enrichSelected, {
+          artifactId,
+          rows: batch.map((entry) => entry.row),
+          fields,
+        })) as { queued: number; reused: number };
+        queued += result.queued;
+        reused += result.reused;
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Enrichment failed.";
+        // The first batch never committed, so there is nothing to resume.
+        if (start === 0) throw new FindCliError(message);
+        throw new FindCliError(
+          `Started ${queued} lookups for the first ${start} of ${entries.length} profiles. Rerun the same command to continue; finished and in-flight lookups are not bought again. ${message}`,
+        );
+      }
+    }
+    const summary = {
+      artifactId,
+      fields,
+      profiles: entries.length,
+      queued,
+      reused,
+    };
+    const readBack = `dench lists rows ${artifactId} --enrichment enriched --limit 100 --json`;
+    if (!wait) {
+      out(ctx, { ...summary, next: readBack });
+      return true;
+    }
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const selected = new Set(entries.map((entry) => entry.index));
+    const inProgress = async () =>
+      (await savedListEntries(ctx, artifactId, "in_progress")).filter((entry) =>
+        selected.has(entry.index),
+      ).length;
+    while ((await inProgress()) && Date.now() < deadline)
+      await sleep(Math.min(ENRICH_WAIT_POLL_MS, deadline - Date.now()));
+    const counts = await enrichmentCounts(ctx, artifactId, selected);
+    out(ctx, {
+      ...summary,
+      done: !counts.in_progress,
+      counts,
+      next: counts.in_progress
+        ? `Still running. Check again with: dench lists rows ${artifactId} --enrichment in_progress --json`
+        : counts.failed
+          ? `dench lists rows ${artifactId} --enrichment failed --limit 100 --json`
+          : readBack,
+    });
+    return true;
+  }
   if (verb === "show") {
     const artifactId = shift(args, "list id");
     assertNoUnknownFlags(args, "lists show");
@@ -1439,20 +1611,7 @@ export async function runWorkspaceArtifactsCommand(opts: {
   const pin = hasFlag(args, "--pin");
   const status = getFlag(args, "--status");
   const enrichment = enrichmentFlag(args);
-  const rowsFlag = getFlag(args, "--rows");
-  const rowIndexes =
-    rowsFlag === undefined
-      ? undefined
-      : rowsFlag.split(",").map((value) => {
-          if (!/^\d+$/.test(value.trim()))
-            throw new FindCliError(
-              "--rows must be comma-separated original zero-based row indices",
-            );
-          const index = Number(value);
-          if (!Number.isSafeInteger(index))
-            throw new FindCliError("Invalid row index");
-          return index;
-        });
+  const rowIndexes = rowIndexesFlag(args);
   assertNoUnknownFlags(args, "artifacts import");
   out(
     ctx,

package/lib/app-sdk-catalog.generated.ts

@@ -140,6 +140,7 @@ export const APP_SDK_OPERATIONS: readonly AppSdkOperationInfo[] = [
   {"id":"workspace.suggestedWork.list","group":"workspace","summary":"List draft suggested-work artifacts.","cli":"dench suggested-work","method":"GET","path":"/suggested-work","permission":"workspace:read","pathParams":[]},
   {"id":"lists.list","group":"lists","summary":"List saved searches (find-result lists) in the workspace, newest first.","cli":"dench lists","method":"GET","path":"/lists","permission":"lists:read","pathParams":[]},
   {"id":"lists.rows","group":"lists","summary":"Read saved rows with current enrichment results and original indices; cursor-paged, without repeating a search.","cli":"dench lists rows","method":"GET","path":"/lists/{artifactId}/rows","permission":"lists:read","pathParams":["artifactId"]},
+  {"id":"lists.enrich","group":"lists","summary":"Buy contact details for 1–100 saved profiles and save them to the list. Skips fields already found, looked up empty, or in flight. Requires a signed-in member or their personal agent.","cli":"dench lists enrich","method":"POST","path":"/lists/{artifactId}/enrich","permission":"lists:write","pathParams":["artifactId"]},
   {"id":"lists.import","group":"lists","summary":"Explicitly import selected saved profiles, optionally filtered by enrichment, with a configured Lead status. Reuses CRM records; never sends outreach or triggers conversion.","cli":"dench artifacts import","method":"POST","path":"/lists/{artifactId}/import","permission":"lists:write","pathParams":["artifactId"]},
   {"id":"lists.get","group":"lists","summary":"Get one saved search / list by artifact id.","cli":"dench lists show","method":"GET","path":"/lists/{artifactId}","permission":"lists:read","pathParams":["artifactId"]},
   {"id":"lists.save","group":"lists","summary":"Save find results as a named list (rows + filters become a workspace artifact).","cli":"dench lists save","method":"POST","path":"/lists","permission":"lists:write","pathParams":[]},

package/lib/command-registry.ts

@@ -943,6 +943,25 @@ const rawApiOperations = [
     responseSchema: anyResponse,
     backend: convex("action", "functions/workspaceArtifacts:listRows"),
   }),
+  op({
+    id: "lists.enrich",
+    group: "lists",
+    summary:
+      "Buy contact details for 1–100 saved profiles and save them to the list. Skips fields already found, looked up empty, or in flight. Requires a signed-in member or their personal agent.",
+    cli: "dench lists enrich",
+    method: "POST",
+    path: "/lists/{artifactId}/enrich",
+    requestSchema: z.object({
+      artifactId: z.string().min(1),
+      rows: z.array(z.record(z.string(), z.unknown())).min(1).max(100),
+      fields: z
+        .array(z.enum(["email", "phone", "personal_email"]))
+        .min(1)
+        .describe("email is work email."),
+    }),
+    responseSchema: anyResponse,
+    backend: convex("action", "functions/workspaceArtifacts:enrichSelected"),
+  }),
   op({
     id: "lists.import",
     group: "lists",