better-supabase 0.0.0 → 0.1.0

package/skills/better-supabase/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: better-supabase
+description: Query and write Supabase data with better-supabase's typed repositories, Results and codegen. Use when code imports better-supabase, when adding a table, query or mutation, or when a Supabase type is out of date.
+---
+
+# better-supabase
+
+The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
+`schema` comes from the generated module (`config.output`, usually
+`src/lib/supabase/generated.ts`). Never edit generated files.
+
+## Workflow: change the schema
+
+1. Write the migration (`supabase/schemas/*.sql` plus `supabase db diff`, or
+   `supabase migration new`).
+2. Apply it with `supabase db reset` (or `supabase migration up`).
+3. Run `pnpm better-supabase gen`, then fix the type errors it surfaces.
+4. Run `pnpm better-supabase doctor` and fix every error it reports (RLS off,
+   missing policies, unindexed foreign keys, drift).
+5. Commit the generated files. CI runs `better-supabase gen --check`.
+
+Done when `gen --check` and `doctor` exit 0 and the project typechecks.
+
+## Workflow: add a query or mutation
+
+1. Get `db` from the request context (see below), never from a global client,
+   so RLS applies.
+2. Call the repository method and return or branch on its `Result`.
+3. If a plugin owns a column (timestamps, soft delete, tenant, actor), leave
+   it out of the input. See [references/plugins.md](references/plugins.md).
+4. Cover the rule with an RLS test as a real user (the
+   `better-supabase-testing` skill).
+
+Done when the call typechecks without casts, the error path returns the
+`DbError` (not a thrown exception), and a test shows another tenant's rows
+stay hidden.
+
+## Where `db` comes from
+
+- Next.js: `const { db } = await next.server()`, `next.route(...)`, `next.action(...)`
+- Next.js Cache Components: keep layouts synchronous; read `next.session()` in a `'use cache: private'` function inside `<Suspense>`, pass the promise to `<SessionProvider>` and read it with `useSession()`
+- Hono: `c.var.db` after `bs.middleware()`
+- oRPC: `context.db` after `bs.middleware()`
+- Edge Functions: `bs.handler((request, { db }) => ...)`
+- Browser: `browser.db`, or the hooks from `createHooks<typeof browser>()`
+
+## Querying
+
+```ts
+const result = await db.customers.findMany({
+  select: ['id', 'name'],
+  where: { status: 'active', notes: { some: { kind: 'call' } } },
+  include: { organization: { select: ['name'] } },
+  orderBy: { name: 'asc' },
+  limit: 20,
+});
+if (!result.ok) return result; // DbError: kind, message, status, code
+const customers = result.data;
+```
+
+- Methods return a `Result`, and database errors never throw. Use `.orThrow()` only where an exception is really wanted.
+- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, `$sql`) use database names.
+- Writes: `create`, `createMany`, `update(id, patch)`, `updateMany`, `upsert`, `delete`.
+- Handlers may return a `Result` directly. Adapters turn errors into RFC 9457 Problem Details with the right status.
+- Server-only admin access: `server.admin()`. Only use it for trusted jobs, never for a user's request.
+- PostgREST has no multi-request transactions. Put multi-step writes in a database function (`db.$rpc()`) or use `postgres.transaction()` on the server.
+
+## Don't
+
+- Don't create supabase-js clients by hand, and don't read cookies yourself. Use the adapters.
+- Don't add `declare module` augmentation for types; everything comes from `schema`.
+- Don't catch and swallow `DbError`; return it, or map it with `mapDbError`.
+- Don't cast rows (`as Customer`). If a type is wrong, the schema or the generated file is out of date: rerun `gen`.
+
+## When something fails
+
+See [references/troubleshooting.md](references/troubleshooting.md) for each
+`DbError` kind and the usual cause.
+
+## Docs
+
+https://bettersupabase.com/docs. Every page is also served as Markdown at
+`https://bettersupabase.com/docs/<path>.md`, and
+https://bettersupabase.com/llms.txt lists them all.

package/skills/better-supabase/references/plugins.md

@@ -0,0 +1,56 @@
+# Plugins
+
+```ts title="src/lib/supabase.ts"
+import { defineSupabase } from 'better-supabase';
+import { actor } from 'better-supabase/plugins/actor';
+import { softDelete } from 'better-supabase/plugins/soft-delete';
+import { tenant } from 'better-supabase/plugins/tenant';
+import { timestamps } from 'better-supabase/plugins/timestamps';
+import { validation } from 'better-supabase/plugins/validation';
+
+import { schema } from './supabase/generated.ts';
+import { validators } from './supabase/generated.zod.ts';
+
+export const sb = defineSupabase(schema)
+  .use(timestamps())
+  .use(softDelete())
+  .use(tenant())
+  .use(actor())
+  .use(validation({ schemas: validators }));
+```
+
+Plugins act on tables by the flags codegen writes. Turn them on in
+`better-supabase.config.ts`, then rerun `gen`:
+
+```ts
+plugins: {
+  timestamps: true,                      // created_at, updated_at
+  softDelete: { column: 'archived_at' }, // default deleted_at
+  tenant: { column: 'organization_id' },
+  actor: true,                           // created_by, updated_by
+}
+```
+
+A table without the columns is left alone, and the types follow:
+`restore()` and `withDeleted` only exist on soft-delete tables.
+
+| Plugin | What it does | Don't |
+| --- | --- | --- |
+| `timestamps()` | Sets `createdAt` and `updatedAt` | set them in `create` or `update` |
+| `softDelete()` | Hides deleted rows, turns `delete` into an update, adds `restore` | filter `deletedAt: null` by hand |
+| `tenant()` | Scopes queries to the request's tenant and fills it on insert | pass `organizationId` from the client |
+| `actor()` | Sets `createdBy` and `updatedBy` | pass the user id yourself |
+| `validation()` | Validates writes with any Standard Schema | validate the same input twice |
+| `rules()` | Flags unbounded reads, missing tenants, sensitive columns and admin keys in the browser | disable a rule without a reason |
+
+## Order
+
+Hooks run in `use()` order, with two exceptions. `softDelete()` runs first,
+so `timestamps()` and `actor()` stamp a soft delete as the update it
+becomes. `validation()` runs last, so it sees the row after `tenant()`
+filled it.
+
+RLS still decides what a user can read and write. `tenant()` makes queries
+explicit and fills the column; it doesn't replace the policy.
+
+Docs: https://bettersupabase.com/docs/plugins.md

package/skills/better-supabase/references/troubleshooting.md

@@ -0,0 +1,39 @@
+# Troubleshooting
+
+Start with `pnpm better-supabase doctor`. It checks the database, RLS,
+`supabase/config.toml` and env files, and links every finding to its fix.
+
+## By `DbError` kind
+
+Branch on `result.error.kind`, not on the message.
+
+| Kind | Usual cause | Fix |
+| --- | --- | --- |
+| `not_found` | The row doesn't exist, or RLS hides it from this user | Check the policy with an `asUser` test before assuming the row is gone |
+| `unauthorized` | No valid session or token | Get `db` from the adapter for this request |
+| `forbidden` | RLS or a grant rejected the write | Fix the policy or the grant; don't switch to `server.admin()` |
+| `conflict` | Unique violation | Use `upsert`, or return the error to the caller |
+| `foreign_key` | Referenced row missing, or still referenced on delete | Create the parent first, or delete children |
+| `not_null`, `check`, `exclusion` | A constraint rejected the row | Validate input earlier with the `validation()` plugin |
+| `invalid_input` | Postgres couldn't parse a value (bad uuid, enum) | Validate before the call |
+| `validation` | A Standard Schema rejected the input; see `issues` | Show the issues to the user |
+| `invalid_request` | The query can't run over PostgREST (for example a relation filter on `update`) | Read the keys first, or use a database function or `better-supabase/postgres` |
+| `multiple_rows` | `findUnique` or a single-row write matched more than one row | Filter by a unique key |
+| `stale` | `update(..., { expect })` found a newer row | Reload the row and retry |
+| `serialization`, `timeout`, `network`, `rate_limited` | Transient | Retry with backoff, or surface the error |
+| `raised` | A database function raised an exception | Read `message` and `code` from the function |
+
+## Other symptoms
+
+- Types don't match the database: run `pnpm better-supabase gen`, then
+  `gen --check` in CI.
+- A column name is `snake_case` in one place and `camelCase` in another:
+  repositories use the configured casing, `$client` and `$sql` use database
+  names.
+- Every request calls the Auth server: the token is being refreshed outside
+  the proxy. Refresh happens only in the Next.js proxy (`next.proxy`).
+- Tests pass with the service role but fail as a user: that's the RLS policy.
+  Test as users, never with the service role.
+
+Docs: https://bettersupabase.com/docs/cli/doctor.md and
+https://bettersupabase.com/docs/guides/limitations.md

package/skills/better-supabase-api/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: better-supabase-api
+description: Build HTTP APIs, Edge Functions and MCP servers on Supabase with better-supabase adapters. Use when adding a route, REST resource, oRPC procedure, Edge Function, MCP tool, webhook, background job or idempotent endpoint.
+---
+
+# APIs with better-supabase
+
+Every adapter resolves the caller once and hands you `{ auth, db, supabase }`.
+`auth.kind` is `user`, `anon`, `service` or `invalid`.
+
+## Workflow: add an endpoint
+
+1. Pick the adapter for the runtime (table below). Setup code for each is in
+   [references/adapters.md](references/adapters.md).
+2. Decide who may call it with `allow` (see below).
+3. Use `db` from the handler context and return its `Result`, a plain value
+   or a `Response`.
+4. For a table exposed as REST, prefer `bs.resource(...)` over hand-written
+   routes, and regenerate `openapi.json` with `better-supabase openapi emit`.
+5. Add an API test that calls the endpoint as a user and as another tenant
+   (the `better-supabase-testing` skill).
+
+Done when the endpoint rejects callers outside `allow`, errors come back as
+Problem Details (no hand-built error JSON), and `openapi emit --check` passes
+if the project has an OpenAPI file.
+
+## Who gets in
+
+`allow` defaults to `['user']`. Use `['user', 'anon']` for public endpoints
+and `['service']` for machine callers. Rejected callers get a 401 with a
+`WWW-Authenticate` header, or a 403, as Problem Details.
+
+## Adapters
+
+| Where | Setup | Handler |
+| --- | --- | --- |
+| Next.js | `createNext(sb)` in `lib/supabase.server.ts` | `next.route((req, { db }) => ...)`, `next.action({ input: schema }, (input, { db }) => ...)` |
+| Hono | `createHono(sb)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST |
+| oRPC | `createOrpc(sb)`, `base.use(bs.middleware())` | `bs.unwrap(context.db.customers.findMany(...))` |
+| Edge Functions | `createEdge(sb, { cors: true })` | `Deno.serve(bs.handler((req, { db }) => ...))` |
+| MCP | `createMcp(sb, { name, version, resources })` | `.tool({ name, input, run: (args, { db }) => ... })` |
+
+Don't build error JSON by hand; errors become Problem Details.
+
+## REST resources
+
+`defineResource` / `bs.resource(table, { operations, list, input })` gives you
+list, get, create, update and delete, with validation and paging (`{ items, page }`).
+`createOpenApi(sb, { resources })` describes the same routes, and
+`better-supabase openapi emit --check` keeps `openapi.json` in sync.
+
+## Background work (`better-supabase/jobs`, needs `sql add jobs idempotency webhook-inbox`)
+
+- `createJobs(postgres.admin, { queue_name: zodSchema })` runs on Supabase Queues (pgmq): `enqueue` in the request, then `work` or `drain` in a worker. The handler throws to retry. `schedule(name, cron, queue, payload)` uses pg_cron. Queue names are lowercase letters, digits and underscores. With a service-role Supabase client instead of SQL, it uses the `pgmq_public` RPCs (no dedupe or schedules).
+- `createIdempotency(postgres.admin).handle(request, handler)` for POST endpoints that clients retry.
+- `createInbox(postgres.admin, { source, secrets }).receive(request)` for webhooks; `process(handler)` later.
+
+Done when a failing job is retried and then archived after `maxAttempts`,
+and a replayed webhook or POST doesn't run twice.
+
+## Testing
+
+Use `localAuth(secret)` as a resolver and `signTestJwt` / `asUser` from
+`better-supabase/testing`. See the `better-supabase-testing` skill.
+
+Docs: https://bettersupabase.com/docs/frameworks/hono.md (and `next`,
+`orpc`, `edge`, `mcp` under `/docs/frameworks/`).

package/skills/better-supabase-api/references/adapters.md

@@ -0,0 +1,108 @@
+# Adapter setup
+
+Each adapter wraps the same `sb` from `src/lib/supabase.ts`:
+
+```ts title="src/lib/supabase.ts"
+import { defineSupabase } from 'better-supabase';
+
+import { schema } from './supabase/generated';
+
+export type { Functions, Models } from './supabase/generated';
+
+export const sb = defineSupabase(schema);
+```
+
+## Next.js
+
+```ts title="src/lib/supabase.server.ts"
+import { createNext } from 'better-supabase/next';
+
+import { sb } from './supabase';
+
+export const next = createNext(sb);
+```
+
+```ts title="src/proxy.ts"
+import type { NextRequest } from 'next/server';
+
+import { next } from './lib/supabase.server';
+
+export const proxy = (request: NextRequest) => next.proxy(request);
+```
+
+The proxy is the only place that refreshes sessions. Server Components,
+route handlers and actions read the verified token:
+
+```ts
+const { db } = await next.server();
+export const GET = next.route((request, { db }) => db.customers.findMany({ limit: 20 }));
+```
+
+## Hono
+
+```ts title="src/server.ts"
+import { type BetterEnv, createHono } from 'better-supabase/hono';
+import { Hono } from 'hono';
+
+import { type Functions, type Models, sb } from './lib/supabase';
+
+const bs = createHono(sb);
+
+const app = new Hono<BetterEnv<Models, Functions, unknown>>()
+  .onError(bs.onError)
+  .use('/api/*', bs.middleware())
+  .get('/api/me', (c) => c.json({ kind: c.var.auth.kind }))
+  .route('/api/customers', bs.resource('customers', { select: ['id', 'name'] }));
+
+export default app;
+```
+
+## oRPC
+
+```ts title="src/router.ts"
+import { os } from '@orpc/server';
+import { createOrpc, type OrpcRequestContext } from 'better-supabase/orpc';
+
+import { sb } from './lib/supabase';
+
+export const bs = createOrpc(sb);
+const authed = os.$context<OrpcRequestContext>().use(bs.middleware());
+
+export const router = {
+  customers: authed.handler(({ context }) =>
+    bs.unwrap(context.db.customers.findMany({ limit: 20 })),
+  ),
+};
+```
+
+## Edge Functions
+
+```ts title="supabase/functions/api/index.ts"
+import { createEdge } from 'better-supabase/edge';
+
+import { sb } from '../_shared/supabase.ts';
+
+const bs = createEdge(sb, { cors: true });
+
+Deno.serve(
+  bs.resources({ customers: { select: ['id', 'name'] } }, { basePath: '/api' }),
+);
+```
+
+## MCP
+
+```ts title="supabase/functions/mcp/index.ts"
+import { createMcp } from 'better-supabase/mcp';
+
+import { sb } from '../_shared/supabase.ts';
+
+const mcp = createMcp(sb, {
+  name: 'crm',
+  version: '0.1.0',
+  resources: { customers: { select: ['id', 'name'] } },
+});
+
+Deno.serve(mcp.fetch);
+```
+
+Tools run as the calling user, so RLS applies to every tool call.

package/skills/better-supabase-testing/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: better-supabase-testing
+description: Test Supabase RLS policies, APIs and SQL against the local stack with better-supabase/testing, typed seeds and pgTAP. Use when writing or fixing tests that touch the database, policies or auth.
+---
+
+# Testing with better-supabase
+
+Test against the local stack (`supabase start`) as real users. Don't mock
+supabase-js, and don't use the service role for anything a user does.
+
+## Workflow: test a table or policy
+
+1. Start the stack (`supabase start`) and write `.env.local` with
+   `better-supabase env`.
+2. Add the rows the test needs to `supabase/seed.ts`, including one row
+   owned by another tenant, then `supabase db reset`.
+3. Write the RLS test with `asUser` for each role that matters.
+4. Assert both directions: the user sees and changes their own rows, and
+   another tenant's rows come back as `not_found` or `forbidden`.
+5. Run `supabase test db` if the project has pgTAP tests.
+
+Done when the test fails after you drop or loosen the policy, and passes
+again once you restore it.
+
+## Setup
+
+- `better-supabase env` writes the URL and keys to `.env.local`; load it in the test setup.
+- Typed fixtures live in `supabase/seed.ts`:
+
+```ts
+import { defineSeed } from 'better-supabase/testing';
+import { sb } from '../src/lib/supabase.ts';
+
+export const seed = defineSeed(sb, {
+  organizations: { acme: { id: ACME, name: 'Acme' } },
+  customers: { first: { id: FIRST, organizationId: ACME, name: 'First' } },
+});
+```
+
+  `better-supabase seed` renders them to SQL for `supabase db reset`, and
+  tests import the same rows (`seed.rows.customers.first.id`).
+
+## RLS tests
+
+```ts
+const alice = await asUser(sb, { sub: aliceId, org_id: ACME }, { postgres });
+expect(await alice.db.customers.count().orThrow()).toBe(1);
+expect(await alice.db.customers.findById(OTHER_ORG_CUSTOMER)).toMatchObject({ ok: false });
+```
+
+- Check both directions: the user sees their own rows and never sees another tenant's.
+- `alice.sql` runs the same checks over direct Postgres.
+- Assert on `result.error.kind` (`not_found`, `forbidden`, `conflict`, `validation`), not on messages.
+
+## API tests
+
+Pass `auth: { resolvers: [localAuth(LOCAL_JWT_SECRET)] }` to the adapter and
+send `authorization: Bearer ${alice.token}`.
+
+## pgTAP
+
+`better-supabase sql add pgtap` installs `tests.create_user`,
+`tests.authenticate_as(user, claims)`, `tests.clear_authentication()` and
+`tests.rls_enabled('public')` for `supabase test db`. Put
+`select tests.rls_enabled('public');` in a test so tables without RLS fail CI.

package/index.js

@@ -1 +0,0 @@
-module.exports = {};