intercom-sdk-patterns

name	intercom-sdk-patterns
description	Apply production-ready intercom-client SDK patterns for TypeScript. Use when implementing Intercom integrations, refactoring SDK usage, or establishing team coding standards for Intercom API calls. Trigger with phrases like "intercom SDK patterns", "intercom best practices", "intercom code patterns", "idiomatic intercom", "intercom typescript".
allowed-tools	Read, Write, Edit
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","support","messaging","intercom"]
compatibility	Designed for Claude Code

Intercom SDK Patterns

Overview

Production-ready patterns for the intercom-client TypeScript SDK covering client initialization, cursor-based pagination, error handling, retry with backoff, compound search, and multi-tenant client factories. Use this skill to Read existing Intercom code, then Write or Edit it to match these patterns — type-safe singletons, memory-efficient pagination, and resilient error handling.

The SKILL.md body carries the essential skeletons (client wrapper, pagination, error-handling shape). Deep implementations and worked examples live in references/ so you can drill in only when you need them:

• Full implementation patterns — error handling, retry/backoff, multi-tenant factory, search-operator table.
• Worked examples — pagination, compound search, combined retry + safe-call.

Prerequisites

• intercom-client package installed (npm install intercom-client).
• TypeScript 5.0+ project with strict mode enabled.
• Familiarity with async/await and async generators.
• An Intercom access token available at runtime (see Authentication below).

Authentication

The SDK authenticates with a workspace access token passed to the IntercomClient constructor. Store it in the INTERCOM_ACCESS_TOKEN environment variable — never hardcode it. Generate the token from Intercom's Developer Hub (Settings → Authentication). For multi-workspace apps, each workspace has its own token; see the multi-tenant factory in references/implementation.md.

Instructions

Step 1: Type-Safe Client Wrapper

Create one lazily-initialized singleton client plus thin, typed helpers. This keeps a single connection pool and gives every call-site full SDK types.

// src/intercom/client.ts
import { IntercomClient } from "intercom-client";
import { Intercom } from "intercom-client";

let instance:  |  = ;

  ():  {
   (!instance) {
    instance =  ({
      : process..!,
    });
  }
   instance;
}


   (): <.> {
   ()..(params);
}