@oxygen-agent/cli 1.1014.1696 → 1.1014.1763

package/node_modules/@oxygen/shared/dist/email-html-sanitize.js

@@ -0,0 +1,96 @@
+/**
+ * Clean raw HTML a customer saves as an email document. Email clients never run
+ * scripts, but the same HTML is previewed in the web app and forwarded by
+ * recipients, so active content is removed on save rather than trusted to every
+ * reader: `<script>` (and other embedding elements), inline `on*` event
+ * handlers, and `javascript:` / `vbscript:` / `data:text/html` URLs in link and
+ * source attributes. Styles, tables, images and merge tags are kept as written.
+ *
+ * Browser-safe and dependency-free. This is a save-time cleanup, not the
+ * preview boundary: the web preview still renders inside a sandboxed iframe.
+ */
+const ACTIVE_ELEMENTS = ["script", "iframe", "object", "embed", "applet", "frame", "frameset", "base"];
+const URL_ATTRIBUTES = ["href", "src", "action", "formaction", "background", "poster", "xlink:href", "srcset", "lowsrc", "dynsrc"];
+/** Decode the entity tricks used to hide a scheme (`&#106;avascript:`, `java&#x09;script:`). */
+function decodeForSchemeCheck(value) {
+    return value
+        .replace(/&#x([0-9a-f]+);?/gi, (_, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+        .replace(/&#(\d+);?/g, (_, dec) => String.fromCharCode(Number.parseInt(dec, 10)))
+        .replace(/&(tab|newline);/gi, "")
+        .replace(/&colon;/gi, ":")
+        // Browsers ignore control characters and whitespace inside a scheme.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000- \u007f-\u009f]+/g, "")
+        .toLowerCase();
+}
+export function isUnsafeEmailUrl(value) {
+    const decoded = decodeForSchemeCheck(value);
+    return decoded.startsWith("javascript:") || decoded.startsWith("vbscript:") || decoded.startsWith("data:text/html")
+        || decoded.startsWith("data:application/xhtml") || decoded.startsWith("data:image/svg+xml");
+}
+// One attribute: a name, then an optional value. `/` separates attributes the way
+// browsers read `<img/onerror=...>`.
+const ATTRIBUTE = /([^\s"'>\/=]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'>]+))?/g;
+function unquote(value) {
+    return (value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")) ? value.slice(1, -1) : value;
+}
+/** The cleaned attribute string, or null when nothing in it needed cleaning. */
+function rewriteAttributes(attrs, removed) {
+    let changed = false;
+    const kept = [];
+    for (const match of attrs.matchAll(ATTRIBUTE)) {
+        const name = match[1] ?? "";
+        const lower = name.toLowerCase();
+        let value = match[2];
+        if (lower.startsWith("on")) {
+            removed.handlers += 1;
+            changed = true;
+            continue;
+        }
+        if (value !== undefined && URL_ATTRIBUTES.includes(lower) && isUnsafeEmailUrl(unquote(value))) {
+            removed.urls += 1;
+            changed = true;
+            value = '"#"';
+        }
+        else if (value !== undefined && lower === "style") {
+            // A style URL can carry the same schemes (`background:url(javascript:...)`).
+            const cleaned = value.replace(/url\(\s*(["']?)([^"')]*)\1\s*\)/gi, (whole, _q, url) => {
+                if (!isUnsafeEmailUrl(url))
+                    return whole;
+                removed.urls += 1;
+                changed = true;
+                return "none";
+            });
+            value = cleaned;
+        }
+        kept.push(value === undefined ? name : `${name}=${value}`);
+    }
+    if (!changed)
+        return null;
+    const selfClosing = /\/\s*$/.test(attrs);
+    return `${kept.length > 0 ? ` ${kept.join(" ")}` : ""}${selfClosing ? " /" : ""}`;
+}
+export function sanitizeEmailHtml(input) {
+    const removed = { elements: 0, handlers: 0, urls: 0 };
+    let html = input;
+    for (const element of ACTIVE_ELEMENTS) {
+        const paired = new RegExp(`<${element}\\b[^>]*>[\\s\\S]*?<\\/${element}\\s*>`, "gi");
+        const single = new RegExp(`<\\/?${element}\\b[^>]*>`, "gi");
+        html = html.replace(paired, () => {
+            removed.elements += 1;
+            return "";
+        });
+        html = html.replace(single, () => {
+            removed.elements += 1;
+            return "";
+        });
+    }
+    // Attributes are rewritten only inside tags (quoted values may hold `>`), so prose
+    // that mentions "onclick=" survives and an untouched tag keeps its exact bytes.
+    html = html.replace(/<([a-z][a-z0-9:-]*)((?:"[^"]*"|'[^']*'|[^'">])*)>/gi, (match, tag, attrs) => {
+        const rewritten = rewriteAttributes(attrs, removed);
+        return rewritten === null ? match : `<${tag}${rewritten}>`;
+    });
+    const sanitized = removed.elements + removed.handlers + removed.urls > 0;
+    return { html, removed, sanitized };
+}

package/node_modules/@oxygen/shared/dist/email-subscriptions.d.ts

@@ -8,8 +8,26 @@
  * Sequences only send to `subscribed` addresses on their own list, on top of
  * do-not-contact. Pure and browser-safe.
  */
-export declare const EMAIL_SUBSCRIPTION_LIST_KINDS: readonly ["marketing", "product_updates", "onboarding"];
+export declare const EMAIL_SUBSCRIPTION_LIST_KINDS: readonly ["marketing", "product_updates", "onboarding", "topic"];
 export type EmailSubscriptionListKind = typeof EMAIL_SUBSCRIPTION_LIST_KINDS[number];
+/**
+ * Topics: a `topic` list is a narrower subject inside an audience list
+ * (`parent_list_id`). A newsletter on a topic mails only the topic's
+ * subscribers. `opt_out` topics are joined together with their audience list
+ * (the same consent evidence, source `topic_default`); `opt_in` topics only by
+ * an explicit choice. Public lists show on the recipient's preference page;
+ * private ones only to someone already subscribed to them.
+ */
+export declare const EMAIL_SUBSCRIPTION_LIST_VISIBILITIES: readonly ["public", "private"];
+export type EmailSubscriptionListVisibility = typeof EMAIL_SUBSCRIPTION_LIST_VISIBILITIES[number];
+export declare const EMAIL_SUBSCRIPTION_DEFAULTS: readonly ["opt_in", "opt_out"];
+export type EmailSubscriptionDefault = typeof EMAIL_SUBSCRIPTION_DEFAULTS[number];
+/** The consent source of a topic subscription made by joining its audience list. */
+export declare const TOPIC_DEFAULT_SOURCE = "topic_default";
+/** The consent source of a change the recipient made on the hosted preference page. */
+export declare const PREFERENCE_CENTER_SOURCE = "preference_center";
+export declare function isEmailSubscriptionListVisibility(value: unknown): value is EmailSubscriptionListVisibility;
+export declare function isEmailSubscriptionDefault(value: unknown): value is EmailSubscriptionDefault;
 export declare const EMAIL_SUBSCRIPTION_STATUSES: readonly ["subscribed", "unsubscribed", "pending", "cleaned"];
 export type EmailSubscriptionStatus = typeof EMAIL_SUBSCRIPTION_STATUSES[number];
 /** Append-only consent event kinds. Status changes plus the provider facts that cause them. */
@@ -48,3 +66,47 @@ export type EmailConsentEvidence = {
 export declare function parseEmailConsentEvidence(value: unknown, options: {
     requireForSubscribe: boolean;
 }): EmailConsentEvidence;
+/**
+ * Contacts of a list: one subscription read together with the Records person it
+ * names (`email_subscriptions.person_id`, a People record). Records owns the
+ * person (name and the workspace's own People fields, the contact
+ * "properties"); the list owns status and consent.
+ */
+export declare const EMAIL_CONTACT_PROPERTY_TYPES: readonly ["string", "number"];
+export type EmailContactPropertyType = typeof EMAIL_CONTACT_PROPERTY_TYPES[number];
+/** Most contacts one list page returns. */
+export declare const EMAIL_CONTACTS_PAGE_LIMIT = 200;
+/**
+ * Most import entries per call that carry a name or properties: each one is a
+ * Records write (create or match the person by email), so these batches are
+ * smaller than an address-only import. The CLI and web split larger files.
+ */
+export declare const EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT = 1000;
+export declare function isEmailContactPropertyType(value: unknown): value is EmailContactPropertyType;
+/** One contact an import sends: the address, and what goes to its People record. */
+export type EmailContactImportRow = {
+    email: string;
+    person_id?: string;
+    first_name?: string;
+    last_name?: string;
+    properties?: Record<string, string>;
+};
+/** Parse CSV text into rows of cells, honouring quoted fields ("" escapes, commas and newlines inside quotes). */
+export declare function parseCsvCells(text: string): string[][];
+/**
+ * Contacts from a CSV with an email column (the shape `subscriptions export`
+ * writes): first_name and last_name go to the person, every other non-reserved
+ * column is a candidate property, named in `propertyColumns` so a caller can
+ * keep only the workspace's real properties.
+ */
+export declare function parseContactsCsv(text: string): {
+    entries: EmailContactImportRow[];
+    propertyColumns: string[];
+};
+/** Keep only properties the workspace has; report the columns dropped. */
+export declare function keepContactProperties(entries: EmailContactImportRow[], known: ReadonlySet<string>): {
+    entries: EmailContactImportRow[];
+    ignored: string[];
+};
+/** Split an import into calls the import route accepts (smaller batches once any entry carries a name or properties). */
+export declare function chunkContactImport<T extends EmailContactImportRow>(entries: T[]): T[][];

package/node_modules/@oxygen/shared/dist/email-subscriptions.js

@@ -8,7 +8,27 @@
  * Sequences only send to `subscribed` addresses on their own list, on top of
  * do-not-contact. Pure and browser-safe.
  */
-export const EMAIL_SUBSCRIPTION_LIST_KINDS = ["marketing", "product_updates", "onboarding"];
+export const EMAIL_SUBSCRIPTION_LIST_KINDS = ["marketing", "product_updates", "onboarding", "topic"];
+/**
+ * Topics: a `topic` list is a narrower subject inside an audience list
+ * (`parent_list_id`). A newsletter on a topic mails only the topic's
+ * subscribers. `opt_out` topics are joined together with their audience list
+ * (the same consent evidence, source `topic_default`); `opt_in` topics only by
+ * an explicit choice. Public lists show on the recipient's preference page;
+ * private ones only to someone already subscribed to them.
+ */
+export const EMAIL_SUBSCRIPTION_LIST_VISIBILITIES = ["public", "private"];
+export const EMAIL_SUBSCRIPTION_DEFAULTS = ["opt_in", "opt_out"];
+/** The consent source of a topic subscription made by joining its audience list. */
+export const TOPIC_DEFAULT_SOURCE = "topic_default";
+/** The consent source of a change the recipient made on the hosted preference page. */
+export const PREFERENCE_CENTER_SOURCE = "preference_center";
+export function isEmailSubscriptionListVisibility(value) {
+    return typeof value === "string" && EMAIL_SUBSCRIPTION_LIST_VISIBILITIES.includes(value);
+}
+export function isEmailSubscriptionDefault(value) {
+    return typeof value === "string" && EMAIL_SUBSCRIPTION_DEFAULTS.includes(value);
+}
 export const EMAIL_SUBSCRIPTION_STATUSES = ["subscribed", "unsubscribed", "pending", "cleaned"];
 /** Append-only consent event kinds. Status changes plus the provider facts that cause them. */
 export const EMAIL_SUBSCRIPTION_EVENT_TYPES = [
@@ -78,3 +98,131 @@ export function parseEmailConsentEvidence(value, options) {
     }
     return evidence;
 }
+/**
+ * Contacts of a list: one subscription read together with the Records person it
+ * names (`email_subscriptions.person_id`, a People record). Records owns the
+ * person (name and the workspace's own People fields, the contact
+ * "properties"); the list owns status and consent.
+ */
+export const EMAIL_CONTACT_PROPERTY_TYPES = ["string", "number"];
+/** Most contacts one list page returns. */
+export const EMAIL_CONTACTS_PAGE_LIMIT = 200;
+/**
+ * Most import entries per call that carry a name or properties: each one is a
+ * Records write (create or match the person by email), so these batches are
+ * smaller than an address-only import. The CLI and web split larger files.
+ */
+export const EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT = 1000;
+export function isEmailContactPropertyType(value) {
+    return typeof value === "string" && EMAIL_CONTACT_PROPERTY_TYPES.includes(value);
+}
+/** Header names an import reads as the contact itself (or as export bookkeeping), never as a property. */
+const CONTACT_CSV_RESERVED = new Set([
+    "email", "email_address", "e-mail", "person_id", "first_name", "last_name", "full_name",
+    "status", "source", "subscribed_at", "unsubscribed_at", "consent_at", "consent_source", "consent_basis",
+    "consent_notice_version", "consent_form_url",
+]);
+/** Parse CSV text into rows of cells, honouring quoted fields ("" escapes, commas and newlines inside quotes). */
+export function parseCsvCells(text) {
+    const rows = [];
+    let row = [];
+    let cell = "";
+    let quoted = false;
+    const input = text.replace(/^/, "");
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input[index];
+        if (quoted) {
+            if (char === "\"" && input[index + 1] === "\"") {
+                cell += "\"";
+                index += 1;
+            }
+            else if (char === "\"")
+                quoted = false;
+            else
+                cell += char;
+        }
+        else if (char === "\"")
+            quoted = true;
+        else if (char === ",") {
+            row.push(cell.trim());
+            cell = "";
+        }
+        else if (char === "\n" || char === "\r") {
+            if (char === "\r" && input[index + 1] === "\n")
+                index += 1;
+            row.push(cell.trim());
+            cell = "";
+            if (row.some((value) => value !== ""))
+                rows.push(row);
+            row = [];
+        }
+        else
+            cell += char;
+    }
+    row.push(cell.trim());
+    if (row.some((value) => value !== ""))
+        rows.push(row);
+    return rows;
+}
+/**
+ * Contacts from a CSV with an email column (the shape `subscriptions export`
+ * writes): first_name and last_name go to the person, every other non-reserved
+ * column is a candidate property, named in `propertyColumns` so a caller can
+ * keep only the workspace's real properties.
+ */
+export function parseContactsCsv(text) {
+    const [headerRow = [], ...body] = parseCsvCells(text);
+    const header = headerRow.map((cell) => cell.toLowerCase());
+    const emailIndex = header.findIndex((cell) => cell === "email" || cell === "email_address" || cell === "e-mail");
+    if (emailIndex < 0) {
+        throw new EmailSubscriptionInputError("invalid_request", "file", "The CSV needs an email column in its header row.");
+    }
+    const at = (name) => header.indexOf(name);
+    const personIndex = at("person_id");
+    const firstIndex = at("first_name");
+    const lastIndex = at("last_name");
+    const propertyColumns = header.flatMap((cell, index) => (cell && !CONTACT_CSV_RESERVED.has(cell) ? [{ key: cell, index }] : []));
+    const entries = body.map((cells) => {
+        const properties = Object.fromEntries(propertyColumns.flatMap(({ key, index }) => (cells[index] ? [[key, cells[index]]] : [])));
+        const read = (index) => (index >= 0 && cells[index] ? cells[index] : undefined);
+        const personId = read(personIndex);
+        const firstName = read(firstIndex);
+        const lastName = read(lastIndex);
+        return {
+            email: cells[emailIndex] ?? "",
+            ...(personId ? { person_id: personId } : {}),
+            ...(firstName ? { first_name: firstName } : {}),
+            ...(lastName ? { last_name: lastName } : {}),
+            ...(Object.keys(properties).length > 0 ? { properties } : {}),
+        };
+    });
+    return { entries, propertyColumns: propertyColumns.map((column) => column.key) };
+}
+/** Keep only properties the workspace has; report the columns dropped. */
+export function keepContactProperties(entries, known) {
+    const columns = new Set(entries.flatMap((entry) => Object.keys(entry.properties ?? {})));
+    const ignored = [...columns].filter((column) => !known.has(column)).sort();
+    if (ignored.length === 0)
+        return { entries, ignored };
+    return {
+        ignored,
+        entries: entries.map((entry) => {
+            if (!entry.properties)
+                return entry;
+            const { properties, ...rest } = entry;
+            const kept = Object.fromEntries(Object.entries(properties).filter(([key]) => known.has(key)));
+            return Object.keys(kept).length > 0 ? { ...rest, properties: kept } : rest;
+        }),
+    };
+}
+function importRowHasFields(entry) {
+    return Boolean(entry.first_name || entry.last_name || (entry.properties && Object.keys(entry.properties).length > 0));
+}
+/** Split an import into calls the import route accepts (smaller batches once any entry carries a name or properties). */
+export function chunkContactImport(entries) {
+    const size = entries.some(importRowHasFields) ? EMAIL_CONTACT_IMPORT_WITH_FIELDS_LIMIT : EMAIL_SUBSCRIPTION_IMPORT_LIMIT;
+    const chunks = [];
+    for (let index = 0; index < entries.length; index += size)
+        chunks.push(entries.slice(index, index + size));
+    return chunks.length > 0 ? chunks : [[]];
+}

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.d.ts

@@ -55,8 +55,11 @@ export type UnsubscribeTokenPayloadV2 = {
     email: string;
     /** Subscription list id the recipient leaves. */
     lst: string;
-    /** `list` leaves only `lst`; `all` leaves every list and suppresses the address. */
-    scope: "list" | "all";
+    /**
+     * `list` leaves only `lst`; `all` leaves every list and suppresses the
+     * address; `test` (a newsletter test send) changes nothing and says so.
+     */
+    scope: "list" | "all" | "test";
     seq?: string;
     enr?: string;
     /** Sending-domain account id, for provenance. */
@@ -71,6 +74,42 @@ export declare function signUnsubscribeTokenV2(payload: UnsubscribeTokenPayloadV
  * v1 callers keep `verifyUnsubscribeToken`, whose contract is unchanged.
  */
 export declare function verifyAnyUnsubscribeToken(token: string, secret: string): AnyUnsubscribeTokenPayload | null;
+/**
+ * v2 `preferences`: the link to the hosted preference page of bulk mail
+ * (`{{preferences_url}}`). Same wire format and secret as the unsubscribe
+ * tokens, but a separate scope that `verifyAnyUnsubscribeToken` refuses, so a
+ * preferences link can never perform a one-click unsubscribe. `test` marks the
+ * link of a newsletter test send: the page says so and changes nothing.
+ */
+export type PreferencesTokenPayload = {
+    v: 2;
+    org: string;
+    email: string;
+    /** The list the email was sent from; the page shows every list the address may manage. */
+    lst: string;
+    scope: "preferences";
+    test?: true;
+    seq?: string;
+    sd?: string;
+    iat: number;
+};
+/** A preferences link stops opening the page a year after the email that carried it. */
+export declare const PREFERENCES_TOKEN_MAX_AGE_MS: number;
+export declare function signPreferencesToken(payload: PreferencesTokenPayload, secret: string): string;
+/**
+ * Verify a preferences token: signature, shape and age. Returns null for any
+ * problem, including an unsubscribe token (wrong scope) and a link older than
+ * PREFERENCES_TOKEN_MAX_AGE_MS; `expired` tells the page which copy to show.
+ */
+export declare function verifyPreferencesToken(token: string, secret: string, nowMs?: number): {
+    payload: PreferencesTokenPayload;
+    expired: false;
+} | {
+    payload: null;
+    expired: boolean;
+};
+/** The hosted preference page: org id in the path (re-checked against the token), token in `token`. */
+export declare function buildPreferencesUrl(orgId: string, token: string, baseUrl: string): string;
 /**
  * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
  * path treats null as "omit the header" (a send with no one-click link still

package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.js

@@ -72,7 +72,7 @@ function parseTokenPayloadV2(body) {
     const lst = typeof candidate.lst === "string" ? candidate.lst.trim() : "";
     if (!org || !email || !email.includes("@") || !lst)
         return null;
-    if (candidate.scope !== "list" && candidate.scope !== "all")
+    if (candidate.scope !== "list" && candidate.scope !== "all" && candidate.scope !== "test")
         return null;
     return {
         v: 2,
@@ -96,6 +96,55 @@ export function verifyAnyUnsubscribeToken(token, secret) {
         return null;
     return parseTokenPayload(body) ?? parseTokenPayloadV2(body);
 }
+/** A preferences link stops opening the page a year after the email that carried it. */
+export const PREFERENCES_TOKEN_MAX_AGE_MS = 365 * 24 * 60 * 60 * 1000;
+export function signPreferencesToken(payload, secret) {
+    const normalized = { ...payload, email: payload.email.trim().toLowerCase() };
+    return signPayload(normalized, secret);
+}
+/**
+ * Verify a preferences token: signature, shape and age. Returns null for any
+ * problem, including an unsubscribe token (wrong scope) and a link older than
+ * PREFERENCES_TOKEN_MAX_AGE_MS; `expired` tells the page which copy to show.
+ */
+export function verifyPreferencesToken(token, secret, nowMs = Date.now()) {
+    const body = splitAndVerifyToken(token, secret);
+    if (body === null)
+        return { payload: null, expired: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    }
+    catch {
+        return { payload: null, expired: false };
+    }
+    if (!parsed || typeof parsed !== "object")
+        return { payload: null, expired: false };
+    const candidate = parsed;
+    const org = typeof candidate.org === "string" ? candidate.org.trim() : "";
+    const email = typeof candidate.email === "string" ? candidate.email.trim().toLowerCase() : "";
+    const lst = typeof candidate.lst === "string" ? candidate.lst.trim() : "";
+    if (candidate.v !== 2 || candidate.scope !== "preferences" || !org || !email.includes("@") || !lst) {
+        return { payload: null, expired: false };
+    }
+    const iat = typeof candidate.iat === "number" && Number.isFinite(candidate.iat) ? candidate.iat : 0;
+    if (nowMs - iat > PREFERENCES_TOKEN_MAX_AGE_MS)
+        return { payload: null, expired: true };
+    return {
+        expired: false,
+        payload: {
+            v: 2, org, email, lst, scope: "preferences",
+            ...(candidate.test === true ? { test: true } : {}),
+            ...(typeof candidate.seq === "string" && candidate.seq ? { seq: candidate.seq } : {}),
+            ...(typeof candidate.sd === "string" && candidate.sd ? { sd: candidate.sd } : {}),
+            iat,
+        },
+    };
+}
+/** The hosted preference page: org id in the path (re-checked against the token), token in `token`. */
+export function buildPreferencesUrl(orgId, token, baseUrl) {
+    return `${baseUrl}/email/preferences/${encodeURIComponent(orgId)}?token=${token}`;
+}
 /**
  * The HMAC signing secret for unsubscribe tokens, or null when unset. The send
  * path treats null as "omit the header" (a send with no one-click link still

package/node_modules/@oxygen/shared/dist/newsletter-analytics.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Newsletter analytics: what one sending-domain Sequence's bulk mail did, read
+ * from its SES ledger (`ox_runs.bulk_email_send_jobs` + `ox_sequencer.bulk_email_events`).
+ *
+ * Opens are estimates: Apple Mail Privacy Protection and corporate link scanners
+ * fetch the tracking pixel and links for the recipient, so every surface labels
+ * opens "estimated", and events SES flags as bots are never counted. Rates are
+ * fractions (0..1) over delivered mail, except the bounce rate, which is over
+ * sent mail (a bounced message was never delivered); null when the denominator is 0.
+ *
+ * Pure and browser-safe: the route, the web panel, the CLI and MCP share it.
+ */
+/** A recipient's furthest outcome, most significant first when several apply. */
+export declare const NEWSLETTER_RECIPIENT_STATUSES: readonly ["queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed", "failed"];
+export type NewsletterRecipientStatus = typeof NEWSLETTER_RECIPIENT_STATUSES[number];
+export declare const NEWSLETTER_TIMELINE_INTERVALS: readonly ["hour", "day"];
+export type NewsletterTimelineInterval = typeof NEWSLETTER_TIMELINE_INTERVALS[number];
+/** The timeline covers the first seven days after the first send. */
+export declare const NEWSLETTER_TIMELINE_DAYS = 7;
+export declare const NEWSLETTER_RECIPIENTS_MAX_LIMIT = 200;
+export declare const NEWSLETTER_RECIPIENTS_DEFAULT_LIMIT = 50;
+export declare const NEWSLETTER_LINKS_LIMIT = 50;
+export type NewsletterLinkStats = {
+    link: string;
+    unique_clicks: number;
+    total_clicks: number;
+};
+export type NewsletterTimelineBucket = {
+    at: string;
+    delivered: number;
+    /** Recipients whose first (non-bot) open fell in this bucket. */
+    opened: number;
+    /** Recipients whose first (non-bot) click fell in this bucket. */
+    clicked: number;
+};
+export type NewsletterAnalytics = {
+    recipients_targeted: number;
+    sent: number;
+    delivered: number;
+    opens: {
+        unique: number;
+        total: number;
+        estimated: true;
+    };
+    clicks: {
+        unique: number;
+        total: number;
+    };
+    bounces: {
+        hard: number;
+        soft: number;
+    };
+    complaints: number;
+    unsubscribes: number;
+    suppressed: number;
+    rates: {
+        open_rate: number | null;
+        click_rate: number | null;
+        bounce_rate: number | null;
+        complaint_rate: number | null;
+        unsubscribe_rate: number | null;
+    };
+    links: NewsletterLinkStats[];
+    timeline: {
+        interval: NewsletterTimelineInterval;
+        start: string | null;
+        buckets: NewsletterTimelineBucket[];
+    };
+    first_sent_at: string | null;
+    last_event_at: string | null;
+};
+export type NewsletterRecipient = {
+    email: string;
+    status: NewsletterRecipientStatus;
+    enrollment_id: string;
+    sent_at: string | null;
+    opens: number;
+    clicks: number;
+    last_event_at: string | null;
+};
+export type NewsletterRecipientsPage = {
+    recipients: NewsletterRecipient[];
+    status: NewsletterRecipientStatus | null;
+    total: number;
+    limit: number;
+    offset: number;
+    next_offset: number | null;
+};
+export declare function isNewsletterRecipientStatus(value: unknown): value is NewsletterRecipientStatus;
+export declare function isNewsletterTimelineInterval(value: unknown): value is NewsletterTimelineInterval;

package/node_modules/@oxygen/shared/dist/newsletter-analytics.js

@@ -0,0 +1,28 @@
+/**
+ * Newsletter analytics: what one sending-domain Sequence's bulk mail did, read
+ * from its SES ledger (`ox_runs.bulk_email_send_jobs` + `ox_sequencer.bulk_email_events`).
+ *
+ * Opens are estimates: Apple Mail Privacy Protection and corporate link scanners
+ * fetch the tracking pixel and links for the recipient, so every surface labels
+ * opens "estimated", and events SES flags as bots are never counted. Rates are
+ * fractions (0..1) over delivered mail, except the bounce rate, which is over
+ * sent mail (a bounced message was never delivered); null when the denominator is 0.
+ *
+ * Pure and browser-safe: the route, the web panel, the CLI and MCP share it.
+ */
+/** A recipient's furthest outcome, most significant first when several apply. */
+export const NEWSLETTER_RECIPIENT_STATUSES = [
+    "queued", "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed", "suppressed", "failed",
+];
+export const NEWSLETTER_TIMELINE_INTERVALS = ["hour", "day"];
+/** The timeline covers the first seven days after the first send. */
+export const NEWSLETTER_TIMELINE_DAYS = 7;
+export const NEWSLETTER_RECIPIENTS_MAX_LIMIT = 200;
+export const NEWSLETTER_RECIPIENTS_DEFAULT_LIMIT = 50;
+export const NEWSLETTER_LINKS_LIMIT = 50;
+export function isNewsletterRecipientStatus(value) {
+    return typeof value === "string" && NEWSLETTER_RECIPIENT_STATUSES.includes(value);
+}
+export function isNewsletterTimelineInterval(value) {
+    return typeof value === "string" && NEWSLETTER_TIMELINE_INTERVALS.includes(value);
+}

package/node_modules/@oxygen/shared/dist/newsletter-test-send.d.ts

@@ -0,0 +1,20 @@
+import { CliHttpError } from "./cli-http-error.js";
+export declare const NEWSLETTER_TEST_MAX_RECIPIENTS = 5;
+/** Test sends (requests, not emails) a workspace may make per day. */
+export declare const NEWSLETTER_TEST_DAILY_LIMIT = 20;
+export declare const NEWSLETTER_TEST_SUBJECT_PREFIX = "[Test] ";
+/** SES message tag every test email carries; event apply and workspace health skip it. */
+export declare const NEWSLETTER_TEST_SES_TAG = "oxygen_test";
+export declare const NEWSLETTER_TEST_FAULT_CODES: {
+    readonly recipientNotMember: "test_send_recipient_not_member";
+    readonly notNewsletter: "test_send_not_newsletter";
+    readonly unavailable: "test_send_unavailable";
+    readonly failed: "test_send_failed";
+};
+export declare function testSendRecipientNotMemberError(recipients: readonly string[]): CliHttpError;
+export declare function testSendNotNewsletterError(): CliHttpError;
+export declare function testSendUnavailableError(): CliHttpError;
+export declare function testSendFailedError(recipients: ReadonlyArray<{
+    email: string;
+    status: string;
+}>): CliHttpError;

package/node_modules/@oxygen/shared/dist/newsletter-test-send.js

@@ -0,0 +1,46 @@
+import { CliHttpError } from "./cli-http-error.js";
+// A newsletter test send: one email step rendered as delivery renders it, sent
+// to at most five verified addresses of the workspace's own members. Web, CLI
+// and MCP share these limits and refusals (ADR 0023: fixed copy, a machine code
+// and a next step; none names SES or another workspace).
+export const NEWSLETTER_TEST_MAX_RECIPIENTS = 5;
+/** Test sends (requests, not emails) a workspace may make per day. */
+export const NEWSLETTER_TEST_DAILY_LIMIT = 20;
+export const NEWSLETTER_TEST_SUBJECT_PREFIX = "[Test] ";
+/** SES message tag every test email carries; event apply and workspace health skip it. */
+export const NEWSLETTER_TEST_SES_TAG = "oxygen_test";
+export const NEWSLETTER_TEST_FAULT_CODES = {
+    recipientNotMember: "test_send_recipient_not_member",
+    notNewsletter: "test_send_not_newsletter",
+    unavailable: "test_send_unavailable",
+    failed: "test_send_failed",
+};
+export function testSendRecipientNotMemberError(recipients) {
+    return new CliHttpError(400, NEWSLETTER_TEST_FAULT_CODES.recipientNotMember, "Test emails go only to verified email addresses of this workspace's members.", {
+        details: {
+            field: "to",
+            recipients: [...recipients],
+            retryable: false,
+            next_step: "Send to your own address or a teammate's verified address; list them with `oxygen sequences test-send <sequence> --list-recipients`.",
+        },
+        exitCode: 1,
+    });
+}
+export function testSendNotNewsletterError() {
+    return new CliHttpError(409, NEWSLETTER_TEST_FAULT_CODES.notNewsletter, "Test sends are for Sequences that send through a sending domain.", {
+        details: { retryable: false, next_step: "Choose a sending domain in the Sequence's Sending settings, then send a test." },
+        exitCode: 1,
+    });
+}
+export function testSendUnavailableError() {
+    return new CliHttpError(503, NEWSLETTER_TEST_FAULT_CODES.unavailable, "Test emails can't be sent right now.", {
+        details: { retryable: true, next_step: "Try again in a few minutes." },
+        exitCode: 1,
+    });
+}
+export function testSendFailedError(recipients) {
+    return new CliHttpError(502, NEWSLETTER_TEST_FAULT_CODES.failed, "The test email could not be sent.", {
+        details: { recipients: [...recipients], retryable: true, next_step: "Check the sending domain is active, then try again." },
+        exitCode: 1,
+    });
+}

package/node_modules/@oxygen/shared/dist/object-storage.d.ts

@@ -103,11 +103,22 @@ export declare function readCopilotAttachmentObject(input: {
     contentType: string | null;
     truncated: boolean;
 }>;
+/** Authenticated callers retain authorization; never mint a transferable GET URL. */
+export declare function openCopilotAttachmentObject(input: {
+    storageKey: string;
+    etag: string;
+    window?: {
+        offset: number;
+        limit: number;
+    };
+    signal?: AbortSignal;
+}): Promise<ReadableStream<Uint8Array>>;
 export declare function getCopilotAttachmentObjectMetadata(input: {
     storageKey: string;
 }): Promise<{
     contentLength: number | null;
     contentType: string | null;
+    etag: string | null;
 }>;
 /**
  * Read the LEADING BYTES of a staged import back out of the bucket.