Kit plugin

• Kit pages by cursor. A list answers a pagination block with end_cursor, start_cursor and has_next_page. Pass end_cursor back as after for the next page, or start_cursor as before for the previous one, and stop when has_next_page is false.
• Only active subscribers are returned by default. subscribers.list takes status; pass all to widen it, or one of active, inactive, bounced, complained, cancelled.
• canceled_at needs the cancelled status. Asking for it beside any other status is refused, and the plugin checks that before the call rather than letting Kit answer 422.
• Creating a subscriber with an address already on the list returns the existing one, so a create is safe to repeat.
• Custom field values go by key, not label. A subscriber’s fields map is keyed by the field’s key, such as last_name. An unknown key is ignored and named in the response warnings array rather than failing, so read warnings when a value seems missing.
• Tag and form subscribes need an existing subscriber. tags.tagSubscriber and forms.subscribe find the subscriber by address and answer 404 when there is none, so call subscribers.create first for a new address. Subscribing through a form then applies the form’s incentive and records added_at.
• No bulk routes. Kit only accepts its /v4/bulk/* routes with an OAuth token, and this plugin authenticates with an API key, so create subscribers one at a time with subscribers.create.
• subscribers.unsubscribe cannot be undone from here. It stops every future send to that person, and only they can resubscribe.
• Rate limits. Kit enforces two request windows and sends Retry-After on a 429, which the plugin honours before backing off.
• Webhooks. The plugin does not receive Kit webhooks; Kit has a separate endpoint-management API that is not wrapped here.

• 16 typed API operations

Setup

npm install corsair @corsair-dev/kit better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/kit better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/kit better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/kit better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { kit } from '@corsair-dev/kit';

export const corsair = createCorsair({
	plugins: [
		kit(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

kit()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'kit',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.kit.api.subscribers.list({ per_page: 25 });

const tenant = corsair.withTenant('acme');
await tenant.kit.api.subscribers.create({ email_address: 'jordan@acme.example', first_name: 'Jordan' });

What’s next