@intercom/cli 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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
+
+- `intercom auth signup` no longer reads its CSRF token from the old signup page, which is moving to the new signup site. It now gets the token from the signup state endpoint, so signup keeps working after the old page redirects.
+
 ## [0.14.0] - 2026-09-02
 
 ### Added

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";
 
@@ -933,6 +944,19 @@ async function fetchCsrfToken(url, timeoutMs = API_TIMEOUT_MS, init) {
   if (!match) throw new Error("Could not find CSRF token");
   return { token: match[1], cookies: extractCookies(response) };
 }
+async function fetchSignupCsrfToken(baseUrl, timeoutMs) {
+  const url = `${baseUrl}/ember/signups/state`;
+  const response = await fetchWithTimeout(
+    url,
+    { headers: { Accept: "application/json" } },
+    { timeoutMs }
+  );
+  if (!response.ok)
+    throw new AuthError(`Failed to fetch ${url}: ${response.status}`);
+  const data = await response.json();
+  if (!data.csrf_token) throw new AuthError("Could not find CSRF token");
+  return { token: data.csrf_token, cookies: extractCookies(response) };
+}
 async function signup(options) {
   const {
     baseUrl,
@@ -943,9 +967,8 @@ async function signup(options) {
     plan = "advanced",
     timeoutMs = API_TIMEOUT_MS
   } = options;
-  const csrfUrl = `${baseUrl}/admins/sign_up/email`;
-  const { token: csrfToken, cookies } = await fetchCsrfToken(
-    csrfUrl,
+  const { token: csrfToken, cookies } = await fetchSignupCsrfToken(
+    baseUrl,
     timeoutMs
   );
   const solutionId = PLAN_SOLUTION_IDS[plan] ?? PLAN_SOLUTION_IDS["advanced"];
@@ -1592,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",
@@ -1633,6 +1663,7 @@ Examples:
       }
       result = raw;
     }
+    result.data = result.data?.map((a) => withWebUrl(a, client.appBaseUrl));
     const items = result.data ?? [];
     render(
       result,
@@ -1676,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(
@@ -1697,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)
@@ -1743,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
       })
     );
   });
@@ -1775,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
       })
     );
   });
@@ -2954,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 || ".";
@@ -3520,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");
@@ -3549,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>\`
@@ -3570,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
@@ -3595,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,
@@ -3603,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()) {
@@ -3731,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;
   }
@@ -5181,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] ?? "";
@@ -5262,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.0",
+  "version": "0.15.0",
   "description": "CLI tool for managing Intercom workspaces",
   "type": "module",
   "packageManager": "pnpm@10.23.0",