# @kody/intercom — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets and
OAuth by **name** only — never paste tokens. Do not disable live webhooks or
jobs. The optional `workspace-health` job is **disabled** by default.

## Auth

| Call | Resolves to |
| --- | --- |
| omit | `intercom` / `intercomAccessToken` |
| `account: 'work'` | `intercom-work` / `intercomAccessToken-work` |
| `integrationName: 'intercom-work'` | that exact OAuth name |
| `secretName: 'intercomAccessToken-work'` | that exact access-token secret |
| `auth: 'oauth' \| 'accessToken'` | force lane when both exist |
| `region: 'us' \| 'eu' \| 'au'` | regional API origin (default `us`) |
| `apiBaseUrl` | absolute regional API origin when not using `region` |

Hosts: `api.intercom.io`, `api.eu.intercom.io`, `api.au.intercom.io`.
REST bases: US `https://api.intercom.io`, EU `https://api.eu.intercom.io`,
AU `https://api.au.intercom.io`. Header: `Intercom-Version: 2.14`.

Do not hard-code a personal workspace id, admin id, or alias.

## Import paths

| Export | Import |
| --- | --- |
| root dispatcher (defaults to smoke-test) | `kody:@kody/intercom` |
| accounts | `kody:@kody/intercom/accounts` |
| me | `kody:@kody/intercom/me` |
| smoke-test | `kody:@kody/intercom/smoke-test` |
| contacts | `kody:@kody/intercom/contacts` |
| list-contacts | `kody:@kody/intercom/list-contacts` |
| get-contact | `kody:@kody/intercom/get-contact` |
| search-contacts | `kody:@kody/intercom/search-contacts` |
| create-contact | `kody:@kody/intercom/create-contact` |
| update-contact | `kody:@kody/intercom/update-contact` |
| conversations | `kody:@kody/intercom/conversations` |
| list-conversations | `kody:@kody/intercom/list-conversations` |
| get-conversation | `kody:@kody/intercom/get-conversation` |
| search-conversations | `kody:@kody/intercom/search-conversations` |
| reply-conversation | `kody:@kody/intercom/reply-conversation` |
| close-conversation | `kody:@kody/intercom/close-conversation` |
| articles | `kody:@kody/intercom/articles` |
| list-articles | `kody:@kody/intercom/list-articles` |
| get-article | `kody:@kody/intercom/get-article` |
| create-article | `kody:@kody/intercom/create-article` |
| update-article | `kody:@kody/intercom/update-article` |
| request | `kody:@kody/intercom/request` |
| scheduled-workspace-health | `kody:@kody/intercom/scheduled-workspace-health` |
| types | `kody:@kody/intercom/types` |

Prefer static `kody:@kody/intercom/...` imports from `execute`. Do not lead with
`packages.invoke`.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/intercom/smoke-test'

export default async function main() {
	return await smokeTest()
	// Without credentials: { ok: true, live: false } + connect / access-token URLs
	// With credentials: { live: true, hasAdminId } (no email)
}
```

Root dispatcher equivalent: `import intercom from 'kody:@kody/intercom'` then
`await intercom({ action: 'smoke-test' })`.

Do not write live Intercom records from a smoke test.

## dryRun / confirm

Mutating helpers require `confirm: true`. Pass `dryRun: true` to inspect the
REST payload without calling Intercom. `./request` treats GET and search POST
as read-only; other POST / PUT / PATCH / DELETE need confirmation.

```js
import createContact from 'kody:@kody/intercom/create-contact'
import replyConversation from 'kody:@kody/intercom/reply-conversation'

export default async function main() {
	const previewContact = await createContact({
		email: 'pat@example.com',
		name: 'Pat',
		dryRun: true,
	})
	const previewReply = await replyConversation({
		id: conversationIdFromCaller,
		body: 'Thanks — looking into this.',
		dryRun: true,
	})
	return { previewContact, previewReply }
}
```

Read helpers:

```js
import listContacts from 'kody:@kody/intercom/list-contacts'
import listConversations from 'kody:@kody/intercom/list-conversations'
import listArticles from 'kody:@kody/intercom/list-articles'

export default async function main() {
	const contacts = await listContacts({ perPage: 10 })
	const conversations = await listConversations({ perPage: 10 })
	const articles = await listArticles({ perPage: 10 })
	return {
		contactCount: contacts.items.length,
		conversationCount: conversations.items.length,
		articleCount: articles.items.length,
	}
}
```

Unwrapped REST:

```js
import request from 'kody:@kody/intercom/request'

export default async function main() {
	return await request({
		path: '/contacts',
		query: { per_page: 5 },
	})
}
```

## Edge cases

- Search uses Intercom's query object, or `email` / `state` shortcuts.
- Reply and close resolve `adminId` from `GET /me` when omitted. Create
  article does the same for `authorId`.
- Helpers project slim records (`id`, role/state/title, timestamps). Use
  `./request` when you need full conversation parts or article HTML.
- Prefer dedicated helpers over assembling `./request` when one exists.
- `./scheduled-workspace-health` only reads `/me` plus first-page counts; the
  `workspace-health` job stays disabled unless the owner enables it.