# @kody/supabase

## Intent

Provide reusable, account-agnostic Supabase helpers so Kody agents can list
projects, administer Auth users, read and write PostgREST tables, manage
Storage, and call the Management API through saved secrets — without
hand-rolling REST or hard-coding a project. Mutations are previewable with
`dryRun: true` and only run live after `confirm: true`.

This listing is meant to be forked. After you fork, save **your** personal
access token and project service role / secret key. Do not treat the live
`@kody/supabase` package storage as yours.

## What it does

- List or inspect organizations and projects on the Management API
- List, create, update, or delete Auth users on a project
- Select, insert, update, or delete PostgREST table rows
- List buckets and objects; upload, delete, or sign Storage objects
- Call an unwrapped Management API or project API path

## Prerequisites / setup

Supabase is **secret-backed**. There is no built-in Kody OAuth app for this
package. Choose the secret that matches the surface:

| Lane | Secret | Host | Used for |
| --- | --- | --- | --- |
| **Personal access token** | `supabasePat` (or `supabasePat-<purpose>`) | `api.supabase.com` | Projects, organizations, `./management-request` |
| **Service role / secret key** | `supabaseServiceRoleKey` (or `supabaseServiceRoleKey-<purpose>`) | `{projectRef}.supabase.co` | Auth admin, PostgREST, Storage, `./request` |

Create a PAT at https://supabase.com/dashboard/account/tokens  
Copy a project service role or secret key at https://supabase.com/dashboard/project/_/settings/api-keys/

The service role / secret key bypasses Row Level Security. Keep it in Kody
secrets only. Never paste it into chat.

### Save the personal access token

https://kody.codes/account/secrets/new?name=supabasePat&description=Supabase%20personal%20access%20token%20for%20the%20Management%20API%20(projects%2C%20orgs%2C%20generic%20%2Fv1%20paths)&allowedHosts=api.supabase.com&scope=user

Approve host **`api.supabase.com`** in the account secrets UI.

### Save the project service role / secret key

Replace `YOUR_PROJECT_REF` with the project ref (the subdomain of
`YOUR_PROJECT_REF.supabase.co`):

https://kody.codes/account/secrets/new?name=supabaseServiceRoleKey&description=Supabase%20project%20service%20role%20or%20secret%20key%20for%20Auth%20admin%2C%20PostgREST%2C%20and%20Storage&allowedHosts=YOUR_PROJECT_REF.supabase.co&scope=user

Approve host **`YOUR_PROJECT_REF.supabase.co`**. For a custom API domain, pass
`projectUrl` on every project call and approve that host instead.

Pass `projectRef` (or `projectUrl`) on Auth, table, Storage, and `./request`
helpers. Do not hard-code a personal project ref in forks of this package.

### Multiple accounts

Every export accepts:

- `account` — `work` → `supabasePat-work` / `supabaseServiceRoleKey-work`
- `patSecretName` — Management API secret override
- `serviceRoleSecretName` — project API secret override
- `secretName` — alias for the PAT on Management helpers, or the service role
  on project helpers

https://kody.codes/account/secrets/new?name=supabasePat-work&description=Supabase%20Management%20API%20PAT%20for%20the%20work%20account&allowedHosts=api.supabase.com&scope=user

### Mutation safety

Mutating helpers require `confirm: true`. Pass `dryRun: true` to inspect the
method, path, and body without calling Supabase. `./request` and
`./management-request` treat GET / HEAD / OPTIONS as read-only; POST / PUT /
PATCH / DELETE need confirmation.

Unfiltered `./update-rows` and `./delete-rows` also need
`allowUnfiltered: true` so a missing filter cannot rewrite or empty a table.

The package-owned `smoke` job is declared with `"enabled": false`. Enabling it
is an operator choice after you fork.

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

## Done when

- `supabasePat` and/or `supabaseServiceRoleKey` are saved; matching hosts are
  approved
- Smoke test returns `ok: true` (live read-only lists when secrets exist)
- Destructive helpers refuse unless `confirm: true`; `dryRun: true` never writes
- Unfiltered update/delete still require `allowUnfiltered: true`

## Branding

The community icon is Supabase's official logo icon from
[Supabase brand assets](https://supabase.com/brand-assets)
(`brand-assets/supabase-logo-icon.svg`). Paths are unmodified. Supabase® is a
trademark of Supabase, Inc. This package is not affiliated with or endorsed by
Supabase, Inc.

## Docs

- [Management API](https://supabase.com/docs/reference/api/introduction)
- [Data REST / PostgREST](https://supabase.com/docs/guides/api)
- [Auth Admin](https://supabase.com/docs/reference/javascript/auth-admin-listusers)
- [Storage](https://supabase.com/docs/guides/storage)
- [Account tokens](https://supabase.com/dashboard/account/tokens)