better-supabase 0.2.0 → 0.4.0

package/skills/better-supabase/SKILL.md

@@ -1,23 +1,39 @@
 ---
 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.
+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, when a Supabase type is out of date, or after upgrading better-supabase.
 ---
 
 # better-supabase
 
-The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
+The data layer is `betterSupabase = defineSupabase(schema)` in `src/lib/supabase/index.ts`.
 `schema` comes from the generated module (`config.output`, usually
 `src/lib/supabase/generated.ts`). Never edit generated files.
 
+The `better-supabase` command ships in the `better-supabase` package, so
+`pnpm better-supabase <command>` works once the package is installed. There
+is no separate CLI package to add.
+
 ## 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`.
+1. Write the migration: edit `supabase/schemas/*.sql`, then run
+   `supabase db schema declarative sync -f <name>` (pg-delta;
+   `supabase db diff -f <name>` when `config.toml` has no
+   `[experimental.pgdelta] enabled = true`), or `supabase migration new` for
+   data and role settings.
+2. For a new table in an exposed schema, in the same file: `enable row level
+security`, a policy per role and command the app uses, and an index on
+   every column a policy filters by. Write tenant checks as
+   `organization_id in (select better_supabase.member_org_ids())`, which
+   Postgres runs once per statement, not `has_org_role(organization_id)`,
+   which runs once per row. List the table in `expose` in
+   `better-supabase.config.ts` and run `pnpm better-supabase sql add grants`:
+   new tables get no Data API grants on their own.
+3. Apply it with `supabase db reset` (or `supabase migration up`).
+4. Run `pnpm better-supabase gen`, then fix the type errors it surfaces.
+5. Run `pnpm better-supabase doctor` and fix every error it reports (RLS off,
+   missing policies, missing grants, unindexed foreign keys, drift).
+6. Commit the generated files. CI runs `better-supabase gen --check`, which
+   prints a diff of each stale file.
 
 Done when `gen --check` and `doctor` exit 0 and the project typechecks.
 
@@ -35,23 +51,48 @@ 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.
 
+## Workflow: after upgrading better-supabase
+
+1. Rerun `pnpm better-supabase sql add` with the kit modules the project
+   installed, so their SQL gets the release's fixes, then write a migration
+   from the changed files.
+2. Run `pnpm better-supabase gen` and commit the result. Since 0.3, a
+   composite foreign key such as `(customer_id, organization_id)` is named
+   after the remaining column (`customer`); set `tables.<name>.relations` in
+   the config to keep an old relation name.
+3. Run `pnpm better-supabase skills install --check` and reinstall the skills
+   when it reports them stale.
+4. Read the release's breaking changes in
+   https://github.com/ScaleDockHQ/better-supabase/blob/main/CHANGELOG.md
+   (guides live under https://bettersupabase.com/docs/migration). For 0.3: time values are
+   `Temporal` (see below), `--db-url` is gone, `doctor --format json` is
+   `doctor --json`, `BetterResultShape` is `BetterResultValue`, and an
+   exhaustive `switch` over the `invalid` auth reason needs an `'actor'` case.
+
+Done when `gen --check`, `doctor` and the typecheck pass.
+
 ## 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()`
+Name the definition `betterSupabase` (in `lib/supabase/index.ts`) and every runtime instance `bs` (`lib/supabase/server.ts`, `lib/supabase/client.ts`, or the Hono, oRPC or Edge Function entry).
+
+- Next.js: `const { db } = await bs.context()`, `bs.route(...)`, `bs.action(...)`
+- Next.js Cache Components: keep layouts synchronous; read `bs.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>()`
+- Browser: `bs.db`, or the hooks from `createHooks<typeof bs>()`
+
+For who the caller is (sessions, claims, OAuth clients, agents, scopes), use
+the `better-supabase-auth` skill.
 
 ## 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' },
+  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
@@ -59,18 +100,33 @@ 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.
+- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, and `queryRaw` on the `better-supabase/postgres` clients) use database names.
 - Writes: `create`, `createMany`, `update(id, patch)`, `updateMany`, `upsert`, `delete`.
+- Page lists with a cursor: `paginate({ after: null, size: 25, orderBy })`, then pass `nextCursor` back as `after` with the same `orderBy` and `where`. Use `page` numbers only when users jump to a page and need a total.
 - 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.
+- Server-only admin access: `bs.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.
 
+## Time values
+
+- With `codecs: { timestamptz: 'instant' }` in the config, `timestamptz` columns decode to `Temporal.Instant` and `timestamp` columns to `Temporal.PlainDateTime`, with microseconds. Without the codec they stay ISO strings.
+- `now` options, job and webhook timestamps and `bucket.sweep({ olderThan })` take `Temporal` values. Auth's `now` stays in epoch milliseconds.
+- On Node 24, Safari and other runtimes without `Temporal`, add `temporal-polyfill` and `import "temporal-polyfill/global"` once at startup. Without it, calls that need `Temporal` return an `unexpected` `DbError` that names the import.
+- Use TypeScript 6 or 7; 5.9 has no Temporal lib.
+
+## CLI in scripts and CI
+
+- No command takes a connection string as an argument. Set `$DATABASE_URL` or `source.dbUrl`, or pipe it in with `--db-url-stdin`.
+- `--json` prints one JSON document on stdout: the result, or Problem Details with a `code` on failure. `--yes` and `CI` turn prompts off.
+- Exit codes: 0 success, 1 a failure or finding (`--check` drift, doctor errors), 2 a usage, config or environment problem. Each error code is listed at https://bettersupabase.com/docs/cli/errors.
+
 ## 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`.
+- Don't convert `Temporal` values to `Date` to compare them; use `.equals()` or `Temporal.Instant.compare`.
 
 ## When something fails
 
@@ -82,3 +138,6 @@ See [references/troubleshooting.md](references/troubleshooting.md) for each
 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.
+
+For Supabase itself (Auth, Storage, RLS, Postgres performance), install
+Supabase's skills next to these: `npx skills add supabase/agent-skills`.

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

@@ -1,17 +1,17 @@
 # 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';
+```ts title="src/lib/supabase/index.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';
+import { schema } from "./generated.ts";
+import { validators } from "./generated.zod.ts";
 
-export const sb = defineSupabase(schema)
+export const betterSupabase = defineSupabase(schema)
   .use(timestamps())
   .use(softDelete())
   .use(tenant())
@@ -34,14 +34,14 @@ plugins: {
 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 |
+| 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
 
@@ -57,9 +57,8 @@ The tenant comes from the verified `tenant_id` claim (renamed with
 `claims.tenant` in `better-supabase.config.ts`), then `app_metadata.tenant_id`.
 Never read it from `user_metadata`, a URL or a request body. When the project
 has a `permdock.config.ts`, PermDock's hook writes that claim and the
-memberships; don't run `sql add tenant` there or call `membership_claims()`
-from a hook. `sql add entitlements` is fine: `features` is not a PermDock
-claim, but PermDock's hook doesn't write it yet, so read entitlements from the
-database on the server instead of `hasEntitlement(session, ...)`.
+memberships: don't run `sql add tenant`, and follow the PermDock reference of
+the `better-supabase-auth` skill
+(https://bettersupabase.com/docs/auth/permdock.md).
 
 Docs: https://bettersupabase.com/docs/plugins.md

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

@@ -7,33 +7,53 @@ Start with `pnpm better-supabase doctor`. It checks the database, RLS,
 
 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 |
+| 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 `bs.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                                   |
+| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Install `temporal-polyfill` and import `temporal-polyfill/global` at startup  |
+
+## By error `code`
+
+| Code                             | Meaning                                                                    | Fix                                                                                        |
+| -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CLAIMS_INVALID` (unauthorized)  | The token verified but failed the `betterSupabase.claims(schema)` schema   | Fix the access token hook or loosen the schema; the error names the failing paths          |
+| `SESSION_REVOKED` (unauthorized) | `checkSession` found the session gone (signed out, or ended by an admin)   | Expected for irreversible actions; ask the user to sign in again                           |
+| `INSUFFICIENT_SCOPE` (forbidden) | A delegated token (OAuth client or agent) lacks a scope the route requires | The 403 carries an `insufficient_scope` challenge; the client asks the user for that scope |
 
 ## 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.
+  repositories use the configured casing, `$client` and `queryRaw` 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`).
+  the proxy. Refresh happens only in the Next.js proxy (`bs.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.
+- A relation name changed after `gen`: a composite foreign key that repeats a
+  column on both sides is named after the remaining column. Set
+  `tables.<name>.relations` in the config to keep the old name.
+- The CLI exits with 2: the command line, the config or an environment
+  variable needs a change. Rerun with `--json` to get the error `code`, and
+  look it up at https://bettersupabase.com/docs/cli/errors.
+- `--db-url` is rejected: set `$DATABASE_URL` or pipe the URL in with
+  `--db-url-stdin`.
+- Two different `Temporal.Instant` values compare equal in `toEqual`: compare
+  with `.equals()` or register an equality tester (the
+  `better-supabase-testing` skill).
 
 Docs: https://bettersupabase.com/docs/cli/doctor.md and
 https://bettersupabase.com/docs/guides/limitations.md

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

@@ -1,28 +1,32 @@
 ---
 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.
+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, OAuth or agent scopes, webhook, background job, cleanup cron 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`.
+`auth.kind` is `user`, `anon`, `service` or `invalid`. For sessions, claims
+and the OAuth client or agent behind a token, see the `better-supabase-auth`
+skill.
 
 ## 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).
+2. Decide who may call it with `allow`, and which scopes a delegated token
+   needs with `scopes` (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).
+5. Add an API test that calls the endpoint as a user and as another tenant,
+   and with a delegated token that lacks the scope (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.
+Done when the endpoint rejects callers outside `allow` and tokens without its
+`scopes`, 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
 
@@ -30,15 +34,36 @@ if the project has an OpenAPI file.
 and `['service']` for machine callers. Rejected callers get a 401 with a
 `WWW-Authenticate` header, or a 403, as Problem Details.
 
+`scopes` limits what a delegated token may do: a token from the Supabase
+OAuth server (`client_id` and `scope`) or one exchanged for an agent (an
+RFC 8693 `act` chain). The guard options of `bs.route`, `bs.action`,
+`bs.handler` (edge) and `bs.middleware` (Hono, oRPC) take it, next to
+`allow`:
+
+```ts
+export const GET = bs.route(
+  (request, { db }) => db.customers.findMany({ limit: 20 }),
+  { scopes: ["customers:read"] },
+);
+```
+
+With `.claims(schema)` on the definition, `auth.claims` is typed in every
+adapter (`c.var.auth`, `context.auth`, the edge handler's `auth`, MCP's
+`ctx.auth`). Read roles from it; don't parse the claims again.
+
+A token without the scope gets a 403 with an `insufficient_scope`
+challenge. The user's own session holds no `client_id` or `act`, so `scopes`
+never limits it. RLS still decides the rows: the token's `sub` is the user.
+
 ## 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 }) => ... })` |
+| Where          | Setup                                                           | Handler                                                                                  |
+| -------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Next.js        | `createNext(betterSupabase)` in `lib/supabase/server.ts`        | `bs.route((req, { db }) => ...)`, `bs.action({ input: schema }, (input, { db }) => ...)` |
+| Hono           | `createHono(betterSupabase)`, `.use('/api/*', bs.middleware())` | `c.var.db`; `bs.resource('customers', {...})` for REST                                   |
+| oRPC           | `createOrpc(betterSupabase)`, `base.use(bs.middleware())`       | `bs.unwrap(context.db.customers.findMany(...))`                                          |
+| Edge Functions | `createEdge(betterSupabase, { cors: true })`                    | `Deno.serve(bs.handler((req, { db }) => ...))`                                           |
+| MCP            | `createMcp(betterSupabase, { name, version, resources })`       | `.tool({ name, input, run: (args, { db }) => ... })`                                     |
 
 Don't build error JSON by hand; errors become Problem Details.
 
@@ -46,17 +71,38 @@ Don't build error JSON by hand; errors become Problem Details.
 
 `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
+`createOpenApi(betterSupabase, { resources })` describes the same routes, and
 `better-supabase openapi emit --check` keeps `openapi.json` in sync.
 
+Pass `pagination: "cursor"` to a resource, `defineListQuery` or an MCP table
+for lists that clients read page by page: the list takes `after` instead of
+`page`, returns `nextCursor` and `hasMore`, and `size` stays capped by
+`maxPageSize`. The OpenAPI document and the JSON Schema describe the cursor.
+
+## MCP servers
+
+- Tools run as the calling user, so RLS applies to every call.
+- `authorize(ctx, tool, args)` refuses a call (`{ allowed: false, reason, scopes }`; with `scopes` it is a 403 `insufficient_scope`). `visible(ctx, tool)` hides tools from `tools/list`. Put a permission or a label in a tool's `meta`; clients never see it.
+- `scopes` on `createMcp` only advertises scopes. Refuse calls in `authorize`, reading `toSession(ctx.auth).delegation?.scopes`.
+- Set `allowedOrigins` and `allowedHosts` (every host the server answers on, previews and local included) against DNS rebinding, and `resourceDocumentation` to a page that explains how to connect.
+
 ## 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.
+- Times are `Temporal.Instant`: `EnqueueOptions.runAt`, `Job.enqueuedAt`, `Job.visibleUntil`, `InboxMessage.receivedAt` and webhook timestamps.
+- Schedule cleanup with pg_cron at a quiet hour: `better_supabase.purge_job_archive('<queue>')`, `purge_webhooks()`, `purge_audit_log()` and `purge_idempotency_keys()`. Only `service_role` can execute them.
 
 Done when a failing job is retried and then archived after `maxAttempts`,
-and a replayed webhook or POST doesn't run twice.
+a replayed webhook or POST doesn't run twice, and each kit table has a purge
+schedule.
+
+## Direct Postgres on the server
+
+- `createPostgres()` opens a pool; `createPostgres({ pool })` runs on an existing `pg.Pool`. `asUser` and `anon` transactions get Supabase's role timeouts (8 s and 3 s); `statementTimeout` takes a number or `{ admin, authenticated, anon }`.
+- `createMany` and `upsertMany` split inserts past 65,535 bind parameters into several statements in one transaction, so large batches don't need manual chunking.
+- In serverless functions, connect through the transaction pooler (port 6543), not a direct connection.
 
 ## Testing
 
@@ -64,4 +110,6 @@ Sign tokens with `signLocalJwt` or `asUser` from `better-supabase/testing`;
 the adapter verifies them against the local JWKS. See the `better-supabase-testing` skill.
 
 Docs: https://bettersupabase.com/docs/frameworks/hono.md (and `next`,
-`orpc`, `edge`, `mcp` under `/docs/frameworks/`).
+`orpc`, `edge`, `mcp` under `/docs/frameworks/`),
+https://bettersupabase.com/docs/kits/jobs.md and
+https://bettersupabase.com/docs/auth/postgres.md.

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

@@ -1,58 +1,64 @@
 # Adapter setup
 
-Each adapter wraps the same `sb` from `src/lib/supabase.ts`:
+Each adapter wraps the same `betterSupabase` from `src/lib/supabase/index.ts`:
 
-```ts title="src/lib/supabase.ts"
-import { defineSupabase } from 'better-supabase';
+```ts title="src/lib/supabase/index.ts"
+import { defineSupabase } from "better-supabase";
 
-import { schema } from './supabase/generated';
+import { schema } from "./generated";
 
-export type { Functions, Models } from './supabase/generated';
+export type { Functions, Models } from "./generated";
 
-export const sb = defineSupabase(schema);
+export const betterSupabase = defineSupabase(schema);
 ```
 
 ## Next.js
 
-```ts title="src/lib/supabase.server.ts"
-import { createNext } from 'better-supabase/next';
+```ts title="src/lib/supabase/server.ts"
+import { createNext } from "better-supabase/next";
 
-import { sb } from './supabase';
+import { betterSupabase } from "./index";
 
-export const next = createNext(sb);
+export const bs = createNext(betterSupabase);
 ```
 
 ```ts title="src/proxy.ts"
-import type { NextRequest } from 'next/server';
+import type { NextRequest } from "next/server";
 
-import { next } from './lib/supabase.server';
+import { bs } from "./lib/supabase/server";
 
-export const proxy = (request: NextRequest) => next.proxy(request);
+export const proxy = (request: NextRequest) => bs.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 }));
+const { db } = await bs.context();
+export const GET = bs.route(
+  (request, { db }) => db.customers.findMany({ limit: 20 }),
+  { scopes: ["customers:read"] }, // only limits OAuth clients and agents
+);
 ```
 
 ## Hono
 
 ```ts title="src/server.ts"
-import { type BetterEnv, createHono } from 'better-supabase/hono';
-import { Hono } from 'hono';
+import { type HonoEnv, createHono } from "better-supabase/hono";
+import { Hono } from "hono";
 
-import { type Functions, type Models, sb } from './lib/supabase';
+import { type Functions, type Models, betterSupabase } from "./lib/supabase";
 
-const bs = createHono(sb);
+const bs = createHono(betterSupabase);
 
-const app = new Hono<BetterEnv<Models, Functions, unknown>>()
+const app = new Hono<HonoEnv<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'] }));
+  .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;
 ```
@@ -60,12 +66,12 @@ export default app;
 ## oRPC
 
 ```ts title="src/router.ts"
-import { os } from '@orpc/server';
-import { createOrpc, type OrpcRequestContext } from 'better-supabase/orpc';
+import { os } from "@orpc/server";
+import { createOrpc, type OrpcRequestContext } from "better-supabase/orpc";
 
-import { sb } from './lib/supabase';
+import { betterSupabase } from "./lib/supabase";
 
-export const bs = createOrpc(sb);
+export const bs = createOrpc(betterSupabase);
 const authed = os.$context<OrpcRequestContext>().use(bs.middleware());
 
 export const router = {
@@ -78,31 +84,48 @@ export const router = {
 ## Edge Functions
 
 ```ts title="supabase/functions/api/index.ts"
-import { createEdge } from 'better-supabase/edge';
+import { createEdge } from "better-supabase/edge";
 
-import { sb } from '../_shared/supabase.ts';
+import { betterSupabase } from "../_shared/supabase.ts";
 
-const bs = createEdge(sb, { cors: true });
+const bs = createEdge(betterSupabase, { cors: true });
 
 Deno.serve(
-  bs.resources({ customers: { select: ['id', 'name'] } }, { basePath: '/api' }),
+  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'] } },
+import { createMcp } from "better-supabase/mcp";
+import { toSession } from "better-supabase/server";
+
+import { betterSupabase } from "../_shared/supabase.ts";
+
+const bs = createMcp(betterSupabase, {
+  name: "crm",
+  version: "0.1.0",
+  scopes: ["openid", "crm.read"],
+  allowedOrigins: ["https://claude.ai"],
+  allowedHosts: ["crm.example.com", "localhost"],
+  resourceDocumentation: "https://crm.example.com/docs/mcp",
+  resources: {
+    customers: { select: ["id", "name"], pagination: "cursor" },
+  },
+  authorize: (ctx) => {
+    const session = toSession(ctx.auth);
+    const granted =
+      session.kind === "user" ? session.delegation?.scopes : undefined;
+    return !granted || granted.includes("crm.read")
+      ? { allowed: true }
+      : { allowed: false, reason: "Needs crm.read", scopes: ["crm.read"] };
+  },
 });
 
-Deno.serve(mcp.fetch);
+Deno.serve(bs.fetch);
 ```
 
-Tools run as the calling user, so RLS applies to every tool call.
+Tools run as the calling user, so RLS applies to every tool call. `scopes`
+on `createMcp` only advertises scopes; `authorize` refuses the call. A
+`delegation` that is unset means the user's own token, which no scope limits.