@kody/cloudflare

Call Cloudflare zones, Workers, analytics, WAF, and Log Explorer with a saved API token.

AGENTS.md

78 lines · 2.2 KB · Markdown

@kody/cloudflare — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by name only — never paste token values. Do not disable live webhooks or jobs (this package ships none).

Secrets

Name	Purpose
`cloudflareApiToken`	API v4, GraphQL analytics, Log Explorer, rulesets

Host: api.cloudflare.com. ./docs hits developers.cloudflare.com without the token.

Import paths

Export	Import
overview / discovery metadata	`kody:@kody/cloudflare` or `kody:@kody/cloudflare/overview`
REST under `/client/v4/` (mutating)	`kody:@kody/cloudflare/api-v4`
GraphQL zone traffic summaries (read-only)	`kody:@kody/cloudflare/analytics`
allowlisted developer docs (read-only)	`kody:@kody/cloudflare/docs`
Log Explorer SQL search (read-only)	`kody:@kody/cloudflare/observability-logs`
WAF custom rule preview/apply (mutating; dry-run default)	`kody:@kody/cloudflare/rulesets`

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

Smoke test (read-only)

Verify the saved token with GET:

import apiV4 from 'kody:@kody/cloudflare/api-v4'

export default async function main() {
	return await apiV4({ path: '/client/v4/user/tokens/verify' })
}

Read helpers

import analytics from 'kody:@kody/cloudflare/analytics'

export default async function main() {
	return await analytics({ zoneName: 'example.com', last: '1h' })
}

import searchLogs from 'kody:@kody/cloudflare/observability-logs'

export default async function main() {
	return await searchLogs({
		accountId: 'your-account-id',
		scriptName: 'my-worker',
		outcome: 'exception',
		last: '30m',
		limit: 25,
	})
}

Mutation safety

./api-v4 sends the method you pass. Prefer GET for smoke tests.

./rulesets defaults to dry-run. Pass apply: true only after reviewing the returned entrypoint body.

Edge cases

No account ids or zone names are baked into the package — callers supply them.
Analytics, Log Explorer, and docs stay read-only.
A read token is enough for verify/analytics/logs; ruleset apply needs firewall edit.