npm package: @helpnest/intercom
Description: Migrate Intercom Articles to HelpNest
Latest version: 0.1.1

# @helpnest/intercom

Migrate your Intercom Articles to HelpNest in one command.

---

## What it does

`@helpnest/intercom` connects to the Intercom Help Center API, pulls your
collections and articles, converts the HTML body of each article to
Markdown, then creates them in your HelpNest instance via the REST API.

Migration order:

1. All **collections** are fetched and created in HelpNest first (parent
   collections before children where possible).
2. Each **article** is transformed and created inside its mapped collection.

---

## Prerequisites

| Requirement | Where to get it |
|---|---|
| **Intercom Access Token** | Intercom → Settings → Developers → Access Token |
| **HelpNest API Key** | HelpNest Dashboard → Settings → API Keys |
| **Node 18+** | [nodejs.org](https://nodejs.org) |

---

## Install

**Global install (recommended for repeated use):**

```bash
npm install -g @helpnest/intercom
helpnest-intercom migrate --help
```

**One-off via npx (no install required):**

```bash
npx @helpnest/intercom migrate --help
```

---

## Usage

```
helpnest-intercom migrate [options]
```

### Options

| Flag | Environment variable | Default | Description |
|---|---|---|---|
| `--intercom-token <token>` | `INTERCOM_ACCESS_TOKEN` | — | Intercom Access Token (required) |
| `--helpnest-url <url>` | `HELPNEST_URL` | `http://localhost:3000` | HelpNest base URL |
| `--helpnest-key <key>` | `HELPNEST_API_KEY` | — | HelpNest API key (required unless `--dry-run`) |
| `--dry-run` | — | false | Print what would be migrated; no API writes |
| `--collections-only` | — | false | Migrate collections only, skip articles |
| `--state <state>` | — | `published` | Which Intercom article state to migrate: `published`, `draft`, or `all` |

All options can be supplied via environment variables instead of flags.

---

## Examples

### Dry run first (always recommended)

```bash
INTERCOM_ACCESS_TOKEN=your_token \
HELPNEST_URL=https://help.yourcompany.com \
HELPNEST_API_KEY=hn_your_api_key \
  npx @helpnest/intercom migrate --dry-run
```

### Full migration (published articles only)

```bash
INTERCOM_ACCESS_TOKEN=your_token \
HELPNEST_URL=https://help.yourcompany.com \
HELPNEST_API_KEY=hn_your_api_key \
  npx @helpnest/intercom migrate
```

### Migrate all articles (published + draft)

```bash
npx @helpnest/intercom migrate \
  --intercom-token your_token \
  --helpnest-url https://help.yourcompany.com \
  --helpnest-key hn_your_api_key \
  --state all
```

### Migrate collections only

```bash
npx @helpnest/intercom migrate \
  --intercom-token your_token \
  --helpnest-url https://help.yourcompany.com \
  --helpnest-key hn_your_api_key \
  --collections-only
```

---

## What gets migrated

| Item | Migrated | Notes |
|---|---|---|
| Collections | Yes | Hierarchy preserved where possible |
| Articles | Yes | All fields mapped |
| HTML body → Markdown | Yes | Converted via `node-html-markdown` |
| Author info | No | HelpNest assigns the API key's user as author |
| Inline images | Preserved as-is | Image URLs are kept in Markdown `![]()` syntax |
| Attachments | No | Intercom file attachments are not included |

---

## After migration

1. **Review draft articles** in your HelpNest dashboard — any Intercom
   draft articles migrated with `--state draft` or `--state all` will
   land as drafts and require publishing.

2. **Check collection nesting** — if your Intercom workspace uses deeply
   nested sections the parent mapping may need manual adjustment depending
   on your HelpNest collection depth limits.

3. **Images** — article images reference Intercom's CDN URLs. Download and
   re-host them in HelpNest's media library if you need them to be
   self-contained.

---

## License

MIT