# @kody/netlify — agent notes

Human setup and intent live in [`README.md`](./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 or enable live jobs
unless the operator asks — the bundled `site-status` job stays `enabled: false`
unless they turn it on after a fork.

## Secrets

| Name | Purpose |
| --- | --- |
| `netlifyToken` | Default PAT (user scope); host `api.netlify.com` |
| `netlifyToken-<label>` | Extra account via `account: "<label>"` or `secretName` |

## Import paths

| Export | Import |
| --- | --- |
| root dispatcher (default `smoke-test`) | `kody:@kody/netlify` |
| request | `kody:@kody/netlify/request` |
| get-user | `kody:@kody/netlify/get-user` |
| list-accounts | `kody:@kody/netlify/list-accounts` |
| list-sites | `kody:@kody/netlify/list-sites` |
| get-site | `kody:@kody/netlify/get-site` |
| list-deploys | `kody:@kody/netlify/list-deploys` |
| get-deploy | `kody:@kody/netlify/get-deploy` |
| create-deploy | `kody:@kody/netlify/create-deploy` |
| restore-deploy | `kody:@kody/netlify/restore-deploy` |
| list-env-vars | `kody:@kody/netlify/list-env-vars` |
| create-env-var | `kody:@kody/netlify/create-env-var` |
| list-forms | `kody:@kody/netlify/list-forms` |
| list-form-submissions | `kody:@kody/netlify/list-form-submissions` |
| smoke-test | `kody:@kody/netlify/smoke-test` |
| scheduled-status | `kody:@kody/netlify/scheduled-status` |

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

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/netlify/smoke-test'

export default async function main() {
	return await smokeTest()
	// Without netlifyToken: { ok: true, live: false, setup URLs }
	// With token: trimmed /user profile — no writes
}
```

Equivalent via root dispatcher:

```js
import netlify from 'kody:@kody/netlify'

export default async function main() {
	return await netlify({ dryRun: true })
}
```

Read-only list:

```js
import listSites from 'kody:@kody/netlify/list-sites'

export default async function main() {
	return await listSites({ per_page: 20 })
}
```

## dryRun / confirm

Pass `dryRun: true` on `create-deploy`, `restore-deploy`, `create-env-var`, and
mutating `request` calls to return `{ dryRun: true, method, path, body }` without
contacting Netlify. Those writes also throw unless `confirm: true`.

```js
import createDeploy from 'kody:@kody/netlify/create-deploy'

export default async function main() {
	return await createDeploy({
		site: 'example-site',
		draft: true,
		dryRun: true,
	})
}
```

```js
import restoreDeploy from 'kody:@kody/netlify/restore-deploy'

export default async function main() {
	return await restoreDeploy({
		site: 'example-site',
		deploy: 'deploy_123',
		dryRun: true,
	})
}
```

```js
import createEnvVar from 'kody:@kody/netlify/create-env-var'

export default async function main() {
	return await createEnvVar({
		accountId: 'acme',
		site: 'example-site',
		key: 'EXAMPLE_FLAG',
		value: '1',
		dryRun: true,
	})
}
```

## Edge cases

- Env-var listing never returns values; dry-run create redacts `value`.
- Never set `production: true` on create-deploy or restore production unless the
  caller explicitly confirmed that target.
- Site ids, team slugs, and form ids come from the call — nothing is hard-coded.
- Do not enable the `site-status` job on the official listing; after a fork,
  enable only if the operator wants the periodic read.
- Fork/adapt: save your own `netlifyToken`; do not point at a shared platform
  store. Keep `dryRun` / `confirm` guards.