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 "intercom-client";
   
   let instance: IntercomClient | null = null;
   
   export function getClient(): IntercomClient {
     if (!instance) {
       const token = process.env.INTERCOM_ACCESS_TOKEN;
       if (!token) {
         throw new Error(
           "INTERCOM_ACCESS_TOKEN not set. Copy .env.example to .env.development"
         );
       }
       instance = new IntercomClient({ token });
     }
     return instance;
   }
   
   export function resetClient(): void {
     instance = null;
   }
   

4. Build a mock client factory (tests/mocks/intercom.ts) covering contacts, conversations, messages, admins, and tags with vi.fn() resolved values, so the unit lane never touches the network. Full factory in implementation.md.

5. Write mocked unit tests against the factory, asserting call arguments and returned shapes. See implementation.md.

6. Tunnel webhooks with ngrok — run the local server, ngrok http 3000, and register the HTTPS URL in Intercom Developer Hub. Use Bash(npx:*) for ngrok. See implementation.md.

7. Wire package scripts (dev, test, test:watch, test:integration, typecheck) — use Edit to add them to package.json, then drive the loop with Bash(npm:*). See implementation.md.

Output

Following this skill produces a working local Intercom development loop:

• A scaffolded src/intercom/ client module and tests/ tree with a reusable mock factory.
• Three environment files — a committed .env.example template plus git-ignored .env.development / .env.test.
• An offline mocked unit test lane (npm run test / test:watch) that runs with no token and no network.
• A token-gated integration lane (npm run test:integration) that is skipped automatically when INTERCOM_ACCESS_TOKEN is absent.
• An ngrok webhook tunnel exposing the local server to Intercom's Developer Hub.

Error Handling

Error	Cause	Solution
INTERCOM_ACCESS_TOKEN not set	Missing .env file	Copy .env.example to .env.development
Port 3000 in use	Another process	lsof -i :3000 and kill, or change port
ngrok tunnel expired	Free tier 2h limit	Restart ngrok or use paid plan
Mock type mismatch	SDK updated	Regenerate mocks from SDK types
rate_limit_exceeded in dev	Dev workspace limits	Add delays between integration tests

Examples

A minimal mocked unit test (from implementation.md):

it("should create a user contact", async () => {
  const contact = await mockClient.contacts.create({
    role: "user",
    externalId: "user-123",
    email: "test@example.com",
  });

  expect(contact.id).toBe("mock-contact-id");
  expect(mockClient.contacts.create).toHaveBeenCalledOnce();
});

For the token-gated integration test pattern (describe.skipIf, live create + cleanup) and the commands that drive each lane, see the examples reference.

Resources

• Full implementation walkthrough — every step's complete code
• Integration examples — live-workspace test pattern and run commands
• intercom-client npm
• Vitest Documentation
• ngrok
• See intercom-sdk-patterns for production-ready code patterns.