@oxygen-agent/cli 1.1014.1035 → 1.1014.1132

package/node_modules/@oxygen/shared/dist/workspace-placement-view.js

@@ -0,0 +1,102 @@
+import { CliHttpError } from "./cli-http-error.js";
+import { placementReceiverLabel } from "./workspace-placement.js";
+export function workspacePlacementView(input, webUrl) {
+    const variants = new Map();
+    const probes = input.plan.probes.map(p => {
+        let v = variants.get(p.variant.key);
+        if (!v) {
+            v = { key: p.variant.key, planned: 0, observed: 0, google_primary: 0, google_promotions: 0, google_social: 0, google_updates: 0, google_forums: 0, microsoft_focused: 0, microsoft_other: 0, spam: 0, other_folder: 0, unknown_folder: 0, unknown_category: 0, not_observed: 0, failed: 0, send_unknown: 0, read_blocked: 0 };
+            variants.set(v.key, v);
+        }
+        v.planned++;
+        const out = input.outcomes[p.id];
+        const o = out?.observation;
+        if (o) {
+            v.observed++;
+            if (o.folder === "spam")
+                v.spam++;
+            else if (o.folder === "other")
+                v.other_folder++;
+            else if (o.folder === "unknown")
+                v.unknown_folder++;
+            else if (o.folder === "inbox") {
+                if (p.receiver.provider === "google" && o.category === "primary")
+                    v.google_primary++;
+                else if (p.receiver.provider === "google" && o.category === "promotions")
+                    v.google_promotions++;
+                else if (p.receiver.provider === "google" && o.category === "social")
+                    v.google_social++;
+                else if (p.receiver.provider === "google" && o.category === "updates")
+                    v.google_updates++;
+                else if (p.receiver.provider === "google" && o.category === "forums")
+                    v.google_forums++;
+                else if (p.receiver.provider === "microsoft" && o.category === "focused")
+                    v.microsoft_focused++;
+                else if (p.receiver.provider === "microsoft" && o.category === "other")
+                    v.microsoft_other++;
+                else if (o.category === "unknown")
+                    v.unknown_category++;
+            }
+        }
+        else if (out?.state === "not_observed")
+            v.not_observed++;
+        else if (out?.state === "send_failed")
+            v.failed++;
+        else if (out?.state === "send_unknown")
+            v.send_unknown++;
+        else if (out?.state === "read_blocked")
+            v.read_blocked++;
+        const state = out?.state ?? (input.deliveries?.[p.id]?.status === "sent" ? "awaiting_results" : input.deliveries?.[p.id]?.status ?? "pending");
+        return { ...workspacePlacementProbeMeta(p), state, status_label: workspacePlacementStateLabel(state), ...(input.deliveries?.[p.id] ? { delivery: input.deliveries[p.id] } : {}), ...(o ? { observation: p.receiver.network_id ? { ...o, receiver_message_id: "private" } : o } : {}) };
+    });
+    const settled = input.plan.probes.filter(p => input.outcomes[p.id]).length;
+    return { id: input.id, provider: "internal", billing_mode: "internal", credits_used: 0, status: settled < probes.length ? "running" : probes.every(p => p.state === "observed") ? "completed" : "incomplete",
+        created_at: new Date(input.created_at).toISOString(), message_count: probes.length, variants: [...variants.values()], probes, plan_hash: input.plan.plan_hash, web_url: webUrl,
+        directional_note: "Observed placement in participating receiving accounts; not a campaign placement guarantee. Primary and Focused are separate provider classifications." };
+}
+export function workspacePlacementStateLabel(state) {
+    return { pending: "Queued", leased: "Preparing send", sent: "Awaiting receiver observation", awaiting_results: "Awaiting receiver observation", observed: "Observed", not_observed: "Not observed within two hours", send_failed: "Send failed", send_unknown: "Send outcome unknown; do not resend", read_blocked: "Receiver could not be checked", uncertain: "Send outcome unknown; do not resend", canceled: "Send canceled", failed: "Send failed" }[state] ?? "Pending";
+}
+function pageNumber(value, fallback, max, field) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > max)
+        throw new CliHttpError(400, "workspace_test_page_invalid", `${field} must be an integer between 0 and ${max}.`);
+    return value;
+}
+export function workspacePlacementProbeMeta(probe) {
+    return { id: probe.id, sender: probe.sender.address, sender_name: probe.sender.display_name ?? null, receiver: placementReceiverLabel(probe.receiver), receiver_provider: probe.receiver.provider, variant: probe.variant.key, subject: probe.variant.subject,
+        body_text_characters: Array.from(probe.variant.body_text).length, body_html_characters: Array.from(probe.variant.body_html ?? "").length };
+}
+export function workspacePlacementCopyPage(plan, input) {
+    const id = typeof input.probeId === "string" ? input.probeId.toLowerCase() : null;
+    const probe = plan.probes.find(p => p.id === id);
+    if (!probe)
+        throw new CliHttpError(400, "workspace_test_page_invalid", "Choose a probe from this workspace test.");
+    const part = input.part ?? "body_text";
+    if (part !== "body_text" && part !== "body_html")
+        throw new CliHttpError(400, "workspace_test_page_invalid", "body_part must be body_text or body_html.");
+    const chars = Array.from(probe.variant[part] ?? "");
+    const offset = pageNumber(input.offset, 0, chars.length, "offset");
+    const limit = pageNumber(input.limit, 3000, 3000, "copy_limit");
+    if (limit < 1)
+        throw new CliHttpError(400, "workspace_test_page_invalid", "copy_limit must be at least 1.");
+    const end = Math.min(chars.length, offset + limit);
+    return { id: probe.id, variant: probe.variant.key, sender: probe.sender.address, sender_name: probe.sender.display_name ?? null, receiver: placementReceiverLabel(probe.receiver), subject: probe.variant.subject, part, offset, total_characters: chars.length, text: chars.slice(offset, end).join(""), has_more: end < chars.length, next_offset: end < chars.length ? end : null };
+}
+export function workspacePlacementProbePage(probes, input, defaultLimit = 10) {
+    const limit = pageNumber(input.limit, defaultLimit, 20, "limit");
+    if (limit < 1)
+        throw new CliHttpError(400, "workspace_test_page_invalid", "limit must be at least 1.");
+    const cursor = typeof input.cursor === "string" ? input.cursor.toLowerCase() : null;
+    const anchor = cursor === null ? -1 : probes.findIndex(p => p.id === cursor);
+    if (input.cursor !== undefined && anchor < 0)
+        throw new CliHttpError(400, "workspace_test_page_invalid", "Use a cursor from this workspace test.");
+    const rows = probes.slice(anchor + 1, anchor + 1 + limit);
+    const more = anchor + 1 + rows.length < probes.length;
+    return { probes: rows, probe_count: probes.length, has_more: more, next_cursor: more ? rows.at(-1).id : null };
+}
+export function workspacePlacementPreviewPage(plan, input = {}) {
+    const { probes: _probes, ...metadata } = plan;
+    return { ...metadata, ...workspacePlacementProbePage(plan.probes.map(workspacePlacementProbeMeta), input, 5) };
+}

package/node_modules/@oxygen/shared/dist/workspace-placement.d.ts

@@ -0,0 +1,84 @@
+export type WorkspacePlacementVariant = {
+    key: string;
+    subject: string;
+    body_text: string;
+    body_html?: string;
+};
+export type WorkspacePlacementMailbox = {
+    id: string;
+    address: string;
+    provider: "google" | "microsoft";
+    transport: string;
+    display_name?: string | null;
+    signature_html: string | null;
+    organization_id?: string;
+    network_id?: string;
+};
+export type WorkspacePlacementProbe = {
+    id: string;
+    sender: WorkspacePlacementMailbox;
+    receiver: WorkspacePlacementMailbox;
+    variant: WorkspacePlacementVariant;
+};
+export type WorkspacePlacementPlan = {
+    request_id: string;
+    organization_id: string;
+    provider: "internal";
+    billing_mode: "internal";
+    credits: 0;
+    allow_paused_probe: boolean;
+    receiver_scope?: "workspace" | "network";
+    rendered_at?: string;
+    rendering?: {
+        tracking_opens: boolean;
+        tracking_clicks: boolean;
+        tracking_host: string | null;
+    };
+    probes: WorkspacePlacementProbe[];
+    excluded_self_sends: number;
+    message_count: number;
+    plan_hash: string;
+};
+export declare function workspacePlacementId(value: unknown): value is string;
+export declare function readWorkspacePlacementVariants(value: unknown): WorkspacePlacementVariant[];
+export declare function readWorkspacePlacementMailboxIds(value: unknown): string[];
+export declare function buildWorkspacePlacementPlan(input: {
+    requestId: string;
+    organizationId: string;
+    senders: WorkspacePlacementMailbox[];
+    receivers: WorkspacePlacementMailbox[];
+    variants: WorkspacePlacementVariant[];
+    allowPausedProbe: boolean;
+    renderedAt?: string;
+    rendering?: WorkspacePlacementPlan["rendering"];
+    network?: boolean;
+    renderVariant?: (variant: WorkspacePlacementVariant, sender: WorkspacePlacementMailbox, probeId: string) => WorkspacePlacementVariant;
+}): WorkspacePlacementPlan;
+export type WorkspacePlacementObservation = {
+    folder: "inbox" | "spam" | "other" | "unknown";
+    category: "primary" | "promotions" | "social" | "updates" | "forums" | "focused" | "other" | "unknown";
+    observed_at: string;
+    receiver_message_id: string;
+};
+export declare function googleWorkspacePlacement(labels: string[], messageId: string, observedAt: string): WorkspacePlacementObservation;
+export declare function microsoftWorkspacePlacement(input: {
+    messageId: string;
+    parentFolderId: string | null;
+    inboxId: string;
+    junkId: string;
+    classification: unknown;
+    observedAt: string;
+}): WorkspacePlacementObservation;
+/** One exact payload owner for preview, transactional enqueue and drain verification. */
+export declare function workspacePlacementPayload(probe: WorkspacePlacementProbe): {
+    kind: "email_send";
+    to: string;
+    subject: string;
+    body: string;
+    body_html?: string;
+    apply_mailbox_signature: boolean;
+    diagnostic_probe_id: string;
+};
+/** Foreign identities remain private even in previews, copy pages and manifests. */
+export declare function placementReceiverLabel(receiver: WorkspacePlacementMailbox): string;
+export declare function publicWorkspacePlacementPlan(plan: WorkspacePlacementPlan): WorkspacePlacementPlan;

package/node_modules/@oxygen/shared/dist/workspace-placement.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { CliHttpError } from "./cli-http-error.js";
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+export function workspacePlacementId(value) { return typeof value === "string" && UUID.test(value); }
+function invalid(message) { throw new CliHttpError(400, "workspace_test_invalid", message); }
+export function readWorkspacePlacementVariants(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > 5)
+        invalid("Choose between one and five copy variants.");
+    const keys = new Set();
+    return value.map(raw => {
+        if (!raw || typeof raw !== "object")
+            invalid("Each variant needs a key, subject and body_text.");
+        const v = raw;
+        if (typeof v.key !== "string" || !/^[a-zA-Z0-9_-]{1,40}$/.test(v.key) || keys.has(v.key))
+            invalid("Variant keys must be unique short names using letters, numbers, underscores or hyphens.");
+        if (typeof v.subject !== "string" || !v.subject.trim() || /[\r\n]/.test(v.subject) || v.subject.length > 998)
+            invalid("Each subject must be a non-empty single line, at most 998 characters.");
+        if (typeof v.body_text !== "string" || !v.body_text.trim() || v.body_text.length > 100_000)
+            invalid("Each body_text must contain between one and 100,000 characters.");
+        if (v.body_html !== undefined && (typeof v.body_html !== "string" || !v.body_html.trim() || v.body_html.length > 200_000))
+            invalid("body_html must contain between one and 200,000 characters when supplied.");
+        if (/\{\{[^}]+\}\}/.test(v.subject + v.body_text + (v.body_html ?? "")))
+            invalid("Resolve personalization variables before testing the exact copy.");
+        keys.add(v.key);
+        return { key: v.key, subject: v.subject, body_text: v.body_text, ...(typeof v.body_html === "string" ? { body_html: v.body_html } : {}) };
+    });
+}
+export function readWorkspacePlacementMailboxIds(value) {
+    if (!Array.isArray(value) || !value.length || value.length > 50 || value.some(v => !workspacePlacementId(v)))
+        invalid("Select one to 50 exact mailbox IDs from this workspace.");
+    return [...new Set(value.map(id => id.toLowerCase()))].sort();
+}
+function probeId(value) {
+    const h = createHash("sha256").update(value).digest("hex");
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+export function buildWorkspacePlacementPlan(input) {
+    if (!workspacePlacementId(input.requestId) || !workspacePlacementId(input.organizationId))
+        invalid("The workspace test request is invalid.");
+    const requestId = input.requestId.toLowerCase();
+    const organizationId = input.organizationId.toLowerCase();
+    const variants = readWorkspacePlacementVariants(input.variants);
+    const senders = [...input.senders].sort((a, b) => a.id.localeCompare(b.id));
+    const receivers = [...input.receivers].sort((a, b) => a.id.localeCompare(b.id));
+    const self = (sender, receiver) => sender.id === receiver.id || sender.address.toLowerCase() === receiver.address.toLowerCase();
+    let excluded = 0, pairs = 0;
+    for (const sender of senders)
+        for (const receiver of receivers) {
+            if (self(sender, receiver))
+                excluded += variants.length;
+            else
+                pairs++;
+        }
+    if ((input.network ? senders.length * variants.length * new Set(receivers.map(r => r.provider)).size : pairs * variants.length) < 1 || (input.network ? senders.length * variants.length * new Set(receivers.map(r => r.provider)).size : pairs * variants.length) > 50)
+        invalid("A workspace test must send between one and 50 messages after excluding self-sends.");
+    const probes = [];
+    // Reject oversized matrices before signatures/HTML/tracking allocate per-probe content.
+    // Rotate variants per receiver: no variant always gets the first submission.
+    for (const [senderIndex, sender] of senders.entries()) {
+        for (const [index, receiver] of receivers.entries()) {
+            if (self(sender, receiver))
+                continue;
+            for (let offset = 0; offset < variants.length; offset++) {
+                const original = variants[(offset + index) % variants.length];
+                if (input.network) {
+                    const group = receivers.filter(r => r.provider === receiver.provider);
+                    const sequence = senderIndex * variants.length + variants.indexOf(original);
+                    if (group[sequence % group.length].id !== receiver.id)
+                        continue;
+                }
+                const id = probeId(`${organizationId}:${requestId}:${sender.id}:${receiver.id}:${original.key}`);
+                const variant = input.renderVariant ? input.renderVariant(original, sender, id) : original;
+                probes.push({ id, sender, receiver, variant });
+            }
+        }
+    }
+    if (!probes.length || probes.length > 50)
+        invalid("A workspace test must send between one and 50 messages after excluding self-sends.");
+    const plan = { request_id: requestId, organization_id: organizationId, provider: "internal",
+        ...(input.network ? { receiver_scope: "network" } : {}), billing_mode: "internal", credits: 0, allow_paused_probe: input.allowPausedProbe,
+        ...(input.renderedAt ? { rendered_at: input.renderedAt } : {}), ...(input.rendering ? { rendering: input.rendering } : {}),
+        probes, excluded_self_sends: excluded, message_count: probes.length };
+    return { ...plan, plan_hash: createHash("sha256").update(JSON.stringify(plan)).digest("hex") };
+}
+export function googleWorkspacePlacement(labels, messageId, observedAt) {
+    const categories = ["PERSONAL", "PROMOTIONS", "SOCIAL", "UPDATES", "FORUMS"].filter(k => labels.includes(`CATEGORY_${k}`));
+    return { folder: labels.includes("SPAM") ? "spam" : labels.includes("INBOX") ? "inbox" : "other",
+        category: categories.length === 1 ? { PERSONAL: "primary", PROMOTIONS: "promotions", SOCIAL: "social", UPDATES: "updates", FORUMS: "forums" }[categories[0]] : "unknown",
+        observed_at: observedAt, receiver_message_id: messageId };
+}
+export function microsoftWorkspacePlacement(input) {
+    return { folder: input.parentFolderId === input.junkId ? "spam" : input.parentFolderId === input.inboxId ? "inbox" : input.parentFolderId ? "other" : "unknown",
+        category: input.classification === "focused" || input.classification === "other" ? input.classification : "unknown",
+        observed_at: input.observedAt, receiver_message_id: input.messageId };
+}
+/** One exact payload owner for preview, transactional enqueue and drain verification. */
+export function workspacePlacementPayload(probe) {
+    return { kind: "email_send", to: probe.receiver.address, subject: probe.variant.subject, body: probe.variant.body_text,
+        ...(probe.variant.body_html ? { body_html: probe.variant.body_html } : {}), apply_mailbox_signature: false, diagnostic_probe_id: probe.id };
+}
+/** Foreign identities remain private even in previews, copy pages and manifests. */
+export function placementReceiverLabel(receiver) {
+    return receiver.network_id ? `${receiver.provider === "google" ? "Google" : "Microsoft"} receiver ${receiver.network_id.slice(0, 8)}` : receiver.address;
+}
+export function publicWorkspacePlacementPlan(plan) {
+    return { ...plan, probes: plan.probes.map(p => ({ ...p, receiver: p.receiver.network_id ? { id: p.receiver.network_id, address: placementReceiverLabel(p.receiver), provider: p.receiver.provider, transport: "network", signature_html: null } : p.receiver })) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.1014.1035",
+  "version": "1.1014.1132",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",