@intercom/cli 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to the Intercom CLI are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+View it from the CLI with `intercom changelog`.
+
+## [0.8.1] - 2026-06-16
+
+### Fixed
+
+- Show the server's actual error message on failed requests instead of a bare `HTTP <status>`. This covers Fin SDK endpoints like `fin workflows upload` and `fin procedures upload`, which report problems (e.g. `YAML syntax error`, `Invalid file content`, `File too large`) in a different format than the rest of the API. `--verbose` now also prints the response body on errors.
+- `fin workflows enable` and `fin workflows disable` now send the workflow state as the name the server expects (`live`/`paused`) instead of an internal numeric value, which the upload endpoint rejected. Both commands work again.
+
+## [0.7.0] - 2026-06-10
+
+### Added
+
+- `intercom changelog` command to view the CLI's release notes from the terminal
+- `fin data-connectors versions <id>` to view a data connector's version history
+- Auto-enable fin-sdk and retry when a fin command hits the gate (#102)
+
+### Changed
+
+- `fin data-connectors list` now shows each connector's state
+- `fin data-connectors get` now shows the full connector definition (method, URL, inputs, outputs)
+- `fin data-connectors create` now takes `--name` and returns the URL to finish configuring the connector in the UI
+
+### Fixed
+
+- Handle `login_verification` redirect in CLI sign-in (#99)
+
+## [0.6.0] - 2026-05-25
+
+### Added
+
+- `fin workflows upload`, `fin workflows enable`, and `fin workflows disable` (#95)
+- `fin monitor pull-flagged` and `fin conversation bulk-send` (#83)
+
+### Changed
+
+- Strip internal fields from conversation responses (#97)
+
+### Fixed
+
+- Target the correct workspace during bootstrap (#96)
+- Parse `fin workflows get` output as YAML, not JSON (#90)
+
+## [0.5.0] - 2026-04-27
+
+### Added
+
+- Emit a Claude Code plugin hint from `--help` and `auth login` (#91)
+
+## [0.4.0] - 2026-04-20
+
+### Added
+
+- `articles search` subcommand (#85)
+- `pricing` command to fetch live pricing information (#67)
+- `fin guidance create` command (#69)
+- `fin` as a binary alias for `intercom` (#66)
+- `intercom config` command (#43)
+- `auth list` and `auth switch` commands (#41)
+- Global `--dry-run` / `-n` flag (#48)
+- `--input` flag on the `api` command and search subcommands (#46)
+- Color output and a `--wide` flag for tables (#44)
+- 5xx retry with exponential backoff (#49)
+
+### Changed
+
+- Strip article bodies from list/search by default (#86)
+- Default messenger snippets to JWT authentication (#81)
+
+### Fixed
+
+- Improve `setup` command reliability for greenfield workspaces (#64)
+
+[0.7.0]: https://github.com/intercom/cli/releases/tag/v0.7.0
+[0.6.0]: https://github.com/intercom/cli/releases/tag/v0.6.0
+[0.5.0]: https://github.com/intercom/cli/releases/tag/v0.5.0
+[0.4.0]: https://github.com/intercom/cli/releases/tag/v0.4.0

package/README.md

@@ -73,6 +73,7 @@ intercom setup --company-name "Acme" --articles-from ./docs
 | `intercom setup` | Orchestrate full workspace setup |
 | `intercom config get\|set\|list` | Manage CLI configuration |
 | `intercom pricing` | Show current Intercom pricing |
+| `intercom changelog` | Show the CLI's release notes / version history |
 | `intercom completion bash\|zsh\|fish` | Generate shell completions |
 
 ## Global Flags
@@ -141,11 +142,11 @@ intercom api /contacts --jq '.data[].email'
 ```bash
 git clone git@github.com:intercom/cli.git
 cd cli
-npm ci
-npm run build   # Build to dist/
-npm test        # Run tests (~5s)
-npm run lint    # TypeScript typecheck
-npm run dev     # Watch mode
+pnpm install
+pnpm build      # Build to dist/
+pnpm test       # Run tests (~5s)
+pnpm lint       # TypeScript typecheck
+pnpm dev        # Watch mode
 
 # Try it locally
 export INTERCOM_TOKEN="<your-token>"
@@ -154,6 +155,35 @@ node dist/index.js me
 
 See [SETUP.md](SETUP.md) for full developer setup guide.
 
+## Releasing
+
+Publishing `@intercom/cli` to npm runs through `.github/workflows/publish.yml`, which fires when a GitHub Release is published. It uses OIDC trusted publishing (GitHub Actions mints a short-lived token per run, so there is no long-lived `NPM_TOKEN`) and npm staged publishing, which holds every version behind a human 2FA approval before it becomes installable. The org-wide reference is the [Engineering Wiki: Release new npm package versions](https://coda.io/d/Engineering-Wiki_duvlW1VbQXK/Release-new-npm-package-versions_suK1gai4).
+
+### Prerequisites (one-time)
+
+- **GitHub:** write access to this repo, to bump the version and create Releases.
+- **npm:** to approve a staged release, log in to npmjs.com as `intercom-npm-publisher` (the package owner). Credentials are in the 1Password Engineering Vault.
+
+### Cut a stable release
+
+1. **Bump the version.** In a PR, set the new `version` in `package.json` and move the unreleased entries in `CHANGELOG.md` under a new `## [X.Y.Z] - YYYY-MM-DD` heading. Merge it to `main` — the workflow refuses any release that is not reachable from the default branch.
+2. **Create a GitHub Release.** From the [Releases page](https://github.com/intercom/cli/releases/new), add a tag `vX.Y.Z` that matches `package.json` exactly (the `v` prefix is required; the workflow asserts `tag == version`). Leave the release label as **None**. Publishing the Release creates the tag and triggers `publish.yml`.
+3. **Wait for the workflow.** It runs the tag and branch guards, builds, then runs `npm stage publish` over OIDC. When the Actions run is green, the version sits in npm's staged queue — uploaded but not yet installable.
+4. **Approve in npm.** Logged in as `intercom-npm-publisher`, open [Staged Packages](https://www.npmjs.com/settings/intercom-npm-publisher/staged-packages), review the version, and **Approve** with 2FA. A stable version publishes to the `latest` dist-tag and is then installable via `npm install -g @intercom/cli`.
+
+### Cut a prerelease
+
+Same path and same approval gate; a prerelease lands on the `next` dist-tag instead of `latest`.
+
+1. Bump `package.json` to a version with a `-` suffix (e.g. `X.Y.Z-beta.1`) and merge to `main` via PR. Prereleases come from the default branch too.
+2. Create a GitHub Release tagged `vX.Y.Z-beta.1` from that commit (the tag must match the version) and tick **Set as a pre-release**.
+3. The workflow detects the `-` suffix and stages to the `next` tag, never `latest`.
+4. Approve the staged version with 2FA as above. Consumers opt in explicitly with `npm install -g @intercom/cli@next`; a plain install still resolves to stable `latest`.
+
+### Reject a staged release
+
+If a staged version should not ship, choose **Reject** in Staged Packages and it is removed without publishing. Rejecting leaves the git tag and GitHub Release behind, so also delete the Release and tag from the GitHub Releases UI. The version can then be re-staged — only published versions are immutable.
+
 ## License
 
 MIT

package/dist/index.js

@@ -61,6 +61,25 @@ async function fetchWithTimeout(url, init, options) {
 
 // src/api/client.ts
 var DEFAULT_BASE_URL = "https://api.intercom.io";
+var MAX_RAW_ERROR_LEN = 500;
+function extractApiError(body) {
+  if (!body || typeof body !== "object") return {};
+  const b = body;
+  if (Array.isArray(b.errors) && b.errors.length > 0) {
+    const first = b.errors[0];
+    return {
+      message: typeof first?.message === "string" ? first.message : void 0,
+      code: typeof first?.code === "string" ? first.code : void 0
+    };
+  }
+  if (typeof b.error === "string") return { message: b.error };
+  if (b.errors && typeof b.errors === "object") {
+    const msgs = Object.values(b.errors).flat().filter((m) => typeof m === "string");
+    if (msgs.length > 0) return { message: msgs.join("; ") };
+  }
+  if (typeof b.message === "string") return { message: b.message };
+  return {};
+}
 var _dryRun = false;
 function setDryRun(enabled) {
   _dryRun = enabled;
@@ -189,9 +208,21 @@ var IntercomClient = class _IntercomClient {
             return response.json();
         }
       }
-      const errorBody = await response.json().catch(() => ({}));
-      const errorMsg = errorBody?.errors?.[0]?.message ?? `HTTP ${response.status}`;
-      const errorCode = errorBody?.errors?.[0]?.code ?? "";
+      const rawBody = await response.text().catch(() => "");
+      if (this.verbose && rawBody) {
+        console.error(`< Body: ${rawBody}`);
+      }
+      let parsedBody;
+      try {
+        parsedBody = rawBody ? JSON.parse(rawBody) : void 0;
+      } catch {
+        parsedBody = void 0;
+      }
+      const extracted = extractApiError(parsedBody);
+      const trimmedBody = rawBody.trim();
+      const rawFallback = trimmedBody.length > MAX_RAW_ERROR_LEN ? `${trimmedBody.slice(0, MAX_RAW_ERROR_LEN)}\u2026` : trimmedBody;
+      const errorMsg = extracted.message ?? (rawFallback || `HTTP ${response.status}`);
+      const errorCode = extracted.code ?? "";
       if (response.status === 401) {
         throw new AuthError(
           `Authentication expired or invalid: ${errorMsg}. Run "intercom auth login" to re-authenticate.`
@@ -2545,9 +2576,13 @@ function registerProceduresCommand(fin) {
 }
 
 // src/commands/fin/data-connectors.ts
+function summarizeKeys(obj) {
+  if (!obj) return "";
+  return Object.keys(obj).join(", ");
+}
 function registerDataConnectorsCommand(fin) {
   const dataConnectors = fin.command("data-connectors").description("Manage Fin SDK data connectors");
-  dataConnectors.command("list").description("List data connectors from the Fin SDK manifest").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
+  dataConnectors.command("list").description("List data connectors from the Fin SDK manifest").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const result = await client.get("/fin-sdk/manifest");
@@ -2559,33 +2594,38 @@ function registerDataConnectorsCommand(fin) {
       }
       const rows = items.map((item) => ({
         ID: String(item.id ?? ""),
-        NAME: String(item.name ?? "")
+        NAME: String(item.name ?? ""),
+        STATE: String(item.state ?? "")
       }));
-      return table({ columns: ["ID", "NAME"], rows });
+      return table({ columns: ["ID", "NAME", "STATE"], rows });
     }, items);
   });
-  dataConnectors.command("create").description("Create a data connector").requiredOption("-f, --field <key=value>", "Field to set (e.g. name=<name>)", (v, acc) => [...acc, v], []).option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function() {
+  dataConnectors.command("create").description("Create a draft data connector (finish configuration in the UI)").requiredOption("--name <name>", "Name for the new data connector").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+The create endpoint only sets the name \u2014 it returns a web_url where you finish
+configuring the connector (request, inputs, outputs, auth) in the Intercom UI.
+
+Example:
+  $ intercom fin data-connectors create --name "Order lookup"`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
-    const fields = opts.field ?? [];
-    const body = {};
-    for (const f of fields) {
-      const eq = f.indexOf("=");
-      if (eq === -1) throw new Error(`Invalid field format: ${f}. Expected key=value`);
-      body[f.slice(0, eq)] = f.slice(eq + 1);
-    }
-    const result = await client.post("/fin-sdk/data-connectors", body);
+    const result = await client.post("/fin-sdk/data-connectors", {
+      name: opts.name
+    });
     render(
       result,
       opts,
       () => detail({
-        "ID": String(result.id ?? ""),
-        "Name": String(result.name ?? ""),
-        "Status": result.status != null ? String(result.status) : void 0
+        ID: String(result.id ?? ""),
+        Name: String(result.name ?? ""),
+        "Web URL": result.web_url != null ? String(result.web_url) : void 0,
+        "Next step": result.message != null ? String(result.message) : void 0
       })
     );
   });
-  dataConnectors.command("get <id>").description("Download a data connector by ID").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+  dataConnectors.command("get <id>").description("Download a data connector's full definition by ID").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function(id) {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const result = await client.get(`/fin-sdk/data-connectors/${id}/download`);
@@ -2593,11 +2633,36 @@ function registerDataConnectorsCommand(fin) {
       result,
       opts,
       () => detail({
-        "ID": String(result.id ?? ""),
-        "Name": String(result.name ?? "")
+        ID: String(result.id ?? ""),
+        Name: String(result.name ?? ""),
+        State: result.state != null ? String(result.state) : void 0,
+        Description: result.description != null ? String(result.description) : void 0,
+        "Direct Fin usage": result.enable_direct_usage != null ? String(result.enable_direct_usage) : void 0,
+        Method: result.request?.method != null ? String(result.request.method) : void 0,
+        URL: result.request?.url != null ? String(result.request.url) : void 0,
+        Inputs: summarizeKeys(result.inputs) || void 0,
+        Outputs: summarizeKeys(result.outputs) || void 0
       })
     );
   });
+  dataConnectors.command("versions <id>").description("List a data connector's server-side version history").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").action(async function(id) {
+    const opts = this.optsWithGlobals();
+    const client = await resolveClient(opts);
+    const result = await client.get(`/fin-sdk/data-connectors/${id}/versions`);
+    const items = result.versions ?? [];
+    render(items, opts, () => {
+      if (items.length === 0) {
+        return "No versions found.";
+      }
+      const rows = items.map((v) => ({
+        STATUS: String(v.status ?? ""),
+        CREATED: String(v.created_at ?? ""),
+        AUTHOR: String(v.author?.name ?? ""),
+        NOTE: String(v.note ?? "")
+      }));
+      return table({ columns: ["STATUS", "CREATED", "AUTHOR", "NOTE"], rows });
+    }, items);
+  });
 }
 
 // src/commands/fin/guidance.ts
@@ -2708,8 +2773,8 @@ function registerAudiencesCommand(fin) {
 import { readFile as readFile3 } from "fs/promises";
 import { basename as basename2 } from "path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-var STATE_LIVE = 1;
-var STATE_PAUSED = 2;
+var STATE_LIVE = "live";
+var STATE_PAUSED = "paused";
 function registerWorkflowsCommand(fin) {
   const workflows = fin.command("workflows").description("Manage Fin SDK workflows");
   workflows.command("list").description("List Fin SDK workflows").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").action(async function() {
@@ -4127,6 +4192,104 @@ function registerConfigCommand(program) {
   });
 }
 
+// src/commands/changelog.ts
+import pc2 from "picocolors";
+
+// src/changelog.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { fileURLToPath } from "url";
+var RELEASE_RE = /^##\s+\[?([^\]]+?)\]?(?:\s+-\s+(.+))?$/;
+var SECTION_RE = /^###\s+(.+)$/;
+var ENTRY_RE = /^[-*]\s+(.+)$/;
+function parseChangelog(markdown) {
+  const releases = [];
+  let release = null;
+  let section = null;
+  for (const raw of markdown.split("\n")) {
+    const line = raw.trimEnd();
+    const releaseMatch = line.match(RELEASE_RE);
+    if (releaseMatch) {
+      release = { version: releaseMatch[1].trim(), date: releaseMatch[2]?.trim() ?? "", sections: [] };
+      section = null;
+      releases.push(release);
+      continue;
+    }
+    if (!release) continue;
+    const sectionMatch = line.match(SECTION_RE);
+    if (sectionMatch) {
+      section = { title: sectionMatch[1].trim(), entries: [] };
+      release.sections.push(section);
+      continue;
+    }
+    const entryMatch = line.match(ENTRY_RE);
+    if (entryMatch && section) {
+      section.entries.push(entryMatch[1].trim());
+    }
+  }
+  return releases;
+}
+var cached;
+function loadChangelog() {
+  if (cached) return cached;
+  const path = fileURLToPath(new URL("../CHANGELOG.md", import.meta.url));
+  cached = parseChangelog(readFileSync5(path, "utf8"));
+  return cached;
+}
+
+// src/commands/changelog.ts
+function normalizeVersion(v) {
+  return v.replace(/^v/i, "");
+}
+function colorEnabled() {
+  return !!process.stdout.isTTY && !process.env.NO_COLOR;
+}
+function renderHuman(releases) {
+  const color = colorEnabled();
+  const out = [];
+  for (const release of releases) {
+    const heading = release.date ? `${release.version} \u2014 ${release.date}` : release.version;
+    out.push(color ? pc2.bold(heading) : heading);
+    for (const section of release.sections) {
+      out.push(`  ${color ? pc2.dim(section.title) : section.title}`);
+      for (const entry of section.entries) {
+        out.push(`    \u2022 ${entry}`);
+      }
+    }
+    out.push("");
+  }
+  return out.join("\n").trimEnd();
+}
+function registerChangelogCommand(program) {
+  program.command("changelog").description("Show the CLI's release notes / version history").argument("[version]", "Show a single version (e.g. 0.7.0)").option("-n, --limit <count>", "Show only the most recent <count> releases").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom changelog                 Show the full release history
+  $ intercom changelog --limit 1       Show only the latest release
+  $ intercom changelog 0.7.0           Show a specific version
+  $ intercom changelog --json          Machine-readable release history`
+  ).action(async function(version) {
+    const opts = this.optsWithGlobals();
+    let releases = loadChangelog();
+    if (version) {
+      const wanted = normalizeVersion(version);
+      const match = releases.find((r) => normalizeVersion(r.version) === wanted);
+      if (!match) {
+        const known = releases.map((r) => r.version).join(", ");
+        throw new CLIError(`No changelog entry for version "${version}". Known versions: ${known}`);
+      }
+      releases = [match];
+    } else if (opts.limit !== void 0) {
+      const limit = parseInt(String(opts.limit), 10);
+      if (isNaN(limit) || limit <= 0) {
+        throw new CLIError("--limit must be a positive integer");
+      }
+      releases = releases.slice(0, limit);
+    }
+    render(releases, opts, () => renderHuman(releases), releases);
+  });
+}
+
 // src/index.ts
 function detectBinaryName() {
   const argv1 = process.argv[1] ?? "";
@@ -4171,6 +4334,7 @@ Environment: Set INTERCOM_TOKEN to skip login entirely.`;
   registerPricingCommand(program);
   registerCompletionCommand(program);
   registerConfigCommand(program);
+  registerChangelogCommand(program);
   program.hook("preAction", (thisCommand, actionCommand) => {
     const rootOpts = thisCommand.opts();
     if (rootOpts.agent && rootOpts.human) {

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@intercom/cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "CLI tool for managing Intercom workspaces",
   "type": "module",
+  "packageManager": "pnpm@10.23.0",
   "bin": {
     "intercom": "dist/index.js",
     "fin": "dist/index.js"
@@ -20,7 +21,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "CHANGELOG.md"
   ],
   "license": "MIT",
   "dependencies": {
@@ -39,5 +41,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
+  },
+  "pnpm": {
+    "overrides": {},
+    "onlyBuiltDependencies": []
   }
 }