@oxygen-agent/cli 1.1014.136 → 1.1014.618

package/dist/commands/suppressions.d.ts

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

package/dist/commands/suppressions.js

@@ -0,0 +1,577 @@
+import { emitCliFailure, writeCreditsReceipt, writeJson } from "../cli-output.js";
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { parseJsonValue, readFileIfPresent, readJsonFileValue, readPositiveNumber, splitCommaList } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { addSuppressionListFlags, suppressionListQuery } from "../workspace-utility-flags.js";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+function readSuppressionBulkKeys(value, flag) {
+    const entries = splitCommaList(value);
+    if (entries.length === 0 || entries.length > 500) {
+        throw new OxygenError("invalid_request", `${flag} requires 1-500 nonblank entries.`, { exitCode: 2 });
+    }
+    return entries;
+}
+function suppressionListParams(options) {
+    const params = new URLSearchParams();
+    const reason = readOption(options.reason);
+    const search = readOption(options.search);
+    const limit = readOption(options.limit);
+    const offset = readOption(options.offset);
+    if (reason)
+        params.set("reason", reason);
+    if (search)
+        params.set("search", search);
+    if (limit)
+        params.set("limit", limit);
+    if (offset)
+        params.set("offset", offset);
+    return params;
+}
+export function registerSuppressionsFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("suppressions")
+        .description("Unified do-not-contact controls for people and typed identities. `policy` decides WHO GETS ADDED automatically -- which replies, bounces, unsubscribes and call outcomes put someone on the list, and whether each one blocks them forever or only stops the current campaign. `crm-backfill` files the people already on the list into your CRM. `import-person` bundles one contact's email, LinkedIn, phone, and explicit company domain; `import` preserves the legacy mixed-file contract; `import-identities` is the integration-level typed endpoint; `hubspot lists|sync` arms additive synchronization. Company DNC applies across Sequence channels and is never inferred from a person's email. Consumes 0 credits.")
+        .addCommand(new Command("policy")
+        .description("Do-not-contact RULES: who gets added to the list automatically. Seven events can add someone -- an email hard bounce, a one-click unsubscribe, opt-out wording in a reply, ANY inbound LinkedIn reply, ANY inbound WhatsApp reply, and the do-not-call / wrong-number call outcomes -- plus an optional rule per inbox reply classification. Each rule is off, stop_only (end this campaign but do not block future ones) or suppress (the default for all seven, and what every version before this did). Blocking itself is never configurable: once someone is on the list they are always skipped. Consumes 0 credits.")
+        .addCommand(new Command("show")
+        .description("Show every do-not-contact rule with its current setting, whether that is your change or the shipped default, and the values it accepts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions policy", options, () => requestOxygen("/api/cli/suppressions/policy"));
+    }))
+        .addCommand(new Command("set")
+        .description("Change one rule. Example: `oxygen suppressions policy set --rule linkedin_reply --effect stop_only` stops a LinkedIn replier's current campaign without blocking them from every future one.")
+        .requiredOption("--rule <key>", "Rule key from `policy show` (e.g. linkedin_reply, whatsapp_reply, email_hard_bounce, reply_status:not_interested).")
+        .requiredOption("--effect <effect>", "off (do nothing), stop_only (end this enrollment only) or suppress (also add to the do-not-contact list).")
+        .option("--reason <reason>", "Reason stamped on the list entry when the rule suppresses. Defaults to the rule's own.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions policy set", options, () => {
+            const rule = readOption(options.rule);
+            if (!rule)
+                throw new Error("--rule is required.");
+            const effect = readOption(options.effect);
+            if (!effect)
+                throw new Error("--effect is required.");
+            const reason = readOption(options.reason);
+            return requestOxygen("/api/cli/suppressions/policy", {
+                method: "POST",
+                body: { rule, effect, ...(reason ? { reason } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("reset")
+        .description("Return one rule (--rule) or every rule (--all) to the shipped default.")
+        .option("--rule <key>", "Rule key to reset.")
+        .option("--all", "Reset every rule instead of one.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions policy set", options, () => {
+            const rule = readOption(options.rule);
+            if (options.all && rule)
+                throw new Error("Pass either --rule or --all, not both.");
+            if (!options.all && !rule)
+                throw new Error("--rule is required (or pass --all).");
+            return requestOxygen("/api/cli/suppressions/policy", {
+                method: "POST",
+                body: options.all ? { reset_all: true } : { rule, reset: true },
+            });
+        });
+    })))
+        .addCommand(new Command("crm-backfill")
+        .description("Create a CRM person record for everyone already on the do-not-contact list, so you can see who they are. New suppressions do this automatically; this covers the ones added before. Previews by default and writes nothing until you pass --live. Consumes 0 credits: it never runs enrichment on the records it creates.")
+        .option("--live", "Actually create the records. Without this the command only reports what it would create.")
+        .option("--limit <n>", "People to process in this call (1-500; default 200).")
+        .option("--offset <n>", "Resume cursor; pass the next_offset from the previous call.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions crm-backfill", options, () => {
+            const limit = readOption(options.limit);
+            const offset = readOption(options.offset);
+            return requestOxygen("/api/cli/suppressions/crm-backfill", {
+                method: "POST",
+                body: {
+                    ...(options.live ? { live: true } : {}),
+                    ...(limit ? { limit: Number(limit) } : {}),
+                    ...(offset ? { offset: Number(offset) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List the org's do-not-contact suppressions, newest first. Filter by --reason or by --search (case-insensitive substring of the lead provider id).")
+        .option("--reason <reason>", "Filter by reason: manual, replied, unsubscribed, bounced, do_not_contact, friends.")
+        .option("--search <text>", "Case-insensitive substring match on the lead provider id.")
+        .option("--limit <n>", "Maximum suppressions to return (1-500; default 100).")
+        .option("--offset <n>", "Pagination offset (0-based).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions list", options, () => {
+            const params = new URLSearchParams();
+            const reason = readOption(options.reason);
+            if (reason)
+                params.set("reason", reason);
+            const search = readOption(options.search);
+            if (search)
+                params.set("search", search);
+            const limit = readOption(options.limit);
+            if (limit)
+                params.set("limit", limit);
+            const offset = readOption(options.offset);
+            if (offset)
+                params.set("offset", offset);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/suppressions${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("add")
+        .description("Add or refresh selected lead ids on the org do-not-contact list so the sequencer never enrolls them again. Use --lead or --leads (1-500). Idempotent; --reason defaults to manual.")
+        .option("--lead <provider_id>", "One lead provider id to suppress; exclusive with --leads.")
+        .option("--leads <ids>", "Comma-separated lead provider ids to suppress in one bounded batch (1-500).")
+        .option("--reason <reason>", "Why: manual (default), replied, unsubscribed, bounced, do_not_contact, friends.")
+        .option("--detail <text>", "Optional free-text note stored with the suppression.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions add", options, () => {
+            const lead = readOption(options.lead);
+            const leads = options.leads !== undefined ? readSuppressionBulkKeys(options.leads, "--leads") : undefined;
+            if (Boolean(lead) === Boolean(leads))
+                throw new OxygenError("invalid_request", "Pass exactly one of --lead or --leads.", { exitCode: 2 });
+            const reason = readOption(options.reason);
+            const detail = readOption(options.detail);
+            return requestOxygen("/api/cli/suppressions", {
+                method: "POST",
+                body: {
+                    ...(leads ? { lead_provider_ids: leads } : { lead_provider_id: lead }),
+                    ...(reason ? { reason } : {}),
+                    ...(detail ? { detail } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("remove")
+        .description("Remove selected leads or every identity of selected merged people from the org do-not-contact list. Choose one of --lead, --leads, --subject-id or --subject-ids; batches hold 1-500 ids. Read a person's metadata.dnc_subject_id in suppressions list, addresses, phones or companies --json.")
+        .option("--lead <provider_id>", "The lead provider id to un-suppress. Mutually exclusive with --subject-id.")
+        .option("--subject-id <id>", "DNC subject id (metadata.dnc_subject_id). Clears that person's email, phone, LinkedIn, and company suppressions in one transaction.")
+        .option("--leads <ids>", "Comma-separated lead provider ids to remove in one bounded batch (1-500).")
+        .option("--subject-ids <ids>", "Comma-separated merged-person subject ids to remove across every ledger (1-500).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        if (options.leads !== undefined || options.subjectIds !== undefined) {
+            await handleAsyncAction("suppressions remove", options, () => {
+                const selectors = [options.lead, options.subjectId, options.leads, options.subjectIds].filter((value) => value !== undefined);
+                if (selectors.length !== 1)
+                    throw new OxygenError("invalid_request", "Pass exactly one of --lead, --leads, --subject-id or --subject-ids.", { exitCode: 2 });
+                return requestOxygen("/api/cli/suppressions", {
+                    method: "DELETE",
+                    body: options.leads !== undefined
+                        ? { lead_provider_ids: readSuppressionBulkKeys(options.leads, "--leads") }
+                        : { subject_ids: readSuppressionBulkKeys(options.subjectIds, "--subject-ids") },
+                });
+            });
+            return;
+        }
+        const subjectId = readOption(options.subjectId);
+        if (!subjectId) {
+            await handleAsyncAction("suppressions remove", options, () => {
+                const lead = readOption(options.lead);
+                if (!lead)
+                    throw new Error("Pass --lead <provider_id> or --subject-id <id>.");
+                return requestOxygen(`/api/cli/suppressions?lead_provider_id=${encodeURIComponent(lead)}`, {
+                    method: "DELETE",
+                });
+            });
+            return;
+        }
+        try {
+            if (readOption(options.lead)) {
+                throw new Error("Pass either --lead or --subject-id, not both.");
+            }
+            const data = await requestOxygen(`/api/cli/suppressions?subject_id=${encodeURIComponent(subjectId)}`, { method: "DELETE" });
+            if (options.json) {
+                writeJson(success("suppressions remove", data));
+            }
+            else {
+                // Same compact multi-ledger receipt style as `suppressions import`:
+                // the per-channel counts plus up to 10 cleared identifiers (the full
+                // list is always in the --json envelope).
+                const parsed = (data ?? {});
+                const identities = Array.isArray(parsed.removed_identities) ? parsed.removed_identities : [];
+                const removedCount = parsed.removed_count ?? 0;
+                writeJson({
+                    subject_id: parsed.subject_id ?? subjectId,
+                    removed_count: removedCount,
+                    removed_emails: parsed.removed?.email ?? 0,
+                    removed_phones: parsed.removed?.phone ?? 0,
+                    removed_linkedin: parsed.removed?.linkedin ?? 0,
+                    removed_companies: parsed.removed?.company ?? 0,
+                    removed_identities: identities.slice(0, 10),
+                    // Counted off removed_count, not the echoed array: the API caps
+                    // that list too, so --json is NOT a way to see the rest. The
+                    // counts above are the exact record of what was cleared.
+                    ...(removedCount > Math.min(identities.length, 10)
+                        ? {
+                            removed_identities_note: `Showing ${Math.min(identities.length, 10)} of ${removedCount} cleared identifiers; the counts above are exact.`,
+                        }
+                        : {}),
+                    ...(parsed.note ? { note: parsed.note } : {}),
+                    deep_link: parsed.deepLink,
+                });
+            }
+            writeCreditsReceipt(data);
+        }
+        catch (error) {
+            emitCliFailure("suppressions remove", error);
+        }
+    }))
+        .addCommand(new Command("import")
+        .description("Bulk-import a do-not-contact blocklist from a file (newline / comma / whitespace separated, max 5000). An entry with '@' goes on the per-address email list; a bare domain (e.g. acme.com) blocks email to that whole domain; a LinkedIn profile URL or member id (ACo...) lands on the people do-not-contact list; any other URL is rejected. A domain block is a sharp tool, so --reason is REQUIRED when the file contains any domains; otherwise manual is the default. Idempotent. Consumes 0 credits.")
+        .requiredOption("--file <path>", "Path to a file of emails, bare domains, LinkedIn profile URLs, and/or LinkedIn member ids, separated by newlines, commas, or whitespace.")
+        .option("--reason <reason>", "Suppression reason. Emails: hard_bounce | complaint | unsubscribe | manual. Domains: manual | complaint | policy. LinkedIn contacts: manual | replied | unsubscribed | bounced | do_not_contact | friends. Required when the file contains any domains; must be valid for every entry type present (manual always is).")
+        .option("--source <text>", "Optional provenance note stored on every imported row (e.g. instantly_export).")
+        .option("--metadata-json <json-or-file>", "Default metadata stored on imported identities.")
+        .option("--detail <text>", "Optional free-text note stored on every imported row.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        try {
+            const file = readOption(options.file);
+            if (!file)
+                throw new Error("--file is required.");
+            const text = readFileSync(resolve(file), "utf8");
+            const entries = [
+                ...new Set(text
+                    .split(/[\s,]+/)
+                    .map((entry) => entry.trim())
+                    .filter((entry) => entry.length > 0)),
+            ];
+            if (entries.length === 0)
+                throw new Error(`No emails, domains, or LinkedIn ids found in ${file}.`);
+            const reason = readOption(options.reason);
+            const source = readOption(options.source);
+            const detail = readOption(options.detail);
+            const data = await requestOxygen("/api/cli/suppressions/import", {
+                method: "POST",
+                body: {
+                    entries,
+                    ...(options.metadataJson !== undefined ? { metadata: parseJsonObject(readFileIfPresent(options.metadataJson)) } : {}),
+                    ...(reason ? { reason } : {}),
+                    ...(source ? { source } : {}),
+                    ...(detail ? { detail } : {}),
+                },
+            });
+            if (options.json) {
+                writeJson(success("suppressions import", data));
+            }
+            else {
+                // Compact human view: the counts plus up to 10 rejected entries (the
+                // full list is always in the --json envelope).
+                const parsed = (data ?? {});
+                const rejected = Array.isArray(parsed.rejected) ? parsed.rejected : [];
+                writeJson({
+                    imported_emails: parsed.imported_emails ?? 0,
+                    imported_domains: parsed.imported_domains ?? 0,
+                    imported_contacts: parsed.imported_contacts ?? 0,
+                    imported_phones: parsed.imported_phones ?? 0,
+                    imported_company_domains: parsed.imported_company_domains ?? 0,
+                    imported_linkedin_companies: parsed.imported_linkedin_companies ?? 0,
+                    accepted_identities: parsed.accepted_identities ?? 0,
+                    rejected_count: rejected.length,
+                    rejected: rejected.slice(0, 10),
+                    ...(rejected.length > 10
+                        ? { rejected_note: `+${rejected.length - 10} more (use --json for the full list)` }
+                        : {}),
+                    deep_link: parsed.deep_link,
+                });
+            }
+            writeCreditsReceipt(data);
+        }
+        catch (error) {
+            emitCliFailure("suppressions import", error);
+        }
+    }))
+        .addCommand(new Command("import-identities")
+        .description("Import a source-neutral typed JSON array into DNC. Kinds: email, phone, linkedin_person, company_domain, linkedin_company. Preferred for integrations; company identities apply across every Sequence channel and are never inferred from a person's email. A company entry is a permanent block on every campaign; to pause a company and resume it later, use `sequences pause-company`.")
+        .requiredOption("--file <path>", "JSON file containing [{kind,value,reason?,source?,detail?,metadata?}], max 5000.")
+        .option("--reason <reason>", "Default reason for entries that omit one.")
+        .option("--source <text>", "Default provenance for entries that omit one.")
+        .option("--detail <text>", "Default note for entries that omit one.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions import-identities", options, () => {
+            const file = readOption(options.file);
+            if (!file)
+                throw new Error("--file is required.");
+            const identities = readJsonFileValue(resolve(file), "--file");
+            if (!Array.isArray(identities) || identities.length === 0 || identities.length > 5000) {
+                throw new Error("--file must contain a non-empty JSON array with at most 5000 identities.");
+            }
+            const reason = readOption(options.reason);
+            const source = readOption(options.source);
+            const detail = readOption(options.detail);
+            return requestOxygen("/api/cli/suppressions/import", {
+                method: "POST",
+                body: {
+                    identities,
+                    ...(reason ? { reason } : {}),
+                    ...(source ? { source } : {}),
+                    ...(detail ? { detail } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("import-person")
+        // Deliberately NOT extended with the subjects[] pointer: this help text
+        // is already 199 chars, and the generated CLI reference cell truncates a
+        // description past 200 to its FIRST sentence — appending anything drops
+        // the "domain is company-wide, never inferred from --email" warning from
+        // the public table. The receipt itself carries `subjects[]`, and
+        // `suppressions remove --help` names where subject ids come from.
+        .description("Import one person as one DNC subject with any combination of email, LinkedIn, E.164 phone, and an explicitly supplied company domain. The domain is company-wide and is never inferred from --email.")
+        .option("--name <name>", "Optional contact display name.")
+        .option("--email <address>", "Email address to suppress.")
+        .option("--linkedin <url_or_id>", "Public LinkedIn person URL or member id to suppress.")
+        .option("--phone <e164>", "Strict E.164 phone number to suppress.")
+        .option("--domain <domain>", "Explicit company-wide domain block. This affects every Sequence channel.")
+        .option("--reason <reason>", "Suppression reason; manual by default and valid for every bundled identifier.")
+        .option("--source <text>", "Optional provenance stored on every identifier.")
+        .option("--detail <text>", "Optional note stored on every identifier.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions import-person", options, () => {
+            const name = readOption(options.name);
+            const email = readOption(options.email);
+            const linkedin = readOption(options.linkedin);
+            const phone = readOption(options.phone);
+            const domain = readOption(options.domain);
+            if (!email && !linkedin && !phone && !domain) {
+                throw new Error("Provide at least one of --email, --linkedin, --phone, or --domain.");
+            }
+            const reason = readOption(options.reason);
+            const source = readOption(options.source);
+            const detail = readOption(options.detail);
+            return requestOxygen("/api/cli/suppressions/import", {
+                method: "POST",
+                body: {
+                    people: [{
+                            ...(name ? { name } : {}),
+                            ...(email ? { email } : {}),
+                            ...(linkedin ? { linkedin_url: linkedin } : {}),
+                            ...(phone ? { phone } : {}),
+                            ...(domain ? { company_domain: domain } : {}),
+                            ...(reason ? { reason } : {}),
+                            ...(source ? { source } : {}),
+                            ...(detail ? { detail } : {}),
+                        }],
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("phones")
+        .description("List phone suppressions (strict E.164) used by call, WhatsApp, and Sequence safety gates.")
+        .option("--reason <reason>", "do_not_call, wrong_number, complaint, or manual.")
+        .option("--search <text>", "Phone substring.")
+        .option("--limit <n>", "Maximum rows (1-500).")
+        .option("--offset <n>", "Pagination offset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions phones", options, () => {
+            const params = suppressionListParams(options);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/suppressions/phones${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("remove-phone")
+        .description("Remove one phone suppression or 1-500 exact E.164 numbers with --phones.")
+        .argument("[phone]", "One strict E.164 number, e.g. +14155550123; exclusive with --phones.")
+        .option("--phones <phones>", "Comma-separated strict E.164 numbers to remove (1-500).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (phone, options) => {
+        await handleAsyncAction("suppressions remove-phone", options, () => {
+            if (Boolean(phone) === (options.phones !== undefined))
+                throw new OxygenError("invalid_request", "Pass one phone or --phones.", { exitCode: 2 });
+            return options.phones !== undefined
+                ? requestOxygen("/api/cli/suppressions/phones", { method: "DELETE", body: { phones: readSuppressionBulkKeys(options.phones, "--phones") } })
+                : requestOxygen(`/api/cli/suppressions/phones?phone=${encodeURIComponent(phone)}`, { method: "DELETE" });
+        });
+    }))
+        .addCommand(new Command("companies")
+        .description("List explicit company-domain and LinkedIn-company suppressions. These stop every Sequence channel.")
+        .option("--kind <kind>", "domain or linkedin_company.")
+        .option("--reason <reason>", "manual, complaint, policy, or do_not_contact.")
+        .option("--search <text>", "Identity substring.")
+        .option("--limit <n>", "Maximum rows (1-500).")
+        .option("--offset <n>", "Pagination offset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions companies", options, () => {
+            const params = suppressionListParams(options);
+            const kind = readOption(options.kind);
+            if (kind)
+                params.set("kind", kind);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/suppressions/companies${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("remove-company")
+        .description("Remove one explicit company suppression or 1-500 exact identities with --identities-json.")
+        .option("--kind <kind>", "domain or linkedin_company; use with --value.")
+        .option("--value <identity>", "One domain or canonical LinkedIn company URL.")
+        .option("--identities-json <json>", "Exact batch of {kind,value} company identities to remove (1-500); exclusive with --kind/--value.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions remove-company", options, () => {
+            const kind = readOption(options.kind);
+            const value = readOption(options.value);
+            if (options.identitiesJson !== undefined) {
+                if (options.kind !== undefined || options.value !== undefined)
+                    throw new OxygenError("invalid_request", "Pass --identities-json or --kind and --value.", { exitCode: 2 });
+                const identities = parseJsonValue(options.identitiesJson, "--identities-json");
+                if (!Array.isArray(identities) || identities.length < 1 || identities.length > 500)
+                    throw new OxygenError("invalid_request", "--identities-json must contain 1-500 {kind,value} objects.", { exitCode: 2 });
+                return requestOxygen("/api/cli/suppressions/companies", { method: "DELETE", body: { identities } });
+            }
+            if (!kind || !value)
+                throw new Error("--kind and --value are required.");
+            const params = new URLSearchParams({ kind, value });
+            return requestOxygen(`/api/cli/suppressions/companies?${params.toString()}`, { method: "DELETE" });
+        });
+    }))
+        .addCommand(new Command("hubspot")
+        .description("Discover and synchronize HubSpot contact/company saved lists into the shared Oxygen DNC endpoint. The same saved lists can be imported as table rows instead — see `oxygen tables hubspot import`, which syncs a do-not-contact list first and then lands the members in a new table.")
+        .addCommand(new Command("lists")
+        .description("List contact/company saved lists and readable identity properties. Reads definitions only; no memberships or writes.")
+        .option("--query <text>", "Optional list-name search.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions hubspot lists", options, () => {
+            const params = new URLSearchParams();
+            const query = readOption(options.query);
+            if (query)
+                params.set("query", query);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/suppressions/hubspot-sync${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("sync")
+        .description("Preview or arm additive HubSpot → DNC sync. Requires at least one contact/company list. Live requires the exact dry-run fingerprint and approval; never enrolls or sends.")
+        .option("--contact-list <id>", "Optional HubSpot contact DNC list id.")
+        .option("--company-list <id>", "Optional HubSpot company DNC list id.")
+        .option("--contact-linkedin-property <name>", "Optional contact LinkedIn profile property.")
+        .option("--company-domain-property <name>", "Company domain property (default domain).", "domain")
+        .option("--company-linkedin-property <name>", "Optional company LinkedIn URL property.")
+        .option("--cron <expression>", "Schedule; default every 15 minutes.")
+        .option("--timezone <iana>", "Schedule timezone; default UTC.")
+        .option("--max-records-per-list <n>", "Complete-snapshot cap (1-5000).", "5000")
+        .option("--max-credits <n>", "Hard credits cap per delivery.", "10")
+        .option("--reviewed-fingerprint <hash>", "Exact dry-run fingerprint, required for live.")
+        .option("--idempotency-key <key>", "Optional first-run idempotency key.")
+        .option("--live", "Arm the Workflow and queue the first durable run.")
+        .option("--approved", "Approve the reviewed bounded recurring reads and additive DNC writes.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions hubspot sync", options, () => {
+            const contactList = readOption(options.contactList);
+            const companyList = readOption(options.companyList);
+            if (!contactList && !companyList)
+                throw new Error("Pass --contact-list and/or --company-list.");
+            const maxRecords = readPositiveInt(options.maxRecordsPerList);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxRecords === undefined || maxRecords > 5000)
+                throw new Error("--max-records-per-list must be between 1 and 5000.");
+            if (maxCredits === undefined)
+                throw new Error("--max-credits must be positive.");
+            const fingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !fingerprint)
+                throw new Error("Live activation requires --reviewed-fingerprint from the exact dry-run.");
+            return requestOxygen("/api/cli/suppressions/hubspot-sync", {
+                method: "POST",
+                body: {
+                    contact_list_id: contactList ?? null,
+                    company_list_id: companyList ?? null,
+                    mode: options.live ? "live" : "dry_run",
+                    max_records_per_list: maxRecords,
+                    max_credits: maxCredits,
+                    ...(readOption(options.contactLinkedinProperty) ? { contact_linkedin_property: readOption(options.contactLinkedinProperty) } : {}),
+                    ...(readOption(options.companyDomainProperty) ? { company_domain_property: readOption(options.companyDomainProperty) } : {}),
+                    ...(readOption(options.companyLinkedinProperty) ? { company_linkedin_property: readOption(options.companyLinkedinProperty) } : {}),
+                    ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+                    ...(readOption(options.timezone) ? { timezone: readOption(options.timezone) } : {}),
+                    ...(fingerprint ? { reviewed_fingerprint: fingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(addSuppressionListFlags(new Command("domains")
+        .description("List the org's whole-domain email blocks, newest first. Filter by --reason (manual | complaint | policy) or --search (case-insensitive substring of the domain)."), "domains")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions domains", options, () => {
+            const suffix = suppressionListQuery(options, "domains");
+            return requestOxygen(`/api/cli/suppressions/domains${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(addSuppressionListFlags(new Command("addresses")
+        .description("List the org's blocked email ADDRESSES, newest first (bounces, unsubscribes, and `suppressions import` land here). Filter by --reason (hard_bounce | complaint | unsubscribe | manual) or --search (case-insensitive substring of the address). Rows carry a CRM person name when one matches."), "addresses")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("suppressions addresses", options, () => {
+            const suffix = suppressionListQuery(options, "addresses");
+            return requestOxygen(`/api/cli/suppressions/addresses${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("remove-domain")
+        .description("Remove one whole-domain email block or 1-500 with --domains immediately; this can restore sending eligibility. There is no preview or --approved flag: approve the exact domains before running. Requires workspace membership and subscription execution access; restricted client logins are denied.")
+        .argument("[domain]", "One bare domain to unblock; exclusive with --domains.")
+        .option("--domains <domains>", "Comma-separated domains to remove (1-500).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("suppressions remove-domain", options, () => {
+            const value = domain?.trim();
+            if (options.domains !== undefined) {
+                if (value)
+                    throw new OxygenError("invalid_request", "Pass one domain or --domains.", { exitCode: 2 });
+                return requestOxygen("/api/cli/suppressions/domains", { method: "DELETE", body: { domains: readSuppressionBulkKeys(options.domains, "--domains") } });
+            }
+            if (!value)
+                throw new Error("A domain is required.");
+            return requestOxygen(`/api/cli/suppressions/domains?domain=${encodeURIComponent(value)}`, {
+                method: "DELETE",
+            });
+        });
+    }))
+        .addCommand(new Command("remove-address")
+        .description("Remove one blocked email address or 1-500 with --emails immediately; this can restore sending eligibility. Whole-domain blocks use remove-domain. There is no preview or --approved flag: approve the exact addresses before running. Requires workspace membership and subscription execution access; restricted client logins are denied.")
+        .argument("[email]", "One blocked address, e.g. ada@acme.com; exclusive with --emails.")
+        .option("--emails <emails>", "Comma-separated exact email addresses to remove (1-500).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        const emails = options.emails;
+        if (emails !== undefined) {
+            await handleAsyncAction("suppressions remove-address", options, () => {
+                if (email)
+                    throw new OxygenError("invalid_request", "Pass one email or --emails.", { exitCode: 2 });
+                return requestOxygen("/api/cli/suppressions/addresses", { method: "DELETE", body: { emails: readSuppressionBulkKeys(emails, "--emails") } });
+            });
+            return;
+        }
+        try {
+            if (!email)
+                throw new OxygenError("invalid_request", "Pass one email or --emails.", { exitCode: 2 });
+            const data = await requestOxygen(`/api/cli/suppressions/addresses?email=${encodeURIComponent(email)}`, { method: "DELETE" });
+            if (options.json) {
+                writeJson(success("suppressions remove-address", data));
+                return;
+            }
+            const link = data.deepLink ?? data.web_url;
+            process.stdout.write(`${data.removed ? "Removed" : "Not found:"} ${data.email ?? email}.${link ? ` ${link}` : ""}\n`);
+        }
+        catch (error) {
+            emitCliFailure("suppressions remove-address", error);
+        }
+    })));
+}

package/dist/commands/table-ingestions.d.ts

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