@ivora/cli 0.0.0-placeholder → 0.1.0

package/dist/commands/api.js

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import { findOperation, getOperationIds, pathParams } from '../catalog.js';
+import { CliError, ExitCode } from '../lib/output.js';
+import { openSession } from '../lib/session.js';
+import { callOperation, resolveTenant } from '../lib/resource.js';
+function keyValues(flag, values) {
+    const result = {};
+    for (const v of values) {
+        const i = v.indexOf('=');
+        if (i < 1)
+            throw new CliError(`${flag} expects name=value, got "${v}".`, ExitCode.Usage);
+        result[v.slice(0, i)] = v.slice(i + 1);
+    }
+    return result;
+}
+const collect = (value, previous) => [...previous, value];
+export function apiCommand(ctx) {
+    return new Command('api')
+        .description('call a read-only (GET) API operation by operationId')
+        .argument('[operation-id]', 'an operationId from the catalog (omit to list them)')
+        .option('--path <name=value>', 'path parameter (repeatable)', collect, [])
+        .option('--query <name=value>', 'query parameter (repeatable)', collect, [])
+        .option('--tenant <id>', 'value for {tenant_id} (default: the key’s only tenant)')
+        .action(async (operationId, opts) => {
+        if (operationId === undefined) {
+            ctx.out().result(getOperationIds().map((id) => ({ operation_id: id })));
+            return;
+        }
+        const op = findOperation(operationId);
+        if (!op) {
+            throw new CliError(`Unknown operation "${operationId}". Run \`ivora api\` to list them.`, ExitCode.Usage);
+        }
+        if (op.method !== 'GET') {
+            throw new CliError(`${operationId} is a ${op.method} operation. \`ivora api\` only calls GET operations for now.`, ExitCode.Usage);
+        }
+        const params = keyValues('--path', opts.path);
+        const query = keyValues('--query', opts.query);
+        const s = await openSession(ctx);
+        if (pathParams(op.path).includes('tenant_id') && params.tenant_id === undefined) {
+            params.tenant_id = await resolveTenant(ctx, s, opts.tenant);
+        }
+        const res = await callOperation(s, operationId, params, { query });
+        // Responses are arbitrary shapes: print JSON in both modes.
+        ctx.out().rawJson(res.data);
+    });
+}

package/dist/commands/login.js

@@ -0,0 +1,85 @@
+import { Command, Option } from 'commander';
+import { CliError, ExitCode } from '../lib/output.js';
+import { ApiClient } from '../lib/http.js';
+import { DEFAULT_PROFILE, assertKeyMatchesProfile, keyRefFor, loadConfig, resolveBaseUrl, saveConfig, validateBaseUrl, validateProfileName, } from '../lib/profiles.js';
+import { accessEnvironment, defaultTenant } from '../lib/access.js';
+import { displayPrefix } from '../lib/secrets.js';
+async function readAll(stream) {
+    let text = '';
+    stream.setEncoding?.('utf8');
+    for await (const chunk of stream)
+        text += String(chunk);
+    return text;
+}
+/** The key comes from IVORA_API_KEY, stdin (piped) or a hidden prompt. Never from argv. */
+async function obtainKey(ctx) {
+    const fromEnv = ctx.env.IVORA_API_KEY?.trim();
+    if (fromEnv)
+        return fromEnv;
+    const raw = ctx.stdin.isTTY
+        ? await ctx.readSecret('API key: ')
+        : ((await readAll(ctx.stdin)).split(/\r?\n/, 1)[0] ?? '');
+    const key = raw.trim();
+    if (!key)
+        throw new CliError('No API key given (pipe it on stdin or type it).', ExitCode.Usage);
+    return key;
+}
+export function loginCommand(ctx) {
+    return new Command('login')
+        .description('verify an API key and save it to a profile (key from stdin, prompt or IVORA_API_KEY)')
+        .addOption(new Option('--base-url <url>', 'API origin to store with the profile'))
+        .action(async (opts) => {
+        const g = ctx.globals();
+        const config = await loadConfig(ctx.env);
+        const name = validateProfileName(g.profile ?? (g.live ? 'live' : DEFAULT_PROFILE));
+        const existing = config.profiles[name];
+        const environment = g.live ? 'live' : (existing?.environment ?? 'test');
+        if (existing && existing.environment !== environment) {
+            throw new CliError(`Profile "${name}" is a ${existing.environment} profile; pick another name.`, ExitCode.Usage);
+        }
+        if (environment === 'live' && !g.live) {
+            throw new CliError('Logging in to a live profile needs --live.', ExitCode.Usage);
+        }
+        const profile = {
+            ...(existing ?? { name, environment }),
+            name,
+            environment,
+            ...(opts.baseUrl ? { baseUrl: validateBaseUrl(opts.baseUrl) } : {}),
+            keyRef: keyRefFor(name),
+        };
+        const apiKey = await obtainKey(ctx);
+        assertKeyMatchesProfile(apiKey, profile);
+        const baseUrl = resolveBaseUrl(profile, ctx.env, (text) => ctx.out().info(`note: ${text}`));
+        // Verify before saving anything.
+        const client = new ApiClient({
+            baseUrl,
+            apiKey,
+            apiVersion: g.apiVersion,
+            ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+        });
+        const access = (await client.request('GET', '/v1/access')).data ?? {};
+        const serverEnvironment = accessEnvironment(access);
+        if (serverEnvironment && serverEnvironment !== environment) {
+            throw new CliError(`The server says this is a ${serverEnvironment} key, not a ${environment} one. Nothing was saved.`, ExitCode.Usage);
+        }
+        const tenantId = defaultTenant(access, (text) => ctx.out().info(`note: ${text}`));
+        if (tenantId)
+            profile.tenantId = tenantId;
+        else
+            delete profile.tenantId;
+        await (await ctx.secrets()).set(profile.keyRef, apiKey);
+        config.profiles[name] = profile;
+        // Only a test profile may become the default; live always needs --live.
+        if (environment === 'test')
+            config.current ??= name;
+        await saveConfig(config, ctx.env);
+        const out = ctx.out();
+        out.result({
+            profile: name,
+            environment,
+            key: displayPrefix(apiKey),
+            tenant_id: profile.tenantId,
+            api_base: baseUrl,
+        });
+    });
+}

package/dist/commands/operations.js

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+import { addListOptions, addTenantOption, runGet, runList } from '../lib/resource.js';
+export function operationsCommand(ctx) {
+    const cmd = new Command('operations').description('read charger operations (never re-dispatches)');
+    addListOptions(cmd.command('list'), 'before')
+        .description('list operations, newest first')
+        .option('--status <status>', 'filter by status')
+        .option('--kind <kind>', 'filter by kind')
+        .option('--actor <actor>', 'filter by actor')
+        .option('--station-id <id>', 'filter by station')
+        .action((opts) => runList(ctx, {
+        operationId: 'charging_and_operations_list_the_project_s_operations',
+        cursorParam: 'before',
+        columns: ['id', 'kind', 'status', 'actor', 'station_id', 'created_at'],
+    }, opts, {
+        status: opts.status,
+        kind: opts.kind,
+        actor: opts.actor,
+        station_id: opts.stationId,
+    }));
+    addTenantOption(cmd.command('get').argument('<operation-id>'))
+        .description('show one operation')
+        .action((id, opts) => runGet(ctx, 'charging_and_operations_inspect_an_operation_without_redispatching_it', 'operation_id', id, opts.tenant));
+    return cmd;
+}

package/dist/commands/profiles.js

@@ -0,0 +1,67 @@
+import { Command } from 'commander';
+import { CliError, ExitCode } from '../lib/output.js';
+import { confirmAction } from '../lib/confirm.js';
+import { loadConfig, saveConfig, validateProfileName } from '../lib/profiles.js';
+export function profilesCommand(ctx) {
+    const cmd = new Command('profiles').description('list, select and remove profiles');
+    cmd
+        .command('list', { isDefault: true })
+        .description('list profiles (no keys are shown)')
+        .action(async () => {
+        const config = await loadConfig(ctx.env);
+        const rows = Object.values(config.profiles).map((p) => ({
+            name: p.name,
+            environment: p.environment,
+            current: config.current === p.name ? '*' : '',
+            tenant_id: p.tenantId ?? '',
+            base_url: p.baseUrl ?? '',
+        }));
+        const out = ctx.out();
+        if (out.json)
+            out.result(rows);
+        else if (rows.length === 0)
+            out.info('No profiles. Run `ivora login`.');
+        else
+            out.result(rows, ['name', 'environment', 'current', 'tenant_id', 'base_url']);
+    });
+    cmd
+        .command('use <name>')
+        .description('set the default profile (test profiles only; live always needs --live)')
+        .action(async (rawName) => {
+        const name = validateProfileName(rawName);
+        const config = await loadConfig(ctx.env);
+        const profile = config.profiles[name];
+        if (!profile)
+            throw new CliError(`No profile "${name}".`, ExitCode.Usage);
+        if (profile.environment === 'live') {
+            throw new CliError('A live profile cannot be the default. Pass --live on each command that should use it.', ExitCode.Usage);
+        }
+        config.current = name;
+        await saveConfig(config, ctx.env);
+        ctx.out().line(`Default profile: ${name}`);
+    });
+    cmd
+        .command('remove <name>')
+        .description('remove a profile and its stored key')
+        .action(async (rawName) => {
+        const name = validateProfileName(rawName);
+        const config = await loadConfig(ctx.env);
+        const profile = config.profiles[name];
+        if (!profile)
+            throw new CliError(`No profile "${name}".`, ExitCode.Usage);
+        await confirmAction(ctx.prompter, {
+            environment: profile.environment,
+            summary: `Remove profile ${name} and its stored key`,
+            write: true,
+            yes: ctx.globals().yes,
+        });
+        if (profile.keyRef)
+            await (await ctx.secrets()).delete(profile.keyRef);
+        config.profiles = Object.fromEntries(Object.entries(config.profiles).filter(([key]) => key !== name));
+        if (config.current === name)
+            delete config.current;
+        await saveConfig(config, ctx.env);
+        ctx.out().line(`Removed profile ${name}`);
+    });
+    return cmd;
+}

package/dist/commands/stations.js

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import { addListOptions, addTenantOption, runGet, runList } from '../lib/resource.js';
+export function stationsCommand(ctx) {
+    const cmd = new Command('stations').description('read charging stations');
+    addListOptions(cmd.command('list'), 'after')
+        .description('list stations')
+        .option('--name <name>', 'filter by name')
+        .option('--charger-id <id>', 'filter by OCPP charger id')
+        .option('--external-reference <ref>', 'filter by your external reference')
+        .action((opts) => runList(ctx, {
+        operationId: 'stations_list_tenant_charging_stations',
+        cursorParam: 'after',
+        columns: ['id', 'name', 'charger_id', 'online', 'last_seen'],
+    }, opts, {
+        name: opts.name,
+        charger_id: opts.chargerId,
+        external_reference: opts.externalReference,
+    }));
+    addTenantOption(cmd.command('get').argument('<station-id>'))
+        .description('show one station')
+        .action((id, opts) => runGet(ctx, 'stations_read_station_and_connector_state', 'station_id', id, opts.tenant));
+    return cmd;
+}

package/dist/commands/tariffs.js

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { Command } from 'commander';
+import { CliError, ExitCode } from '../lib/output.js';
+import { openSession } from '../lib/session.js';
+import { addListOptions, addTenantOption, callOperation, parseIntOption, resolveTenant, runGet, runList, } from '../lib/resource.js';
+/** Reads JSON from a file path, or from stdin for `-`. */
+async function readJsonInput(ctx, what, source) {
+    let text;
+    try {
+        if (source === '-') {
+            const chunks = [];
+            for await (const c of ctx.stdin)
+                chunks.push(Buffer.from(c));
+            text = Buffer.concat(chunks).toString('utf8');
+        }
+        else {
+            text = await readFile(source, 'utf8');
+        }
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new CliError(`Cannot read ${what} JSON from ${source}: ${err.message}`, ExitCode.Usage);
+    }
+}
+export function tariffsCommand(ctx) {
+    const cmd = new Command('tariffs').description('read tariffs; quote and simulate prices');
+    addListOptions(cmd.command('list'), 'after')
+        .description('list tariffs')
+        .option('--external-reference <ref>', 'filter by your external reference')
+        .option('--include-archived', 'include archived tariffs')
+        .action((opts) => runList(ctx, {
+        operationId: 'tariffs_and_bills_read_tenant_billing_tariffs',
+        cursorParam: 'after',
+        columns: ['id', 'name', 'currency', 'external_reference'],
+    }, opts, {
+        external_reference: opts.externalReference,
+        include_archived: opts.includeArchived ? true : undefined,
+    }));
+    addTenantOption(cmd.command('get').argument('<tariff-id>'))
+        .description('show one tariff')
+        .action((id, opts) => runGet(ctx, 'tariffs_and_bills_read_one_tariff', 'tariff_id', id, opts.tenant));
+    addTenantOption(cmd.command('quote').argument('<tariff-id>'))
+        .description('price a session under a stored tariff (read-only)')
+        .requiredOption('--session <file>', 'session profile JSON file, or - for stdin')
+        .option('--location-id <id>', 'apply this location’s tax lines')
+        .action(async (id, opts) => {
+        const session = await readJsonInput(ctx, 'session', opts.session);
+        const locationId = parseIntOption('--location-id', opts.locationId);
+        const s = await openSession(ctx);
+        const tenant = await resolveTenant(ctx, s, opts.tenant);
+        const res = await callOperation(s, 'tariffs_and_bills_quote_a_session_s_cost_under_a_stored_tariff', { tenant_id: tenant, tariff_id: id }, {
+            body: { session, ...(locationId !== undefined ? { location_id: locationId } : {}) },
+            readOnly: true,
+        });
+        ctx.out().result(res.data ?? {});
+    });
+    addTenantOption(cmd.command('simulate'))
+        .description('price a session under a draft tariff that is not stored (read-only)')
+        .requiredOption('--tariff <file>', 'tariff definition JSON file, or - for stdin')
+        .requiredOption('--session <file>', 'session profile JSON file')
+        .option('--location-id <id>', 'apply this location’s tax lines')
+        .action(async (opts) => {
+        if (opts.tariff === '-' && opts.session === '-') {
+            throw new CliError('Only one of --tariff and --session can read stdin.', ExitCode.Usage);
+        }
+        const tariff = await readJsonInput(ctx, 'tariff', opts.tariff);
+        const session = await readJsonInput(ctx, 'session', opts.session);
+        const locationId = parseIntOption('--location-id', opts.locationId);
+        const s = await openSession(ctx);
+        const tenant = await resolveTenant(ctx, s, opts.tenant);
+        const res = await callOperation(s, 'tariffs_and_bills_simulate_a_tariff_draft_against_a_session', { tenant_id: tenant }, {
+            body: {
+                tariff,
+                session,
+                ...(locationId !== undefined ? { location_id: locationId } : {}),
+            },
+            readOnly: true,
+        });
+        ctx.out().result(res.data ?? {});
+    });
+    return cmd;
+}

package/dist/commands/webhooks.js

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import { addTenantOption, callOperation, resolveTenant, runGet } from '../lib/resource.js';
+import { openSession } from '../lib/session.js';
+export function webhooksCommand(ctx) {
+    const cmd = new Command('webhooks').description('read webhook endpoints');
+    addTenantOption(cmd.command('list'))
+        .description('list webhook endpoints')
+        .action(async (opts) => {
+        const s = await openSession(ctx);
+        const tenant = await resolveTenant(ctx, s, opts.tenant);
+        const res = await callOperation(s, 'webhooks_and_events_list_webhook_endpoints', { tenant_id: tenant });
+        const out = ctx.out();
+        const rows = (res.data?.data ?? []);
+        if (out.json)
+            out.result({ data: rows });
+        else
+            out.result(rows, ['id', 'url', 'status', 'events']);
+    });
+    addTenantOption(cmd.command('get').argument('<webhook-id>'))
+        .description('show one webhook endpoint')
+        .action((id, opts) => runGet(ctx, 'webhooks_and_events_read_one_webhook_endpoint', 'webhook_id', id, opts.tenant));
+    return cmd;
+}

package/dist/commands/whoami.js

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { accessEnvironment, accessKeyInfo, accessTenantIds } from '../lib/access.js';
+import { envTag } from '../lib/output.js';
+import { openSession } from '../lib/session.js';
+export function whoamiCommand(ctx) {
+    return new Command('whoami')
+        .description('show the profile, environment, tenant and scopes of the current key')
+        .action(async () => {
+        const s = await openSession(ctx);
+        const access = (await s.client.request('GET', '/v1/access')).data ?? {};
+        const caps = (await s.client.request('GET', '/v1/capabilities'))
+            .data;
+        const tenants = accessTenantIds(access);
+        const key = accessKeyInfo(access);
+        const result = {
+            profile: s.profile.name,
+            environment: accessEnvironment(access) ?? s.profile.environment,
+            api_base: s.baseUrl,
+            tenant_id: tenants.length === 1 ? tenants[0] : undefined,
+            tenants,
+            scopes: access.scopes ?? [],
+            ...(key ? { key } : {}),
+            capabilities: caps ?? {},
+        };
+        const out = ctx.out();
+        if (!out.json)
+            out.line(envTag(s.profile.environment));
+        out.result(result);
+    });
+}

package/dist/lib/access.js

@@ -0,0 +1,51 @@
+import { CliError, ExitCode } from './output.js';
+/**
+ * The profile environment for the server's `environment` value: "production" is a live key,
+ * "test" a test key. Undefined when the server does not say; an unknown value is refused, so a
+ * key is never saved for the wrong environment.
+ */
+export function accessEnvironment(access) {
+    if (access.environment === undefined)
+        return undefined;
+    if (access.environment === 'production')
+        return 'live';
+    if (access.environment === 'test')
+        return 'test';
+    throw new CliError(`The server reported an unknown environment ("${String(access.environment)}").`, ExitCode.Usage);
+}
+/** The tenant ids the key can reach, as strings. */
+export function accessTenantIds(access) {
+    if (!Array.isArray(access.tenants))
+        return [];
+    return access.tenants
+        .map((t) => t?.id)
+        .filter((id) => typeof id === 'number' && Number.isSafeInteger(id))
+        .map(String);
+}
+/**
+ * The tenant to remember for a key: the only one it can reach. With none or several there is no
+ * default, and `note` explains why.
+ */
+export function defaultTenant(access, note) {
+    const ids = accessTenantIds(access);
+    if (ids.length === 1)
+        return ids[0];
+    if (ids.length === 0)
+        note('this key has no tenant, so no default tenant is set.');
+    else
+        note(`this key can reach ${ids.length} tenants (${ids.join(', ')}); no default tenant is set.`);
+    return undefined;
+}
+/** The key details for display, when the server sends them. */
+export function accessKeyInfo(access) {
+    const key = access.key;
+    if (!key || typeof key !== 'object')
+        return undefined;
+    const info = {};
+    for (const field of ['id', 'prefix', 'label', 'created_at', 'expires_at']) {
+        const value = key[field];
+        if (typeof value === 'string' || typeof value === 'number')
+            info[field] = String(value);
+    }
+    return Object.keys(info).length > 0 ? info : undefined;
+}

package/dist/lib/confirm.js

@@ -0,0 +1,51 @@
+import { createInterface } from 'node:readline/promises';
+import { CliError, ExitCode, envTag } from './output.js';
+/** Prompts on stderr and reads stdin, so stdout stays clean for results. */
+export function ttyPrompter(input = process.stdin, output = process.stderr) {
+    return {
+        interactive: input.isTTY === true && output.isTTY === true,
+        async ask(question) {
+            const rl = createInterface({ input, output, terminal: true });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+    };
+}
+export function needsConfirmation(req) {
+    if (!req.write)
+        return false;
+    return req.dangerous === true || req.environment === 'live';
+}
+/** Resolves when the action may proceed; throws a CliError (exit 3) when it is refused. */
+export async function confirmAction(prompter, req) {
+    if (!needsConfirmation(req) || req.yes)
+        return;
+    if (!prompter.interactive) {
+        throw new CliError(`${req.summary}: confirmation needed. Pass --yes to run non-interactively.`, ExitCode.ConfirmRefused);
+    }
+    const answer = await prompter.ask(`${envTag(req.environment, req.project)} ${req.summary}. Continue? [y/N] `);
+    if (!/^(y|yes)$/i.test(answer.trim())) {
+        throw new CliError('Cancelled.', ExitCode.ConfirmRefused);
+    }
+}
+/**
+ * Type-the-name confirmation. Returns the confirmed name, which the caller sends to the API
+ * (the server checks it again). Non-interactive runs must pass --confirm-name.
+ */
+export async function confirmName(prompter, req) {
+    let typed = req.confirmName;
+    if (typed === undefined) {
+        if (!prompter.interactive) {
+            throw new CliError(`Pass --confirm-name "<name>" to confirm ${req.what} non-interactively.`, ExitCode.ConfirmRefused);
+        }
+        typed = await prompter.ask(`${envTag(req.environment, req.project)} Type "${req.expected}" to confirm ${req.what}: `);
+    }
+    if (typed.trim() !== req.expected) {
+        throw new CliError('The name did not match. Nothing was changed.', ExitCode.ConfirmRefused);
+    }
+    return req.expected;
+}