@oxygen-agent/cli 1.1014.1600 → 1.1014.1763

package/dist/sequences-brand-kit-command.d.ts

@@ -0,0 +1,28 @@
+import { JsonOptions } from "./cli-output.js";
+import { ExtractedCommandActionHandler } from "./command-support.js";
+import { Command } from "commander";
+type BrandKitSetOptions = JsonOptions & {
+    logoUrl?: string;
+    logoWidth?: string;
+    colorBackground?: string;
+    colorContentBackground?: string;
+    colorText?: string;
+    colorLink?: string;
+    colorButton?: string;
+    colorButtonText?: string;
+    containerWidth?: string;
+    font?: string;
+    companyName?: string;
+    postalAddress?: string;
+    social?: string;
+    preferencePageTitle?: string;
+    preferencePageDescription?: string;
+};
+/** `network=url` pairs, comma-separated; "" clears every link. */
+export declare function readSocialLinksOption(value: string | undefined): Array<{
+    network: string;
+    url: string;
+}> | undefined;
+export declare function brandKitSetBody(options: BrandKitSetOptions): Record<string, unknown>;
+export declare function sequencesBrandKitCommand(handleAsyncAction: ExtractedCommandActionHandler): Command;
+export {};

package/dist/sequences-brand-kit-command.js

@@ -0,0 +1,83 @@
+import { requestOxygen } from "./http-client.js";
+import { readClearableOption } from "./util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+/** A whole number; "" clears (null); absence leaves the field alone. */
+function readClearableInteger(value, flag) {
+    const text = readClearableOption(value);
+    if (text === undefined || text === null)
+        return text;
+    const parsed = Number(text);
+    if (!Number.isInteger(parsed))
+        throw new OxygenError("invalid_request", `${flag} must be a whole number.`, { exitCode: 2 });
+    return parsed;
+}
+/** `network=url` pairs, comma-separated; "" clears every link. */
+export function readSocialLinksOption(value) {
+    if (value === undefined)
+        return undefined;
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean).map((entry) => {
+        const at = entry.indexOf("=");
+        if (at <= 0) {
+            throw new OxygenError("invalid_request", "--social takes network=url pairs, e.g. linkedin=https://linkedin.com/company/acme.", { exitCode: 2 });
+        }
+        return { network: entry.slice(0, at).trim().toLowerCase(), url: entry.slice(at + 1).trim() };
+    });
+}
+export function brandKitSetBody(options) {
+    // A literal \n in a shell argument is a line break in the address.
+    const postalAddress = options.postalAddress === undefined ? undefined : options.postalAddress.replace(/\\n/g, "\n");
+    // An absent flag stays undefined, which the JSON body drops: only named fields change.
+    const body = {
+        logo_url: readClearableOption(options.logoUrl),
+        logo_width: readClearableInteger(options.logoWidth, "--logo-width"),
+        background_color: readClearableOption(options.colorBackground),
+        content_background_color: readClearableOption(options.colorContentBackground),
+        text_color: readClearableOption(options.colorText),
+        link_color: readClearableOption(options.colorLink),
+        button_color: readClearableOption(options.colorButton),
+        button_text_color: readClearableOption(options.colorButtonText),
+        container_width: readClearableInteger(options.containerWidth, "--container-width"),
+        font_family: readClearableOption(options.font),
+        company_name: readClearableOption(options.companyName),
+        postal_address: postalAddress === undefined ? undefined : (postalAddress.trim() ? postalAddress : null),
+        social_links: readSocialLinksOption(options.social),
+        preference_page_title: readClearableOption(options.preferencePageTitle),
+        preference_page_description: readClearableOption(options.preferencePageDescription),
+    };
+    if (Object.values(body).every((value) => value === undefined)) {
+        throw new OxygenError("invalid_request", "Pass at least one brand kit flag, such as --postal-address.", { exitCode: 2 });
+    }
+    return body;
+}
+export function sequencesBrandKitCommand(handleAsyncAction) {
+    return new Command("brand-kit")
+        .description("The workspace's newsletter brand kit: logo, colours, width, font, company name, postal address, social links and preference page title. Every newsletter's footer carries the company name and postal address; a newsletter starts only once the postal address is set. 0 credits.")
+        .addCommand(new Command("get")
+        .description("Show the brand kit with defaults applied and whether newsletters can start (newsletter_ready).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences brand-kit get", options, () => requestOxygen("/api/cli/sequencer/brand-kit"));
+    }))
+        .addCommand(new Command("set")
+        .description("Change brand kit fields; only the flags you pass change, and \"\" clears one (a colour, width or font returns to its default).")
+        .option("--logo-url <url>", "https:// URL of the logo image.")
+        .option("--logo-width <px>", "Logo width in pixels, 40-600.")
+        .option("--color-background <hex>", "Page background, e.g. #f4f4f5.")
+        .option("--color-content-background <hex>", "Content area background.")
+        .option("--color-text <hex>", "Body text colour.")
+        .option("--color-link <hex>", "Link colour.")
+        .option("--color-button <hex>", "Button colour.")
+        .option("--color-button-text <hex>", "Button text colour.")
+        .option("--container-width <px>", "Content width in pixels, 480-800 (default 600).")
+        .option("--font <font>", "system, georgia, arial, helvetica or verdana.")
+        .option("--company-name <name>", "Shown in every newsletter's footer.")
+        .option("--postal-address <address>", "Postal address for every newsletter's footer, up to 500 characters; \\n starts a new line.")
+        .option("--social <links>", "Comma-separated network=url pairs (website, linkedin, x, facebook, instagram, youtube, tiktok, github).")
+        .option("--preference-page-title <title>", "Title of the subscription preference page.")
+        .option("--preference-page-description <text>", "Text under the preference page title.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences brand-kit set", options, () => requestOxygen("/api/cli/sequencer/brand-kit", { method: "PATCH", body: brandKitSetBody(options) }));
+    }));
+}

package/dist/sequences-content-commands.d.ts

@@ -0,0 +1,28 @@
+import { Command } from "commander";
+import type { ExtractedCommandActionHandler } from "./command-support.js";
+/** The content flags `sequences content set` and `email-templates save` share. */
+export type ContentFileOptions = {
+    htmlFile?: string;
+    jsonFile?: string;
+    textFile?: string;
+    previewText?: string;
+    name?: string;
+};
+export declare function readRevisionFlag(value: string | undefined, flag: string): number | undefined;
+/** The document fields a set call sends: from --html-file or a --json-file export, with optional text and preview overrides. */
+export declare function contentBody(options: ContentFileOptions): Record<string, unknown>;
+type LoadedSequence = {
+    sequence: {
+        id: string;
+        name?: string;
+        status?: string;
+        definition: {
+            steps?: unknown[];
+        };
+    };
+    sequence_revision?: string;
+    web_url?: string;
+};
+export declare function readSequence(sequence: string): Promise<LoadedSequence>;
+export declare function sequencesContentCommand(handleAsyncAction: ExtractedCommandActionHandler): Command;
+export {};

package/dist/sequences-content-commands.js

@@ -0,0 +1,176 @@
+import { readFileSync } from "node:fs";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { sequenceContentStep, withSequenceStepBodyDocument } from "@oxygen/shared/sequences";
+import { Command } from "commander";
+import { parseJsonValue } from "./command-support.js";
+import { requestOxygen } from "./http-client.js";
+import { isRecord, readOption } from "./util.js";
+export function readRevisionFlag(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const revision = Number(value);
+    if (!Number.isInteger(revision) || revision < 1)
+        throw new OxygenError("invalid_request", `${flag} must be a positive integer.`, { exitCode: 2 });
+    return revision;
+}
+function readTextFile(path, flag) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        throw new OxygenError("invalid_request", `${flag} could not be read.`, { details: { flag, path }, exitCode: 2 });
+    }
+}
+/** The document fields a set call sends: from --html-file or a --json-file export, with optional text and preview overrides. */
+export function contentBody(options) {
+    let exported = {};
+    if (options.jsonFile) {
+        const parsed = parseJsonValue(readTextFile(options.jsonFile, "--json-file"), "--json-file");
+        if (!isRecord(parsed) || typeof parsed.html !== "string") {
+            throw new OxygenError("invalid_request", "--json-file must hold a JSON object with html (and optional text, preview_text, editor_json).", { exitCode: 2 });
+        }
+        exported = parsed;
+    }
+    // Flags override the export field by field; one object, no self-spreads.
+    const html = options.htmlFile ? readTextFile(options.htmlFile, "--html-file") : exported.html;
+    const text = options.textFile ? readTextFile(options.textFile, "--text-file") : exported.text;
+    const previewText = options.previewText ?? exported.preview_text;
+    const name = readOption(options.name);
+    return {
+        html,
+        ...(text !== undefined ? { text } : {}),
+        ...(previewText !== undefined ? { preview_text: previewText } : {}),
+        ...(exported.editor_json !== undefined ? { editor_json: exported.editor_json } : {}),
+        ...(name ? { name } : {}),
+    };
+}
+/** A step's content links to its Sequence's web home (a newsletter's composer), not the document's. */
+function sequenceLink(read) {
+    return read.web_url ? { web_url: read.web_url, deepLink: read.web_url } : {};
+}
+export async function readSequence(sequence) {
+    const read = await requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}`);
+    const loaded = read.sequence;
+    if (!loaded?.id || !loaded.definition) {
+        throw new OxygenError("sequence_not_found", "Sequence not found.", { details: { sequence }, exitCode: 4 });
+    }
+    return {
+        sequence: { ...loaded, id: loaded.id, definition: loaded.definition },
+        ...(read.sequence_revision ? { sequence_revision: read.sequence_revision } : {}),
+        ...(read.web_url ? { web_url: read.web_url } : {}),
+    };
+}
+async function contentGet(sequence, options) {
+    const stepId = readOption(options.step);
+    if (!stepId)
+        throw new OxygenError("invalid_request", "--step is required.", { exitCode: 2 });
+    const read = await readSequence(sequence);
+    const { step, bodyDocument } = sequenceContentStep(read.sequence.definition, stepId);
+    if (!bodyDocument) {
+        return {
+            sequence_id: read.sequence.id, step_id: stepId, body_document: null,
+            body_template: step.body_template ?? "", body_html_template: step.body_html_template ?? null,
+            next_step: `Give this step a designed body: oxygen sequences content set ${read.sequence.id} --step ${stepId} --html-file <file>`,
+            ...sequenceLink(read),
+        };
+    }
+    const query = bodyDocument.revision ? `?revision=${bodyDocument.revision}` : "";
+    const document = await requestOxygen(`/api/cli/email-documents/${encodeURIComponent(bodyDocument.id)}${query}`);
+    return { sequence_id: read.sequence.id, step_id: stepId, body_document: bodyDocument, ...document, ...sequenceLink(read) };
+}
+async function contentSet(sequence, options) {
+    const stepId = readOption(options.step);
+    if (!stepId)
+        throw new OxygenError("invalid_request", "--step is required.", { exitCode: 2 });
+    const fromDocument = readOption(options.fromDocument);
+    const fromStarter = readOption(options.fromStarter);
+    const sources = [fromDocument, fromStarter, options.htmlFile || options.jsonFile].filter(Boolean).length;
+    if (sources > 1) {
+        throw new OxygenError("conflicting_flags", "Pass one of --from-document, --from-starter or --html-file/--json-file.", { exitCode: 2 });
+    }
+    if (sources === 0) {
+        throw new OxygenError("invalid_request", "Pass --html-file, --json-file, --from-document or --from-starter.", { exitCode: 2 });
+    }
+    const revision = readRevisionFlag(options.revision, "--revision");
+    const expectedRevision = readRevisionFlag(options.expectedRevision, "--expected-revision");
+    if (revision !== undefined && !fromDocument)
+        throw new OxygenError("invalid_request", "--revision applies to --from-document.", { exitCode: 2 });
+    const body = fromDocument || fromStarter ? {} : contentBody(options);
+    const read = await readSequence(sequence);
+    const { bodyDocument } = sequenceContentStep(read.sequence.definition, stepId);
+    if (read.sequence.status && read.sequence.status !== "draft") {
+        throw new OxygenError("sequence_journey_locked", "A started sequence keeps the content it went live with. Duplicate it to a new draft to change the email.", {
+            details: { sequence_id: read.sequence.id, status: read.sequence.status, next_step: `oxygen sequences duplicate ${read.sequence.id}` }, exitCode: 1,
+        });
+    }
+    let saved;
+    if (fromDocument) {
+        saved = await requestOxygen(`/api/cli/email-documents/${encodeURIComponent(fromDocument)}`, {
+            method: "POST", body: {
+                action: "duplicate", role: "step",
+                ...(revision !== undefined ? { revision } : {}),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+            },
+        });
+    }
+    else if (fromStarter) {
+        saved = await requestOxygen("/api/cli/email-documents", {
+            method: "POST", body: { role: "step", starter_id: fromStarter, name: readOption(options.name) ?? `${read.sequence.name ?? "Sequence"}: ${stepId}` },
+        });
+    }
+    else if (bodyDocument) {
+        saved = await requestOxygen(`/api/cli/email-documents/${encodeURIComponent(bodyDocument.id)}`, {
+            method: "PATCH", body: { ...body, ...(expectedRevision !== undefined ? { expected_revision: expectedRevision } : {}) },
+        });
+    }
+    else {
+        saved = await requestOxygen("/api/cli/email-documents", {
+            method: "POST", body: { role: "step", name: `${read.sequence.name ?? "Sequence"}: ${stepId}`, ...body },
+        });
+    }
+    const documentId = saved.document?.id;
+    if (!documentId)
+        throw new OxygenError("unexpected_response", "The email was saved but its id was not returned; run sequences content get.", { exitCode: 1 });
+    const definition = withSequenceStepBodyDocument({ steps: read.sequence.definition.steps ?? [] }, stepId, documentId);
+    if (definition) {
+        await requestOxygen(`/api/cli/sequences/${encodeURIComponent(read.sequence.id)}`, {
+            method: "PATCH", body: { definition, ...(read.sequence_revision ? { expected_revision: read.sequence_revision } : {}) },
+        });
+    }
+    return { ...saved, sequence_id: read.sequence.id, step_id: stepId, body_document: { id: documentId }, definition_updated: definition !== null, ...sequenceLink(read) };
+}
+export function sequencesContentCommand(handleAsyncAction) {
+    return new Command("content")
+        .description("A newsletter step's designed email body (HTML up to 100 KB), stored as a revisioned email document the step references. Sends through a sending domain; merge tags render per recipient with HTML escaping; {{unsubscribe_url}} places the unsubscribe link (else a footer is added).")
+        .addCommand(new Command("get")
+        .description("Show an email step's content: its email document (HTML, text, preview text, revision, size against the 100 KB limit), or its plain body when it has none.")
+        .argument("<sequence>", "Sequence id or slug.")
+        .requiredOption("--step <id>", "The email_send step id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences content get", options, () => contentGet(sequence, options));
+    }))
+        .addCommand(new Command("set")
+        .description("Set a draft sequence's email step body from an HTML file or an editor JSON export: saves a new revision of the step's email document (creating it on first use) and points the step at it. Scripts and event handlers are removed; HTML above 100 KB is refused.")
+        .argument("<sequence>", "Sequence id or slug (a draft).")
+        .requiredOption("--step <id>", "The email_send step id.")
+        .option("--html-file <path>", "The email HTML.")
+        .option("--json-file <path>", "A JSON object { html, text?, preview_text?, editor_json? }, e.g. the editor's export.")
+        .option("--text-file <path>", "The plain-text part. Default: derived from the HTML.")
+        .option("--preview-text <text>", "The inbox preview line shown after the subject.")
+        .option("--name <name>", "Document name.")
+        .option("--from-document <id>", "Start from a copy of this email document or template instead of a file.")
+        .option("--from-starter <id>", "Start from a copy of a built-in starter template (ids: `oxygen email-templates list`).")
+        .option("--revision <n>", "With --from-document: copy this revision (default its current one).")
+        .option("--expected-revision <n>", "Refuse the save if the step's document is no longer at this revision (another edit landed).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences content set", options, () => contentSet(sequence, options));
+    }))
+        .addCommand(new Command("templates")
+        .description("List the workspace's email templates and the built-in starters (no content); start a step from one with `sequences content set --from-document <id>` or `--from-starter <id>`. Manage them with `oxygen email-templates`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sequences content templates", options, () => requestOxygen("/api/cli/email-documents?role=template"));
+    }));
+}

package/dist/sequences-newsletter-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+/** Validated `--interval`; undefined when absent. */
+export declare function readNewsletterIntervalFlag(value: string | undefined): string | undefined;
+/** The newsletter block of `sequences stats` (empty for a mailbox Sequence). */
+export declare function formatNewsletterStatsLines(value: unknown): string[];
+export declare function sequencesRecipientsCommand(): Command;

package/dist/sequences-newsletter-commands.js

@@ -0,0 +1,108 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { NEWSLETTER_RECIPIENT_STATUSES, NEWSLETTER_TIMELINE_INTERVALS, isNewsletterRecipientStatus, isNewsletterTimelineInterval, } from "@oxygen/shared/newsletter-analytics";
+import { Command } from "commander";
+import { handleReadActionWithLens, renderTextTable } from "./command-support.js";
+import { requestOxygen } from "./http-client.js";
+import { isRecord } from "./util.js";
+/**
+ * Newsletter analytics on the CLI: the `newsletter` block `sequences stats`
+ * prints for a sending-domain Sequence, its `--interval` flag, and
+ * `oxygen sequences recipients`. MCP twin: `oxygen_newsletters` stats / recipients.
+ */
+const record = (value) => (isRecord(value) ? value : {});
+const count = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+const percent = (value) => (typeof value === "number" && Number.isFinite(value) ? `${(value * 100).toFixed(1)}%` : "—");
+/** Validated `--interval`; undefined when absent. */
+export function readNewsletterIntervalFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isNewsletterTimelineInterval(value)) {
+        throw new OxygenError("invalid_request", `--interval must be one of ${NEWSLETTER_TIMELINE_INTERVALS.join(", ")}.`, { exitCode: 2 });
+    }
+    return value;
+}
+/** The newsletter block of `sequences stats` (empty for a mailbox Sequence). */
+export function formatNewsletterStatsLines(value) {
+    if (!isRecord(value))
+        return [];
+    const opens = record(value.opens);
+    const clicks = record(value.clicks);
+    const bounces = record(value.bounces);
+    const rates = record(value.rates);
+    const lines = [
+        "",
+        "Newsletter (SES)",
+        `Targeted ${count(value.recipients_targeted)} · sent ${count(value.sent)} · delivered ${count(value.delivered)} · suppressed ${count(value.suppressed)}`,
+        ...renderTextTable(["METRIC", "UNIQUE", "TOTAL", "RATE"], [
+            ["Opens (estimated)", String(count(opens.unique)), String(count(opens.total)), percent(rates.open_rate)],
+            ["Clicks", String(count(clicks.unique)), String(count(clicks.total)), percent(rates.click_rate)],
+            ["Hard bounces", String(count(bounces.hard)), "", percent(rates.bounce_rate)],
+            ["Soft bounces", String(count(bounces.soft)), "", ""],
+            ["Complaints", String(count(value.complaints)), "", percent(rates.complaint_rate)],
+            ["Unsubscribes", String(count(value.unsubscribes)), "", percent(rates.unsubscribe_rate)],
+        ]),
+        "Opens are estimated (Apple Mail Privacy Protection and scanners open mail); bot events are excluded. Rates are over delivered, bounces over sent.",
+    ];
+    const links = Array.isArray(value.links) ? value.links.filter(isRecord) : [];
+    if (links.length > 0) {
+        lines.push("", ...renderTextTable(["LINK", "UNIQUE", "TOTAL"], links.map((link) => [
+            String(link.link ?? ""), String(count(link.unique_clicks)), String(count(link.total_clicks)),
+        ])));
+    }
+    return lines;
+}
+function formatRecipients(data) {
+    const recipients = Array.isArray(data.recipients) ? data.recipients.filter(isRecord) : [];
+    const total = count(data.total);
+    const offset = count(data.offset);
+    const lines = [
+        `${typeof data.name === "string" ? data.name : "Newsletter"}: ${total} ${data.status ? `${String(data.status)} ` : ""}recipient${total === 1 ? "" : "s"}`
+            + (recipients.length > 0 ? ` (showing ${offset + 1}-${offset + recipients.length})` : ""),
+    ];
+    if (recipients.length > 0) {
+        lines.push("", ...renderTextTable(["EMAIL", "STATUS", "OPENS", "CLICKS", "LAST EVENT"], recipients.map((row) => [
+            String(row.email ?? ""), String(row.status ?? ""), String(count(row.opens)), String(count(row.clicks)),
+            typeof row.last_event_at === "string" ? row.last_event_at : "—",
+        ])));
+    }
+    if (typeof data.next_offset === "number")
+        lines.push("", `Next page: --offset ${data.next_offset}`);
+    const link = typeof data.web_url === "string" ? data.web_url : null;
+    if (link)
+        lines.push("", link);
+    return `${lines.join("\n")}\n`;
+}
+function wholeFlag(value, flag) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value.trim()))
+        throw new OxygenError("invalid_request", `${flag} must be a non-negative whole number.`, { exitCode: 2 });
+    return value.trim();
+}
+export function sequencesRecipientsCommand() {
+    return new Command("recipients")
+        .description(`A newsletter's (sending-domain Sequence's) recipients, one row per message with its status (${NEWSLETTER_RECIPIENT_STATUSES.join(", ")}), opens, clicks and last event, newest activity first. Paged by --offset. Opens are estimated; bot events are excluded. 0 credits.`)
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--status <status>", `Only recipients with this status: ${NEWSLETTER_RECIPIENT_STATUSES.join(", ")}.`)
+        .option("--limit <n>", "Rows per page (1-200, default 50).")
+        .option("--offset <n>", "Skip this many rows (pass next_offset from the previous page).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleReadActionWithLens("sequences recipients", options, () => {
+            if (options.status !== undefined && !isNewsletterRecipientStatus(options.status)) {
+                throw new OxygenError("invalid_request", `--status must be one of ${NEWSLETTER_RECIPIENT_STATUSES.join(", ")}.`, { exitCode: 2 });
+            }
+            const params = new URLSearchParams();
+            if (options.status)
+                params.set("status", options.status);
+            const limit = wholeFlag(options.limit, "--limit");
+            if (limit !== undefined)
+                params.set("limit", limit);
+            const offset = wholeFlag(options.offset, "--offset");
+            if (offset !== undefined)
+                params.set("offset", offset);
+            const query = params.toString();
+            return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/recipients${query ? `?${query}` : ""}`);
+        }, formatRecipients);
+    });
+}

package/dist/sequences-test-send-command.d.ts

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

package/dist/sequences-test-send-command.js

@@ -0,0 +1,47 @@
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { NEWSLETTER_TEST_MAX_RECIPIENTS } from "@oxygen/shared/newsletter-test-send";
+import { Command } from "commander";
+import { parseJsonValue } from "./command-support.js";
+import { requestOxygen } from "./http-client.js";
+import { isRecord, readOption } from "./util.js";
+async function testSend(sequence, options) {
+    if (options.listRecipients) {
+        if (options.to || options.sampleLead) {
+            throw new OxygenError("conflicting_flags", "--list-recipients takes no --to or --sample-lead.", { exitCode: 2 });
+        }
+        return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/test-send`);
+    }
+    const stepId = readOption(options.step);
+    if (!stepId)
+        throw new OxygenError("invalid_request", "--step is required.", { exitCode: 2 });
+    const to = (options.to ?? "").split(",").map((entry) => entry.trim()).filter(Boolean);
+    if (to.length === 0)
+        throw new OxygenError("invalid_request", "--to is required: one or more member email addresses, comma-separated.", { exitCode: 2 });
+    if (to.length > NEWSLETTER_TEST_MAX_RECIPIENTS) {
+        throw new OxygenError("invalid_request", `--to takes at most ${NEWSLETTER_TEST_MAX_RECIPIENTS} addresses.`, { exitCode: 2 });
+    }
+    let sampleLead;
+    if (options.sampleLead !== undefined) {
+        const parsed = parseJsonValue(options.sampleLead, "--sample-lead");
+        if (!isRecord(parsed))
+            throw new OxygenError("invalid_request", "--sample-lead must be a JSON object of merge values.", { exitCode: 2 });
+        sampleLead = parsed;
+    }
+    return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/test-send`, {
+        method: "POST",
+        body: { step_id: stepId, to, ...(sampleLead ? { sample_lead: sampleLead } : {}) },
+    });
+}
+export function sequencesTestSendCommand(handleAsyncAction) {
+    return new Command("test-send")
+        .description(`Send a test copy of a newsletter (sending-domain) email step to up to ${NEWSLETTER_TEST_MAX_RECIPIENTS} verified addresses of this workspace's members, rendered as delivery renders it with the subject prefixed "[Test]". Costs 0.05 credits per email; 20 test sends per workspace per day. Writes no Sequence activity and is left out of analytics.`)
+        .argument("<sequence>", "Sequence id or slug.")
+        .option("--step <id>", "The email_send step id.")
+        .option("--to <emails>", "Member email addresses, comma-separated.")
+        .option("--sample-lead <json>", "Merge values as a JSON object. Default: the first enrolled lead's values, else each tag's fallback.")
+        .option("--list-recipients", "List the member addresses a test may go to instead of sending.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences test-send", options, () => testSend(sequence, options));
+    });
+}

package/dist/workspace-placement-commands.js

@@ -11,7 +11,8 @@ export function registerWorkspacePlacementCommands(root, handle) {
         .option("--request-id <id>", "Request UUID from preview.").option("--plan <hash>", "Exact preview plan hash.").option("--max-live-sends <n>", "Maximum approved diagnostic emails (1–50).")
         .option("--preview-cursor <id>", "Read the next manifest page using the same input, request ID and rendering time.").option("--preview-limit <n>", "Preview manifest page size (1–20); never use with approval.")
         .option("--preview-probe-id <id>", "Read exact rendered copy for a preview probe; reuse request ID and rendering time.").option("--preview-part <part>", "body_text or body_html.").option("--preview-offset <n>", "Unicode character offset returned by copy preview.").option("--preview-copy-limit <n>", "Copy page size (1–3000 characters).")
-        .option("--allow-paused-probe", "Explicitly allow diagnostic sends from paused senders, preserving pauses.").option("--json", "Print JSON.")
+        .option("--allow-paused-probe", "Explicitly allow diagnostic sends from paused senders, preserving pauses.")
+        .option("--allow-daily-limit-override", "Staff only: approve daily sender/receiver quota exceptions for this exact test, one diagnostic per sender. Preserve mailbox settings.").option("--json", "Print JSON.")
         .action(async (options) => handle("deliverability workspace-test run", options, () => {
         const input = readJsonFileValue(resolve(options.input), "--input");
         if (!input || typeof input !== "object" || Array.isArray(input))
@@ -20,7 +21,7 @@ export function registerWorkspacePlacementCommands(root, handle) {
                 ...(options.approved ? { approved: true } : {}), ...(options.requestId ? { request_id: options.requestId } : {}),
                 ...(options.plan ? { plan_hash: options.plan } : {}), ...(options.renderedAt ? { rendered_at: options.renderedAt } : {}), ...(options.trackingOpens ? { tracking_opens: true } : {}), ...(options.trackingClicks ? { tracking_clicks: true } : {}), ...(options.maxLiveSends ? { max_live_sends: Number(options.maxLiveSends) } : {}),
                 ...(options.receiverEnvironment ? { receiver_environment: options.receiverEnvironment } : {}), ...(options.receiverWorkspace ? { receiver_workspace_id: options.receiverWorkspace } : {}),
-                ...(options.allowPausedProbe ? { allow_paused_probe: true } : {}), ...(options.receiverScope ? { receiver_scope: options.receiverScope } : {}), ...(options.receiverProviders ? { receiver_providers: String(options.receiverProviders).split(",") } : {}),
+                ...(options.allowPausedProbe ? { allow_paused_probe: true } : {}), ...(options.allowDailyLimitOverride ? { allow_daily_limit_override: true } : {}), ...(options.receiverScope ? { receiver_scope: options.receiverScope } : {}), ...(options.receiverProviders ? { receiver_providers: String(options.receiverProviders).split(",") } : {}),
                 ...(options.previewCursor ? { preview_cursor: options.previewCursor } : {}), ...(options.previewLimit !== undefined ? { preview_limit: Number(options.previewLimit) } : {}),
                 ...(options.previewProbeId ? { preview_probe_id: options.previewProbeId } : {}), ...(options.previewPart ? { preview_part: options.previewPart } : {}), ...(options.previewOffset !== undefined ? { preview_offset: Number(options.previewOffset) } : {}), ...(options.previewCopyLimit !== undefined ? { preview_copy_limit: Number(options.previewCopyLimit) } : {}) } });
     })))

package/node_modules/@oxygen/formula/dist/evaluate.js

@@ -1,7 +1,7 @@
 import { OxygenError } from "@oxygen/shared/cli-result";
 import { evaluateNoveltyScore } from "./refactor-internals/novelty-score.js";
 import { CROSS_ROW_FUNCTIONS, parseFormulaExpression, } from "./expression.js";
-import { FORMULA_FUNCTION_REGISTRY, checkFormulaFunctionArity, compareFormulaValues, formulaExpressionError, formulaValuesEqual, readFormulaNumber, toFormulaBoolean, } from "./formula-functions.js";
+import { FORMULA_FUNCTION_REGISTRY, checkFormulaFunctionArity, compareFormulaValues, unsupportedFormulaFunctionError, formulaExpressionError, formulaValuesEqual, readFormulaNumber, toFormulaBoolean, } from "./formula-functions.js";
 export function evaluateFormulaInScope(expression, scope, options = {}) {
     return evaluateFormulaAst(parseFormulaExpression(expression, options), scope);
 }
@@ -37,9 +37,7 @@ function evaluateFormulaAstWithMode(node, scope, resolutionMode) {
             if (spec?.evaluate) {
                 return spec.evaluate(node.args.map(evaluateArgument));
             }
-            throw formulaExpressionError("Unsupported formula function.", {
-                function: node.name,
-            });
+            throw unsupportedFormulaFunctionError(node.name);
         }
     }
 }

package/node_modules/@oxygen/formula/dist/expression.d.ts

@@ -19,11 +19,6 @@ export type FormulaAst = {
     name: string;
     args: FormulaAst[];
 };
-/**
- * Functions evaluated against the whole column rather than the current scope.
- * They are intercepted before registry dispatch (the registry entry carries
- * metadata only) because they need a corpus the scope supplies.
- */
 export declare const CROSS_ROW_FUNCTIONS: ReadonlySet<string>;
 /**
  * How to tokenize. One flag today, and it is deliberately opt-in: a table formula
@@ -62,6 +57,13 @@ export declare function validateFormulaAst(ast: FormulaAst): void;
  * for days with received_length 290 against the old 256 cap.
  */
 export declare function validateFormulaRegexLiterals(ast: FormulaAst): void;
+/**
+ * SAVE-TIME ONLY, like validateFormulaRegexLiterals: refuse `||` next to a text
+ * literal. `||` is logical or here, so SQL's `first_name || ' ' || last_name`
+ * parses and stores, then fills every row with `true`. Stored columns keep
+ * reading; only a new write is refused, with the concat form to use instead.
+ */
+export declare function validateFormulaTextJoin(expression: string): void;
 /** Validate syntax, supported functions, and arity without evaluating any data. */
 export declare function validateFormulaExpression(expression: string, options?: ParseOptions): void;
 export declare function walkExpression(node: FormulaAst, visit: (node: FormulaAst) => void): void;

package/node_modules/@oxygen/formula/dist/expression.js

@@ -1,9 +1,11 @@
-import { FORMULA_FUNCTION_REGISTRY, MAX_FORMULA_REGEX_PATTERN_LENGTH, checkFormulaFunctionArity, formulaExpressionError, } from "./formula-functions.js";
+import { FORMULA_FUNCTION_REGISTRY, MAX_FORMULA_REGEX_PATTERN_LENGTH, checkFormulaFunctionArity, formulaExpressionError, unsupportedFormulaFunctionError, } from "./formula-functions.js";
 /**
  * Functions evaluated against the whole column rather than the current scope.
  * They are intercepted before registry dispatch (the registry entry carries
  * metadata only) because they need a corpus the scope supplies.
  */
+/** SQL an author pasted: `case when`, `cast(x as type)` or `x::type`. */
+const SQL_SYNTAX_PATTERN = /\bcase\s+when\b|\bcast\s*\([^)]*\bas\b|::/i;
 export const CROSS_ROW_FUNCTIONS = new Set(["novelty_score"]);
 export function parseFormulaExpression(expression, options = {}) {
     const parser = new FormulaParser(tokenize(expression, options), expression);
@@ -30,9 +32,7 @@ export function validateFormulaAst(ast) {
         }
         const spec = FORMULA_FUNCTION_REGISTRY.get(normalized);
         if (!spec) {
-            throw formulaExpressionError("Unsupported formula function.", {
-                function: node.name,
-            });
+            throw unsupportedFormulaFunctionError(node.name);
         }
         checkFormulaFunctionArity(spec, node.args.length);
     });
@@ -78,6 +78,22 @@ export function validateFormulaRegexLiterals(ast) {
         });
     });
 }
+/**
+ * SAVE-TIME ONLY, like validateFormulaRegexLiterals: refuse `||` next to a text
+ * literal. `||` is logical or here, so SQL's `first_name || ' ' || last_name`
+ * parses and stores, then fills every row with `true`. Stored columns keep
+ * reading; only a new write is refused, with the concat form to use instead.
+ */
+export function validateFormulaTextJoin(expression) {
+    const tokens = tokenize(expression);
+    tokens.forEach((token, index) => {
+        if (token.type !== "operator" || token.value !== "||")
+            return;
+        if (tokens[index - 1]?.type !== "string" && tokens[index + 1]?.type !== "string")
+            return;
+        throw formulaExpressionError("|| is logical or in formulas, not text joining; join text with concat(first_name, \" \", last_name).", { position: token.position, expression, hint: "Use concat(a, b, ...) to join text; || and or compare truth values." });
+    });
+}
 /** Validate syntax, supported functions, and arity without evaluating any data. */
 export function validateFormulaExpression(expression, options = {}) {
     validateFormulaAst(parseFormulaExpression(expression, options));
@@ -310,6 +326,9 @@ class FormulaParser {
         return formulaExpressionError(message, {
             position: token.position,
             expression: this.expression,
+            ...(SQL_SYNTAX_PATTERN.test(this.expression)
+                ? { hint: "SQL CASE/CAST is not formula syntax: use if(condition, then, else), switch(value, case1, result1, ..., default) and number(value)." }
+                : {}),
         });
     }
 }
@@ -423,6 +442,9 @@ function tokenize(expression, options = {}) {
             position: index,
             character: char,
             expression,
+            ...(char === "[" || char === "]"
+                ? { hint: "Formulas have no [index] access: use first(list), last(list), path(value, \"0\") or email_domain(email)." }
+                : {}),
         });
     }
     tokens.push({ type: "eof", position: expression.length });

package/node_modules/@oxygen/formula/dist/formula-functions.d.ts

@@ -50,6 +50,12 @@ export declare function readFormulaJsonPath(value: unknown, rawPath: string): un
 export declare function checkFormulaFunctionArity(spec: FormulaFunctionMeta, received: number): void;
 export declare const FORMULA_DATE_UNITS: readonly ["seconds", "minutes", "hours", "days", "weeks", "months", "years"];
 export declare const FORMULA_FUNCTION_REGISTRY: ReadonlyMap<string, FormulaFunctionSpec>;
+/**
+ * The refusal for a call to a function the formula language does not have:
+ * the likely intended function (`did_you_mean`) and every supported name, so the
+ * author corrects the call without another lookup.
+ */
+export declare function unsupportedFormulaFunctionError(name: string): OxygenError;
 export declare const FORMULA_FUNCTION_CATEGORIES: readonly FormulaFunctionCategory[];
 export declare function listFormulaFunctions(category?: FormulaFunctionCategory): FormulaFunctionMeta[];
 /** Operators the expression language supports, for the discovery surfaces. */