zoodealio 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,259 @@
-# Temporary Holding Version
+# Zoodealio CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`zoodealio` is a command line wrapper over the partner API (`/openapi`). It prints JSON,
+takes JSON bodies, and describes itself, so people, scripts and AI agents can drive the
+same contract as the Zoodealio MCP server (`Mcp/OpenApiMcpTools.cs`) and the
+[Zapier app](../zapier/README.md). It adds no API surface: every command is one
+documented `/openapi` request, and bodies pass through unchanged.
+
+It has no runtime dependencies and needs Node 22 or newer.
+
+## Install
+
+```sh
+npm install -g zoodealio
+zoodealio login
+zoodealio whoami
+```
+
+or run it without installing: `npx zoodealio whoami` (after a `zoodealio login` elsewhere, or with
+`ZOODEALIO_API_KEY` set). From a checkout of this repo, `node integrations/cli/bin/zoodealio.js`
+runs the working copy.
+
+## Authenticate
+
+### Sign in (the default)
+
+```sh
+zoodealio login            # opens your browser; approve "Sign in Zoodealio CLI on <device>"
+zoodealio login --no-browser   # print the URL to stderr instead (SSH, containers)
+zoodealio login --name work-laptop   # device name shown at sign-in (default: this host)
+zoodealio logout           # revokes this machine's key and forgets it
+```
+
+`login` binds a loopback port, sends you to Zoodealio AI to approve, and exchanges the one-time
+code (with PKCE) for a personal API key named `CLI – <device>`. It waits up to 5 minutes. It prints
+`{ok, email, name, keyPrefix, origin}` and never the key.
+
+The key is stored per API origin in `$XDG_CONFIG_HOME/zoodealio/credentials.json`
+(default `~/.config/zoodealio/credentials.json`; `%APPDATA%\zoodealio\credentials.json` on Windows),
+written atomically with mode `0600` in a `0700` directory. Keys are per environment:
+`zoodealio login --env dev` stores a separate login. `ZOODEALIO_WEB_URL` overrides the sign-in
+page origin the way `ZOODEALIO_API_URL` overrides the API origin.
+
+### API key for CI and servers
+
+Copy a personal API key from **Settings → API** in Zoodealio AI and export it:
+
+```sh
+export ZOODEALIO_API_KEY=zoo_...
+```
+
+`ZOODEALIO_API_KEY` wins over a stored login. If neither is present the CLI exits 3 with
+`Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.` and sends nothing.
+A 401 on a stored login means it was revoked or expired; run `zoodealio login` again.
+
+The key is sent only as the `ApiKey` header. It is never printed: errors, `--dry-run` output and
+`whoami` show it as `zoo_…<last4>` (the one exception is `keys create`, whose purpose is to show a
+new key once). Redirects are refused so the header cannot be forwarded. The key keeps its owner's
+workspace and property scope. Every request sends `User-Agent: zoodealio-cli/<version>`.
+
+`zoodealio whoami` confirms the key works and shows the target origin, `source` (`login` or
+`env`) and, for a login, the `email`.
+
+### Keys
+
+```sh
+zoodealio keys list                 # your keys; "current" marks the one in use
+zoodealio keys create --name ci     # prints the raw key once
+zoodealio keys revoke <id> --yes
+```
+
+Key management needs a key created by `zoodealio login`; keys made with `keys create` or in the web
+app cannot manage keys.
+
+### MCP
+
+`zoodealio mcp` is a stdio MCP server that forwards each JSON-RPC message to the hosted
+`/openapi/mcp` endpoint with your key, so MCP clients need no HTTP or header setup.
+
+```sh
+claude mcp add zoodealio -- zoodealio mcp
+```
+
+Cursor (`.cursor/mcp.json`) or VS Code (`.vscode/mcp.json`, under `servers`):
+
+```json
+{ "mcpServers": { "zoodealio": { "command": "zoodealio", "args": ["mcp"] } } }
+```
+
+Run `zoodealio login` first (or put `ZOODEALIO_API_KEY` in the client's `env`). Stdout carries only
+JSON-RPC; logs go to stderr.
+
+## Environments
+
+| Selection | API origin |
+| --- | --- |
+| default | `https://api.zoodealio.ai` |
+| `--env dev` | `https://dev.api.zoodealio.ai` |
+| `ZOODEALIO_API_URL=http://localhost:5256` | that origin (overrides both) |
+
+Keys are per environment. Use a local API URL only for a local API; the port above is an
+example, use whichever yours runs on.
+
+## Output and errors
+
+stdout carries JSON and nothing else: pretty-printed on a terminal, compact when piped
+(`--pretty` forces pretty). An empty or 204 response prints `null`. Help text is the only
+non-JSON stdout.
+
+Failures print one JSON object on stderr and exit non-zero:
+
+```json
+{"error":{"status":404,"code":"not_found","title":"Not Found","detail":"..."}}
+```
+
+`title` and `detail` come from the API's problem response when present. `status` is `null`
+for usage and network errors. A 429 adds `retryAfter` in seconds.
+
+| Exit | Meaning | `code` |
+| --- | --- | --- |
+| 0 | Success | |
+| 1 | Other API or network error; login cancelled or timed out | `http_error`, `network_error`, `login_cancelled`, `login_timeout` |
+| 2 | Usage: unknown command or flag, missing argument, bad ID or JSON, missing `--yes`, or HTTP 400 | `usage`, `bad_request` |
+| 3 | Not signed in, or not authenticated or allowed (401, 403) | `unauthorized`, `forbidden` |
+| 4 | Not found (404) | `not_found` |
+| 5 | Conflict, precondition or validation failure (409, 412, 422) | `conflict`, `precondition_failed`, `validation_failed` |
+| 6 | Rate limited (429) | `rate_limited` |
+
+Route IDs are GUIDs and are checked before any request is made.
+
+## Global flags
+
+| Flag | Effect |
+| --- | --- |
+| `--env prod\|dev` | Pick the environment (default `prod`) |
+| `--pretty` | Pretty-print JSON even when piped |
+| `--dry-run` | Print `{method, url, headers, body}` with the key redacted and send nothing; works without a key |
+| `--yes` | Confirm a destructive command (not needed with `--dry-run`) |
+| `--help` | Help for the CLI or one command |
+
+Write bodies come from `--body '<json>'`, `--body @file.json` or `--body -` (stdin). Where
+a body is trivial, convenience flags build it instead; use one or the other, not both.
+List commands accept `--page` and `--page-size`. `--if-match <etag>` sends optimistic
+concurrency on `properties update`, `offers accept` and `offers request-details`.
+
+## Commands
+
+`zoodealio commands` prints the authoritative catalogue. In short:
+
+| Command | Request | Notes |
+| --- | --- | --- |
+| `properties list` | GET Properties | `--search`, `--state` |
+| `properties get <id>` | GET Properties/{id} | |
+| `properties create` | POST Properties | `--body` |
+| `properties update <id>` | PUT Properties/{id} | `--body`, `--if-match`; replaces wholesale |
+| `properties photos list\|add\|delete` | photos | `add`: `--url` (repeatable) or `--body`; `delete <id> <photoId>` needs `--yes` |
+| `properties documents list\|add\|delete` | documents | same shape as photos |
+| `properties import-status <id> <importId>` | GET imports/{importId} | Photo and document imports |
+| `offers list` | GET Offers | `--property` required, `--status` |
+| `offers get <id>`, `offers history <id>` | GET | |
+| `offers accept <id>` | POST accept | `--yes` required; `--attributes <json\|@file>`, `--if-match` |
+| `offers request-details <id>` | POST request-details | `--if-match` |
+| `transactions get <id>` | GET Transactions/{id} | |
+| `transactions active` | GET Transactions/active | `--property` required |
+| `comping status <transactionId>` | GET Transactions/{id}/comping | |
+| `team members`, `team get <id>`, `teams list` | GET Team | `--search` |
+| `team invite` | POST Team/members | `--email` (+ `--first-name`, `--last-name`, `--team`, `--admin-team`) or `--body` |
+| `team remove <id>` | DELETE Team/members/{id} | `--yes` required |
+| `webhooks event-types\|list\|deliveries` | GET Webhooks | `deliveries`: `--subscription`, `--status` |
+| `webhooks create` | POST Webhooks | `--url` and `--event` (repeatable) or `--body` |
+| `webhooks update <id>` | PUT Webhooks/{id} | `--body` (`endpointUrl`, `eventTypes`, `isActive`) |
+| `webhooks rotate <id>`, `webhooks delete <id>` | POST, DELETE | `--yes` required |
+| `login`, `logout` | | Browser sign-in and sign-out; `login` takes `--no-browser`, `--name` |
+| `keys list\|create\|revoke` | GET, POST, DELETE Keys | `create`: `--name`; `revoke <id>` needs `--yes`; needs a `login` key |
+| `mcp` | POST `/openapi/mcp` | stdio MCP bridge |
+| `whoami` | | Key check; prints `{ok, origin, key, source, email?}` |
+| `openapi` | GET `/_openapi/partner.json` | Partner OpenAPI document; no key needed |
+| `api <METHOD> <path>` | any `/openapi/...` | `--query k=v` (repeatable), `--body`; `DELETE` needs `--yes` |
+| `commands` | | Command catalogue as JSON |
+
+Destructive commands (`keys revoke`, `offers accept`, `team remove`, `properties photos delete`,
+`properties documents delete`, `webhooks rotate`, `webhooks delete`, and `api ... DELETE`)
+refuse to run without `--yes`, exit 2, and send nothing. `--dry-run` previews them
+without `--yes`, since it sends nothing either.
+
+`api` accepts `Properties` or `/openapi/Properties`. Paths that are absolute URLs, contain
+`..`, or fall outside `/openapi/` are rejected.
+
+## Examples
+
+```sh
+# Properties: search, then import photos from URLs
+zoodealio properties list --search "Elm St" --state AZ
+zoodealio properties photos add <propertyId> --url https://example.com/front.jpg
+zoodealio properties import-status <propertyId> <importId>
+
+# Offers: list for a property, preview an accept, then accept
+zoodealio offers list --property <propertyId>
+zoodealio offers accept <offerId> --dry-run
+zoodealio offers accept <offerId> --yes
+
+# Transactions and comping
+zoodealio transactions active --property <propertyId>
+zoodealio comping status <transactionId>
+
+# Team
+zoodealio team invite --email new@example.com --first-name Ada --team <teamId>
+
+# Webhooks: create a subscription (the signing secret is shown once)
+zoodealio webhooks create --url https://example.com/hooks --event offer.created --event comping.completed
+
+# Anything else under /openapi
+zoodealio api GET Properties --query pageSize=5
+```
+
+## For AI agents
+
+- Start with `zoodealio commands`. It lists every command with its method, path, arguments,
+  flags and a `destructive` marker, generated from the same table the parser uses.
+- stdout is JSON only and errors are JSON on stderr, so parse stdout on exit 0 and
+  stderr otherwise. Branch on the exit code (for example back off on 6 using `retryAfter`).
+- Run writes with `--dry-run` first and check the URL and body, then run them again
+  without it.
+- `--yes` is a gate for explicit human intent. Pass it only when the person asked for that
+  destructive action (accepting an offer, removing a member, deleting or rotating a
+  webhook); do not add it to make an error go away.
+- For request body shapes run `zoodealio openapi`, which prints the partner OpenAPI document.
+- Prefer webhooks, or polling `comping status` and `import-status`, to long waits. See
+  [OPEN_API_WEBHOOKS.md](../../docs/OPEN_API_WEBHOOKS.md) for events, signatures and delivery.
+
+## Limits
+
+- No multipart uploads of local files. Photos and documents are imported from URLs only
+  (`photos add --url`); `api` cannot send multipart either.
+- No keychain or interactive prompts. Credentials are `ZOODEALIO_API_KEY` or the
+  `credentials.json` written by `zoodealio login`.
+
+## Development
+
+```sh
+cd integrations/cli
+npm install
+npm run check   # eslint, tsc --noEmit (checkJs), node --test
+```
+
+## Releasing
+
+npm no longer lets a token that bypasses 2FA publish directly, so releases are staged and then
+approved by a maintainer with 2FA:
+
+```sh
+cd integrations/cli
+npm version <patch|minor|major> --no-git-tag-version   # in a PR, then merge
+npm run check
+npm stage publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
+```
+
+Then approve it on npmjs.com (avatar → Staged Packages → Approve). A version with a `-` suffix
+(`0.2.0-beta.1`) is staged with `--tag next` so `latest` stays stable.

package/bin/zoodealio.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const { run } = require('../src/cli');
+
+run(process.argv.slice(2), {
+    env: process.env,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+}).then((code) => {
+    process.exitCode = code;
+});

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "zoodealio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Zoodealio command line tool: the partner API as JSON, built for people, scripts and AI agents",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zoodealio-admin/zoodealioai-services.git",
+    "directory": "integrations/cli"
+  },
+  "homepage": "https://zoodealio.ai/developers",
+  "bin": {
+    "zoodealio": "bin/zoodealio.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --test-isolation=none test/*.test.js",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run lint && npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.1",
+    "@types/node": "22.19.0",
+    "eslint": "9.39.1",
+    "globals": "16.5.0",
+    "typescript": "5.9.3"
+  }
+}

package/src/args.js

@@ -0,0 +1,94 @@
+const { parseArgs } = require('node:util');
+const { usage } = require('./errors');
+const { COMMANDS, GLOBAL_FLAGS, GUID, helpText, usageLine } = require('./commands');
+
+/** @typedef {import('./commands').Command} Command */
+
+const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+/** One parseArgs option set covering every flag any command knows; per-command validity is checked after. */
+const OPTIONS = (() => {
+    /** @type {Record<string, {type: 'string' | 'boolean', multiple?: boolean}>} */
+    const options = {};
+    for (const f of [...GLOBAL_FLAGS, ...COMMANDS.flatMap((c) => c.flags)]) {
+        options[f.name] = f.type === 'string' ? { type: 'string', multiple: true } : { type: 'boolean' };
+    }
+    return options;
+})();
+
+/**
+ * @param {string[]} argv
+ * @returns {{help: string} | {command: Command, args: Record<string, string>, flags: Record<string, any>}}
+ */
+function parse(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    } catch (err) {
+        throw usage(/** @type {Error} */ (err).message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) return { help: helpText(positionals) };
+    if (positionals.length === 0) throw usage('missing command; run `zoodealio --help`');
+
+    let command;
+    for (const c of COMMANDS) {
+        const words = c.name.split(' ');
+        if (words.every((w, i) => positionals[i] === w) && (!command || words.length > command.name.split(' ').length)) command = c;
+    }
+    if (!command) throw usage(`unknown command: ${positionals.join(' ')}`);
+
+    const rest = positionals.slice(command.name.split(' ').length);
+    if (rest.length !== command.args.length) throw usage(`expected: ${usageLine(command)}`);
+    /** @type {Record<string, string>} */
+    const args = {};
+    command.args.forEach((a, i) => {
+        if (a.guid && !GUID.test(rest[i])) throw usage(`<${a.name}> must be a GUID, got: ${rest[i]}`);
+        args[a.name] = rest[i];
+    });
+
+    const allowed = new Map([...GLOBAL_FLAGS, ...command.flags].map((f) => [f.name, f]));
+    /** @type {Record<string, any>} */
+    const flags = {};
+    for (const [name, value] of Object.entries(values)) {
+        const spec = allowed.get(name);
+        if (!spec) throw usage(`--${name} is not valid for \`${command.name}\``);
+        if (spec.type === 'boolean') flags[name] = value;
+        else if (spec.multiple) flags[name] = value;
+        else if (/** @type {string[]} */ (value).length > 1) throw usage(`--${name} may be given only once`);
+        else flags[name] = /** @type {string[]} */ (value)[0];
+    }
+    for (const f of command.flags) if (f.required && flags[f.name] === undefined) throw usage(`missing required flag --${f.name}`);
+    return { command, args, flags };
+}
+
+/**
+ * Validates an `api` escape-hatch path and returns it rooted at /openapi/.
+ * @param {string} input
+ * @returns {string}
+ */
+function normalizeApiPath(input) {
+    const bad = () => usage(`api path must be under /openapi/ (got: ${input})`);
+    let decoded = input;
+    for (let i = 0; i < 4; i++) {
+        if (/(^|[\\/])\.\.?([\\/]|$)/.test(decoded) || /[\\?#]|:\/\/|^\/\//.test(decoded) || [...decoded].some((ch) => ch.charCodeAt(0) < 32)) throw bad();
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        } catch {
+            throw bad();
+        }
+        if (next === decoded) break;
+        decoded = next;
+    }
+    const trimmed = input.replace(/^\/+/, '');
+    const first = trimmed.split('/')[0].toLowerCase();
+    if (first === 'openapi') {
+        if (trimmed.split('/').length < 2 || !trimmed.split('/')[1]) throw bad();
+        return `/openapi/${trimmed.slice(first.length + 1)}`;
+    }
+    if (input.startsWith('/') || trimmed === '') throw bad();
+    return `/openapi/${trimmed}`;
+}
+
+module.exports = { parse, normalizeApiPath, METHODS };

package/src/cli.js

@@ -0,0 +1,168 @@
+const { CliError, usage } = require('./errors');
+const { parse, normalizeApiPath, METHODS } = require('./args');
+const { catalogue } = require('./commands');
+const { resolveBody } = require('./input');
+const { USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send } = require('./http');
+const { readCredential, saveCredential, removeCredential } = require('./credentials');
+const { browserLogin, resolveWebOrigin, defaultDevice } = require('./login');
+const { bridge } = require('./mcp');
+
+/**
+ * @typedef {{env: Record<string, string | undefined>, stdout: {write(s: string): unknown, isTTY?: boolean},
+ *   stderr: {write(s: string): unknown}, stdin: AsyncIterable<string | Buffer>, fetch?: typeof fetch,
+ *   openBrowser?: (url: string) => Promise<void>, loginTimeoutMs?: number}} Io
+ */
+
+/**
+ * Runs the CLI.
+ * @param {string[]} argv
+ * @param {Io} io
+ * @returns {Promise<number>} exit code
+ */
+async function run(argv, io) {
+    const envKey = (io.env.ZOODEALIO_API_KEY || '').trim();
+    /** Every key seen this run; none may appear in output. */
+    const secrets = new Set(envKey ? [envKey] : []);
+    try {
+        await execute(argv, io, envKey, secrets);
+        return 0;
+    } catch (err) {
+        const error = err instanceof CliError
+            ? err
+            : new CliError({ exit: 1, code: 'internal', title: 'Unexpected error', detail: /** @type {Error} */ (err).message });
+        // A key can appear JSON-escaped (newline, quote, backslash) inside the serialized error.
+        io.stderr.write(`${scrubKeys(JSON.stringify(error.toJSON()), secrets)}\n`);
+        return error.exit;
+    }
+}
+
+/**
+ * @param {string[]} argv
+ * @param {Io} io
+ * @param {string} envKey
+ * @param {Set<string>} secrets
+ */
+async function execute(argv, io, envKey, secrets) {
+    const parsed = parse(argv);
+    if ('help' in parsed) {
+        io.stdout.write(parsed.help);
+        return;
+    }
+    const { command, args, flags } = parsed;
+    const pretty = !!flags.pretty || !!io.stdout.isTTY;
+    /** @param {unknown} value */
+    const emit = (value) => io.stdout.write(`${JSON.stringify(value ?? null, null, pretty ? 2 : 0)}\n`);
+
+    if (command.name === 'commands') return emit(catalogue());
+
+    const origin = resolveOrigin(io.env, flags.env);
+    const stored = readCredential(io.env, origin);
+    if (stored) secrets.add(stored.key);
+    const source = envKey ? 'env' : stored ? 'login' : undefined;
+    const key = envKey || stored?.key || '';
+
+    if (['login', 'logout', 'mcp'].includes(command.name)) {
+        if (flags['dry-run']) throw usage(`--dry-run is not supported for \`${command.name}\``);
+        if (command.name === 'login') {
+            const result = await browserLogin({
+                apiOrigin: origin, webOrigin: resolveWebOrigin(io.env, flags.env), device: (flags.name?.trim() || defaultDevice()).slice(0, 64),
+                noBrowser: !!flags['no-browser'], openBrowser: io.openBrowser, timeoutMs: io.loginTimeoutMs, stderr: io.stderr, fetch: io.fetch,
+            });
+            secrets.add(result.key);
+            saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            return emit({ ok: true, email: result.email, name: result.name, keyPrefix: result.keyPrefix, origin });
+        }
+        if (command.name === 'logout') {
+            if (!stored) {
+                return emit({
+                    ok: true, loggedOut: false,
+                    detail: envKey ? 'Signed in only through ZOODEALIO_API_KEY; nothing to sign out of.' : 'Not signed in.',
+                });
+            }
+            try {
+                await send(io.fetch || fetch, {
+                    method: 'DELETE', url: buildUrl(origin, `/openapi/Keys/${encodeURIComponent(stored.keyId)}`, []),
+                    headers: { Accept: 'application/json', 'User-Agent': USER_AGENT, ApiKey: stored.key },
+                });
+            } catch (err) {
+                // 401/404 mean the key is already gone; anything else keeps the login so it can be retried.
+                if (!(err instanceof CliError) || (err.status !== 401 && err.status !== 404)) throw err;
+            }
+            removeCredential(io.env, origin);
+            return emit({ ok: true, loggedOut: true, email: stored.email, origin });
+        }
+        if (!key) throw notSignedIn();
+        return bridge({ url: origin, key, stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, fetch: io.fetch, scrub: (s) => scrubKeys(s, secrets), storedLogin: source === 'login' });
+    }
+
+    /** @type {string} */
+    let method;
+    /** @type {string} */
+    let path;
+    /** @type {[string, string][]} */
+    const query = [];
+    let destructive = !!command.destructive;
+    if (command.name === 'api') {
+        method = args.method.toUpperCase();
+        if (!METHODS.includes(method)) throw usage(`method must be one of ${METHODS.join(', ')}`);
+        path = normalizeApiPath(args.path);
+        destructive = method === 'DELETE';
+        for (const kv of flags.query || []) {
+            const eq = kv.indexOf('=');
+            if (eq < 1) throw usage(`--query expects k=v, got: ${kv}`);
+            query.push([kv.slice(0, eq), kv.slice(eq + 1)]);
+        }
+    } else {
+        method = /** @type {string} */ (command.method);
+        path = /** @type {string} */ (command.path).replace(/\{(\w+)\}/g, (_, name) => encodeURIComponent(args[name]));
+        for (const f of command.flags) if (f.query && flags[f.name] !== undefined) query.push([f.query, flags[f.name]]);
+    }
+    if (destructive && !flags.yes && !flags['dry-run']) throw usage(`\`${command.name}\` is destructive; pass --yes to confirm`);
+
+    /** @type {unknown} */
+    let body;
+    if (flags.body !== undefined) {
+        if ((command.convenience || []).some((n) => flags[n] !== undefined)) throw usage('use either --body or the convenience flags, not both');
+        body = await resolveBody(flags.body, io.stdin);
+    } else if (command.build) {
+        body = command.build(flags);
+        if (body === undefined && command.body === 'required') throw usage('provide --body or the convenience flags');
+    } else if (command.body === 'required') {
+        throw usage('--body is required');
+    }
+
+    const needsKey = command.auth !== false;
+    if (needsKey && !key && !flags['dry-run']) throw notSignedIn();
+
+    const url = buildUrl(origin, path, query);
+    /** @param {string} apiKey */
+    const headers = (apiKey) => ({
+        Accept: 'application/json',
+        'User-Agent': USER_AGENT,
+        ...(needsKey ? { ApiKey: apiKey } : {}),
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...(flags['if-match'] === undefined ? {} : { 'If-Match': flags['if-match'] }),
+    });
+
+    if (flags['dry-run']) return emit({ method, url, headers: headers(redactKey(key)), body: body ?? null });
+
+    /** @type {unknown} */
+    let result;
+    try {
+        result = await send(io.fetch || fetch, { method, url, headers: headers(key), body });
+    } catch (err) {
+        if (source === 'login' && err instanceof CliError && err.status === 401) {
+            throw new CliError({ exit: 3, status: 401, code: 'unauthorized', title: 'Login revoked or expired', detail: 'The stored login was revoked or expired. Run zoodealio login again.' });
+        }
+        throw err;
+    }
+    if (command.name === 'keys revoke' && source === 'login' && stored && args.id === stored.keyId) removeCredential(io.env, origin);
+    if (command.name === 'whoami') return emit({ ok: true, origin, key: redactKey(key), source, ...(source === 'login' && stored ? { email: stored.email } : {}) });
+    return emit(result);
+}
+
+function notSignedIn() {
+    return new CliError({ exit: 3, code: 'unauthorized', title: 'Not signed in', detail: 'Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.' });
+}
+
+module.exports = { run };