@oxygen-agent/cli 1.1014.1600 → 1.1014.1763

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/native-chat.d.ts

@@ -57,6 +57,7 @@ export type ChatMessage = {
         id: string | null;
         name: string;
         kind: "customer" | "staff" | "agent" | "system";
+        image_url?: string | null;
     };
     visibility: "public" | "internal";
     source: "web" | "cli" | "mcp";
@@ -78,6 +79,7 @@ export type ChatChannel = {
     id: string;
     organization_id: string;
     name: string;
+    icon_url?: string | null;
     updated_at: string;
     unread_count: number;
     open_count: number;
@@ -89,6 +91,7 @@ export type ChatMember = {
     id: string;
     name: string;
     email: string | null;
+    image_url?: string | null;
 };
 export type ChatChannelView = {
     channel: ChatChannel;
@@ -96,6 +99,10 @@ export type ChatChannelView = {
     members: ChatMember[];
     cursor: string;
 };
+export type ChatThreadsView = Omit<ChatChannelView, "channel"> & {
+    initialized: boolean;
+    channel: ChatChannel | null;
+};
 export type ChatThreadView = {
     thread: ChatThread;
     messages: ChatMessage[];
@@ -122,3 +129,5 @@ export type ChatThreadPatch = {
         required_roles?: string[];
     };
 };
+/** Display-only URLs; never fetch these server-side or expose credential-bearing URLs. */
+export declare function nativeChatImageUrl(value: unknown): string | null;

package/node_modules/@oxygen/shared/dist/native-chat.js

@@ -1 +1,12 @@
-export {};
+/** Display-only URLs; never fetch these server-side or expose credential-bearing URLs. */
+export function nativeChatImageUrl(value) {
+    if (typeof value !== "string" || value.length > 2_048)
+        return null;
+    try {
+        const url = new URL(value.trim());
+        return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}

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.

package/node_modules/@oxygen/shared/dist/object-storage.js

@@ -252,10 +252,22 @@ export async function readCopilotAttachmentObject(input) {
         truncated,
     };
 }
+/** Authenticated callers retain authorization; never mint a transferable GET URL. */
+export async function openCopilotAttachmentObject(input) {
+    const { client, config } = resolveClient();
+    const result = await client.send(new GetObjectCommand({
+        Bucket: config.bucket, Key: input.storageKey, IfMatch: input.etag,
+        ...(input.window ? { Range: `bytes=${input.window.offset}-${input.window.offset + input.window.limit - 1}` } : {}),
+    }), input.signal ? { abortSignal: input.signal } : {});
+    if (!result.Body)
+        throw new Error("Attachment object had no body.");
+    return result.Body.transformToWebStream();
+}
 export async function getCopilotAttachmentObjectMetadata(input) {
     const { client, config } = resolveClient();
     const result = await client.send(new HeadObjectCommand({ Bucket: config.bucket, Key: input.storageKey }));
     return {
+        etag: result.ETag ?? null,
         contentLength: typeof result.ContentLength === "number" ? result.ContentLength : null,
         contentType: typeof result.ContentType === "string" ? result.ContentType : null,
     };

package/node_modules/@oxygen/shared/dist/onboarding-research.d.ts

@@ -21,8 +21,15 @@ export declare const ONBOARDING_RESEARCH_MODEL: {
     readonly level: "medium";
     readonly reasoningEffort: "low";
 };
-/** Provider credits OXYGEN pays for one workspace's onboarding research, over its lifetime. */
-export declare const ONBOARDING_RESEARCH_MAX_CREDITS = 300;
+/**
+ * Provider credits OXYGEN pays for one workspace's onboarding research, over its
+ * lifetime, restarts included. Raised from 300 (Philipp, 2026-10-21: "we can
+ * increase the limit to make the research really good"): a full run took up to
+ * 121 credits, and the Oxygen Demo Workspace ran out on its eighth start.
+ */
+export declare const ONBOARDING_RESEARCH_MAX_CREDITS = 2000;
+/** What one onboarding run (one funded turn) may spend of it, so a run has room to go deep and a restart has room too. */
+export declare const ONBOARDING_RESEARCH_RUN_MAX_CREDITS = 500;
 /** Ceiling on any one research call; a call that names a higher one is lowered to it. */
 export declare const ONBOARDING_RESEARCH_MAX_CREDITS_PER_CALL = 15;
 /** The onboarding turn's own and its sub-agents' inference, credited back once the turn settles. */

package/node_modules/@oxygen/shared/dist/onboarding-research.js

@@ -18,8 +18,15 @@ export const ONBOARDING_RESEARCH_SUBAGENT = "onboarding_researcher";
  * Reliable calls first, then speed: one place to change once measured.
  */
 export const ONBOARDING_RESEARCH_MODEL = { level: "medium", reasoningEffort: "low" };
-/** Provider credits OXYGEN pays for one workspace's onboarding research, over its lifetime. */
-export const ONBOARDING_RESEARCH_MAX_CREDITS = 300;
+/**
+ * Provider credits OXYGEN pays for one workspace's onboarding research, over its
+ * lifetime, restarts included. Raised from 300 (Philipp, 2026-10-21: "we can
+ * increase the limit to make the research really good"): a full run took up to
+ * 121 credits, and the Oxygen Demo Workspace ran out on its eighth start.
+ */
+export const ONBOARDING_RESEARCH_MAX_CREDITS = 2_000;
+/** What one onboarding run (one funded turn) may spend of it, so a run has room to go deep and a restart has room too. */
+export const ONBOARDING_RESEARCH_RUN_MAX_CREDITS = 500;
 /** Ceiling on any one research call; a call that names a higher one is lowered to it. */
 export const ONBOARDING_RESEARCH_MAX_CREDITS_PER_CALL = 15;
 /** The onboarding turn's own and its sub-agents' inference, credited back once the turn settles. */

package/node_modules/@oxygen/shared/dist/plan-band.d.ts

@@ -94,6 +94,15 @@ export declare function resolveDefaultTriggerRunCreditCeilingForPlan(resolution:
 export declare function resolveDefaultConnectionCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number;
 /** The same default for one standing or webhook table auto-run batch. */
 export declare function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution: PlanSpendResolution, options?: RepricingOptions): number | null;
+/**
+ * PROPOSED defaults, not yet a product decision: newsletter (sending-domain)
+ * emails one workspace may reserve per UTC day. Newsletters are paid-only, so
+ * free is 0. The staff override and the workspace's share of the SES quota
+ * (`bulkEmailWorkspaceDailyAllowance`) can only lower this.
+ */
+export declare const BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND: Readonly<Record<PlanBand, number>>;
+/** The largest plan cap: no sending domain's own daily ceiling may exceed it. */
+export declare const BULK_EMAIL_MAX_DAILY_CAP: number;
 /**
  * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
  * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,

package/node_modules/@oxygen/shared/dist/plan-band.js

@@ -203,6 +203,23 @@ export function resolveDefaultAutoRunBatchCreditCeilingForPlan(resolution, optio
 function bandSpendResolution(band) {
     return { planTier: band === "free" ? null : `oxygen_${band}`, limitsTier: PLAN_BAND_LIMITS_TIER[band] };
 }
+/**
+ * PROPOSED defaults, not yet a product decision: newsletter (sending-domain)
+ * emails one workspace may reserve per UTC day. Newsletters are paid-only, so
+ * free is 0. The staff override and the workspace's share of the SES quota
+ * (`bulkEmailWorkspaceDailyAllowance`) can only lower this.
+ */
+export const BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND = Object.freeze({
+    free: 0,
+    "49": 5_000,
+    "99": 10_000,
+    "199": 25_000,
+    "499": 50_000,
+    "999": 100_000,
+    "1999": 250_000,
+});
+/** The largest plan cap: no sending domain's own daily ceiling may exceed it. */
+export const BULK_EMAIL_MAX_DAILY_CAP = Math.max(...Object.values(BULK_EMAIL_DAILY_CAP_PER_PLAN_BAND));
 /**
  * Public webhook ingress (repricing 2026-09, decision L4.4, ratified
  * 2026-09-26): deliveries a minute that one webhook target (a Table endpoint,