# @kody/kit

`community-icon.svg` is Kit's official wordmark from
[kit.com/brand](https://kit.com/brand) on Kit bright blue `#44B1FF`. Kit® is a
trademark of Kit. This package is not affiliated with or endorsed by Kit.

Share this package as https://kody.codes/@kody/kit
(never a `/community/{listing_id}` URL).

## Intent

Reusable Kit (ConvertKit) helpers so Kody agents can list and update **the
caller's** subscribers, forms, tags, broadcast drafts, and sequences. Reads are
free-form. Mutations support `dryRun: true` and require `confirm: true`.
Broadcast helpers are **draft-only** and never send or schedule.

This listing is meant to be forked. After you fork, connect **your** Kit
account. No form ids, list names, sender addresses, or templates are baked in.

## What it does

- List, get, or upsert subscribers and manage tags
- List forms or add a subscriber to a form id the caller provides
- Create or update **draft** broadcasts (send from the Kit UI)
- Create sequences and enroll subscribers after confirmation
- Verify credentials with a smoke test before any write

## Prerequisites / setup

Kit has **no built-in Kody OAuth app**. Choose one lane:

| Lane | When to use | Credential |
| --- | --- | --- |
| **API key** (recommended for personal automation) | Own-account scripts | User secret `kitApiKey` (or `kitApiKey-<purpose>`) sent as `X-Kit-Api-Key` |
| **OAuth** | Kit App Store apps, refresh tokens, multi-account | Saved integration `kit` or `kit-<purpose>` |

Required API host: **`api.kit.com`**. Approve it in the account secrets UI.
Saving a secret does not approve hosts by itself. Never paste keys into chat.

### Lane A — v4 API key

1. Create a v4 key at [Developer settings](https://app.kit.com/account_settings/developer_settings)
2. Save it (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=kitApiKey&description=Kit%20v4%20API%20key%20for%20subscribers%2C%20forms%2C%20tags%2C%20broadcasts%2C%20and%20sequences&allowedHosts=api.kit.com&scope=user

3. Approve host `api.kit.com`

### Lane B — BYO OAuth

1. Create a Kit app and turn on API access:
   https://developers.kit.com/kit-app-store/building-apps#creating-your-app
2. Set the redirect URI **exactly** to `https://kody.codes/connect/oauth`
3. Connect while signed in to Kody:

https://kody.codes/connect/oauth?provider=kit&authorizeUrl=https%3A%2F%2Fapi.kit.com%2Fv4%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.kit.com%2Fv4%2Foauth%2Ftoken&apiBaseUrl=https%3A%2F%2Fapi.kit.com%2Fv4&scopes=public&flow=confidential&pkce=false&allowedHosts=api.kit.com&dashboardUrl=https%3A%2F%2Fdevelopers.kit.com%2Fkit-app-store%2Fbuilding-apps%23creating-your-app

4. Paste the Kit client id and client secret into the Kody wizard (never into chat)
5. Reconnect later with https://kody.codes/connect/oauth?provider=kit

OAuth authorize URL: `https://api.kit.com/v4/oauth/authorize`. Token URL:
`https://api.kit.com/v4/oauth/token`. Default scope is `public`.

To connect a second account, change `provider` (for example `provider=kit-work`)
and pass `account: 'work'` or `integrationName: 'kit-work'` /
`secretName: 'kitApiKey-work'` on every call.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and
mutation guards.

## Done when

- `kitApiKey` is saved or OAuth `kit` is connected; host `api.kit.com` is approved
- Smoke test returns `ok: true` (live account sample when credentials exist)
- Broadcast helpers only create/update drafts; sends stay in the Kit UI
- Live writes refuse unless `confirm: true`; `dryRun: true` never contacts Kit

## Jobs

`account-health` calls `./scheduled-account-health` weekly (Monday 09:00 UTC).
It is **`enabled: false`**. Enabling it is an operator choice after you fork
and confirm the read is right for your account.