octoparse-cli 0.1.14

package/dist/commands/auth.js

@@ -0,0 +1,283 @@
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { firstPositionalArg, hasFlag, valueAfter } from '../cli/args.js';
+import { printEnvelope, printUsageError } from '../cli/output.js';
+import { API_BASE_URL_ENV, ApiRequestError, validateApiKey } from '../runtime/api-client.js';
+import { API_KEY_ENV, maskApiKey, normalizeApiKey, removeApiKey, resolveAuth, saveApiKey } from '../runtime/auth.js';
+import { EXIT_OK, EXIT_OPERATION_FAILED } from '../types.js';
+export const API_KEYS_URL = 'https://www.octoparse.com/console/account-center/api-keys';
+export async function authCommand(subcommand, args) {
+    const json = hasFlag([subcommand ?? '', ...args], '--json');
+    if (subcommand === 'login') {
+        return authLogin(args);
+    }
+    if (subcommand === 'status') {
+        return authStatus(args);
+    }
+    if (subcommand === 'logout') {
+        return authLogout(args);
+    }
+    return printUsageError(json, 'Error: invalid auth subcommand', 'Usage: octoparse auth <login|status|logout> [--json]');
+}
+export async function ensureAuthenticated(json) {
+    const auth = await resolveAuth();
+    if (auth.authenticated)
+        return EXIT_OK;
+    return printAuthRequired(json);
+}
+export function printAuthRequired(json) {
+    const message = [
+        'API key required.',
+        `Create one at ${API_KEYS_URL}, then run "octoparse auth login".`,
+        `For CI, set ${API_KEY_ENV}.`
+    ].join(' ');
+    if (json) {
+        printEnvelope(false, undefined, 'AUTH_REQUIRED', message);
+    }
+    else {
+        console.error('Authentication failed: an API key is required.');
+        console.error('');
+        console.error('Create an API key:');
+        console.error(`  ${API_KEYS_URL}`);
+        console.error('');
+        console.error('Then run:');
+        console.error('  octoparse auth login');
+        console.error('');
+        console.error(`For CI or scripts, set ${API_KEY_ENV}.`);
+    }
+    return EXIT_OPERATION_FAILED;
+}
+async function authLogin(args) {
+    const json = hasFlag(args, '--json');
+    const readFromStdin = hasFlag(args, '--stdin');
+    const providedApiKey = normalizeApiKey(firstPositionalArg(args, ['--api-base-url']) ?? '');
+    const shouldOpen = shouldOpenApiKeyPage(args, json, readFromStdin, Boolean(providedApiKey));
+    try {
+        if (!providedApiKey && !readFromStdin && !json) {
+            printLoginInstructions(shouldOpen);
+        }
+        if (shouldOpen) {
+            await openUrl(API_KEYS_URL);
+        }
+        const apiKey = providedApiKey
+            ? providedApiKey
+            : readFromStdin
+                ? await readApiKeyFromStdin()
+                : await readSecretFromTty('Paste API key: ');
+        const validation = await validateApiKey({ apiKey, baseUrl: valueAfter(args, '--api-base-url') });
+        const credentials = await saveApiKey(apiKey);
+        const status = {
+            authenticated: true,
+            source: 'file',
+            keyPreview: maskApiKey(credentials.apiKey),
+            credentialsFile: join(homedir(), '.octoparse', 'credentials.json'),
+            verified: true,
+            apiBaseUrl: validation.baseUrl
+        };
+        if (json) {
+            printEnvelope(true, status);
+        }
+        else {
+            console.log(`API key verified and saved: ${status.keyPreview}`);
+            console.log(`API: ${status.apiBaseUrl}`);
+            console.log(`Credentials: ${status.credentialsFile}`);
+            console.log('');
+            console.log('Next:');
+            console.log('  octoparse task list');
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ApiRequestError ? error.code : 'AUTH_LOGIN_FAILED';
+        if (json)
+            printEnvelope(false, undefined, code, message);
+        else {
+            console.error(`Login failed: ${message}`);
+            console.error('API key was not saved.');
+            if (code === 'AUTH_INVALID') {
+                console.error('');
+                console.error('Check:');
+                console.error('  1. Whether the full API key was copied');
+                console.error(`  2. Whether the API key belongs to the current API environment, or check ${API_BASE_URL_ENV} / env status`);
+                console.error(`  3. Create a new API key: ${API_KEYS_URL}`);
+            }
+        }
+        return EXIT_OPERATION_FAILED;
+    }
+}
+function printLoginInstructions(willOpenBrowser) {
+    console.log('Octo Engine uses your Octoparse API key to verify your account and access tasks.');
+    console.log('');
+    if (willOpenBrowser) {
+        console.log('Opening API key page:');
+    }
+    else {
+        console.log('Create API key:');
+    }
+    console.log(`  ${API_KEYS_URL}`);
+    console.log('');
+    if (willOpenBrowser) {
+        console.log('If the browser did not open, copy the URL above.');
+    }
+    console.log('Create an API key in the browser, then paste it here.');
+    console.log('The key will be verified before it is saved locally.');
+    console.log('');
+}
+function shouldOpenApiKeyPage(args, json, readFromStdin, hasProvidedApiKey) {
+    if (json || readFromStdin || hasProvidedApiKey || hasFlag(args, '--no-open'))
+        return false;
+    if (process.env.CI === 'true')
+        return false;
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+function openUrl(url) {
+    const command = process.platform === 'darwin'
+        ? 'open'
+        : process.platform === 'win32'
+            ? 'cmd'
+            : 'xdg-open';
+    const args = process.platform === 'win32'
+        ? ['/c', 'start', '', url]
+        : [url];
+    return new Promise((resolveOpen) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: 'ignore'
+        });
+        child.on('error', () => resolveOpen());
+        child.unref();
+        resolveOpen();
+    });
+}
+async function authStatus(args) {
+    const json = hasFlag(args, '--json');
+    const auth = await resolveAuth();
+    if (!auth.authenticated || !auth.apiKey) {
+        if (json) {
+            return printAuthRequired(true);
+        }
+        console.log('Not authenticated');
+        console.log('Run: octoparse auth login');
+        return EXIT_OPERATION_FAILED;
+    }
+    try {
+        const validation = await validateApiKey({
+            apiKey: auth.apiKey,
+            baseUrl: valueAfter(args, '--api-base-url')
+        });
+        const { apiKey: _apiKey, ...status } = auth;
+        const result = {
+            ...status,
+            verified: true,
+            apiBaseUrl: validation.baseUrl
+        };
+        if (json) {
+            printEnvelope(true, result);
+            return EXIT_OK;
+        }
+        console.log(`Authenticated: yes (${status.source})`);
+        console.log('Verified: yes');
+        console.log(`API: ${validation.baseUrl}`);
+        console.log(`API key: ${status.keyPreview}`);
+        if (status.source === 'env') {
+            console.log(`Source: ${API_KEY_ENV}`);
+        }
+        else {
+            console.log(`Credentials: ${status.credentialsFile}`);
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = error instanceof ApiRequestError ? error.code : 'AUTH_STATUS_FAILED';
+        if (json) {
+            printEnvelope(false, undefined, code, message);
+        }
+        else {
+            console.error(`Authentication failed: ${message}`);
+            if (code === 'AUTH_INVALID') {
+                console.error('Re-login with: octoparse auth login');
+            }
+        }
+        return EXIT_OPERATION_FAILED;
+    }
+}
+async function authLogout(args) {
+    const json = hasFlag(args, '--json');
+    const removed = await removeApiKey();
+    const { apiKey: _apiKey, ...status } = await resolveAuth();
+    const result = { removed, ...status };
+    if (json) {
+        printEnvelope(true, result);
+        return EXIT_OK;
+    }
+    console.log(removed ? 'Stored API key removed' : 'No stored API key found');
+    if (status.authenticated && status.source === 'env') {
+        console.log(`${API_KEY_ENV} is still set and will continue to be used for this shell.`);
+    }
+    return EXIT_OK;
+}
+async function readApiKeyFromStdin() {
+    if (process.stdin.isTTY) {
+        throw new Error('Pass the API key through stdin when using --stdin');
+    }
+    let value = '';
+    process.stdin.setEncoding('utf8');
+    for await (const chunk of process.stdin) {
+        value += chunk;
+    }
+    const apiKey = value.trim();
+    if (!apiKey)
+        throw new Error('API key cannot be empty');
+    return apiKey;
+}
+function readSecretFromTty(prompt) {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    if (!stdin.isTTY || !stdout.isTTY) {
+        return Promise.reject(new Error('This is not an interactive terminal; use --stdin'));
+    }
+    return new Promise((resolveSecret, rejectSecret) => {
+        let value = '';
+        const wasRaw = stdin.isRaw;
+        const cleanup = () => {
+            stdin.off('data', handleData);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            stdout.write('\n');
+        };
+        const finish = () => {
+            cleanup();
+            const apiKey = value.trim();
+            apiKey ? resolveSecret(apiKey) : rejectSecret(new Error('API key cannot be empty'));
+        };
+        const handleData = (chunk) => {
+            const input = chunk.toString('utf8');
+            for (const char of input) {
+                if (char === '\u0003') {
+                    cleanup();
+                    rejectSecret(new Error('Cancelled'));
+                    return;
+                }
+                if (char === '\r' || char === '\n') {
+                    finish();
+                    return;
+                }
+                if (char === '\u007f' || char === '\b') {
+                    value = value.slice(0, -1);
+                    continue;
+                }
+                if (char >= ' ') {
+                    value += char;
+                }
+            }
+        };
+        stdout.write(prompt);
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', handleData);
+    });
+}

package/dist/commands/capabilities.js

@@ -0,0 +1,118 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { printEnvelope } from '../cli/output.js';
+import { API_BASE_URL_ENV } from '../runtime/api-client.js';
+import { API_KEY_ENV } from '../runtime/auth.js';
+import { EXIT_OK } from '../types.js';
+export async function capabilitiesCommand(version, json) {
+    const data = {
+        name: 'octoparse',
+        version,
+        agentContractVersion: 1,
+        authentication: {
+            requiredForUse: true,
+            loginVerifiesKeyBeforeSaving: true,
+            setupCommandsWithoutAuth: ['auth login', 'auth status', 'auth logout', 'env status', 'env prod', 'env online'],
+            diagnosticCommandsWithoutAuth: ['--help', '--version', 'capabilities', 'doctor', 'browser doctor'],
+            env: API_KEY_ENV,
+            file: join(homedir(), '.octoparse', 'credentials.json')
+        },
+        output: {
+            jsonEnvelope: { success: { ok: true, data: {} }, failure: { ok: false, error: { code: 'ERROR_CODE', message: 'message' } } },
+            jsonlEvents: ['run.started', 'row', 'log', 'run.paused', 'run.resumed', 'run.stopping', 'run.stopped'],
+            detachedBootstrap: ['bootstrap.json', 'stdout.log', 'stderr.log'],
+            stdout: 'machine data only in --json/--jsonl mode',
+            stderr: 'human diagnostics and failures'
+        },
+        machineContract: {
+            stable: true,
+            defaultOutput: 'human',
+            schemas: {
+                capabilities: 'schemas/capabilities-v1.schema.json',
+                jsonEnvelope: 'schemas/json-envelope-v1.schema.json',
+                runEvent: 'schemas/run-event-v1.schema.json',
+                detachedBootstrap: 'schemas/detached-bootstrap-v1.schema.json'
+            },
+            json: {
+                flag: '--json',
+                envelope: {
+                    successRequiredFields: ['ok', 'data'],
+                    failureRequiredFields: ['ok', 'error.code', 'error.message']
+                },
+                usageErrorsUseEnvelope: true,
+                commonErrorCodes: [
+                    'AUTH_REQUIRED',
+                    'AUTH_INVALID',
+                    'USAGE_ERROR',
+                    'UNKNOWN_COMMAND',
+                    'TASK_INVALID',
+                    'RUN_FORMAT_UNSUPPORTED',
+                    'DETACHED_RUN_FAILED',
+                    'ENGINE_RUN_FAILED',
+                    'LOCAL_RUN_ALREADY_RUNNING',
+                    'LOCAL_RUN_LIMIT_EXCEEDED',
+                    'LOCAL_RUN_CONTROL_FAILED',
+                    'RUN_CONTROL_FAILED',
+                    'RUN_NOT_FOUND',
+                    'LOCAL_LOT_NOT_FOUND',
+                    'UNSUPPORTED_EXPORT_FORMAT'
+                ]
+            },
+            jsonl: {
+                flag: '--jsonl',
+                command: 'run <taskId>',
+                eventField: 'event',
+                stableEvents: ['run.started', 'row', 'log', 'run.paused', 'run.resumed', 'run.stopping', 'run.stopped'],
+                rowLimitFlag: '--max-rows'
+            },
+            artifacts: {
+                localRunDir: ['meta.json', 'control.json', 'events.jsonl', 'logs.jsonl', 'rows.jsonl'],
+                detachedBootstrapDir: ['bootstrap.json', 'stdout.log', 'stderr.log']
+            },
+            lifecycle: {
+                detachModel: 'child-process',
+                daemonRequired: false,
+                activeRunIdentity: 'taskId',
+                artifactRunIdentity: 'runId',
+                maxActiveLocalRunsPerTaskId: 1,
+                orphanDetection: true,
+                cleanupCommands: ['local cleanup', 'runs cleanup']
+            }
+        },
+        exitCodes: {
+            0: 'success',
+            1: 'operation failed',
+            2: 'runtime/environment failure',
+            3: 'unsupported task definition'
+        },
+        commands: [
+            { command: 'doctor', risk: 'low', json: true, authRequired: false },
+            { command: 'auth login/status/logout', risk: 'medium', json: true, authRequired: false },
+            { command: 'env prod/online/status', risk: 'medium', json: true, hidden: true, authRequired: false },
+            { command: 'task list', risk: 'low', json: true, authRequired: true },
+            { command: 'task inspect/validate', risk: 'low', json: true, authRequired: true },
+            { command: 'run <taskId>', risk: 'medium', json: true, jsonl: true, authRequired: true },
+            { command: 'cloud start/stop <taskId>', risk: 'medium', json: true, authRequired: true },
+            { command: 'cloud status/history <taskId>', risk: 'low', json: true, authRequired: true },
+            { command: 'local status/history <taskId>', risk: 'low', json: true, authRequired: true },
+            { command: 'local cleanup', risk: 'low', json: true, authRequired: true },
+            { command: 'local export <taskId>', risk: 'medium', json: true, authRequired: true },
+            { command: 'local pause/resume/stop <taskId>', risk: 'medium', json: true, authRequired: true },
+            { command: 'data history <taskId>', risk: 'low', json: true, authRequired: true },
+            { command: 'data export <taskId>', risk: 'medium', json: true, authRequired: true },
+            { command: 'runs list/status/logs/data', risk: 'low', json: true, internal: true, authRequired: true },
+            { command: 'runs cleanup', risk: 'low', json: true, internal: true, authRequired: true }
+        ],
+        dataSources: ['local', 'cloud'],
+        exportFormats: ['xlsx', 'csv', 'html', 'json', 'xml'],
+        env: {
+            apiKey: API_KEY_ENV,
+            apiBaseUrl: API_BASE_URL_ENV
+        }
+    };
+    if (json)
+        printEnvelope(true, data);
+    else
+        console.log(JSON.stringify(data, null, 2));
+    return EXIT_OK;
+}

package/dist/commands/cloud.js

@@ -0,0 +1,241 @@
+import { firstPositionalArg, hasFlag, valueAfter } from '../cli/args.js';
+import { printEnvelope, printUsageError } from '../cli/output.js';
+import { printAuthRequired } from './auth.js';
+import { ApiRequestError, fetchCloudDataBatch, fetchCloudHistory, fetchCloudStatus, startCloudTask, stopCloudTask } from '../runtime/api-client.js';
+import { resolveAuth } from '../runtime/auth.js';
+import { EXIT_OK, EXIT_OPERATION_FAILED } from '../types.js';
+export async function cloudCommand(subcommand, args) {
+    const json = hasFlag([subcommand ?? '', ...args], '--json');
+    if (subcommand === 'start' || subcommand === 'stop') {
+        return cloudAction(subcommand, args);
+    }
+    if (subcommand === 'status') {
+        return cloudStatus(args);
+    }
+    if (subcommand === 'history') {
+        return cloudHistory(args);
+    }
+    return printUsageError(json, 'Error: invalid cloud subcommand; cloud extraction supports start/stop, not pause/resume.', 'Usage: octoparse cloud <start|stop|status|history> <taskId> [--json]');
+}
+async function cloudAction(command, args) {
+    const taskId = firstPositionalArg(args, ['--api-base-url']);
+    const json = hasFlag(args, '--json');
+    if (!taskId) {
+        return printUsageError(json, 'Error: missing taskId', `Usage: octoparse cloud ${command} <taskId> [--json]`);
+    }
+    const auth = await resolveAuth();
+    if (!auth.authenticated || !auth.apiKey) {
+        return printAuthRequired(json);
+    }
+    try {
+        const result = command === 'start'
+            ? await startCloudTask({ apiKey: auth.apiKey, taskId, baseUrl: valueAfter(args, '--api-base-url') })
+            : await stopCloudTask({ apiKey: auth.apiKey, taskId, baseUrl: valueAfter(args, '--api-base-url') });
+        if (json) {
+            printEnvelope(true, { taskId, action: command, ...result });
+        }
+        else {
+            console.log(`Cloud ${command}: ${taskId}`);
+            printCloudApiResult(result);
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        return printApiError(json, `Failed to ${command} cloud extraction`, error);
+    }
+}
+async function cloudStatus(args) {
+    const taskId = firstPositionalArg(args, ['--api-base-url']);
+    const json = hasFlag(args, '--json');
+    if (!taskId) {
+        return printUsageError(json, 'Error: missing taskId', 'Usage: octoparse cloud status <taskId> [--json]');
+    }
+    const auth = await resolveAuth();
+    if (!auth.authenticated || !auth.apiKey) {
+        return printAuthRequired(json);
+    }
+    try {
+        const result = await fetchCloudStatus({ apiKey: auth.apiKey, taskId, baseUrl: valueAfter(args, '--api-base-url') });
+        if (json) {
+            printEnvelope(true, { taskId, ...result });
+        }
+        else {
+            printCloudLiveInfo(taskId, result.data);
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        return printApiError(json, 'Failed to fetch cloud extraction status', error);
+    }
+}
+export async function cloudHistory(args) {
+    const taskId = firstPositionalArg(args, ['--api-base-url', '--source']);
+    const json = hasFlag(args, '--json');
+    if (!taskId) {
+        return printUsageError(json, 'Error: missing taskId', 'Usage: octoparse cloud history <taskId> [--json]');
+    }
+    const auth = await resolveAuth();
+    if (!auth.authenticated || !auth.apiKey) {
+        return printAuthRequired(json);
+    }
+    try {
+        const result = await fetchCloudHistory({ apiKey: auth.apiKey, taskId, baseUrl: valueAfter(args, '--api-base-url') });
+        const items = await withCloudExportStats({
+            apiKey: auth.apiKey,
+            taskId,
+            baseUrl: valueAfter(args, '--api-base-url'),
+            items: result.data
+        });
+        if (json) {
+            printEnvelope(true, { taskId, ...result, data: items });
+        }
+        else {
+            if (!items.length) {
+                console.log(`No cloud extraction history found: ${taskId}`);
+                return EXIT_OK;
+            }
+            console.log(`Cloud extraction history: ${taskId}\n`);
+            for (const item of items) {
+                const record = asRecord(item);
+                console.log(formatCloudHistoryLine(record));
+            }
+        }
+        return EXIT_OK;
+    }
+    catch (error) {
+        return printApiError(json, 'Failed to fetch cloud extraction history', error);
+    }
+}
+async function withCloudExportStats(options) {
+    return Promise.all(options.items.map(async (item) => {
+        const record = asRecord(item);
+        const lotId = stringValue(record.lot);
+        if (!lotId)
+            return item;
+        const stats = await fetchCloudExportStats({
+            apiKey: options.apiKey,
+            taskId: options.taskId,
+            lotId,
+            baseUrl: options.baseUrl
+        });
+        return stats ? { ...record, ...stats } : item;
+    }));
+}
+async function fetchCloudExportStats(options) {
+    try {
+        const result = await fetchCloudDataBatch({
+            apiKey: options.apiKey,
+            taskId: options.taskId,
+            lotId: options.lotId,
+            baseUrl: options.baseUrl,
+            offset: 0,
+            size: 1
+        });
+        const data = asRecord(result.data);
+        const uniqueRows = numberValue(data.total);
+        const duplicateRows = numberValue(data.duplicate);
+        if (uniqueRows === null && duplicateRows === null)
+            return null;
+        const resolvedUniqueRows = uniqueRows ?? 0;
+        return {
+            uniqueRows: resolvedUniqueRows,
+            duplicateRows: duplicateRows ?? 0,
+            exportRows: resolvedUniqueRows
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function formatCloudHistoryLine(record) {
+    const rows = String(record.extCnt ?? record.dataCnt ?? 0);
+    const uniqueRows = numberValue(record.uniqueRows);
+    const duplicateRows = numberValue(record.duplicateRows);
+    const exportStats = uniqueRows === null
+        ? ''
+        : `  uniqueRows=${uniqueRows}${duplicateRows && duplicateRows > 0 ? `  duplicateRows=${duplicateRows}` : ''}`;
+    return `  ${String(record.lot ?? '')}  ${cloudStatusName(record.status)}  rows=${rows}${exportStats}  ${String(record.startTime ?? record.startExtractTime ?? '')}`;
+}
+function printCloudApiResult(result) {
+    console.log(`API: ${result.baseUrl}${result.endpoint}`);
+    const data = asRecord(result.data);
+    if (!Object.keys(data).length) {
+        console.log('Result: ok');
+        return;
+    }
+    for (const [key, value] of Object.entries(data)) {
+        console.log(`${key}: ${formatValue(value)}`);
+    }
+}
+function printCloudLiveInfo(taskId, data) {
+    const info = asRecord(data);
+    if (!Object.keys(info).length) {
+        console.log(`${taskId}  no_status`);
+        return;
+    }
+    console.log(`${taskId}  ${cloudStatusName(info.status)}`);
+    if (info.lot !== undefined)
+        console.log(`Lot: ${String(info.lot)}`);
+    if (info.extCnt !== undefined || info.dataCnt !== undefined)
+        console.log(`Rows: ${String(info.extCnt ?? info.dataCnt)}`);
+    if (info.startTime !== undefined || info.startExtractTime !== undefined)
+        console.log(`Start: ${String(info.startTime ?? info.startExtractTime)}`);
+    if (info.endTime !== undefined)
+        console.log(`End: ${String(info.endTime)}`);
+    const progress = asRecord(info.stProg);
+    if (Object.keys(progress).length) {
+        console.log(`Subtasks: executing=${String(progress.executingCnt ?? 0)} finished=${String(progress.finishedCnt ?? 0)} stopped=${String(progress.stoppedCnt ?? 0)} waiting=${String(progress.waittingCnt ?? 0)}`);
+    }
+}
+function cloudStatusName(status) {
+    const value = Number(status);
+    if (value === -1)
+        return 'initializing';
+    if (value === 0 || value === 1)
+        return 'waiting';
+    if (value === 2 || value === 3)
+        return 'running';
+    if (value === 4)
+        return 'stopped';
+    if (value === 5)
+        return 'completed';
+    return status === undefined || status === null ? 'unknown' : String(status);
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value.trim() : value === undefined || value === null ? '' : String(value).trim();
+}
+function numberValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number.parseInt(value, 10);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function formatValue(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 printApiError(json, prefix, error) {
+    const code = error instanceof ApiRequestError ? error.code : 'API_REQUEST_FAILED';
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+        printEnvelope(false, undefined, code, message);
+    }
+    else {
+        console.error(`${code === 'AUTH_INVALID' ? 'Authentication failed' : prefix}: ${message}`);
+        if (error instanceof ApiRequestError && error.body && code !== 'AUTH_INVALID') {
+            console.error(`Response: ${error.body}`);
+        }
+    }
+    return EXIT_OPERATION_FAILED;
+}