@oxygen-agent/cli 1.1014.1696 → 1.1014.1763

package/dist/commands/sequences.js

@@ -3,7 +3,12 @@ import { parseJsonObject, readNonNegativeInt, readPositiveInt } from "../cli-val
 import { ansi, collectRepeatable, handleReadActionWithLens, parseJsonValue, readCreditCeilingOrZero, readCsvOption, readJsonFileValue, readPositiveNumber, readPublishingPostText, renderTextTable, splitCommaList } from "../command-support.js";
 import { addContractFlags, readContractFlags } from "../contract-flags.js";
 import { requestOxygen } from "../http-client.js";
+import { sequencesBrandKitCommand } from "../sequences-brand-kit-command.js";
+import { sequencesContentCommand } from "../sequences-content-commands.js";
+import { formatNewsletterStatsLines, readNewsletterIntervalFlag, sequencesRecipientsCommand } from "../sequences-newsletter-commands.js";
+import { sequencesTestSendCommand } from "../sequences-test-send-command.js";
 import { networkMiningHostServed } from "../network-mining-host.js";
+import { parseStartAtFlag } from "../sequence-start-at.js";
 import { parseWorkingDaysOption } from "../sender-limits-flags.js";
 import { isRecord, readOption } from "../util.js";
 import { OxygenError, success } from "@oxygen/shared/cli-result";
@@ -576,6 +581,10 @@ function formatSequenceChannelFunnels(funnels, replies) {
     const channels = ["linkedin", "email", "whatsapp"].filter((channel) => isRecord(byChannel[channel]));
     if (channels.length === 0)
         return [];
+    // OXYGEN offers no open tracking, so on such a deployment every channel's
+    // opens are not_supported and the column would read n/a on every row (Tim,
+    // 2026-10-22: hide it). It stays while any channel can report opens.
+    const showOpened = channels.some((channel) => stringValue(recordValue(recordValue(recordValue(byChannel[channel]).coverage).opened).state) !== "not_supported");
     const rows = channels.map((channel) => {
         const funnel = recordValue(byChannel[channel]);
         const invites = recordValue(funnel.invites);
@@ -585,13 +594,13 @@ function formatSequenceChannelFunnels(funnels, replies) {
             numberText(funnel.sends),
             numericValue(invites.sent) === null ? "n/a" : `${numberText(invites.accepted)}/${numberText(invites.sent)}`,
             funnelMetricText(funnel, "delivered"),
-            funnelMetricText(funnel, "opened"),
+            ...(showOpened ? [funnelMetricText(funnel, "opened")] : []),
             funnelMetricText(funnel, "replied"),
             funnelRateText(funnel, "replyRate", "replied"),
             funnelMetricText(funnel, "positiveReplied"),
         ];
     });
-    const lines = ["", ...renderTextTable(["CHANNEL", "PEOPLE", "SENDS", "ACCEPTED", "DELIVERED", "OPENED", "REPLIED", "REPLY RATE", "POSITIVE"], rows)];
+    const lines = ["", ...renderTextTable(["CHANNEL", "PEOPLE", "SENDS", "ACCEPTED", "DELIVERED", ...(showOpened ? ["OPENED"] : []), "REPLIED", "REPLY RATE", "POSITIVE"], rows)];
     // Name the remedy once per distinct gap rather than once per row.
     const remedies = new Map();
     for (const channel of channels) {
@@ -688,6 +697,7 @@ function formatSequenceStatsHealth(data) {
             ["Replies", numberText(stats.totalReplies ?? stats.replied)],
         ]));
     }
+    lines.push(...formatNewsletterStatsLines(data.newsletter));
     const link = stringValue(data.web_url) ?? stringValue(data.deepLink);
     if (link)
         lines.push("", link);
@@ -760,7 +770,12 @@ function operationalStateText(sequence, operational) {
     if (!state)
         return null;
     // The server's own `lifecycle`; the shared helper covers a server that predates it.
-    const lifecycle = stringValue(sequence.lifecycle) ?? sequenceDisplayStatus(stringValue(sequence.status) ?? "", state);
+    const settings = isRecord(sequence.settings) ? sequence.settings : null;
+    const lifecycle = stringValue(sequence.lifecycle) ?? sequenceDisplayStatus(stringValue(sequence.status) ?? "", state, settings);
+    if (lifecycle === "scheduled") {
+        const startAt = stringValue(settings?.start_at);
+        return `${state} (scheduled${startAt ? ` for ${startAt}` : ""})`;
+    }
     return lifecycle === "completed" ? `${state} (completed)` : state;
 }
 /** A listed Sequence's launch warnings (e.g. two sending schedules), one line each. */
@@ -1342,7 +1357,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .description("List sequences with persisted launch status kept separate from current operational state. Fleet counts report marked-active versus operationally-live (active with nonterminal work), and rows explain flowing, paced, paused, blocked, degraded, drained, or empty work without SQL. An active sequence whose every lead has finished shows drained (completed); leads enrolled into it later are contacted on its next dispatch tick. --stats joins each row's LIFETIME funnel.")
         .option("--status <status>", "Filter by status: draft, active, paused, or archived.")
         .addOption(new Option("--operational-state <state>", "Filter by current work state; fleet counts remain unfiltered: empty, drained, never_started (enrolled leads, never launched), blocked, degraded, flowing, paced, or paused (work waiting on a paused sequence).").choices(["empty", "drained", "never_started", "blocked", "degraded", "flowing", "paced", "paused"]))
-        .addOption(new Option("--lifecycle <lifecycle>", "Filter by the lifecycle a person reads; fleet counts remain unfiltered: draft, active, completed (active, every lead finished), paused, or archived.").choices([...SEQUENCE_LIFECYCLES]))
+        .addOption(new Option("--lifecycle <lifecycle>", "Filter by the lifecycle a person reads; fleet counts remain unfiltered: draft, scheduled (active, start_at still ahead), active, completed (active, every lead finished), paused, or archived.").choices([...SEQUENCE_LIFECYCLES]))
         .addOption(new Option("--channel <channel>", "Only sequences carrying this channel.").choices(["email", "linkedin", "whatsapp"]))
         .option("--tag <tag>", "Only sequences carrying this workspace tag (see `oxygen tags list`).")
         .option("--stats", "Attach lifetime stats per sequence (a stats pass per row — slower on large workspaces)."), SEQUENCE_LIST_PROJECTION_CONTRACT)
@@ -1672,8 +1687,8 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .option("--bounce-protection <json>", "Sequence bounce policy JSON (partial updates merge): enabled=true, warning_rate=.02, pause_rate=.03, min_sends=20, window_days=7. Hard bounces / accepted sends in the rolling window; pauses this sequence, not the fleet. Rates are fractions; mailbox protection is separate.")
         .option("--auto-optimize", "Enable the sequence-wide A/B auto-winner (default on).")
         .option("--no-auto-optimize", "Disable the sequence-wide A/B auto-winner; manual variant decisions stay available.")
-        .option("--reply-to-stop-text <text>", "Optional first-touch email footer (max 500 characters); empty clears.")
-        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as the Sending settings switch: a visible recipient-bound link (plain text shows the URL, HTML a linked Unsubscribe label) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. Use --reply-to-stop-text for an optional first-touch email footer. `sequences update` can switch on the link or the headers alone.")
+        .option("--reply-to-stop-text <text>", "Optional first-touch email footer (max 500 characters); with the unsubscribe option on, plain-text emails show it in place of the link. Empty clears.")
+        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as the Sending settings switch: a visible opt-out (HTML a linked Unsubscribe label; plain text the --reply-to-stop-text line, else a default opt-out line, never the URL) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. Use --reply-to-stop-text for an optional first-touch email footer. `sequences update` can switch on the link or the headers alone.")
         .option("--no-include-unsubscribe", "Turn off both the visible unsubscribe link and the one-click headers.")
         .option("--tracking-opens", "Opt in to open tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
         .option("--no-tracking-opens", "Turn OFF the open pixel for this sequence's native email sends (a deliverability knob — a pixel is spam-filter surface).")
@@ -1822,12 +1837,12 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .option("--bounce-protection <json>", "Sequence bounce policy JSON (partial updates merge): enabled=true, warning_rate=.02, pause_rate=.03, min_sends=20, window_days=7. Hard bounces / accepted sends in the rolling window; pauses this sequence, not the fleet. Rates are fractions; mailbox protection is separate.")
         .option("--auto-optimize", "Turn the A/B auto-winner on (the default): every step with variants is judged on replies, pausing losers once each variant has 100 sends and 5 replies, unless the step sets its own auto_optimize.")
         .option("--no-auto-optimize", "Disable the sequence-wide A/B auto-winner; manual variant decisions stay available.")
-        .option("--reply-to-stop-text <text>", "Optional first-touch email footer (max 500 characters); empty clears.")
-        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as the Sending settings switch: a visible recipient-bound link (plain text shows the URL, HTML a linked Unsubscribe label) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. Use --reply-to-stop-text for an optional first-touch email footer.")
+        .option("--reply-to-stop-text <text>", "Optional first-touch email footer (max 500 characters); with the unsubscribe option on, plain-text emails show it in place of the link. Empty clears.")
+        .option("--include-unsubscribe", "Add an unsubscribe option to emails, the same as the Sending settings switch: a visible opt-out (HTML a linked Unsubscribe label; plain text the --reply-to-stop-text line, else a default opt-out line, never the URL) plus one-click headers that mail apps show as an Unsubscribe button, both on first-touch cold emails; in-thread follow-ups carry neither. Zapbox sends (mailboxes imported from Zapmail, `transport: \"zapbox\"` in `mailboxes list --json`) carry the link only. Off by default. Use --reply-to-stop-text for an optional first-touch email footer.")
         .option("--no-include-unsubscribe", "Turn off both the visible unsubscribe link and the one-click headers.")
         .option("--include-unsubscribe-headers", "Only the one-click unsubscribe headers (default off); --include-unsubscribe turns on the headers and the visible link together.")
         .option("--no-include-unsubscribe-headers", "Omit one-click headers.")
-        .option("--include-unsubscribe-link", "Only the visible recipient-bound unsubscribe footer on first-touch cold emails (default off; --include-unsubscribe adds the one-click headers too). Plain-text messages show the URL, while HTML messages show a linked Unsubscribe label.")
+        .option("--include-unsubscribe-link", "Only the visible recipient-bound unsubscribe footer on first-touch cold emails (default off; --include-unsubscribe adds the one-click headers too). HTML messages show a linked Unsubscribe label; plain-text messages show the --reply-to-stop-text line, else a default opt-out line, instead of the URL.")
         .option("--no-include-unsubscribe-link", "Turn the visible unsubscribe footer OFF. Future first-touch emails send the authored body unchanged; existing suppression records remain enforced.")
         .option("--tracking-opens", "Opt in to open tracking (default off). Requires a verified tracking domain and deployment tracking secret.")
         .option("--no-tracking-opens", "Turn OFF the open pixel for this sequence's native email sends (a deliverability knob — a pixel is spam-filter surface).")
@@ -2038,6 +2053,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .option("--max-live-sends <n>", "Total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). Required for email, WhatsApp, or crm_task steps; guided LinkedIn binds its positive cap in launch_review.")
         .option("--launch-review-json <json>", "Guided onboarding: echo the exact preview.launch_review (digest, expiry, positive action ceiling and nonnegative credit cap). Changed inputs require a new preview.")
         .option("--launch-review-file <path>", "Read the exact launch_review object from a JSON file instead of --launch-review-json.")
+        .option("--at <time>", "Schedule a draft's start: an ISO timestamp with a timezone (2026-11-02T09:00:00Z) or \"in 30m\" / \"in 2h\" / \"in 3d\", at most 30 days ahead. With --approved it activates now and sends nothing before then (lifecycle scheduled); cancel with `sequences unschedule`.")
         .option("--dry-run", "Activate the sequence (status draft → active, startedAt set) in dry-run mode: every step advances with simulated actions — no sends, CRM writes, provider calls, or credits. This is NOT the preview: `sequences start` with no flags is the side-effect-free launch preview. A later live start (--approved) restarts those leads from the first step so they are contacted for real, except deleted source rows, a person another live campaign contacts under exclude_contacted, and older duplicates of a person.")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
@@ -2051,6 +2067,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
                 : options.launchReviewJson !== undefined ? parseJsonObject(options.launchReviewJson) : undefined;
             if (launchReview !== undefined && !isRecord(launchReview))
                 throw new OxygenError("invalid_request", "The launch review must be the exact object returned by the preview.", { exitCode: 2 });
+            const startAt = options.at === undefined ? undefined : parseStartAtFlag(options.at);
             return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/start`, {
                 method: "POST",
                 body: {
@@ -2059,6 +2076,7 @@ export function registerSequencesFamily(program, handleAsyncAction) {
                     ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
                     ...(maxLiveSends !== undefined ? { max_live_sends: maxLiveSends } : {}),
                     ...(launchReview !== undefined ? { launch_review: launchReview } : {}),
+                    ...(startAt !== undefined ? { start_at: startAt } : {}),
                 },
             });
         });
@@ -2147,6 +2165,15 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         await handleAsyncAction("sequences pause", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/status`, {
             method: "POST", body: { status: "paused" },
         }));
+    }))
+        .addCommand(new Command("unschedule")
+        .description("Cancel a scheduled start (`sequences start --at`) before it comes: the Sequence returns to draft, its leads to pending, and the start time is cleared. Refused once the start has come or anything was planned; pause it then. Repeating it changes nothing.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences unschedule", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/unschedule`, {
+            method: "POST", body: {},
+        }));
     }))
         .addCommand(new Command("resume")
         .description("Resume a paused sequence. A campaign paused at its live send cap pauses again at once: raise the cap and resume in one step with `sequences start <sequence> --max-live-sends <n>` (preview, then --approved).")
@@ -2440,12 +2467,17 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         });
     }))
         .addCommand(new Command("stats")
-        .description("Show one sequence's persisted launch status and current operational state separately, including reasons, open work, lifetime sent/terminal-failed/deferral counts, and the funnel. Today's completed sends, reservations and remaining capacity appear in the default output and daily_budget. operational.reasons carries why work is waiting (outside_send_window, mailbox_spacing, daily_send_cap_reached, ...). For a per-day send series use `sequences analytics --sequence <id> --range <window>`.")
+        .description("Show one sequence's persisted launch status and current operational state separately, including reasons, open work, lifetime sent/terminal-failed/deferral counts, and the funnel. Today's completed sends, reservations and remaining capacity appear in the default output and daily_budget. operational.reasons carries why work is waiting (outside_send_window, mailbox_spacing, daily_send_cap_reached, ...). For a per-day send series use `sequences analytics --sequence <id> --range <window>`. A newsletter (sending-domain Sequence) adds a newsletter block: delivered, estimated opens, clicks per link, bounces, complaints, unsubscribes and a first-week timeline; per-recipient status is `sequences recipients`.")
         .argument("<sequence>", "Sequence id or slug.")
+        .option("--interval <hour|day>", "Newsletter timeline buckets over the first 7 days (default day).")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
-        await handleReadActionWithLens("sequences stats", options, () => requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/stats`), formatSequenceStatsHealth);
+        await handleReadActionWithLens("sequences stats", options, () => {
+            const interval = readNewsletterIntervalFlag(options.interval);
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/stats${interval ? `?interval=${interval}` : ""}`);
+        }, formatSequenceStatsHealth);
     }))
+        .addCommand(sequencesRecipientsCommand())
         .addCommand(new Command("esp")
         .description("ESP breakdown of this sequence's email sending scope: which provider each enrolled lead's mail routes through (google/microsoft, plus named gateways like Proofpoint/Mimecast and non-matchable hosts), folded against your sending mailbox pool. Shows how many leads the CURRENT --esp-matching mode would defer before you turn it on. Resolves domains from MX + SPF (0 credits, DNS only) and caches the result, warming the send path. Preview before flipping strict/prefer.")
         .argument("<sequence>", "Sequence id or slug.")
@@ -2480,5 +2512,8 @@ export function registerSequencesFamily(program, handleAsyncAction) {
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleSequenceVariantsAction(sequence, options);
-    })));
+    }))
+        .addCommand(sequencesContentCommand(handleAsyncAction))
+        .addCommand(sequencesBrandKitCommand(handleAsyncAction))
+        .addCommand(sequencesTestSendCommand(handleAsyncAction)));
 }

package/dist/commands/subscriptions.d.ts

@@ -1,9 +1,7 @@
 import { ExtractedCommandActionHandler } from "../command-support.js";
+import { type EmailContactImportRow } from "@oxygen/shared/email-subscriptions";
 import { Command } from "commander";
-type ImportEntry = {
-    email: string;
-    person_id?: string;
-};
+type ImportEntry = EmailContactImportRow;
 /** Read --file as JSON (by extension or content) or as CSV with an email column. */
 export declare function readSubscriptionImportFile(path: string): ImportEntry[];
 export declare function registerSubscriptionsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/subscriptions.js

@@ -1,9 +1,16 @@
 import { requestOxygen } from "../http-client.js";
 import { isRecord, readOption } from "../util.js";
 import { OxygenError } from "@oxygen/shared/cli-result";
+import { EmailSubscriptionInputError, chunkContactImport, keepContactProperties, parseContactsCsv, } from "@oxygen/shared/email-subscriptions";
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+/** --description / --parent on update: absent leaves it, "" clears it (null). */
+function clearableOption(value) {
+    if (value === undefined)
+        return {};
+    return { value: readOption(value) ?? null };
+}
 function evidenceBody(options) {
     const noticeVersion = readOption(options.noticeVersion);
     const noticeTextHash = readOption(options.noticeTextHash);
@@ -25,48 +32,25 @@ function requireSubscribeEvidence(options, status) {
         throw new OxygenError("consent_evidence_required", "Subscribing needs consent evidence: --notice-version with --notice-text-hash, or --basis naming where consent came from.", { details: { field: "evidence" }, exitCode: 2 });
     }
 }
-/** Split one CSV line, honouring double-quoted fields with "" escapes. */
-function splitCsvLine(line) {
-    const cells = [];
-    let cell = "";
-    let quoted = false;
-    for (let index = 0; index < line.length; index += 1) {
-        const char = line[index];
-        if (quoted) {
-            if (char === "\"" && line[index + 1] === "\"") {
-                cell += "\"";
-                index += 1;
-            }
-            else if (char === "\"")
-                quoted = false;
-            else
-                cell += char;
-        }
-        else if (char === "\"")
-            quoted = true;
-        else if (char === ",") {
-            cells.push(cell.trim());
-            cell = "";
-        }
-        else
-            cell += char;
-    }
-    cells.push(cell.trim());
-    return cells;
-}
 function csvEntries(text) {
-    const lines = text.replace(/^/, "").split(/\r?\n/).filter((line) => line.trim());
-    const header = splitCsvLine(lines[0] ?? "").map((cell) => cell.toLowerCase());
-    const emailIndex = header.findIndex((cell) => cell === "email" || cell === "email_address" || cell === "e-mail");
-    if (emailIndex < 0) {
-        throw new OxygenError("invalid_request", "The CSV needs an email column in its header row.", { exitCode: 2 });
+    try {
+        return parseContactsCsv(text).entries;
     }
-    const personIndex = header.findIndex((cell) => cell === "person_id");
-    return lines.slice(1).map((line) => {
-        const cells = splitCsvLine(line);
-        const personId = personIndex >= 0 ? cells[personIndex] : undefined;
-        return { email: cells[emailIndex] ?? "", ...(personId ? { person_id: personId } : {}) };
-    });
+    catch (error) {
+        if (error instanceof EmailSubscriptionInputError)
+            throw new OxygenError("invalid_request", error.message, { details: { field: error.field }, exitCode: 2 });
+        throw error;
+    }
+}
+/**
+ * Keep only the columns that are contact properties of this workspace, so a
+ * stray column (a CRM export's "company", an index) is reported, not refused.
+ */
+async function keepKnownProperties(entries) {
+    if (!entries.some((entry) => entry.properties && Object.keys(entry.properties).length > 0))
+        return { entries, ignored: [] };
+    const known = await requestOxygen("/api/cli/subscriptions/properties");
+    return keepContactProperties(entries, new Set((known.properties ?? []).map((property) => property.key)));
 }
 function jsonEntries(value) {
     const list = Array.isArray(value) ? value : isRecord(value) && Array.isArray(value.entries) ? value.entries : null;
@@ -77,7 +61,16 @@ function jsonEntries(value) {
         if (typeof entry === "string")
             return { email: entry };
         if (isRecord(entry) && typeof entry.email === "string") {
-            return { email: entry.email, ...(typeof entry.person_id === "string" ? { person_id: entry.person_id } : {}) };
+            const properties = isRecord(entry.properties)
+                ? Object.fromEntries(Object.entries(entry.properties).flatMap(([key, value]) => (typeof value === "string" || typeof value === "number" ? [[key, String(value)]] : [])))
+                : {};
+            return {
+                email: entry.email,
+                ...(typeof entry.person_id === "string" ? { person_id: entry.person_id } : {}),
+                ...(typeof entry.first_name === "string" && entry.first_name ? { first_name: entry.first_name } : {}),
+                ...(typeof entry.last_name === "string" && entry.last_name ? { last_name: entry.last_name } : {}),
+                ...(Object.keys(properties).length > 0 ? { properties } : {}),
+            };
         }
         return { email: "" };
     });
@@ -121,24 +114,133 @@ function runSubscriptionsSet(email, options) {
         },
     });
 }
-function runSubscriptionsImport(options) {
+/**
+ * Send the import in route-sized calls (one consent evidence record covers
+ * every call: the same source vouched for the whole file) and add up the
+ * counts. Invalid indexes refer to the file's own rows.
+ */
+async function runSubscriptionsImport(options) {
     const list = requireFlag(options.list, "--list");
     const source = requireFlag(options.source, "--source");
     const status = readOption(options.status) ?? "subscribed";
     requireSubscribeEvidence(options, status);
-    const entries = readSubscriptionImportFile(requireFlag(options.file, "--file"));
+    const read = readSubscriptionImportFile(requireFlag(options.file, "--file"));
+    const { entries, ignored } = await keepKnownProperties(read);
     const evidence = evidenceBody(options);
-    return requestOxygen("/api/cli/subscriptions/import", {
+    const chunks = chunkContactImport(entries);
+    let last = {};
+    const totals = { received: 0, created: 0, updated: 0, unchanged: 0, kept_cleaned: 0, people_written: 0, people_matched: 0 };
+    const invalid = [];
+    let offset = 0;
+    for (const chunk of chunks) {
+        last = await requestOxygen("/api/cli/subscriptions/import", {
+            method: "POST",
+            body: {
+                list,
+                entries: chunk,
+                status,
+                source,
+                ...(evidence ? { evidence } : {}),
+            },
+        });
+        for (const key of Object.keys(totals))
+            totals[key] += Number(last[key] ?? 0);
+        for (const entry of last.invalid ?? [])
+            invalid.push({ ...entry, index: entry.index + offset });
+        offset += chunk.length;
+    }
+    if (chunks.length === 1 && ignored.length === 0)
+        return last;
+    const written = totals.created + totals.updated;
+    return {
+        ...last,
+        ...totals,
+        invalid,
+        calls: chunks.length,
+        ...(ignored.length > 0 ? { ignored_columns: ignored } : {}),
+        changed: written > 0,
+        effect_outcome: written > 0 ? (invalid.length > 0 ? "partial" : "applied") : totals.received === 0 ? "no_data" : "no_change",
+        message: `${written} of ${totals.received} addresses changed on ${list} in ${chunks.length} call(s)`
+            + (ignored.length > 0 ? `; columns that are not contact properties were skipped: ${ignored.join(", ")}` : "")
+            + ".",
+    };
+}
+/** --property key=value, repeatable; key= (empty) clears the property. */
+function readPropertyFlags(values) {
+    if (!values || values.length === 0)
+        return undefined;
+    const properties = {};
+    for (const value of values) {
+        const at = value.indexOf("=");
+        if (at <= 0) {
+            throw new OxygenError("invalid_request", "--property takes key=value (key= clears it).", { details: { field: "properties", value }, exitCode: 2 });
+        }
+        const raw = value.slice(at + 1);
+        properties[value.slice(0, at).trim()] = raw === "" ? null : raw;
+    }
+    return properties;
+}
+function contactFieldBody(options) {
+    const properties = readPropertyFlags(options.property);
+    return {
+        // An explicit empty flag clears the field on the person.
+        ...(options.firstName !== undefined ? { first_name: options.firstName === "" ? null : options.firstName } : {}),
+        ...(options.lastName !== undefined ? { last_name: options.lastName === "" ? null : options.lastName } : {}),
+        ...(properties ? { properties } : {}),
+    };
+}
+function collect(value, previous = []) {
+    return [...previous, value];
+}
+function runContactsList(options) {
+    const params = new URLSearchParams({ list: requireFlag(options.list, "--list") });
+    for (const [key, value] of [["search", options.search], ["status", options.status], ["after", options.after], ["limit", options.limit]]) {
+        const read = readOption(value);
+        if (read)
+            params.set(key, read);
+    }
+    return requestOxygen(`/api/cli/subscriptions/contacts?${params.toString()}`);
+}
+function runContactsAdd(email, options) {
+    const list = requireFlag(options.list, "--list");
+    const status = readOption(options.status) ?? "subscribed";
+    const note = readOption(options.note);
+    if (!note)
+        requireSubscribeEvidence(options, status);
+    const source = readOption(options.source);
+    const evidence = evidenceBody(options);
+    return requestOxygen("/api/cli/subscriptions/contacts", {
         method: "POST",
         body: {
             list,
-            entries,
+            email,
             status,
-            source,
+            ...(source ? { source } : {}),
+            ...(note ? { note } : {}),
             ...(evidence ? { evidence } : {}),
+            ...contactFieldBody(options),
         },
     });
 }
+function runContactsEdit(email, options) {
+    return requestOxygen("/api/cli/subscriptions/contacts", {
+        method: "PATCH",
+        body: { list: requireFlag(options.list, "--list"), email, ...contactFieldBody(options) },
+    });
+}
+function runContactsRemove(email, options) {
+    const params = new URLSearchParams({ list: requireFlag(options.list, "--list"), email });
+    return requestOxygen(`/api/cli/subscriptions/contacts?${params.toString()}`, { method: "DELETE" });
+}
+async function runSubscriptionsExport(options) {
+    const list = requireFlag(options.list, "--list");
+    const output = resolve(requireFlag(options.output, "--output"));
+    const params = new URLSearchParams({ list, format: "csv" });
+    const saved = await requestOxygen(`/api/cli/subscriptions/contacts/export?${params.toString()}`, {
+        binaryOutputPath: output,
+    });
+    return { list, path: saved.path, bytes: saved.bytes, message: `Saved ${list}'s contacts to ${saved.path}.` };
+}
 function addEvidenceFlags(command) {
     return command
         .option("--notice-version <version>", "Version of the consent notice the person saw (with --notice-text-hash).")
@@ -158,18 +260,64 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         await handleAsyncAction("subscriptions lists list", options, () => requestOxygen("/api/cli/subscriptions/lists"));
     }))
         .addCommand(new Command("create")
-        .description("Create a subscription list.")
+        .description("Create a subscription list or a topic. A topic (--kind topic --parent <list>) is a narrower subject inside an audience list; a newsletter on a topic mails only its subscribers. --default opt_out puts the list's subscribers on the topic (same consent); opt_in waits for each recipient's choice on their preference page.")
         .argument("<key>", "Stable key: lowercase letters, digits, - and _, such as newsletter.")
         .requiredOption("--name <name>", "Display name.")
-        .requiredOption("--kind <kind>", "marketing, product_updates or onboarding.")
+        .requiredOption("--kind <kind>", "marketing, product_updates, onboarding or topic.")
         .option("--description <text>", "What subscribers get.")
+        .option("--visibility <visibility>", "public (default; on the preference page) or private (shown only to subscribers).")
+        .option("--default <subscription>", "Topics: opt_in (default) or opt_out (joined with the parent list).")
+        .option("--parent <key-or-id>", "Topics: the audience list this topic belongs to.")
         .option("--json", "Print a JSON envelope.")
         .action(async (key, options) => {
         await handleAsyncAction("subscriptions lists create", options, () => {
             const description = readOption(options.description);
+            const visibility = readOption(options.visibility);
+            const defaultSubscription = readOption(options.default);
+            const parent = readOption(options.parent);
             return requestOxygen("/api/cli/subscriptions/lists", {
                 method: "POST",
-                body: { key, name: options.name, kind: options.kind, ...(description ? { description } : {}) },
+                body: {
+                    key,
+                    name: options.name,
+                    kind: options.kind,
+                    ...(description ? { description } : {}),
+                    ...(visibility ? { visibility } : {}),
+                    ...(defaultSubscription ? { default_subscription: defaultSubscription } : {}),
+                    ...(parent ? { parent } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Change a list or topic: name, description, kind, visibility, default subscription or parent. Turning a topic opt_out puts its list's current subscribers on it, each with their own consent evidence. The key never changes.")
+        .argument("<list>", "List key or id.")
+        .option("--name <name>", "Display name.")
+        .option("--kind <kind>", "marketing, product_updates, onboarding or topic.")
+        .option("--description <text>", "What subscribers get (\"\" clears it).")
+        .option("--visibility <visibility>", "public or private.")
+        .option("--default <subscription>", "Topics: opt_in or opt_out.")
+        .option("--parent <key-or-id>", "Topics: the audience list (\"\" clears it).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (list, options) => {
+        await handleAsyncAction("subscriptions lists update", options, () => {
+            const name = readOption(options.name);
+            const kind = readOption(options.kind);
+            const visibility = readOption(options.visibility);
+            const defaultSubscription = readOption(options.default);
+            const description = clearableOption(options.description);
+            const parent = clearableOption(options.parent);
+            return requestOxygen("/api/cli/subscriptions/lists", {
+                method: "PATCH",
+                body: {
+                    list,
+                    ...(name ? { name } : {}),
+                    ...(kind ? { kind } : {}),
+                    ...(visibility ? { visibility } : {}),
+                    ...(defaultSubscription ? { default_subscription: defaultSubscription } : {}),
+                    ...("value" in description ? { description: description.value } : {}),
+                    ...("value" in parent ? { parent: parent.value } : {}),
+                },
             });
         });
     })))
@@ -191,7 +339,7 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         await handleAsyncAction("subscriptions set", options, () => runSubscriptionsSet(email, options));
     }))
         .addCommand(addEvidenceFlags(new Command("import")
-        .description("Import up to 5,000 addresses onto one list under one consent evidence record. --file is JSON (emails or { email, person_id }) or CSV with an email column. Addresses cleaned by a complaint or hard bounce stay off; invalid rows are reported by index.")
+        .description("Import addresses onto one list under one consent evidence record. --file is JSON (emails or { email, first_name, last_name, properties }) or CSV with an email column; first_name, last_name and contact-property columns go to each person on Records People (created or matched by email). Large files are sent in batches. Addresses cleaned by a complaint or hard bounce stay off; invalid rows are reported by index.")
         .requiredOption("--list <key-or-id>", "Subscription list key or id.")
         .requiredOption("--file <path>", "JSON or CSV file of addresses.")
         .requiredOption("--source <source>", "Where these addresses came from, e.g. webinar_2026_10.")
@@ -199,5 +347,103 @@ export function registerSubscriptionsFamily(program, handleAsyncAction) {
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("subscriptions import", options, () => runSubscriptionsImport(options));
-    })));
+    }))
+        .addCommand(new Command("export")
+        .description("Save every contact of a list as CSV: each status, the consent that subscribed it (when, source, basis or notice), name and contact properties.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .requiredOption("--output <path>", "CSV file to create (must not exist).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions export", options, () => runSubscriptionsExport(options));
+    }))
+        .addCommand(registerContactsCommands(handleAsyncAction))
+        .addCommand(registerPropertiesCommands(handleAsyncAction)));
+}
+function addContactFieldFlags(command) {
+    return command
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--first-name <name>", "First name on the person's Records People record (\"\" clears it).")
+        .option("--last-name <name>", "Last name on the person's Records People record (\"\" clears it).")
+        .option("--property <key=value>", "A contact property, repeatable; key= clears it. List keys with subscriptions properties list.", collect);
+}
+function registerContactsCommands(handleAsyncAction) {
+    return new Command("contacts")
+        .description("Contacts of a subscription list: each address with its status, consent source and its Records person (name and contact properties).")
+        .addCommand(new Command("list")
+        .description("List a list's contacts with status, source, subscribed date, name and properties; search by email or name.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--search <text>", "Match the email or the person's name.")
+        .option("--status <status>", "Only subscribed, unsubscribed, pending or cleaned.")
+        .option("--after <email>", "next_cursor of the previous page.")
+        .option("--limit <n>", "Contacts per page, 1 to 200 (default 50).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions contacts list", options, () => runContactsList(options));
+    }))
+        .addCommand(addEvidenceFlags(addContactFieldFlags(new Command("add")
+        .description("Add one contact to a list by hand, with consent evidence (--note says where consent came from), and write its name and properties to Records People.")
+        .argument("<email>", "Email address."))
+        .option("--status <status>", "Status to set (default subscribed).")
+        .option("--source <source>", "Where this contact came from (default manual).")
+        .option("--note <text>", "How you got this person's consent; recorded as the consent basis with your name."))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts add", options, () => runContactsAdd(email, options));
+    }))
+        .addCommand(addContactFieldFlags(new Command("edit")
+        .description("Edit a contact's name or properties on its Records People record. Status and consent stay as they are.")
+        .argument("<email>", "Email address."))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts edit", options, () => runContactsEdit(email, options));
+    }))
+        .addCommand(new Command("remove")
+        .description("Remove a contact from a list. Its consent history is kept and its Records person is untouched; to stop mail but keep it listed, use subscriptions set --status unsubscribed.")
+        .argument("<email>", "Email address.")
+        .requiredOption("--list <key-or-id>", "Subscription list key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (email, options) => {
+        await handleAsyncAction("subscriptions contacts remove", options, () => runContactsRemove(email, options));
+    }));
+}
+function registerPropertiesCommands(handleAsyncAction) {
+    return new Command("properties")
+        .description("Contact properties: text or number fields on Records People that newsletters use as {{contact.<key>}}.")
+        .addCommand(new Command("list")
+        .description("List contact properties (key, label, type).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("subscriptions properties list", options, () => requestOxygen("/api/cli/subscriptions/properties"));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a contact property: a new text or number field on Records People.")
+        .argument("<key>", "Field key, e.g. plan; {{contact.plan}} in a template.")
+        .option("--label <label>", "Display name (default the key).")
+        .option("--type <type>", "string or number (default string).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties create", options, () => {
+            const label = readOption(options.label);
+            const type = readOption(options.type);
+            return requestOxygen("/api/cli/subscriptions/properties", {
+                method: "POST",
+                body: { key, ...(label ? { label } : {}), ...(type ? { type } : {}) },
+            });
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Rename a contact property. Its key never changes.")
+        .argument("<key>", "Property key.")
+        .requiredOption("--label <label>", "New display name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties update", options, () => requestOxygen("/api/cli/subscriptions/properties", { method: "PATCH", body: { key, label: options.label } }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete a contact property: the People field is removed and its values archived (restorable on the People table).")
+        .argument("<key>", "Property key.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (key, options) => {
+        await handleAsyncAction("subscriptions properties delete", options, () => requestOxygen(`/api/cli/subscriptions/properties?${new URLSearchParams({ key }).toString()}`, { method: "DELETE" }));
+    }));
 }

package/dist/sequence-start-at.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `sequences start --at`: an ISO 8601 timestamp with a timezone, or a relative
+ * "in 30m" / "in 2h" / "in 3d". Returns the canonical UTC timestamp the start
+ * route stores; the same future and 30-day bounds apply as on the server, so a
+ * bad value fails before any request.
+ */
+export declare function parseStartAtFlag(value: string, now?: Date): string;