# @kody/netlify

## Intent

Reusable Netlify REST helpers so Kody agents can inspect **the caller's** sites,
deploys, environment-variable metadata, and forms — not a shared platform
account. Auth is a saved personal access token. Reads are free-form. Mutations
(`create-deploy`, `restore-deploy`, `create-env-var`, and mutating `request`
calls) support `dryRun: true`, and live writes also require `confirm: true`.

This listing is meant to be forked. After you fork, save your own `netlifyToken`
and call the helpers in your account. No personal site ids or team slugs are
hard-coded. Environment-variable listing returns keys, scopes, and contexts
only — values are never returned.

Share this package as https://kody.codes/@kody/netlify

## What it does

- List and get sites, deploys, forms, and form submissions
- List environment-variable **metadata** (never values)
- Create deploys, restore a previous deploy, or create env vars with
  `dryRun` / `confirm` guards
- Escape-hatch `request` for paths without a typed helper
- Credential smoke test that stays read-only

## Prerequisites / setup

Create a [Netlify personal access token](https://app.netlify.com/user/applications#personal-access-tokens),
then save it in Kody (do not paste the value in chat):

```
https://kody.codes/account/secrets/new?name=netlifyToken&description=Netlify%20personal%20access%20token%20(Bearer%20for%20api.netlify.com)&allowedHosts=api.netlify.com&scope=user
```

1. Open [User settings → Applications → Personal access tokens](https://app.netlify.com/user/applications#personal-access-tokens).
2. Create a token. If the team uses SAML SSO, grant the token access to that team.
3. Save it at the URL above. In the account secrets UI, approve host `api.netlify.com`.
4. Smoke-test (see [`AGENTS.md`](./AGENTS.md)).

Default helper input: omit `secretName`. The package sends `Authorization: Bearer`
using `netlifyToken`.

Pass `account: "work"` to use secret `netlifyToken-work`, or pass
`secretName: "netlifyToken-team"`. There are no hard-coded account aliases.

### Hosts

- `api.netlify.com` — all REST calls (required)
- `app.netlify.com` — token dashboard (setup only)

### Mutation safety

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 same writes also throw unless `confirm: true`.

`restore-deploy` publishes the chosen deploy to the site's production URL. Do
not restore or create production deploys unless the caller explicitly confirmed
that target. Env-var dry-run previews redact `value`. Listing env vars never
returns values.

Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and
confirm guards.

## Done when

- `netlifyToken` is saved; host `api.netlify.com` is approved
- Smoke test returns `ok: true` (live `/user` profile when the token exists)
- Destructive helpers refuse unless `confirm: true`; `dryRun: true` never writes
- Env-var listing never returns values

## Jobs

`site-status` lists sites on a 12-hour cron. It is **`enabled: false`**. Enabling
it is an operator choice after you fork and confirm the read is right for your
account.

## Branding

`community-icon.svg` is Netlify's official monogram from the
[Netlify press / brand assets](https://www.netlify.com/press) kit (full-color
light mode). Netlify is a trademark of Netlify, Inc. This package is not
affiliated with or endorsed by Netlify.

## Docs

- [Get started with the Netlify API](https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/)
- [OpenAPI reference](https://open-api.netlify.com/)
- [Personal access tokens](https://app.netlify.com/user/applications#personal-access-tokens)