@staqon.one/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @staqon.one/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.
+A command-line tool for a StaqOn workspace owner — send messages, post ads, run e-StaqOn Verify approvals, manage External and Internal team members, and raise escalation matters, all from your terminal.
+
+The CLI never holds, sees, or asks you to paste a raw API key. Instead it uses a device-pairing flow: you approve each computer once from your StaqOn dashboard, and after that every call goes through StaqOn's own proxy on your workspace's behalf. Full technical details for engineers who want them are at [`/developer`](https://staqon.one/developer) (the live, interactive Swagger spec) — this README covers the CLI's own commands.
+
+## Install
+
+```bash
+npm install -g @staqon.one/cli
+```
+
+Requires Node 18+.
+
+## Sign in
+
+```bash
+staqon login
+```
+
+This prints an 8-character code and a link (`https://staqon.one/cli?code=XXXX-XXXX`). Open the link (or go to `/cli` and type the code) while signed in to StaqOn as the workspace owner, pick which workspace to pair, and confirm. If your web session is more than 15 minutes old, you'll be asked for your MPIN first.
+
+The code expires in 10 minutes. Once approved, the CLI stores a session token locally (`~/.staqon/credentials.json`, permissions `0600`) and you won't need to log in again until that session is revoked or expires.
+
+**A prerequisite:** the workspace owner must turn on "Allow CLI access" in **Workspace Settings → API → CLI access** before `staqon login` can succeed. This is a separate, per-workspace switch — turning it off immediately signs out every paired computer.
+
+```bash
+staqon whoami     # confirm you're paired, see your rate-limit usage and which commands are available
+staqon logout     # forget the session on THIS computer (does not revoke it server-side — use the dashboard for that)
+```
+
+## How calls are authorized
+
+Every command goes through StaqOn's own CLI proxy, never a tenant's raw API key:
+
+1. Your paired session's bearer token (`stq_cli_...`) authenticates the call.
+2. StaqOn checks, on every single call, that your workspace's "Allow CLI access" switch is still on and that you're still that workspace's active owner.
+3. StaqOn picks which of the workspace's own API keys to act as — automatically if there's exactly one eligible key for that command, or you'll be asked to disambiguate with `--team <id-or-slug>` if there are several active teams of the right type.
+4. The underlying endpoint runs exactly as it would for a direct API call — same validation, same responses.
+
+If a command returns `"error": "team_required"` with a list of teams, re-run it with `--team <id-or-slug>`.
+
+## Rate limits
+
+Two independent limits apply to every call:
+
+- **This CLI session:** 30 requests/minute, 3,000/day — separate from, and in addition to, the workspace's own API key limits.
+- **The workspace's underlying API key:** if that key is already at its own limit from *direct* API traffic, CLI calls pause too (CLI traffic itself never counts against or depletes the key's direct-API headroom — they're tracked separately).
+
+A `429` response includes `Retry-After` in seconds either way.
+
+## Commands
+
+### Members (External team)
+
+```bash
+staqon members list [--page 1] [--limit 50] [--search text] [--team id-or-slug]
+staqon members get --email you@example.com
+staqon members get --member-id 123
+staqon members add --name "Jane Doe" --email jane@example.com
+staqon members remove --email jane@example.com
+staqon members teams --external-ref your-ref-from-link-invite
+```
+
+`--limit` accepts 1–200 on `list`. `add` only takes `--name` and `--email` — there is no phone field on this endpoint.
+
+Removing a member archives their thread (history is kept) and drops their team/conversation membership.
+
+### Internal team members
+
+```bash
+staqon internal-members [--page 1] [--limit 50] [--search text] [--team id-or-slug]
+```
+
+Same shape as `members list`, but for Internal teams: no guest-role filter, and it reports each member's `role` instead of message stats (Internal is a one-way feed, not a conversation).
+
+### Messaging (External team)
+
+```bash
+staqon messages send --email jane@example.com --message "Hello!"
+staqon messages comment --username jane.doe --comment "Thanks for your order" [--external-ref my-idempotency-key]
+staqon messages read --username jane.doe [--limit 50] [--before 1000 | --after 2000]
+```
+
+- `send` and `comment` both write into a member's thread as the workspace. `send` uses the member's email; `comment` uses their StaqOn username and supports an `--external-ref` so a retried call with the same ref is idempotent — but **the uniqueness check is workspace-wide, not per recipient**: reusing the same ref for a different recipient will silently fail to reach them (you'll get a 409 back, not a second delivery).
+- `read` requires an **approved consent link** for that member — you'll get a 403 if the member hasn't linked. `send`/`comment` don't need that link (writing in is the workspace's own authority).
+- `--before`/`--after` page through history; use one or the other, not both.
+
+### Internal messaging
+
+```bash
+staqon internal-message --username jane.doe --message "Your ticket was updated" [--title "Ticket #123"] [--link-url https://...] [--external-ref ref]
+```
+
+A one-way push into the member's API Messages feed — not a conversation (no replies, reactions, or attachments). Requires the member's explicit, separate consent for *internal* messages: a 403 means they haven't opted in; a 404 with "Internal Link is not set up" means the workspace hasn't configured that gate at all yet.
+
+### e-StaqOn Verify — push approval for sensitive actions
+
+```bash
+staqon verify start --username jane.doe --action "Withdraw $500" --context "Approve withdrawal of $500 to your linked bank account?" [--ttl 60]
+staqon verify check --id <verification_id>
+staqon verify cancel --id <verification_id>
+```
+
+`start` pushes an approval prompt to the member's StaqOn app and returns a `verification_id`. Poll `check` until you get `verified: true` (approved), or `verified: false` with a `reason` of `pending`, `declined`, `timeout`, or `cancelled`. `ttl` is 30–180 seconds (default 30; out-of-range values are clamped, not rejected). `cancel` withdraws a still-pending request — if the member already answered, you'll get a 409 and their answer stands, not your cancellation.
+
+This requires an approved, **unexpired** consent link for the member (stricter than `messages send`'s check).
+
+### Advertisement API
+
+```bash
+staqon ad upload-image --file ./banner.jpg
+staqon ad send --body "Big autumn sale, 20% off everything" --button-label "Shop now" --button-url https://example.com/sale [--image-url <from upload-image>] [--external-ref campaign-001]
+staqon ad status --external-ref campaign-001
+staqon ad status --request-id 812
+```
+
+Requires an **ad-purpose** API key on the target team (separate from your messaging key — created in Workspace Settings → API → Ad API). `ad send` is asynchronous: it queues the send and returns right away; poll `ad status` for progress and final counts. `upload-image` enforces JPEG/PNG/WebP under 300KB; images are centre-cropped to 16:9 server-side.
+
+### Escalation matters
+
+```bash
+staqon escalation raise --email jane@example.com --title "Repeated no-shows" --description "..." --due-date 2026-12-01 [--priority high]
+staqon escalation list [--page 1] [--limit 50] [--status open]
+staqon escalation get --matter-id 42
+```
+
+`--due-date` must be strictly after today. `--priority` is one of `low`, `medium`, `high`, `critical` (default `medium`). `list`/`get` only ever show matters your key can see — scoped to "the target member is in this key's team," not by any other workspace linkage.
+
+### Status and webhook health
+
+```bash
+staqon status [--internal]
+staqon webhooks [--internal]
+```
+
+`status` reports member counts and your current rate-limit usage for the External (default) or Internal surface. `webhooks` reports each registered webhook's health — a webhook that fails 10 consecutive deliveries auto-disables, and this is the only way to notice that happened short of your own monitoring.
+
+## A note on API keys and this CLI
+
+Creating a **new** Messaging or Ad API key from the dashboard requires the workspace's Link integration to be set up first — the "+ New key" button is disabled with a "Set up Link first" tooltip until then. Keys created before Link was required keep working. This restriction is enforced in the dashboard UI, not by the API itself, and it has nothing to do with CLI pairing — CLI access is a separate switch and doesn't require Link at all.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| `staqon login` never completes | The workspace owner hasn't approved the code at `/cli` yet, or 10 minutes passed — run `staqon login` again. |
+| Any command returns 401 "...missing, expired or revoked" | Your paired session is gone. Run `staqon login` again. |
+| 403 "CLI access is turned off for this workspace" | The owner turned the workspace's CLI switch off. They'll need to turn it back on and you'll need to pair again. |
+| 409 "no_key" | The workspace has no active API key of the right surface+purpose for that command. The owner creates one in Workspace Settings → API. |
+| 409 "team_required" | The workspace has more than one eligible team for that command. Re-run with `--team <id-or-slug>` — the error body lists the choices. |
+
+## License
+
+MIT
+</content>

package/dist/api/client.js

@@ -0,0 +1,71 @@
+import { BASE_URL, loadSession, saveSession, clearSession } from '../config.js';
+export class StaqOnApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(typeof body.error === 'string' ? body.error : `HTTP ${status}`);
+        this.status = status;
+        this.body = body;
+    }
+}
+/**
+ * The real, server-enforced ceiling for every paginated CLI list endpoint
+ * (members.php, internal/members.php, messages.php): Swagger says
+ * `maximum: 200` on all three. The OLD cli had a client-side MAX_LIST_LIMIT
+ * of 100 — that was a self-imposed, unnecessarily tight cap, not a server
+ * fact. Verified against openapi.yaml this session (Nov 11 2026).
+ */
+export const MAX_LIST_LIMIT = 200;
+function buildQuery(params = {}) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined)
+            qs.set(k, String(v));
+    }
+    const s = qs.toString();
+    return s ? `?${s}` : '';
+}
+/**
+ * The CLI's ONE front door, matching /api/v1/cli-proxy.php exactly:
+ *   GET|POST /api/v1/cli-proxy.php?_ep=<name>&...their own query
+ *   Authorization: Bearer stq_cli_<64 hex>
+ *   X-StaqOn-Team: <team id or slug>   (only when the workspace has >1 eligible team)
+ * Never sends X-API-Key — the proxy drops it server-side anyway; the CLI
+ * never holds, or needs, a raw tenant key.
+ */
+export async function proxy(ep, opts = {}) {
+    const session = await loadSession();
+    if (!session) {
+        throw new StaqOnApiError(401, { error: 'Not logged in. Run: staqon login' });
+    }
+    const method = opts.method ?? (opts.json ? 'POST' : 'GET');
+    const url = `${BASE_URL}/api/v1/cli-proxy.php${buildQuery({ _ep: ep, ...opts.query })}`;
+    const headers = {
+        Authorization: `Bearer ${session.token}`,
+    };
+    if (opts.team)
+        headers['X-StaqOn-Team'] = opts.team;
+    if (opts.json)
+        headers['Content-Type'] = 'application/json';
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: opts.json ? JSON.stringify(opts.json) : undefined,
+    });
+    const body = (await res.json().catch(() => ({})));
+    if (res.status === 401) {
+        // Session is gone/expired/revoked server-side — don't leave a dead token lying around locally.
+        await clearSession();
+        throw new StaqOnApiError(401, {
+            error: body.error ?? 'This CLI session is missing, expired or revoked. Run: staqon login',
+        });
+    }
+    if (!res.ok)
+        throw new StaqOnApiError(res.status, body);
+    return body;
+}
+/** `_ep=whoami` — no backing file; the proxy answers directly with session/workspace/limits/access. */
+export async function whoami() {
+    return proxy('whoami', { method: 'GET' });
+}
+export { BASE_URL, loadSession, saveSession, clearSession };

package/dist/auth.js

@@ -0,0 +1,102 @@
+import { BASE_URL, saveSession, clearSession, loadSession } from './config.js';
+const CLI_VERSION = '0.1.0'; // keep in sync with package.json
+async function postJson(path, body) {
+    const res = await fetch(`${BASE_URL}/api/cli-pair.php?action=${path}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = (await res.json());
+    if (!res.ok || data.ok === false) {
+        throw new Error(data.error ?? `Login failed (HTTP ${res.status})`);
+    }
+    return data;
+}
+function osLabel() {
+    const p = process.platform;
+    if (p === 'darwin')
+        return 'macOS';
+    if (p === 'win32')
+        return 'Windows';
+    if (p === 'linux')
+        return 'Linux';
+    return p;
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Device-pairing login, matching api/cli-pair.php exactly:
+ *   1. code_request -> {pair_id, code, verification_url, poll_secret, expires_in, interval}
+ *   2. show the code + verification_url to the user
+ *   3. poll {pair_id, poll_secret} every `interval` seconds until approved/denied/expired
+ *   4. on 'approved', the token is minted and returned EXACTLY ONCE on that poll response —
+ *      save it immediately; a repeat poll after that returns 'consumed', not the token again.
+ *
+ * No API key is ever involved. The workspace owner approves the device at
+ * <verification_url> (StaqOn's own /cli page), picking which workspace and,
+ * if their web session is stale, re-entering their MPIN — all server-side.
+ */
+export async function login(deviceLabel) {
+    const label = deviceLabel ?? `${osLabel()} computer`;
+    const start = await postJson('code_request', {
+        device_label: label,
+        os: osLabel(),
+        cli_version: CLI_VERSION,
+    });
+    console.log('');
+    console.log(`  To finish signing in, visit: ${start.verification_url}`);
+    console.log(`  And enter this code: ${start.code}`);
+    console.log('');
+    console.log('  Waiting for approval (this code expires in 10 minutes)...');
+    const deadline = Date.now() + start.expires_in * 1000;
+    const intervalMs = Math.max(start.interval, 1) * 1000;
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const poll = await postJson('poll', {
+            pair_id: start.pair_id,
+            poll_secret: start.poll_secret,
+        });
+        if (poll.status === 'pending')
+            continue;
+        if (poll.status === 'approved' && poll.token && poll.workspace) {
+            await saveSession({
+                token: poll.token,
+                workspace: poll.workspace,
+                expires_at: poll.expires_at ?? '',
+                paired_at: new Date().toISOString(),
+            });
+            return { workspace: poll.workspace };
+        }
+        if (poll.status === 'denied')
+            throw new Error('Login request was denied.');
+        if (poll.status === 'expired')
+            throw new Error('Login code expired. Run: staqon login');
+        if (poll.status === 'consumed')
+            throw new Error('This login code was already used. Run: staqon login');
+        throw new Error(poll.error ?? `Unexpected login status: ${poll.status}`);
+    }
+    throw new Error('Login timed out. Run: staqon login');
+}
+/**
+ * Rotates the current session token via ?action=refresh. The OLD token
+ * stays valid for 5 more minutes server-side (CLI_ROTATE_GRACE=300), so a
+ * failed save here doesn't strand the user mid-rotation.
+ */
+export async function refresh() {
+    const session = await loadSession();
+    if (!session)
+        throw new Error('Not logged in. Run: staqon login');
+    const res = await fetch(`${BASE_URL}/api/cli-pair.php?action=refresh`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${session.token}` },
+    });
+    const data = (await res.json());
+    if (!res.ok || !data.ok || !data.token) {
+        throw new Error(data.error ?? 'Could not refresh. Run: staqon login');
+    }
+    await saveSession({ ...session, token: data.token });
+}
+export async function logout() {
+    await clearSession();
+}

package/dist/commands/ad.js

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { proxy, BASE_URL, loadSession } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+function teamOpt(cmd) {
+    return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+export function registerAdCommands(program) {
+    const ad = program.command('ad').description('Advertisement API — send a card to every member thread of a team');
+    teamOpt(ad
+        .command('upload-image')
+        .description('Upload one banner image (JPEG/PNG/WebP, max 300KB) and get back an image_url for `ad send --image-url`')
+        .requiredOption('--file <path>', 'local path to the image')).action(async (opts) => {
+        try {
+            const session = await loadSession();
+            if (!session)
+                throw new Error('Not logged in. Run: staqon login');
+            const data = await readFile(opts.file);
+            const form = new FormData();
+            form.append('image', new Blob([data]), opts.file.split('/').pop() ?? 'image');
+            const headers = { Authorization: `Bearer ${session.token}` };
+            if (opts.team)
+                headers['X-StaqOn-Team'] = opts.team;
+            const res = await fetch(`${BASE_URL}/api/v1/cli-proxy.php?_ep=external/ad-image`, {
+                method: 'POST',
+                headers,
+                body: form,
+            });
+            const body = (await res.json());
+            if (!res.ok)
+                throw new Error(typeof body.error === 'string' ? body.error : `HTTP ${res.status}`);
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(ad
+        .command('send')
+        .description('Queue an ad card to every active thread of the team — asynchronous: returns 202 immediately, poll `ad status` for progress')
+        .requiredOption('--body <text>', '50-900 characters')
+        .requiredOption('--button-label <text>', '1-30 characters')
+        .requiredOption('--button-url <url>', 'must start with https://')
+        .option('--image-url <url>', 'from `ad upload-image`, same workspace+team')
+        .option('--external-ref <ref>', 'idempotency key — repeating it returns the original send\'s counts, sends nothing twice')).action(async (opts) => {
+        try {
+            const body = await proxy('external/ad', {
+                method: 'POST',
+                team: opts.team,
+                json: {
+                    body: opts.body,
+                    button_label: opts.buttonLabel,
+                    button_url: opts.buttonUrl,
+                    image_url: opts.imageUrl,
+                    external_ref: opts.externalRef,
+                },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(ad
+        .command('status')
+        .description('Progress or final result of one ad send — look up by external_ref or ad_request_id')
+        .option('--external-ref <ref>')
+        .option('--request-id <id>')).action(async (opts) => {
+        if (!opts.externalRef && !opts.requestId)
+            fail(new Error('Pass --external-ref or --request-id.'));
+        try {
+            const body = await proxy('external/ad-status', {
+                method: 'GET',
+                team: opts.team,
+                query: { external_ref: opts.externalRef, ad_request_id: opts.requestId },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+}

package/dist/commands/auth.js

@@ -0,0 +1,37 @@
+import { login, logout } from '../auth.js';
+import { whoami as fetchWhoami } from '../api/client.js';
+import { ok, fail } from '../output.js';
+export function registerAuthCommands(program) {
+    program
+        .command('login')
+        .description('Pair this computer with a StaqOn workspace (device-code flow — no API key needed)')
+        .option('--label <name>', 'a name for this computer, shown to the workspace owner when they approve')
+        .action(async (opts) => {
+        try {
+            const { workspace } = await login(opts.label);
+            ok(`Paired with workspace "${workspace.name}" (${workspace.slug}).`);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    program
+        .command('logout')
+        .description('Forget this computer\'s paired session (does not revoke it on the server — use the dashboard for that)')
+        .action(async () => {
+        await logout();
+        ok('Logged out locally. The server-side session, if still live, can be revoked from the workspace\'s CLI access page.');
+    });
+    program
+        .command('whoami')
+        .description('Show the paired workspace, session info, rate-limit usage, and which commands are available')
+        .action(async () => {
+        try {
+            const body = await fetchWhoami();
+            console.log(JSON.stringify(body, null, 2));
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+}

package/dist/commands/members.js

@@ -0,0 +1,111 @@
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+function teamOpt(cmd) {
+    return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+export function registerMemberCommands(program) {
+    const members = program.command('members').description('Manage external team members');
+    teamOpt(members
+        .command('list')
+        .description('List this team\'s external (guest) members')
+        .option('--page <n>', 'page number', '1')
+        .option('--limit <n>', `page size, 1-${MAX_LIST_LIMIT} (default 50)`, '50')
+        .option('--search <text>', 'match against name or email')).action(async (opts) => {
+        try {
+            const body = await proxy('external/members', {
+                method: 'GET',
+                team: opts.team,
+                query: { page: opts.page, limit: opts.limit, search: opts.search },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(members
+        .command('get')
+        .description('Get one external member, by email or member_id')
+        .option('--email <email>')
+        .option('--member-id <id>')).action(async (opts) => {
+        try {
+            const body = await proxy('external/member', {
+                method: 'GET',
+                team: opts.team,
+                query: { email: opts.email, member_id: opts.memberId },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(members
+        .command('add')
+        .description('Add (or re-add) a member to this external team')
+        .requiredOption('--name <name>')
+        .requiredOption('--email <email>')).action(async (opts) => {
+        try {
+            const body = await proxy('external/add-member', {
+                method: 'POST',
+                team: opts.team,
+                json: { name: opts.name, email: opts.email },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(members
+        .command('remove')
+        .description('Remove a member from this external team (archives their thread; history kept)')
+        .requiredOption('--email <email>')).action(async (opts) => {
+        try {
+            const body = await proxy('external/remove-member', {
+                method: 'POST',
+                team: opts.team,
+                json: { email: opts.email },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(members
+        .command('teams')
+        .description('Which external teams has a linked member joined? (looked up by external_ref)')
+        .requiredOption('--external-ref <ref>', 'the external_ref originally sent to link-invite')).action(async (opts) => {
+        try {
+            const body = await proxy('external/member-teams', {
+                method: 'GET',
+                team: opts.team,
+                query: { external_ref: opts.externalRef },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    // Internal-surface member listing — same family, different endpoint/scope (no guest filter, reports role not message stats).
+    teamOpt(program
+        .command('internal-members')
+        .description('List this key\'s internal team members (role-based, no external thread stats)')
+        .option('--page <n>', 'page number', '1')
+        .option('--limit <n>', `page size, 1-${MAX_LIST_LIMIT} (default 50)`, '50')
+        .option('--search <text>', 'match against name, email or username')).action(async (opts) => {
+        try {
+            const body = await proxy('internal/members', {
+                method: 'GET',
+                team: opts.team,
+                query: { page: opts.page, limit: opts.limit, search: opts.search },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+}

package/dist/commands/messaging.js

@@ -0,0 +1,92 @@
+import { proxy, MAX_LIST_LIMIT } from '../api/client.js';
+import { fail, printJson } from '../output.js';
+function teamOpt(cmd) {
+    return cmd.option('--team <idOrSlug>', 'team id or slug — only needed if the workspace has more than one eligible team');
+}
+export function registerMessagingCommands(program) {
+    const messages = program.command('messages').description('Send and read External team member conversations');
+    teamOpt(messages
+        .command('send')
+        .description('Send a message into a member\'s thread, as the workspace owner')
+        .requiredOption('--email <email>')
+        .requiredOption('--message <text>', 'max 60000 characters')).action(async (opts) => {
+        try {
+            const body = await proxy('external/message', {
+                method: 'POST',
+                team: opts.team,
+                json: { email: opts.email, message: opts.message },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(messages
+        .command('comment')
+        .description('Post a comment into a member\'s thread, attributed to the workspace (no consent link needed — writing in is the workspace\'s own authority)')
+        .requiredOption('--username <username>')
+        .requiredOption('--comment <text>', 'max 60000 characters')
+        .option('--external-ref <ref>', 'idempotency key, max 190 chars — scoped to the WHOLE WORKSPACE, not per recipient; reusing it for a different recipient silently does not reach them')).action(async (opts) => {
+        try {
+            const body = await proxy('external/comment', {
+                method: 'POST',
+                team: opts.team,
+                json: { username: opts.username, comment: opts.comment, external_ref: opts.externalRef },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    teamOpt(messages
+        .command('read')
+        .description('Read a member\'s thread history — requires an APPROVED consent link for that member (403 if not present)')
+        .requiredOption('--username <username>')
+        .option('--limit <n>', `1-${MAX_LIST_LIMIT} (default 50)`, '50')
+        .option('--before <id>', 'message id cursor — older messages, newest-first')
+        .option('--after <id>', 'message id cursor — newer messages, oldest-first (mutually exclusive with --before)')).action(async (opts) => {
+        if (opts.before && opts.after)
+            fail(new Error('Use either --before or --after, not both.'));
+        try {
+            const body = await proxy('external/messages', {
+                method: 'GET',
+                team: opts.team,
+                query: { username: opts.username, limit: opts.limit, before: opts.before, after: opts.after },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+    // Internal surface: one-way feed push, NOT a conversation (no replies/reactions/attachments).
+    // Requires an APPROVED link_type='internal' consent row (stricter than External's write path).
+    teamOpt(program
+        .command('internal-message')
+        .description('Push a one-way message into a member\'s API Messages feed (internal surface — requires member consent)')
+        .requiredOption('--username <username>')
+        .requiredOption('--message <text>', 'max 60000 characters')
+        .option('--title <text>', 'max 200 characters')
+        .option('--link-url <url>', 'must be http(s)')
+        .option('--external-ref <ref>', 'idempotency key, max 190 chars — scoped per API key, not per recipient')).action(async (opts) => {
+        try {
+            const body = await proxy('internal/message', {
+                method: 'POST',
+                team: opts.team,
+                json: {
+                    username: opts.username,
+                    message: opts.message,
+                    title: opts.title,
+                    link_url: opts.linkUrl,
+                    external_ref: opts.externalRef,
+                },
+            });
+            printJson(body);
+        }
+        catch (e) {
+            fail(e);
+        }
+    });
+}