@oxygen-agent/cli 1.922.14 → 1.936.1

package/dist/ugc-commands.js

@@ -0,0 +1,748 @@
+import { requestOxygen } from "./http-client.js";
+function parseField(value, field) {
+    if (field.kind === "array" || field.kind === "object") {
+        const parsed = JSON.parse(String(value));
+        if (field.kind === "array"
+            ? !Array.isArray(parsed) ||
+                !parsed.every((item) => typeof item === "string")
+            : !parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error(`${field.name} must be a JSON ${field.kind === "array" ? "array of strings" : "object"}.`);
+        return parsed;
+    }
+    if (field.kind === "number") {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < 0)
+            throw new Error(`${field.name} must be a nonnegative finite number.`);
+        return parsed;
+    }
+    if (field.kind === "boolean") {
+        if (value === true || value === "true")
+            return true;
+        if (value === false || value === "false")
+            return false;
+        throw new Error(`${field.name} must be true or false.`);
+    }
+    return value;
+}
+export function registerUgcCommands(program, handle) {
+    const ugc = program
+        .command("ugc")
+        .description("Manage UGC programs and independent creator participations: briefs, voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability.");
+    const groups = new Map();
+    const group = (name) => {
+        let command = groups.get(name);
+        if (!command) {
+            command = ugc.command(name);
+            groups.set(name, command);
+        }
+        return command;
+    };
+    group("programs")
+        .command("list")
+        .description("Read UGC programs in the active workspace. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc programs list", options, () => {
+        const query = new URLSearchParams({ view: "programs" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("programs")
+        .command("get")
+        .description("Read UGC program in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc programs get", options, () => {
+        const query = new URLSearchParams({ view: "program" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("creators")
+        .command("list")
+        .description("Read UGC participations in the active workspace. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc creators list", options, () => {
+        const query = new URLSearchParams({ view: "participations" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("briefs")
+        .command("list")
+        .description("Read one program's UGC briefs. Read-only; requires --program-id.")
+        .showHelpAfterError(`Briefs belong to a program. Run \`${program.name() || "oxygen"} ugc programs list --json\` to find its ID, then \`${program.name() || "oxygen"} ugc briefs list --program-id <id> --json\`.`)
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc briefs list", options, () => {
+        const query = new URLSearchParams({ view: "briefs" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("posts")
+        .command("list")
+        .description("Read UGC posts in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--cursor <cursor>", "Opaque next_cursor from the previous page.")
+        .option("--limit <count>", "Posts per page, 1–500.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc posts list", options, () => {
+        const query = new URLSearchParams({ view: "posts" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        if (options.cursor)
+            query.set("cursor", String(options.cursor));
+        if (options.limit)
+            query.set("limit", String(options.limit));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("analytics")
+        .command("get")
+        .description("Read UGC analytics in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc analytics get", options, () => {
+        const query = new URLSearchParams({ view: "analytics" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("knowledge")
+        .command("list")
+        .description("Read UGC knowledge in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc knowledge list", options, () => {
+        const query = new URLSearchParams({ view: "knowledge" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("voice")
+        .command("get")
+        .description("Read UGC voice in the active workspace. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .requiredOption("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc voice get", options, () => {
+        const query = new URLSearchParams({ view: "voice" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("sponsorship")
+        .command("get")
+        .description("Read UGC sponsorship in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc sponsorship get", options, () => {
+        const query = new URLSearchParams({ view: "sponsorship" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    const writes = [
+        {
+            action: "program_create",
+            command: "programs create",
+            description: "Create a master UGC program. Free: 0 credits, no provider call.",
+            fields: [
+                {
+                    name: "name",
+                    kind: "string",
+                    description: "Program name.",
+                    required: true,
+                },
+                {
+                    name: "product_url",
+                    kind: "string",
+                    description: "Product website URL.",
+                    required: true,
+                },
+                {
+                    name: "description",
+                    kind: "string",
+                    description: "Program description.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_slugs",
+                    kind: "array",
+                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "brand_approval_required",
+                    kind: "boolean",
+                    description: "Require a separate brand approval before publishing.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs update",
+            description: "Update program settings and selected shared knowledge.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "name",
+                    kind: "string",
+                    description: "Program name.",
+                    required: false,
+                },
+                {
+                    name: "product_url",
+                    kind: "string",
+                    description: "Product website URL.",
+                    required: false,
+                },
+                {
+                    name: "description",
+                    kind: "string",
+                    description: "Program description.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_slugs",
+                    kind: "array",
+                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "brand_approval_required",
+                    kind: "boolean",
+                    description: "Require a separate brand approval before publishing.",
+                    required: false,
+                },
+                {
+                    name: "status",
+                    kind: "string",
+                    description: "Program status, or revoked for a participation.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "invite_create",
+            command: "creators invite",
+            description: "Create a shareable invite for an independent creator. No email is sent.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "email",
+                    kind: "string",
+                    description: "Invitee email. Returns a shareable invitation; does not send email.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "invite_revoke",
+            command: "creators revoke-invite",
+            description: "Revoke an unaccepted invitation.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "invitation_id",
+                    kind: "string",
+                    description: "Exact invitation ID to revoke.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "invite_accept",
+            command: "creators accept",
+            description: "Accept an exact invitation in the creator workspace and choose who may approve.",
+            fields: [
+                {
+                    name: "token",
+                    kind: "string",
+                    description: "Exact invitation token.",
+                    required: true,
+                },
+                {
+                    name: "approval_mode",
+                    kind: "string",
+                    description: "creator: creator approves; delegated: master operators may approve and schedule.",
+                    required: true,
+                },
+                {
+                    name: "linkedin_url",
+                    kind: "string",
+                    description: "Creator LinkedIn profile URL.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "participation_update",
+            command: "creators update",
+            description: "Connect an existing LinkedIn sender, change approval authority, or revoke participation.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "approval_mode",
+                    kind: "string",
+                    description: "creator: creator approves; delegated: master operators may approve and schedule.",
+                    required: false,
+                },
+                {
+                    name: "sender_account_id",
+                    kind: "string",
+                    description: "Existing physical LinkedIn connection ID; reused across programs.",
+                    required: false,
+                },
+                {
+                    name: "status",
+                    kind: "string",
+                    description: "Program status, or revoked for a participation.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "brief_create",
+            command: "briefs create",
+            description: "Create a brief with ordered questions. Free: 0 credits, no provider call.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: true,
+                },
+                {
+                    name: "prompt",
+                    kind: "string",
+                    description: "Instructions for this brief.",
+                    required: true,
+                },
+                {
+                    name: "questions",
+                    kind: "array",
+                    description: "Ordered questions for the creator.",
+                    required: true,
+                },
+                {
+                    name: "cycle",
+                    kind: "string",
+                    description: "Brief cycle label.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "brief_update",
+            command: "briefs update",
+            description: "Update a program brief.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "brief_id",
+                    kind: "string",
+                    description: "Brief ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: false,
+                },
+                {
+                    name: "prompt",
+                    kind: "string",
+                    description: "Instructions for this brief.",
+                    required: false,
+                },
+                {
+                    name: "questions",
+                    kind: "array",
+                    description: "Ordered questions for the creator.",
+                    required: false,
+                },
+                {
+                    name: "cycle",
+                    kind: "string",
+                    description: "Brief cycle label.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_enroll",
+            command: "posts enroll",
+            description: "Enroll one existing creator-owned post in this participation.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "draft_create",
+            command: "posts draft",
+            description: "Preview AI drafting from brief answers; execute only with approved and a credit ceiling.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "brief_id",
+                    kind: "string",
+                    description: "Brief ID.",
+                    required: true,
+                },
+                {
+                    name: "answers",
+                    kind: "array",
+                    description: "Answers in brief question order.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "max_credits",
+                    kind: "number",
+                    description: "Explicit credit ceiling from preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_update",
+            command: "posts update",
+            description: "Edit or schedule an enrolled post with creator or delegated authority; publishing gates still apply.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: false,
+                },
+                {
+                    name: "content_text",
+                    kind: "string",
+                    description: "Edited post text.",
+                    required: false,
+                },
+                {
+                    name: "scheduled_for",
+                    kind: "string",
+                    description: "Future ISO-8601 publishing time with timezone.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_approve",
+            command: "posts approve",
+            description: "Record creator or explicitly delegated operator approval of the current post.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "source_revision",
+                    kind: "string",
+                    description: "Exact reviewed content fingerprint returned by posts list.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "brand_approve",
+            command: "posts brand-approve",
+            description: "Record separate master brand approval of the current post.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "source_revision",
+                    kind: "string",
+                    description: "Exact reviewed content fingerprint returned by posts list.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "voice_import",
+            command: "voice import",
+            description: "Preview LinkedIn voice import; execute only with approved and a credit ceiling.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "max_credits",
+                    kind: "number",
+                    description: "Explicit credit ceiling from preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_preview",
+            command: "sponsorship preview",
+            description: "Preview seat charges and monthly 10,000-credit creator grants for this program.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_ids",
+                    kind: "array",
+                    description: "Exact creator participation IDs to sponsor.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_confirm",
+            command: "sponsorship confirm",
+            description: "Approve the exact sponsorship quote; each master program pays separately even for the same account.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_ids",
+                    kind: "array",
+                    description: "Exact creator participation IDs to sponsor.",
+                    required: true,
+                },
+                {
+                    name: "quote",
+                    kind: "string",
+                    description: "Exact sponsorship quote returned by preview.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "amplification_save",
+            command: "amplification save",
+            description: "Save exact opted-in sender scope and bounded post-specific amplification. Enabling needs explicit approval.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participant_sender_ids",
+                    kind: "array",
+                    description: "Exact opted-in participant sender IDs.",
+                    required: true,
+                },
+                {
+                    name: "actions",
+                    kind: "array",
+                    description: "Allowed post-specific amplification actions.",
+                    required: true,
+                },
+                {
+                    name: "enabled",
+                    kind: "boolean",
+                    description: "Enable the bounded amplification policy.",
+                    required: true,
+                },
+                {
+                    name: "max_actions_per_post",
+                    kind: "number",
+                    description: "Hard limit for amplification actions on each enrolled published post.",
+                    required: true,
+                },
+                {
+                    name: "max_credits_per_cycle",
+                    kind: "number",
+                    description: "Hard credit ceiling for the amplification cycle.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "delay_min_seconds",
+                    kind: "number",
+                    description: "Minimum amplification delay, 60–3600 seconds.",
+                    required: false,
+                },
+                {
+                    name: "delay_max_seconds",
+                    kind: "number",
+                    description: "Maximum amplification delay, 60–86400 seconds.",
+                    required: false,
+                },
+            ],
+        },
+    ];
+    for (const spec of writes) {
+        const [family, leaf] = spec.command.split(" ");
+        const command = group(family).command(leaf).description(spec.description);
+        for (const field of spec.fields) {
+            const flag = `--${field.name.replaceAll("_", "-")}${field.name === "approved" ? "" : ` <${field.kind === "array" || field.kind === "object" ? "json" : field.kind === "boolean" ? "true|false" : "value"}>`}`;
+            if (field.required)
+                command.requiredOption(flag, field.description);
+            else
+                command.option(flag, field.description);
+        }
+        command
+            .option("--json", "Print a JSON envelope.")
+            .action((options) => handle(`ugc ${spec.command}`, options, () => {
+            const body = { action: spec.action };
+            for (const field of spec.fields) {
+                const key = field.name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+                if (options[key] !== undefined)
+                    body[field.name] = parseField(options[key], field);
+            }
+            return requestOxygen("/api/cli/ugc", { method: "POST", body });
+        }));
+    }
+}