# @kody/kit — 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 by
**name** only — never paste key values. Do not disable live webhooks or jobs
(the bundled `account-health` job stays `enabled: false` unless the operator
turns it on after a fork).

## Auth

| Lane | Credential |
| --- | --- |
| API key | `kitApiKey` / `kitApiKey-<purpose>` → header `X-Kit-Api-Key` |
| OAuth | integration `kit` / `kit-<purpose>` |

Host: `api.kit.com`. Multi-account: `account: 'work'` → `kit-work` /
`kitApiKey-work`, or pass `integrationName` / `secretName` explicitly.

## Import paths

| Export | Import |
| --- | --- |
| root dispatcher (default `smoke-test`) + re-exports | `kody:@kody/kit` |
| accounts | `kody:@kody/kit/accounts` |
| account | `kody:@kody/kit/account` |
| request | `kody:@kody/kit/request` |
| subscribers | `kody:@kody/kit/subscribers` |
| tags | `kody:@kody/kit/tags` |
| forms | `kody:@kody/kit/forms` |
| broadcasts | `kody:@kody/kit/broadcasts` |
| sequences | `kody:@kody/kit/sequences` |
| html | `kody:@kody/kit/html` |
| smoke-test | `kody:@kody/kit/smoke-test` |
| scheduled-account-health | `kody:@kody/kit/scheduled-account-health` |
| types | `kody:@kody/kit/types` |

Prefer static `kody:@kody/kit/...` imports from `execute`. Do not lead with
`packages.invoke`. Pass `maxItems` on list helpers or large accounts can exhaust
the execute timeout.

## Smoke test (read-only)

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

export default async function main() {
	return await smokeTest()
	// Without credentials: { ok: true, live: false, setup URLs }
	// With key/OAuth: live account + a few broadcasts — no writes
}
```

Equivalent via root dispatcher:

```js
import kit from 'kody:@kody/kit'

export default async function main() {
	return await kit({ action: 'smoke-test' })
}
```

## dryRun / confirm

Pass `dryRun: true` on writes to return `{ dryRun: true, method, path, body }`
without contacting Kit. Live writes throw unless `confirm: true`.

```js
import { createBroadcastDraft } from 'kody:@kody/kit/broadcasts'
import { subscribeAndTag } from 'kody:@kody/kit/subscribers'

export default async function main() {
	const draftPreview = await createBroadcastDraft({
		subject: 'Workshop reminder',
		content: '<p>See you tomorrow.</p>',
		dryRun: true,
	})
	const signupPreview = await subscribeAndTag({
		email_address: 'ada@example.com',
		tagName: 'waitlist',
		dryRun: true,
	})
	return { draftPreview, signupPreview }
}
```

A live draft only after explicit user approval of the exact subject and body:

```js
import { createBroadcastDraft } from 'kody:@kody/kit/broadcasts'

export default async function main() {
	return await createBroadcastDraft({
		subject: 'Workshop reminder',
		content: '<p>See you tomorrow.</p>',
		confirm: true,
	})
}
```

## Edge cases

- Broadcast helpers refuse `send_at` and send/publish statuses. There is no
  send-broadcast export. A human sends drafts from the returned `editUrl`.
- Form ids, tag names, sender addresses, and sequence names come from the call.
  This package has no default list, form, or template.
- Always pass `maxItems` on exploratory list helpers.
- Errors: missing credentials → save `kitApiKey` or connect OAuth; 401 → approve
  host `api.kit.com`; 403 → some bulk/purchase endpoints require OAuth; timeout
  on lists → pass `maxItems`.
- Do not enable the `account-health` job on the official listing; after a fork,
  enable only if the operator wants the weekly read.