@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/people.js

@@ -0,0 +1,353 @@
+import { parseJsonObject, readNonNegativeInt, readPositiveInt } from "../cli-values.js";
+import { readCreditCeilingOrZero, readCsvOption, readFileIfPresent, readRangeOption, readSearchPlanJson } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+// Table-driven Employee Finder help, written once and shared by `people search
+// plan` and `people search run` so the price shape reads the same on both.
+const PEOPLE_SEARCH_FROM_TABLE_HELP = "Search every company LinkedIn URL in a table column for the people you describe — --titles, --exclude-titles, --seniorities, --job-functions, --education, location and --min-connections all apply per company. 1 credit per company per page; rows land in a new people table with a company relation back to each source row. Pass the table id or slug plus --linkedin-url-column, and bound it with --company-limit. For up to 50 companies this is the expensive way: people search preview --from-table samples them free and people search run --source people_search charges one page across all of them.";
+const PEOPLE_SEARCH_LINKEDIN_COLUMN_HELP = "Column key in --from-table holding each company's LinkedIn URL.";
+const PEOPLE_SEARCH_COMPANY_OFFSET_HELP = "Skip this many companies in --from-table. Use it to source the rest after a first-company preview.";
+const PEOPLE_SEARCH_COMPANY_LIMIT_HELP = "Fetch people for at most this many companies from --from-table. Start with --company-limit 1.";
+const PEOPLE_SEARCH_JOB_FUNCTIONS_HELP = "Comma-separated job functions: Sales, Marketing, Engineering, Finance, ...";
+const PEOPLE_SEARCH_CONTINENTS_HELP = "Comma-separated continents: Europe, North America, Asia, ...";
+const PEOPLE_SEARCH_SALES_REGIONS_HELP = "Comma-separated sales regions: EMEA, NAMER, APAC, LATAM.";
+const PEOPLE_SEARCH_MIN_CONNECTIONS_HELP = "Only return people with at least this many LinkedIn connections (0-500).";
+function readPeopleSearchSource(options) {
+    const table = readOption(options.fromTable);
+    const column = readOption(options.linkedinUrlColumn);
+    if (!table && !column)
+        return null;
+    if (!table || !column) {
+        throw new OxygenError("invalid_request", "--from-table and --linkedin-url-column go together: name the table holding your companies and the column holding each company's LinkedIn URL.", { details: { from_table: table ?? null, linkedin_url_column: column ?? null }, exitCode: 1 });
+    }
+    return { table, linkedin_url_column: column, ...readPeopleSearchCompanyWindow(options) };
+}
+function readPeopleSearchCompanyWindow(options) {
+    const offset = readNonNegativeInt(options.companyOffset);
+    const limit = readPositiveInt(options.companyLimit);
+    return {
+        ...(offset !== undefined ? { company_offset: offset } : {}),
+        ...(limit !== undefined ? { company_limit: limit } : {}),
+    };
+}
+// `--pages-per-company` is the customer-readable spelling of `--max-pages` on a
+// table-driven run, where a page is one provider request per company. Two spellings
+// of one ceiling must never disagree silently on a paid run.
+function readPeopleSearchMaxPages(options) {
+    const perCompany = readPositiveInt(options.pagesPerCompany);
+    const maxPages = readPositiveInt(options.maxPages);
+    if (perCompany !== undefined && maxPages !== undefined && perCompany !== maxPages) {
+        throw new OxygenError("invalid_request", "--pages-per-company and --max-pages set the same ceiling. Pass one of them.", { details: { pages_per_company: perCompany, max_pages: maxPages }, exitCode: 1 });
+    }
+    return perCompany ?? maxPages;
+}
+// A customer pointing at a table has already said what they want; making them
+// also invent a sentence is a question with one answer. The synthesized prompt is
+// the same one the web wizard sends, so both surfaces plan from identical input.
+function readPeopleSearchPrompt(options, source) {
+    if (options.prompt)
+        return readFileIfPresent(options.prompt);
+    if (!source)
+        return null;
+    return `Employees at companies in ${String(source.table)}`;
+}
+function readPeopleSearchPlanBody(options) {
+    const targetCount = readPositiveInt(options.targetCount);
+    const filters = readPeopleSearchFilters(options);
+    const source = readPeopleSearchSource(options);
+    const prompt = readPeopleSearchPrompt(options, source);
+    if (!prompt) {
+        throw new OxygenError("invalid_request", "Pass --prompt, or --from-table with --linkedin-url-column to source employees from a table you already have.", { exitCode: 1 });
+    }
+    return {
+        prompt,
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
+        ...(source ? { source } : {}),
+        ...(filters ? { filters } : {}),
+        // Free sizing is on by default; only --no-estimate (options.estimate === false) opts out.
+        estimate: options.estimate !== false,
+        ...(options.materializePreview ? { materialize_preview: true } : {}),
+    };
+}
+function readPeopleSearchRunBody(options) {
+    const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
+    // --source people_search is the Find people lane: the free preview's filters
+    // ARE the request, so no prompt, plan or companies table is synthesized.
+    if (options.source !== undefined && options.source !== "people_search") {
+        throw new OxygenError("invalid_request", "--source must be people_search; use --from-table to find decision makers at the companies in a table.", { exitCode: 1 });
+    }
+    if (options.source === "people_search") {
+        if (!options.sourceFiltersJson) {
+            throw new OxygenError("invalid_request", "--source people_search needs --source-filters-json (the same filters as people search preview).", { exitCode: 1 });
+        }
+        const maxCreditsNative = readCreditCeilingOrZero(options.maxCredits);
+        const nativeTarget = readPositiveInt(options.targetCount);
+        // Forwarded so the server refuses them by name; the native lane reads only
+        // --source-filters-json (OXP-1.39.2 S6).
+        const plannerFilters = readPeopleSearchFilters(options);
+        return {
+            source: "people_search",
+            source_filters: parseJsonObject(readFileIfPresent(options.sourceFiltersJson)),
+            ...(plannerFilters ? { filters: plannerFilters } : {}),
+            ...(readOption(options.tableName) ? { table_name: readOption(options.tableName) } : {}),
+            ...(options.table ? { table: options.table } : {}),
+            ...(options.project ? { project: options.project } : {}),
+            ...(options.mode ? { mode: options.mode } : {}),
+            ...(maxCreditsNative !== undefined ? { max_credits: maxCreditsNative } : {}),
+            ...(nativeTarget !== undefined ? { target_count: nativeTarget } : {}),
+            ...(options.approved ? { approved: true } : {}),
+        };
+    }
+    const source = readPeopleSearchSource(options);
+    // --from-table is itself the request, so it satisfies the prompt requirement the
+    // same way --plan-json does. A submitted plan already carries its own source and
+    // prompt, so nothing is synthesized on top of one.
+    const prompt = readPeopleSearchPrompt(options, plan ? null : source);
+    if (!prompt && !plan) {
+        throw new OxygenError("invalid_request", "Pass --prompt, --plan-json, --from-table with --linkedin-url-column, or --source people_search with --source-filters-json.", { exitCode: 1 });
+    }
+    const maxPages = readPeopleSearchMaxPages(options);
+    const maxCredits = readCreditCeilingOrZero(options.maxCredits);
+    const targetCount = readPositiveInt(options.targetCount);
+    const filters = prompt ? readPeopleSearchFilters(options) : null;
+    const sourceOverrides = source ? {} : readPeopleSearchCompanyWindow(options);
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(plan ? { plan } : {}),
+        ...(options.routeId ? { route_id: options.routeId } : {}),
+        ...(options.toolId ? { tool_id: options.toolId } : {}),
+        ...(options.table ? { table: options.table } : {}),
+        ...(options.project ? { project: options.project } : {}),
+        ...(options.upsertKey ? { upsert_key: options.upsertKey } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(maxPages !== undefined ? { max_pages: maxPages } : {}),
+        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
+        ...(source ? { source } : {}),
+        ...(Object.keys(sourceOverrides).length > 0 ? { source_overrides: sourceOverrides } : {}),
+        ...(filters ? { filters } : {}),
+        // Free sizing is on by default when planning from a prompt; --no-estimate opts out.
+        ...(prompt ? { estimate: options.estimate !== false } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+// PeopleSearchFilters mirror (structural — the server validates the shape). Builds a
+// filters object from individual --titles/--seniorities/etc. flags, then lets --filters-json
+// win per top-level filter path so an agent can pass a precise object while still using
+// convenience flags for the rest.
+function readPeopleSearchFilters(options) {
+    const filters = {};
+    const titles = {};
+    const titleInclude = readCsvOption(options.titles);
+    if (titleInclude.length > 0)
+        titles.include = titleInclude;
+    const adjacent = readCsvOption(options.adjacentTitles);
+    if (adjacent.length > 0)
+        titles.include_adjacent = adjacent;
+    const titleExclude = readCsvOption(options.excludeTitles);
+    if (titleExclude.length > 0)
+        titles.exclude = titleExclude;
+    const titleMatch = options.titleMatch?.trim().toLowerCase();
+    if (titleMatch) {
+        if (titleMatch !== "keyword" && titleMatch !== "exact") {
+            throw new OxygenError("invalid_title_match", '--title-match must be "keyword" or "exact".', {
+                details: { flag: "--title-match", value: options.titleMatch },
+                exitCode: 1,
+            });
+        }
+        titles.match_mode = titleMatch;
+    }
+    if (Object.keys(titles).length > 0)
+        filters.titles = titles;
+    const seniorities = readCsvOption(options.seniorities);
+    if (seniorities.length > 0)
+        filters.seniorities = { include: seniorities };
+    const departments = readCsvOption(options.departments);
+    if (departments.length > 0)
+        filters.departments = { include: departments };
+    const jobFunctions = readCsvOption(options.jobFunctions);
+    if (jobFunctions.length > 0)
+        filters.job_functions = jobFunctions;
+    const keywords = readCsvOption(options.keywords);
+    if (keywords.length > 0)
+        filters.keywords = { include: keywords };
+    const geo = readPeopleSearchGeo(options);
+    if (geo)
+        filters.geo = geo;
+    const minConnections = readNonNegativeInt(options.minConnections);
+    if (minConnections !== undefined)
+        filters.min_connections = minConnections;
+    const contactability = {};
+    if (options.requireEmail)
+        contactability.require_work_email = true;
+    if (options.requirePhone)
+        contactability.require_mobile = true;
+    if (Object.keys(contactability).length > 0)
+        filters.contactability = contactability;
+    const company = {};
+    const companyDomains = readCsvOption(options.companyDomains);
+    if (companyDomains.length > 0)
+        company.domains = { include: companyDomains };
+    const companyNames = readCsvOption(options.companyNames);
+    if (companyNames.length > 0)
+        company.names = { include: companyNames };
+    const employees = readRangeOption(options.employees, "--employees");
+    if (employees)
+        company.employee_count = employees;
+    if (Object.keys(company).length > 0)
+        filters.company = company;
+    const maxPerCompany = readPositiveInt(options.maxPerCompany);
+    if (maxPerCompany !== undefined)
+        filters.max_results_per_company = maxPerCompany;
+    const explicit = options.filtersJson ? parseJsonObject(readFileIfPresent(options.filtersJson)) : null;
+    if (explicit) {
+        for (const [key, value] of Object.entries(explicit)) {
+            filters[key] = value;
+        }
+    }
+    return Object.keys(filters).length > 0 ? filters : null;
+}
+// Person location filters share one `geo` object: country, continent, and sales
+// region are separate provider fields, so each one must merge into it rather than
+// replace it.
+function readPeopleSearchGeo(options) {
+    const geo = {};
+    const countries = readCsvOption(options.countries);
+    if (countries.length > 0)
+        geo.countries = countries;
+    const continents = readCsvOption(options.continents);
+    if (continents.length > 0)
+        geo.continents = continents;
+    const salesRegions = readCsvOption(options.salesRegions);
+    if (salesRegions.length > 0)
+        geo.sales_regions = salesRegions;
+    return Object.keys(geo).length > 0 ? geo : null;
+}
+export function registerPeopleFamily(program, handleAsyncAction) {
+    program
+        .command("people")
+        .description("People and contact prospecting workflows.")
+        .addCommand(new Command("search")
+        .description("Plan, dry-run, or queue provider-backed people/contact search.")
+        .addCommand(new Command("filters")
+        .description("List Find people filter fields and options without a provider call: people.* (title, level, function, location, education) and company.* (industry, headcount, location, funding, up to 50 company LinkedIn URLs). Every enum field ships its full accepted-value list, so no value has to be guessed. Shape rule: only a field whose own key ends in .include or .exclude takes {include, exclude} — every other list field takes the strings directly. For the companies in a table you already have, sample them free with people search preview --from-table <table> --linkedin-url-column <key>, then people search plan|run --from-table to search each company and write a company relation back.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("people search filters", options, () => requestOxygen("/api/cli/people/search/preview"));
+    }))
+        .addCommand(new Command("preview")
+        .description("Preview up to 50 people free, using native filters from people search filters. For the companies in one of your tables, pass --from-table with --linkedin-url-column; for a few named companies, put their LinkedIn company URLs in company.linkedin_url. Totals, per-company counts, company_fit (what a person row cannot tell you about fit) and the priced next step come first, the rows last. Then people search run --source people_search --source-filters-json <same filters> for a quoted, approved table fill; people search run --from-table instead runs one paid search per company in a table and covers each one.")
+        .requiredOption("--filters-json <json-or-file>", 'Nested native filters as JSON or @file/path, e.g. {"people":{"job_title":{"include":["VP Sales"]}},"company":{"linkedin_url":["https://linkedin.com/company/acme"]}}; {} searches all.')
+        .option("--from-table <table>", "Free sample of Find decision makers at companies: search the first 50 companies in this table in one free page. Pair with --linkedin-url-column.")
+        .option("--linkedin-url-column <key>", "Column of --from-table that holds each company's LinkedIn URL.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("people search preview", options, async () => {
+            if ((options.fromTable === undefined) !== (options.linkedinUrlColumn === undefined)) {
+                throw new OxygenError("invalid_request", "--from-table and --linkedin-url-column go together.", { exitCode: 1 });
+            }
+            return requestOxygen("/api/cli/people/search/preview", {
+                method: "POST",
+                body: {
+                    filters: parseJsonObject(readFileIfPresent(options.filtersJson)),
+                    ...(options.fromTable !== undefined
+                        ? { source: { table: options.fromTable, linkedin_url_column: options.linkedinUrlColumn } }
+                        : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("plan")
+        .description("Compile a people-search prompt and optional typed persona filters into ordered provider routes without provider calls.")
+        .option("--prompt <text-or-file>", "People-search prompt, or a path to a prompt file. Required unless --from-table names the companies to source employees from.")
+        .option("--target-count <n>", "Desired contact count. Omit it to plan every match the live route can reach, up to a tenth of the spendable credits. Single-plan ceiling 50,000; larger requests return an explicit clamp warning and segmentation guidance.")
+        .option("--source-intent <intent>", "Override detected intent: persona_search, account_contacts, audience_sizing, profile_lookup, concept_persona, or fallback_broad.")
+        .option("--filters-json <json-or-file>", "PeopleSearchFilters JSON inline or a @file/path; wins over individual flags per top-level filter path.")
+        .option("--titles <csv>", "Comma-separated job titles to include.")
+        .option("--title-match <mode>", "How to match --titles: keyword (default, full-text/partial, highest recall) or exact (literal title only).")
+        .option("--adjacent-titles <csv>", "Comma-separated adjacent/looser titles to accept.")
+        .option("--exclude-titles <csv>", "Comma-separated job titles to exclude.")
+        .option("--seniorities <csv>", "Comma-separated seniority levels: C-Suite, VP, Director, Manager, Staff.")
+        .option("--departments <csv>", "Comma-separated departments/functions: Sales, Marketing, Engineering, ...")
+        .option("--job-functions <csv>", PEOPLE_SEARCH_JOB_FUNCTIONS_HELP)
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 person country codes.")
+        .option("--continents <csv>", PEOPLE_SEARCH_CONTINENTS_HELP)
+        .option("--sales-regions <csv>", PEOPLE_SEARCH_SALES_REGIONS_HELP)
+        .option("--min-connections <n>", PEOPLE_SEARCH_MIN_CONNECTIONS_HELP)
+        .option("--from-table <table>", PEOPLE_SEARCH_FROM_TABLE_HELP)
+        .option("--linkedin-url-column <key>", PEOPLE_SEARCH_LINKEDIN_COLUMN_HELP)
+        .option("--company-offset <n>", PEOPLE_SEARCH_COMPANY_OFFSET_HELP)
+        .option("--company-limit <n>", PEOPLE_SEARCH_COMPANY_LIMIT_HELP)
+        .option("--keywords <csv>", "Comma-separated free-text persona keywords.")
+        .option("--company-domains <csv>", "Comma-separated company domains to scope contacts to.")
+        .option("--company-names <csv>", "Comma-separated company names to scope contacts to.")
+        .option("--employees <range>", "Company employee count range: 20-200, 500+, or -50.")
+        .option("--require-email", "Only return people with a work email available (provider-dependent).")
+        .option("--require-phone", "Only return people with a phone/mobile available (provider-dependent).")
+        .option("--max-per-company <n>", "Cap on contacts per company for account-anchored searches.")
+        .option("--estimate", "Run a free count probe for an estimated match count (on by default).")
+        .option("--no-estimate", "Skip the default free count probe (people-search sizing is on by default).")
+        .option("--materialize-preview", "Create a preview table with route rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("people search plan", options, () => requestOxygen("/api/cli/people/search/plan", {
+            method: "POST",
+            body: readPeopleSearchPlanBody(options),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Return a dry-run request or queue a live people-search ingestion run. Upsert dedup is on linkedin_url.")
+        .option("--source <source>", "Use people_search with --source-filters-json instead of a prompt or plan: the same filters as people search preview, no prompt needed.")
+        .option("--source-filters-json <json-or-file>", 'Same nested filters as the free preview, e.g. {"people":{"job_title":{"include":["VP Sales"]}}}; use with --source people_search.')
+        .option("--table-name <name>", "Name the table this run creates. Ignored when --table names an existing table, which must already exist.")
+        .option("--prompt <text-or-file>", "People-search prompt, or a path to a prompt file.")
+        .option("--plan-json <json-or-file>", "Plan JSON returned by people search plan, or a path to a JSON file.")
+        .option("--route-id <id>", "Route id from the plan to execute.")
+        .option("--tool-id <tool>", "Tool id from the plan to execute.")
+        .option("--table <table>", "Existing table id or slug to receive rows. If omitted for live, Oxygen creates a table.")
+        .option("--project <project>", "Folder (project) id or slug the created table lands in. Ignored with --table. Defaults to the workspace default folder.")
+        .option("--upsert-key <column>", "Column key used for live upsert. Must match the plan upsert key (linkedin_url).")
+        .option("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-pages <n>", "Maximum provider pages to ingest. Defaults to the route estimate. With --from-table it means pages per company.")
+        .option("--max-credits <n>", "Required credit ceiling for live runs.")
+        .option("--target-count <n>", "How many people to source. Omit it to take every match, up to what one query reaches and a tenth of the spendable credits. Single-plan ceiling 50,000.")
+        .option("--source-intent <intent>", "Override detected intent when planning from --prompt.")
+        .option("--filters-json <json-or-file>", "PeopleSearchFilters JSON inline or a @file/path when planning from --prompt; wins over individual flags per top-level filter path.")
+        .option("--titles <csv>", "Comma-separated job titles to include when planning from --prompt.")
+        .option("--title-match <mode>", "How to match --titles: keyword (default, full-text/partial, highest recall) or exact (literal title only).")
+        .option("--adjacent-titles <csv>", "Comma-separated adjacent titles when planning from --prompt.")
+        .option("--exclude-titles <csv>", "Comma-separated job titles to exclude when planning from --prompt.")
+        .option("--seniorities <csv>", "Comma-separated seniority levels when planning from --prompt.")
+        .option("--departments <csv>", "Comma-separated departments/functions when planning from --prompt.")
+        .option("--job-functions <csv>", PEOPLE_SEARCH_JOB_FUNCTIONS_HELP)
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 person country codes when planning from --prompt.")
+        .option("--continents <csv>", PEOPLE_SEARCH_CONTINENTS_HELP)
+        .option("--sales-regions <csv>", PEOPLE_SEARCH_SALES_REGIONS_HELP)
+        .option("--min-connections <n>", PEOPLE_SEARCH_MIN_CONNECTIONS_HELP)
+        .option("--from-table <table>", PEOPLE_SEARCH_FROM_TABLE_HELP)
+        .option("--linkedin-url-column <key>", PEOPLE_SEARCH_LINKEDIN_COLUMN_HELP)
+        .option("--company-offset <n>", PEOPLE_SEARCH_COMPANY_OFFSET_HELP)
+        .option("--company-limit <n>", PEOPLE_SEARCH_COMPANY_LIMIT_HELP)
+        .option("--pages-per-company <n>", "Alias for --max-pages on a --from-table run: provider pages per company, 50 people per page.")
+        .option("--keywords <csv>", "Comma-separated persona keywords when planning from --prompt.")
+        .option("--company-domains <csv>", "Comma-separated company domains when planning from --prompt.")
+        .option("--company-names <csv>", "Comma-separated company names when planning from --prompt.")
+        .option("--employees <range>", "Company employee count range when planning from --prompt.")
+        .option("--require-email", "Only return people with a work email available when planning from --prompt.")
+        .option("--require-phone", "Only return people with a phone available when planning from --prompt.")
+        .option("--max-per-company <n>", "Cap on contacts per company when planning from --prompt.")
+        .option("--estimate", "Run a free count probe when planning from --prompt (on by default).")
+        .option("--no-estimate", "Skip the default free count probe when planning from --prompt.")
+        .option("--approved", "Required for live runs after inspecting dry-run output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("people search run", options, () => requestOxygen("/api/cli/people/search/run", {
+            method: "POST",
+            body: readPeopleSearchRunBody(options),
+        }));
+    })));
+}

package/dist/commands/posts.d.ts

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

package/dist/commands/posts.js

@@ -0,0 +1,139 @@
+import { parseJsonArray, readFileIfPresent } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { LINKEDIN_SENDER_LIMIT_DEFAULTS, LINKEDIN_SENDER_LIMIT_MAXIMUMS } from "@oxygen/shared/linkedin-sequences";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+// Shared query string for `posts comments` / `posts reactions` (post social_id +
+// optional comment scope, pagination, sort, and account selection).
+function buildPostEngagementQuery(options) {
+    const params = new URLSearchParams();
+    params.set("post", readOption(options.post) ?? "");
+    const commentId = readOption(options.commentId);
+    if (commentId)
+        params.set("comment_id", commentId);
+    const sortBy = readOption(options.sortBy);
+    if (sortBy)
+        params.set("sort_by", sortBy);
+    const cursor = readOption(options.cursor);
+    if (cursor)
+        params.set("cursor", cursor);
+    const limit = readOption(options.limit);
+    if (limit)
+        params.set("limit", limit);
+    const account = readOption(options.account);
+    if (account)
+        params.set("account", account);
+    return params.toString();
+}
+export function registerPostsFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("posts")
+        .description("Read and publish LinkedIn posts through a connected account. `get`, `comments`, and `reactions` are LIVE provider reads: they use 0 Oxygen credits but consume the sender's daily account-read allowance. Do not use them when a task forbids provider calls; use `publishing comments list` for the local Community queue, which discovers recent posts owned by connected accounts in the background. `create` publishes a real post (approval-gated). The direct commands here address ONE post you already have an id for; aggregate analytics are `oxygen publishing analytics` (LinkedIn includes owned posts discovered from the provider).")
+        .addCommand(new Command("get")
+        .description("LIVE provider read of one LinkedIn post. Uses 0 Oxygen credits but consumes the sender's metered account-read allowance; do not run it when the task forbids provider calls. Returns the post and its composite social_id (reuse that social_id for `posts comments`, `posts reactions`, and `engagement harvest --source unipile` — NOT the raw activity URN). This does not populate or refresh the durable `publishing comments` queue.")
+        .requiredOption("--post <id>", "Numeric activity id, activity URL, or composite social_id. For a direct live read, take the id from the post's LinkedIn URL or a scheduled post (`oxygen publishing posts get <post_id>` → provider_post_id); Community discovers recent owned posts separately in the background.")
+        .option("--account <ref>", "Sender account to read through (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("posts get", options, () => {
+            const params = new URLSearchParams();
+            params.set("post", readOption(options.post) ?? "");
+            const account = readOption(options.account);
+            if (account)
+                params.set("account", account);
+            return requestOxygen(`/api/cli/linkedin/posts?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("comments")
+        .description("Read one post's comments live from LinkedIn (or one comment's replies with --comment-id). This consumes the sender's metered account-read allowance, uses 0 Oxygen credits, and does not populate the durable queue. For the zero-provider-call cross-post work queue, use `publishing comments list`. --post MUST be the composite social_id from `posts get`, not the activity URN.")
+        .requiredOption("--post <social_id>", "Composite post social_id from `posts get`.")
+        .option("--comment-id <id>", "List replies to this comment instead of top-level comments.")
+        .option("--sort-by <sort>", "Comment sort order (provider-defined, e.g. recent|relevant).")
+        .option("--cursor <cursor>", "Pagination cursor from a previous page.")
+        .option("--limit <n>", "Max comments to return this page.")
+        .option("--account <ref>", "Sender account to read through. Omit for the org default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("posts comments", options, () => requestOxygen(`/api/cli/linkedin/posts/comments?${buildPostEngagementQuery(options)}`));
+    }))
+        .addCommand(new Command("reactions")
+        .description("List a post's reactions (or a comment's reactions with --comment-id). --post MUST be the composite social_id from `posts get`. Metered as an account read.")
+        .requiredOption("--post <social_id>", "Composite post social_id from `posts get`.")
+        .option("--comment-id <id>", "List reactions to this comment instead of the post.")
+        .option("--cursor <cursor>", "Pagination cursor from a previous page.")
+        .option("--limit <n>", "Max reactions to return this page.")
+        .option("--account <ref>", "Sender account to read through. Omit for the org default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("posts reactions", options, () => requestOxygen(`/api/cli/linkedin/posts/reactions?${buildPostEngagementQuery(options)}`));
+    }))
+        .addCommand(new Command("create")
+        .description(`Publish a LinkedIn post from the connected account. A REAL public write, so it prints a preview by default and only publishes with --approved. Counts against the account's posts_per_day cap (default ${LINKEDIN_SENDER_LIMIT_DEFAULTS.posts_per_day}, max ${LINKEDIN_SENDER_LIMIT_MAXIMUMS.posts_per_day}), not the daily action total, and is exempt from working hours and action spacing. (Company-page posting is not supported — Unipile exposes it only via the fragile raw route.)`)
+        .option("--text <text>", "Post body text.")
+        .option("--text-file <path>", "Read the post body from a file (alternative to --text).")
+        .option("--account <ref>", "Sender account to post from. Omit for the org default.")
+        .option("--as-organization <id>", "Publish as a company page the account administers (advanced; may require raw-route support).")
+        .option("--repost <id>", "Quote or share this LinkedIn post.")
+        .option("--include-job-posting <id>", "Embed a LinkedIn job preview.")
+        .option("--attachments-json <json-or-file>", "Up to 20 {content:<base64>,content_type:<MIME>,filename:<name>} objects; use a local JSON file for media.")
+        .option("--external-link <url>", "Attach an external link to the post.")
+        .option("--approved", "Publish for real. Without this flag, prints a preview only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("posts create", options, () => {
+            const inlineText = readOption(options.text);
+            const textFile = readOption(options.textFile);
+            const text = inlineText ?? (textFile ? readFileSync(resolve(textFile), "utf8") : undefined);
+            if (!text || !text.trim())
+                throw new Error("--text or --text-file is required to publish a post.");
+            const account = readOption(options.account);
+            const asOrganization = readOption(options.asOrganization);
+            const externalLink = readOption(options.externalLink);
+            return requestOxygen("/api/cli/linkedin/posts", {
+                method: "POST",
+                body: {
+                    text,
+                    ...(account ? { account } : {}),
+                    ...(asOrganization ? { as_organization: asOrganization } : {}),
+                    ...(externalLink ? { external_link: externalLink } : {}),
+                    ...(readOption(options.repost) ? { repost: readOption(options.repost) } : {}),
+                    ...(readOption(options.includeJobPosting) ? { include_job_posting: readOption(options.includeJobPosting) } : {}),
+                    ...(options.attachmentsJson !== undefined ? { attachments: parseJsonArray(readFileIfPresent(options.attachmentsJson)) } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete a LinkedIn post the connected account authored — a REAL, irreversible public write. Refuses without --approved (exit 7). --post is the composite social_id returned when the post was created (or by `oxygen posts get`), NOT the activity URN. To remove only the OXYGEN copy, including a settled published copy, while keeping LinkedIn intact, use `oxygen publishing posts delete`.")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (the id returned when the post was created).")
+        .option("--account <ref>", "Sender account that authored the post (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--approved", "Actually delete the post. Without it the command refuses and deletes nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("posts delete", options, () => {
+            const post = readOption(options.post);
+            if (!post)
+                throw new Error("--post is required (the composite social_id from `oxygen posts get`).");
+            const account = readOption(options.account);
+            // The DELETE route has no preview mode — it removes the live post on
+            // the first call — so the approval gate lives here. Refuse rather than
+            // silently deleting a real, public, irreversible artifact.
+            if (!options.approved) {
+                throw new OxygenError("approval_required", "Deleting a LinkedIn post is a real, irreversible public write. Re-run with --approved to delete it.", {
+                    details: { post, ...(account ? { account } : {}) },
+                    exitCode: 7,
+                });
+            }
+            const params = new URLSearchParams();
+            params.set("post", post);
+            if (account)
+                params.set("account", account);
+            return requestOxygen(`/api/cli/linkedin/posts?${params.toString()}`, {
+                method: "DELETE",
+            });
+        });
+    })));
+}

package/dist/commands/profiles.d.ts

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