zoodealio 0.2.0 → 0.2.1

package/README.md

@@ -2,8 +2,8 @@
 
 `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
+same contract as the Zoodealio MCP server and the Zoodealio Zapier app. 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.
@@ -31,9 +31,15 @@ zoodealio login --name work-laptop   # device name shown at sign-in (default: th
 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.
+`login` opens your browser on the sign-in page, explains the steps and prints the link. In a
+terminal, press **Enter** to open it again, **c** to copy the link, or **q** to cancel; the link also
+works pasted into any browser, on this or another device. Sign in the way you usually do and click **Authorize**; the terminal
+finishes by itself and suggests what to run next. Run by a script or an agent (no terminal), it
+opens the browser the same way and prints the link, without the key prompt. All of this goes to stderr.
+
+Under the hood it 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}` on stdout 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),
@@ -225,8 +231,8 @@ zoodealio api GET Properties --query pageSize=5
   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.
+- Prefer webhooks, or polling `comping status` and `import-status`, to long waits. The
+  [developer docs](https://zoodealio.ai/developers#webhooks) cover events, signatures and delivery.
 
 ## Limits
 

package/bin/zoodealio.js

@@ -1,11 +1,34 @@
 #!/usr/bin/env node
 const { run } = require('../src/cli');
 
+/**
+ * Single keypresses from the terminal while `login` waits; the returned function hands the terminal back.
+ * @param {(key: string) => void} handler
+ */
+function onKey(handler) {
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.setEncoding('utf8');
+    stdin.resume();
+    const listener = (/** @type {string} */ data) => {
+        for (const key of data) handler(key);
+    };
+    stdin.on('data', listener);
+    return () => {
+        stdin.off('data', listener);
+        stdin.setRawMode(false);
+        stdin.pause();
+    };
+}
+
 run(process.argv.slice(2), {
     env: process.env,
     stdout: process.stdout,
     stderr: process.stderr,
     stdin: process.stdin,
+    // Someone is at a terminal: prompt for keys. Agents and scripts never get a prompt.
+    interactive: !!process.stdin.isTTY && !!process.stderr.isTTY,
+    onKey,
 }).then((code) => {
     process.exitCode = code;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zoodealio",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Zoodealio command line tool: the partner API as JSON, built for people, scripts and AI agents",
   "license": "UNLICENSED",
   "repository": {

package/src/args.js

@@ -29,7 +29,7 @@ function parse(argv) {
     }
     const { values, positionals } = parsed;
     if (values.help) return { help: helpText(positionals) };
-    if (positionals.length === 0) throw usage('missing command; run `zoodealio --help`');
+    if (positionals.length === 0) return { help: helpText([]) };
 
     let command;
     for (const c of COMMANDS) {

package/src/cli.js

@@ -6,11 +6,13 @@ const { USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send } = requ
 const { readCredential, saveCredential, removeCredential } = require('./credentials');
 const { browserLogin, resolveWebOrigin, defaultDevice } = require('./login');
 const { bridge } = require('./mcp');
+const { createUi } = require('./ui');
 
 /**
  * @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
+ *   openBrowser?: (url: string) => Promise<void>, copy?: (text: string) => Promise<void>, loginTimeoutMs?: number,
+ *   interactive?: boolean, onKey?: (handler: (key: string) => void) => () => void}} Io
  */
 
 /**
@@ -64,12 +66,34 @@ async function execute(argv, io, envKey, secrets) {
     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 ui = createUi(io.stderr, { fancy: !!io.interactive && !io.env.NO_COLOR });
             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,
+                envName: flags.env || 'prod', noBrowser: !!flags['no-browser'], openBrowser: io.openBrowser, copy: io.copy,
+                interactive: io.interactive, onKey: io.onKey, timeoutMs: io.loginTimeoutMs, ui, fetch: io.fetch,
             });
             secrets.add(result.key);
-            saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            const file = saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            const dev = flags.env && flags.env !== 'prod' ? ` --env ${flags.env}` : '';
+            const home = io.env.HOME || io.env.USERPROFILE;
+            const where = home && file.startsWith(home) ? `~${file.slice(home.length)}` : file;
+            const { style } = ui;
+            const next = [
+                [`zoodealio whoami${dev}`, 'check who you\'re signed in as'],
+                [`zoodealio properties list${dev}`, 'your first call'],
+                [`zoodealio mcp --help`, 'connect an AI client'],
+                ['zoodealio logout', 'sign this computer out'],
+            ];
+            const width = Math.max(...next.map(([c]) => c.length)) + 3;
+            ui.say();
+            ui.say(`${style.green('✓')} Signed in as ${style.bold(result.email)}${dev ? ` ${style.dim(`(${flags.env})`)}` : ''}`);
+            ui.say(`  ${style.dim(`Key "${result.name}" saved to ${where}`)}`);
+            ui.say();
+            ui.say(`  ${style.bold('Next')}`);
+            for (const [cmd, what] of next) ui.say(`    ${cmd.padEnd(width)}${style.dim(what)}`);
+            ui.say();
+            // A person at a terminal has just read all that; the JSON is for scripts and agents.
+            if (io.interactive && io.stdout.isTTY) return;
             return emit({ ok: true, email: result.email, name: result.name, keyPrefix: result.keyPrefix, origin });
         }
         if (command.name === 'logout') {

package/src/commands.js

@@ -7,7 +7,7 @@ const { parseJsonArg } = require('./input');
  * @typedef {{name: string, description: string, guid?: boolean}} Arg
  * @typedef {{name: string, summary: string, method: string | null, path: string | null, args: Arg[],
  *   flags: Flag[], body?: 'required' | 'optional', convenience?: string[], destructive?: boolean,
- *   auth?: boolean, build?: (flags: Record<string, any>) => unknown}} Command
+ *   auth?: boolean, build?: (flags: Record<string, any>) => unknown, notes?: string[]}} Command
  */
 
 /**
@@ -137,6 +137,14 @@ const COMMANDS = [
     }),
     cmd('login', 'Sign in through the browser and store a CLI key', null, null, {
         auth: false,
+        notes: [
+            'Opens the Zoodealio sign-in page in your browser. Sign in the way you usually do and click',
+            'Authorize; this terminal then finishes by itself. In a terminal, press Enter to open it',
+            'again, c to copy the link, or q to cancel. The link is always printed too, for when no browser',
+            'can be opened (SSH, containers: use --no-browser and open it on another device).',
+            'The key is saved for this computer; zoodealio logout removes it.',
+            'On CI or a server, set ZOODEALIO_API_KEY instead.',
+        ],
         flags: [
             { name: 'no-browser', type: 'boolean', description: 'Print the sign-in URL to stderr instead of opening a browser' },
             str('name', 'Device name shown at sign-in (default: this host)'),
@@ -149,7 +157,15 @@ const COMMANDS = [
         build: (f) => ({ name: f.name }),
     }),
     cmd('keys revoke', 'Revoke an API key', 'DELETE', '/openapi/Keys/{id}', { args: [id('id', 'Key id')], destructive: true }),
-    cmd('mcp', 'Run a stdio MCP server bridged to /openapi/mcp', 'POST', '/openapi/mcp'),
+    cmd('mcp', 'Run a stdio MCP server bridged to /openapi/mcp', 'POST', '/openapi/mcp', {
+        notes: [
+            'Uses your zoodealio login (or ZOODEALIO_API_KEY). Add it to an AI client:',
+            '  Claude Code:        claude mcp add --scope user zoodealio -- zoodealio mcp',
+            '  Claude Desktop,',
+            '  Cursor, VS Code:    {"command": "zoodealio", "args": ["mcp"]}',
+            'Add --env dev to the args for the dev environment.',
+        ],
+    }),
     cmd('whoami', 'Check the API key and show the target origin', 'GET', '/openapi/Webhooks/event-types'),
     cmd('openapi', 'Print the partner OpenAPI document (no key needed)', 'GET', '/_openapi/partner.json', { auth: false }),
     cmd('api', 'Call any /openapi endpoint directly (DELETE needs --yes)', null, null, {
@@ -208,8 +224,21 @@ function helpText(prefix) {
         if (exact.destructive) lines.push('Destructive: requires --yes.');
         for (const a of exact.args) lines.push(`  <${a.name}>  ${a.description}`);
         for (const f of exact.flags) lines.push(`  --${f.name}  ${f.description}${f.required ? ' (required)' : ''}`);
+        if (exact.notes) lines.push('', ...exact.notes);
     } else {
         lines.push('zoodealio <command> [args] [flags]', '', 'JSON on stdout; errors as JSON on stderr. Sign in with `zoodealio login` or set ZOODEALIO_API_KEY.', '');
+        if (prefix.length === 0) {
+            lines.push(
+                'Get started:',
+                '  zoodealio login             Sign in through your browser',
+                '  zoodealio whoami            Check who you\'re signed in as',
+                '  zoodealio properties list   Your first call',
+                '  zoodealio mcp --help        Connect an AI client (Claude, Cursor, VS Code)',
+                '  zoodealio commands          Every command as JSON, for AI agents',
+                '',
+                'Commands:',
+            );
+        }
         for (const c of matches) lines.push(`  ${c.name.padEnd(28)}${c.summary}`);
         lines.push('', 'Global flags:');
         for (const f of GLOBAL_FLAGS) lines.push(`  --${f.name.padEnd(10)}${f.description}`);

package/src/credentials.js

@@ -69,9 +69,11 @@ function writeAll(env, all) {
  * @param {Record<string, string | undefined>} env
  * @param {string} origin
  * @param {Credential} credential
+ * @returns {string} the credentials file
  */
 function saveCredential(env, origin, credential) {
     writeAll(env, { ...readAll(env, true), [origin]: credential });
+    return path.join(configDir(env), 'credentials.json');
 }
 
 /**

package/src/login.js

@@ -37,6 +37,27 @@ function openBrowser(url) {
     });
 }
 
+/**
+ * Puts text on the system clipboard with the first tool this machine has. Rejects when none works.
+ * @param {string} text
+ * @returns {Promise<void>}
+ */
+async function copyToClipboard(text) {
+    const tools = process.platform === 'darwin' ? [['pbcopy', []]]
+        : process.platform === 'win32' ? [['clip', []]]
+            : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+    for (const [command, args] of /** @type {[string, string[]][]} */ (tools)) {
+        const ok = await new Promise((resolve) => {
+            const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.once('error', () => resolve(false));
+            child.once('close', (code) => resolve(code === 0));
+            child.stdin.end(text);
+        });
+        if (ok) return;
+    }
+    throw new Error('no clipboard tool');
+}
+
 const PAGE = (/** @type {string} */ message) => `<!doctype html><meta charset="utf-8"><title>Zoodealio CLI</title><body style="font-family:system-ui;text-align:center;margin-top:4rem"><h1>${message}</h1><p>You can close this tab and return to your terminal.</p>`;
 
 /**
@@ -89,8 +110,13 @@ async function listenForCallback(state, timeoutMs) {
 
 /**
  * Browser sign-in (authorization code + PKCE). Returns the exchange response; the caller stores it.
- * @param {{apiOrigin: string, webOrigin: string, device: string, noBrowser: boolean,
- *   openBrowser?: (url: string) => Promise<void>, timeoutMs?: number, stderr: {write(s: string): unknown}, fetch?: typeof fetch}} opts
+ * Everything it says goes to stderr, so stdout stays JSON. In a terminal someone is typing in
+ * (`interactive` with `onKey`), Enter opens the browser, c copies the link and q cancels; otherwise the
+ * browser opens straight away. The link is always printed, in case no browser can be opened.
+ * @param {{apiOrigin: string, webOrigin: string, device: string, envName: string, noBrowser: boolean,
+ *   openBrowser?: (url: string) => Promise<void>, copy?: (text: string) => Promise<void>,
+ *   interactive?: boolean, onKey?: (handler: (key: string) => void) => () => void,
+ *   timeoutMs?: number, ui: ReturnType<typeof import('./ui').createUi>, fetch?: typeof fetch}} opts
  * @returns {Promise<{key: string, keyId: string, keyPrefix: string, name: string, email: string}>}
  */
 async function browserLogin(opts) {
@@ -100,31 +126,81 @@ async function browserLogin(opts) {
     const listener = await listenForCallback(state, opts.timeoutMs ?? LOGIN_TIMEOUT_MS);
     try {
         const url = `${opts.webOrigin}/cli/login?${new URLSearchParams({ port: String(listener.port), state, challenge, device: opts.device })}`;
-        let opened = false;
-        if (!opts.noBrowser) {
+        const { ui } = opts;
+        const { style } = ui;
+        const minutes = Math.max(1, Math.round((opts.timeoutMs ?? LOGIN_TIMEOUT_MS) / 60000));
+        const open = async () => {
             try {
                 await (opts.openBrowser || openBrowser)(url);
-                opened = true;
+                ui.say(`  ${style.dim('Opened your browser. Nothing there? Use the link above, or press Enter.')}`);
             } catch {
-                // fall through to printing the URL
+                ui.say(`  ${style.red('Couldn\'t open a browser.')} Copy the link above into one.`);
             }
+        };
+        const prompting = !opts.noBrowser && !!opts.interactive && !!opts.onKey;
+
+        ui.say();
+        ui.say(`  ${style.bold(`Sign in to Zoodealio${opts.envName === 'prod' ? '' : ` (${opts.envName})`}`)}`);
+        ui.say();
+        ui.say(opts.noBrowser ? '  1. Open the link below in a browser, on this or any device.'
+            : '  1. Your browser opens the sign-in page. If it doesn\'t, use the link below.');
+        ui.say(`  2. Sign in the way you usually do, then click ${style.bold('Authorize')} for "${opts.device}".`);
+        ui.say('  3. Come back here. This finishes by itself.');
+        ui.say();
+        ui.say(`  ${style.dim('Link:')} ${style.link(url)}`);
+        if (prompting) ui.say(`  ${style.dim('Press Enter to open it again · c to copy the link · q to cancel')}`);
+        ui.say();
+
+        /** @type {() => void} */
+        let stopKeys = () => {};
+        /** @type {Promise<{code?: string, error?: string}>} */
+        let cancelled = new Promise(() => {});
+        if (!opts.noBrowser) await open();
+        if (prompting) {
+            cancelled = new Promise((resolve) => {
+                stopKeys = /** @type {(handler: (key: string) => void) => () => void} */ (opts.onKey)((key) => {
+                    if (key === '\r' || key === '\n') {
+                        void open();
+                    } else if (key === 'c' || key === 'C') {
+                        (opts.copy || copyToClipboard)(url).then(
+                            () => ui.say(`  ${style.green('✓')} Link copied. Paste it into your browser.`),
+                            () => ui.say(`  ${style.red('Couldn\'t reach the clipboard.')} Select the link above to copy it.`),
+                        );
+                    } else if (key === 'q' || key === 'Q' || key === '\u0003') {
+                        resolve({ error: 'cancelled' });
+                    }
+                });
+            });
         }
-        if (!opened) opts.stderr.write(`Open this URL in a browser to sign in:\n${url}\n`);
+        ui.spin(`Waiting for you to authorize in the browser… ${style.dim(`(the link works for ${minutes} minute${minutes === 1 ? '' : 's'})`)}`);
 
-        const { code, error } = await listener.result;
+        let result;
+        try {
+            result = await Promise.race([listener.result, cancelled]);
+        } finally {
+            stopKeys();
+            ui.done();
+        }
+        const { code, error } = result;
         if (!code) {
             throw new CliError({
                 exit: 1, code: error === 'cancelled' ? 'login_cancelled' : 'login_failed',
                 title: error === 'cancelled' ? 'Login cancelled' : 'Login failed',
-                detail: error === 'cancelled' ? 'Sign-in was cancelled in the browser.' : `The browser reported: ${error}`,
+                detail: error === 'cancelled' ? 'Sign-in was cancelled.' : `The browser reported: ${error}`,
             });
         }
-        return /** @type {any} */ (await send(opts.fetch || fetch, {
-            method: 'POST',
-            url: `${opts.apiOrigin}/openapi/cli-logins/exchange`,
-            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
-            body: { code, verifier },
-        }));
+        ui.say(`${ui.style.green('✓')} Authorized in the browser`);
+        ui.spin('Finishing sign-in…');
+        try {
+            return /** @type {any} */ (await send(opts.fetch || fetch, {
+                method: 'POST',
+                url: `${opts.apiOrigin}/openapi/cli-logins/exchange`,
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
+                body: { code, verifier },
+            }));
+        } finally {
+            ui.done();
+        }
     } finally {
         listener.close();
     }

package/src/ui.js

@@ -0,0 +1,59 @@
+/**
+ * What a person sees on stderr while `login` runs. In a terminal it has color and a spinner; for
+ * agents, scripts and NO_COLOR it is the same text, plain, one line per message.
+ */
+
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+/**
+ * @param {{write(s: string): unknown}} stream
+ * @param {{fancy: boolean}} options fancy = an interactive terminal that allows color
+ */
+function createUi(stream, { fancy }) {
+    /** @param {string} code @returns {(s: string) => string} */
+    const paint = (code) => (s) => (fancy ? `\u001b[${code}m${s}\u001b[0m` : s);
+    const style = { bold: paint('1'), dim: paint('2'), green: paint('32'), cyan: paint('36'), red: paint('31'), link: paint('4;36') };
+
+    /** @type {{text: string, timer: NodeJS.Timeout, frame: number} | null} */
+    let spinner = null;
+    const draw = () => {
+        if (!spinner) return;
+        stream.write(`\r\u001b[2K${style.cyan(FRAMES[spinner.frame % FRAMES.length])} ${spinner.text}`);
+        spinner.frame++;
+    };
+    const clear = () => {
+        if (spinner) stream.write('\r\u001b[2K');
+    };
+
+    /** Prints a line, keeping any spinner on the line below it. @param {string} [line] */
+    const say = (line = '') => {
+        clear();
+        stream.write(`${line}\n`);
+        draw();
+    };
+
+    return {
+        style,
+        say,
+        /** @param {string} text */
+        spin(text) {
+            if (!fancy) {
+                stream.write(`${text}\n`);
+                return;
+            }
+            spinner = { text, frame: 0, timer: setInterval(draw, 80) };
+            draw();
+        },
+        /** Stops the spinner, replacing it with a final line. @param {string} [line] */
+        done(line) {
+            if (spinner) {
+                clearInterval(spinner.timer);
+                clear();
+                spinner = null;
+            }
+            if (line) stream.write(`${line}\n`);
+        },
+    };
+}
+
+module.exports = { createUi };