@kody/airtable

@kody/airtable — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Auth is the saved OAuth integration airtable / airtable-* or user secret airtablePat — never paste tokens. Do not disable live webhooks or jobs.

Auth

Required host: api.airtable.com. REST base: https://api.airtable.com/v0.

Import paths

Prefer static kody:@kody/airtable/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only)

import smokeTest from 'kody:@kody/airtable/smoke-test'

export default async function main() {
	return await smokeTest()
	// without creds => { ok: true, live: false, ...setup URLs }
	// with OAuth/PAT => { ok: true, live: true, hasViewerId } — no email
}

Read-only samples:

import listBases from 'kody:@kody/airtable/list-bases'
import listTables from 'kody:@kody/airtable/list-tables'

export default async function main() {
	const { items: bases } = await listBases()
	return await listTables({
		baseId: bases[0]?.id ?? '',
	})
}

import request from 'kody:@kody/airtable/request'

export default async function main() {
	return await request({
		path: '/meta/whoami',
	})
}

dryRun / confirm (writes)

create-record, update-record, delete-record, create-comment, and mutating ./request methods (POST / PUT / PATCH / DELETE) require confirm: true. Pass dryRun: true to inspect the REST payload without calling Airtable. GET via ./request is read-only.

import createRecord from 'kody:@kody/airtable/create-record'

export default async function main() {
	const preview = await createRecord({
		baseId: 'appXXXXXXXXXXXXXX',
		tableIdOrName: 'tblXXXXXXXXXXXXXX',
		fields: { Name: 'Investigate checkout timeout' },
		dryRun: true,
	})
	// Only after explicit user confirmation of base, table, and fields:
	return await createRecord({
		baseId: 'appXXXXXXXXXXXXXX',
		tableIdOrName: 'tblXXXXXXXXXXXXXX',
		fields: { Name: 'Investigate checkout timeout' },
		confirm: true,
	})
}

Edge cases / fork notes

• Prefer table ids (tbl…) over names when a name can collide or contain spaces.
• Helpers project slim objects (no collaborator emails). Use ./request for extra fields.
• If Airtable returns 401/403 or an insufficient-scope error, helpers throw a message that names the missing scope and the next setup URL.
• Do not hard-code a personal base id, table name, or alias.
• No package-owned jobs are enabled.
• Never paste Airtable OAuth client secrets or PAT values into chat or logs.