@kody/kit

@kody/kit

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

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.

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

Agent setup

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

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
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
4. Run the smoke test below

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.

When To Use

• 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 ./smoke-test before any write

Mutation safety

• Pass dryRun: true on writes to return { dryRun: true, method, path, body } without contacting Kit.
• Live writes throw unless confirm: true.
• 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.

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

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,
})

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

await createBroadcastDraft({
	subject: 'Workshop reminder',
	content: '<p>See you tomorrow.</p>',
	confirm: true,
})

Smoke test

./smoke-test is safe before anyone saves credentials: it returns { ok: true, live: false } and the setup URLs. After an API key or OAuth connection and host approval, a static import reads the account and a few broadcasts — it does not create subscribers or send email.

import kit from 'kody:@kody/kit'

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

Exports

• kody:@kody/kit — action dispatcher (defaults to smoke-test); also re-exports every helper
• kody:@kody/kit/subscribers — list, get, create, update, unsubscribe, subscribe-and-tag
• kody:@kody/kit/tags — list, create, ensure, tag, untag
• kody:@kody/kit/forms — list forms, add subscriber to a form, list segments
• kody:@kody/kit/broadcasts — list, get, draft create/update, delete, stats
• kody:@kody/kit/sequences — list/create sequences and emails, enroll
• kody:@kody/kit/html — generic Liquid greeting and HTML blocks
• kody:@kody/kit/account — account, email stats, growth stats
• kody:@kody/kit/accounts — resolve integration/secret names
• kody:@kody/kit/request — raw v4 path helper
• kody:@kody/kit/smoke-test — dry-run self-check, then a live read
• kody:@kody/kit/scheduled-account-health — no-arg weekly wrapper (job account-health is disabled by default)

Pass maxItems on list helpers. Without a cap, large accounts can exhaust the execute timeout.

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.

Errors