# @kody/supabase — 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 PAT or service-role values. Do not enable the
bundled `smoke` job unless the operator asks after a fork. Do not disable live
webhooks or jobs.

## Secrets

| Name | Purpose |
| --- | --- |
| `supabasePat` | Management API PAT; host `api.supabase.com` |
| `supabaseServiceRoleKey` | Project service role / secret key; host `{projectRef}.supabase.co` |
| `supabasePat-<label>` / `supabaseServiceRoleKey-<label>` | Extra account via `account`, `patSecretName`, `serviceRoleSecretName`, or `secretName` |

## Import paths

| Export | Import |
| --- | --- |
| root overview + smoke | `kody:@kody/supabase` |
| accounts | `kody:@kody/supabase/accounts` |
| setup | `kody:@kody/supabase/setup` |
| smoke-test | `kody:@kody/supabase/smoke-test` |
| list-projects | `kody:@kody/supabase/list-projects` |
| get-project | `kody:@kody/supabase/get-project` |
| list-organizations | `kody:@kody/supabase/list-organizations` |
| list-users | `kody:@kody/supabase/list-users` |
| get-user | `kody:@kody/supabase/get-user` |
| create-user | `kody:@kody/supabase/create-user` |
| update-user | `kody:@kody/supabase/update-user` |
| delete-user | `kody:@kody/supabase/delete-user` |
| select-rows | `kody:@kody/supabase/select-rows` |
| insert-rows | `kody:@kody/supabase/insert-rows` |
| update-rows | `kody:@kody/supabase/update-rows` |
| delete-rows | `kody:@kody/supabase/delete-rows` |
| list-buckets | `kody:@kody/supabase/list-buckets` |
| list-objects | `kody:@kody/supabase/list-objects` |
| upload-object | `kody:@kody/supabase/upload-object` |
| delete-object | `kody:@kody/supabase/delete-object` |
| create-signed-url | `kody:@kody/supabase/create-signed-url` |
| request | `kody:@kody/supabase/request` |
| management-request | `kody:@kody/supabase/management-request` |
| types | `kody:@kody/supabase/types` |

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

## Smoke test (read-only)

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

export default async function main() {
	return await supabase()
	// Without credentials: { smoke: { ok: true, live: false }, setup URLs }
	// With secrets: read-only list calls — never writes
}
```

Or the dedicated export:

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

export default async function main() {
	return await smokeTest()
}
```

## dryRun / confirm

Pass `dryRun: true` on mutations to inspect method/path/body without calling
Supabase. Live mutations also require `confirm: true`. Unfiltered
`update-rows` / `delete-rows` need `allowUnfiltered: true`.

```js
import insertRows from 'kody:@kody/supabase/insert-rows'

export default async function main() {
	return await insertRows({
		projectRef: 'yourprojectref00000',
		table: 'items',
		rows: [{ name: 'Preview only' }],
		dryRun: true,
	})
}
```

Read-only examples:

```js
import listProjects from 'kody:@kody/supabase/list-projects'
import selectRows from 'kody:@kody/supabase/select-rows'

export default async function main() {
	const projects = await listProjects({ limit: 20 })
	const rows = await selectRows({
		projectRef: 'yourprojectref00000',
		table: 'items',
		select: 'id,name',
		limit: 10,
	})
	return { projects, rows }
}
```

Escape hatch:

```js
import managementRequest from 'kody:@kody/supabase/management-request'

export default async function main() {
	return await managementRequest({ path: '/v1/projects' })
}
```

## Edge cases

- Management API base: `https://api.supabase.com`
- Project API base: `https://{projectRef}.supabase.co`
- PostgREST filters use operator strings such as `{ id: 'eq.1' }`
- `./list-users` omits email and phone unless `includeIdentifiers: true`
- Never hard-code a personal project ref in forks
- Keep the `smoke` job `enabled: false` on the official listing
- Fork/adapt: save the caller's own PAT / service-role secrets; keep
  `dryRun` / `confirm` / `allowUnfiltered` guards