From intercom-pack
Upgrades intercom-client npm SDK from v5 to v6+, migrates contacts/conversations API calls, handles TypeScript changes, error handling, and pagination.
How this skill is triggered — by the user, by Claude, or both
Slash command
/intercom-pack:intercom-upgrade-migrationThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide for upgrading the `intercom-client` npm package and handling Intercom API version changes. The SDK was rewritten in TypeScript starting at v6, which introduced significant breaking changes from the v5 CommonJS API.
Guide for upgrading the intercom-client npm package and handling Intercom API version changes. The SDK was rewritten in TypeScript starting at v6, which introduced significant breaking changes from the v5 CommonJS API.
intercom-client installed# Current SDK version
npm list intercom-client
# Latest available
npm view intercom-client version
# Current API version (check response headers)
curl -s -D - -o /dev/null \
-H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
https://api.intercom.io/me 2>/dev/null | grep -i intercom-version
The v6 SDK is a full TypeScript rewrite with a new API surface.
Client Initialization:
// v5 (CommonJS)
const Intercom = require("intercom-client");
const client = new Intercom.Client({ token: "xxx" });
// v6+ (TypeScript ESM)
import { IntercomClient } from "intercom-client";
const client = new IntercomClient({ token: "xxx" });
Contact Operations:
// v5
await client.users.create({ email: "test@example.com" });
await client.leads.create({ email: "lead@example.com" });
await client.users.find({ id: "abc" });
await client.users.list();
// v6+ (unified contacts API)
await client.contacts.create({ role: "user", email: "test@example.com" });
await client.contacts.create({ role: "lead", email: "lead@example.com" });
await client.contacts.find({ contactId: "abc" });
await client.contacts.list();
Conversation Operations:
// v5
await client.conversations.reply({ id: "123", body: "Hello", type: "admin", admin_id: "456" });
// v6+
await client.conversations.reply({
conversationId: "123",
body: "Hello",
type: "admin",
adminId: "456",
});
Error Handling:
// v5
try { ... } catch (e) { console.log(e.statusCode, e.body); }
// v6+
import { IntercomError } from "intercom-client";
try { ... } catch (e) {
if (e instanceof IntercomError) {
console.log(e.statusCode, e.message, e.body);
}
}
Pagination:
// v5 - callback style
client.users.scroll.each({}, (users) => { /* ... */ });
// v6+ - async iteration
const response = await client.contacts.list();
for await (const contact of response) {
// Auto-paginates
}
// Or manual cursor-based pagination
let startingAfter: string | undefined;
do {
const page = await client.contacts.list({ perPage: 50, startingAfter });
// process page.data
startingAfter = page.pages?.next?.startingAfter ?? undefined;
} while (startingAfter);
Intercom API versions control response shapes. The SDK defaults to a compatible version, but you can pin explicitly.
// Current stable version: 2.11
// SDK handles version headers automatically
// To use specific version via raw requests:
const response = await fetch("https://api.intercom.io/contacts", {
headers: {
Authorization: `Bearer ${token}`,
"Intercom-Version": "2.11",
"Content-Type": "application/json",
},
});
# 1. Create upgrade branch
git checkout -b upgrade/intercom-client-v6
# 2. Install new version
npm install intercom-client@latest
# 3. Run type checks (will surface breaking changes)
npx tsc --noEmit 2>&1 | grep "intercom"
# 4. Run tests
npm test
# 5. Fix breaking changes identified by TypeScript and tests
# 6. Test against dev workspace
INTERCOM_ACCESS_TOKEN=$DEV_TOKEN npm run test:integration
# 7. Commit and PR
git add -A && git commit -m "chore: upgrade intercom-client to v6"
// v6+ exports types under Intercom namespace
import { Intercom } from "intercom-client";
// Use typed request/response interfaces
const request: Intercom.CreateContactRequest = {
role: "user",
email: "test@example.com",
};
const contact: Intercom.Contact = await client.contacts.create(request);
| v5 Method | v6 Method |
|---|---|
client.users.create() | client.contacts.create({ role: "user" }) |
client.leads.create() | client.contacts.create({ role: "lead" }) |
client.users.find({ id }) | client.contacts.find({ contactId }) |
client.users.update({ id }) | client.contacts.update({ contactId }) |
client.users.list() | client.contacts.list() |
client.conversations.reply({ id }) | client.conversations.reply({ conversationId }) |
client.events.create() | client.dataEvents.create() |
client.tags.tag() | client.contacts.tag() |
new Intercom.Client({ token }) | new IntercomClient({ token }) |
e.statusCode | e instanceof IntercomError ? e.statusCode : ... |
| Issue | Detection | Solution |
|---|---|---|
Cannot find module 'intercom-client' | Import fails | npm install intercom-client |
Property 'users' does not exist | TypeScript error | Migrate users/leads to contacts |
Property 'id' does not exist | Changed param names | Use contactId, conversationId |
| Response shape changed | Runtime errors | Check API version headers |
For CI integration during upgrades, see intercom-ci-integration.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin intercom-packApplies intercom-client TypeScript SDK patterns: type-safe wrappers, cursor pagination generators, error handling. For Intercom integrations, refactoring, or standards.
Upgrades @hubspot/api-client SDK and migrates HubSpot Node.js APIs from v1/v2 to v3, fixing breaking changes in auth, associations, batch APIs, and TypeScript types.
Upgrades klaviyo-api SDK versions and migrates from v1/v2 legacy APIs to current REST API, handling breaking changes between revisions.