higherdata 0.4.0 → 0.5.0

package/README.md

@@ -251,3 +251,11 @@ higherdata config set auto-update true
 Explicit `higherdata update` remains available with an opt-out or a server
 minimum-version refusal. Users on 0.3.0 must reinstall once to obtain the update
 command: `npm install --global higherdata@latest`.
+
+### Credentials and diagnostics
+
+The CLI stores saved API keys in macOS Keychain, Windows Credential Manager, or Linux Secret Service (for example GNOME Keyring or KWallet). Existing plaintext profiles migrate on first use. Config files retain only a keychain reference. On platforms without a supported keychain, or when a persistent Linux service is absent, the CLI keeps the existing file fallback with mode 0600. A missing native binding, locked store or inaccessible keychain returns an error rather than downgrading credentials. `higherdata logout` removes the active profile's keychain entry. `HIGHERDATA_API_KEY` remains available for CI.
+
+Server failures print the error code, user-safe message and request id to stderr. JSON and JSONL results stay on stdout. Non-interactive commands also print a one-line newer-version notice on stderr using the existing daily compatibility check.
+
+When `higherdata tools email.find` returns `status: ambiguous`, select an opaque id from `companyCandidates` and retry with `--company-id`. This choice does not submit verification requests. An exact match to one primary domain is selected automatically when the complete company match set is available.

package/dist/index.js

@@ -20487,11 +20487,50 @@ var init_zod = __esm({
   }
 });
 
+// src/keychain.ts
+async function nativeKeychain(platform = process.platform, load = () => import("@napi-rs/keyring")) {
+  if (!["darwin", "linux", "win32"].includes(platform)) return null;
+  let binding;
+  try {
+    binding = await load();
+  } catch {
+    return null;
+  }
+  const entry = (account) => new binding.AsyncEntry(service, account, { linux: { store: "secret-service" } });
+  try {
+    entry("availability");
+  } catch (error63) {
+    const message = error63 instanceof Error ? error63.message : "";
+    if (platform === "linux" && /org\.freedesktop\.DBus\.Error\.(?:ServiceUnknown|NameHasNoOwner)|DBUS_SESSION_BUS_ADDRESS|Unable to autolaunch a dbus-daemon|Failed to connect to socket|No such file or directory/u.test(message)) return null;
+    throw error63;
+  }
+  return {
+    get: (account) => entry(account).getPassword(AbortSignal.timeout(3e3)),
+    set: (account, secret) => entry(account).setPassword(secret, AbortSignal.timeout(3e3)),
+    remove: async (account) => {
+      await entry(account).deleteCredential(AbortSignal.timeout(3e3));
+    }
+  };
+}
+var service, systemKeychain;
+var init_keychain = __esm({
+  "src/keychain.ts"() {
+    "use strict";
+    service = "io.higherdata.cli";
+    systemKeychain = () => nativeKeychain();
+  }
+});
+
 // src/config.ts
 import { chmod, mkdir, open as open2, readFile, rename, unlink } from "fs/promises";
 import { homedir } from "os";
 import { dirname, join } from "path";
 import { randomUUID } from "crypto";
+function warnAboutFileKeychainFallback() {
+  if (warnedAboutFileKeychainFallback) return;
+  warnedAboutFileKeychainFallback = true;
+  process.stderr.write("HigherData could not access a system keychain. Credentials will be stored in the config file with 0600 permissions.\n");
+}
 function configPath(home = homedir()) {
   return join(home, ".config", "higherdata", "config.json");
 }
@@ -20500,7 +20539,7 @@ function validateConfig(value) {
   if (!result.success) throw new ConfigError("Invalid HigherData config: check profiles and activeProfile");
   return result.data;
 }
-async function readConfig(path2 = configPath()) {
+async function readDiskConfig(path2) {
   let contents2;
   try {
     contents2 = await readFile(path2, "utf8");
@@ -20519,8 +20558,56 @@ async function readConfig(path2 = configPath()) {
   }
   return validateConfig(value);
 }
-async function writeConfig(config2, path2 = configPath()) {
+async function readConfig(path2 = configPath(), loadKeychain = systemKeychain) {
+  let config2 = await readDiskConfig(path2);
+  if (!Object.values(config2.profiles).some((profile) => profile.apiKey || profile.keychainId)) return config2;
+  try {
+    const keychain = await loadKeychain();
+    const migrate = keychain && Object.values(config2.profiles).some((profile) => profile.apiKey);
+    for (const profile of Object.values(config2.profiles)) {
+      if (!profile.keychainId) continue;
+      if (!keychain) throw new Error();
+      const secret = await keychain.get(profile.keychainId);
+      if (secret) profile.apiKey = secret;
+      else delete profile.apiKey;
+    }
+    if (migrate) {
+      await writeConfig(config2, path2, async () => keychain);
+      config2 = await readConfig(path2, async () => keychain);
+    }
+    return config2;
+  } catch {
+    throw new ConfigError("Cannot access the HigherData keychain. Unlock it or restore access before retrying.");
+  }
+}
+async function writeConfig(config2, path2 = configPath(), loadKeychain = systemKeychain) {
   const value = validateConfig(config2);
+  const previous = await readDiskConfig(path2);
+  const profiles = Object.values(value.profiles);
+  const previousIds = Object.values(previous.profiles).flatMap((profile) => profile.keychainId ? [profile.keychainId] : []);
+  if (profiles.some((profile) => profile.apiKey || profile.keychainId) || previousIds.length) {
+    try {
+      const keychain = await loadKeychain();
+      if (!keychain && (previousIds.length || profiles.some((profile) => profile.keychainId))) throw new Error();
+      if (!keychain && profiles.some((profile) => profile.apiKey)) warnAboutFileKeychainFallback();
+      if (keychain) {
+        for (const profile of profiles) {
+          if (profile.apiKey) {
+            profile.keychainId ??= randomUUID();
+            await keychain.set(profile.keychainId, profile.apiKey);
+            delete profile.apiKey;
+          } else if (profile.keychainId) {
+            if (!previousIds.includes(profile.keychainId)) await keychain.remove(profile.keychainId);
+            delete profile.keychainId;
+          }
+        }
+        const retained = new Set(profiles.map((profile) => profile.keychainId));
+        for (const id of previousIds) if (!retained.has(id)) await keychain.remove(id);
+      }
+    } catch {
+      throw new ConfigError("Cannot update the HigherData keychain. Unlock it or restore access before retrying.");
+    }
+  }
   await mkdir(dirname(path2), { recursive: true, mode: 448 });
   const temporaryPath = `${path2}.${randomUUID()}.tmp`;
   try {
@@ -20552,11 +20639,12 @@ function resolveSettings(config2, options = {}, env = process.env) {
     space: profile.space
   };
 }
-var DEFAULT_API_URL, apiUrlSchema, profileSchema, configSchema, ConfigError;
+var DEFAULT_API_URL, apiUrlSchema, profileSchema, configSchema, ConfigError, warnedAboutFileKeychainFallback;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
     init_zod();
+    init_keychain();
     DEFAULT_API_URL = "https://higherdata.io";
     apiUrlSchema = external_exports.url().refine((value) => {
       try {
@@ -20570,6 +20658,7 @@ var init_config = __esm({
     profileSchema = external_exports.strictObject({
       apiUrl: apiUrlSchema.optional(),
       apiKey: external_exports.string().min(1).optional(),
+      keychainId: external_exports.uuid().optional(),
       space: external_exports.string().min(1).optional()
     });
     configSchema = external_exports.strictObject({
@@ -20585,6 +20674,7 @@ var init_config = __esm({
         this.name = "ConfigError";
       }
     };
+    warnedAboutFileKeychainFallback = false;
   }
 });
 
@@ -21657,6 +21747,11 @@ var init_generated = __esm({
                       "type": "string",
                       "maxLength": 120
                     },
+                    "domain": {
+                      "description": "Exact normalized company domain. Company searches only.",
+                      "type": "string",
+                      "maxLength": 253
+                    },
                     "missingField": {
                       "description": "Only records with an empty synced property.",
                       "type": "string",
@@ -21939,6 +22034,44 @@ var init_generated = __esm({
           "additionalProperties": false
         }
       },
+      {
+        "name": "crm.list_enrichment_jobs",
+        "description": "List your CRM enrichment previews and proposal jobs in this space, newest first. History contains no record samples.",
+        "risk": "read",
+        "scopes": [
+          "crm:write"
+        ],
+        "input": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "type": "object",
+          "properties": {
+            "cursor": {
+              "description": "Continuation from the previous history page.",
+              "type": "object",
+              "properties": {
+                "createdAt": {
+                  "type": "string",
+                  "format": "date-time",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+                  "description": "Creation time of the last job on the previous page."
+                },
+                "id": {
+                  "type": "string",
+                  "format": "uuid",
+                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+                  "description": "Id of the last job on the previous page."
+                }
+              },
+              "required": [
+                "createdAt",
+                "id"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
       {
         "name": "crm.push",
         "description": "Propose CRM changes for human review. Creates a pending-approval change set. It never dispatches a HubSpot write; approve fields and call changes.apply separately. Dry run returns the proposal only.",
@@ -22339,6 +22472,11 @@ var init_generated = __esm({
               "type": "string",
               "maxLength": 120
             },
+            "domain": {
+              "description": "Exact normalized company domain. Company searches only.",
+              "type": "string",
+              "maxLength": 253
+            },
             "missingField": {
               "description": "Only records with an empty synced property.",
               "type": "string",
@@ -24895,6 +25033,36 @@ var init_generated = __esm({
                     "filters": {
                       "type": "object",
                       "properties": {
+                        "companyNames": {
+                          "description": "Company name prefixes. Match any name.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "excludeCompanyNames": {
+                          "description": "Company name prefixes to leave out.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "domain": {
+                          "description": "Company website domain. Exact host matching; root sites rank first.",
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 320
+                        },
                         "countryCodes": {
                           "description": "Two-letter country codes to include.",
                           "minItems": 1,
@@ -25066,9 +25234,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "excludeNaics2022Codes": {
@@ -25078,9 +25244,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "fundingTypes": {
@@ -25209,12 +25373,6 @@ var init_generated = __esm({
                             "maxLength": 320
                           }
                         },
-                        "domain": {
-                          "description": "Website domain. Matching is exact on the host, and a root site ranks first.",
-                          "type": "string",
-                          "minLength": 1,
-                          "maxLength": 320
-                        },
                         "insights": {
                           "description": "Insights filters. Supply at least one.",
                           "type": "object",
@@ -25918,6 +26076,36 @@ var init_generated = __esm({
                     "filters": {
                       "type": "object",
                       "properties": {
+                        "companyNames": {
+                          "description": "Company name alternatives or a domain. Finds the 50 closest token or prefix matches, ignoring punctuation, accents and legal suffixes.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "excludeCompanyNames": {
+                          "description": "Company name prefixes to leave out.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "domain": {
+                          "description": "Company website domain. Exact host matching; root sites rank first.",
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 320
+                        },
                         "countryCodes": {
                           "description": "Two-letter country codes to include.",
                           "minItems": 1,
@@ -26017,9 +26205,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "excludeNaics2022Codes": {
@@ -26029,9 +26215,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "fundingTypes": {
@@ -26160,6 +26344,25 @@ var init_generated = __esm({
                             "maxLength": 320
                           }
                         },
+                        "personNames": {
+                          "description": "Person name alternatives. Requires a company name, domain or id. Matches first or last name for one token, or first and last name for two tokens, ignoring case and accents.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "email": {
+                          "description": "Exact work email address, matched through the email index.",
+                          "type": "string",
+                          "maxLength": 320,
+                          "format": "email",
+                          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+                        },
                         "personCities": {
                           "description": "Person cities to include. Requires personCountryCodes.",
                           "minItems": 1,
@@ -26716,7 +26919,7 @@ var init_generated = __esm({
       },
       {
         "name": "lists.refresh",
-        "description": "Preview or refresh a static selection or audience in bounded pages. Record and new-record caps stop a refresh before list changes. Dry run reports additions, flags and removals.",
+        "description": "Preview or refresh a static selection or audience in bounded pages. Record caps keep the first matching records that fit. New-record caps can block a refresh before changes. Dry run reports additions, flags and removals.",
         "risk": "write_local",
         "scopes": [
           "data:read",
@@ -26748,7 +26951,7 @@ var init_generated = __esm({
       },
       {
         "name": "lists.run",
-        "description": "Queue a bounded static-list data refresh for the current warehouse release when background jobs are configured, or return jobs_unavailable. Runs are idempotent per list and release. Dry run returns the proposed release without writing or dispatching.",
+        "description": "Queue a background preview or refresh. Only one job runs per list. Owners and admins can refresh dynamic lists now, including the current release. Dry run reports the proposed release without queueing.",
         "risk": "write_local",
         "scopes": [
           "data:read",
@@ -26763,6 +26966,15 @@ var init_generated = __esm({
               "format": "uuid",
               "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
               "description": "Saved list id."
+            },
+            "purpose": {
+              "default": "refresh",
+              "description": "Preview counts without changing records, or refresh using the saved caps.",
+              "type": "string",
+              "enum": [
+                "preview",
+                "refresh"
+              ]
             }
           },
           "required": [
@@ -26771,6 +26983,37 @@ var init_generated = __esm({
           "additionalProperties": false
         }
       },
+      {
+        "name": "lists.status",
+        "description": "Read the progress and count-only summary of a background list preview or refresh.",
+        "risk": "read",
+        "scopes": [
+          "data:read"
+        ],
+        "input": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+              "description": "Saved list id."
+            },
+            "runId": {
+              "type": "string",
+              "format": "uuid",
+              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+              "description": "Background run id returned by lists.run."
+            }
+          },
+          "required": [
+            "id",
+            "runId"
+          ],
+          "additionalProperties": false
+        }
+      },
       {
         "name": "lookup.company",
         "description": "Look up a company by exactly one domain, exact name (optionally with location), or opaque hdo_ id. Returns bounded candidates and ambiguity metadata.  Insights fields and filters require the Insights or Unlimited plan.",
@@ -27079,6 +27322,36 @@ var init_generated = __esm({
           "$schema": "https://json-schema.org/draft/2020-12/schema",
           "type": "object",
           "properties": {
+            "companyNames": {
+              "description": "Company name prefixes. Match any name.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "excludeCompanyNames": {
+              "description": "Company name prefixes to leave out.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "domain": {
+              "description": "Company website domain. Exact host matching; root sites rank first.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
+            },
             "countryCodes": {
               "description": "Two-letter country codes to include.",
               "minItems": 1,
@@ -27250,9 +27523,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "excludeNaics2022Codes": {
@@ -27262,9 +27533,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "fundingTypes": {
@@ -27406,12 +27675,6 @@ var init_generated = __esm({
               "minLength": 1,
               "maxLength": 2048
             },
-            "domain": {
-              "description": "Website domain. Matching is exact on the host, and a root site ranks first.",
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 320
-            },
             "insights": {
               "description": "Insights filters. Supply at least one.",
               "type": "object",
@@ -28114,6 +28377,36 @@ var init_generated = __esm({
           "$schema": "https://json-schema.org/draft/2020-12/schema",
           "type": "object",
           "properties": {
+            "companyNames": {
+              "description": "Company name prefixes. Match any name.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "excludeCompanyNames": {
+              "description": "Company name prefixes to leave out.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "domain": {
+              "description": "Company website domain. Exact host matching; root sites rank first.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
+            },
             "countryCodes": {
               "description": "Two-letter country codes to include.",
               "minItems": 1,
@@ -28285,9 +28578,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "excludeNaics2022Codes": {
@@ -28297,9 +28588,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "fundingTypes": {
@@ -28428,12 +28717,6 @@ var init_generated = __esm({
                 "maxLength": 320
               }
             },
-            "domain": {
-              "description": "Website domain. Matching is exact on the host, and a root site ranks first.",
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 320
-            },
             "insights": {
               "description": "Insights filters. Supply at least one.",
               "type": "object",
@@ -29121,7 +29404,7 @@ var init_generated = __esm({
       },
       {
         "name": "search.facets",
-        "description": "Read available country, state, industry, NAICS and funding filter values from HigherData Core, with optional country-scoped company, person or job city suggestions. Eligible plans also receive technology product suggestions.",
+        "description": "Read release-built country, state, industry, NAICS, funding, department, seniority and role family values from HigherData Core, with optional country-scoped company, person or job city suggestions. Eligible plans also receive technology product suggestions.",
         "risk": "read",
         "scopes": [
           "data:read"
@@ -29220,7 +29503,7 @@ var init_generated = __esm({
       },
       {
         "name": "search.people",
-        "description": "Find people in HigherData Core, with 1 to 5 positive company HQ country codes or industries required unless companyId scopes the search to one company. Person, job and company location use distinct filters; each city filter requires its corresponding country. Company-scoped contacts also support legacy contactLocation filters. Pages contain at most 50 people and opaque ids. ",
+        "description": "Find people in HigherData Core, with 1 to 5 positive company HQ country codes or industries required unless a company id, company name, domain or indexed email scopes the search. Person names require a company scope. Person, job and company location use distinct filters; each city filter requires its corresponding country. Company-scoped contacts also support legacy contactLocation filters. Pages contain at most 50 people and opaque ids. ",
         "risk": "read",
         "scopes": [
           "data:read"
@@ -29229,6 +29512,36 @@ var init_generated = __esm({
           "$schema": "https://json-schema.org/draft/2020-12/schema",
           "type": "object",
           "properties": {
+            "companyNames": {
+              "description": "Company name alternatives or a domain. Finds the 50 closest token or prefix matches, ignoring punctuation, accents and legal suffixes.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "excludeCompanyNames": {
+              "description": "Company name prefixes to leave out.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "domain": {
+              "description": "Company website domain. Exact host matching; root sites rank first.",
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 320
+            },
             "countryCodes": {
               "description": "Two-letter country codes to include.",
               "minItems": 1,
@@ -29328,9 +29641,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "excludeNaics2022Codes": {
@@ -29340,9 +29651,7 @@ var init_generated = __esm({
               "type": "array",
               "items": {
                 "type": "string",
-                "minLength": 1,
-                "maxLength": 120,
-                "pattern": "\\S"
+                "pattern": "^[0-9]{6}$"
               }
             },
             "fundingTypes": {
@@ -29471,6 +29780,25 @@ var init_generated = __esm({
                 "maxLength": 320
               }
             },
+            "personNames": {
+              "description": "Person name alternatives. Requires a company name, domain or id. Matches first or last name for one token, or first and last name for two tokens, ignoring case and accents.",
+              "minItems": 1,
+              "maxItems": 5,
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 120,
+                "pattern": "\\S"
+              }
+            },
+            "email": {
+              "description": "Exact work email address, matched through the email index.",
+              "type": "string",
+              "maxLength": 320,
+              "format": "email",
+              "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+            },
             "personCities": {
               "description": "Person cities to include. Requires personCountryCodes.",
               "minItems": 1,
@@ -29955,6 +30283,36 @@ var init_generated = __esm({
                     "filters": {
                       "type": "object",
                       "properties": {
+                        "companyNames": {
+                          "description": "Company name prefixes. Match any name.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "excludeCompanyNames": {
+                          "description": "Company name prefixes to leave out.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "domain": {
+                          "description": "Company website domain. Exact host matching; root sites rank first.",
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 320
+                        },
                         "countryCodes": {
                           "description": "Two-letter country codes to include.",
                           "minItems": 1,
@@ -30126,9 +30484,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "excludeNaics2022Codes": {
@@ -30138,9 +30494,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "fundingTypes": {
@@ -30269,12 +30623,6 @@ var init_generated = __esm({
                             "maxLength": 320
                           }
                         },
-                        "domain": {
-                          "description": "Website domain. Matching is exact on the host, and a root site ranks first.",
-                          "type": "string",
-                          "minLength": 1,
-                          "maxLength": 320
-                        },
                         "insights": {
                           "description": "Insights filters. Supply at least one.",
                           "type": "object",
@@ -30978,6 +31326,36 @@ var init_generated = __esm({
                     "filters": {
                       "type": "object",
                       "properties": {
+                        "companyNames": {
+                          "description": "Company name alternatives or a domain. Finds the 50 closest token or prefix matches, ignoring punctuation, accents and legal suffixes.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "excludeCompanyNames": {
+                          "description": "Company name prefixes to leave out.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "domain": {
+                          "description": "Company website domain. Exact host matching; root sites rank first.",
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 320
+                        },
                         "countryCodes": {
                           "description": "Two-letter country codes to include.",
                           "minItems": 1,
@@ -31077,9 +31455,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "excludeNaics2022Codes": {
@@ -31089,9 +31465,7 @@ var init_generated = __esm({
                           "type": "array",
                           "items": {
                             "type": "string",
-                            "minLength": 1,
-                            "maxLength": 120,
-                            "pattern": "\\S"
+                            "pattern": "^[0-9]{6}$"
                           }
                         },
                         "fundingTypes": {
@@ -31220,6 +31594,25 @@ var init_generated = __esm({
                             "maxLength": 320
                           }
                         },
+                        "personNames": {
+                          "description": "Person name alternatives. Requires a company name, domain or id. Matches first or last name for one token, or first and last name for two tokens, ignoring case and accents.",
+                          "minItems": 1,
+                          "maxItems": 5,
+                          "type": "array",
+                          "items": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 120,
+                            "pattern": "\\S"
+                          }
+                        },
+                        "email": {
+                          "description": "Exact work email address, matched through the email index.",
+                          "type": "string",
+                          "maxLength": 320,
+                          "format": "email",
+                          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+                        },
                         "personCities": {
                           "description": "Person cities to include. Requires personCountryCodes.",
                           "minItems": 1,
@@ -32012,7 +32405,7 @@ function retryAfter(response, data, now) {
 }
 function apiError(response, data, now) {
   const parsed = failure2.safeParse(data), error63 = parsed.success ? parsed.data.error : null;
-  return new HigherDataError(typeof error63 === "object" && error63?.message ? error63.message : "The HigherData API request failed.", typeof error63 === "string" ? error63 : error63?.code ?? "http_error", response.status, retryAfter(response, data, now));
+  return new HigherDataError(typeof error63 === "object" && error63?.message ? error63.message : "The HigherData API request failed.", typeof error63 === "string" ? error63 : error63?.code ?? "http_error", response.status, retryAfter(response, data, now), response.headers.get("x-request-id") ?? void 0);
 }
 async function responseJson(response) {
   if (!response.body) throw new HigherDataError("The API returned an invalid response.", "invalid_response");
@@ -32067,16 +32460,18 @@ var init_transport = __esm({
     init_zod();
     failure2 = external_exports.object({ error: external_exports.union([external_exports.string(), external_exports.object({ code: external_exports.string().max(128), message: external_exports.string().max(2048).optional(), retry_after: external_exports.number().nonnegative().finite().optional() })]) });
     HigherDataError = class extends Error {
-      constructor(message, code, status = 0, retryAfter2) {
+      constructor(message, code, status = 0, retryAfter2, requestId) {
         super(message);
         this.code = code;
         this.status = status;
         this.retryAfter = retryAfter2;
+        this.requestId = requestId;
         this.name = "HigherDataError";
       }
       code;
       status;
       retryAfter;
+      requestId;
     };
     limits = external_exports.object({ maxRetries: external_exports.number().int().min(0).max(5), timeoutMs: external_exports.number().int().min(1).max(3e5), maxRetryDelayMs: external_exports.number().int().min(0).max(3e5) });
     MAX_RESPONSE = 8 * 1024 * 1024;
@@ -32228,7 +32623,11 @@ var init_api2 = __esm({
           }
         } catch (error63) {
           if (error63 instanceof HigherDataError) {
-            if (error63.status) throw apiFailure(error63.status, { error: { code: error63.code, message: error63.message } });
+            if (error63.status) {
+              const mapped = apiFailure(error63.status, { error: { code: error63.code, message: error63.message } });
+              const plain = (value) => (this.settings.apiKey ? value.replaceAll(this.settings.apiKey, "[redacted]") : value).replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
+              throw new CliError(`${plain(error63.code)}: ${plain(error63.message === "The HigherData API request failed." ? mapped.message : error63.message)}${error63.requestId ? ` (request: ${plain(error63.requestId)})` : ""}`, mapped.exitCode);
+            }
             if (error63.code === "response_too_large") throw new CliError("The API response exceeded the CLI size limit.");
             throw new CliError(error63.message);
           }
@@ -35798,7 +36197,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "higherdata",
-      version: "0.4.0",
+      version: "0.5.0",
       type: "module",
       bin: {
         higherdata: "dist/index.js"
@@ -35848,6 +36247,9 @@ var init_package = __esm({
       },
       higherdata: {
         minimumServerVersion: "0.2.0"
+      },
+      optionalDependencies: {
+        "@napi-rs/keyring": "2.1.0"
       }
     };
   }
@@ -38788,6 +39190,12 @@ function customerOutput(value) {
 }
 function renderOutput(value, mode) {
   value = customerOutput(value);
+  if (value.status === "ambiguous" && Array.isArray(value.companyCandidates)) {
+    if (mode === "human") return `${cell(value.message)}
+${renderOutput({ items: value.companyCandidates }, "human")}`;
+    return `${JSON.stringify(value)}
+`;
+  }
   if (mode === "json") return `${JSON.stringify(value)}
 `;
   const scoped = value.peopleAtCompany && typeof value.peopleAtCompany === "object" ? value.peopleAtCompany.people : void 0;
@@ -43835,18 +44243,19 @@ function suggestionOptions(kind, known, key) {
   if (kind === "cities") return known.cities?.[key ?? ""] ?? [];
   if (kind === "industries") return known.industries.map((value) => ({ value, label: value }));
   if (kind === "funding") return known.fundingTypes.map((value) => ({ value, label: value }));
-  if (kind === "levels") return JOB_LEVELS.map((value) => ({ value, label: value }));
-  if (kind === "functions") return JOB_FUNCTIONS.map((value) => ({ value, label: value }));
+  if (kind === "levels") return (known.jobLevels ?? JOB_LEVELS).map((value) => ({ value, label: value }));
+  if (kind === "functions") return (known.jobFunctions ?? []).map((value) => ({ value, label: value }));
+  if (kind === "roles") return (known.gtmRoleFamilies ?? []).map((value) => ({ value, label: value.replace(/_/g, " ") }));
   if (kind === "products") {
     const leaf = key?.split(".").pop() ?? "";
     const included = leaf.startsWith("exclude") ? leaf.charAt(7).toLowerCase() + leaf.slice(8) : leaf;
     return (known.technologyProducts?.[included] ?? []).map((value) => ({ value, label: value }));
   }
-  if (kind === "naics") return (known.naics2022Codes ?? []).map((value) => ({ value, label: naicsLabel(value) }));
+  if (kind === "naics") return (known.naics2022Codes ?? []).map((value) => ({ value, label: known.naicsLabels?.[value] ?? naicsLabel(value) }));
   if (kind === "technologies") return technologyCategories.map((value) => ({ value, label: TECH_LABELS[value] }));
   return [];
 }
-var EMPTY_KNOWN, COUNTRY_CODES, COUNTRY_ALIASES, US_STATES, CA_REGIONS, JOB_LEVELS, JOB_FUNCTIONS, TECH_LABELS, regions, countriesByName;
+var EMPTY_KNOWN, COUNTRY_CODES, COUNTRY_ALIASES, US_STATES, CA_REGIONS, JOB_LEVELS, TECH_LABELS, regions, countriesByName;
 var init_values = __esm({
   "../../src/lib/search-ui/values.ts"() {
     "use strict";
@@ -43937,21 +44346,6 @@ var init_values = __esm({
       YT: "Yukon"
     };
     JOB_LEVELS = ["C-Team", "VP", "Director", "Manager", "Staff"];
-    JOB_FUNCTIONS = [
-      "Operations",
-      "Sales",
-      "Marketing",
-      "Engineering",
-      "Finance",
-      "Human Resources",
-      "Information Technology",
-      "Product",
-      "Support",
-      "Legal",
-      "Customer Success",
-      "Business Development",
-      "Data"
-    ];
     TECH_LABELS = {
       crm: "CRM",
       marketingAutomation: "Marketing automation",
@@ -43994,6 +44388,25 @@ function range2(min, max, estimate, money = false) {
   const value = estimate ?? min ?? max;
   return value === null ? null : format2(value);
 }
+function stringValues(value) {
+  if (!value) return [];
+  if (!value.trim().startsWith("[")) return [value.trim()];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.map((item) => typeof item === "string" || typeof item === "number" ? String(item).trim() : "") : [];
+  } catch {
+    return [];
+  }
+}
+function naicsDisplay(codes, titles) {
+  const descriptions = stringValues(titles), seen = /* @__PURE__ */ new Set();
+  const labels = stringValues(codes).flatMap((code, index) => {
+    if (!/^[0-9]{6}$/.test(code) || seen.has(code)) return [];
+    seen.add(code);
+    return [descriptions[index] ? `${code} ${descriptions[index]}` : naicsLabel(code)];
+  });
+  return labels.length ? labels.join("; ") : null;
+}
 function recordDisplayValues(record2) {
   const text2 = (key) => typeof record2[key] === "string" ? record2[key] : null;
   const number5 = (key) => typeof record2[key] === "number" ? record2[key] : null;
@@ -44001,7 +44414,7 @@ function recordDisplayValues(record2) {
     ...record2,
     location: locationLabel(text2("headquartersCity"), text2("headquartersStateCode"), text2("headquartersCountryCode")),
     address: [text2("headquartersStreet"), text2("headquartersPostcode")].filter(Boolean).join(", "),
-    naics: [text2("industryNaics2022Code"), text2("industryNaics2022Description")].filter(Boolean).join(" "),
+    naics: naicsDisplay(text2("industryNaics2022Code"), text2("industryNaics2022Description")),
     employees: range2(number5("employeeCountMin"), number5("employeeCountMax"), number5("employeeCountEstimate") ?? number5("employeeCount")),
     revenue: range2(number5("revenueMinUsd"), number5("revenueMaxUsd"), number5("revenueEstimateUsd"), true)
   };
@@ -44021,6 +44434,7 @@ var init_format2 = __esm({
 // ../../src/lib/search-ui/filter-groups.ts
 function groupFor(key) {
   const leaf = key.split(".").pop() ?? key;
+  if (["companyNames", "excludeCompanyNames", "domain", "excludeDomains", "personNames", "email"].includes(leaf)) return "Name and contact";
   if (key.startsWith("insights") || /technolog/i.test(leaf)) return "Insights";
   if (/country|state|cities|city|region|postcode/i.test(leaf)) return "Location";
   if (/industr|naics/i.test(leaf)) return "Industry";
@@ -44044,6 +44458,7 @@ var init_filter_groups = __esm({
   "../../src/lib/search-ui/filter-groups.ts"() {
     "use strict";
     GROUP_ORDER = [
+      "Name and contact",
       "Location",
       "Industry",
       "Company size",
@@ -45892,9 +46307,7 @@ function createProgram(overrides = {}) {
     if (["login", "update", "upgrade"].includes(command.name()) || ["mcp", "skills", "config"].includes(command.parent?.name() ?? "")) return;
     if (command === program2 && (!runtime.updater.stdinTTY || !runtime.updater.stdoutTTY || Object.hasOwn(runtime.env, "CI") || program2.opts().json || program2.opts().jsonl)) return;
     const settings = resolveSettings(await runtime.readConfig(), command.optsWithGlobals(), runtime.env);
-    const interactive = runtime.updater.stdinTTY && runtime.updater.stdoutTTY && !Object.hasOwn(runtime.env, "CI") && !command.optsWithGlobals().json && !command.optsWithGlobals().jsonl;
-    await checkCliVersion({ apiUrl: settings.apiUrl, version: package_default.version, cache: runtime.versionCache, fetchImpl: runtime.fetchImpl, now: runtime.now, warn: interactive ? runtime.err : () => {
-    } });
+    await checkCliVersion({ apiUrl: settings.apiUrl, version: package_default.version, cache: runtime.versionCache, fetchImpl: runtime.fetchImpl, now: runtime.now, warn: runtime.err });
   });
   program2.command("update").alias("upgrade").description("Install the latest HigherData CLI release").action(() => updateCli({ version: package_default.version, fetchImpl: runtime.fetchImpl, runtime: runtime.updater, env: runtime.env, out: runtime.out }));
   program2.command("config").description("Configure the CLI").command("set <key> <value>").action(async (key, value) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "higherdata",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "higherdata": "dist/index.js"
@@ -50,5 +50,8 @@
   },
   "higherdata": {
     "minimumServerVersion": "0.2.0"
+  },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.0"
   }
 }