higherdata 0.2.2 → 0.3.0

package/README.md

@@ -222,3 +222,5 @@ The metadata request times out after three seconds. On network failure the CLI
 uses its last known policy; with no cached policy it allows the command. Failed
 checks are cached for a day too. A read-only cache directory allows commands but
 cannot persist the daily check, so subsequent invocations may check again.
+
+Download the loaded search page to a new file with `higherdata search companies --country-code CA --out results.csv`. Add `--all` to download up to 5,000 rows, or use a `.jsonl` destination for JSON Lines. The interactive results screen offers "This page" and "All results" when you press `d`. For larger sets, save the search to a list and export the list. Existing files are never overwritten.

package/dist/index.js

@@ -28133,6 +28133,10 @@ function retryAfter(response, data, now) {
     const date5 = Date.parse(value);
     if (Number.isFinite(date5)) return Math.max(0, (date5 - now) / 1e3);
   }
+  if (response.status === 429) {
+    const reset = response.headers.get("ratelimit-reset");
+    if (reset !== null && /^\d+(?:\.\d+)?$/.test(reset.trim())) return Number(reset);
+  }
   const parsed = failure2.safeParse(data);
   return parsed.success && typeof parsed.data.error !== "string" ? parsed.data.error.retry_after : void 0;
 }
@@ -28340,8 +28344,16 @@ var init_api2 = __esm({
       async request(path2, input2, options = {}) {
         if (options.authenticated && !this.settings.apiKey) throw new CliError("Run higherdata login or set HIGHERDATA_API_KEY.", EXIT_CODES.AUTH);
         try {
-          const response = await this.transport.request(path2, input2, { ...options, idempotencyKey: this.settings.idempotencyKey });
-          return { status: response.status, data: response.data };
+          for (let attempt = 0; ; attempt++) {
+            try {
+              return await this.transport.request(path2, input2, { ...options, idempotencyKey: this.settings.idempotencyKey });
+            } catch (error63) {
+              if (!(error63 instanceof HigherDataError) || error63.status !== 429 || !options.rateLimitRecovery || attempt >= 5) throw error63;
+              const wait = (error63.retryAfter ?? 1) * 1e3;
+              if (!Number.isFinite(wait) || wait > 3e5) throw error63;
+              await options.rateLimitRecovery.sleep(Math.max(100, wait));
+            }
+          }
         } catch (error63) {
           if (error63 instanceof HigherDataError) {
             if (error63.status) throw apiFailure(error63.status, { error: { code: error63.code, message: error63.message } });
@@ -31914,7 +31926,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "higherdata",
-      version: "0.2.2",
+      version: "0.3.0",
       type: "module",
       bin: {
         higherdata: "dist/index.js"
@@ -34894,6 +34906,9 @@ function cell(value) {
   const text2 = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
   return text2.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
 }
+function lookupMatchColumns(row) {
+  return { kind: cell(row.kind), name: cell(row.label), details: cell(row.detail) };
+}
 function customerOutput(value) {
   if (Array.isArray(value)) return value.map(customerOutput);
   if (!value || typeof value !== "object") return value;
@@ -34903,10 +34918,10 @@ function renderOutput(value, mode) {
   value = customerOutput(value);
   if (mode === "json") return `${JSON.stringify(value)}
 `;
-  const records = Array.isArray(value.items) ? value.items : Array.isArray(value.candidates) ? value.candidates : [value];
+  const records = Array.isArray(value.items) ? value.items : Array.isArray(value.candidates) ? value.candidates : Array.isArray(value.matches) ? value.matches : [value];
   if (mode === "jsonl") return records.map((record2) => JSON.stringify(record2)).join("\n") + (records.length ? "\n" : "");
   if (!records.length) return "No results.\n";
-  const rows = records.map((record2) => record2);
+  const rows = records.map((record2) => Array.isArray(value.matches) ? lookupMatchColumns(record2) : record2);
   const columns = rows.some((row) => "companyName" in row) ? rows.some((row) => "fullName" in row) ? ["id", "fullName", "jobTitle", "companyName", "emailAddress"] : ["id", "companyName", "normalizedDomain", "headquartersCountryCode"] : Object.keys(rows[0]);
   const headings = columns.map((column) => column.replace(/([a-z])([A-Z])/gu, "$1 $2").toUpperCase());
   const widths = columns.map((column, index) => rows.reduce((width, row) => Math.min(64, Math.max(width, cell(row[column]).length)), headings[index].length));
@@ -34922,6 +34937,105 @@ var init_output = __esm({
   }
 });
 
+// ../../src/lib/csv/search-download.ts
+function csvCell(value) {
+  let text2 = value === null || value === void 0 ? "" : String(value);
+  if (/^[\s\u0000-\u001f]*[=+\-@]/.test(text2)) text2 = `'${text2}`;
+  return `"${text2.replaceAll('"', '""')}"`;
+}
+function pageCsv(headers, rows) {
+  const lines = [headers.map(csvCell).join(","), ...rows.map((row) => row.map(csvCell).join(","))];
+  return `${lines.join("\r\n")}\r
+`;
+}
+function companyPageCsv(items) {
+  return pageCsv(
+    [...COMPANY_DOWNLOAD_FIELDS],
+    items.map((item) => COMPANY_DOWNLOAD_FIELDS.map((field) => item[field]))
+  );
+}
+function peoplePageCsv(items) {
+  return pageCsv(
+    [...PEOPLE_DOWNLOAD_FIELDS],
+    items.map((item) => PEOPLE_DOWNLOAD_FIELDS.map((field) => item[field]))
+  );
+}
+function searchPageJsonl(kind, items) {
+  const fields = kind === "companies" ? COMPANY_DOWNLOAD_FIELDS : PEOPLE_DOWNLOAD_FIELDS;
+  return items.map((item) => JSON.stringify(Object.fromEntries(fields.map((field) => [field, item[field] ?? null]))) + "\n").join("");
+}
+var COMPANY_DOWNLOAD_FIELDS, PEOPLE_DOWNLOAD_FIELDS;
+var init_search_download = __esm({
+  "../../src/lib/csv/search-download.ts"() {
+    "use strict";
+    COMPANY_DOWNLOAD_FIELDS = ["id", "companyName", "normalizedDomain", "headquartersCountryCode", "industryLinkedin", "employeeCountEstimate"];
+    PEOPLE_DOWNLOAD_FIELDS = ["id", "fullName", "jobTitle", "companyName", "emailAddress", "countryCode"];
+  }
+});
+
+// src/search-download.ts
+import { open as open5 } from "fs/promises";
+function searchDownloadFormat(path2) {
+  if (!/\.(csv|jsonl)$/.test(path2)) throw new CliError("Choose a new .csv or .jsonl destination.");
+  return path2.endsWith(".jsonl") ? "jsonl" : "csv";
+}
+async function downloadSearch(api, name, input2, path2, options) {
+  const format2 = searchDownloadFormat(path2);
+  if (options.all && api.settings.idempotencyKey) throw new CliError("An idempotency key applies to one page. Omit --all.");
+  const file2 = await open5(path2, "wx", 384);
+  let count = 0, first = true, cursor = input2.cursor, loaded = options.loadedPage;
+  const seen = /* @__PURE__ */ new Set();
+  if (typeof cursor === "string") seen.add(cursor);
+  try {
+    while (true) {
+      let raw, headers;
+      if (loaded) {
+        raw = loaded;
+        loaded = void 0;
+      } else {
+        const response = await api.request(`/api/v1/tools/${name}`, { ...input2, ...cursor === void 0 ? {} : { cursor } }, { authenticated: true, rateLimitRecovery: options });
+        raw = response.data;
+        headers = response.headers;
+      }
+      const page = pageSchema2.safeParse(raw);
+      if (!page.success || page.data.items.some((item) => typeof item.id !== "string" || !(name === "search.companies" ? /^hdo_[a-f0-9]{32}$/ : /^hdp_[a-f0-9]{32}$/).test(item.id))) throw new CliError("The API returned an invalid search page.");
+      const items = page.data.items.slice(0, SEARCH_DOWNLOAD_CAP - count);
+      if (format2 === "jsonl") await file2.writeFile(searchPageJsonl(name === "search.companies" ? "companies" : "people", items));
+      else {
+        const csv = (name === "search.companies" ? companyPageCsv : peoplePageCsv)(items);
+        await file2.writeFile(first ? csv : csv.slice(csv.indexOf("\r\n") + 2));
+      }
+      first = false;
+      count += items.length;
+      options.progress?.(`Downloaded ${count.toLocaleString("en-US")} of 5,000`);
+      const next = page.data.nextCursor;
+      if (!options.all || !next || count === SEARCH_DOWNLOAD_CAP) return { rows: count, capped: !!options.all && count === SEARCH_DOWNLOAD_CAP && (!!next || items.length < page.data.items.length) };
+      if (seen.has(next)) throw new CliError("The API repeated a cursor. Pagination stopped.");
+      seen.add(next);
+      cursor = next;
+      if (headers?.get("ratelimit-remaining") === "0") {
+        const reset = headers.get("ratelimit-reset");
+        if (reset !== null && /^\d+(?:\.\d+)?$/.test(reset.trim())) await options.sleep(Number(reset) * 1e3);
+      }
+    }
+  } finally {
+    await file2.close();
+  }
+}
+var SEARCH_DOWNLOAD_CAP, SEARCH_DOWNLOAD_CAP_NOTICE, isSearchResults, pageSchema2;
+var init_search_download2 = __esm({
+  "src/search-download.ts"() {
+    "use strict";
+    init_zod();
+    init_search_download();
+    init_api2();
+    SEARCH_DOWNLOAD_CAP = 5e3;
+    SEARCH_DOWNLOAD_CAP_NOTICE = "Download stopped at 5,000 rows. Save the search to a list and export the list for larger sets.";
+    isSearchResults = (name) => name === "search.companies" || name === "search.people";
+    pageSchema2 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable() });
+  }
+});
+
 // ../../node_modules/smol-toml/dist/error.js
 function getLineColFromPtr(string4, ptr) {
   let lines = string4.slice(0, ptr).split(/\r?\n/);
@@ -37342,7 +37456,7 @@ var init_main = __esm({
 
 // src/install.ts
 import { constants } from "fs";
-import { access, chmod as chmod2, lstat, mkdir as mkdir3, open as open5, readFile as readFile3, readdir, rename as rename3, unlink as unlink3 } from "fs/promises";
+import { access, chmod as chmod2, lstat, mkdir as mkdir3, open as open6, readFile as readFile3, readdir, rename as rename3, unlink as unlink3 } from "fs/promises";
 import { execFile as execFile2 } from "child_process";
 import { promisify, isDeepStrictEqual } from "util";
 import { homedir as homedir2 } from "os";
@@ -37416,7 +37530,7 @@ async function safeParents(path2) {
   await mkdir3(dirname3(path2), { recursive: true, mode: 448 });
 }
 async function privateFile(path2, text2) {
-  const file2 = await open5(path2, "wx", 384);
+  const file2 = await open6(path2, "wx", 384);
   try {
     await file2.writeFile(text2, "utf8");
   } finally {
@@ -38049,7 +38163,7 @@ var init_model = __esm({
       ["account", "Account", "Usage, limits and API keys"],
       ["icp", "ICP", "Build your ideal customer profile"]
     ];
-    groupTools = (group) => TOOL_CATALOG.filter((tool) => tool.name.startsWith(`${group}.`));
+    groupTools = (group) => TOOL_CATALOG.filter((tool) => tool.name.startsWith(`${group}.`) && tool.name !== "lookup.find");
     toolByName = (name) => TOOL_CATALOG.find((tool) => tool.name === name);
     clean = (value) => String(value ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
     title = (value) => value.replaceAll("_", " ").replace(/([a-z])([A-Z])/gu, "$1 $2").replace(/\b\w/gu, (c) => c.toUpperCase());
@@ -38137,19 +38251,43 @@ var init_install_menu = __esm({
 });
 
 // src/terminal/banner.ts
-function bannerFrame(frame, columns) {
-  const full = Array.from({ length: 6 }, (_, row) => [..."HIGHERDATA"].map((letter) => GLYPHS[letter][row]).join(" "));
-  const visible = frame < 5 ? Math.ceil((frame + 1) / 5 * full[0].length) : full[0].length;
-  const indent = Math.max(0, Math.floor((columns - full[0].length) / 2));
-  const widths = [24, 12, 18], offsets = [0, 6, 3];
-  const logo = widths.flatMap((width, index) => {
-    const progress = Math.max(0, Math.min(1, (frame - 5 - index) / 2));
-    const line = " ".repeat(Math.max(0, Math.floor((columns - 24) / 2)) + offsets[index]) + "\u2588".repeat(Math.ceil(width * progress));
-    return [line, line, ""];
+function markFrame(size, progress = [1, 1, 1]) {
+  const scale = size === "large" ? 3 : 1;
+  return [8, 4, 6].flatMap((units, index) => {
+    const width = Math.round(units * scale * Math.max(0, Math.min(1, progress[index])));
+    const indent = " ".repeat([0, 2, 1][index] * scale);
+    const cap = width > 2 ? indent + " " + "\u2584".repeat(width - 2) : "";
+    const base2 = width ? indent + "\u2580".repeat(width) : "";
+    return size === "large" ? [cap, width ? indent + "\u2588".repeat(width) : "", cap.replaceAll("\u2584", "\u2580")] : [cap, base2];
+  });
+}
+function wordmarkFrame(frame = BANNER_FRAMES - 1) {
+  const visible = frame < 5 ? Math.ceil((frame + 1) / 5 * WORDMARK_WIDTH) : WORDMARK_WIDTH;
+  return Array.from({ length: 6 }, (_, row) => {
+    const higher = [..."HIGHER"].map((letter) => GLYPHS[letter][row]).join(" ") + " ";
+    const data = [..."DATA"].map((letter) => GLYPHS[letter][row]).join(" ");
+    return { higher: higher.slice(0, visible), data: data.slice(0, Math.max(0, visible - higher.length)) };
   });
-  return [...full.map((line) => " ".repeat(indent) + line.slice(0, visible)), "", ...logo, frame >= 10 ? " ".repeat(Math.max(0, Math.floor((columns - 23) / 2))) + "HIGHERDATA by HigherOps" : ""].map((line) => line.trimEnd());
 }
-var GLYPHS, BANNER_FRAMES, BANNER_DURATION_MS, SMALL_MARK, shouldAnimate;
+function homeBrandLayout(columns, rows, extraRows = 0) {
+  const sideBySide = columns - 4 >= WORDMARK_WIDTH + 3 + MARK_WIDTH;
+  const headerRows = sideBySide ? 10 : 17;
+  return { large: columns - 4 >= WORDMARK_WIDTH && rows >= headerRows + 14 + extraRows, sideBySide, headerRows };
+}
+function busyFrame(frame, size = "large") {
+  return markFrame(size, [0, 1, 2].map((index) => 0.65 + 0.35 * (1 + Math.sin(frame * Math.PI / 4 - index * Math.PI / 2)) / 2));
+}
+function bannerFrame(frame, columns) {
+  const wordmark = wordmarkFrame(frame).map((line) => line.higher + line.data);
+  const indent = " ".repeat(Math.max(0, Math.floor((columns - WORDMARK_WIDTH) / 2)));
+  const logo = markFrame("large", [0, 1, 2].map((index) => Math.max(0, Math.min(1, (frame - 5 - index) / 2))));
+  const markIndent = " ".repeat(Math.max(0, Math.floor((columns - MARK_WIDTH) / 2)));
+  return [...wordmark.map((line) => indent + line), "", ...logo.map((line) => markIndent + line), frame >= 10 ? " ".repeat(Math.max(0, Math.floor((columns - 23) / 2))) + "HIGHERDATA by HigherOps" : ""].map((line) => line.trimEnd());
+}
+function animationOptions(args = process.argv.slice(2)) {
+  return { banner: !args.includes("--no-banner"), json: args.includes("--json"), jsonl: args.includes("--jsonl") };
+}
+var GLYPHS, BANNER_FRAMES, BANNER_DURATION_MS, MARK_WIDTH, WORDMARK_WIDTH, shouldAnimate;
 var init_banner = __esm({
   "src/terminal/banner.ts"() {
     "use strict";
@@ -38165,13 +38303,15 @@ var init_banner = __esm({
     };
     BANNER_FRAMES = 11;
     BANNER_DURATION_MS = 1210;
-    SMALL_MARK = ["\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588", "  \u2588\u2588\u2588\u2588  ", " \u2588\u2588\u2588\u2588\u2588\u2588 "];
+    MARK_WIDTH = 24;
+    WORDMARK_WIDTH = [..."HIGHERDATA"].reduce((width, letter) => width + GLYPHS[letter][0].length, "HIGHERDATA".length - 1);
     shouldAnimate = (tty, options, env) => tty && options.banner !== false && !options.json && !options.jsonl && !Object.hasOwn(env, "CI");
   }
 });
 
 // src/terminal/screens.tsx
-import { Box, Text } from "ink";
+import { useEffect, useState } from "react";
+import { Box, Text, useStdout } from "ink";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function Menu({ items, selected, limit, color, width }) {
   const start = Math.max(0, Math.min(selected - Math.floor(limit / 2), items.length - limit));
@@ -38194,17 +38334,54 @@ function Menu({ items, selected, limit, color, width }) {
     ] })
   ] });
 }
+function Mark({ lines, color }) {
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: lines.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line || " " }, i)) });
+}
+function Wordmark({ color, frame }) {
+  return /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: WORDMARK_WIDTH, children: wordmarkFrame(frame).map((line, i) => /* @__PURE__ */ jsxs(Text, { children: [
+    line.higher,
+    /* @__PURE__ */ jsx(Text, { color, children: line.data })
+  ] }, i)) });
+}
+function BusyMark({ color, size = "large", options = animationOptions(), env = process.env }) {
+  const { stdout } = useStdout(), [frame, setFrame] = useState(0);
+  const animate = shouldAnimate(Boolean(stdout.isTTY), options, env);
+  useEffect(() => {
+    if (!animate) return;
+    const timer = setInterval(() => setFrame((value) => (value + 1) % 8), 120);
+    return () => clearInterval(timer);
+  }, [animate]);
+  return /* @__PURE__ */ jsx(Mark, { lines: animate ? busyFrame(frame, size) : markFrame(size), color });
+}
 function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "default", space = "Default", workspace = "HigherOps", remaining = "--" }) {
   const width = Math.max(40, columns), color = colors ? "#f2b705" : void 0;
-  const limit = Math.max(4, rows - 12);
+  const limit = Math.max(4, rows - 15);
+  const extraRows = [state.error, state.notice].reduce((count, text2) => count + Math.ceil(clean(text2).length / (width - 4)), 0);
+  const brand = homeBrandLayout(width, rows, extraRows), largeHome = state.screen === "home" && brand.large;
   if (state.screen === "banner") return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, children: [
-    bannerFrame(state.frame, width).map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)),
+    /* @__PURE__ */ jsx(Box, { paddingLeft: Math.max(0, Math.floor((width - WORDMARK_WIDTH) / 2)), children: /* @__PURE__ */ jsx(Wordmark, { color, frame: state.frame }) }),
+    /* @__PURE__ */ jsx(Text, { children: " " }),
+    /* @__PURE__ */ jsx(Mark, { lines: bannerFrame(state.frame, width).slice(7, 16), color }),
+    /* @__PURE__ */ jsx(Text, { dimColor: true, children: bannerFrame(state.frame, width)[16] || " " }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Press any key to start" })
   ] });
   const fields = state.tool ? fieldsFor(state.tool.input, state.input, state.variant) : [];
   let help = "Up/Down choose. Enter opens. Esc back. Ctrl+C quit.";
   let content;
-  if (state.screen === "home") content = /* @__PURE__ */ jsx(Menu, { items: homeItems, selected: state.selected, limit: Math.max(4, rows - 14), color, width: width - 4 });
+  if (state.screen === "home") help = "Up/Down choose. Enter opens. / Look up. Ctrl+C quit.";
+  if (state.screen === "home") content = /* @__PURE__ */ jsx(Menu, { items: homeItems, selected: state.selected, limit: Math.max(4, rows - (largeHome ? brand.headerRows : 6) - 8 - extraRows), color, width: width - 4 });
+  if (state.screen === "lookup") {
+    content = /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "Look up" }),
+      /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Name, work email, international phone, domain, LinkedIn or record id" }),
+      /* @__PURE__ */ jsxs(Text, { color, wrap: "wrap", children: [
+        "> ",
+        clean(state.text),
+        "_"
+      ] })
+    ] });
+    help = "Type or paste. Enter looks up. Esc home.";
+  }
   if (state.screen === "install") {
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
       /* @__PURE__ */ jsxs(Text, { bold: true, children: [
@@ -38275,6 +38452,12 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
     ] });
     help = "Enter edit/run. Arrays: comma separated. Blank clears. Esc back.";
   }
+  if (state.screen === "download-choice") {
+    content = /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsx(Text, { bold: true, children: "Download search results" }),
+      /* @__PURE__ */ jsx(Menu, { items: [{ label: "This page", hint: "Loaded rows, no new request" }, { label: "All results", hint: "Same search, up to 5,000 rows" }], selected: state.selected, limit: 2, color, width: width - 4 })
+    ] });
+  }
   if (["edit", "upload", "download", "space"].includes(state.screen)) {
     const field = fields.find((field2) => field2.path === state.field);
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -38296,7 +38479,7 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
   }
   if (state.screen === "busy") {
     content = /* @__PURE__ */ jsxs(Fragment, { children: [
-      SMALL_MARK.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)),
+      /* @__PURE__ */ jsx(BusyMark, { color, size: rows >= 28 ? "large" : "compact" }),
       /* @__PURE__ */ jsx(Text, { children: state.notice || "Working..." })
     ] });
     help = "The current operation is running. It is never retried automatically.";
@@ -38315,35 +38498,58 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
   }
   if (state.screen === "results") {
     const items = rowsOf(state.result);
-    const list = state.tool?.name === "lists.get" && state.input.id && Array.isArray(state.result.lists) ? state.result.lists[0] : void 0;
-    content = /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx(Text, { bold: true, children: state.tool?.name ?? "Enrichment job" }),
-      list && /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
-        clean(list.name),
-        " / ",
-        clean(list.type),
-        " / ",
-        list.recurringEnabled ? "Each release" : "On demand",
-        " / ",
-        clean(list.maxRecords),
-        " records / ",
-        clean(list.maxNewRecordsPerRefresh),
-        " new records per refresh"
-      ] }),
-      items.length ? /* @__PURE__ */ jsx(Menu, { items: items.map((row) => ({ label: rowLabel(row), hint: row.matchesCriteria === false ? "No longer matches" : clean(row.status ?? row.jobTitle ?? row.normalizedDomain ?? row.domain ?? row.headquartersCountryCode) })), selected: state.selected, limit: limit - (list ? 3 : 2), color, width: width - 4 }) : recordFields(state.result).slice(state.selected, state.selected + limit).map(([key, value]) => /* @__PURE__ */ jsxs(Text, { wrap: "truncate-end", children: [
-        key,
-        ": ",
-        value
-      ] }, key)),
-      /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
-        items.length ? `${items.length} on this page. ` : "",
-        state.result.nextCursor ? "More records available." : "End of page."
-      ] })
-    ] });
-    help = "Enter detail. N next page. R refresh. D download. E edit inputs. Esc back.";
-    if (!state.tool) help = "E installation options. Esc home. ";
-    if (state.tool?.name === "searches.list") help = "Enter reopen search. A create audience. N next page. E edit. Esc back.";
-    if (state.tool?.name === "lists.get" && state.input.id) help += " P preview refresh.";
+    if (state.tool?.name === "lookup.find") {
+      content = /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+          "Look up: ",
+          clean(state.input.query)
+        ] }),
+        items.length ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx(Text, { dimColor: true, children: "KIND / NAME / DETAILS" }),
+          /* @__PURE__ */ jsx(Menu, { items: items.map((row) => {
+            const match = lookupMatchColumns(row);
+            return { label: `${match.kind}: ${match.name}`, hint: match.details };
+          }), selected: state.selected, limit: limit - 2, color, width: width - 4 })
+        ] }) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsxs(Text, { children: [
+            "No match for ",
+            clean(state.input.query)
+          ] }),
+          /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Try Search to find companies or people with filters." })
+        ] })
+      ] });
+      help = "Enter detail. E edit lookup. Esc home.";
+    } else {
+      const list = state.tool?.name === "lists.get" && state.input.id && Array.isArray(state.result.lists) ? state.result.lists[0] : void 0;
+      content = /* @__PURE__ */ jsxs(Fragment, { children: [
+        /* @__PURE__ */ jsx(Text, { bold: true, children: state.tool?.name ?? "Enrichment job" }),
+        list && /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
+          clean(list.name),
+          " / ",
+          clean(list.type),
+          " / ",
+          list.recurringEnabled ? "Each release" : "On demand",
+          " / ",
+          clean(list.maxRecords),
+          " records / ",
+          clean(list.maxNewRecordsPerRefresh),
+          " new records per refresh"
+        ] }),
+        items.length ? /* @__PURE__ */ jsx(Menu, { items: items.map((row) => ({ label: rowLabel(row), hint: row.matchesCriteria === false ? "No longer matches" : clean(row.status ?? row.jobTitle ?? row.normalizedDomain ?? row.domain ?? row.headquartersCountryCode) })), selected: state.selected, limit: limit - (list ? 3 : 2), color, width: width - 4 }) : recordFields(state.result).slice(state.selected, state.selected + limit).map(([key, value]) => /* @__PURE__ */ jsxs(Text, { wrap: "truncate-end", children: [
+          key,
+          ": ",
+          value
+        ] }, key)),
+        /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+          items.length ? `${items.length} on this page. ` : "",
+          state.result.nextCursor ? "More records available." : "End of page."
+        ] })
+      ] });
+      help = "Enter detail. N next page. R refresh. D download. E edit inputs. Esc back.";
+      if (!state.tool) help = "E installation options. Esc home. ";
+      if (state.tool?.name === "searches.list") help = "Enter reopen search. A create audience. N next page. E edit. Esc back.";
+      if (state.tool?.name === "lists.get" && state.input.id) help += " P preview refresh.";
+    }
   }
   if (state.screen === "detail") {
     const row = detailRecord(state.row), isCore = coreRecord(state.row);
@@ -38390,26 +38596,45 @@ function TerminalScreen({ state, columns, rows = 28, colors = true, profile = "d
     help = "Enter sends. Ctrl+B step limit. Ctrl+N new conversation. Esc home.";
   }
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", width, borderStyle: "double", paddingX: 1, children: [
-    /* @__PURE__ */ jsxs(Box, { justifyContent: "space-between", children: [
+    largeHome ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      /* @__PURE__ */ jsxs(Box, { flexDirection: brand.sideBySide ? "row" : "column", gap: brand.sideBySide ? 3 : 1, children: [
+        /* @__PURE__ */ jsx(Wordmark, { color }),
+        /* @__PURE__ */ jsx(Mark, { lines: markFrame("large"), color })
+      ] }),
+      /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
+        "by HigherOps / ",
+        clean(profile),
+        " / ",
+        clean(workspace),
+        " / ",
+        clean(space),
+        " / ",
+        clean(remaining),
+        " email verifications remaining"
+      ] })
+    ] }) : /* @__PURE__ */ jsxs(Box, { justifyContent: "space-between", children: [
       /* @__PURE__ */ jsxs(Box, { gap: 1, children: [
-        /* @__PURE__ */ jsx(Box, { flexDirection: "column", children: SMALL_MARK.map((line, i) => /* @__PURE__ */ jsx(Text, { color, children: line }, i)) }),
+        /* @__PURE__ */ jsx(Mark, { lines: markFrame("compact"), color }),
         /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
-          /* @__PURE__ */ jsx(Text, { bold: true, color, children: "HIGHERDATA" }),
+          /* @__PURE__ */ jsxs(Text, { bold: true, children: [
+            "Higher",
+            /* @__PURE__ */ jsx(Text, { color, children: "Data" })
+          ] }),
           /* @__PURE__ */ jsx(Text, { dimColor: true, children: "by HigherOps" }),
           /* @__PURE__ */ jsx(Text, { dimColor: true, children: clean(profile) })
         ] })
       ] }),
-      /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "flex-end", children: [
+      /* @__PURE__ */ jsxs(Box, { flexDirection: "column", alignItems: "flex-end", flexShrink: 1, children: [
         /* @__PURE__ */ jsx(Text, { wrap: "truncate-end", children: clean(workspace) }),
         /* @__PURE__ */ jsx(Text, { dimColor: true, wrap: "truncate-end", children: clean(space) }),
-        /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+        /* @__PURE__ */ jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [
           clean(remaining),
           " email verifications remaining"
         ] })
       ] })
     ] }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, children: "\u2550".repeat(Math.max(1, width - 4)) }),
-    /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: width - 4, minHeight: Math.min(rows - 7, 16), children: content }),
+    /* @__PURE__ */ jsx(Box, { flexDirection: "column", width: width - 4, minHeight: largeHome ? 0 : Math.max(0, Math.min(rows - 16, 13)), children: content }),
     state.error && /* @__PURE__ */ jsx(Text, { color: colors ? "red" : void 0, children: clean(state.error) }),
     state.notice && state.screen !== "busy" && /* @__PURE__ */ jsx(Text, { dimColor: true, children: clean(state.notice) }),
     /* @__PURE__ */ jsx(Text, { dimColor: true, wrap: "wrap", children: help })
@@ -38419,6 +38644,7 @@ var initialState, accountItems, homeItems;
 var init_screens = __esm({
   "src/terminal/screens.tsx"() {
     "use strict";
+    init_output();
     init_tool_commands();
     init_banner();
     init_install_menu();
@@ -38432,8 +38658,8 @@ var init_screens = __esm({
       { id: "skills-install", label: "Install skills", hint: "Five task guides for Claude Code or Codex" },
       { id: "quit", label: "Quit", hint: "" }
     ];
-    homeItems = [["Find", ["search", "searches", "lookup", "icp", "ask"]], ["Work", ["lists", "enrich", "email", "jobs"]], ["Govern", ["suppress", "crm", "changes", "hygiene"]], ["Account", ["account"]]].flatMap(([section, ids]) => ids.map((id, index) => {
-      const group = GROUPS.find(([name]) => name === id);
+    homeItems = [["Find", ["find", "search", "searches", "lookup", "icp", "ask"]], ["Work", ["lists", "enrich", "email", "jobs"]], ["Govern", ["suppress", "crm", "changes", "hygiene"]], ["Account", ["account"]]].flatMap(([section, ids]) => ids.map((id, index) => {
+      const group = id === "find" ? ["find", "Look up", "Name, email, phone, domain, LinkedIn or record id"] : GROUPS.find(([name]) => name === id);
       return { id, label: group?.[1] ?? "Ask HigherData", hint: group?.[2] ?? "Plan a request, limit its steps", section: index === 0 ? section : "" };
     }));
   }
@@ -38448,25 +38674,25 @@ __export(app_exports, {
 });
 import { randomUUID as randomUUID6 } from "crypto";
 import { createReadStream as createReadStream2 } from "fs";
-import { open as open6 } from "fs/promises";
-import { useEffect, useRef, useState } from "react";
+import { open as open7 } from "fs/promises";
+import { useEffect as useEffect2, useRef, useState as useState2 } from "react";
 import { render, useApp, useInput, useWindowSize } from "ink";
 import { jsx as jsx2 } from "react/jsx-runtime";
 function InteractiveApp({ session }) {
   const { exit } = useApp(), { columns, rows } = useWindowSize();
   const settings = session.settings();
-  const [chrome, setChrome] = useState({ workspace: "Workspace", remaining: "--" });
-  const [state, setState] = useState(() => ({ ...initialState(), screen: shouldAnimate(true, session.options, session.runtime.env) ? "banner" : "home" }));
+  const [chrome, setChrome] = useState2({ workspace: "Workspace", remaining: "--" });
+  const [state, setState] = useState2(() => ({ ...initialState(), screen: shouldAnimate(true, session.options, session.runtime.env) ? "banner" : "home" }));
   const current = useRef(state);
   current.current = state;
   const mounted = useRef(true), request = useRef(false), back = useRef(initialState());
-  useEffect(() => {
+  useEffect2(() => {
     mounted.current = true;
     return () => {
       mounted.current = false;
     };
   }, []);
-  useEffect(() => {
+  useEffect2(() => {
     let active = true;
     if (!settings.apiKey || !settings.space) return;
     void Promise.all([session.call("account.whoami", {}), session.call("account.usage", {})]).then(([identity, usage]) => {
@@ -38479,12 +38705,12 @@ function InteractiveApp({ session }) {
       active = false;
     };
   }, [session, settings.apiKey, settings.space]);
-  useEffect(() => {
+  useEffect2(() => {
     if (state.screen !== "banner") return;
     const timer = setInterval(() => setState((s) => s.frame >= BANNER_FRAMES - 1 ? { ...s, screen: "home" } : { ...s, frame: s.frame + 1 }), BANNER_DURATION_MS / BANNER_FRAMES);
     return () => clearInterval(timer);
   }, [state.screen]);
-  useEffect(() => {
+  useEffect2(() => {
     const job = state.result.job;
     const id = job?.id ?? (state.tool?.name === "jobs.get" ? state.result.id : void 0);
     const status = job?.status ?? state.result.status;
@@ -38542,6 +38768,7 @@ function InteractiveApp({ session }) {
   function activate(item) {
     const s = current.current;
     if (item.id === "quit") exit();
+    else if (item.id === "find") patch({ screen: "lookup", tool: toolByName("lookup.find"), input: {}, text: "", selected: 0 });
     else if (item.id === "mcp-install" || item.id === "skills-install") patch({ screen: "install", group: item.id === "mcp-install" ? "mcp" : "skills", tool: null, input: { agent: "claude", scope: "user", profile: "default" }, selected: 0 });
     else if (item.id === "space") {
       back.current = s;
@@ -38568,12 +38795,27 @@ function InteractiveApp({ session }) {
       return;
     }
     if (s.screen === "busy") return;
+    if (s.screen === "home" && input2 === "/") {
+      activate({ id: "find" });
+      return;
+    }
     if (key.escape && s.screen === "filter-group") {
       patch({ screen: "form", selected: searchGroups(s.tool.input, s.input).findIndex((group) => group.group === s.filterGroup) });
       return;
     }
     if (key.escape) {
-      patch(s.screen === "home" ? { screen: "home" } : ["edit", "download", "space", "upload"].includes(s.screen) ? { ...back.current } : { screen: s.screen === "detail" ? "results" : s.screen === "form" ? "tools" : "home", selected: 0 });
+      patch(s.screen === "home" ? { screen: "home" } : ["edit", "download", "download-choice", "space", "upload"].includes(s.screen) ? { ...back.current } : { screen: s.screen === "detail" ? "results" : s.screen === "form" ? "tools" : "home", selected: 0 });
+      return;
+    }
+    if (s.screen === "lookup") {
+      if (key.return && s.text.trim()) void work("Looking up your record...", () => session.lookup(s.text));
+      else if (key.backspace || key.delete) patch({ text: s.text.slice(0, -1) });
+      else if (!key.return && !key.ctrl && !key.meta && !key.upArrow && !key.downArrow) patch({ text: s.text + input2 });
+      return;
+    }
+    if (s.screen === "download-choice") {
+      if (key.upArrow || key.downArrow) patch({ selected: s.selected === 0 ? 1 : 0 });
+      else if (key.return) patch({ screen: "download", field: "New destination .csv or .jsonl file", text: "" });
       return;
     }
     if (["edit", "download", "space", "upload"].includes(s.screen)) {
@@ -38587,8 +38829,10 @@ function InteractiveApp({ session }) {
         }
         if (s.screen === "download") {
           void work("Downloading into a new file...", async () => {
-            await session.download(back.current, s.text);
-            return { ...back.current, notice: `Saved ${s.text}` };
+            const notice = await session.download(back.current, s.text, { all: isSearchResults(back.current.tool?.name) && s.selected === 1, progress: (text2) => {
+              if (mounted.current) patch({ notice: text2 });
+            } });
+            return { ...back.current, notice: `Saved ${s.text}${notice ? `. ${notice}` : ""}` };
           });
           return;
         }
@@ -38697,15 +38941,15 @@ function InteractiveApp({ session }) {
         patch({ input: { ...s.input, cursor: s.result.nextCursor } });
         void work("Loading the next page...", async () => ({ screen: "results", selected: 0, input: { ...s.input, cursor: s.result.nextCursor }, result: await session.call(s.tool.name, { ...s.input, cursor: s.result.nextCursor }) }));
       } else if (input2 === "r" && s.tool) runTool(!needsConfirmation(s.tool));
-      else if (input2 === "e") patch({ screen: s.tool ? "form" : "install", selected: 0 });
+      else if (input2 === "e") patch({ screen: s.tool?.name === "lookup.find" ? "lookup" : s.tool ? "form" : "install", text: s.tool?.name === "lookup.find" ? String(s.input.query ?? "") : s.text, selected: 0 });
       else if (input2 === "d") {
         back.current = s;
-        patch({ screen: "download", field: "New destination .csv or .jsonl file", text: "" });
+        patch({ screen: isSearchResults(s.tool?.name) ? "download-choice" : "download", selected: 0, field: "New destination .csv or .jsonl file", text: "" });
       } else if (input2 === "a" && s.tool?.name === "searches.list") {
         const row = rowsOf(s.result)[s.selected];
         if (row) form("lists.create", { type: "audience", savedSearchId: row.id, recurringEnabled: true, maxRecords: 1e3, maxNewRecordsPerRefresh: 1e3, removeNonmatches: false });
       } else if (input2 === "p" && s.tool?.name === "lists.get" && typeof s.input.id === "string") form("lists.refresh", { id: s.input.id, maxNewRecords: 1e3 });
-      else if (key.return) {
+      else if (key.return && (rowsOf(s.result).length || s.tool?.name !== "lookup.find")) {
         void work("Opening the record...", () => session.openRow(s));
       }
     } else if (s.screen === "detail") {
@@ -38735,6 +38979,7 @@ var TerminalSession;
 var init_app = __esm({
   "src/terminal/app.tsx"() {
     "use strict";
+    init_search_download2();
     init_tool_commands();
     init_api2();
     init_config();
@@ -38758,6 +39003,12 @@ var init_app = __esm({
       async load() {
         this.config = await this.runtime.readConfig();
       }
+      async lookup(query) {
+        const result = await this.call("lookup.find", { query });
+        const state = { ...initialState(), screen: "results", tool: toolByName("lookup.find"), input: { query }, result };
+        if (result.exactMatch === true && rowsOf(result).length === 1) return { ...state, ...await this.openRow(state) };
+        return state;
+      }
       settings() {
         return resolveSettings(this.config, this.options, this.runtime.env);
       }
@@ -38787,15 +39038,22 @@ var init_app = __esm({
         this.config.profiles[this.config.activeProfile] = { apiUrl: settings.apiUrl, apiKey: key };
         await this.runtime.writeConfig(this.config);
       }
-      async download(state, path2) {
+      async download(state, path2, options = {}) {
         if (!path2.trim()) throw new CliError("Enter a new destination file.");
         path2 = path2.trim();
         if (!/\.(csv|jsonl)$/.test(path2)) throw new CliError("Choose a new .csv or .jsonl destination.");
+        if (isSearchResults(state.tool?.name)) {
+          const input2 = { ...state.input };
+          const loadedPage = !options.all || !input2.cursor ? state.result : void 0;
+          if (options.all) delete input2.cursor;
+          const result = await downloadSearch(this.api(), state.tool.name, input2, path2, { ...options, loadedPage, sleep: this.runtime.sleep });
+          return result.capped ? SEARCH_DOWNLOAD_CAP_NOTICE : "";
+        }
         const job = state.result.job;
         const jobId = state.result.jobId ?? job?.id ?? (state.tool?.name.startsWith("jobs.") ? state.result.id ?? state.input.jobId : void 0);
         const exportTool = state.tool?.name === "lists.get" && state.input.id ? "lists.export" : state.tool?.name;
         if (typeof jobId !== "string" && !["lists.export", "suppress.export"].includes(exportTool ?? "")) throw new CliError("Open a completed job or a list export to download a file.");
-        const file2 = await open6(path2.trim(), "wx", 384);
+        const file2 = await open7(path2.trim(), "wx", 384);
         try {
           const format2 = path2.endsWith(".jsonl") ? "jsonl" : "csv";
           if (typeof jobId === "string") await downloadBulkJob(this.api(), jobId, format2, async (text2) => {
@@ -38935,11 +39193,12 @@ async function buildFilters(api, options, kind) {
 
 // src/commands.ts
 init_output();
+init_search_download2();
 
 // src/pagination.ts
 init_zod();
 init_api2();
-var pageSchema2 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
+var pageSchema3 = external_exports.object({ items: external_exports.array(external_exports.record(external_exports.string(), external_exports.unknown())).max(50), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
 var exportSchema = external_exports.object({ content: external_exports.string(), mimeType: external_exports.enum(["text/csv", "application/x-ndjson"]), nextCursor: external_exports.string().min(1).max(2048).nullable(), zeroResults: external_exports.boolean() });
 async function pagedTool(api, name, input2, all, exporting = false) {
   if (all && api.settings.idempotencyKey) throw new CliError("An idempotency key applies to one page. Omit --all.");
@@ -38952,7 +39211,7 @@ async function pagedTool(api, name, input2, all, exporting = false) {
   let empty = true;
   while (true) {
     const raw = await api.tool(name, { ...input2, ...cursor === void 0 ? {} : { cursor } });
-    const page = (exporting ? exportSchema : pageSchema2).safeParse(raw);
+    const page = (exporting ? exportSchema : pageSchema3).safeParse(raw);
     if (!page.success) throw new CliError("The API returned an invalid cursor page.");
     if ("items" in page.data) records.push(...page.data.items);
     else {
@@ -39246,10 +39505,18 @@ function registerCommands(program2, runtime) {
     emit(identity, mode);
   });
   const search = program2.command("search").description("Search HigherData Core");
-  for (const kind of ["companies", "people"]) pageOptions(excludeList(addFilterOptions(search.command(kind).description(`Find ${kind}`), kind === "people"))).action(async (options, command) => {
+  for (const kind of ["companies", "people"]) pageOptions(excludeList(addFilterOptions(search.command(kind).description(`Find ${kind}`), kind === "people"))).option("--out <path>", "Download to a new .csv or .jsonl file (up to 5,000 rows with --all)").action(async (options, command) => {
     const { api, mode } = await session(command);
+    if (options.out) searchDownloadFormat(options.out);
     const filters = await buildFilters(api, options, kind);
-    emit(await pagedTool(api, `search.${kind}`, { ...filters, limit: options.limit, ...options.cursor ? { cursor: options.cursor } : {}, ...excluded(options) }, Boolean(options.all)), mode);
+    const input2 = { ...filters, limit: options.limit, ...options.cursor ? { cursor: options.cursor } : {}, ...excluded(options) };
+    if (options.out) {
+      const result = await downloadSearch(api, `search.${kind}`, input2, options.out, { all: Boolean(options.all), sleep: runtime.sleep, progress: (text2) => runtime.err(`${text2}
+`) });
+      if (result.capped) runtime.err(`${SEARCH_DOWNLOAD_CAP_NOTICE}
+`);
+      emit({ path: options.out, ...result }, mode);
+    } else emit(await pagedTool(api, `search.${kind}`, input2, Boolean(options.all)), mode);
   });
   addFilterOptions(program2.command("count").description("Estimate companies and their contacts")).action(async (options, command) => {
     const { api, mode } = await session(command);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "higherdata",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "type": "module",
   "bin": {
     "higherdata": "dist/index.js"