Skip to content

README.md

108 lines · 4.7 KB · Markdown

@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:

LaneSecretHostUsed for
Personal access tokensupabasePat (or supabasePat-<purpose>)api.supabase.comProjects, organizations, ./management-request
Service role / secret keysupabaseServiceRoleKey (or supabaseServiceRoleKey-<purpose>){projectRef}.supabase.coAuth 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 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 (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