better-supabase 0.5.1 → 0.6.0

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

@@ -82,6 +82,25 @@ export const router = {
 };
 ```
 
+For a contract from `@orpc/contract`, use the same middleware on the
+implementer and serve it with `OpenAPIHandler`, so errors keep their HTTP
+status (RLS denials answer 403):
+
+```ts title="src/server.ts"
+const os = implement(contract)
+  .$context<OrpcRequestContext>()
+  .use(bs.middleware());
+const router = os.router({
+  customers: {
+    get: os.customers.get.handler(({ context, input }) =>
+      bs.unwrap(context.db.customers.findById(input.id)),
+    ),
+  },
+});
+const handle = bs.fetchHandler(new OpenAPIHandler(router), { prefix: "/api" });
+const app = new Hono().all("/api/*", (c) => handle(c.req.raw));
+```
+
 ## Edge Functions
 
 ```ts title="supabase/functions/api/index.ts"
@@ -96,6 +115,152 @@ Deno.serve(
 );
 ```
 
+## Middleware entries and bridges
+
+`withBetterSupabase(server, { allow })` from `better-supabase/server` is one
+`@supabase/middleware` entry: it resolves the caller, guards, and contributes
+`bs`, `db`, `sql`, `jwtClaims`, `userClaims` and `authMode`. Put
+`withPostgresClient` or `withCors` next to it, then run the array with the
+bridge for the framework:
+
+```ts title="src/hooks.server.ts"
+import { createServer, withBetterSupabase } from "better-supabase/server";
+import { toSvelteKit } from "better-supabase/sveltekit";
+
+import { betterSupabase } from "$lib/supabase";
+
+export const handle = toSvelteKit([
+  withBetterSupabase(createServer(betterSupabase), {
+    refresh: true,
+    allow: ["user", "anon"],
+  }),
+]);
+```
+
+| Framework           | Bridge                                             | Where the keys land                                 |
+| ------------------- | -------------------------------------------------- | --------------------------------------------------- |
+| Hono                | `toHono(entries)` from `better-supabase/hono`      | `c.var`                                             |
+| Edge, Deno, Workers | `toEdge(entries, handler)` from `/edge`            | the handler's `ctx`                                 |
+| oRPC                | `toOrpc(entries, rpcHandler)` from `/orpc`         | the initial `context`                               |
+| Expo API routes     | `toExpo(entries, handler)` from `/expo`            | the handler's `ctx`                                 |
+| TanStack Start      | `toTanStackStart(entries)` from `/tanstack-start`  | middleware `context`                                |
+| SvelteKit           | `toSvelteKit(entries)` from `/sveltekit`           | `event.locals`                                      |
+| React Router        | `toReactRouter(entries, key)` from `/react-router` | `context.get(key)`                                  |
+| H3, Nitro, Nuxt     | `toH3(entries)` from `/h3`                         | `event.context`                                     |
+| Elysia              | `toElysia(entries)` from `/elysia`                 | `.derive(({ request }) => bridge.context(request))` |
+| Nitro 2, Nuxt       | `toH3V1(entries)` from `/h3/v1`                    | `event.context`                                     |
+| Node `http`         | `toNodeHandler(entries, handler)` from `/node`     | the handler's `ctx`                                 |
+| Express             | `toExpress(entries)` from `/node`                  | `res.locals`                                        |
+| Fastify             | `toFastify(entries)` from `/node`                  | `request.locals`                                    |
+| Koa                 | `toKoa(entries)` from `/node`                      | `ctx.state`                                         |
+| NestJS              | `toNestMiddleware(entries)` from `/nestjs`         | `@Ctx("db")` in a controller                        |
+
+Don't use the `@supabase/server/adapters/*` adapters: they are deprecated and
+removed on 2026-12-01. Don't put `withSupabase` and `withBetterSupabase` in
+one array; they write the same keys and the type checker rejects it. Set
+`refresh: true` only on the bridge that runs once per request with a response
+(request middleware, the `handle` hook), never in Server Components.
+
+## Node, Express, Fastify and Koa
+
+`better-supabase/node` types each framework structurally, so it adds no
+dependency. Each bridge has a guard and an error handler that answers
+`.orThrow()` failures with Problem Details:
+
+```ts title="app.ts"
+import express from "express";
+import { guard, problemErrorHandler, toExpress } from "better-supabase/node";
+import { withBetterSupabase } from "better-supabase/server";
+
+import { bs } from "./lib/server";
+
+const app = express();
+app.use(
+  toExpress([
+    withBetterSupabase(bs, { refresh: true, allow: ["user", "anon"] }),
+  ]),
+);
+app.get("/admin/members", guard({ roles: ["admin"] }), async (req, res) => {
+  res.json(await res.locals.db.members.findMany().orThrow());
+});
+app.use(problemErrorHandler());
+```
+
+| Framework   | Bridge                              | Guard                                   | Errors                  |
+| ----------- | ----------------------------------- | --------------------------------------- | ----------------------- |
+| `node:http` | `toNodeHandler(entries, handler)`   | `allow` on `withBetterSupabase`         | the handler's `Result`  |
+| Express     | `toExpress(entries)`                | `guard(options)` per route              | `problemErrorHandler()` |
+| Fastify     | `toFastify(entries)` in `onRequest` | `fastifyGuard(options)` as `preHandler` | `problemErrorHandler()` |
+| Koa         | `toKoa(entries)`                    | `koaGuard(options)`                     | built into `toKoa`      |
+
+For Fastify, call `app.decorateRequest("locals", null)` first. Type
+Express's `res.locals` by extending `Express.Locals` with
+`BetterSupabaseContributions<Models, Functions, unknown>` from
+`better-supabase/server`.
+
+## NestJS
+
+```ts title="src/app.module.ts"
+consumer
+  .apply(toNestMiddleware([withBetterSupabase(bs, { allow: ["user"] })]))
+  .forRoutes("*");
+```
+
+```ts title="src/notes.controller.ts"
+import { Controller, Get, UseFilters, UseGuards } from "@nestjs/common";
+import { Ctx, guard, problemFilter } from "better-supabase/nestjs";
+
+@Controller("notes")
+@UseFilters(problemFilter())
+export class NotesController {
+  @Get()
+  @UseGuards(guard({ roles: ["admin"] }))
+  list(@Ctx("db") db: Db) {
+    return db.notes.findMany({ select: ["id", "title"] }).orThrow();
+  }
+}
+```
+
+## Astro and SolidStart
+
+```ts title="src/lib/server.ts"
+import { createAstro } from "better-supabase/astro";
+
+export const bs = createAstro(betterSupabase, { signIn: "/sign-in" });
+// src/middleware.ts: export const onRequest = bs.onRequest;
+```
+
+In a page, `const refused = await bs.guard(Astro, { roles: ["admin"] })`
+returns the refusal to send, and `bs.locals(Astro).db` is the caller's
+`db`. Wrap an Action's handler with `bs.action({ input, requireTenant }, fn)`.
+`createImageService({ url })` serves Storage images through Astro's image
+service.
+
+```ts title="src/lib/server.ts"
+import { createSolidStart } from "better-supabase/solid-start";
+import { getRequestEvent } from "solid-js/web";
+
+export const bs = createSolidStart(betterSupabase, {
+  getRequestEvent,
+  signIn: "/sign-in",
+});
+// src/middleware.ts: export default createMiddleware(bs.middleware);
+```
+
+In a `"use server"` query, `const { db } = await bs.require()`; for forms,
+`bs.action({ input }, (input, { db }) => ...)`.
+
+## Nuxt and Nitro 2
+
+Export the entries from `server/better-supabase.ts`, register the module
+with `modules: ["better-supabase/nuxt"]` and
+`betterSupabase: { server: "~~/server/better-supabase" }` in
+`nuxt.config.ts`, or run them yourself with
+`defineEventHandler(toH3V1(entries))` from `better-supabase/h3/v1`. Guard a
+route with `(await guard({ roles: ["admin"] })(event)) ?? ...`, and turn
+`.orThrow()` failures into Problem Details with `problemOnError()`. On H3 2
+and Nitro 3, use the same helpers from `better-supabase/h3`.
+
 ## MCP
 
 ```ts title="supabase/functions/mcp/index.ts"
@@ -132,3 +297,45 @@ Tools run as the calling user, so RLS applies to every tool call.
 tokens that lack one, and `authorize` refuses a single call. The session comes
 from the `Authorization` header only, never from a cookie. A
 `delegation` that is unset means the user's own token, which no scope limits.
+
+On Supabase Edge Functions, set `[functions.mcp] verify_jwt = false` in
+`supabase/config.toml`; the gateway's own 401 has no OAuth challenge. The
+server then derives its public URL from `SUPABASE_FUNCTION_SLUG` and the
+gateway's `X-Forwarded-*` headers and serves the metadata at
+`/functions/v1/mcp/oauth-protected-resource`, so leave `resource` unset there.
+CORS preflights are answered by default (`cors: false` turns them off).
+To keep a Supabase library MCP block's pipeline instead, add
+`withBetterDb(betterSupabase)()` from `better-supabase/server` after its
+`withSupabase` entry for `ctx.db`.
+
+### MCP on the official SDK
+
+```ts title="src/mcp.ts"
+import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
+import { createMcpAuth, withBetterSupabaseMcp } from "better-supabase/mcp/sdk";
+
+import { betterSupabase } from "./lib/supabase/schema";
+
+const auth = createMcpAuth(betterSupabase, {
+  resource: "https://crm.example.com/mcp",
+  advertisedScopes: ["crm.read"],
+});
+
+const handler = createMcpHandler(() => {
+  const server = withBetterSupabaseMcp(
+    new McpServer({ name: "crm", version: "0.1.0" }),
+    auth,
+  );
+  server.registerTool("count_customers", {}, async ({ db }) => {
+    const count = await db.customers.count().orThrow();
+    return { content: [{ type: "text", text: String(count) }] };
+  });
+  return server;
+});
+
+export default { fetch: auth.serve(handler) };
+```
+
+`auth.serve` answers the RFC 9728 metadata and the 401 challenge, then passes
+the verified `authInfo` to the SDK handler. `auth.verifier` plugs into the
+SDK's own `requireBearerAuth` when you keep your own routing.

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

@@ -0,0 +1,125 @@
+# AI blocks, agents and SDK adapters
+
+The AI blocks store data and never import an AI SDK. The SDK code lives in
+the adapter subpaths (`better-supabase/ai-sdk/*`, `/chat-sdk`, `/eve`) or in
+the app. Each block takes `transport` (calls as the user) and, where it
+writes on the user's behalf, `service` (calls as the service role). Use
+`rpcTransport(supabase)` over PostgREST or `sqlTransport(postgres.asUser(claims))`
+over direct Postgres. Its docs page is
+`https://bettersupabase.com/docs/blocks/<name>.md`.
+
+## Knowledge and memory
+
+```bash
+pnpm better-supabase sql add knowledge memory   # adds tenant, access and vector-search
+```
+
+```ts
+import { embedWith } from "better-supabase/ai-sdk/embeddings";
+import {
+  createKnowledge,
+  rpcTransport,
+} from "better-supabase/blocks/knowledge";
+import { createMemory } from "better-supabase/blocks/memory";
+
+const embedder = embedWith("openai/text-embedding-3-small");
+const knowledge = createKnowledge({
+  transport: rpcTransport(supabase),
+  service: rpcTransport(admin),
+  embedder,
+});
+const memory = createMemory({
+  transport: rpcTransport(supabase),
+  service: rpcTransport(admin),
+  embedder,
+});
+```
+
+- Ingest with `knowledge.ingest.text(organizationId, { title, text, source })`
+  and search with `knowledge.search(organizationId, query, { scopes, k })`.
+  A scope is `organization`, `user`, `agent` or `chat` (with an `id`).
+- Give the model the knowledge with `searchTool(knowledge, organizationId, { scopes, onHits })`
+  and cite with `toSourceParts(hits)`; rerank with `rerankWith(model, { topN })`.
+  `supabaseEmbed` uses Supabase's built-in model instead of a gateway model.
+- Memory has files (`memory.run(organizationId, { command, path, ... })`),
+  archival facts (`memory.archival.save` and `.search`) and versioned
+  documents (`memory.documents.read` and `.write` with `expectedVersion`).
+- In a chat route, from `better-supabase/ai-sdk/memory`: `withMemory(instructions, memory, organizationId)`
+  adds the core memory, `memoryTool` and `recallTool` are the tools, and
+  `anthropicMemory(anthropic.tools, memory, organizationId)` backs
+  Anthropic's built-in memory tool. Run `extractMemories({ model, memory })`
+  as a job handler with a service-role `memory`.
+
+## Agents, connectors and scheduled tasks
+
+```bash
+pnpm better-supabase sql add agents connectors ai-tasks
+```
+
+- `createAgents({ transport })` stores assistants: `agents.create(organizationId, { slug, name, instructions, tools, knowledgeScopes })`,
+  then `agents.publish(id, "organization")`.
+- Run a stored agent with `createAgentRuntime({ agent, model, tools, policies, knowledge, instructions })`
+  from `better-supabase/ai-sdk/agents`, then `runtime.stream({ messages })`.
+  Wrap the model with `moderationMiddleware({ chats, organizationId, chatId, check })`
+  to check input and output; a blocked turn throws `ModerationBlockedError`.
+- `createConnectors({ transport, service, credentials })` stores MCP servers
+  per organization. OAuth servers get one grant per user behind a
+  `credential_ref`. From `better-supabase/ai-sdk/mcp`: `authorizeConnector`
+  starts the OAuth flow, `completeConnector` finishes it on the callback
+  route, and `connectAll(servers, { connectors, userId, vault, credentials, chatKey })`
+  returns `{ tools, skipped, close }`. Call `close()` in a `finally`.
+  Review changed tool lists with `connectors.fingerprints.check`, `.approve`
+  and `.reject`.
+- `createAiTasks({ transport, service, run })` stores scheduled prompts with
+  a `cron` and a `timezone`. `tick()` queues the due runs (handle them with
+  `runJob()` on the `ai_task_run` queue when the `jobs` module is
+  installed); without jobs, call `drain()` from a cron route.
+
+## Files, cache and batches
+
+- `aiFileDownload(files)` as `experimental_download` in `streamText` reads
+  Storage file parts; `saveGeneratedFiles(files, images, { organizationId, ownerId, chatId })`
+  stores generated images; `providerFile(files, fileId, provider, upload)`
+  caches a provider's file id. All from `better-supabase/ai-sdk/files`.
+- `aiBatches({ providers })` from `better-supabase/ai-sdk/batches` starts a
+  batch per tenant with `.start({ organizationId, userId }, { requests })`,
+  polls it with the `pollJob()` handler and pages results with `.results(batchId, { after, limit })`.
+
+## eve (Node only)
+
+```bash
+pnpm add eve @workflow/world @workflow/world-postgres pg
+pnpm better-supabase sql add workflow-sdk-world ai-chat memory knowledge credentials inbox
+```
+
+Set `experimental.workflow.world` to `"better-supabase/workflow-sdk/world"`
+in `defineAgent`, then use the helpers from `better-supabase/eve`:
+
+| Helper                    | Where it goes                          | What it does                                            |
+| ------------------------- | -------------------------------------- | ------------------------------------------------------- |
+| `supabaseAuth({ env })`   | `eveChannel({ auth: [...] })`          | signs eve routes in with the Supabase session           |
+| `credentialAuth(...)`     | a connection's `auth`                  | resolves the connection's token from a `credential_ref` |
+| `supabaseMemory(...)`     | `defineMemoryProvider(...)`            | backs eve memory with the memory and knowledge blocks   |
+| `supabaseDocumentBackend` | `fileMemory({ backend })`              | stores file memory in `memory_documents`                |
+| `persistSessions(...)`    | `defineHook({ events })`               | copies sessions into the AI chat tables                 |
+| `routeInbox(...)`         | `chatSdkChannel()` over `inboxAdapter` | hands inbox conversations in bot mode to eve            |
+
+## Chat SDK bots
+
+```bash
+pnpm add chat
+pnpm better-supabase sql add chat-sdk-state inbox
+```
+
+From `better-supabase/chat-sdk`: `createSupabaseState(...)` is the Chat SDK
+state adapter on Postgres, `inboxAdapter(...)` answers in the in-app widget,
+`webhook(...)` receives platform webhooks, `inboundHandler(...).drain()`
+replays them, `deliver(...)` sends staff replies and `maintain(...)` runs on
+a cron. Mirror platform messages into the inbox with
+`handler.mirror(thread, message)`. Platform adapters such as
+`@chat-adapter/slack` are the app's own dependencies.
+
+Docs: https://bettersupabase.com/docs/ai-sdk.md (and `agents`, `mcp`,
+`embeddings`, `memory`, `files`, `batches` under `/docs/ai-sdk/`),
+https://bettersupabase.com/docs/eve.md and
+https://bettersupabase.com/docs/chat-sdk.md.

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

@@ -0,0 +1,65 @@
+# Expo and React Native
+
+## Server (web): `better-supabase/expo`
+
+Needs `expo-server` 55 or later and, in `app.json`, `web.output: "server"`
+plus the `expo-router` plugin options `unstable_useServerDataLoaders` and
+`unstable_useServerMiddleware`.
+
+```ts title="src/lib/supabase/server.ts"
+import { createExpo } from "better-supabase/expo";
+import { betterSupabase } from "./index";
+
+export const bs = createExpo(betterSupabase);
+```
+
+```tsx title="src/app/customers/index.tsx"
+export const loader = bs.loader(
+  ({ db }) => db.customers.findMany({ select: ["id", "name"] }).orThrow(),
+  { allow: ["user"] },
+);
+```
+
+```ts title="src/app/+middleware.ts"
+export default bs.middleware();
+```
+
+- Loaders run as the caller (bearer token first, then the cookie), so RLS applies.
+- A refused caller and a `DbException` from `.orThrow()` become a `StatusError` with the right status.
+- Only `+middleware.ts` refreshes the session; loaders never do.
+- Loader data is JSON: select the columns the screen needs and turn Temporal values into strings.
+- API routes: `export const GET = bs.handler((request, { db }) => db.customers.findMany())` in `+api.ts`.
+
+## Device: `better-supabase/client/native`
+
+```ts title="src/lib/supabase/native.ts"
+import { createClient } from "@supabase/supabase-js";
+import {
+  autoRefreshOnForeground,
+  createNativeClient,
+  secureStorage,
+} from "better-supabase/client/native";
+import * as SecureStore from "expo-secure-store";
+import { AppState } from "react-native";
+
+const supabase = createClient(url, key, {
+  auth: {
+    storage: secureStorage(SecureStore),
+    persistSession: true,
+    detectSessionInUrl: false,
+  },
+});
+autoRefreshOnForeground(supabase, AppState);
+export const bs = createNativeClient(betterSupabase, supabase);
+```
+
+- `autoRefreshOnForeground(supabase, AppState)` refreshes the session only while the app is active; supabase-js can't detect the background on React Native.
+- Never import `better-supabase/client` on the device: it pulls in `@supabase/ssr`.
+- Hermes has no `Temporal`: `defineSupabase(schema, { temporal: Temporal })` with `temporal-polyfill`, no global install.
+- Put device-only code (SecureStore, PowerSync) in `.native.ts` files or modules only they import.
+
+Done when the web export has no `expo-secure-store` or PowerSync code, a loader
+answers 401 for a signed-out request, and a native screen reads with `bs.db`.
+
+Docs: https://bettersupabase.com/docs/frameworks/expo.md and
+https://bettersupabase.com/docs/frontend/react-native.md.

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

@@ -0,0 +1,35 @@
+# PowerSync (offline reads and writes)
+
+```ts title="src/lib/powersync/database.ts"
+import { powersyncExecutor } from "better-supabase/powersync";
+
+export const local = betterSupabase.connect(powersyncExecutor(powersync));
+```
+
+- `local.customers.findMany(...)` and `list.run(local, query)` run on the device's SQLite database and return the same rows (casing, Temporal values) as PostgREST.
+- Live results: `watch(powersync, () => list.run(local, query), { tables: sqliteTables(betterSupabase, ["customers"]), onResult })`.
+- Includes, related counts, full-text search, `db.rpc` and writes to tables without a primary key return a `DbError` of kind `unsupported`. Assert `checkSqlite(betterSupabase, list)` in a test for every list a native screen runs.
+- `ilike` is SQLite `like` (case-insensitive for ASCII only).
+
+## Uploading local writes
+
+In the connector's `uploadData`, replay each `CrudEntry` through the online
+client's repositories (`bs.db` from `better-supabase/client/native`), so RLS
+and validation run:
+
+| `entry.op` | Call                                        |
+| ---------- | ------------------------------------------- |
+| `PUT`      | `upsert({ ...entry.opData, id: entry.id })` |
+| `PATCH`    | `update(entry.id, entry.opData)`            |
+| `DELETE`   | `delete(entry.id)`                          |
+
+Decide by `error.kind`, with an exhaustive `switch` ending in a `never` check:
+
+- Retry (throw, PowerSync calls again): `network`, `timeout`, `aborted`, `rate_limited`, `serialization`, `unauthorized`, `unexpected`.
+- Conflict (complete, then show it on the row): `conflict`, `stale`, `foreign_key`.
+- Discard (complete): every other kind; the server will never accept it.
+
+Never throw for a kind that can't succeed: it blocks the upload queue.
+
+Docs: https://bettersupabase.com/docs/repository/powersync.md and
+https://bettersupabase.com/docs/guides/offline-first.md.

package/skills/better-supabase-api/references/streams-credentials.md

@@ -0,0 +1,105 @@
+# Streams, credentials and the Workflow World
+
+## Resumable streams
+
+Store long output (a chat answer, a workflow's progress) so a client that
+reconnects reads the rest instead of starting over.
+
+```bash
+pnpm better-supabase sql add streams
+```
+
+```ts
+import {
+  postgresStreamStore,
+  resumeFromStore,
+  sqlTransport,
+  teeToStore,
+} from "better-supabase/streams";
+
+const streams = postgresStreamStore({
+  transport: sqlTransport(postgres.asService()),
+});
+
+// POST: send the output and store it at the same time.
+const { stream, persisted } = teeToStore(streams, chatId, output, {
+  owner: userId,
+  kind: "chat",
+  onCancel: () => controller.abort(),
+});
+after(() => persisted);
+
+// GET: resume from the last chunk the client has.
+const rest = await resumeFromStore(streams, id, { fromIdx }).orThrow();
+if (rest === undefined) return new Response(null, { status: 204 });
+```
+
+For Redis, `redisStreamStore({ url: process.env.REDIS_URL })` from
+`better-supabase/streams/redis` (add `redis`, or pass your own client). Keep
+`persisted` alive with `after` or `waitUntil`, or the stored copy stops
+when the response ends.
+
+## Credentials
+
+Third-party tokens never go in a column. A row holds a `credential_ref`
+(`{ provider, secret, scope }`) and a `CredentialProvider` resolves it.
+
+```bash
+pnpm better-supabase sql add credentials
+```
+
+```ts
+import {
+  sqlTransport,
+  subjectFor,
+  vaultCredentials,
+} from "better-supabase/credentials";
+
+export const bs = createServer(betterSupabase, {
+  credentials: vaultCredentials({
+    transport: sqlTransport(postgres.asService()),
+  }),
+});
+
+// In a handler:
+const subject = subjectFor(ctx);
+if (ctx.credentials === undefined || subject === undefined)
+  return unauthorized();
+const token = await ctx.credentials
+  .getToken(row.credential_ref, { subject })
+  .orThrow();
+await fetch(url, { headers: token.headers });
+```
+
+- On Vercel Connect, pass `vercelConnectCredentials()` from
+  `better-supabase/vercel-connect` instead (add `@vercel/connect`).
+- Check a custom provider with `testCredentialProvider` from
+  `better-supabase/testing`.
+
+## The Workflow World on Supabase (Node only)
+
+```bash
+pnpm better-supabase sql add workflow-sdk-world   # adds workflows and jobs
+pnpm add workflow @workflow/world @workflow/world-postgres pg
+```
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world
+SUPABASE_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
+```
+
+The entry's default export reads its options from the environment, so
+setting `WORKFLOW_TARGET_WORLD` is enough. To build it in code, call
+`createSupabaseWorld({ connectionString, delivery: "pg_net" })`. The World
+imports `pg` and Node built-ins: never import it from an edge or browser
+entry.
+
+From `better-supabase/workflow-sdk`, which runs anywhere: `startFor(ctx, workflow, args)`
+starts a run members see under RLS, `authorizeHook(token, ctx)` checks a
+caller before `resumeHook`, `protectWebHandler(handler, key, { can })` refuses callers before a workflow UI route or a run's stream and
+`workflowStarter({ name: workflow })` hands scheduled starts from the
+`workflows` block to the SDK.
+
+Docs: https://bettersupabase.com/docs/blocks/streams.md,
+https://bettersupabase.com/docs/extending/credentials.md and
+https://bettersupabase.com/docs/blocks/workflow-sdk.md.

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

@@ -1,6 +1,6 @@
 ---
 name: better-supabase-auth
-description: Read and check the caller in better-supabase apps, including sessions, typed claims, user profiles, OAuth clients and agents acting for a user, scopes, ended sessions and PermDock. Use when code reads auth, session or claims, when adding a custom access token hook, an OAuth or agent integration, sign-out, account deletion or role changes, or when the project has a permdock.config.ts.
+description: Read and check the caller in better-supabase apps, including sessions, typed claims, user profiles, OAuth clients and agents acting for a user, scopes, ended sessions and authorization providers. Use when code reads auth, session or claims, when adding a custom access token hook, an OAuth or agent integration, sign-out, account deletion or role changes, or when better-supabase.config.ts has an authorization key.
 ---
 
 # Auth with better-supabase
@@ -50,7 +50,8 @@ path treats `invalid` as `anon`.
    `betterSupabase.userMetadata(schema)` and read `session.profile`.
 3. Read roles, memberships, the tenant and entitlements from the verified
    claims only. Never from `user_metadata`, `session.profile`, a URL or a
-   request body.
+   request body. A tenant from the URL or input is only safe through the
+   `tenant` resolver or the `{ tenant }` option, which check membership.
 
 Done when `session.claims` is typed without casts, and a token whose claims
 fail the schema gets a 401 with code `CLAIMS_INVALID`.
@@ -101,22 +102,40 @@ if (ended) return err(ended); // unauthorized, code SESSION_REVOKED
 It needs a connection that can read `auth.sessions` (`createPostgres().admin`).
 Nothing calls it by default; keep it to the actions that need it.
 
+When RLS checks the session (so an ended session sees no rows), sign the
+browser out on page loads instead of showing an empty app. Next.js:
+`bs.proxy(request, { endedSession: { redirect: "/login" } })` asks Auth on
+document loads (and on `paths`), clears the cookies and redirects with
+`?reason=session_ended`.
+A proxy or middleware with its own Supabase client calls
+`sessionStatus(request, { url, publishableKey })` from `better-supabase/ssr`
+(`"ended"` on a 401 or 403 from Auth; treat `"unknown"` as active) and
+`clearSessionCookies(request, response, { url })` before redirecting.
+
 Done when the irreversible action returns `SESSION_REVOKED` for a signed-out
 session in a test.
 
+To lock a user out, call `bs.suspendAccount(userId, { suspended: true })`
+(it bans the user in Auth and ends every session and refresh token), or
+`bs.endSessions(userId)` to sign them out everywhere without a ban. A ban
+alone leaves the refresh tokens, which work again once the ban is lifted. To
+switch a member off in one organization only, use the organizations block's
+`suspendMember`.
+
 ## When claims change
 
 A token carries the claims from when Auth issued it, so a revoked role or
 membership lasts until the next refresh. When that window matters:
 
 - Write policies that read the source of truth, for example
-  `organization_id in (select better_supabase.member_org_ids())`, instead of
+  `organization_id in (select better_supabase.member_organization_ids())`, instead of
   the claim.
 - For signed-out, banned or deleted users, add the `sessions` SQL module and a
   restrictive policy with `using ((select better_supabase.session_active()))`
   on the tables that guard sensitive data.
 - After a change the user made themselves (joining an organization), call
-  `supabase.auth.refreshSession()` in the browser.
+  `supabase.auth.refreshSession()` in the browser (in Next.js, through
+  `useSessionChange`'s `refreshToken`, below).
 - In Next.js, drop the user's cached views with
   `bs.invalidateSession(userId, { tags })`.
 
@@ -126,16 +145,33 @@ membership lasts until the next refresh. When that window matters:
   `'use cache: private'` function. It tags the entry `bs:session:<user id>`
   and caps its lifetime at the token's.
 - `bs.cached({ tags, life: { stale } })` adds tags and caps the stale time
-  further, for example for a PermDock snapshot.
+  further, for example for a permission snapshot.
+- `bs.cached({ tables: ["customers"] })` tags the entry by table, so an
+  action that writes the table drops it without a hand-written tag.
+- `bs.invalidateSession(userId)` reaches the server caches and the caller's
+  router only; another user's browser keeps its private entries until they
+  go stale.
+- After signing in or out: `useSessionChange(sessionChanged)` from
+  `better-supabase/next/client`. After switching the active organization:
+  `useSessionChange(sessionChanged, router, { refreshToken: supabase })`, so
+  the new token reaches the server before it renders.
+- For a tenant from the route params, call `bs.cached({ tenant })` and take
+  the tenant as an argument of the `'use cache: private'` function, so it is
+  part of the cache key. Outside a cache, use `bs.context({ tenant })`.
+- In the proxy, set `bs.proxy(request, { protect, expiredPrefetch: "render" })`
+  instead of returning early for `{ kind: "anon", reason: "expired" }` in
+  `protect`. A prefetch never refreshes, so without it the prefetch caches a
+  redirect to sign-in.
 - Keep layouts synchronous: pass the `bs.session()` promise to
   `<SessionProvider>` and read it with `useSession()`.
 
-## PermDock
+## Authorization providers
 
-When the project has a `permdock.config.ts`, PermDock owns the access token
-hook, roles, memberships and the tenant claim. Read
-[references/permdock.md](references/permdock.md) before touching the hook,
-claims, tenant or entitlements.
+When `better-supabase.config.ts` has an `authorization` key, another package
+answers permission checks and may own the access token hook, roles,
+memberships and the tenant claim. Read
+[references/authorization-providers.md](references/authorization-providers.md)
+before touching the hook, claims, tenant or entitlements.
 
 ## Don't
 
@@ -154,4 +190,4 @@ https://bettersupabase.com/docs/auth.md,
 https://bettersupabase.com/docs/frameworks/next.md (bearer callers),
 https://bettersupabase.com/docs/auth/account-deletion.md,
 https://bettersupabase.com/docs/frameworks/next-cache-components.md and
-https://bettersupabase.com/docs/auth/permdock.md.
+https://bettersupabase.com/docs/extending/authorization-providers.md.