@oxygen-agent/cli 1.1011.855 → 1.1011.974

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.1011.855
+Version: 1.1011.974

package/dist/admin-lead-magnet-commands.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+/** `oxygen admin lead-magnets`: the staff CMS for the public /resources catalog, the same rows /admin/lead-magnets edits. */
+export declare function registerAdminLeadMagnetCommands(program: Command, handle: Handle): void;
+export {};

package/dist/admin-lead-magnet-commands.js

@@ -0,0 +1,128 @@
+import { readFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { Option } from "commander";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { resolveLiveDryRunMode } from "./cli-values.js";
+import { requestOxygen } from "./http-client.js";
+// The resource JSON documented in docs/marketing-resources.md, mapped to the API body.
+const FILE_FIELDS = {
+    slug: "slug", title: "title", description: "description", imageUrl: "image_url", imageAlt: "image_alt",
+    redirectUrl: "redirect_url", status: "status", sortOrder: "sort_order",
+};
+const COVER_TYPES = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp" };
+// The server's own ceiling (LEAD_MAGNET_MAX_IMAGE_BYTES), checked first so an oversized file is never sent.
+const MAX_COVER_BYTES = 4 * 1024 * 1024;
+const usageError = (message) => new OxygenError("invalid_request", message, { exitCode: 2 });
+/** `oxygen admin lead-magnets`: the staff CMS for the public /resources catalog, the same rows /admin/lead-magnets edits. */
+export function registerAdminLeadMagnetCommands(program, handle) {
+    const admin = program.commands.find((command) => command.name() === "admin");
+    if (!admin)
+        throw new Error("Admin commands must be registered first.");
+    const leadMagnets = admin
+        .command("lead-magnets")
+        .description("Publish, update and unpublish the email-gated lead magnets (resources) on the public /resources catalog. Staff only.");
+    leadMagnets
+        .command("list")
+        .description("List every lead magnet (resource) on /resources, drafts included, with status and public URL. Staff only, read-only.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("admin lead-magnets list", options, () => requestOxygen("/api/cli/admin/lead-magnets")));
+    leadMagnets
+        .command("get")
+        .description("Show one lead magnet (resource) by slug: every field, draft or published, and its public /resources URL. Staff only, read-only.")
+        .argument("<slug>", "The resource's slug (its /resources/<slug> path) or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((slug, options) => handle("admin lead-magnets get", options, () => requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`)));
+    leadMagnets
+        .command("upsert")
+        .description("Publish or update the lead magnet (resource) at a slug on /resources from a resource JSON file and/or flags; --cover uploads a local image. Dry run by default: prints the exact row and changed fields, uploads and writes nothing. --live applies it, and a published resource is public at once. Staff only.")
+        .option("--file <path>", "Resource JSON with slug, title, description, imageUrl, imageAlt, redirectUrl, status, sortOrder. Flags override its values.")
+        .option("--slug <slug>", "Permanent public slug (/resources/<slug>): lowercase letters, digits and hyphens. A new slug creates another resource.")
+        .option("--title <text>", "Title, up to 160 characters.")
+        .option("--description <text>", "Brief description, up to 600 characters.")
+        .option("--redirect-url <url>", "HTTPS link the visitor opens after entering an email.")
+        .option("--cover <path>", "Local PNG, JPEG or WebP cover image, up to 4 MB, uploaded to public storage on --live.")
+        .option("--image-url <url>", "HTTPS URL of an already hosted cover image, instead of --cover.")
+        .option("--image-alt <text>", "Cover alt text. Defaults to the title.")
+        .addOption(new Option("--status <status>", "published lists it on /resources; draft hides it. A new resource defaults to draft.").choices(["published", "draft"]))
+        .option("--sort-order <n>", "Catalog position, lowest first. Defaults to 0.")
+        .option("--dry-run", "Preview without uploading or writing (the default).")
+        .option("--live", "Upload the cover and write the resource.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("admin lead-magnets upsert", options, () => upsertLeadMagnet(options)));
+    leadMagnets
+        .command("unpublish")
+        .description("Unpublish a lead magnet (resource): set it to draft, which removes it and its page from /resources and keeps its email records. Dry run by default; --live applies it. Staff only.")
+        .argument("<slug>", "The resource's slug.")
+        .option("--dry-run", "Preview without writing (the default).")
+        .option("--live", "Unpublish it.")
+        .option("--json", "Print a JSON envelope.")
+        .action((slug, options) => handle("admin lead-magnets unpublish", options, () => requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, {
+        method: "POST",
+        body: { status: "draft", mode: resolveLiveDryRunMode(options) },
+    })));
+}
+async function upsertLeadMagnet(options) {
+    const mode = resolveLiveDryRunMode(options);
+    if (options.cover !== undefined && options.imageUrl !== undefined) {
+        throw new OxygenError("conflicting_flags", "Pass either --cover or --image-url, not both.", { exitCode: 1 });
+    }
+    const fromFile = options.file === undefined ? {} : await readResourceFile(options.file);
+    if (options.slug !== undefined && fromFile.slug !== undefined && fromFile.slug !== options.slug) {
+        throw usageError(`--slug ${options.slug} does not match the file's slug ${String(fromFile.slug)}. The slug is the resource's identity: drop --slug or fix the file.`);
+    }
+    const flags = {
+        slug: options.slug, title: options.title, description: options.description, redirect_url: options.redirectUrl,
+        image_url: options.imageUrl, image_alt: options.imageAlt, status: options.status,
+        sort_order: options.sortOrder === undefined ? undefined : readSortOrder(options.sortOrder),
+    };
+    const { slug, ...fields } = { ...fromFile, ...Object.fromEntries(Object.entries(flags).filter(([, value]) => value !== undefined)) };
+    if (typeof slug !== "string" || !slug)
+        throw usageError("Name the resource with --slug, or a slug in --file.");
+    // A local cover replaces any imageUrl the file carries.
+    if (options.cover !== undefined)
+        delete fields.image_url;
+    const body = { ...fields, mode };
+    if (options.cover === undefined) {
+        return requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, { method: "POST", body });
+    }
+    const form = new FormData();
+    form.append("payload", JSON.stringify(body));
+    form.append("image", await readCover(options.cover));
+    return requestOxygen(`/api/cli/admin/lead-magnets/${encodeURIComponent(slug)}`, { method: "POST", formData: form });
+}
+async function readResourceFile(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(resolve(path), "utf8"));
+    }
+    catch (error) {
+        throw usageError(`--file must be a readable JSON file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw usageError("--file must hold one JSON object.");
+    const unknown = Object.keys(parsed).filter((key) => !Object.hasOwn(FILE_FIELDS, key));
+    if (unknown.length > 0) {
+        throw usageError(`--file has unknown fields: ${unknown.join(", ")}. A resource file has ${Object.keys(FILE_FIELDS).join(", ")}.`);
+    }
+    return Object.fromEntries(Object.entries(parsed).map(([key, value]) => [FILE_FIELDS[key], value]));
+}
+async function readCover(path) {
+    const type = COVER_TYPES[extname(path).toLowerCase()];
+    if (!type)
+        throw usageError("--cover must be a .png, .jpg, .jpeg or .webp image.");
+    let bytes;
+    try {
+        bytes = await readFile(resolve(path));
+    }
+    catch (error) {
+        throw usageError(`--cover could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (bytes.byteLength > MAX_COVER_BYTES)
+        throw usageError("--cover must be 4 MB or smaller.");
+    return new File([bytes], basename(path), { type });
+}
+function readSortOrder(value) {
+    if (!/^-?\d+$/.test(value.trim()))
+        throw usageError("--sort-order must be a whole number.");
+    return Number(value);
+}

package/dist/command-manifest.js

@@ -78,6 +78,9 @@ const MUTATING_VERBS = new Set([
     // Thread field, while a future `field-get` would be a read.
     "field-set",
     "file", "forward", "grant", "harvest", "history", "import", "insert", "interrupt", "invite",
+    // `crm keep` clears a seeded sample record's marker for good: from then on the
+    // record counts in pipeline totals. A verb that reads like "leave as is".
+    "keep",
     "label-add", "label-remove", "launch", "log", "login", "logout", "mark-all-read", "mark-read", "materialize", "merge",
     "migrate",
     "move", "note", "off", "onboard", "order", "pause", "pin", "priority", "provision",
@@ -105,6 +108,8 @@ const MUTATING_COMMANDS = new Set([
     "managed-inboxes recover",
     "mailboxes warmup status",
     "mailboxes warmup reconnect",
+    // Immediately moves a provider proxy and may pause or resume the sender.
+    "senders proxy-country",
     // A noun leaf with its own action (not a group), so the default would
     // advertise a STANDING per-viewer paid-enrichment toggle as a read. `enrichment`
     // itself is not a MUTATING_VERBS entry because the other two `enrichment`
@@ -182,6 +187,10 @@ const ZERO_CREDIT_APPROVAL_COMMANDS = new Set([
 // one. Keep the exception exact so genuine `run` actions remain mutations.
 const READ_ONLY_COMMANDS = new Set([
     "workflows run",
+    // `history` is a mutating verb for `whatsapp history` (it backfills a chat);
+    // these two only read a row's and a cell's recorded changes.
+    "rows history",
+    "cells history",
     // Inspect existing creator receipts; never generate or import again.
     "ugc posts draft-status",
     "ugc posts history",
@@ -190,6 +199,8 @@ const READ_ONLY_COMMANDS = new Set([
 // invocation still previews, so machine-readable discovery must not imply that
 // calling the command without its confirmation flag writes anything.
 const PREVIEW_BY_DEFAULT_COMMANDS = new Set([
+    "deliverability placement-test run",
+    "deliverability placement-test send",
     "managed-inboxes recover",
     // /api/cli/find/run treats an omitted mode as dry_run for every Find capability.
     "find email",

package/dist/functions-commands.js

@@ -42,7 +42,7 @@ export function registerFunctionsCommands(program, handle) {
         .requiredOption("--expected-draft-hash <hash>", "function.draft.contentHash returned by draft or describe; rejects concurrent edits.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions publish", options, () => requestOxygen("/api/cli/functions", { method: "POST", body: { operation: "publish", function: ref, expected_draft_hash: options.expectedDraftHash } })));
-    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations, the table that called each one, and their captured versions. For a call that did not complete, creditsUsed can show the estimate; `table-runs provider-summary <run_id>` reports the credits actually captured.")
+    functions.command("runs <function>").description("Inspect a Function's latest 100 invocations, the table that called each one, and their captured versions and bindings: each run's overwrite policy, output mapping and run condition as they were when it ran. Per row, the calling table's Function cell records overwrite_policy, written_columns, overwritten_columns (filled cells it replaced) and kept_columns (filled cells empty_only left). For a call that did not complete, creditsUsed can show the estimate; `table-runs provider-summary <run_id>` reports the credits actually captured.")
         .option("--json", "Print a JSON envelope.")
         .action((ref, options) => handle("functions runs", options, () => requestOxygen(`/api/cli/functions/runs?${new URLSearchParams({ function: ref })}`)));
     functions.command("rename <function> <name>").description("Rename a Function while preserving its identity, callers and published execution.")