@inboxychat/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# @inboxychat/cli — `inboxy`
 
-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 for agencies and support: check a key, read orders, contacts and
+usage, and diagnose a setup. It supports public reads and audited, explicitly confirmed operation adapters.
+
+Published on npm as [`@inboxychat/cli`](https://www.npmjs.com/package/@inboxychat/cli).
+Full guide (English and Arabic): https://inboxy.chat/developers/cli
+
+## Install
+
+Needs Node.js 20.3 or newer.
+
+```bash
+npm i -g @inboxychat/cli
+inboxy --version
+# or without installing:
+npx -y -p @inboxychat/cli inboxy --help
+```
+
+Create the key in the Inboxy dashboard as a company admin (Developers → API,
+`/developer-center/api`), with only the scopes you need
+(`orders:read`, `contacts:read`, `analytics:read`, ...) and an expiry.
+
+### From this repository
+
+```bash
+pnpm install
+pnpm --filter @inboxychat/cli build          # builds the SDK too
+node packages/inboxy-cli/dist/bin.js --help
+```
+
+## Sign in
+
+```bash
+inboxy auth login                      # browser approval on a terminal
+pbpaste | inboxy auth login            # or pipe a key (not a TTY; stays out of shell history)
+inboxy auth login --profile client-a   # one profile per company (agencies)
+inboxy auth status                     # where the key comes from + is it accepted
+inboxy auth logout --profile client-a
+```
+
+On a terminal, `inboxy auth login` opens Inboxy in the browser. You approve the
+code, and the CLI stores the API key that approval mints. The key is never a
+command-line argument: `inboxy auth login <key>` or a `--key` / `--token` /
+`--api-key` flag on any command is refused (exit 2) without echoing what was
+typed. When stdin is not a terminal, the same command reads a key from the pipe instead.
+
+It is stored in the OS keychain (macOS Keychain via `security`, Linux Secret Service via
+`secret-tool`; the secret goes to those tools on stdin, not argv). Without a
+keychain (or with `--store file`) it goes into the config file with mode `0600`
+in a `0700` directory; a config file other users can read is refused.
+
+Config: `$INBOXY_CONFIG_DIR`, else `$XDG_CONFIG_HOME/inboxy`, else
+`~/.config/inboxy/config.json`. It holds the API URL and where the key lives.
+
+`INBOXY_API_KEY` / `INBOXY_API_URL` / `INBOXY_PROFILE` override everything.
+`INBOXY_KEYCHAIN=off` disables the keychain.
+
+## Commands
+
+```
+inboxy whoami                         company, key name, scopes, expiry, rate limits
+inboxy usage                          plan usage against limits
+inboxy stores list                    connected-store count vs plan limit (*)
+inboxy orders list [--status pending] [--payment-status ..] [--fulfillment-status ..]
+                   [--source shopify] [--store <id>] [--contact <id>] [--search <text>]
+                   [--after <iso>] [--before <iso>]
+inboxy orders get <id>
+inboxy contacts search [text] [--status ..] [--stage lead] [--tags <ids>]
+                   [--created-after <iso>] [--created-before <iso>]
+inboxy doctor                         URL, key, key format, reachability, scopes,
+                                      key expiry, clock skew, config permissions
+```
+
+(\*) The public API has no stores route yet, so `stores list` shows the count
+from plan usage and says so (`items: null` in JSON). Per-store health is in the
+dashboard.
+
+Paging: `--limit 1-100`, `--cursor <nextCursor>`, or `--all` (follows cursors,
+up to `--max-pages`, default 10). Global: `--json`, `--profile`, `--url`,
+`--timeout <ms>`. Global options may come before or after the command.
+
+## `--json`
+
+One document on stdout, schema version 1 (fields may be added, never renamed or removed):
+
+```json
+{ "schemaVersion": 1, "ok": true, "command": "orders list",
+  "data": [ ... ], "meta": { "limit": 20, "hasMore": true, "nextCursor": "...", "pages": 1 } }
+
+{ "schemaVersion": 1, "ok": false, "command": "orders list",
+  "error": { "kind": "forbidden", "code": "INSUFFICIENT_PERMISSIONS", "status": 403,
+             "message": "This API key does not have the \"orders:read\" scope. ...",
+             "details": { "requiredScope": "orders:read" }, "retryAfterSeconds": null } }
+```
+
+`data` items are the public API v1 objects unchanged.
+
+## Exit codes
+
+| Code | Meaning                                                                   |
+| ---- | ------------------------------------------------------------------------- |
+| 0    | OK                                                                        |
+| 1    | Unexpected error                                                          |
+| 2    | Usage error (bad flag, bad value, invalid id) — nothing was sent          |
+| 3    | Configuration: no key, bad URL, config file permissions, no keychain      |
+| 4    | Key refused (401)                                                         |
+| 5    | Forbidden (403): missing scope, company paused, key owner no longer admin |
+| 6    | Not found (404)                                                           |
+| 7    | Rate limited (429) — see `retryAfterSeconds`                              |
+| 8    | Network error, timeout or cancelled                                       |
+| 9    | Server error or a response that is not the API envelope                   |
+| 10   | `doctor` found at least one failing check                                 |
+
+## Safety
+
+- The key is never printed. Errors and JSON pass through redaction (any
+  `inboxy_…` value, any `Bearer …` value and the exact key in use), even when a
+  server message echoes the header back. Status output shows only the 8-character
+  prefix the dashboard also shows.
+- No shell: inputs reach the API only as validated, percent-encoded path
+  segments or query values; ids must be 1–64 letters, digits, `_` or `-`.
+- HTTPS only (plain `http://` for `localhost` only); redirects are refused.
+
+## Tests
+
+```bash
+pnpm --filter @inboxychat/cli test
+```
+
+`test/cli.e2e.test.ts` runs the built binary against the local mock API:
+every command, paging, filters, exit codes, the key never in stdout/stderr,
+no shell interpolation, auth login/status/logout with the 0600 file, refusal
+of a world-readable config, profiles per company, and doctor (clock skew,
+scopes, expiry, refused key, unreachable URL). `test/cli.inprocess.test.ts`
+covers the keychain path with a fake keychain and redaction of a key echoed by
+the server. The macOS Keychain adapter was also checked once by hand with a
+throwaway entry (store, update, read, delete).
+
+## Audited operations
+
+`inboxy operations list` and `operations inspect <id>` expose the same 80 schemas
+as the SDK and MCP. `operations preview <id> --input '<json>' --idempotency-key
+<unique-key>` validates locally without credentials or network access. Review the
+payload and warning, then explicitly approve with `operations run <id> --input
+'<same-json>' --idempotency-key <same-key> --confirm <preview-hash>`.
+Use `--json` for structured output. Do not put sensitive input in shell history;
+call the SDK directly when inputs contain private material. A changed payload or
+key invalidates confirmation. No automatic retry occurs. Existing API scopes,
+roles and tenant isolation apply. This is bounded coverage, not full UI parity;
+see [SDK operation boundaries](../inboxy-sdk/README.md#audited-operation-adapters).
+
+
+### Expanded operation coverage
+
+The source catalog now has 80 operations (553 discovery routes). Added inbox
+assignment/status/labels/internal notes; separate one-message text sending;
+reviewed AI text knowledge and channel assignments; manual orders, state/payment/
+fulfillment records; product/category creation and updates. Inspect the catalog
+for exact schemas. Media/templates/bulk sends, scheduling, order cancellation/
+refunds, URL/file knowledge ingestion and complete automation coverage remain out
+of scope. Orders may trigger configured automation; payment-record changes do not
+charge a payment provider.
+
+For a send, preview `inbox.message.send` with `conversationId`, `target` containing
+`contactId`, `channelId`, `channelType` (uppercase enum), and `body.content`.
+Inspect the conversation first and approve the exact recipient, channel and full
+text. CLI uses `messages send --input <same-json> --idempotency-key <same-key>
+--confirm <hash>`; MCP uses the separate `message_send` tool with identical input,
+idempotencyKey and confirmation. Generic operation execution in CLI/MCP refuses
+sends. The SDK dispatch includes a confirmed-target header, validated against the
+current tenant conversation before send; a mismatch requires a new inspection and
+approval. Stable clientMessageId supplements the existing idempotency middleware.
+
+The lifecycle slice adds contact status/stage/assignment/internal notes, tag management and bounded flat custom-field replacement. It adds automation graph/run inspection, inactive draft creation and pause, plus campaign audience estimation, pause and cancel. Tag changes may trigger configured automations. Automation graph editing/publish remain unavailable; a preview estimate does not authorize scheduling.
+
+Workflow activation: first execute `automations.activation.preview`, show the entire returned preview, then pass it unchanged as `body.approval` to `automations.activate` with an exact confirmation and idempotency key. The server rechecks tenant, published version/hash, complete preview and workflow revision in a transaction. MCP uses `lifecycle_activate`; CLI uses `lifecycle activate <operation>`. The generic operation runner refuses activate effects, including AI publish/channel changes. `automations.simulate` uses existing dry services and skips external side effects.
+
+Campaign delivery uses `campaigns.approval` to resolve a complete snapshot (audience, sender, template/content, limits and exact time). Pass that unchanged in `body.approval` to `campaigns.send`, `campaigns.resume` or `campaigns.schedule`, preview locally, then obtain explicit approval. MCP requires `campaign_send` or `campaign_schedule`; CLI requires `campaigns send <operation>` or `campaigns schedule`. The server freezes approval and checks it again before delivery. These actions can send real customer messages and consume budget. Keep the same idempotency key for recovery. Version 0.2.0 is prepared locally; publication and API deployment are separate release steps.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { runCli } from './cli.js';
+/** Opens an http(s) URL in the OS browser. Argument array only — no shell. */
+function openBrowser(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return;
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => undefined);
+    child.unref();
+}
+async function readAll(stream) {
+    let data = '';
+    stream.setEncoding('utf8');
+    for await (const chunk of stream)
+        data += chunk;
+    return data;
+}
+/** Reads a line from the terminal without echoing it. */
+function promptHidden(prompt) {
+    const stdin = process.stdin;
+    process.stderr.write(prompt);
+    return new Promise((resolve) => {
+        let input = '';
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n' || ch === '\u0004') {
+                    stdin.setRawMode(false);
+                    stdin.pause();
+                    stdin.off('data', onData);
+                    process.stderr.write('\n');
+                    resolve(input);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    stdin.setRawMode(false);
+                    process.stderr.write('\n');
+                    process.exit(130);
+                }
+                if (ch === '\u007f' || ch === '\b')
+                    input = input.slice(0, -1);
+                else
+                    input += ch;
+            }
+        };
+        stdin.on('data', onData);
+    });
+}
+const io = {
+    stdout: (t) => process.stdout.write(t),
+    stderr: (t) => process.stderr.write(t),
+    readSecret: (prompt) => (process.stdin.isTTY ? promptHidden(prompt) : readAll(process.stdin)),
+    interactive: Boolean(process.stdin.isTTY),
+    openUrl: openBrowser,
+    env: process.env,
+    now: () => Date.now(),
+};
+runCli(process.argv.slice(2), io).then((code) => {
+    process.exitCode = code;
+}, () => {
+    process.stderr.write('inboxy: unexpected failure\n');
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,8EAA8E;AAC9E,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO;IACxE,MAAM,OAAO,GACX,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IAC7F,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3F,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACnC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,MAAyB;IAC9C,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM;QAAE,IAAI,IAAI,KAAe,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yDAAyD;AACzD,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,CAAC,MAAM,EAAE,CAAC;QACf,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,EAAE;YAC/B,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;oBAClD,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;oBACxB,KAAK,CAAC,KAAK,EAAE,CAAC;oBACd,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;oBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAC3B,OAAO,CAAC,KAAK,CAAC,CAAC;oBACf,OAAO;gBACT,CAAC;gBACD,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;oBACpB,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;oBACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBAC3B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACpB,CAAC;gBACD,IAAI,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI;oBAAE,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;;oBAC1D,KAAK,IAAI,EAAE,CAAC;YACnB,CAAC;QACH,CAAC,CAAC;QACF,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,EAAE,GAAU;IAChB,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACtC,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC7F,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;IACzC,OAAO,EAAE,WAAW;IACpB,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAEF,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CACpC,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,GAAG,EAAE;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACrD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+import { type Keychain } from '@inboxychat/sdk';
+import { type CliIO } from './output.js';
+export declare const CLI_VERSION = "0.2.0";
+export interface CliDeps {
+    /** Override the OS keychain (tests); undefined = detect, null = none. */
+    keychain?: Keychain | null;
+}
+/** Commands that only touch local configuration (no capability behind them). */
+export declare const LOCAL_COMMANDS: readonly ["auth login", "auth logout", "auth status", "doctor"];
+/**
+ * Data commands: each is the adapter of one registered capability (UX26-F,
+ * apps/api/src/lib/capabilities). A command without one is not offered.
+ */
+export declare const DATA_COMMANDS: string[];
+export declare const OPERATION_COMMANDS: readonly ["operations list", "operations inspect", "operations preview", "operations run", "messages send", "lifecycle activate", "campaigns send", "campaigns schedule"];
+export declare function runCli(argv: string[], io: CliIO, deps?: CliDeps): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AASA,OAAO,EAuBL,KAAK,QAAQ,EAKd,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAmC,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAE1E,eAAO,MAAM,WAAW,UAAU,CAAC;AAmEnC,MAAM,WAAW,OAAO;IACtB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AA6DD,gFAAgF;AAChF,eAAO,MAAM,cAAc,iEAAkE,CAAC;AAE9F;;;GAGG;AACH,eAAO,MAAM,aAAa,UAEzB,CAAC;AAEF,eAAO,MAAM,kBAAkB,2KASrB,CAAC;AAaX,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,GAAE,OAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA6f3F"}