@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/integrations.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerIntegrationsFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;

package/dist/commands/integrations.js

@@ -0,0 +1,290 @@
+import { assertModeFlagsExclusive, parseJsonObject } from "../cli-values.js";
+import { collectRepeatable, parseJsonValue, readPositiveNumber } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { INTEGRATION_CONNECT_ACCOUNT_CONTRACT } from "@oxygen/shared/contracts/integration-connect";
+import { Command, Option } from "commander";
+function resolveComposioRunMode(options) {
+    assertModeFlagsExclusive(options);
+    if (options.live === true)
+        return "live";
+    if (options.dryRun === true)
+        return "dry_run";
+    const raw = readOption(options.mode);
+    if (raw) {
+        const normalized = raw.trim().toLowerCase().replace("-", "_");
+        if (normalized === "live" || normalized === "dry_run")
+            return normalized;
+        throw new OxygenError("invalid_mode", "--mode must be 'live' or 'dry_run'.", { details: { mode: raw }, exitCode: 1 });
+    }
+    return "dry_run";
+}
+function readNamedCredentials(entries) {
+    if (!entries || entries.length === 0)
+        return undefined;
+    const credentials = {};
+    for (const entry of entries) {
+        const separator = entry.indexOf("=");
+        if (separator <= 0) {
+            throw new Error("--credential must use name=value (for example, --credential subdomain=us).");
+        }
+        const name = entry.slice(0, separator).trim();
+        const value = entry.slice(separator + 1).trim();
+        if (!/^[A-Za-z][A-Za-z0-9_.-]{0,99}$/.test(name)) {
+            throw new Error("--credential has an invalid field name.");
+        }
+        if (!value) {
+            throw new Error(`--credential ${name}= requires a non-empty value.`);
+        }
+        if (Object.hasOwn(credentials, name)) {
+            throw new Error(`--credential field '${name}' was provided more than once.`);
+        }
+        credentials[name] = value;
+    }
+    return credentials;
+}
+export function registerIntegrationsFamily(program, handleAsyncAction) {
+    program
+        .command("integrations")
+        .description("Connect third-party tools such as PostHog, Slack, and HubSpot, and manage raw provider-webhook subscriptions. Start with `integrations list` to confirm any provider is supported, see its auth mode, and distinguish free connection setup from per-action credit estimates. Trigger-ready workspace events live under `workflows events list`. Local mailbox exports use `mailboxes import`, not this group.")
+        .addCommand(new Command("events")
+        .description("Inspect raw provider event definitions and manage subscriptions that feed workflows; use `workflows events list` for the trigger-ready workspace catalog.")
+        .addCommand(new Command("list")
+        .description("List raw provider event definitions and this org's enabled subscriptions. To choose a workflow trigger, use `oxygen workflows events list`.")
+        .option("--source <source>", "Filter by event source, such as hubspot or composio.gmail.")
+        .option("--event <event>", "Filter by event type, such as contact.created.")
+        .option("--toolkit <id>", "Filter by toolkit / integration id, such as gmail.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("integrations events list", options, () => {
+            const query = new URLSearchParams();
+            if (readOption(options.source))
+                query.set("source", readOption(options.source) ?? "");
+            if (readOption(options.event))
+                query.set("event", readOption(options.event) ?? "");
+            if (readOption(options.toolkit))
+                query.set("toolkit", readOption(options.toolkit) ?? "");
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/integrations/events${suffix}`);
+        });
+    }))
+        .addCommand(new Command("enable")
+        .description("Enable a provider event for a connected integration account.")
+        .requiredOption("--source <source>", "Event source, such as hubspot or composio.gmail.")
+        .requiredOption("--event <event>", "Event type, such as contact.created.")
+        .option("--connection-id <connection_id>", "Specific integration connection id. Defaults to the active default connection.")
+        .option("--trigger-config <json>", "JSON object passed to the provider when registering the trigger (Composio triggers only).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("integrations events enable", options, () => {
+            const triggerConfigRaw = readOption(options.triggerConfig);
+            let triggerConfig;
+            if (triggerConfigRaw) {
+                const parsed = parseJsonValue(triggerConfigRaw, "--trigger-config");
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    throw new OxygenError("invalid_request", "--trigger-config must be a JSON object.", {
+                        exitCode: 1,
+                    });
+                }
+                triggerConfig = parsed;
+            }
+            return requestOxygen("/api/cli/integrations/events/enable", {
+                method: "POST",
+                body: {
+                    source: readOption(options.source),
+                    event: readOption(options.event),
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(triggerConfig ? { trigger_config: triggerConfig } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable a provider event for a connected integration account.")
+        .requiredOption("--source <source>", "Event source, such as hubspot.")
+        .requiredOption("--event <event>", "Event type, such as contact.created.")
+        .option("--connection-id <connection_id>", "Specific integration connection id. Defaults to the active default connection.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("integrations events disable", options, () => requestOxygen("/api/cli/integrations/events/disable", {
+            method: "POST",
+            body: {
+                source: readOption(options.source),
+                event: readOption(options.event),
+                ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("deliveries")
+        .description("List recent provider webhook deliveries (Composio triggers, HubSpot webhooks, etc.) and the workflow runs they kicked off.")
+        .option("--source <source>", "Filter by event source, such as hubspot or composio.gmail.")
+        .option("--event <event>", "Filter by event type, such as contact.created or GMAIL_NEW_GMAIL_MESSAGE.")
+        .option("--toolkit <id>", "Filter by integration/toolkit id, such as gmail or hubspot.")
+        .option("--connection-id <connection_id>", "Filter by a specific integration connection id.")
+        .option("--result <result>", "Filter by delivery result: success or error.")
+        .option("--limit <n>", "Maximum deliveries to return (1-200). Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("integrations events deliveries", options, () => {
+            const query = new URLSearchParams();
+            const set = (key, value) => {
+                const trimmed = readOption(value);
+                if (trimmed)
+                    query.set(key, trimmed);
+            };
+            set("source", options.source);
+            set("event", options.event);
+            set("toolkit", options.toolkit);
+            set("connection_id", options.connectionId);
+            set("result", options.result);
+            set("limit", options.limit);
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/integrations/events/deliveries${suffix}`);
+        });
+    })))
+        .addCommand(new Command("list")
+        .description("List supported integrations and this org's connections. Add --integration <id> to read one integration and its connection state.")
+        .option("--integration <id>", "Return only this integration and its connections, such as hubspot.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("integrations list", options, () => {
+            const integration = readOption(options.integration)?.trim();
+            return requestOxygen(`/api/cli/integrations/composio/list${integration ? `?integration=${encodeURIComponent(integration)}` : ""}`);
+        });
+    }))
+        .addCommand(addContractFlags(new Command("connect")
+        .description("Connect an integration. For OAuth toolkits, running this command immediately creates a pending provider authorization and returns a redirect URL; account access starts only if you approve on the provider's page. This is not a price preview. On a repriced workspace, a connected X account reserves 1,000 credits ($10) monthly; inspect current connection prices and first billing timing with `oxygen billing commitments --view connection-prices --json` before connecting. API-key integrations accept --api-key. Run without credentials only for an API-key integration to get a 0-credit preview of its exact fields (mode: needs_api_key): no credential is submitted, nothing is stored, and no provider call is made. Use repeatable --credential name=value when a provider also requires a host, subdomain, or other named value. To keep a secret out of shell history and process arguments, open the preview's web_url and submit it in Connections; --api-key is for controlled noninteractive use. Credential submission creates or replaces the connection immediately and needs no separate --approved flag. LinkedIn and WhatsApp return a hosted sign-in link instead (`oxygen senders connect` / `oxygen whatsapp connect` are the canonical paths).")
+        .argument("<integration_id>", "Integration id, such as 'slack' or 'serpapi'.")
+        .option("--api-key <value>", "API key for controlled noninteractive use. Literal values can appear in shell history and process arguments; prefer the preview web_url for manual entry.")
+        .option("--credential <name=value>", "Named provider credential field. Repeat for multi-field integrations (for example, PostHog: --credential subdomain=us).", collectRepeatable, [])
+        .option("--country <code>", "ISO 3166-1 alpha-2 country where the LinkedIn account owner normally signs in (required for `connect linkedin`; picks the egress proxy from the 56 countries OXYGEN has LinkedIn proxies in).")
+        .option("--pairing-phone-number <e164>", "WhatsApp only: pair by code sent to this E.164 number instead of showing a QR.")
+        .addOption(new Option("--acknowledge-risk", "Deprecated: LinkedIn connect no longer needs it. Still accepted so older scripts keep running.").hideHelp())
+        .option("--return-to <path>", "In-product destination after OAuth approval.")
+        .option("--json", "Print a JSON envelope."), INTEGRATION_CONNECT_ACCOUNT_CONTRACT, {
+        account_id: {
+            valueName: "<id>",
+            help: "Provider account id for integrations that span multiple accounts (e.g. Cloudflare when the token can access more than one account).",
+        },
+    })
+        .action(async (integrationId, options) => {
+        await handleAsyncAction("integrations connect", options, () => {
+            const apiKey = readOption(options.apiKey)?.trim();
+            const credentials = readNamedCredentials(options.credential);
+            const country = readOption(options.country)?.trim();
+            const pairingPhoneNumber = readOption(options.pairingPhoneNumber)?.trim();
+            return requestOxygen("/api/cli/integrations/connect", {
+                method: "POST",
+                body: {
+                    integration_id: integrationId,
+                    ...(apiKey ? { api_key: apiKey } : {}),
+                    ...(credentials ? { credentials } : {}),
+                    ...readContractFlags(options, INTEGRATION_CONNECT_ACCOUNT_CONTRACT),
+                    ...(readOption(options.returnTo) ? { return_to: readOption(options.returnTo) } : {}),
+                    ...(country ? { country } : {}),
+                    ...(pairingPhoneNumber ? { pairing_phone_number: pairingPhoneNumber } : {}),
+                    ...(options.acknowledgeRisk ? { acknowledge_linkedin_risk: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("test")
+        .description("Re-validate a stored integration API key against the provider and heal the connection when it passes (recovers benched or scope-degraded connections without re-pasting the key).")
+        .argument("<integration_id>", "Integration id, such as 'instantly'.")
+        .option("--connection-id <id>", "Test a specific connected account when multiple exist.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (integrationId, options) => {
+        const connectionId = readOption(options.connectionId)?.trim();
+        await handleAsyncAction("integrations test", options, () => requestOxygen("/api/cli/integrations/test", {
+            method: "POST",
+            body: {
+                integration_id: integrationId,
+                ...(connectionId ? { connection_id: connectionId } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("disconnect")
+        .description("Disconnect an integration. LinkedIn and WhatsApp remove the connected account; pass --connection-id when more than one is connected.")
+        .argument("<integration_id>", "Integration id, such as 'slack'.")
+        .option("--connection-id <id>", "Disconnect a specific connected account when multiple exist.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (integrationId, options) => {
+        const connectionId = readOption(options.connectionId)?.trim();
+        await handleAsyncAction("integrations disconnect", options, () => requestOxygen("/api/cli/integrations/disconnect", {
+            method: "POST",
+            body: {
+                integration_id: integrationId,
+                ...(connectionId ? { connection_id: connectionId } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("actions")
+        .description("List actions available for a connected integration — Composio toolkits and native providers (e.g. Instantly) alike.")
+        .argument("<integration_id>", "Integration id, such as 'slack'.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (integrationId, options) => {
+        await handleAsyncAction("integrations actions", options, () => {
+            const params = new URLSearchParams({ integration_id: integrationId });
+            return requestOxygen(`/api/cli/integrations/composio/actions?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("destinations")
+        .description("List where a connected integration can send — for Microsoft Teams, your teams and your chats, plus one team's channels with --team-id. Free: these are read-only lookups, so no approval or credit cap is needed.")
+        .argument("<integration_id>", "Integration id. Supported: 'microsoft_teams'.")
+        .option("--team-id <id>", "List this team's channels as well.")
+        .option("--kind <kind>", "Narrow to one of: teams, channels, chats. Default lists teams and chats.")
+        .option("--connection-id <id>", "Use a specific connection when several are active.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (integrationId, options) => {
+        await handleAsyncAction("integrations destinations", options, () => {
+            const params = new URLSearchParams({ integration_id: integrationId });
+            const teamId = readOption(options.teamId);
+            if (teamId)
+                params.set("team_id", teamId);
+            const kind = readOption(options.kind);
+            if (kind)
+                params.set("kind", kind);
+            const connectionId = readOption(options.connectionId);
+            if (connectionId)
+                params.set("connection_id", connectionId);
+            return requestOxygen(`/api/cli/integrations/destinations?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("run")
+        .description("Run an action for a connected integration — Composio toolkits and native providers alike.")
+        .argument("<integration_id>", "Integration id, such as 'slack'.")
+        .argument("<action_slug>", "Composio action slug, such as 'SLACK_SEND_MESSAGE'.")
+        .option("--connection-id <id>", "Select this workspace connection.")
+        .option("--credential-mode <mode>", "managed, user_api_key, or user_oauth.")
+        .option("--input <json>", "Arguments as JSON object. Default: empty object.")
+        .option("--live", "Execute the action live. Default is dry-run.")
+        .option("--dry-run", "Force dry-run (no provider call).")
+        .option("--mode <mode>", "'live' or 'dry_run'. Overridden by --live/--dry-run if provided.")
+        .option("--approved", "Required for live actions after inspecting dry-run output.")
+        .option("--max-credits <n>", "Required positive credit cap for live actions.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (integrationId, actionSlug, options) => {
+        await handleAsyncAction("integrations run", options, () => {
+            const args = readOption(options.input)
+                ? parseJsonObject(readOption(options.input))
+                : {};
+            const mode = resolveComposioRunMode(options);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            return requestOxygen("/api/cli/integrations/composio/run", {
+                method: "POST",
+                body: {
+                    integration_id: integrationId,
+                    action_slug: actionSlug,
+                    arguments: args,
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+                    mode,
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                },
+            });
+        });
+    }));
+}

package/dist/commands/knowledge.d.ts

@@ -0,0 +1,3 @@
+import { ExtractedCommandActionHandler } from "../command-support.js";
+import { Command } from "commander";
+export declare function registerKnowledgeFamily(program: Command, handleAsyncAction: ExtractedCommandActionHandler): void;