intercom-client

intercom-client is the official Node.js and TypeScript SDK for the Intercom customer messaging and support platform’s REST API. Generated with Fern directly from Intercom’s API definition, it exposes every resource — contacts, companies, conversations, tickets, articles, help centers, data attributes, and more — as a typed, promise-based client with request and response interfaces exported for every operation.

The library ships as a modern dual CJS/ESM package with runtime support for Node.js 18+, Vercel, Cloudflare Workers, Deno, Bun, and React Native. It bundles automatic retries with exponential backoff and jitter, configurable timeouts, abortable requests, iterator-based pagination, pluggable authentication, and structured logging, so teams building on top of Intercom (chat, help desk, ticketing, or workflow automation) get a consistent, low-boilerplate client instead of hand-rolling HTTP calls against the raw API.

What You Get

• A single IntercomClient with lazily-instantiated, resource-scoped sub-clients (client.contacts, client.conversations, client.tickets, etc.) for every Intercom API area
• Fully typed request and response interfaces for every endpoint, exported under the Intercom namespace
• Typed error subclasses (e.g. UnauthorizedError, NotFoundError) thrown per documented failure mode, plus a base IntercomError and IntercomTimeoutError
• Automatic pagination via an AsyncIterable Page wrapper so list endpoints can be looped over directly or paged manually
• Built-in retry-with-backoff, configurable timeouts, abort-signal support, and a swappable fetch implementation for restricted runtimes
• Support for both region-specific environments (US, EU, AU) and a custom baseUrl override, plus a withRawResponse() accessor for raw headers/status

Common Use Cases

• Syncing contacts, companies, and their custom attributes between Intercom and an internal CRM or data warehouse
• Building conversational or helpdesk automations that read and reply to conversations, tickets, and notes
• Publishing and maintaining Help Center articles and collections programmatically from a CMS or docs pipeline
• Sending targeted in-app or push messages and tracking custom data events from a product backend
• Exporting Intercom data (companies, conversations, data attributes) in bulk for analytics or compliance workflows

Under The Hood

Architecture The SDK centers on IntercomClient (src/Client.ts), which lazily instantiates one dedicated client per API resource (AdminsClient, ContactsClient, ConversationsClient, and 30+ others under src/api/resources/) via ??= getters, so only the resources a consumer touches get constructed. Every resource client shares normalized options from BaseClient.ts (auth provider, headers, timeout, retries, custom fetch) and delegates actual HTTP work to core/fetcher, which wraps fetch with retry/backoff (requestWithRetries.ts), URL construction, and typed response parsing. Pagination is abstracted into a single reusable Page<T, R> class (core/pagination/Page.ts) implementing AsyncIterable, and authentication is pluggable through an AuthProvider interface with BearerToken/BasicAuth implementations — a change to the core request or pagination contract would ripple through every one of the 36 resource clients, since they all import from the same core/ and BaseClient.ts modules rather than duplicating request logic.

Tech Stack Written in TypeScript and built with tsc into parallel CJS and ESM output (tsconfig.cjs.json / tsconfig.esm.json), targeting Node.js 18+ as well as Cloudflare Workers, Deno, Bun, and React Native via a pluggable fetch layer. Ships with zero runtime dependencies; tooling is Biome for linting and formatting, Vitest for tests (with a unit/wire project split), and MSW for mock HTTP servers in wire tests. Package management is pnpm with a workspace config, and the whole client is generated from Intercom’s API definition using the Fern code-generation toolchain, with a large reference.md serving as the exhaustive per-method API reference.

Code Quality Test coverage spans three tiers: tests/unit for core utilities (auth, fetcher, URL encoding, base64, logging), tests/wire for per-resource request/response contract tests against a mock server pool, and tests/integration for end-to-end calls against live-shaped fixtures across nearly every resource. Errors are modeled as typed classes rather than swallowed, methods carry JSDoc with @param/@throws/@example blocks, and Biome enforces consistent formatting and lint rules across the generated codebase. Being Fern-generated, hand-authored contributions are discouraged in favor of regenerating from the API definition, which trades some organic code-review history for strict internal consistency across all 36 resources.

API Design The public surface favors discoverability and safety over minimalism: resource-scoped clients (client.contacts.list(...)) read naturally, every parameter and return type is fully typed, and list endpoints return an async-iterable Page so callers can for await results without manually tracking cursors. Advanced needs are covered without adding boilerplate to the common path — request-level header/query overrides, retry limits, timeouts, abort signals, and a .withRawResponse() escape hatch for raw headers are all opt-in. The version pin (version option, e.g. 2.14) and region-specific IntercomEnvironment constants make it straightforward to target a specific Intercom API version and data region explicitly.