@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/find.js

@@ -0,0 +1,159 @@
+import { readCreditCeilingOrZero, readPositiveNumber } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { Command } from "commander";
+function buildFindBody(capability, options) {
+    const body = { capability };
+    const set = (key, value) => {
+        if (value)
+            body[key] = value;
+    };
+    if (capability === "person") {
+        set("linkedin_url", options.linkedinUrl);
+        set("linkedin_id", options.linkedinId);
+        set("sales_navigator_url", options.salesNavigatorUrl);
+        set("email", options.email);
+        set("full_name", options.fullName);
+        set("first_name", options.firstName);
+        set("last_name", options.lastName);
+        set("company_domain", options.companyDomain);
+        set("company_name", options.companyName);
+        if (options.includeRaw)
+            body.include_raw = true;
+    }
+    else if (capability === "company") {
+        // The catalog needs no identity and spends nothing; it is the answer to
+        // "which fields exist and what do they cost" before any field is named.
+        if (options.listFields) {
+            body.list_fields = true;
+            return body;
+        }
+        set("domain", options.domain);
+        set("name", options.name);
+        set("linkedin_url", options.linkedinUrl);
+        if (options.fields) {
+            const fields = options.fields.split(",").map((field) => field.trim()).filter(Boolean);
+            if (fields.length > 0)
+                body.fields = fields;
+        }
+        if (options.checkTechnologies) {
+            const technologies = options.checkTechnologies.split(",").map((entry) => entry.trim()).filter(Boolean);
+            if (technologies.length > 0)
+                body.check_technologies = technologies;
+        }
+    }
+    else {
+        set("linkedin_url", options.linkedinUrl);
+        set("full_name", options.fullName);
+        set("first_name", options.firstName);
+        set("last_name", options.lastName);
+        set("email", options.email);
+        set("company_domain", options.companyDomain);
+        set("company_name", options.companyName);
+        set("company_linkedin_url", options.companyLinkedinUrl);
+    }
+    if (options.mode)
+        body.mode = options.mode;
+    // Company only: 0 is a real ceiling meaning "run only the zero-credit lanes".
+    // The person capabilities are paid on every lane, so 0 stays a usage error
+    // there. `!== undefined` because 0 is falsy and would otherwise be dropped.
+    const maxCredits = capability === "company"
+        ? readCreditCeilingOrZero(options.maxCredits)
+        : readPositiveNumber(options.maxCredits);
+    if (maxCredits !== undefined)
+        body.max_credits = maxCredits;
+    // Phone-only opt-in; the route ignores it for other capabilities.
+    if (options.verify)
+        body.verify = true;
+    return body;
+}
+export function registerFindFamily(program, handleAsyncAction) {
+    program
+        .command("find")
+        .description("One-shot contact and company lookups over enrichment waterfalls (no table). dry_run previews the plan for free (which lanes would run, in order, and what each costs — not the answer); live spends and needs --max-credits.")
+        .addCommand(new Command("email")
+        .description("Find a person's work email via an input-aware multi-provider waterfall: a LinkedIn URL, name+domain, or first/last+domain each select the best provider profile, with an email-pattern pre-step and verification. dry_run shows the resolved profile + chain for free.")
+        .option("--linkedin-url <url>", "Person LinkedIn profile URL (strongest signal).")
+        .option("--full-name <name>", "Person full name.")
+        .option("--first-name <name>", "Person first name.")
+        .option("--last-name <name>", "Person last name.")
+        .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
+        .option("--company-name <name>", "Company name.")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. When the resolved chain runs the guessed-address pass (the name+domain and first/last+domain profiles, not the LinkedIn-URL one) the block also carries estimate.pattern_guess_verification_credits — the verification checks that pass bills before any named provider is dialled. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find email", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("email", options) }));
+    }))
+        .addCommand(new Command("personal-email")
+        .description("Find a person's personal (non-work) email — for ad-audience uploads, recruiting, or founder outreach — via a cost-ordered multi-provider waterfall that bills only on a hit and grades the address with MillionVerifier before returning it. Every default lane keys on a LinkedIn URL; ContactOut also accepts a known email or full name + company. dry_run previews the chain and its price for free.")
+        .option("--linkedin-url <url>", "Person LinkedIn profile URL (strongest signal; every default lane accepts it).")
+        .option("--email <email>", "Known email as an identity fallback (ContactOut lane).")
+        .option("--full-name <name>", "Person full name (with a company domain or name; ContactOut lane).")
+        .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
+        .option("--company-name <name>", "Company name.")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find personal-email", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("personal_email", options) }));
+    }))
+        .addCommand(new Command("phone")
+        .description("Find a person's mobile phone via a multi-provider waterfall. The provider chain is input-aware: a LinkedIn URL unlocks the full cost-ordered chain (Blitz first), email/name use the providers that accept them.")
+        .option("--linkedin-url <url>", "Person LinkedIn profile URL (strongest signal for phone).")
+        .option("--email <email>", "Known email as an identity fallback.")
+        .option("--full-name <name>", "Person full name.")
+        .option("--company-domain <domain>", "Company apex domain.")
+        .option("--company-name <name>", "Company name.")
+        .option("--verify", "Verify the found number with ClearoutPhone — adds line_type/carrier and keeps the number on a non-verdict (only a genuine 'not valid' is discarded).")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find phone", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("phone", options) }));
+    }))
+        .addCommand(new Command("linkedin")
+        .description("Resolve a person's LinkedIn URL from name + company (or email), with identity validation. Each lane tried bills until the 2026-09 repricing date; from it a URL found that matches the person costs a flat 5 credits and a miss costs 0.")
+        .option("--full-name <name>", "Person full name.")
+        .option("--email <email>", "Known email.")
+        .option("--company-domain <domain>", "Company apex domain.")
+        .option("--company-name <name>", "Company name.")
+        .option("--company-linkedin-url <url>", "Company LinkedIn URL.")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find linkedin", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("linkedin", options) }));
+    }))
+        .addCommand(new Command("person")
+        .description("Enrich one person from a LinkedIn URL, a LinkedIn public id or member id, a Sales Navigator link, or an email / name + company: one managed profile lookup returns the profile block — first, last and full name, current company and its LinkedIn URL, job title, job start date, education and school, headline, bio, location and follower count — the same fields the person_enrich table preset extracts for free. An email or name is first resolved to the profile through the LinkedIn URL waterfall (priced as an identity prerequisite). A member id uses managed enrichment. A Sales Navigator link resolves on the workspace's own HarvestAPI key. dry_run previews the lookup and its price for free.")
+        .option("--linkedin-url <url>", "Person LinkedIn profile URL (linkedin.com/in/<handle>).")
+        .option("--linkedin-id <id>", "LinkedIn public identifier (the part after /in/), or a member ID beginning ACo/ACw; both support managed enrichment. Preview checks input shape and price without resolving the ID.")
+        .option("--sales-navigator-url <url>", "Sales Navigator lead or people link; resolved on the workspace's own HarvestAPI key.")
+        .option("--email <email>", "Known email; resolved to the profile through the LinkedIn URL waterfall first.")
+        .option("--full-name <name>", "Person full name; with --company-domain or --company-name, resolved through the LinkedIn URL waterfall first.")
+        .option("--first-name <name>", "Person first name.")
+        .option("--last-name <name>", "Person last name.")
+        .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
+        .option("--company-name <name>", "Company name.")
+        .option("--include-raw", "Also return the provider's raw profile payload (profile_raw) for fields the profile block does not carry.")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the profile.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: estimate.recommended_max_credits funds the profile lookup plus, for an email or name input, every lane of the LinkedIn URL waterfall that resolves it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find person", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("person", options) }));
+    }))
+        .addCommand(new Command("company")
+        .description("Enrich a company via a waterfall: identity, firmographics, structured funding, competitors, corporate structure, acquisitions, news, job openings, tech stack, web-presence URLs. `--list-fields` prints the catalog with per-field cost.")
+        .option("--domain <domain>", "Company apex domain.")
+        .option("--name <name>", "Company name.")
+        .option("--linkedin-url <url>", "Company LinkedIn URL.")
+        .option("--fields <fields>", "Comma-separated field keys from --list-fields (e.g. headcount,industry,funding_stage,latest_funding_round,competitors,technologies,job_openings). Defaults to domain,linkedin_url,headcount,industry,description,founded_year,hq_country — the identity plus everything one profile lookup answers for free. Unknown keys are refused, never silently dropped.")
+        .option("--list-fields", "Print the field catalog (category, description, provider count, per-row credits: free / fixed / ~estimated) and exit. Needs no identity; spends nothing.")
+        .option("--check-technologies <names>", "Comma-separated technology names for the technology_check field, answered yes/no against the detected stack (e.g. hubspot,salesforce).")
+        .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live; 0 can still call providers on zero-credit lanes and reuse any priced lane this workspace already has a cached answer for (the other priced lanes are skipped as credit_ceiling_reached). Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that funds every lane in the plan, and estimate.min_credits, what the plan costs if each field is answered by its first lane.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("find company", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("company", options) }));
+    }));
+}

package/dist/commands/followers.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerFollowersFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/followers.js

@@ -0,0 +1,39 @@
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerFollowersFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("followers")
+        .description("Read the followers of YOUR OWN connected LinkedIn account into a Clay-like workspace table you can enrich, qualify, and enroll from. Imports run as a slow, durable background drip under a dedicated conservative read budget — they never burst and never starve the sequencer's own reads. For the followers of a company page — a competitor's audience — use `oxygen tables followers check` instead.")
+        .addCommand(new Command("import")
+        .description("Start (or re-arm) a followers import. Followers drip into a workspace table + the deduped mirror over many ticks; poll `followers status` to watch them accrue. The import keeps itself fresh by periodically re-walking followers in the background (new followers dedupe in). No messages are sent and no Oxygen credits are charged.")
+        .option("--account <ref>", "Sender account to import (sender id, connection id, or Unipile account id). Omit to import every active LinkedIn account.")
+        .option("--table <ref>", "Existing workspace table (id or slug) to import into. Omit to create or reuse a 'LinkedIn Followers' table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("followers import", options, () => {
+            const account = readOption(options.account);
+            const table = readOption(options.table);
+            return requestOxygen("/api/cli/linkedin/followers/import", {
+                method: "POST",
+                body: {
+                    ...(account ? { account } : {}),
+                    ...(table ? { table } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("status")
+        .description("Show followers-import progress (per-sender drip status, followers ingested, last error) plus a preview of the followers table and a deep-link to open it.")
+        .option("--account <ref>", "Scope to one sender account (sender id, connection id, or Unipile account id).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("followers status", options, () => {
+            const account = readOption(options.account);
+            const params = new URLSearchParams();
+            if (account)
+                params.set("account", account);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/linkedin/followers/status${suffix ? `?${suffix}` : ""}`);
+        });
+    })));
+}

package/dist/commands/formulas.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerFormulasFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/formulas.js

@@ -0,0 +1,43 @@
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerFormulasFamily(program, handleAsyncAction) {
+    program
+        .command("formulas")
+        .description("Formula language for formula columns and per-column run conditions (only-run-if).")
+        .addCommand(new Command("functions")
+        .description("List every formula function (name, signature, examples), the operator grammar, and the expression_notes that a signature cannot teach (bare column keys, string escapes, no regex flags, read-time evaluation). The same language powers formula columns and --run-condition gates.")
+        .option("--category <category>", "Filter by category: logic, string, number, date, url_email, array, json, null_handling, cross_row.")
+        .option("--query <text>", "Find functions by name, signature or description.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("formulas functions", options, () => {
+            const category = readOption(options.category);
+            const params = new URLSearchParams();
+            if (category)
+                params.set("category", category);
+            if (readOption(options.query))
+                params.set("query", readOption(options.query));
+            const query = params.size ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/tables/formulas/functions${query}`, { method: "GET" });
+        });
+    }))
+        .addCommand(new Command("validate")
+        .description("Validate a formula against a table and preview its output on sample rows — free, no writes. Draft → validate → attach with `oxygen columns add --kind formula`.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--expression <expr>", "The formula expression to validate, e.g. \"if(score > 80, 'hot', 'warm')\".")
+        .option("--rows <n>", "How many sample rows to evaluate (0-25, default 5).")
+        .option("--row-id <id...>", "Evaluate specific row ids instead of the first rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("formulas validate", options, () => requestOxygen("/api/cli/tables/formulas/validate", {
+            method: "POST",
+            body: {
+                table,
+                expression: options.expression,
+                ...(readOption(options.rows) ? { sample_limit: Number(readOption(options.rows)) } : {}),
+                ...(options.rowId && options.rowId.length > 0 ? { row_ids: options.rowId } : {}),
+            },
+        }));
+    }));
+}

package/dist/commands/home.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerHomeFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/home.js

@@ -0,0 +1,22 @@
+import { homeStandupMarksSeen } from "../home-standup.js";
+import { requestOxygen } from "../http-client.js";
+/**
+ * `oxygen home`: the outcome-neutral workspace standup. Only the plain view printed to
+ * an interactive terminal is the person looking and marks Home as seen; `--json`, or
+ * output an agent's shell or a pipe captures, sends `mark_seen=false` and leaves the
+ * person's Home marker alone (founder decision, 2026-10-05; see home-standup.ts).
+ */
+async function readHomeStandup(options) {
+    return requestOxygen(homeStandupMarksSeen({ json: options.json, isTTY: process.stdout.isTTY })
+        ? "/api/cli/home/standup"
+        : "/api/cli/home/standup?mark_seen=false");
+}
+export function registerHomeFamily(program, handleAsyncAction) {
+    program
+        .command("home")
+        .description("Your workspace standup: what happened since you last looked, what needs you, and a year of workspace activity. 0 credits. With --json, or when the output is not a terminal (an agent's shell or a pipe), it is a pure read: the same window, and your Home \"last seen\" marker stays where you left it. Only the plain view in a terminal counts as you looking: like opening Home on the web, it marks Home as seen (at most every four hours), so your next standup counts from then.")
+        .option("--json", "Print a JSON envelope. A pure read: leaves your Home \"last seen\" marker alone.")
+        .action(async (options) => {
+        await handleAsyncAction("home standup", options, () => readHomeStandup(options));
+    });
+}

package/dist/commands/inbox.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerInboxFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;