@openbat/cli 0.1.0

package/README.md

@@ -0,0 +1,292 @@
+# @openbat/cli
+
+Command-line tool for managing OpenBat chatbots end-to-end — read
+analytics + conversations, manage settings + keys + webhooks + workflows
++ reports, run experiments, and help install the SDK in a target app.
+
+> **Companion docs**: [`@openbat/mcp`](../mcp/README.md) (same surface
+> over MCP), [`lib/openbat-tools/`](../../lib/openbat-tools/README.md)
+> (tool registry that powers both), and the
+> [A-Z test guide](../../docs/agent-surface-testing.md).
+
+## Install
+
+```bash
+npm i -g @openbat/cli
+# or run on demand without installing:
+npx @openbat/cli --help
+```
+
+---
+
+## Authentication — four key kinds
+
+The CLI accepts any read-capable OpenBat key. Pick the smallest scope
+that works:
+
+| Prefix | Kind | Scope | What you can do |
+|---|---|---|---|
+| `ob_read_*` | read | one chatbot, **read-only** | Listing, analytics, conversations, export |
+| `ob_admin_*` | admin | one chatbot, **read+write** | All of read, plus webhooks / workflows / reports / settings / mint read keys |
+| `ob_pat_*` | PAT | one user across multiple chatbots and orgs | All of admin, plus `chatbots create/delete`, `org`, mint admin keys, multi-chatbot inventory |
+| `ob_live_*` | ingest | (rejected by the CLI) | SDK-only — capture endpoint. Never use here. |
+
+PATs also carry a sub-scope on the row (`read` or `admin`). A read-scope
+PAT can list across all your chatbots but mutate nothing.
+
+Generate keys in the dashboard:
+- **Read key** → `Settings → API Keys → Generate Read key`
+- **Admin key** → `Settings → API Keys → Generate Admin key`
+- **PAT** → `Settings → Personal Access Tokens`
+
+Each plaintext is shown exactly once.
+
+### Save the key
+
+```bash
+# Recommended — stdin keeps the plaintext out of shell history:
+echo "ob_pat_..." | openbat config set-key --from-stdin
+```
+
+Stored at `~/.openbatrc` with mode `0600`. The CLI refuses to load if
+the perms are looser than that.
+
+**Auth resolution order** (each falls through to the next):
+
+1. `--api-key <key>` flag — convenient but leaks into shell history;
+   discouraged.
+2. `$OPENBAT_API_KEY` env var — best for CI.
+3. `~/.openbatrc` — persistent local default.
+
+If you accidentally try to set an ingest key (`ob_live_*`), the CLI
+rejects it with a helpful error.
+
+---
+
+## Command tree
+
+```
+openbat
+├── config
+│   ├── set-key            Store / replace the key in ~/.openbatrc
+│   ├── set-url <baseUrl>  Override the API base URL
+│   └── show               Print the resolved config (key prefix only)
+│
+├── auth                                                      [any kind]
+│   ├── whoami             Show kind, chatbots in scope, orgs (PAT only)
+│   └── audit-log [--days] Recent api_audit_log entries (stub today)
+│
+├── org                                                       [pat]
+│   ├── list                                                  List user's orgs
+│   ├── show                                                  Active org + members
+│   ├── rename --id ORG --name "..."                          Owner only
+│   ├── members list --id ORG
+│   ├── members invite --id ORG --email --role member|admin
+│   ├── members set-role --id ORG --member M --role admin|member
+│   ├── members remove --id ORG --member M
+│   └── invitations list --id ORG
+│
+├── chatbots                                                  [any kind]
+│   ├── list                                                  Every chatbot in scope
+│   ├── create --name --website [--docs-url] [--mcp-url]      [pat] mint chatbot + ingest key
+│   └── delete <id>                                           [admin/pat] cascade delete
+│
+├── chatbot (legacy alias)
+│   └── info                                                  [any kind] current chatbot row
+│
+├── conversations                                             [any kind]
+│   ├── list [--days N] [--from ISO] [--to ISO] [--limit N]
+│   └── show <id>
+│
+├── users                                                     [any kind]
+│   └── list --chatbot ID [--days] [--search]                 External users + health
+│
+├── settings                                                  [admin or pat]
+│   ├── update --chatbot ID [--description] [--website-url] [--language]
+│   └── keys
+│       ├── list-admin --chatbot ID
+│       ├── rotate-ingest --chatbot ID                        New ob_live_* (shown once)
+│       ├── generate-read --chatbot ID                        New ob_read_* (shown once)
+│       ├── generate-admin --chatbot ID --name N [--expires-in-days]  [pat] new ob_admin_*
+│       └── revoke-admin --chatbot ID --key KEYID             [pat] revoke
+│
+├── webhooks                                                  [admin or pat]
+│   ├── list --chatbot ID
+│   ├── create --chatbot ID --name --url --type discord|slack|custom    Returns signing secret (once)
+│   └── delete --chatbot ID --webhook WHID
+│
+├── workflows                                                 [admin or pat]
+│   ├── list --chatbot ID
+│   └── create --chatbot ID --name --template T --trigger-value V --webhook WHID [--message TPL]
+│       Templates: flag-to-webhook | outcome-to-webhook | sentiment-drop-to-webhook
+│
+├── reports                                                   [admin or pat]
+│   ├── list --chatbot ID
+│   └── create --chatbot ID [--name "..."]                    Returns org-private dashboard URL
+│
+├── analysis                                                  [admin or pat]
+│   ├── list --chatbot ID [--type] [--pending]
+│   └── add --chatbot ID --type intent|flag|assistant_outcome|assistant_issue
+│            --name SLUG --display-name "..." --description "..."
+│
+├── analytics                                                 [any kind]
+│   ├── overview
+│   └── sentiment [--days N]
+│
+├── export --format json|csv [--out FILE]                     [any kind] streaming export
+│
+└── sdk                                                       [any kind]
+    ├── install-instructions [--framework next|node|vercel-ai-sdk] [--chatbot ID]
+    └── verify --chatbot ID [--timeout N]                     Polls until first event
+```
+
+Every command supports `--json` for raw output (default for non-TTY
+stdout, so piping into `jq` always works).
+
+---
+
+## Write commands — what to expect
+
+Mutating commands follow a consistent output convention so scripts
+and humans can both consume them cleanly:
+
+- **Plaintext secrets go to stderr**, inside a "shown ONCE" banner:
+
+  ```
+  ────────────────────────────────────────────────────────────
+    Webhook signing secret (shown ONCE — store this now)
+
+    whsec_abcdef…
+  ────────────────────────────────────────────────────────────
+  ```
+
+- **Structured response goes to stdout** without the plaintext, so
+  `... | jq` keeps working:
+
+  ```bash
+  openbat webhooks create --chatbot $CB --name foo --url ... --type slack > webhook.json
+  jq .id webhook.json
+  ```
+
+- **Errors go to stderr with a non-zero exit code.** API key plaintext
+  is automatically redacted from any error message (`ob_admin_<16 chars>…<hidden>`).
+
+- **HTTP 401 vs 403**: a 401 means "key invalid / expired / wrong kind
+  for this endpoint" — usually fixed by `openbat auth whoami` + a fresh
+  key. A 403 means "key valid but lacks permission" — e.g. a read-scope
+  PAT trying to mutate, or a member trying to do an owner-only action.
+
+- **HTTP 429** includes a `Retry-After` header. The CLI surfaces it in
+  the error message.
+
+---
+
+## Quickstart — chatbot zero to first event
+
+End-to-end in under 5 minutes. The full A-Z (including SDK install in a
+real Next.js app) lives in
+[`docs/agent-surface-testing.md`](../../docs/agent-surface-testing.md).
+
+```bash
+# 0. Configure a PAT (you mint this in the dashboard).
+echo "ob_pat_..." | openbat config set-key --from-stdin
+
+# 1. Verify scope.
+openbat auth whoami
+
+# 2. Create a chatbot.
+openbat chatbots create --name "My Bot" --website https://example.com
+#   stderr: Ingest API key (shown ONCE)
+#   stdout: { chatbot: { id, ... }, dashboardUrl }
+CB=<chatbot id from stdout>
+
+# 3. Mint an admin key so we can manage it without the PAT.
+openbat settings keys generate-admin --chatbot $CB --name "dev" --expires-in-days 30
+#   stderr: ob_admin_... (shown ONCE)
+
+# 4. Add a webhook + a workflow that fires it on a flag.
+openbat webhooks create --chatbot $CB --name "ops" \
+  --url https://hooks.slack.com/services/T.../B.../X --type slack
+#   stdout: { id: WH_ID, ... }
+
+openbat analysis add --chatbot $CB --type flag --name billing_issue \
+  --display-name "Billing Issue" --description "Customer raises a billing concern"
+
+openbat workflows create --chatbot $CB \
+  --name "billing → slack" \
+  --template flag-to-webhook \
+  --trigger-value billing_issue \
+  --webhook $WH_ID
+
+# 5. Help an agent install the SDK in a target app.
+openbat sdk install-instructions --framework next --chatbot $CB
+# Markdown to stdout — agent (or you) follows the steps.
+
+# 6. After SDK is wired up + a real chat sent, verify ingestion:
+openbat sdk verify --chatbot $CB --timeout 60
+# Exits 0 on first event, 2 on timeout.
+
+# 7. Read your data.
+openbat conversations list --days 7
+openbat analytics overview
+```
+
+---
+
+## Override the API base URL
+
+```bash
+openbat config set-url https://staging.openbat.dev
+# or per-invocation:
+openbat --base-url http://localhost:3000 auth whoami
+# or via env:
+OPENBAT_BASE_URL=http://localhost:3000 openbat auth whoami
+```
+
+The CLI **refuses non-HTTPS base URLs** unless they point at `localhost`
+or `127.0.0.1`. There is no `--insecure` escape hatch.
+
+---
+
+## Security properties
+
+- API key plaintext never lands in any error message — auto-redacted to
+  `ob_<kind>_<first 16>…<hidden>`.
+- HTTPS-only base URL (localhost exception only).
+- `~/.openbatrc` enforced at `mode 0600`; the loader refuses looser perms.
+- Mint commands print plaintext to stderr only, with a "shown ONCE"
+  banner. Pipe stderr to `/dev/null` if you don't want it on screen
+  (you'll lose the secret).
+- Every authenticated call lands in `api_audit_log` server-side
+  (migration 036) — operators can answer "who did what when" via
+  Supabase Studio.
+
+## Rate limits
+
+Per-tool buckets keyed by credential. The strict ones to know about:
+
+| Operation | Limit |
+|---|---|
+| Create chatbot | 5 per hour per PAT |
+| Mint or rotate any key | 10 per hour per credential |
+| Create backtest | 10 per hour per PAT |
+| Invite org member | 20 per hour per PAT |
+| Chat with an AI report | 30 per minute per credential |
+| Generic write | 60 per minute per credential |
+| Generic read | 600 per minute per credential |
+| Export | 30 per hour per credential |
+
+429 responses include `Retry-After` (seconds).
+
+---
+
+## See also
+
+- [`@openbat/mcp`](../mcp/README.md) — the same surface to Claude /
+  Cursor / any MCP client.
+- [`@openbat/sdk`](../sdk/README.md) — capture conversations from your
+  app (uses the ingest key only).
+- [`lib/openbat-tools/`](../../lib/openbat-tools/README.md) — the
+  registry that powers every CLI command + MCP tool + v1 route.
+- [A-Z test guide](../../docs/agent-surface-testing.md) — clone the
+  repo and exercise every key kind, CLI, MCP, SDK in ~30 minutes.

package/bin/openbat

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Thin shim — loads the CommonJS entry compiled by tsup.
+require("../dist/index.js");

package/dist/api-client.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Minimal fetch wrapper used by both the CLI and the MCP server.
+ *
+ * Two design properties worth preserving:
+ *
+ *   • **HTTPS-only.** The constructor refuses non-HTTPS base URLs unless
+ *     they point at localhost. There is no `--insecure` escape hatch —
+ *     if you need to test against a self-signed cert, fix the cert.
+ *
+ *   • **Key redaction.** The client never emits the plaintext API key in
+ *     any error message. If a request fails, only the response status
+ *     and the server's generic error string are exposed.
+ */
+type ApiClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+};
+declare class ApiClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(opts: ApiClientOptions);
+    /**
+     * Issue a GET against `path` (must begin with `/`). Returns the parsed
+     * JSON on 200. Throws an Error whose message is safe to print (key
+     * redacted, status included).
+     */
+    get<T = unknown>(path: string): Promise<T>;
+    /** Issue a POST with a JSON body. */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Issue a PATCH with a JSON body. */
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Issue a DELETE. Body is rarely used; we still allow it. */
+    delete<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Pass-through for streaming endpoints (export). Returns the raw body. */
+    getRaw(path: string): Promise<{
+        body: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+}
+
+export { ApiClient, type ApiClientOptions };

package/dist/api-client.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal fetch wrapper used by both the CLI and the MCP server.
+ *
+ * Two design properties worth preserving:
+ *
+ *   • **HTTPS-only.** The constructor refuses non-HTTPS base URLs unless
+ *     they point at localhost. There is no `--insecure` escape hatch —
+ *     if you need to test against a self-signed cert, fix the cert.
+ *
+ *   • **Key redaction.** The client never emits the plaintext API key in
+ *     any error message. If a request fails, only the response status
+ *     and the server's generic error string are exposed.
+ */
+type ApiClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+};
+declare class ApiClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(opts: ApiClientOptions);
+    /**
+     * Issue a GET against `path` (must begin with `/`). Returns the parsed
+     * JSON on 200. Throws an Error whose message is safe to print (key
+     * redacted, status included).
+     */
+    get<T = unknown>(path: string): Promise<T>;
+    /** Issue a POST with a JSON body. */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Issue a PATCH with a JSON body. */
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Issue a DELETE. Body is rarely used; we still allow it. */
+    delete<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Pass-through for streaming endpoints (export). Returns the raw body. */
+    getRaw(path: string): Promise<{
+        body: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+}
+
+export { ApiClient, type ApiClientOptions };

package/dist/api-client.js

@@ -0,0 +1,175 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/api-client.ts
+var api_client_exports = {};
+__export(api_client_exports, {
+  ApiClient: () => ApiClient
+});
+module.exports = __toCommonJS(api_client_exports);
+var import_node_url = require("url");
+var KEY_REGEX = /ob_(?:live|read|admin|pat)_[0-9a-f]{32}/g;
+function redact(s) {
+  return s.replace(KEY_REGEX, (k) => `${k.slice(0, 16)}\u2026<hidden>`);
+}
+function assertHttpsOrLocalhost(baseUrl) {
+  let url;
+  try {
+    url = new import_node_url.URL(baseUrl);
+  } catch {
+    throw new Error(`Invalid base URL: ${redact(baseUrl)}`);
+  }
+  if (url.protocol === "https:") return;
+  if (url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1")) {
+    return;
+  }
+  throw new Error(
+    "Refusing to use a non-HTTPS base URL. localhost / 127.0.0.1 are allowed for dev."
+  );
+}
+var _apiKey, _ApiClient_instances, mutate_fn;
+var ApiClient = class {
+  constructor(opts) {
+    __privateAdd(this, _ApiClient_instances);
+    __privateAdd(this, _apiKey);
+    assertHttpsOrLocalhost(opts.baseUrl);
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    __privateSet(this, _apiKey, opts.apiKey);
+  }
+  /**
+   * Issue a GET against `path` (must begin with `/`). Returns the parsed
+   * JSON on 200. Throws an Error whose message is safe to print (key
+   * redacted, status included).
+   */
+  async get(path) {
+    const url = `${this.baseUrl}${path}`;
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "GET",
+        headers: {
+          "x-openbat-key": __privateGet(this, _apiKey),
+          accept: "application/json"
+        }
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Request to ${redact(url)} failed: ${redact(msg)}`);
+    }
+    return parseResponse(res, url);
+  }
+  /** Issue a POST with a JSON body. */
+  async post(path, body) {
+    return __privateMethod(this, _ApiClient_instances, mutate_fn).call(this, "POST", path, body);
+  }
+  /** Issue a PATCH with a JSON body. */
+  async patch(path, body) {
+    return __privateMethod(this, _ApiClient_instances, mutate_fn).call(this, "PATCH", path, body);
+  }
+  /** Issue a DELETE. Body is rarely used; we still allow it. */
+  async delete(path, body) {
+    return __privateMethod(this, _ApiClient_instances, mutate_fn).call(this, "DELETE", path, body);
+  }
+  /** Pass-through for streaming endpoints (export). Returns the raw body. */
+  async getRaw(path) {
+    const url = `${this.baseUrl}${path}`;
+    const res = await fetch(url, {
+      method: "GET",
+      headers: {
+        "x-openbat-key": __privateGet(this, _apiKey)
+      }
+    });
+    if (!res.ok || !res.body) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(
+        `GET ${redact(url)} \u2192 ${res.status} ${res.statusText}${errText ? `: ${redact(errText.slice(0, 200))}` : ""}`
+      );
+    }
+    return {
+      body: res.body,
+      contentType: res.headers.get("content-type") ?? "application/octet-stream"
+    };
+  }
+};
+_apiKey = new WeakMap();
+_ApiClient_instances = new WeakSet();
+mutate_fn = async function(method, path, body) {
+  const url = `${this.baseUrl}${path}`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        "x-openbat-key": __privateGet(this, _apiKey),
+        "content-type": "application/json",
+        accept: "application/json"
+      },
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Request to ${redact(url)} failed: ${redact(msg)}`);
+  }
+  return parseResponse(res, url);
+};
+async function parseResponse(res, url) {
+  if (res.status === 401) {
+    throw new Error(
+      "Unauthorized. The API key was rejected (invalid, wrong kind for this endpoint, expired, or revoked)."
+    );
+  }
+  if (res.status === 403) {
+    throw new Error(
+      "Forbidden. The credential is valid but lacks permission for this operation (e.g. read-scope PAT can't mutate)."
+    );
+  }
+  if (res.status === 429) {
+    const retry = res.headers.get("retry-after");
+    throw new Error(
+      `Rate limited.${retry ? ` Retry after ${retry}s.` : ""}`
+    );
+  }
+  if (!res.ok) {
+    let errBody = null;
+    try {
+      errBody = await res.json();
+    } catch {
+    }
+    throw new Error(
+      `GET ${redact(url)} \u2192 ${res.status} ${res.statusText}${errBody?.error ? `: ${redact(errBody.error)}` : ""}`
+    );
+  }
+  try {
+    return await res.json();
+  } catch {
+    throw new Error(`Response from ${redact(url)} was not valid JSON`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiClient
+});

package/dist/api-client.mjs

@@ -0,0 +1,6 @@
+import {
+  ApiClient
+} from "./chunk-CRJZM45P.mjs";
+export {
+  ApiClient
+};