Resources

A resource serves a table as REST routes, and defineApi documents the same object, so the routes and the spec can't drift. The adapters mount them: Hono with bs.resource(table, options), Edge Functions and Next.js with bs.resources(map, options), and MCP as table tools.

import { defineAction } from "better-supabase/hono";
import { ok } from "better-supabase";

export const customers = {
  operations: ["list", "get", "update", "delete"],
  select: ["id", "name", "status", "organizationId"],
  input: { update: CustomerPatch },
  permissions: { update: "customers.update", delete: "customers.delete" },
  hooks: {
    beforeUpdate: (ctx, data) =>
      ok({ ...data, updatedBy: ctx.context.actor?.id }),
  },
  actions: {
    archive: defineAction({
      method: "POST",
      path: "/{id}/archive",
      summary: "Archive a customer",
      permission: "customers.archive",
      handler: (ctx, { id }) =>
        ctx.db.customers.update(String(id), { status: "archived" }),
    }),
  },
} as const;

app.route("/api/customers", bs.resource("customers", customers));

export const api = defineApi(betterSupabase, {
  info: { title: "CRM API", version: "1.0.0" },
  basePath: "/api",
  authorizer,
  resources: { customers },
});

The options are the resource description plus what only the server needs: select (the columns every operation returns), input (Standard Schemas that validate bodies before they reach the repository), hooks and the action handlers.

A method a resource doesn't serve answers 405 with an Allow header, a malformed key or body answers 400, and a cross-site form post that rides on the session cookie answers 403 with code: "CROSS_SITE_REQUEST".

HooksCopy Anchor Link

Hooks put business logic around the repository. Each one returns a Result (or a promise of one): an error Result ends the request with that error, and a thrown error becomes an unexpected error. They run after the authorizer.

ctx is { db, table, request, context }: the repositories bound to the caller (RLS applies), the table key, the HTTP request when there is one, and the verified request context (actor, tenant and claims). target is { id, data, query, row }, where row is set when a permission check already fetched the row.

Change the response shapeCopy Anchor Link

An after* hook can return another shape than the row. Describe it in output, keyed by operation, so the document matches; for list it is the item schema inside the page:

const customers = {
  output: { get: CustomerView, list: CustomerSummary },
  hooks: {
    afterGet: (ctx, row) => ok(toView(row)),
    afterList: (ctx, page) => ok({ ...page, items: page.items.map(toSummary) }),
  },
};

ActionsCopy Anchor Link

An action is a custom operation on the collection (/export) or on one row (/{id}/send). defineAction types the handler's data and query from the input and query schemas, which are validated first:

import { defineAction } from "better-supabase/hono";

const send = defineAction({
  method: "POST",
  path: "/{id}/send",
  input: SendInput,
  query: SendQuery,
  output: SendResult,
  emits: ["customer.sent"],
  handler: (ctx, { id, data, query }) => sendCustomer(ctx.db, id, data, query),
});

The handler returns a Result, a plain value or a Response. Action names start with a letter, use letters, digits and _, and can't be list, get, create, update or delete. The operation id is <action><Table> (archiveCustomers). defineAction is exported from better-supabase/hono, better-supabase/edge and better-supabase/next.

PermissionsCopy Anchor Link

permissions gives an operation a permission reference, and an action has its own permission. The server's authorizer decides each one, before the hooks run:

list filters instead of refusing: rows the authorizer denies are left out of items, and the other page fields stay as the query returned them. permissions: true asks the authorizer's forOperation(table, operation) for every enabled operation; it throws when the authorizer has no forOperation.

A refusal is a 403 Problem Details response with the permission key:

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://bettersupabase.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "kind": "forbidden",
  "detail": "customers.delete needs an approval",
  "code": "APPROVAL_REQUIRED",
  "permission": "customers.delete",
  "approval": { "id": "apr_9" }
}

code is PERMISSION_DENIED for a denial and APPROVAL_REQUIRED when the authorizer asks for an approval first; approval.id names the request to approve. A declared permission without an authorizer denies every caller, so a forgotten setup never opens a route. RLS still decides which rows the caller can reach.

In the document, every operation with a permission carries x-better-supabase-permission with the key, and its 403 is the shared PermissionDenied response with examples for each code.