@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/senders.js

@@ -0,0 +1,393 @@
+import { readPositiveInt } from "../cli-values.js";
+import { putAvatarBytesToStorage, splitCommaList } from "../command-support.js";
+import { addContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { buildSenderLimitsBody, SENDER_LIMITS_FLAG_OVERLAY } from "../sender-limits-flags.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { operationPath } from "@oxygen/shared/contracts/operations";
+import { SENDER_LIMITS_SET_OPERATION } from "@oxygen/shared/contracts/sender-limits";
+import { Command, Option } from "commander";
+export function registerSendersFamily(program, handleAsyncAction) {
+    program.addCommand(new Command("senders")
+        .description("Manage the org's connected LinkedIn sender accounts for Sequencer: list, connect, sync, get details, disconnect, and tune rate limits. This group is LinkedIn/WhatsApp accounts only; the cross-channel identity (one person's name and photo) that owns inboxes as well is `oxygen senders profiles`.")
+        .addCommand(new Command("list")
+        .description("List connected LinkedIn sender accounts with health status, rate limits, and today's usage. Disconnected accounts are hidden unless you pass --status disconnected.")
+        .option("--status <status>", "Filter by sender status: active, paused, disconnected, restricted, or credentials_required.")
+        .option("--no-usage", "Skip today's per-account usage counts for a faster, lighter response.")
+        .option("--tag <tags>", "Comma-separated workspace tags — matches sender accounts carrying ANY of these tags (see `oxygen tags list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders list", options, () => {
+            const params = new URLSearchParams();
+            // The server counts usage unless told not to, so --no-usage must say so.
+            params.set("include_usage", options.usage === false ? "false" : "true");
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const tags = splitCommaList(options.tag);
+            if (tags.length > 0)
+                params.set("tag", tags.join(","));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/senders${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("checkpoints")
+        .description("List LinkedIn senders stuck on a security checkpoint (2FA / OTP / in-app validation), each with status, warm-up day, today's usage vs. caps, and the latest error — plus a fleet tally of every sender by status. Read-only; no provider call, no credits. Solve one with `senders checkpoint solve <id> <code>`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders checkpoints", options, () => requestOxygen("/api/cli/senders/checkpoints"));
+    }))
+        .addCommand(new Command("connect")
+        .description("Get a hosted sign-in link to connect a new LinkedIn account (or reconnect with --reconnect). This command creates a pending provider authorization. Inspect prices first with `oxygen billing commitments --view connection-prices --json`, which creates no authorization. A covering dollar seat and a credit reservation are alternative billing rails. Read the seat coverage and actual commitment before relying on the next monthly billing date, especially on reconnect. Once the workspace is repriced that reservation is 3,400 credits ($34) monthly; with the credit gate active, a connect the balance cannot cover fails with insufficient_credits. Invites, messages and other LinkedIn actions cost 0 credits on top. `oxygen billing seats --json` shows held seats and next-connection eligibility; paying-seat coverage may remain unknown. Inspect `oxygen billing commitments --json` for an account’s actual reservation, and `oxygen billing estimate --linkedin-accounts <n> --json` prices n accounts against your plan. A workspace linked to another organization's plan is billed at that organization. New accounts require --country (the owner's normal LinkedIn login country) and default to syncing only conversations OXYGEN starts; use --inbox-scope all to opt into the full LinkedIn inbox. Use --cookie-auth and --custom-proxy to expose those inputs in the hosted sign-in wizard; their secrets never pass through OXYGEN. Use --count for bulk onboarding; --count above 1 needs --owner-consent (each owner connects their own account). Links are shareable and valid for 10 minutes.")
+        .option("--reconnect <connection_id>", "Reconnect an existing connection instead of creating a new one. Accepts a connection id.")
+        .option("--country <code>", "Required for new accounts: ISO 3166-1 alpha-2 code for the account owner's normal LinkedIn login country (for example DE or US); one of the 56 countries OXYGEN has LinkedIn proxies in.")
+        .option("--sales-nav", "Request Classic + Sales Navigator access during hosted sign-in.")
+        .option("--cookie-auth", "Offer LinkedIn cookie authentication in the hosted sign-in wizard. The account owner enters li_at/li_a there; OXYGEN never receives them.")
+        .option("--custom-proxy", "Let the account owner enter a custom proxy in the hosted sign-in wizard. OXYGEN never receives the proxy credentials.")
+        .option("--count <n>", "Mint N hosted-auth links in one call for bulk onboarding (1-25, default 1). Every link uses the same --country; use separate calls for different login countries. Ignored when reconnecting.")
+        .option("--share-link", "Return a shareable connection link for one account; its owner completes authentication.")
+        .option("--inbox-scope <scope>", "LinkedIn inbox privacy for new accounts: oxygen_initiated (default) or all. Reconnect preserves the existing account setting.")
+        .addOption(new Option("--acknowledge-risk", "Deprecated: connecting no longer needs it. Still accepted so older scripts keep running.").hideHelp())
+        .option("--owner-consent", "Required with --count above 1: each account owner connects their own account.")
+        .option("--established", "The account is an established profile: skip the ~2-week warm-up a new account gets by default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders connect", options, () => {
+            const reconnect = readOption(options.reconnect);
+            const country = readOption(options.country)?.toUpperCase();
+            const count = readPositiveInt(options.count);
+            const inboxScope = readOption(options.inboxScope);
+            return requestOxygen("/api/cli/senders/connect", {
+                method: "POST",
+                body: {
+                    ...(reconnect ? { reconnect_connection_id: reconnect } : {}),
+                    ...(country ? { country } : {}),
+                    ...(options.salesNav ? { sales_nav: true } : {}),
+                    ...(options.cookieAuth ? { cookie_auth: true } : {}),
+                    ...(options.customProxy ? { custom_proxy: true } : {}),
+                    ...(count ? { count } : {}),
+                    ...(options.shareLink ? { share_link: true } : {}),
+                    ...(inboxScope ? { inbox_sync_scope: inboxScope } : {}),
+                    ...(options.acknowledgeRisk ? { acknowledge_linkedin_risk: true } : {}),
+                    ...(options.ownerConsent ? { owner_consent: true } : {}),
+                    ...(options.established ? { established: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("inbox-scope")
+        .description("Inspect or change which LinkedIn conversations OXYGEN stores for one sender. Scope changes are internal and zero-credit: they do not sync LinkedIn or send a message.")
+        .addCommand(new Command("get")
+        .description("Show whether a sender syncs only OXYGEN-started conversations or its entire LinkedIn inbox.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders inbox-scope get", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/inbox-scope`));
+    }))
+        .addCommand(new Command("set")
+        .description("Set LinkedIn inbox privacy. oxygen_initiated hides and stops ingesting unrelated chats; all opts into the full inbox. This internal, zero-credit change does not trigger a provider sync or send a message. Existing stored messages are not deleted.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .requiredOption("--scope <scope>", "oxygen_initiated or all.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders inbox-scope set", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/inbox-scope`, {
+            method: "PATCH",
+            body: { scope: options.scope },
+        }));
+    })))
+        .addCommand(new Command("proxy-country")
+        .description("Move a LinkedIn sender's automatic proxy to another country without reconnecting. The account picks a proxy there at once when one is free; otherwise its sequences stay paused and each `senders sync` asks again. Zero credits.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .requiredOption("--country <code>", "ISO 3166-1 alpha-2 country where the account owner logs in; one of the 56 countries OXYGEN has LinkedIn proxies in (others are refused with the list).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders proxy-country", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/proxy-country`, {
+            method: "PATCH",
+            body: { country: options.country.trim().toUpperCase() },
+        }));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one LinkedIn sender account with status, limits, daily-reset timezone, and usage. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders get", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}`));
+    }))
+        .addCommand(new Command("tag")
+        .description("Replace a sender account's workspace tags (whole set; `--tags \"\"` clears) — e.g. pool the senders behind one campaign tag. See `oxygen tags list` for the vocabulary.")
+        .argument("<id>", "Sender account id or Unipile account id.")
+        .requiredOption("--tags <tags>", "Comma-separated workspace tags (replaces the whole set; empty clears).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders tag", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/tags`, {
+            method: "POST",
+            body: { tags: splitCommaList(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("health")
+        .description("Show a one-call health snapshot for a LinkedIn sender: status, the latest error reason, any open security checkpoint, today's usage, the warm-up ramp, when the daily quota resets, and inbox sync (last sync, latest failure, back-off). Read-only — no provider call, no credits. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders health", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/health`));
+    }))
+        .addCommand(new Command("inmail-balance")
+        .description("Show remaining LinkedIn InMail credits for a sender (Premium / Sales Navigator / Recruiter each hold a separate pool). Run before enrolling an `inmail` sequencer step so a campaign does not stall on an account with zero credits. Read-only — not billed. <id> defaults to the org's primary sender.")
+        .argument("[id]", "Sender account id, connection id, or Unipile account id. Defaults to the org's primary sender.")
+        .option("--service <service>", "Narrow to one credit pool: classic | sales_navigator | recruiter. Defaults to every subscribed service.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders inmail-balance", options, () => {
+            const query = new URLSearchParams();
+            if (id)
+                query.set("account", id);
+            const service = readOption(options.service);
+            if (service)
+                query.set("service", service);
+            const suffix = query.toString();
+            return requestOxygen(`/api/cli/linkedin/inmail-balance${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("sync")
+        .description("Refresh LinkedIn account state (status, profile) from Unipile. Pass --connection-id to sync one account, or omit it to sync all.")
+        .option("--connection-id <id>", "Sync a specific connection id. Defaults to syncing all connected accounts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders sync", options, () => {
+            const connectionId = readOption(options.connectionId);
+            return requestOxygen("/api/cli/senders/sync", {
+                method: "POST",
+                body: {
+                    ...(connectionId ? { connection_id: connectionId } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("disconnect")
+        .description("Disconnect a LinkedIn sender account so it stops sending. Works on an account that is already disconnected. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders disconnect", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/disconnect`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("checkpoint")
+        .description("Resolve a LinkedIn security checkpoint (2FA / OTP / in-app validation) so a stuck sender can return to active. Account administration — no credits, no approval gate.")
+        .option("--json", "Print a JSON envelope.")
+        .addCommand(new Command("solve")
+        .description("Submit the LinkedIn checkpoint code Unipile is waiting on to finish authentication. <id> accepts a sender account id, connection id, or Unipile account id; <code> is the verification code LinkedIn sent.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .argument("<code>", "The verification code LinkedIn sent (2FA / OTP / in-app validation).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, code, options) => {
+        await handleAsyncAction("senders checkpoint solve", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/checkpoint/solve`, {
+            method: "POST",
+            body: { code },
+        }));
+    }))
+        .addCommand(new Command("resend")
+        .description("Ask LinkedIn to resend the checkpoint code so you can read a fresh one, then submit it with `senders checkpoint solve`. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders checkpoint resend", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/checkpoint/resend`, {
+            method: "POST",
+        }));
+    })))
+        .addCommand(new Command("limits")
+        .description("View and adjust per-account daily action limits, working hours (the times LinkedIn actions may run) and the timezone they use.")
+        .option("--json", "Print a JSON envelope.")
+        .addCommand(new Command("get")
+        .description("Show current limits, overrides, working hours (timezone, days, start, end), defaults, hard maximums, and the caution levels above which LinkedIn restriction risk rises, for an account. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .argument("<id>", "Sender account id, connection id, or Unipile account id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders limits get", options, () => requestOxygen(`/api/cli/senders/${encodeURIComponent(id)}/limits`));
+    }))
+        .addCommand(addContractFlags(new Command(SENDER_LIMITS_SET_OPERATION.cli.path.at(-1) ?? "set")
+        .description(SENDER_LIMITS_SET_OPERATION.cli.summary)
+        .argument("<id>", SENDER_LIMITS_SET_OPERATION.cli.argument?.description), SENDER_LIMITS_SET_OPERATION.contract, SENDER_LIMITS_FLAG_OVERLAY)
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders limits set", options, () => {
+            const body = buildSenderLimitsBody(options);
+            return requestOxygen(operationPath(SENDER_LIMITS_SET_OPERATION, { id }), {
+                method: SENDER_LIMITS_SET_OPERATION.method,
+                body,
+            });
+        });
+    })))
+        .addCommand(new Command("profiles")
+        .description("Sender profiles: group a person's LinkedIn + WhatsApp senders and email inboxes into one sending identity — one name, one first/last name, one photo. A sequence can then send every channel from the same persona, and `oxygen managed-inboxes subscribe/add-inboxes --sender <id>` orders new mailboxes under that identity instead of making you retype it per mailbox. Every email inbox always belongs to one of these profiles, so attaching moves an inbox and detaching one is refused. Manage: list, get, create, update, set-photo, attach/detach accounts, delete.")
+        .addCommand(new Command("list")
+        .description("List sender profiles with their per-channel account counts (LinkedIn / WhatsApp / inboxes).")
+        .option("--status <status>", "Filter by status: active, paused, or archived.")
+        .option("--tag <tags>", "Comma-separated workspace tags — matches sender profiles carrying ANY of these tags (see `oxygen tags list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders profiles list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const tags = splitCommaList(options.tag);
+            if (tags.length > 0)
+                params.set("tag", tags.join(","));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/senders/profiles${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("tag")
+        .description("Replace a sender profile's workspace tags (whole set; `--tags \"\"` clears) — one edit pools the whole sending identity behind a campaign tag. Member accounts keep their own tags. See `oxygen tags list` for the vocabulary.")
+        .argument("<id>", "Sender profile id.")
+        .requiredOption("--tags <tags>", "Comma-separated workspace tags (replaces the whole set; empty clears).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles tag", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}/tags`, {
+            method: "POST",
+            body: { tags: splitCommaList(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one sender profile with the LinkedIn/WhatsApp senders and inboxes attached to it.")
+        .argument("<id>", "Sender profile id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles get", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a sender profile: one person's sending identity — their LinkedIn/WhatsApp senders and email inboxes under one name and photo. --from-linkedin seeds the name + avatar from a LinkedIn account and attaches it; then assign inboxes and WhatsApp with --mailboxes / --senders. Without --from-linkedin, --name is required. Give the profile --first-name and --last-name too: those are the exact names the inbox vendor stamps when you order mailboxes with `oxygen managed-inboxes subscribe --sender <id>`, and the vendor has no way to change a name after provisioning. Attaching a LinkedIn sender (--from-linkedin or --senders) gives the profile that account's LinkedIn photo, mirrored into Oxygen storage, unless you pass --avatar-url; a photo you upload later with set-photo --file always wins over the LinkedIn one.")
+        .option("--name <name>", "Display name for the profile. Optional when --from-linkedin is given (derived from the LinkedIn account).")
+        .option("--first-name <name>", "The person's first name, as it should appear on mailboxes ordered for this sender. Defaults to splitting --name / the LinkedIn name on the first space.")
+        .option("--last-name <name>", "The person's last name, as it should appear on mailboxes ordered for this sender. Ordering managed inboxes for this sender needs both names; a one-word name leaves it blank and the order is refused rather than guessed.")
+        .option("--from-linkedin <senderId>", "Seed the profile from this LinkedIn/WhatsApp sender account id: derives the name and MIRRORS the LinkedIn photo into Oxygen storage (LinkedIn's own URL expires, so a mirrored copy is what an inbox vendor can still fetch hours later) and attaches the account.")
+        .option("--avatar-from-linkedin", "Use the attached LinkedIn account's mirrored photo for this new profile.")
+        .option("--avatar-upload-key <key>", "Use the storage_key returned by managed-inboxes upload-avatar; verified server-side.")
+        .option("--avatar-url <url>", "Use this image URL as the profile photo instead of the LinkedIn one. Must be a public https URL. An expiring link (e.g. media.licdn.com with e=<epoch>) is stored but marked non-durable and is NOT sent to an inbox vendor — use `set-photo --file` to host a permanent copy.")
+        .option("--status <status>", "Initial status: active (default), paused, or archived.")
+        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach. A LinkedIn sender also supplies the profile's photo when it has none of its own.")
+        .option("--mailboxes <ids>", "Comma-separated email mailbox ids to attach.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("senders profiles create", options, () => requestOxygen("/api/cli/senders/profiles", {
+            method: "POST",
+            body: {
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.firstName) ? { first_name: readOption(options.firstName) } : {}),
+                ...(readOption(options.lastName) ? { last_name: readOption(options.lastName) } : {}),
+                ...(readOption(options.fromLinkedin) ? { from_sender_account_id: readOption(options.fromLinkedin) } : {}),
+                ...(options.avatarFromLinkedin ? { avatar_from_linkedin: true } : {}),
+                ...(readOption(options.avatarUploadKey) ? { avatar_upload_key: readOption(options.avatarUploadKey) } : {}),
+                ...(readOption(options.avatarUrl) ? { avatar_url: readOption(options.avatarUrl) } : {}),
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+                ...(options.senders ? { sender_account_ids: splitCommaList(options.senders) } : {}),
+                ...(options.mailboxes ? { mailbox_ids: splitCommaList(options.mailboxes) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("update")
+        .description("Update a sender profile's own fields (display name, first/last name, avatar, status). Use `attach`/`detach` to change its accounts, and `set-photo` for the full photo menu (upload a file, mirror LinkedIn again, or clear).")
+        .argument("<id>", "Sender profile id.")
+        .option("--name <name>", "New display name.")
+        .option("--first-name <name>", "New first name — the exact one an inbox vendor stamps on mailboxes ordered for this sender.")
+        .option("--last-name <name>", "New last name — the exact one an inbox vendor stamps on mailboxes ordered for this sender. Fix it BEFORE ordering: the vendor cannot rename a mailbox afterwards.")
+        .option("--avatar-url <url>", "New avatar image URL (empty string clears it). Must be a public https URL; an expiring link is stored but marked non-durable and is NOT sent to an inbox vendor.")
+        .option("--status <status>", "New status: active, paused, or archived.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles update", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: {
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.firstName) ? { first_name: readOption(options.firstName) } : {}),
+                ...(readOption(options.lastName) ? { last_name: readOption(options.lastName) } : {}),
+                ...(options.avatarUrl !== undefined ? { avatar_url: readOption(options.avatarUrl) ?? "" } : {}),
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("set-photo")
+        .description("Set the reusable sender identity's profile picture for FUTURE managed-inbox orders made with --sender <id>. Pick exactly one source: --file (upload your own image; Oxygen hosts it permanently), --url (a public https image), --from-linkedin (re-mirror the photo from the attached LinkedIn account), or --clear. Hosting matters: an inbox vendor fetches the photo HOURS after an order, so an expiring LinkedIn CDN URL can ship the mailbox faceless. This updates Oxygen's sender profile only: it does not change already-provisioned mailbox photos or call the inbox provider. For a one-off typed-name order using profile_picture_url in --mailboxes JSON, use `oxygen managed-inboxes upload-avatar <path>` instead. Precedence: a photo you upload (--file) or set with --url is yours and is never overwritten by Oxygen; a sender with a LinkedIn account attached and no photo of its own gets that LinkedIn photo automatically (existing senders are backfilled), so --clear on such a sender is temporary — upload your own photo to override LinkedIn's. If LinkedIn's CDN refuses the stored picture, Oxygen re-syncs the account and retries once; read back avatar_durable, where false means only an expiring link could be kept. Free — no credits.")
+        .argument("<id>", "Sender profile id (from `oxygen senders profiles list`).")
+        .option("--file <path>", "Upload a PNG, JPEG, or WebP from disk (max 8MB) and use it. Oxygen hosts the image permanently, so an inbox vendor can still fetch it at provisioning time.")
+        .option("--url <url>", "Use an image already published at a public https URL. If the link expires (e.g. media.licdn.com with e=<epoch>) the photo is kept for Oxygen's own UI but marked non-durable and NEVER sent to an inbox vendor.")
+        .option("--from-linkedin", "Re-mirror the photo from this profile's attached LinkedIn account into Oxygen storage. Use it when the person changed their LinkedIn picture. If the CDN refuses the stored picture, the account is re-synced and the mirror retried once; when it still fails, the expiring link is kept, avatar_durable reads false, and the worker retries later.")
+        .option("--clear", "Remove the photo. Mailboxes ordered afterwards ship without one. On a sender with a LinkedIn account attached this is temporary — the LinkedIn photo is adopted again on the next sync; upload your own photo to override it instead.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles set-photo", options, async () => {
+            const filePath = readOption(options.file);
+            const url = readOption(options.url);
+            const chosen = [
+                filePath ? "--file" : null,
+                url ? "--url" : null,
+                options.fromLinkedin ? "--from-linkedin" : null,
+                options.clear ? "--clear" : null,
+            ].filter((flag) => flag !== null);
+            // Refuse locally rather than letting the server pick a winner: the
+            // photo is what an inbox vendor stamps permanently, so "which source
+            // won" is never a question a caller should have to reverse-engineer
+            // from the response.
+            if (chosen.length === 0) {
+                throw new OxygenError("invalid_request", "Pass one photo source: --file <path>, --url <https url>, --from-linkedin, or --clear.", { exitCode: 2 });
+            }
+            if (chosen.length > 1) {
+                throw new OxygenError("conflicting_flags", `Pass exactly one photo source, not ${chosen.join(" + ")}.`, { exitCode: 2 });
+            }
+            // --file stages the bytes first, then finishes on the profile write
+            // like every other source: one response, carrying the profile and its
+            // deep-link, instead of leaving the caller holding a storage key and
+            // an unfinished profile.
+            const body = filePath
+                ? { avatar_upload_key: await putAvatarBytesToStorage(filePath) }
+                : url
+                    ? { avatar_url: url }
+                    : options.fromLinkedin
+                        ? { avatar_from_linkedin: true }
+                        : { avatar_url: "" };
+            return await requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`, {
+                method: "PATCH",
+                body,
+            });
+        });
+    }))
+        .addCommand(new Command("attach")
+        .description("Attach senders and/or inboxes to a profile. An account belongs to one profile at a time — attaching moves it. Attaching a LinkedIn sender to a profile without a photo of its own gives it that account's LinkedIn photo (mirrored into Oxygen storage); an uploaded or URL-set photo is never replaced. Read back has_photo and avatar_durable in the result.")
+        .argument("<id>", "Sender profile id.")
+        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach. A LinkedIn sender also supplies the profile's photo when it has none of its own.")
+        .option("--mailboxes <ids>", "Comma-separated email mailbox ids to attach.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles attach", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: {
+                ...(options.senders ? { sender_account_ids: splitCommaList(options.senders) } : {}),
+                ...(options.mailboxes ? { mailbox_ids: splitCommaList(options.mailboxes) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("detach")
+        .description("Detach LinkedIn/WhatsApp senders from a profile, returning them to the unassigned pool. --mailboxes is refused: an email inbox always belongs to a sender, so there is no unassigned pool for it — move it with `senders profiles attach <other-profile> --mailboxes <id>`, which reassigns it.")
+        .argument("<id>", "Sender profile id.")
+        .option("--senders <ids>", "Comma-separated sender account ids to detach.")
+        .option("--mailboxes <ids>", "Comma-separated email mailbox ids to detach.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles detach", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`, {
+            method: "PATCH",
+            body: {
+                ...(options.senders ? { detach_sender_account_ids: splitCommaList(options.senders) } : {}),
+                ...(options.mailboxes ? { detach_mailbox_ids: splitCommaList(options.mailboxes) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete a sender profile. Refused while the profile still owns inboxes — move them to another profile first; LinkedIn/WhatsApp accounts detach (return to the pool) and are never deleted.")
+        .argument("<id>", "Sender profile id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("senders profiles delete", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`, { method: "DELETE" }));
+    }))));
+}

package/dist/commands/sequences.d.ts

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