@prospera/eprospera-cli 0.1.0

package/dist/src/index.js

@@ -0,0 +1,244 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Command, CommanderError } from "commander";
+import { runApplicationCreate } from "./commands/application/create.js";
+import { runApplicationGet } from "./commands/application/get.js";
+import { runApplicationList } from "./commands/application/list.js";
+import { runApplicationPay } from "./commands/application/pay.js";
+import { runApplicationWatch } from "./commands/application/watch.js";
+import { runAuthLogin } from "./commands/auth/login.js";
+import { runAuthLogout } from "./commands/auth/logout.js";
+import { runAuthWhoami } from "./commands/auth/whoami.js";
+import { runCompletion } from "./commands/completion.js";
+import { runConfigGet } from "./commands/config/get.js";
+import { runConfigList } from "./commands/config/list.js";
+import { runConfigSet } from "./commands/config/set.js";
+import { runConfigUnset } from "./commands/config/unset.js";
+import { runEntityDocuments } from "./commands/entity/documents.js";
+import { runEntityGet } from "./commands/entity/get.js";
+import { runEntitySearch } from "./commands/entity/search.js";
+import { runEntityVerify } from "./commands/entity/verify.js";
+import { runMeIdVerification } from "./commands/me/id-verification.js";
+import { runMeProfile } from "./commands/me/profile.js";
+import { runMeResidency } from "./commands/me/residency.js";
+import { runSchema } from "./commands/schema.js";
+import { ExitCodes, ExitError } from "./errors.js";
+import { printError } from "./output/format.js";
+import { VERSION } from "./version.js";
+export function createProgram(deps = {}) {
+    const program = new Command();
+    const stdout = deps.streams?.stdout ?? process.stdout;
+    const stderr = deps.streams?.stderr ?? process.stderr;
+    program
+        .name("eprospera")
+        .description("Command-line wrapper over the e-Prospera public API.")
+        .version(VERSION)
+        .showHelpAfterError()
+        .exitOverride()
+        .configureOutput({
+        writeOut: (value) => stdout.write(value),
+        writeErr: (value) => stderr.write(value),
+    })
+        .option("--json", "Pretty-print JSON to stdout and suppress incidental output.")
+        .option("--raw", "Print compact single-line JSON to stdout.")
+        .option("--fields <keys>", "Restrict output keys for read commands.")
+        .option("--quiet", "Suppress incidental human output.")
+        .option("-y, --yes", "Skip confirmation prompts.")
+        .option("--api-key <value>", "Use this bearer token instead of environment or stored credentials.")
+        .option("--dry-run", "Validate locally and print the request that would be sent.")
+        .option("--no-auto-json", "Disable automatic JSON output when stdout is not a TTY.")
+        .option("--skip-scope-check", "Skip cached local Agent Key scope preflight.");
+    const entity = program
+        .command("entity")
+        .description("Verify, search, inspect, and fetch documents.");
+    entity
+        .command("verify")
+        .argument("<rpn>")
+        .action(function (rpn) {
+        return runApplicationSafe(() => runEntityVerify(rpn, globals(this), deps));
+    });
+    entity
+        .command("search")
+        .argument("<query>")
+        .action(function (query) {
+        return runApplicationSafe(() => runEntitySearch(query, globals(this), deps));
+    });
+    entity
+        .command("get")
+        .argument("<id>")
+        .action(function (id) {
+        return runApplicationSafe(() => runEntityGet(id, globals(this), deps));
+    });
+    entity
+        .command("documents")
+        .argument("<id>")
+        .action(function (id) {
+        return runApplicationSafe(() => runEntityDocuments(id, globals(this), deps));
+    });
+    const application = program
+        .command("application")
+        .description("Create, pay, list, inspect, and watch applications.");
+    application.command("list").action(function () {
+        return runApplicationSafe(() => runApplicationList(globals(this), deps));
+    });
+    application
+        .command("create")
+        .requiredOption("--file <path>", "Read the application request body from a JSON file.")
+        .action(function () {
+        return runApplicationSafe(() => runApplicationCreate(this.opts(), globals(this), deps));
+    });
+    application
+        .command("get")
+        .argument("<id>")
+        .action(function (id) {
+        return runApplicationSafe(() => runApplicationGet(id, globals(this), deps));
+    });
+    application
+        .command("pay")
+        .argument("<id>")
+        .requiredOption("--coupon <code>", "Coupon code to apply.")
+        .action(function (id) {
+        return runApplicationSafe(() => runApplicationPay(id, this.opts(), globals(this), deps));
+    });
+    application
+        .command("watch")
+        .argument("<id>")
+        .option("--timeout <duration>", "Hard polling timeout.")
+        .option("--initial-interval <duration>", "Polling interval before backoff.")
+        .option("--max-interval <duration>", "Maximum polling interval after backoff.")
+        .action(function (id) {
+        return runApplicationSafe(() => runApplicationWatch(id, this.opts(), globals(this), deps));
+    });
+    const me = program.command("me").description("Read profile data for the credential owner.");
+    me.command("profile").action(function () {
+        return runApplicationSafe(() => runMeProfile(globals(this), deps));
+    });
+    me.command("residency").action(function () {
+        return runApplicationSafe(() => runMeResidency(globals(this), deps));
+    });
+    me.command("id-verification").action(function () {
+        return runApplicationSafe(() => runMeIdVerification(globals(this), deps));
+    });
+    const auth = program
+        .command("auth")
+        .description("Log in, inspect, and remove local credentials.");
+    auth
+        .command("login")
+        .option("--agent-key", "Prompt for an ak- Agent Key and validate it.")
+        .option("--standard-key", "Prompt for an sk- standard API key.")
+        .option("--scopes <csv>", "Comma-separated Agent Key scopes to cache.")
+        .action(function () {
+        return runApplicationSafe(() => runAuthLogin(this.opts(), globals(this), deps));
+    });
+    auth.command("whoami").action(function () {
+        return runApplicationSafe(() => runAuthWhoami(globals(this), deps));
+    });
+    auth.command("logout").action(function () {
+        return runApplicationSafe(() => runAuthLogout(globals(this), deps));
+    });
+    const config = program.command("config").description("Read and write local CLI configuration.");
+    config
+        .command("get")
+        .argument("<key>")
+        .action(function (key) {
+        return runApplicationSafe(() => runConfigGet(key, globals(this), deps));
+    });
+    config
+        .command("set")
+        .argument("<key>")
+        .argument("<value>")
+        .action(function (key, value) {
+        return runApplicationSafe(() => runConfigSet(key, value, globals(this), deps));
+    });
+    config.command("list").action(function () {
+        return runApplicationSafe(() => runConfigList(globals(this), deps));
+    });
+    config
+        .command("unset")
+        .argument("<key>")
+        .action(function (key) {
+        return runApplicationSafe(() => runConfigUnset(key, globals(this), deps));
+    });
+    const completion = program
+        .command("completion")
+        .description("Generate shell completion scripts.");
+    for (const shell of ["bash", "zsh", "fish"]) {
+        completion.command(shell).action(function () {
+            return runApplicationSafe(() => runCompletion(shell, globals(this), deps));
+        });
+    }
+    completion.command("powershell").action(function () {
+        return runApplicationSafe(() => runCompletion("powershell", globals(this), deps));
+    });
+    program
+        .command("schema")
+        .description("Print this OpenCLI document to stdout.")
+        .action(function () {
+        return runApplicationSafe(() => runSchema(globals(this), deps));
+    });
+    return program;
+}
+export async function runCli(argv = process.argv, deps = {}) {
+    const program = createProgram(deps);
+    try {
+        await program.parseAsync([...argv], { from: "node" });
+        return ExitCodes.Success;
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.exitCode === ExitCodes.Success) {
+            return ExitCodes.Success;
+        }
+        const globalsFromArgv = argvGlobals(argv);
+        if (error instanceof CommanderError) {
+            const result = printError(new ExitError({
+                code: "INVALID_USAGE",
+                message: error.message,
+                exitCode: ExitCodes.Usage,
+                cause: error,
+            }), {
+                json: globalsFromArgv.json,
+                raw: globalsFromArgv.raw,
+                noAutoJson: globalsFromArgv.autoJson === false,
+                streams: deps.streams,
+                env: deps.env,
+            });
+            return result.exitCode;
+        }
+        const result = printError(error, {
+            json: globalsFromArgv.json,
+            raw: globalsFromArgv.raw,
+            noAutoJson: globalsFromArgv.autoJson === false,
+            streams: deps.streams,
+            env: deps.env,
+        });
+        return result.exitCode;
+    }
+}
+function globals(command) {
+    const opts = command.optsWithGlobals();
+    return {
+        json: opts.json,
+        raw: opts.raw,
+        fields: opts.fields,
+        quiet: opts.quiet,
+        yes: opts.yes,
+        apiKey: opts.apiKey,
+        dryRun: opts.dryRun,
+        autoJson: opts.autoJson,
+        skipScopeCheck: opts.skipScopeCheck,
+    };
+}
+function argvGlobals(argv) {
+    return {
+        json: argv.includes("--json"),
+        raw: argv.includes("--raw"),
+        autoJson: argv.includes("--no-auto-json") ? false : undefined,
+    };
+}
+async function runApplicationSafe(action) {
+    await action();
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    process.exitCode = await runCli();
+}
+//# sourceMappingURL=index.js.map

package/dist/src/output/format.d.ts

@@ -0,0 +1,27 @@
+import { type ExitCode } from "../errors.js";
+import { type TablePreset } from "./table.js";
+import { type OutputMode, type OutputModeOptions, type TerminalLike } from "./tty.js";
+export type OutputWriter = TerminalLike & {
+    write(chunk: string): unknown;
+};
+export type OutputStreams = {
+    stdin?: TerminalLike;
+    stdout?: OutputWriter;
+    stderr?: OutputWriter;
+};
+export type PrintOptions = OutputModeOptions & {
+    quiet?: boolean;
+    fields?: string | readonly string[];
+    table?: TablePreset;
+    schema?: unknown;
+    env?: NodeJS.ProcessEnv;
+    streams?: OutputStreams;
+    human?: (data: unknown) => string;
+};
+export type PrintErrorResult = {
+    exitCode: ExitCode;
+};
+export declare function print(data: unknown, options?: PrintOptions): OutputMode;
+export declare function printError(error: unknown, options?: PrintOptions): PrintErrorResult;
+export declare function parseFields(fields: string | readonly string[] | undefined): string[];
+export declare function selectFields(data: unknown, fields: readonly string[]): unknown;

package/dist/src/output/format.js

@@ -0,0 +1,126 @@
+import { ExitCodes, ExitError } from "../errors.js";
+import { renderTable } from "./table.js";
+import { resolveOutputMode, terminalCapabilities, } from "./tty.js";
+export function print(data, options = {}) {
+    const streams = resolveStreams(options.streams);
+    const mode = resolveOutputMode(options, streams);
+    const selected = selectFields(data, parseFields(options.fields));
+    if (mode === "json") {
+        writeLine(streams.stdout, JSON.stringify(selected ?? null, null, 2));
+        return mode;
+    }
+    if (mode === "raw") {
+        writeLine(streams.stdout, JSON.stringify(selected ?? null));
+        return mode;
+    }
+    const capabilities = terminalCapabilities({ ...options, mode }, streams);
+    const rendered = options.human?.(selected) ??
+        renderTable(selected, options.table, {
+            color: capabilities.color,
+        });
+    writeLine(streams.stdout, rendered);
+    return mode;
+}
+export function printError(error, options = {}) {
+    const streams = resolveStreams(options.streams);
+    const mode = resolveOutputMode(options, streams);
+    const { envelope, exitCode } = errorEnvelope(error);
+    if (mode === "json") {
+        writeLine(streams.stdout, JSON.stringify(envelope, null, 2));
+        return { exitCode };
+    }
+    if (mode === "raw") {
+        writeLine(streams.stdout, JSON.stringify(envelope));
+        return { exitCode };
+    }
+    const capabilities = terminalCapabilities({ ...options, mode }, streams);
+    const prefix = capabilities.color ? "\u001b[31mError:\u001b[39m" : "Error:";
+    writeLine(streams.stderr, `${prefix} ${envelope.error.message}`);
+    return { exitCode };
+}
+export function parseFields(fields) {
+    if (!fields) {
+        return [];
+    }
+    const rawFields = typeof fields === "string" ? [fields] : fields;
+    const parsed = rawFields.flatMap((field) => field.split(",").map((part) => part.trim()));
+    return [...new Set(parsed.filter((field) => field.length > 0))];
+}
+export function selectFields(data, fields) {
+    if (fields.length === 0) {
+        return data;
+    }
+    if (Array.isArray(data)) {
+        return data.map((item) => selectObjectFields(item, fields));
+    }
+    return selectObjectFields(data, fields);
+}
+function selectObjectFields(data, fields) {
+    if (!isRecord(data)) {
+        return data;
+    }
+    const output = {};
+    for (const field of fields) {
+        const path = field.split(".").filter((part) => part.length > 0);
+        const value = readPath(data, path);
+        if (value !== undefined) {
+            writePath(output, path, value);
+        }
+    }
+    return output;
+}
+function readPath(data, path) {
+    let current = data;
+    for (const part of path) {
+        if (!isRecord(current) || !(part in current)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function writePath(output, path, value) {
+    let current = output;
+    for (const [index, part] of path.entries()) {
+        if (index === path.length - 1) {
+            current[part] = value;
+            return;
+        }
+        const next = current[part];
+        if (!isRecord(next)) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+}
+function errorEnvelope(error) {
+    if (error instanceof ExitError) {
+        return {
+            envelope: error.toEnvelope(),
+            exitCode: error.exitCode,
+        };
+    }
+    return {
+        envelope: {
+            error: {
+                code: "UNEXPECTED_ERROR",
+                message: error instanceof Error ? error.message : "Unexpected error.",
+            },
+        },
+        exitCode: ExitCodes.Generic,
+    };
+}
+function resolveStreams(streams) {
+    return {
+        stdin: streams?.stdin ?? process.stdin,
+        stdout: streams?.stdout ?? process.stdout,
+        stderr: streams?.stderr ?? process.stderr,
+    };
+}
+function writeLine(writer, value) {
+    writer.write(value.endsWith("\n") ? value : `${value}\n`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=format.js.map

package/dist/src/output/table.d.ts

@@ -0,0 +1,5 @@
+export type TablePreset = "entities" | "applications" | "documents";
+export type RenderTableOptions = {
+    color?: boolean;
+};
+export declare function renderTable(data: unknown, preset?: TablePreset, options?: RenderTableOptions): string;

package/dist/src/output/table.js

@@ -0,0 +1,124 @@
+import Table from "cli-table3";
+import pc from "picocolors";
+const PRESET_COLUMNS = {
+    entities: [
+        { key: "id", label: "ID" },
+        { key: "name", label: "Name" },
+        { key: "type", label: "Type" },
+        { key: "residentPermitNumber", label: "RPN" },
+    ],
+    applications: [
+        { key: "id", label: "ID" },
+        { key: "statusId", label: "Status" },
+        { key: "legalEntityId", label: "Legal Entity" },
+        { key: "createdAt", label: "Created" },
+    ],
+    documents: [
+        { key: "id", label: "ID" },
+        { key: "name", label: "Name" },
+        { key: "version", label: "Version" },
+        { key: "createdAt", label: "Created" },
+        { key: "fileUrl", label: "URL" },
+    ],
+};
+export function renderTable(data, preset, options = {}) {
+    const unwrapped = unwrapData(data);
+    if (preset) {
+        return renderRows(toRows(unwrapped), PRESET_COLUMNS[preset], options);
+    }
+    if (Array.isArray(unwrapped)) {
+        return renderRows(unwrapped, inferColumns(unwrapped), options);
+    }
+    if (isRecord(unwrapped)) {
+        return renderKeyValueTable(unwrapped, options);
+    }
+    return formatCell(unwrapped);
+}
+function renderRows(rows, columns, options) {
+    if (rows.length === 0) {
+        return "(empty)";
+    }
+    const table = new Table({
+        head: columns.map((column) => formatHeader(column.label, options.color)),
+        wordWrap: true,
+    });
+    for (const row of rows) {
+        table.push(columns.map((column) => formatCell(readPath(row, column.key))));
+    }
+    return table.toString();
+}
+function renderKeyValueTable(data, options) {
+    const table = new Table({
+        head: [formatHeader("Key", options.color), formatHeader("Value", options.color)],
+        wordWrap: true,
+    });
+    for (const [key, value] of Object.entries(data)) {
+        table.push([key, formatCell(value)]);
+    }
+    return table.toString();
+}
+function inferColumns(rows) {
+    const keys = new Set();
+    for (const row of rows) {
+        if (!isRecord(row)) {
+            return [{ key: "value", label: "Value" }];
+        }
+        for (const key of Object.keys(row)) {
+            keys.add(key);
+            if (keys.size >= 6) {
+                break;
+            }
+        }
+        if (keys.size >= 6) {
+            break;
+        }
+    }
+    return [...keys].map((key) => ({ key, label: humanizeKey(key) }));
+}
+function toRows(value) {
+    return Array.isArray(value) ? value : [value];
+}
+function unwrapData(data) {
+    if (isRecord(data) && "data" in data) {
+        return data.data;
+    }
+    return data;
+}
+function readPath(value, path) {
+    if (path === "value") {
+        return value;
+    }
+    let current = value;
+    for (const part of path.split(".")) {
+        if (!isRecord(current) || !(part in current)) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function formatCell(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function formatHeader(value, color) {
+    return color ? pc.bold(value) : value;
+}
+function humanizeKey(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .replace(/\b\w/g, (letter) => letter.toUpperCase());
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+//# sourceMappingURL=table.js.map

package/dist/src/output/tty.d.ts

@@ -0,0 +1,26 @@
+export type OutputMode = "human" | "json" | "raw";
+export type OutputModeOptions = {
+    json?: boolean;
+    raw?: boolean;
+    noAutoJson?: boolean;
+};
+export type TerminalCapabilityOptions = OutputModeOptions & {
+    mode?: OutputMode;
+    quiet?: boolean;
+    env?: NodeJS.ProcessEnv;
+};
+export type TerminalLike = {
+    isTTY?: boolean;
+};
+export type TerminalStreams = {
+    stdin?: TerminalLike;
+    stdout?: TerminalLike;
+    stderr?: TerminalLike;
+};
+export type TerminalCapabilities = {
+    color: boolean;
+    spinner: boolean;
+    interactive: boolean;
+};
+export declare function resolveOutputMode(options?: OutputModeOptions, streams?: TerminalStreams): OutputMode;
+export declare function terminalCapabilities(options?: TerminalCapabilityOptions, streams?: TerminalStreams): TerminalCapabilities;

package/dist/src/output/tty.js

@@ -0,0 +1,41 @@
+export function resolveOutputMode(options = {}, streams = {}) {
+    if (options.raw) {
+        return "raw";
+    }
+    if (options.json) {
+        return "json";
+    }
+    const stdout = streams.stdout ?? process.stdout;
+    if (!options.noAutoJson && !isTty(stdout)) {
+        return "json";
+    }
+    return "human";
+}
+export function terminalCapabilities(options = {}, streams = {}) {
+    const mode = options.mode ?? resolveOutputMode(options, streams);
+    const stdout = streams.stdout ?? process.stdout;
+    const stderr = streams.stderr ?? process.stderr;
+    const stdin = streams.stdin ?? process.stdin;
+    const env = options.env ?? process.env;
+    const machineMode = mode !== "human";
+    const quiet = options.quiet ?? false;
+    const decorationsAllowed = !machineMode && !quiet && isTty(stdout);
+    const noColor = isSet(env.NO_COLOR);
+    const forceColor = isEnabled(env.FORCE_COLOR);
+    const ci = isEnabled(env.CI);
+    return {
+        color: decorationsAllowed && !noColor && (!ci || forceColor),
+        spinner: decorationsAllowed && isTty(stderr) && !ci,
+        interactive: !machineMode && !quiet && isTty(stdin),
+    };
+}
+function isTty(stream) {
+    return stream.isTTY === true;
+}
+function isSet(value) {
+    return value !== undefined && value !== "";
+}
+function isEnabled(value) {
+    return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+}
+//# sourceMappingURL=tty.js.map

package/dist/src/polling/watch.d.ts

@@ -0,0 +1,19 @@
+export type WatchApplicationState = {
+    id?: string;
+    statusId?: string;
+    [key: string]: unknown;
+};
+export type WatchApplicationOptions = {
+    timeoutMs?: number;
+    initialIntervalMs?: number;
+    maxIntervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    onTransition?: (application: WatchApplicationState) => void | Promise<void>;
+};
+export type WatchApplicationResult = {
+    application: WatchApplicationState;
+    terminal: "approved";
+};
+export declare function watchApplication(fetchApplication: () => Promise<WatchApplicationState>, options?: WatchApplicationOptions): Promise<WatchApplicationResult>;
+export declare function parseDurationMs(value: string | undefined, fallbackMs: number): number;