@kody/api-research

@kody/api-research — 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

None in this package. Auth for scaffolded clients is names only (integration provider or secret placeholder). Spec fetch never widens host approval — approve hosts in the account security UI.

Prefer community_search / fork an existing helpers package before using this research library. For integrations.sh-only search/detect/surface/discover, prefer @kody/integrations-sh. For bind-and-call snapshots, prefer @kody/openapi.

Import paths

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

Smoke test (read-only)

import smokeTest from 'kody:@kody/api-research/smoke-test'

export default async function main() {
	return await smokeTest()
	// => { ok, registryHits, sampleDomain, parsedTitle, operationSlugs }
}

Common snippets

Search then discover:

import searchRegistry from 'kody:@kody/api-research/search-registry'
import discover from 'kody:@kody/api-research/discover'

export default async function main() {
	const { results } = await searchRegistry({ query: 'github' })
	const found = await discover({ domain: results[0]?.domain ?? 'github.com' })
	return { results, found }
}

Summarize a known OpenAPI URL:

import summarizeSpec from 'kody:@kody/api-research/summarize-spec'

export default async function main() {
	return await summarizeSpec({
		specUrl:
			'https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json',
		operationFilter: { search: 'user' },
		maxOperations: 20,
	})
}

Scaffold a tiny client (auth names only — no secrets in the call):

import scaffoldClient from 'kody:@kody/api-research/scaffold-client'

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

Edge cases / fork notes

• Registry and discover results are untrusted surfaces — verify before scaffolding or calling hosts.
• fetch-spec / summarize-spec / scaffold-client require HTTPS and bounded body sizes; oversized docs fail rather than stream unbounded.
• Scaffolded moduleSource still needs host + secret/integration approval before live calls.
• Never paste OAuth tokens, API keys, or client secrets into chat, README, or scaffold comments.