intercom-local-dev-loop

name	intercom-local-dev-loop
description	Configure Intercom local development with testing, mocking, and hot reload. Use when setting up a development environment, writing tests against the Intercom API, or establishing a fast iteration cycle against a dev workspace. Trigger with phrases like "intercom dev setup", "intercom local development", "intercom dev environment", "develop with intercom", "test intercom locally".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(npx:*)
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","support","messaging","intercom"]
compatibility	Designed for Claude Code

Intercom Local Dev Loop

Overview

Set up a fast local development workflow for Intercom integrations with proper test isolation, mocking strategies, and webhook tunneling. The loop has two lanes: a mocked unit lane that runs offline with no token, and an integration lane that talks to a real dev workspace and is skipped automatically when no token is present.

Prerequisites

• Completed intercom-install-auth setup
• Node.js 18+ with npm/pnpm
• A test/development Intercom workspace (separate from production)

Authentication

The client authenticates with a single Intercom bearer access token, issued per workspace by the intercom-install-auth step. Read it from process.env.INTERCOM_ACCESS_TOKEN (loaded from git-ignored .env.development); never hardcode it. The mocked unit lane needs no token at all — pointing the loop at a different dev workspace is only a matter of swapping the .env.development value.

Instructions

Work through these steps to stand up the loop. The full, copy-paste-ready code for every step lives in the implementation walkthrough.

1. Scaffold the project structure — an src/intercom/ module (singleton client.ts, plus contacts.ts / conversations.ts / types.ts), a tests/ tree with a mocks/ factory, and three env files (.env.example committed, .env.development and .env.test git-ignored). Use Write to create each file. See implementation.md.

2. Configure environments — commit .env.example as the template and keep real tokens in the git-ignored .env.development. See implementation.md.

3. Write an environment-aware client singleton that reads the token, throws a clear error when it is missing, and exposes a resetClient() for tests. The skeleton:

   // src/intercom/client.ts
   import { IntercomClient } from ;
   
    :  |  = ;
   
     ():  {
      (!instance) {
        token = process..;
        (!token) {
           (
           
         );
       }
       instance =  ({ token });
     }
      instance;
   }
   
     ():  {
     instance = ;
   }