| name | intercom-upgrade-migration |
| description | Upgrade the intercom-client SDK across major versions and handle Intercom API
version changes safely. Use when a project is pinned to an old intercom-client
release, when the v5 CommonJS API must move to the v6 TypeScript rewrite, or
when detecting breaking changes in a new Intercom release before shipping.
Trigger with phrases like "upgrade intercom", "intercom migration",
"intercom breaking changes", "update intercom SDK", "intercom API version".
|
| allowed-tools | Read, Write, Edit, Bash(npm:*), Bash(git:*) |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| argument-hint | [current-version] [target-version] |
| tags | ["saas","support","messaging","intercom"] |
| compatibility | Designed for Claude Code |
Intercom Upgrade & Migration
Overview
Upgrade the intercom-client npm package and handle Intercom API version
changes without breaking production traffic. The v6 TypeScript rewrite changed
the API surface — most notably unifying users/leads into a single contacts
API — so this skill drives a branch-based, type-checked upgrade that surfaces
every breaking change through the compiler and test suite before merge.
Deep material lives in references/ so this file stays scannable:
- Full v5 → v6 migration guide — every changed
operation with before/after code, API-version pinning, the upgrade procedure,
type-import changes, and the method cheat sheet.
- Worked examples — three end-to-end runs from version
detection through a committed upgrade branch.
Prerequisites
- A project with
intercom-client already installed (npm list intercom-client
shows the current version).
- Git available for branch-based upgrades and reviewable diffs.
- A working test suite, ideally including an integration suite that can run
against a dev Intercom workspace.
- TypeScript (
tsc) configured if migrating to v6+, since the compiler is the
primary breaking-change detector.
Authentication
Intercom API calls authenticate with a workspace access token passed as a Bearer
token. Read it from the INTERCOM_ACCESS_TOKEN environment variable — never
hardcode it. Version-detection curls and the integration test step both consume
this variable:
export INTERCOM_ACCESS_TOKEN="<workspace-access-token>"
Use a separate dev-workspace token ($DEV_TOKEN) for the integration test step
so the upgrade is validated without touching production data.
Instructions
Follow the workflow at a high level here; drill into
the migration guide for the exact code diffs.
Step 1: Check current versions
Read (with the Read tool or npm list) the installed version, the latest
published version, and the live API version to size the upgrade:
npm list intercom-client
npm view intercom-client version
curl -s -D - -o /dev/null \
-H \
https://api.intercom.io/me 2>/dev/null | grep -i intercom-version
