@kody/openapi

@kody/openapi — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke checks, snippets, and edge cases. Never paste tokens or credential values. Do not disable live webhooks or jobs.

Auth

Auth is names only on bind/call:

Never store raw credentials. Spec fetch and calls do not widen host approval — approve hosts in the account security UI. Prefer community_search / a product helpers package before bind-and-call. For registry search, summarize, or scaffold, prefer @kody/api-research.

Person accounts: community_fork first, then import kody:@<username>/openapi/... (not live @kody/openapi).

Import paths

Replace <username> with the fork owner (or kody when running as the platform listing owner).

Prefer static kody:@<username>/openapi/... imports from execute. Do not lead with packages.invoke.

Smoke test (read-only storage)

Uses an inline ping spec — no live API call.

import smokeTest from 'kody:@<username>/openapi/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok: true, slug: 'ping', ... }
}

Common snippets

Bind then call (auth names only):

import bind from 'kody:@<username>/openapi/bind'
import call from 'kody:@<username>/openapi/call'

export default async function main() {
	await bind({
		name: 'github',
		specUrl:
			'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
		apiBaseUrl: 'https://api.github.com',
		auth: { kind: 'integration', provider: 'github' },
		selection: { operationIds: ['users_get_authenticated'] },
	})

	return await call({
		name: 'github',
		operation: 'users_get_authenticated',
	})
}

List / get / refresh / unbind:

import list from 'kody:@<username>/openapi/list'
import get from 'kody:@<username>/openapi/get'
import refresh from 'kody:@<username>/openapi/refresh'
import unbind from 'kody:@<username>/openapi/unbind'

export default async function main() {
	const { bindings } = await list()
	const detail = await get({ name: 'github' })
	await refresh({ name: 'github' })
	await unbind({ name: 'github' })
	return { bindings, detail }
}

Edge cases / fork notes

• Bindings live in this package's packageStorage() — fork before writing.
• Selection is bounded (about 100 operations); narrow with operationIds, pathPrefixes, or similar selection fields.
• YAML OpenAPI needs JSON conversion first (@kody/api-research parse helpers).
• Calls require host approval for apiBaseUrl; failures are not silent empties.
• Never paste OAuth tokens, API keys, or client secrets into chat, README, or binding metadata.