@keystrokehq/intercom

Official Keystroke integration for Intercom — contacts, companies, conversations, tickets, help-center content, and lifecycle webhooks.

Credential sets live under ./credential-sets. Operations live under ./operations. Shared Zod schemas live under ./schemas. The residual provider-app seed descriptor remains at src/provider-apps/ until the provider-app primitive refactor deletes it.

Installation

pnpm add @keystrokehq/intercom

Credentials

Intercom is an OAuth-backed integration. Customers connect through the Keystroke app; private-app access tokens work for development.

Public connection (intercomCredentialSet):

• INTERCOM_ACCESS_TOKEN — OAuth or private-app bearer token
• INTERCOM_API_REGION (optional) — 'us' (default), 'eu', or 'au'

Platform provider-app credential set (intercomAppCredentialSet, exposure: 'platform-only'):

• clientId, clientSecret — Intercom app id + secret (secret is also the webhook HMAC-SHA1 key)
• webhookClientSecret (optional) — rotate the webhook key independently if needed
• appId (optional) — Intercom workspace / app id for log disambiguation

Quickstart

import { getContactOperation } from '@keystrokehq/intercom/operations';

await getContactOperation.run(
  { contactId: 'abc123' },
  { credentials: { intercom: { INTERCOM_ACCESS_TOKEN: '…', INTERCOM_API_REGION: 'eu' } } }
);

Every REST call sends the pinned Intercom-Version: 2.15 header from src/utils/client.ts. Region-aware base URLs resolve from INTERCOM_API_REGION (us → api.intercom.io, eu → api.eu.intercom.io, au → api.au.intercom.io).

Webhook verification helpers live in src/utils/verification.ts (verifyIntercomWebhookRequest, HMAC-SHA1 over raw body via X-Hub-Signature).

See PLAN.md for the full specification and IMPLEMENTATION_NOTES.md for build history.