@intercom/cli 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,128 @@
+# Intercom CLI
+
+CLI tool for managing Intercom workspaces. Designed for both human operators and AI agents.
+
+## Install
+
+```bash
+npm install -g @intercom/cli
+```
+
+## Quick Start
+
+```bash
+# Authenticate with your API token
+export INTERCOM_TOKEN="<your-token>"
+
+# Check your identity
+intercom me
+
+# List help center articles
+intercom articles list
+
+# Get a conversation
+intercom conversations get <conversation-id>
+
+# Set up a workspace with articles and Fin
+intercom setup --company-name "Acme" --articles-from ./docs
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `intercom api <endpoint>` | Raw API access (like `gh api`) |
+| `intercom auth login` | Authenticate with token |
+| `intercom auth logout` | Remove stored credentials |
+| `intercom auth status` | Show current auth state |
+| `intercom auth bootstrap` | Bootstrap OAuth via Developer Hub |
+| `intercom me` | Show current admin and workspace |
+| `intercom articles list\|get\|create\|update\|delete` | Manage help center articles |
+| `intercom contacts list\|get\|create\|update\|delete` | Manage contacts |
+| `intercom conversations list\|get\|reply` | Manage conversations |
+| `intercom help-center list\|get\|create` | Manage help center collections |
+| `intercom messenger get\|update\|snippet` | Configure Messenger |
+| `intercom fin manifest` | Show Fin SDK manifest |
+| `intercom fin enable` | Enable Fin AI Agent |
+| `intercom fin guidance list\|get` | Manage Fin guidance |
+| `intercom setup` | Orchestrate full workspace setup |
+
+## Global Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as pretty-printed JSON |
+| `--jq <expr>` | Filter JSON output (subset of jq) |
+| `--workspace <id>` | Override default workspace |
+| `--verbose` | Show HTTP request/response details |
+| `--no-retry` | Disable automatic rate limit retry |
+| `--timeout <seconds>` | Request timeout in seconds |
+| `--version` | Print CLI version |
+
+## Agent / Pipe Mode
+
+When stdout is not a TTY (piped to another program), the CLI automatically outputs compact NDJSON — one JSON object per line. No flag needed:
+
+```bash
+# Automatic NDJSON when piped
+intercom articles list | jq '.title'
+
+# Force JSON with flag
+intercom articles list --json
+
+# Filter inline
+intercom articles list --jq '.data[].title'
+```
+
+## Raw API Access
+
+The `intercom api` command provides direct access to any Intercom API endpoint:
+
+```bash
+# GET request (default)
+intercom api /me
+
+# POST with fields
+intercom api /articles -f title="Hello" -f author_id=123
+
+# Typed fields (booleans, numbers, file reads)
+intercom api /articles -F draft:=true -F body=@article.html
+
+# Auto-paginate
+intercom api /articles --paginate
+
+# Use jq to filter
+intercom api /contacts --jq '.data[].email'
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `INTERCOM_TOKEN` | API token (bypasses credential store) |
+| `INTERCOM_API_BASE_URL` | Override API base URL |
+| `INTERCOM_APP_BASE_URL` | Override app base URL |
+| `INTERCOM_CONFIG_DIR` | Override config directory |
+| `INTERCOM_PASSWORD` | Password for signup/bootstrap |
+
+## Development
+
+```bash
+git clone git@github.com:intercom/cli.git
+cd cli
+npm ci
+npm run build   # Build to dist/
+npm test        # Run tests (~9s)
+npm run lint    # TypeScript typecheck
+npm run dev     # Watch mode
+
+# Try it locally
+export INTERCOM_TOKEN="<your-token>"
+node dist/index.js me
+```
+
+See [SETUP.md](SETUP.md) for full developer setup guide.
+
+## License
+
+MIT

package/dist/chunk-QEXGKXTU.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+// src/types.ts
+var CLIError = class extends Error {
+  constructor(message, exitCode = 1, error) {
+    super(message);
+    this.exitCode = exitCode;
+    this.error = error;
+    this.name = "CLIError";
+  }
+};
+var AuthError = class extends CLIError {
+  constructor(message) {
+    super(message, 2);
+  }
+};
+var RateLimitError = class extends CLIError {
+  constructor(message, retryAfter) {
+    super(message, 3);
+    this.retryAfter = retryAfter;
+  }
+};
+var NotFoundError = class extends CLIError {
+  constructor(message) {
+    super(message, 4);
+  }
+};
+var PermissionError = class extends CLIError {
+  constructor(message) {
+    super(message, 5);
+  }
+};
+var TimeoutError = class extends CLIError {
+  constructor(message) {
+    super(message, 6);
+  }
+};
+function detectAuthType(token) {
+  try {
+    const decoded = Buffer.from(token, "base64").toString("utf-8");
+    if (decoded.startsWith("tok:")) {
+      return "oauth";
+    }
+  } catch {
+  }
+  return "api_key";
+}
+
+// src/output/json.ts
+function formatJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+function applyJq(data, expr) {
+  if (expr === ".") return data;
+  if (!expr.startsWith(".")) {
+    throw new CLIError(
+      `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
+    );
+  }
+  if (/[|(){},;]/.test(expr)) {
+    throw new CLIError(
+      `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
+    );
+  }
+  const parts = expr.replace(/^\.\s*/, "").split(/\./).filter(Boolean);
+  for (const part of parts) {
+    if (!/^\w+(\[\])?$/.test(part)) {
+      throw new CLIError(
+        `Unsupported jq expression: "${expr}". Supported: ".", ".field", ".field.nested", ".field[].nested"`
+      );
+    }
+  }
+  let current = data;
+  for (const part of parts) {
+    const arrayMatch = part.match(/^(\w+)\[\]$/);
+    if (arrayMatch) {
+      const key = arrayMatch[1];
+      if (current && typeof current === "object" && key in current) {
+        const arr = current[key];
+        if (!Array.isArray(arr)) return void 0;
+        current = arr;
+      } else {
+        return void 0;
+      }
+    } else if (Array.isArray(current)) {
+      current = current.map(
+        (item) => item && typeof item === "object" ? item[part] : void 0
+      );
+    } else if (current && typeof current === "object") {
+      current = current[part];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+
+export {
+  CLIError,
+  AuthError,
+  RateLimitError,
+  NotFoundError,
+  PermissionError,
+  TimeoutError,
+  detectAuthType,
+  formatJson,
+  applyJq
+};
+//# sourceMappingURL=chunk-QEXGKXTU.js.map

package/dist/chunk-QEXGKXTU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/output/json.ts"],"sourcesContent":["export interface IntercomError {\n  code: string;\n  message: string;\n  status: number;\n  retry_after?: number;\n}\n\nexport class CLIError extends Error {\n  constructor(\n    message: string,\n    public readonly exitCode: number = 1,\n    public readonly error?: IntercomError,\n  ) {\n    super(message);\n    this.name = \"CLIError\";\n  }\n}\n\nexport class AuthError extends CLIError {\n  constructor(message: string) {\n    super(message, 2);\n  }\n}\n\nexport class RateLimitError extends CLIError {\n  constructor(\n    message: string,\n    public readonly retryAfter: number,\n  ) {\n    super(message, 3);\n  }\n}\n\nexport class NotFoundError extends CLIError {\n  constructor(message: string) {\n    super(message, 4);\n  }\n}\n\nexport class PermissionError extends CLIError {\n  constructor(message: string) {\n    super(message, 5);\n  }\n}\n\nexport class TimeoutError extends CLIError {\n  constructor(message: string) {\n    super(message, 6);\n  }\n}\n\nexport type AuthType = \"oauth\" | \"api_key\";\n\n/**\n * Detect whether a token is an OAuth token or an API key.\n * Eagle OAuth tokens are base64-encoded and decode to \"tok:...\" format.\n */\nexport function detectAuthType(token: string): AuthType {\n  try {\n    const decoded = Buffer.from(token, \"base64\").toString(\"utf-8\");\n    if (decoded.startsWith(\"tok:\")) {\n      return \"oauth\";\n    }\n  } catch {\n    // Not valid base64 — assume API key\n  }\n  return \"api_key\";\n}\n\nexport interface StoredCredential {\n  token: string;\n  auth_type: AuthType;\n  app_id: string;\n  workspace_name?: string;\n  expires_at?: string;\n}\n\nexport interface WorkspaceConfig {\n  app_id: string;\n  name: string;\n}\n\nexport interface Config {\n  workspaces: Record<string, WorkspaceConfig>;\n  default?: string;\n}\n\nexport interface PaginatedResponse<T> {\n  type: \"list\";\n  data: T[];\n  pages?: {\n    next?: string;\n    page: number;\n    per_page: number;\n    total_pages: number;\n  };\n}\n","import { CLIError } from \"../types.js\";\n\nexport function formatJson(data: unknown): string {\n  return JSON.stringify(data, null, 2);\n}\n\nexport function applyJq(data: unknown, expr: string): unknown {\n  if (expr === \".\") return data;\n\n  // Must start with \".\"\n  if (!expr.startsWith(\".\")) {\n    throw new CLIError(\n      `Unsupported jq expression: \"${expr}\". Supported: \".\", \".field\", \".field.nested\", \".field[].nested\"`,\n    );\n  }\n\n  // Reject pipes, functions, parens, etc.\n  if (/[|(){},;]/.test(expr)) {\n    throw new CLIError(\n      `Unsupported jq expression: \"${expr}\". Supported: \".\", \".field\", \".field.nested\", \".field[].nested\"`,\n    );\n  }\n\n  const parts = expr.replace(/^\\.\\s*/, \"\").split(/\\./).filter(Boolean);\n\n  for (const part of parts) {\n    if (!/^\\w+(\\[\\])?$/.test(part)) {\n      throw new CLIError(\n        `Unsupported jq expression: \"${expr}\". Supported: \".\", \".field\", \".field.nested\", \".field[].nested\"`,\n      );\n    }\n  }\n  let current: unknown = data;\n\n  for (const part of parts) {\n    const arrayMatch = part.match(/^(\\w+)\\[\\]$/);\n    if (arrayMatch) {\n      const key = arrayMatch[1];\n      if (current && typeof current === \"object\" && key in current) {\n        const arr = (current as Record<string, unknown>)[key];\n        if (!Array.isArray(arr)) return undefined;\n        current = arr;\n      } else {\n        return undefined;\n      }\n    } else if (Array.isArray(current)) {\n      current = current.map((item) =>\n        item && typeof item === \"object\"\n          ? (item as Record<string, unknown>)[part]\n          : undefined,\n      );\n    } else if (current && typeof current === \"object\") {\n      current = (current as Record<string, unknown>)[part];\n    } else {\n      return undefined;\n    }\n  }\n\n  return current;\n}\n"],"mappings":";;;AAOO,IAAM,WAAN,cAAuB,MAAM;AAAA,EAClC,YACE,SACgB,WAAmB,GACnB,OAChB;AACA,UAAM,OAAO;AAHG;AACA;AAGhB,SAAK,OAAO;AAAA,EACd;AACF;AAEO,IAAM,YAAN,cAAwB,SAAS;AAAA,EACtC,YAAY,SAAiB;AAC3B,UAAM,SAAS,CAAC;AAAA,EAClB;AACF;AAEO,IAAM,iBAAN,cAA6B,SAAS;AAAA,EAC3C,YACE,SACgB,YAChB;AACA,UAAM,SAAS,CAAC;AAFA;AAAA,EAGlB;AACF;AAEO,IAAM,gBAAN,cAA4B,SAAS;AAAA,EAC1C,YAAY,SAAiB;AAC3B,UAAM,SAAS,CAAC;AAAA,EAClB;AACF;AAEO,IAAM,kBAAN,cAA8B,SAAS;AAAA,EAC5C,YAAY,SAAiB;AAC3B,UAAM,SAAS,CAAC;AAAA,EAClB;AACF;AAEO,IAAM,eAAN,cAA2B,SAAS;AAAA,EACzC,YAAY,SAAiB;AAC3B,UAAM,SAAS,CAAC;AAAA,EAClB;AACF;AAQO,SAAS,eAAe,OAAyB;AACtD,MAAI;AACF,UAAM,UAAU,OAAO,KAAK,OAAO,QAAQ,EAAE,SAAS,OAAO;AAC7D,QAAI,QAAQ,WAAW,MAAM,GAAG;AAC9B,aAAO;AAAA,IACT;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO;AACT;;;ACjEO,SAAS,WAAW,MAAuB;AAChD,SAAO,KAAK,UAAU,MAAM,MAAM,CAAC;AACrC;AAEO,SAAS,QAAQ,MAAe,MAAuB;AAC5D,MAAI,SAAS,IAAK,QAAO;AAGzB,MAAI,CAAC,KAAK,WAAW,GAAG,GAAG;AACzB,UAAM,IAAI;AAAA,MACR,+BAA+B,IAAI;AAAA,IACrC;AAAA,EACF;AAGA,MAAI,YAAY,KAAK,IAAI,GAAG;AAC1B,UAAM,IAAI;AAAA,MACR,+BAA+B,IAAI;AAAA,IACrC;AAAA,EACF;AAEA,QAAM,QAAQ,KAAK,QAAQ,UAAU,EAAE,EAAE,MAAM,IAAI,EAAE,OAAO,OAAO;AAEnE,aAAW,QAAQ,OAAO;AACxB,QAAI,CAAC,eAAe,KAAK,IAAI,GAAG;AAC9B,YAAM,IAAI;AAAA,QACR,+BAA+B,IAAI;AAAA,MACrC;AAAA,IACF;AAAA,EACF;AACA,MAAI,UAAmB;AAEvB,aAAW,QAAQ,OAAO;AACxB,UAAM,aAAa,KAAK,MAAM,aAAa;AAC3C,QAAI,YAAY;AACd,YAAM,MAAM,WAAW,CAAC;AACxB,UAAI,WAAW,OAAO,YAAY,YAAY,OAAO,SAAS;AAC5D,cAAM,MAAO,QAAoC,GAAG;AACpD,YAAI,CAAC,MAAM,QAAQ,GAAG,EAAG,QAAO;AAChC,kBAAU;AAAA,MACZ,OAAO;AACL,eAAO;AAAA,MACT;AAAA,IACF,WAAW,MAAM,QAAQ,OAAO,GAAG;AACjC,gBAAU,QAAQ;AAAA,QAAI,CAAC,SACrB,QAAQ,OAAO,SAAS,WACnB,KAAiC,IAAI,IACtC;AAAA,MACN;AAAA,IACF,WAAW,WAAW,OAAO,YAAY,UAAU;AACjD,gBAAW,QAAoC,IAAI;AAAA,IACrD,OAAO;AACL,aAAO;AAAA,IACT;AAAA,EACF;AAEA,SAAO;AACT;","names":[]}