@intercom/cli 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 View it from the CLI with `intercom changelog`.
 
+## [0.15.0] - 2026-11-06
+
+### Added
+
+- `intercom fin workflows list`, `get` and `upload` now return a `web_url` that opens the workflow in the visual builder. The builder URL uses a different id from the workflow's `id`, so use this field instead of building the URL yourself.
+- `intercom articles list`, `search`, `get`, `create` and `update` add a `web_url` that opens each article in the Intercom editor, in the workspace's own region.
+- `intercom fin workflows upload --note <text>` labels the saved version, as `fin procedures upload --note` already does. The note shows in `intercom fin workflows versions <id>`.
+
+### Fixed
+
+- `intercom fin workflows upload --verify` no longer reports drift on `web_url` or `workflow_instance_id`. The server assigns those itself, so a file copied from another workflow no longer fails verification.
+- `intercom fin workflows get <id> --version <version_id>` and `intercom fin procedures get <id> --version <version_id>` now download that version. Before, a space between `--version` and the id printed the CLI's own version instead; only `--version=<version_id>` worked.
+- `intercom fin workflows upload --verify` no longer reports drift when an uploaded audio file, such as a phone greeting or hold music, comes back with a fresh download signature. The link still points at the same file.
+
 ## [0.14.1] - 2026-10-27
 
 ### Fixed

package/dist/index.js

@@ -59,6 +59,51 @@ async function fetchWithTimeout(url, init, options) {
   return response;
 }
 
+// src/api/regions.ts
+var REGION_BASE_URLS = {
+  us: "https://api.intercom.io",
+  eu: "https://api.eu.intercom.io",
+  au: "https://api.au.intercom.io"
+};
+var APP_BASE_URLS = {
+  [REGION_BASE_URLS.us]: "https://app.intercom.com",
+  [REGION_BASE_URLS.eu]: "https://app.eu.intercom.com",
+  [REGION_BASE_URLS.au]: "https://app.au.intercom.com"
+};
+function appBaseUrlFor(apiBaseUrl) {
+  return process.env.INTERCOM_APP_BASE_URL || APP_BASE_URLS[apiBaseUrl.replace(/\/+$/, "")];
+}
+function regionBaseUrl(region) {
+  if (!region) return void 0;
+  return REGION_BASE_URLS[region];
+}
+function normalizeRegion(value) {
+  if (typeof value !== "string") return void 0;
+  switch (value.trim().toLowerCase()) {
+    case "us":
+    case "usa":
+    case "united states":
+      return "us";
+    case "eu":
+    case "europe":
+      return "eu";
+    case "au":
+    case "australia":
+      return "au";
+    default:
+      return void 0;
+  }
+}
+function detectRegion(me) {
+  if (!me || typeof me !== "object") return void 0;
+  const m = me;
+  const app = m.app;
+  return normalizeRegion(app?.region ?? m.region);
+}
+function resolveBaseUrl(region) {
+  return process.env.INTERCOM_API_BASE_URL || regionBaseUrl(region) || void 0;
+}
+
 // src/api/client.ts
 var DEFAULT_BASE_URL = "https://api.intercom.io";
 var MAX_RAW_ERROR_LEN = 500;
@@ -104,6 +149,9 @@ var IntercomClient = class _IntercomClient {
     this.verbose = options.verbose ?? false;
     this.timeoutMs = options.timeoutMs ?? API_TIMEOUT_MS;
   }
+  get appBaseUrl() {
+    return appBaseUrlFor(this.baseUrl);
+  }
   authHeader() {
     if (this.authType === "api_key") {
       return `Basic ${Buffer.from(`${this.appId}:${this.token}`).toString("base64")}`;
@@ -363,43 +411,6 @@ ${await value.text()}`);
   }
 };
 
-// src/api/regions.ts
-var REGION_BASE_URLS = {
-  us: "https://api.intercom.io",
-  eu: "https://api.eu.intercom.io",
-  au: "https://api.au.intercom.io"
-};
-function regionBaseUrl(region) {
-  if (!region) return void 0;
-  return REGION_BASE_URLS[region];
-}
-function normalizeRegion(value) {
-  if (typeof value !== "string") return void 0;
-  switch (value.trim().toLowerCase()) {
-    case "us":
-    case "usa":
-    case "united states":
-      return "us";
-    case "eu":
-    case "europe":
-      return "eu";
-    case "au":
-    case "australia":
-      return "au";
-    default:
-      return void 0;
-  }
-}
-function detectRegion(me) {
-  if (!me || typeof me !== "object") return void 0;
-  const m = me;
-  const app = m.app;
-  return normalizeRegion(app?.region ?? m.region);
-}
-function resolveBaseUrl(region) {
-  return process.env.INTERCOM_API_BASE_URL || regionBaseUrl(region) || void 0;
-}
-
 // src/auth/store.ts
 import { readFileSync, mkdirSync } from "fs";
 
@@ -1604,6 +1615,13 @@ function htmlToText(html) {
 function stripBody(items) {
   return items.map(({ body: _body, ...rest }) => rest);
 }
+function withWebUrl(article, appBaseUrl) {
+  if (!appBaseUrl || article.id == null || article.workspace_id == null) return article;
+  return {
+    ...article,
+    web_url: `${appBaseUrl}/a/apps/${String(article.workspace_id)}/knowledge-hub/article/${String(article.id)}`
+  };
+}
 function registerArticlesCommand(program) {
   const articles = program.command("articles").description("Manage help center articles (list, get, create, update, delete, search)").addHelpText(
     "after",
@@ -1645,6 +1663,7 @@ Examples:
       }
       result = raw;
     }
+    result.data = result.data?.map((a) => withWebUrl(a, client.appBaseUrl));
     const items = result.data ?? [];
     render(
       result,
@@ -1688,6 +1707,11 @@ Examples:
         data.articles = stripBody(data.articles);
       }
     }
+    if (Array.isArray(result.data)) {
+      result.data = result.data.map((a) => withWebUrl(a, client.appBaseUrl));
+    } else if (result.data && Array.isArray(result.data.articles)) {
+      result.data.articles = result.data.articles.map((a) => withWebUrl(a, client.appBaseUrl));
+    }
     const dataAfter = result.data;
     const items = Array.isArray(dataAfter) ? dataAfter : dataAfter?.articles ?? [];
     render(
@@ -1709,12 +1733,13 @@ Examples:
   articles.command("get <id>").description("Get a help center article 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(`/articles/${id}`);
+    const result = withWebUrl(await client.get(`/articles/${id}`), client.appBaseUrl);
     render(result, opts, () => {
       const meta = detail({
         ID: String(result.id ?? ""),
         Title: String(result.title ?? ""),
         State: String(result.state ?? ""),
+        "Web URL": result.web_url != null ? String(result.web_url) : void 0,
         "Author ID": result.author_id != null ? String(result.author_id) : void 0,
         Updated: formatTimestamp(result.updated_at),
         Created: formatTimestamp(result.created_at)
@@ -1755,14 +1780,15 @@ Use -F for typed values (numbers, booleans) and @file reads.`
       const parsed = parseInt(body.author_id, 10);
       if (!isNaN(parsed)) body.author_id = parsed;
     }
-    const result = await client.post("/articles", body);
+    const result = withWebUrl(await client.post("/articles", body), client.appBaseUrl);
     render(
       result,
       opts,
       () => detail({
         ID: String(result.id ?? ""),
         Title: String(result.title ?? ""),
-        State: String(result.state ?? "")
+        State: String(result.state ?? ""),
+        "Web URL": result.web_url != null ? String(result.web_url) : void 0
       })
     );
   });
@@ -1787,14 +1813,15 @@ Use -F for typed values (numbers, booleans) and @file reads.`
       const parsed = parseInt(body.author_id, 10);
       if (!isNaN(parsed)) body.author_id = parsed;
     }
-    const result = await client.put(`/articles/${id}`, body);
+    const result = withWebUrl(await client.put(`/articles/${id}`, body), client.appBaseUrl);
     render(
       result,
       opts,
       () => detail({
         ID: String(result.id ?? ""),
         Title: String(result.title ?? ""),
-        State: String(result.state ?? "")
+        State: String(result.state ?? ""),
+        "Web URL": result.web_url != null ? String(result.web_url) : void 0
       })
     );
   });
@@ -2966,7 +2993,36 @@ function scalarsMatch(sent, saved) {
   if (typeof saved === "object") {
     return false;
   }
-  return String(sent) === String(saved);
+  if (String(sent) === String(saved)) {
+    return true;
+  }
+  const unsignedSent = withoutSignature(String(sent));
+  return unsignedSent !== null && unsignedSent === withoutSignature(String(saved));
+}
+var SIGNATURE_PARAMS = ["expires", "signature", "req"];
+var UPLOAD_HOSTS = [
+  /^downloads\.intercomcdn\.eu$/,
+  /^downloads(\.[a-z]+)?\.intercomcdn\.com$/,
+  /\.intercom-attachments(-[0-9]+)?\.(com|eu)$/,
+  /^video-messages\.intercomcdn\.com$/,
+  /\.intercom-mail\.(com|eu)$/
+];
+function withoutSignature(value) {
+  if (!/^https?:\/\//i.test(value)) {
+    return null;
+  }
+  try {
+    const url = new URL(value);
+    if (!UPLOAD_HOSTS.some((host) => host.test(url.hostname))) {
+      return null;
+    }
+    for (const param of SIGNATURE_PARAMS) {
+      url.searchParams.delete(param);
+    }
+    return url.toString();
+  } catch {
+    return null;
+  }
 }
 function findDrift(sent, saved, path = "") {
   const here = path || ".";
@@ -3532,7 +3588,16 @@ function ensureWorkflowType(raw) {
 }
 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() {
+  workflows.command("list").description("List Fin SDK workflows").option("--json", "Output as JSON").option("--verbose", "Show HTTP request/response details").addHelpText(
+    "after",
+    `
+Examples:
+  $ intercom fin workflows list
+  $ intercom fin workflows list --jq '.web_url'
+
+Each workflow's web_url opens it in the visual builder. Use it rather than
+building a URL from id: the builder uses a different id.`
+  ).action(async function() {
     const opts = this.optsWithGlobals();
     const client = await resolveClient(opts);
     const result = await client.get("/fin-sdk/workflows");
@@ -3561,7 +3626,8 @@ Examples:
   $ intercom fin workflows get 42 --version 4821    # print that version's YAML
 
 The YAML it prints is ready to edit and re-upload with
-\`intercom fin workflows upload\`.
+\`intercom fin workflows upload\`. Its web_url field links to the workflow in
+the visual builder, whose URL uses a different id from this one.
 
 --version downloads the re-uploadable YAML of a historical version, so you can
 diff a local file against what is live (\`intercom fin workflows versions <id>\`
@@ -3582,19 +3648,22 @@ shows which version that is).`
       console.log(text.replace(/\n+$/, ""));
     }
   });
-  workflows.command("upload <file>").description('Upload a workflow YAML file (creates if id is "new", updates if numeric)').option("--verify", "Fail if the saved workflow differs from the file uploaded").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
+  workflows.command("upload <file>").description('Upload a workflow YAML file (creates if id is "new", updates if numeric)').option("--note <text>", "Version note to record against this save").option("--verify", "Fail if the saved workflow differs from the file uploaded").option("--json", "Output as JSON").option("--jq <expr>", "Filter JSON output with jq expression").option("--verbose", "Show HTTP request/response details").addHelpText(
     "after",
     `
 Examples:
   $ intercom fin workflows upload ./welcome.yaml
   $ intercom fin workflows get wf-42 > local.yaml; vim local.yaml; intercom fin workflows upload local.yaml
-  $ intercom fin workflows upload ./new.yaml --json | jq .visual_builder_url
+  $ intercom fin workflows upload ./new.yaml --json | jq .web_url
   $ intercom fin workflows upload ./welcome.yaml --verify
+  $ intercom fin workflows upload ./welcome.yaml --note "added VIP routing"
 
 The YAML file's id field determines whether this creates or updates:
   id: "new"   \u2192 creates a new workflow
   id: <int>   \u2192 updates the existing workflow with that id
 
+--note labels this save in \`intercom fin workflows versions <id>\`.
+
 --verify compares the workflow the server saved against the file just uploaded
 and exits non-zero listing any field that did not survive the round-trip. Fields
 the server adds (ids, defaults) are ignored; only content that was sent and came
@@ -3607,6 +3676,9 @@ back missing or changed is reported.`
     const formData = new FormData();
     const blob = new Blob([yamlBody], { type: "application/x-yaml" });
     formData.append("file_data", blob, basename3(filePath));
+    if (opts.note) {
+      formData.append("version_note", opts.note);
+    }
     const result = await client.postFormData("/fin-sdk/upload", formData);
     render(
       result,
@@ -3615,7 +3687,7 @@ back missing or changed is reported.`
         "ID": String(result.id ?? ""),
         "Type": result.type != null ? String(result.type) : void 0,
         "Message": result.message != null ? String(result.message) : void 0,
-        "Visual Builder URL": result.visual_builder_url != null ? String(result.visual_builder_url) : void 0
+        "Web URL": result.web_url != null || result.visual_builder_url != null ? String(result.web_url ?? result.visual_builder_url) : void 0
       })
     );
     if (opts.verify && !isDryRun()) {
@@ -3743,6 +3815,8 @@ function withoutExpectedChanges(sent) {
   const rest = { ...sent };
   delete rest.type;
   delete rest.version;
+  delete rest.web_url;
+  delete rest.workflow_instance_id;
   if (String(rest.id ?? "").toLowerCase() === "new") {
     delete rest.id;
   }
@@ -5193,6 +5267,18 @@ Examples:
   });
 }
 
+// src/argv.ts
+function attachVersionValues(argv) {
+  const out = [...argv];
+  for (let i = 3; i < out.length - 1; i++) {
+    if (out[i] === "--") break;
+    if (out[i] === "--version" && !out[i + 1].startsWith("-")) {
+      out.splice(i, 2, `--version=${out[i + 1]}`);
+    }
+  }
+  return out;
+}
+
 // src/index.ts
 function detectBinaryName() {
   const argv1 = process.argv[1] ?? "";
@@ -5274,7 +5360,7 @@ var isMainModule = process.argv[1]?.endsWith("index.js") || process.argv[1]?.end
 if (isMainModule) {
   const program = createProgram();
   try {
-    await program.parseAsync();
+    await program.parseAsync(attachVersionValues(process.argv));
   } catch (err) {
     handleError(err);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intercom/cli",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "CLI tool for managing Intercom workspaces",
   "type": "module",
   "packageManager": "pnpm@10.23.0",