@myapihq/cli 1.0.82 → 1.1.0-wip.0

package/dist/commands/webhook.js

@@ -1,68 +1,84 @@
 import { webhook as sdkWebhook } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
+import { requireOrg } from '../helpers.js';
+export const SCHEMA = {
+    org: 'string',
+    name: 'string',
+    description: 'string',
+};
 export async function list(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi webhook list --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi webhook list [--org <id>]');
     const endpoints = await sdkWebhook.listEndpoints(config.api_key, orgId);
-    if (flags.json)
+    if (flags.json) {
         printJson(endpoints);
-    else
-        printTable(endpoints);
+        return;
+    }
+    printTable(endpoints, {
+        flags,
+        empty: 'No webhook endpoints yet. Create one with: myapi webhook create --name <name>',
+    });
 }
 export async function create(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
+    const orgId = requireOrg(flags, config, 'myapi webhook create --name <name> [--description <desc>] [--org <id>]');
     const name = flags.name;
+    if (!name)
+        error('Missing required arguments.\nUsage: myapi webhook create --name <name> [--description <desc>] [--org <id>]');
     const description = flags.description;
-    if (!orgId || !name) {
-        error("Missing required arguments.\nUsage: myapi webhook create --name <name> [--description <desc>] --org <id>\n(Or set defaults via: myapi config set-org <id>)");
-    }
     const res = await sdkWebhook.createEndpoint(config.api_key, orgId, name, description);
-    success(`Webhook created! ID: ${res.id}\nInbound URL: ${res.inbound_url}`);
+    success(`Webhook created! ID: ${res.id}\nInbound URL: ${res.url}`);
 }
 export async function del(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi webhook delete <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi webhook delete <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi webhook delete <id> [--org <id>]');
     await sdkWebhook.deleteEndpoint(config.api_key, orgId, id);
     success(`Webhook ${id} deleted`);
 }
 export async function delivery(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi webhook delivery <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi webhook delivery <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi webhook delivery <id> [--org <id>]');
     const res = await sdkWebhook.getDelivery(config.api_key, orgId, id);
     printJson(res);
 }
+// ── Dispatcher ───────────────────────────────────────────────────────────────
+const SUBCOMMAND_USAGE = {
+    'list': 'myapi webhook list [--org <id>] [--json]',
+    'create': 'myapi webhook create --name <name> [--description <desc>] [--org <id>]',
+    'delete': 'myapi webhook delete <id> [--org <id>]',
+    'delivery': 'myapi webhook delivery <delivery_id> [--org <id>]',
+};
 export async function run(subcommand, args, flags) {
     if (!subcommand || (flags.help && !subcommand)) {
-        info('Usage: myapi webhook <subcommand>\n\nSubcommands:\n  list       List all inbound webhook endpoints\n  create     Create a new endpoint to receive data (returns an inbound URL)\n  delete     Delete a webhook endpoint\n  delivery   Inspect a specific webhook delivery (headers, payload, status)\n\nNote: All webhook commands require the --org <id> flag.');
+        info(`Usage: myapi webhook <subcommand>
+
+Subcommands:
+  list       List all inbound webhook endpoints
+  create     Create a new endpoint to receive data (returns an inbound URL)
+  delete     Delete a webhook endpoint
+  delivery   Inspect a specific webhook delivery (payload, received_at)
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         return;
     }
     if (flags.help) {
-        if (subcommand === 'list')
-            info('Usage: myapi webhook list --org <id> [--json]\n\nLists all webhook endpoints for the organization, including their IDs and inbound slugs.');
-        else if (subcommand === 'create')
-            info('Usage: myapi webhook create --name <name> [--description <desc>] --org <id>\n\nCreates a new inbound webhook endpoint. Returns the unique inbound URL to give to third parties.');
-        else if (subcommand === 'delete')
-            info('Usage: myapi webhook delete <id> --org <id>\n\nPermanently deletes the specified webhook endpoint.');
-        else if (subcommand === 'delivery')
-            info('Usage: myapi webhook delivery <delivery_id> --org <id>\n\nRetrieves the exact HTTP headers, JSON payload, and processing status of a specific received webhook. Useful for debugging inbound data.');
+        const usage = SUBCOMMAND_USAGE[subcommand];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${subcommand}. Run "myapi webhook --help" for the list.`);
         return;
     }
-    if (subcommand === 'list')
-        await list(flags);
-    else if (subcommand === 'create')
-        await create(flags);
-    else if (subcommand === 'delete')
-        await del(args[0], flags);
-    else if (subcommand === 'delivery')
-        await delivery(args[0], flags);
-    else
-        error(`Unknown subcommand: ${subcommand}. Run "myapi webhook --help" for a list of valid subcommands.`);
+    switch (subcommand) {
+        case 'list': return list(flags);
+        case 'create': return create(flags);
+        case 'delete': return del(args[0], flags);
+        case 'delivery': return delivery(args[0], flags);
+        default: error(`Unknown subcommand: ${subcommand}. Run "myapi webhook --help" for a list of valid subcommands.`);
+    }
 }

package/dist/commands/workflow.d.ts

@@ -1,7 +1,13 @@
-export declare function list(flags: Record<string, string | boolean>): Promise<void>;
-export declare function create(flags: Record<string, string | boolean>): Promise<void>;
-export declare function enable(id: string, flags: Record<string, string | boolean>): Promise<void>;
-export declare function disable(id: string, flags: Record<string, string | boolean>): Promise<void>;
-export declare function del(id: string, flags: Record<string, string | boolean>): Promise<void>;
-export declare function runs(id: string, flags: Record<string, string | boolean>): Promise<void>;
-export declare function run(subcommand: string | undefined, args: string[], flags: Record<string, string | boolean>): Promise<void>;
+import type { FlagSchema } from '../flags.js';
+import { type Flags } from '../helpers.js';
+export declare const SCHEMA: FlagSchema;
+export declare function list(flags: Flags): Promise<void>;
+export declare function get(id: string, flags: Flags): Promise<void>;
+export declare function create(flags: Flags): Promise<void>;
+export declare function update(id: string, flags: Flags): Promise<void>;
+export declare function enable(id: string, flags: Flags): Promise<void>;
+export declare function disable(id: string, flags: Flags): Promise<void>;
+export declare function del(id: string, flags: Flags): Promise<void>;
+export declare function runs(id: string, flags: Flags): Promise<void>;
+export declare function getRun(runId: string, flags: Flags): Promise<void>;
+export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/workflow.js

@@ -1,107 +1,209 @@
 import { workflow as sdkWorkflow } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
+import { requireOrg } from '../helpers.js';
+export const SCHEMA = {
+    org: 'string',
+    name: 'string',
+    'endpoint-id': 'string',
+    steps: 'string',
+    'no-enable': 'boolean',
+};
+function summarizeWorkflow(w) {
+    return {
+        id: w.id,
+        name: w.name,
+        enabled: w.enabled,
+        endpoint_id: w.trigger_config?.endpoint_id ?? '',
+        steps: Array.isArray(w.steps) ? w.steps.length : 0,
+        created_at: w.created_at,
+    };
+}
+function summarizeRun(r) {
+    return {
+        id: r.id,
+        workflow_id: r.workflow_id,
+        status: r.status,
+        attempt: r.attempt,
+        error: r.error ?? '',
+        started_at: r.started_at ?? '',
+        finished_at: r.finished_at ?? '',
+        created_at: r.created_at,
+    };
+}
 export async function list(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi workflow list --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi workflow list [--org <id>]');
     const workflows = await sdkWorkflow.listWorkflows(config.api_key, orgId);
-    if (flags.json)
+    if (flags.json) {
         printJson(workflows);
-    else
-        printTable(workflows);
+        return;
+    }
+    printTable(workflows.map(summarizeWorkflow), {
+        flags,
+        empty: 'No workflows yet. Create one with: myapi workflow create --name <n> --endpoint-id <id> --steps <json>',
+    });
+}
+export async function get(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi workflow get <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow get <id> [--org <id>]');
+    const wf = await sdkWorkflow.getWorkflow(config.api_key, orgId, id);
+    printJson(wf);
 }
 export async function create(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
+    const orgId = requireOrg(flags, config, 'myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
     const name = flags.name;
     const endpointId = flags['endpoint-id'];
-    if (!orgId || !name || !endpointId || !flags.steps) {
-        error("Missing required arguments.\nUsage: myapi workflow create --name <name> --endpoint-id <id> --steps <json> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    if (!name || !endpointId || !flags.steps) {
+        error('Missing required arguments.\nUsage: myapi workflow create --name <name> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]');
     }
     let steps;
     try {
         steps = JSON.parse(flags.steps);
     }
-    catch (err) {
-        error("Invalid JSON for --steps");
+    catch {
+        error('Invalid JSON for --steps');
     }
     const wf = await sdkWorkflow.createWorkflow(config.api_key, orgId, {
         name,
         trigger_config: { endpoint_id: endpointId },
-        steps
+        steps,
     });
-    await sdkWorkflow.enableWorkflow(config.api_key, orgId, wf.id);
-    success(`Workflow created and enabled! ID: ${wf.id}`);
+    const shouldEnable = flags['no-enable'] !== true;
+    if (shouldEnable) {
+        await sdkWorkflow.enableWorkflow(config.api_key, orgId, wf.id);
+        success(`Workflow created and enabled! ID: ${wf.id}`);
+    }
+    else {
+        success(`Workflow created (disabled). ID: ${wf.id}`);
+    }
+}
+export async function update(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi workflow update <id> [--name <name>] [--endpoint-id <id>] [--steps <json>] [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow update <id> [--name <name>] [--endpoint-id <id>] [--steps <json>] [--org <id>]');
+    const payload = {};
+    if (typeof flags.name === 'string')
+        payload.name = flags.name;
+    if (typeof flags['endpoint-id'] === 'string')
+        payload.trigger_config = { endpoint_id: flags['endpoint-id'] };
+    if (typeof flags.steps === 'string') {
+        try {
+            payload.steps = JSON.parse(flags.steps);
+        }
+        catch {
+            error('Invalid JSON for --steps');
+        }
+    }
+    if (!payload.name && !payload.trigger_config && !payload.steps) {
+        error('Nothing to update. Provide at least one of --name, --endpoint-id, --steps.');
+    }
+    const wf = await sdkWorkflow.updateWorkflow(config.api_key, orgId, id, payload);
+    success(`Workflow ${wf.id} updated`);
 }
 export async function enable(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi workflow enable <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi workflow enable <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow enable <id> [--org <id>]');
     await sdkWorkflow.enableWorkflow(config.api_key, orgId, id);
     success(`Workflow ${id} enabled`);
 }
 export async function disable(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi workflow disable <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi workflow disable <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow disable <id> [--org <id>]');
     await sdkWorkflow.disableWorkflow(config.api_key, orgId, id);
     success(`Disabled workflow ${id}`);
 }
 export async function del(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi workflow delete <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi workflow delete <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow delete <id> [--org <id>]');
     await sdkWorkflow.deleteWorkflow(config.api_key, orgId, id);
     success(`Deleted workflow ${id}`);
 }
 export async function runs(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi workflow runs <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi workflow runs <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi workflow runs <workflow_id> [--org <id>]');
     const wRuns = await sdkWorkflow.listWorkflowRuns(config.api_key, orgId, id);
-    if (flags.json)
+    if (flags.json) {
         printJson(wRuns);
-    else
-        printTable(wRuns);
+        return;
+    }
+    printTable(wRuns.map(summarizeRun), {
+        flags,
+        empty: 'No runs yet for this workflow.',
+    });
+}
+export async function getRun(runId, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi workflow get-run <run_id> [--org <id>]');
+    if (!runId)
+        error('Missing required arguments.\nUsage: myapi workflow get-run <run_id> [--org <id>]');
+    const run = await sdkWorkflow.getWorkflowRun(config.api_key, orgId, runId);
+    printJson(run);
 }
+// ── Dispatcher ───────────────────────────────────────────────────────────────
+const SUBCOMMAND_USAGE = {
+    'list': 'myapi workflow list [--org <id>] [--json]',
+    'get': 'myapi workflow get <id> [--org <id>]',
+    'create': 'myapi workflow create --name <str> --endpoint-id <id> --steps <json> [--no-enable] [--org <id>]',
+    'update': 'myapi workflow update <id> [--name <str>] [--endpoint-id <id>] [--steps <json>] [--org <id>]',
+    'enable': 'myapi workflow enable <id> [--org <id>]',
+    'disable': 'myapi workflow disable <id> [--org <id>]',
+    'delete': 'myapi workflow delete <id> [--org <id>]',
+    'runs': 'myapi workflow runs <workflow_id> [--org <id>] [--json]',
+    'get-run': 'myapi workflow get-run <run_id> [--org <id>]',
+};
 export async function run(subcommand, args, flags) {
     if (!subcommand || (flags.help && !subcommand)) {
-        info('Usage: myapi workflow <subcommand>\n\nSubcommands:\n  list       List all workflows\n  create     Create and enable a new workflow\n  enable     Enable a workflow\n  disable    Disable a workflow\n  delete     Delete a workflow\n  runs       List recent executions (runs) of a workflow\n\nNote: All workflow commands require the --org <id> flag.');
+        info(`Usage: myapi workflow <subcommand>
+
+Subcommands:
+  list                 List all workflows
+  get <id>             Show a single workflow
+  create               Create a workflow (enabled by default; --no-enable to stage)
+  update <id>          Patch name / endpoint-id / steps
+  enable <id>          Enable a workflow
+  disable <id>         Disable a workflow
+  delete <id>          Delete a workflow
+  runs <workflow_id>   List recent executions of a workflow
+  get-run <run_id>     Show a single run with full payload
+
+Step types for --steps:
+  send_email     {"type":"send_email","from":"<mailbox>","to":"{{payload.email}}","subject":"...","template_id":"<id>"|"html":"..."}
+  slack_message  {"type":"slack_message","webhook_url":"https://hooks.slack.com/...","text":"...{{payload.field}}..."}
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         return;
     }
     if (flags.help) {
-        if (subcommand === 'list')
-            info('Usage: myapi workflow list --org <id> [--json]\n\nLists all workflows in your organization, showing their ID, name, status, and attached webhook endpoint.');
-        else if (subcommand === 'create')
-            info('Usage: myapi workflow create --name <name> --endpoint-id <id> --steps <json_array> --org <id>\n\nCreates a new webhook-triggered workflow and immediately enables it.\n\nArguments:\n  --name          A friendly name for your workflow.\n  --endpoint-id   The UUID of the my-webhook-api endpoint that will trigger this workflow.\n  --steps         A raw JSON array defining the actions to take when triggered.\n\nExample Steps Payload:\n  \'[{"type": "send_email", "from": "hello@example.com", "to": "{{payload.user.email}}", "subject": "Welcome!", "template_id": "abc-123"}]\n  \'[{"type": "slack_message", "webhook_url": "https://hooks.slack.com/...", "text": "New lead: {{payload.name}}"}]\'');
-        else if (subcommand === 'enable')
-            info('Usage: myapi workflow enable <id> --org <id>\n\nActivates a disabled workflow so it begins listening to its webhook trigger again.');
-        else if (subcommand === 'disable')
-            info('Usage: myapi workflow disable <id> --org <id>\n\nPauses a workflow. The attached webhook will still accept data, but the workflow steps will not execute.');
-        else if (subcommand === 'delete')
-            info('Usage: myapi workflow delete <id> --org <id>\n\nDeletes the workflow permanently.');
-        else if (subcommand === 'runs')
-            info('Usage: myapi workflow runs <workflow_id> --org <id> [--json]\n\nLists the 100 most recent executions of the specified workflow, including completion status and any error messages.');
+        const usage = SUBCOMMAND_USAGE[subcommand];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${subcommand}. Run "myapi workflow --help" for the list.`);
         return;
     }
-    if (subcommand === 'list')
-        await list(flags);
-    else if (subcommand === 'create')
-        await create(flags);
-    else if (subcommand === 'enable')
-        await enable(args[0], flags);
-    else if (subcommand === 'disable')
-        await disable(args[0], flags);
-    else if (subcommand === 'delete')
-        await del(args[0], flags);
-    else if (subcommand === 'runs')
-        await runs(args[0], flags);
-    else
-        error(`Unknown subcommand: ${subcommand}. Run "myapi workflow --help" for a list of valid subcommands.`);
+    switch (subcommand) {
+        case 'list': return list(flags);
+        case 'get': return get(args[0], flags);
+        case 'create': return create(flags);
+        case 'update': return update(args[0], flags);
+        case 'enable': return enable(args[0], flags);
+        case 'disable': return disable(args[0], flags);
+        case 'delete': return del(args[0], flags);
+        case 'runs': return runs(args[0], flags);
+        case 'get-run': return getRun(args[0], flags);
+        default: error(`Unknown subcommand: ${subcommand}. Run "myapi workflow --help" for a list of valid subcommands.`);
+    }
 }

package/dist/flags.d.ts

@@ -0,0 +1,8 @@
+export type FlagType = 'string' | 'boolean' | 'number';
+export type FlagSchema = Record<string, FlagType>;
+export declare const GLOBAL_FLAGS: FlagSchema;
+export interface ParsedArgs {
+    args: string[];
+    flags: Record<string, string | boolean | number>;
+}
+export declare function parseFlags(argv: string[], schema?: FlagSchema): ParsedArgs;

package/dist/flags.js

@@ -0,0 +1,88 @@
+// Per-command flag schemas. Each command file owns its own schema and passes
+// it to `parseFlags`, which knows whether `--foo` consumes the next token.
+//
+// This replaces the global VALUE_FLAGS allowlist that previously lived in
+// utils.ts — adding a new value flag without registering it would silently
+// turn it into a boolean (e.g. `--html '<p>'` becoming `flags.html === true`).
+// Flags every command understands.
+export const GLOBAL_FLAGS = {
+    help: 'boolean',
+    json: 'boolean',
+    verbose: 'boolean',
+    yes: 'boolean',
+    y: 'boolean',
+};
+export function parseFlags(argv, schema = {}) {
+    const merged = { ...GLOBAL_FLAGS, ...schema };
+    const args = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '-h') {
+            flags.help = true;
+            continue;
+        }
+        if (arg === '-v') {
+            flags.version = true;
+            continue;
+        }
+        if (arg === '--') {
+            // Everything after `--` is positional.
+            args.push(...argv.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith('--')) {
+            let key;
+            let inlineValue;
+            if (arg.includes('=')) {
+                const eq = arg.indexOf('=');
+                key = arg.slice(2, eq);
+                inlineValue = arg.slice(eq + 1);
+            }
+            else {
+                key = arg.slice(2);
+            }
+            const type = merged[key];
+            // Unknown flags: tolerate as boolean (with --key=value still honored)
+            // so additions to the schema don't silently break someone's script.
+            if (type === undefined) {
+                flags[key] = inlineValue ?? true;
+                continue;
+            }
+            if (type === 'boolean') {
+                if (inlineValue !== undefined) {
+                    flags[key] = inlineValue !== 'false' && inlineValue !== '0';
+                }
+                else {
+                    flags[key] = true;
+                }
+                continue;
+            }
+            // Value flag (string | number).
+            let raw = inlineValue;
+            if (raw === undefined) {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    raw = next;
+                    i++;
+                }
+            }
+            if (raw === undefined) {
+                // Value flag with no value — keep as boolean true so callers can
+                // detect "they tried to pass it" and surface a helpful usage error.
+                flags[key] = true;
+                continue;
+            }
+            if (type === 'number') {
+                const n = Number(raw);
+                flags[key] = isNaN(n) ? raw : n;
+            }
+            else {
+                flags[key] = raw;
+            }
+            continue;
+        }
+        args.push(arg);
+    }
+    return { args, flags };
+}

package/dist/flags.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flags.test.js

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { parseFlags } from './flags.js';
+const SCHEMA = {
+    org: 'string',
+    name: 'string',
+    years: 'number',
+    'no-enable': 'boolean',
+};
+describe('parseFlags', () => {
+    it('treats unknown flags as boolean by default (forward-compatible)', () => {
+        const { args, flags } = parseFlags(['funnel', 'get', '--json', 'abc-123'], SCHEMA);
+        expect(flags.json).toBe(true);
+        expect(args).toEqual(['funnel', 'get', 'abc-123']);
+    });
+    it('treats global booleans (--yes, --help, --verbose) as boolean', () => {
+        const { flags } = parseFlags(['--yes', '--help', '--verbose'], SCHEMA);
+        expect(flags.yes).toBe(true);
+        expect(flags.help).toBe(true);
+        expect(flags.verbose).toBe(true);
+    });
+    it('consumes the next token for declared string flags', () => {
+        const { args, flags } = parseFlags(['org', 'create', '--name', 'Acme Inc', '--yes'], SCHEMA);
+        expect(flags.name).toBe('Acme Inc');
+        expect(flags.yes).toBe(true);
+        expect(args).toEqual(['org', 'create']);
+    });
+    it('supports --key=value for any flag', () => {
+        const { flags } = parseFlags(['--org=abc-123', '--json'], SCHEMA);
+        expect(flags.org).toBe('abc-123');
+        expect(flags.json).toBe(true);
+    });
+    it('declared string flag with no next token becomes boolean true', () => {
+        const { flags } = parseFlags(['--name'], SCHEMA);
+        expect(flags.name).toBe(true);
+    });
+    it('declared string flag followed by another flag does not consume it', () => {
+        const { flags } = parseFlags(['--org', '--json'], SCHEMA);
+        expect(flags.org).toBe(true);
+        expect(flags.json).toBe(true);
+    });
+    it('-h maps to help', () => {
+        const { flags } = parseFlags(['-h'], SCHEMA);
+        expect(flags.help).toBe(true);
+    });
+    it('-v maps to version', () => {
+        const { flags } = parseFlags(['-v'], SCHEMA);
+        expect(flags.version).toBe(true);
+    });
+    it('collects positional args correctly', () => {
+        const { args, flags } = parseFlags(['domain', 'register', 'example.com', '--org', 'uuid-here'], SCHEMA);
+        expect(args).toEqual(['domain', 'register', 'example.com']);
+        expect(flags.org).toBe('uuid-here');
+    });
+    it('parses declared number flags as numbers', () => {
+        const { flags } = parseFlags(['--years', '3'], SCHEMA);
+        expect(flags.years).toBe(3);
+        expect(typeof flags.years).toBe('number');
+    });
+    it('declared boolean flag does not consume next token', () => {
+        const { args, flags } = parseFlags(['--no-enable', 'abc'], SCHEMA);
+        expect(flags['no-enable']).toBe(true);
+        expect(args).toEqual(['abc']);
+    });
+    it('-- terminator: everything after is positional', () => {
+        const { args, flags } = parseFlags(['--name', 'X', '--', '--not-a-flag', 'y'], SCHEMA);
+        expect(flags.name).toBe('X');
+        expect(args).toEqual(['--not-a-flag', 'y']);
+    });
+    it('unknown --key=value preserved as a string (not silently lost)', () => {
+        const { flags } = parseFlags(['--mystery=42'], SCHEMA);
+        expect(flags.mystery).toBe('42');
+    });
+});

package/dist/helpers.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from './config.js';
+export type Flags = Record<string, string | boolean | number>;
+export declare function requireOrg(flags: Flags, config: Config, usage: string): string;
+export declare function requireDomain(arg: string | undefined, flags: Flags, config: Config, usage: string): string;
+export declare function requireArg(value: string | undefined, name: string, usage: string): string;
+export declare function requireFlag(flags: Flags, name: string, usage: string): string;

package/dist/helpers.js

@@ -0,0 +1,29 @@
+import { error } from './output.js';
+// Resolve org id from --org or the configured default. On miss, exit with a
+// usage-aware error that points the user at both the flag and the config command.
+export function requireOrg(flags, config, usage) {
+    const orgId = flags.org || config.default_org;
+    if (!orgId || typeof orgId !== 'string') {
+        error(`Missing required arguments.\nUsage: ${usage}\n(Or set default: myapi config set-org <id>)`);
+    }
+    return orgId;
+}
+export function requireDomain(arg, flags, config, usage) {
+    const domain = arg || flags.domain || config.default_domain;
+    if (!domain || typeof domain !== 'string') {
+        error(`Missing required arguments.\nUsage: ${usage}\n(Or set default: myapi config set-domain <domain>)`);
+    }
+    return domain;
+}
+export function requireArg(value, name, usage) {
+    if (!value)
+        error(`Missing required argument: ${name}.\nUsage: ${usage}`);
+    return value;
+}
+export function requireFlag(flags, name, usage) {
+    const v = flags[name];
+    if (v === undefined || v === true || v === false || v === '') {
+        error(`Missing required flag: --${name}.\nUsage: ${usage}`);
+    }
+    return String(v);
+}