@proxy-checkout/cli 0.1.0-prx-128.104.1

package/dist/esm/cli.js

@@ -0,0 +1,465 @@
+import { createInterface } from "node:readline/promises";
+import { login, logout, status } from "./auth.js";
+import { commandSchemaDocument, commandSchemas, llmsFullDocument } from "./command-schema.js";
+import { CliConfigStore } from "./config.js";
+import { asCliError, CliError, cliExitCodes, usageError } from "./errors.js";
+import { CliOutput } from "./output.js";
+import { forwardSelectedDelivery, ProxyWebhooksClient, runListener, } from "./webhooks.js";
+export const cliVersion = "0.1.0-prx-128.104.1";
+export async function runCli(argv, options = {}) {
+    const io = options.io ?? {
+        isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        stderr: process.stderr,
+        stdin: process.stdin,
+        stdout: process.stdout,
+    };
+    let output = new CliOutput(io.isTTY ? "human" : "jsonl", io);
+    let processSignal;
+    try {
+        const parsedGlobals = parseGlobalOptions([...argv], io, options.environment ?? process.env);
+        output = new CliOutput(parsedGlobals.options.format, io);
+        if (parsedGlobals.options.version) {
+            output.result({ version: cliVersion }, `proxy ${cliVersion}`);
+            return cliExitCodes.success;
+        }
+        if (parsedGlobals.options.llmsFull) {
+            const document = llmsFullDocument();
+            output.result({ document, schema_version: "2026-07-14" }, document);
+            return cliExitCodes.success;
+        }
+        if (parsedGlobals.args.join(" ") === "commands schema") {
+            output.result(commandSchemaDocument(), JSON.stringify(commandSchemaDocument(), null, 2));
+            return cliExitCodes.success;
+        }
+        const matched = matchCommand(parsedGlobals.args);
+        if (parsedGlobals.options.schema) {
+            if (!matched)
+                throw usageError("Unknown command for --schema");
+            const schema = commandSchemaDocument(matched.command.path);
+            if (!schema)
+                throw usageError("Unknown command for --schema");
+            output.result(schema, JSON.stringify(schema, null, 2));
+            return cliExitCodes.success;
+        }
+        if (!matched || parsedGlobals.options.help) {
+            output.result({ commands: commandSchemas.map((command) => command.path), version: cliVersion }, matched ? commandHelp(matched.command) : rootHelp());
+            return matched || parsedGlobals.options.help ? cliExitCodes.success : cliExitCodes.usage;
+        }
+        if (matched.command.streaming && parsedGlobals.options.format === "json") {
+            throw usageError("Streaming commands require --format jsonl or human");
+        }
+        assertRequestedMode(matched.command, parsedGlobals.options.expectedMode);
+        const commandOptions = parseCommandOptions(matched.args, matched.command.options);
+        const configStore = options.configStore ??
+            new CliConfigStore({ environment: options.environment ?? process.env });
+        const profileName = configStore.profileName(parsedGlobals.options.profileName ?? readOptionalString(commandOptions, "--profile"));
+        const requestedApiBase = parsedGlobals.options.apiBaseUrl ?? readOptionalString(commandOptions, "--api-base");
+        processSignal = options.signal ? undefined : createProcessSignal();
+        const signal = options.signal ?? processSignal?.signal;
+        if (!signal)
+            throw new Error("CLI abort signal was not initialized");
+        await executeCommand({
+            command: matched.command,
+            configStore,
+            expectedMerchantId: parsedGlobals.options.expectedMerchantId,
+            expectedMode: parsedGlobals.options.expectedMode,
+            io,
+            noInput: parsedGlobals.options.noInput,
+            options: commandOptions,
+            output,
+            profileName,
+            requestedApiBase,
+            signal,
+        });
+        return cliExitCodes.success;
+    }
+    catch (error) {
+        const cliError = asCliError(error);
+        output.error(cliError);
+        return cliError.exitCode;
+    }
+    finally {
+        processSignal?.dispose();
+    }
+}
+async function executeCommand(input) {
+    if (input.command.path === "auth login") {
+        const existingProfile = await input.configStore.readProfile(input.profileName);
+        const apiBaseUrl = input.configStore.apiBaseUrl(input.requestedApiBase, existingProfile);
+        const profile = await login({
+            apiBaseUrl,
+            configStore: input.configStore,
+            expectedMerchantId: input.expectedMerchantId,
+            expectedMode: input.expectedMode,
+            name: readOptionalString(input.options, "--name"),
+            noBrowser: readBoolean(input.options, "--no-browser"),
+            output: input.output,
+            profileName: input.profileName,
+            signal: input.signal,
+        });
+        input.output.result(publicProfile(input.profileName, profile), `Authenticated profile ${input.profileName} for test merchant ${profile.merchantId}.`);
+        return;
+    }
+    const resolved = await input.configStore.resolveCredential({
+        apiBaseUrl: input.requestedApiBase,
+        profileName: input.profileName,
+    });
+    if (input.command.path === "auth status") {
+        const remoteProfile = await status(resolved);
+        assertRemoteTarget(remoteProfile, input);
+        input.output.result({
+            profile: {
+                ...remoteProfile,
+                credential_source: resolved.source,
+                profile: resolved.profileName,
+            },
+        }, `Profile ${resolved.profileName} is authenticated for ${remoteProfile.merchant_id} (${remoteProfile.mode}).`);
+        return;
+    }
+    if (input.command.path === "auth logout") {
+        if (input.expectedMerchantId || input.expectedMode) {
+            assertRemoteTarget(await status(resolved), input);
+        }
+        await logout({
+            apiBaseUrl: resolved.apiBaseUrl,
+            configStore: input.configStore,
+            profileName: resolved.profileName,
+            removeLocalProfile: resolved.source !== "environment",
+            token: resolved.token,
+        });
+        input.output.result({ profile: resolved.profileName, revoked: true }, `Logged out profile ${resolved.profileName}.`);
+        return;
+    }
+    if (input.expectedMerchantId || input.expectedMode) {
+        assertRemoteTarget(await status(resolved), input);
+    }
+    const webhooks = new ProxyWebhooksClient(resolved.apiBaseUrl, resolved.token);
+    if (input.command.path === "webhooks endpoints list") {
+        const endpoints = await webhooks.listEndpoints();
+        input.output.result({ webhook_endpoints: endpoints }, formatEndpointList(endpoints));
+        return;
+    }
+    if (input.command.path === "webhooks listeners create") {
+        const listener = await webhooks.createListener(readRequiredString(input.options, "--endpoint"));
+        input.output.result({ listener }, `Created listener ${listener.id}; lease expires ${listener.lease_expires_at}.`);
+        return;
+    }
+    if (input.command.path === "webhooks listeners status") {
+        const listener = await webhooks.getListener(readRequiredString(input.options, "--listener"));
+        input.output.result({ listener }, `Listener ${listener.id} is ${listener.status}; lease expires ${listener.lease_expires_at}.`);
+        return;
+    }
+    if (input.command.path === "webhooks listeners heartbeat") {
+        const listener = await webhooks.heartbeat(readRequiredString(input.options, "--listener"));
+        input.output.result({ listener }, `Extended listener ${listener.id} through ${listener.lease_expires_at}.`);
+        return;
+    }
+    if (input.command.path === "webhooks listeners close") {
+        const listener = await webhooks.close(readRequiredString(input.options, "--listener"));
+        input.output.result({ listener }, `Closed listener ${listener.id}.`);
+        return;
+    }
+    if (input.command.path === "webhooks deliveries list") {
+        const deliveries = await webhooks.listDeliveries(readRequiredString(input.options, "--listener"), readOptionalInteger(input.options, "--limit"));
+        input.output.result({ deliveries }, `${deliveries.length} local webhook deliveries.`);
+        return;
+    }
+    if (input.command.path === "webhooks deliveries replay") {
+        const replay = await webhooks.replay(readRequiredString(input.options, "--listener"), readRequiredString(input.options, "--delivery"), readRequiredString(input.options, "--reason"));
+        input.output.result(replay, "Replay scheduled.");
+        return;
+    }
+    if (input.command.path === "webhooks deliveries forward") {
+        const deliveryId = readOptionalString(input.options, "--delivery");
+        const replayOutboxEventId = readOptionalString(input.options, "--replay-outbox");
+        if (Number(Boolean(deliveryId)) + Number(Boolean(replayOutboxEventId)) !== 1) {
+            throw usageError("Exactly one of --delivery or --replay-outbox is required");
+        }
+        const result = await forwardSelectedDelivery({
+            client: webhooks,
+            ...(deliveryId ? { deliveryId } : {}),
+            forwardTo: readRequiredString(input.options, "--forward-to"),
+            listenerId: readRequiredString(input.options, "--listener"),
+            ...(replayOutboxEventId ? { replayOutboxEventId } : {}),
+            signal: input.signal,
+        });
+        input.output.result(result, `Forwarded selected delivery ${result.webhook_delivery_id}.`);
+        return;
+    }
+    if (input.command.path === "listen") {
+        const endpoints = await webhooks.listEndpoints();
+        const sourceEndpointId = await selectEndpoint({
+            endpoints,
+            io: input.io,
+            noInput: input.noInput,
+            output: input.output,
+            requested: readOptionalString(input.options, "--endpoint"),
+        });
+        const maxEvents = readOptionalInteger(input.options, "--max-events") ?? 0;
+        if (maxEvents < 0)
+            throw usageError("--max-events must be zero or greater");
+        await runListener({
+            client: webhooks,
+            forwardTo: readRequiredString(input.options, "--forward-to"),
+            maxEvents,
+            output: input.output,
+            pspConfigId: readOptionalString(input.options, "--stripe-psp-config"),
+            signal: input.signal,
+            sourceEndpointId,
+            stripe: readBoolean(input.options, "--stripe"),
+        });
+        return;
+    }
+    throw usageError(`Unsupported command: ${input.command.path}`);
+}
+function parseGlobalOptions(args, io, environment) {
+    const defaultFormat = io.isTTY ? "human" : "jsonl";
+    const options = {
+        format: parseFormat(environment.PROXY_FORMAT ?? defaultFormat),
+        help: false,
+        llmsFull: false,
+        noInput: false,
+        schema: false,
+        version: false,
+    };
+    const remaining = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        const [name, inlineValue] = splitOption(argument);
+        if (name === "--format" ||
+            name === "--profile" ||
+            name === "--api-base" ||
+            name === "--merchant" ||
+            name === "--mode") {
+            const value = inlineValue ?? args[index + 1];
+            if (!value || value.startsWith("--"))
+                throw usageError(`${name} requires a value`);
+            if (inlineValue === undefined)
+                index += 1;
+            if (name === "--format")
+                options.format = parseFormat(value);
+            if (name === "--profile")
+                options.profileName = value;
+            if (name === "--api-base")
+                options.apiBaseUrl = value;
+            if (name === "--merchant") {
+                if (!/^merch_[A-Za-z0-9_-]+$/.test(value)) {
+                    throw usageError("--merchant must be a Proxy merchant ID");
+                }
+                options.expectedMerchantId = value;
+            }
+            if (name === "--mode") {
+                if (value !== "test" && value !== "live") {
+                    throw usageError("--mode must be test or live");
+                }
+                options.expectedMode = value;
+            }
+            continue;
+        }
+        if (name === "--no-input")
+            options.noInput = true;
+        else if (name === "--schema")
+            options.schema = true;
+        else if (name === "--llms-full")
+            options.llmsFull = true;
+        else if (name === "--help" || name === "-h")
+            options.help = true;
+        else if (name === "--version" || name === "-v")
+            options.version = true;
+        else
+            remaining.push(argument);
+    }
+    return { args: remaining, options };
+}
+function parseCommandOptions(args, schemas) {
+    const allowed = new Map(schemas.map((schema) => [schema.name, schema]));
+    const values = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument.startsWith("--"))
+            throw usageError(`Unexpected argument: ${argument}`);
+        const [name, inlineValue] = splitOption(argument);
+        const schema = allowed.get(name);
+        if (!schema)
+            throw usageError(`Unknown option for this command: ${name}`);
+        if (values.has(schema.name))
+            throw usageError(`Option may be specified only once: ${name}`);
+        if (schema.type === "boolean") {
+            if (inlineValue !== undefined)
+                throw usageError(`${name} does not accept a value`);
+            values.set(schema.name, true);
+            continue;
+        }
+        const raw = inlineValue ?? args[index + 1];
+        if (!raw || raw.startsWith("--"))
+            throw usageError(`${name} requires a value`);
+        if (inlineValue === undefined)
+            index += 1;
+        if (schema.type === "integer") {
+            if (!/^-?\d+$/.test(raw))
+                throw usageError(`${name} requires an integer`);
+            values.set(schema.name, Number(raw));
+        }
+        else {
+            values.set(schema.name, raw);
+        }
+    }
+    for (const schema of schemas) {
+        if (schema.required && !values.has(schema.name)) {
+            throw usageError(`Missing required option: ${schema.name}`);
+        }
+    }
+    return values;
+}
+function matchCommand(args) {
+    const sorted = [...commandSchemas].sort((left, right) => right.path.split(" ").length - left.path.split(" ").length);
+    for (const command of sorted) {
+        const parts = command.path.split(" ");
+        if (parts.every((part, index) => args[index] === part)) {
+            return { args: args.slice(parts.length), command };
+        }
+    }
+    return undefined;
+}
+async function selectEndpoint(input) {
+    if (input.requested) {
+        if (!input.endpoints.some((endpoint) => endpoint.id === input.requested)) {
+            throw new CliError("Requested source endpoint is not active or does not belong to this merchant", "cli_source_endpoint_not_found", cliExitCodes.conflict);
+        }
+        return input.requested;
+    }
+    if (input.endpoints.length === 0) {
+        throw new CliError("No active HTTPS webhook endpoint is available as a relay source", "cli_source_endpoint_required", cliExitCodes.conflict);
+    }
+    if (input.endpoints.length === 1)
+        return input.endpoints[0].id;
+    if (input.noInput || !input.io.isTTY) {
+        throw usageError("Multiple source endpoints are available; pass --endpoint with --no-input");
+    }
+    input.output.notice(input.endpoints
+        .map((endpoint, index) => `${index + 1}. ${endpoint.id} — ${endpoint.url}`)
+        .join("\n"));
+    const prompt = createInterface({
+        input: input.io.stdin,
+        output: input.io.stderr,
+    });
+    try {
+        const answer = await prompt.question("Select a source endpoint number: ");
+        const selected = input.endpoints[Number(answer) - 1];
+        if (!selected)
+            throw usageError("Invalid endpoint selection");
+        return selected.id;
+    }
+    finally {
+        prompt.close();
+    }
+}
+function publicProfile(profileName, profile) {
+    return {
+        profile: {
+            api_base_url: profile.apiBaseUrl,
+            api_version: profile.apiVersion,
+            capability_version: profile.capabilityVersion,
+            credential_id: profile.credentialId,
+            credential_store: profile.credentialStore,
+            expires_at: profile.expiresAt,
+            merchant_id: profile.merchantId,
+            mode: profile.mode,
+            name: profile.name,
+            organization_id: profile.organizationId,
+            profile: profileName,
+        },
+    };
+}
+function formatEndpointList(endpoints) {
+    return endpoints.length === 0
+        ? "No active HTTPS webhook endpoints."
+        : endpoints.map((endpoint) => `${endpoint.id}\t${endpoint.url}`).join("\n");
+}
+function parseFormat(value) {
+    if (value === "human" || value === "json" || value === "jsonl")
+        return value;
+    throw usageError("--format must be human, json, or jsonl");
+}
+function assertRequestedMode(command, mode) {
+    if (!mode || command.modes.includes(mode)) {
+        return;
+    }
+    throw new CliError(mode === "live"
+        ? "This CLI command is not enabled for live mode"
+        : "This CLI command is not enabled for the requested mode", mode === "live" ? "cli_live_mode_not_enabled" : "cli_mode_not_allowed", cliExitCodes.permission);
+}
+function assertRemoteTarget(profile, expected) {
+    if (expected.expectedMerchantId && profile.merchant_id !== expected.expectedMerchantId) {
+        throw new CliError("The CLI credential does not match the requested merchant", "cli_merchant_not_allowed", cliExitCodes.permission);
+    }
+    if (expected.expectedMode && profile.mode !== expected.expectedMode) {
+        throw new CliError("The CLI credential does not match the requested mode", expected.expectedMode === "live" ? "cli_live_mode_not_enabled" : "cli_mode_not_allowed", cliExitCodes.permission);
+    }
+}
+function splitOption(value) {
+    const separator = value.indexOf("=");
+    return separator < 0
+        ? [value, undefined]
+        : [value.slice(0, separator), value.slice(separator + 1)];
+}
+function readRequiredString(values, name) {
+    const value = values.get(name);
+    if (typeof value !== "string")
+        throw usageError(`Missing required option: ${name}`);
+    return value;
+}
+function readOptionalString(values, name) {
+    const value = values.get(name);
+    return typeof value === "string" ? value : undefined;
+}
+function readOptionalInteger(values, name) {
+    const value = values.get(name);
+    return typeof value === "number" ? value : undefined;
+}
+function readBoolean(values, name) {
+    return values.get(name) === true;
+}
+function createProcessSignal() {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once("SIGINT", abort);
+    process.once("SIGTERM", abort);
+    return {
+        signal: controller.signal,
+        dispose() {
+            process.removeListener("SIGINT", abort);
+            process.removeListener("SIGTERM", abort);
+        },
+    };
+}
+function rootHelp() {
+    return [
+        `Proxy CLI ${cliVersion}`,
+        "",
+        "Usage: proxy <command> [options]",
+        "",
+        ...commandSchemas.map((command) => `  ${command.path.padEnd(31)} ${command.description}`),
+        "",
+        "Global options:",
+        "  --format human|json|jsonl   Structured output (non-TTY default: jsonl)",
+        "  --no-input                  Prohibit prompts",
+        "  --profile NAME              Credential profile",
+        "  --merchant ID               Assert the target merchant",
+        "  --mode test|live            Assert the command mode",
+        "  --api-base URL              Proxy API base URL",
+        "  --schema                    Print a command's machine-readable schema",
+        "  --llms-full                 Print the complete agent-facing command reference",
+        "  --help                      Show help",
+        "  --version                   Show version",
+    ].join("\n");
+}
+function commandHelp(command) {
+    return [
+        `Usage: proxy ${command.path} [options]`,
+        "",
+        command.description,
+        "",
+        ...command.options.map((option) => `  ${option.name.padEnd(24)} ${option.description}`),
+    ].join("\n");
+}

package/dist/esm/command-schema.d.ts

@@ -0,0 +1,23 @@
+export type CommandOptionType = "boolean" | "integer" | "string";
+export interface CommandOptionSchema {
+    description: string;
+    env?: string;
+    name: `--${string}`;
+    required?: boolean;
+    sensitive?: boolean;
+    type: CommandOptionType;
+}
+export interface CommandSchema {
+    capabilities: string[];
+    description: string;
+    interactive: boolean;
+    modes: Array<"test" | "live">;
+    options: CommandOptionSchema[];
+    output: string;
+    path: string;
+    streaming?: boolean;
+}
+export declare const commandSchemas: readonly CommandSchema[];
+export declare function findCommandSchema(path: string): CommandSchema | undefined;
+export declare function commandSchemaDocument(path?: string): unknown;
+export declare function llmsFullDocument(): string;