@kody/supabase

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

When To Use

• 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

Auth

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

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

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.

Exports

Smoke test

import supabase from 'kody:@kody/supabase'

export default async function main() {
	return await supabase()
}

Without credentials this returns { smoke: { ok: true, live: false } } plus the PAT and service-role setup URLs. After secrets are saved it performs read-only list calls (project refs, optional bucket names) and never writes.

Preview a mutation without credentials:

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,
	})
}

Examples

import listProjects from 'kody:@kody/supabase/list-projects'

export default async function main() {
	return await listProjects({ limit: 20 })
}

import selectRows from 'kody:@kody/supabase/select-rows'
import insertRows from 'kody:@kody/supabase/insert-rows'

export default async function main() {
	const rows = await selectRows({
		projectRef: 'yourprojectref00000',
		table: 'items',
		select: 'id,name',
		limit: 10,
	})
	const preview = await insertRows({
		projectRef: 'yourprojectref00000',
		table: 'items',
		rows: [{ name: 'Follow up' }],
		dryRun: true,
	})
	return { rows, preview }
}

Unwrapped Management API:

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

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

Notes

• 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 you pass includeIdentifiers: true
• This package is not affiliated with or endorsed by Supabase, Inc.

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.

Docs

• Management API
• Data REST / PostgREST
• Auth Admin
• Storage
• Account tokens