better-supabase 0.4.0 → 0.5.1

package/README.md

@@ -1,12 +1,64 @@
 # better-supabase
 
-**A typed data layer, auth glue and CLI for Supabase apps, APIs, MCP servers and jobs.**
+**Typed repositories, auth glue and a CLI for Supabase apps, APIs, MCP servers and jobs.**
 
 [![npm](https://img.shields.io/npm/v/better-supabase)](https://www.npmjs.com/package/better-supabase)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ScaleDockHQ/better-supabase/blob/main/LICENSE)
 ![TypeScript](https://img.shields.io/badge/TypeScript-6%20%7C%207-3178c6.svg)
 
-`better-supabase gen` extends `supabase gen types` with relation cardinality, unique keys, CHECK unions and typed jsonb. The generated `schema` gives every table a typed repository that compiles to one PostgREST request, returns a `Result` instead of throwing, and runs as the caller so RLS always applies.
+[Docs](https://bettersupabase.com/docs) · [Quickstart](https://bettersupabase.com/docs/getting-started) · [Examples](https://bettersupabase.com/docs/examples) · [Changelog](https://bettersupabase.com/changelog) · [GitHub](https://github.com/ScaleDockHQ/better-supabase)
+
+better-supabase sits on top of the supabase-js client you already use. You keep your database, your RLS policies, Supabase Auth and Storage. The CLI reads your schema and generates a typed repository for every table, so a query is a typed object instead of a string, a typo in a column name is a compile error, and the row type follows what you selected.
+
+It also writes the glue every Supabase app repeats: the session cookie and token refresh for Next.js, Hono, oRPC, Edge Functions and MCP servers, pagination, soft delete, timestamps, cache invalidation, background jobs and typed Storage and Realtime. It is built on [`@supabase/supabase-js`](https://github.com/supabase/supabase-js), [`@supabase/server`](https://github.com/supabase/server), [`@supabase/middleware`](https://github.com/supabase/middleware) and [`@supabase/ssr`](https://github.com/supabase/ssr). It is an independent open-source project, not made by Supabase.
+
+## Before and after
+
+With supabase-js, the query is a string and the error is a Postgres code:
+
+```ts
+const { data, error } = await supabase
+  .from("customers")
+  .select("id, name, organization(name), notes!inner(kind)")
+  .eq("status", "active")
+  .eq("notes.kind", "call")
+  .order("name")
+  .limit(20);
+if (error) throw error;
+
+const { error: insertError } = await supabase.from("tags").insert({ name });
+if (insertError?.code === "23505") return { message: "Tag already exists" };
+```
+
+With better-supabase, every column, relation and operator is typed, and errors are values with a `kind`:
+
+```ts
+const customers = await db.customers.findMany({
+  select: ["id", "name"],
+  where: { status: "active", notes: { some: { kind: "call" } } },
+  include: { organization: { select: ["name"] } },
+  orderBy: { name: "asc" },
+  limit: 20,
+});
+// customers.data: { id: string; name: string; organization: { name: string } }[]
+
+const tag = await db.tags.create({ organizationId, name });
+if (tag.error?.kind === "conflict") return { message: "Tag already exists" };
+```
+
+Each call is still one PostgREST request, and it runs as the signed-in user, so your RLS policies decide what it can read and write. The [supabase-js migration guide](https://bettersupabase.com/docs/migration/supabase-js) maps every supabase-js call to its repository equivalent, and the two work side by side while you move over.
+
+## What you get
+
+- **Stronger generated types.** [`better-supabase gen`](https://bettersupabase.com/docs/cli/gen) writes the same `database.types.ts` as `supabase gen types` and adds relationship cardinality, unique keys, CHECK-constraint unions, typed jsonb and camelCase column maps.
+- **A typed repository per table.** [`findMany`, `findUnique`, `create`, `upsert`, `paginate`, counts and aggregates](https://bettersupabase.com/docs/repository), with nested relation filters and includes, compiled to PostgREST or to SQL on a direct Postgres connection.
+- **Results instead of exceptions.** Every call returns a [`Result` with a plain, serializable `DbError`](https://bettersupabase.com/docs/concepts/results) that you can return from server actions and RPC handlers. `.orThrow()` is opt-in, and adapters turn errors into RFC 9457 Problem Details with the right status.
+- **Your casing.** Keep database names with `casing: 'snake'`, or get [camelCase rows](https://bettersupabase.com/docs/concepts/casing) renamed inside the PostgREST query.
+- **Auth without extra round trips.** Valid access tokens are [verified locally](https://bettersupabase.com/docs/auth) against the JWKS and never reach the Auth server. Refresh happens once, in the proxy. The service role is an explicit `bs.admin()` call.
+- **Cache tags that follow writes.** Mutations [invalidate the tables they change](https://bettersupabase.com/docs/concepts/caching), with read-your-writes in Next.js server actions and table-based invalidation in TanStack Query.
+- **Plugins.** [Timestamps, soft delete, tenant scoping, actor columns, validation and rules](https://bettersupabase.com/docs/plugins), each versioned and opt-in.
+- **Kits for the SQL every app repeats.** [Jobs on Supabase Queues](https://bettersupabase.com/docs/kits/jobs), webhook inboxes, idempotency keys, organizations and invitations, notifications, list pages, typed Storage paths and Realtime topics, vector search and Stripe entitlements. [`better-supabase sql add`](https://bettersupabase.com/docs/kits/sql) writes the tables, functions and policies into your declarative schema.
+- **Tests and CI checks.** [`asUser`](https://bettersupabase.com/docs/testing) runs RLS tests as any user against the local stack, `gen --check` fails on schema drift, and [`doctor`](https://bettersupabase.com/docs/cli/doctor) reports security and performance findings, with SARIF output for code scanning.
 
 ## Install
 
@@ -15,18 +67,21 @@ pnpm add better-supabase @supabase/supabase-js
 pnpm add -D pg
 ```
 
-ESM only. The package includes the `better-supabase` CLI, which needs Node 24 or later; the runtime entries run on every WinterTC runtime (Node, Deno, Bun, Workers, Supabase Edge Functions). TypeScript 6 and 7 are tested.
+Before installing, `npx better-supabase init` detects your frameworks and prints the install command for your package manager. The package is ESM only. The CLI needs Node 24 or later, and the runtime entries run on every WinterTC runtime. On runtimes without a native `Temporal` (Node 24, Safari), load [`temporal-polyfill`](https://bettersupabase.com/docs/concepts/temporal) once at startup. TypeScript 6 and 7 are tested.
 
 ## Quick start
 
-Or start with `npx better-supabase init`, which detects your frameworks and prints the install command.
+Generate the typed schema from your local stack:
 
 ```bash
 supabase start
 pnpm better-supabase init   # config, src/lib/supabase/index.ts and framework glue
+pnpm better-supabase env    # URL and keys into .env.local
 pnpm better-supabase gen    # database.types.ts and generated.ts
 ```
 
+Define the client once, then connect it per request with the current user's Supabase client:
+
 ```ts
 import { createClient } from "@supabase/supabase-js";
 import { defineSupabase } from "better-supabase";
@@ -37,16 +92,78 @@ export const betterSupabase = defineSupabase(schema);
 
 const db = betterSupabase.connect(createClient(url, publishableKey));
 
-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 = await db.customers
+  .findMany({ select: ["id", "name"], where: { status: "active" } })
+  .orThrow();
+```
+
+`defineSupabase` holds no secrets and no connection. Because you connect with the client for the current user, every query runs under their RLS policies.
+
+## Use it where you run
+
+An adapter verifies the session, refreshes it where it should and gives each handler a `db` for the caller. In Next.js:
+
+```tsx
+// src/lib/supabase/server.ts
+export const bs = createNext(betterSupabase);
+
+// src/proxy.ts
+export const proxy = (request: NextRequest) => bs.proxy(request);
+
+// app/customers/page.tsx
+export default async function Customers() {
+  const { db } = await bs.context();
+  const customers = await db.customers
+    .findMany({ select: ["id", "name"] })
+    .orThrow();
+  return <CustomerList customers={customers} />;
+}
 ```
 
+| Where you run                      | What the adapter gives you                                              | Docs                                                       |
+| ---------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Next.js                            | Proxy, Server Components, route handlers, server actions and cache tags | [Next.js](https://bettersupabase.com/docs/frameworks/next) |
+| Hono                               | Middleware, Result-aware handlers and REST resources that match OpenAPI | [Hono](https://bettersupabase.com/docs/frameworks/hono)    |
+| oRPC                               | A middleware that adds the caller's repositories to the oRPC context    | [oRPC](https://bettersupabase.com/docs/frameworks/orpc)    |
+| Edge Functions, Deno, Bun, Workers | Fetch handlers with the caller's repositories                           | [Edge](https://bettersupabase.com/docs/frameworks/edge)    |
+| MCP servers                        | Tools from your tables and your own code, running as the signed-in user | [MCP](https://bettersupabase.com/docs/frameworks/mcp)      |
+| React and TanStack Query           | A browser client, typed hooks, query and mutation options, live queries | [Frontend](https://bettersupabase.com/docs/frontend/query) |
+
+## The CLI
+
+The `better-supabase` command ships in this package:
+
+```bash
+pnpm better-supabase init                   # config, client and framework glue
+pnpm better-supabase env                    # local URL and keys into .env.local
+pnpm better-supabase gen                    # database.types.ts and generated.ts
+pnpm better-supabase gen --check            # exit 1 in CI when the schema drifted
+pnpm better-supabase doctor                 # RLS, grants, indexes and Supabase advisors
+pnpm better-supabase doctor --format sarif  # the same findings for GitHub code scanning
+pnpm better-supabase sql add jobs           # a SQL kit module into supabase/schemas
+pnpm better-supabase skills install         # Agent Skills for your coding agent
+```
+
+See the [CLI reference](https://bettersupabase.com/docs/cli) for every command and flag.
+
+## Works with
+
+| Area       | Supported                                                                 |
+| ---------- | ------------------------------------------------------------------------- |
+| Frameworks | Next.js 16, Hono, oRPC, Supabase Edge Functions, MCP servers              |
+| Runtimes   | Node.js, Deno, Bun, Cloudflare Workers, Vercel Functions, Supabase Edge   |
+| Frontend   | React 19, TanStack Query 5, live queries over Realtime                    |
+| Validation | Zod, Valibot and any Standard Schema                                      |
+| Standards  | OpenAPI 3.1, RFC 9457, OpenTelemetry, CloudEvents, Standard Webhooks, MCP |
+| Testing    | Vitest, pgTAP, the Supabase local stack                                   |
+
+## Good to know
+
+- **It does not replace supabase-js.** Auth flows, Storage and Realtime stay on the supabase-js client, which is one property away as `db.$client`.
+- **It does not replace RLS.** Queries run as the caller and your policies decide. Bypassing them takes an explicit `bs.admin()`.
+- **A direct Postgres connection is optional.** Queries go through PostgREST by default. [`better-supabase/postgres`](https://bettersupabase.com/docs/auth/postgres) runs the same repository API over SQL for jobs, scripts and transactions.
+- **PostgREST's limits still apply.** There are no transactions across requests, and a few filters only work on reads. The [limitations page](https://bettersupabase.com/docs/guides/limitations) lists each one and what to use instead.
+
 ## Subpaths
 
 | Import                                                     | What it gives you                                                        |
@@ -64,6 +181,8 @@ if (!result.ok) return result; // DbError: kind, message, status, code
 | `better-supabase/hono`, `/orpc`, `/edge`                   | Framework adapters                                                       |
 | `better-supabase/mcp`                                      | MCP servers whose tools run as the signed-in user                        |
 | `better-supabase/jobs`                                     | Supabase Queues jobs, idempotency keys and a webhook inbox               |
+| `better-supabase/orgs`                                     | Organizations, members, invitations and switching from the SQL kit       |
+| `better-supabase/notifications`                            | Sending, listing and delivering notifications from the SQL kit           |
 | `better-supabase/list`                                     | Search, facets, sorting and pagination from one definition               |
 | `better-supabase/storage`, `/realtime`                     | Typed bucket paths and broadcast topics                                  |
 | `better-supabase/env`                                      | Validated Supabase settings                                              |
@@ -75,7 +194,7 @@ if (!result.ok) return result; // DbError: kind, message, status, code
 
 ## For AI agents
 
-The package ships [Agent Skills](https://agentskills.io) in `skills/`:
+The package ships [Agent Skills](https://agentskills.io) for queries, APIs, auth and tests:
 
 ```bash
 npx skills add ScaleDockHQ/better-supabase
@@ -83,12 +202,12 @@ npx skills add ScaleDockHQ/better-supabase
 pnpm better-supabase skills install
 ```
 
-The docs are also available as [`/llms.txt`](https://bettersupabase.com/llms.txt), as Markdown at `/docs/<page>.md`, and through the docs MCP server at `https://bettersupabase.com/mcp`.
+The docs are also available as [`/llms.txt`](https://bettersupabase.com/llms.txt), as Markdown at `/docs/<page>.md`, and through the read-only docs MCP server at `https://bettersupabase.com/mcp`.
 
 ## Documentation
 
-[bettersupabase.com/docs](https://bettersupabase.com/docs)
+The full documentation is at [bettersupabase.com/docs](https://bettersupabase.com/docs), and a runnable app for every adapter is in [`apps/examples`](https://github.com/ScaleDockHQ/better-supabase/tree/main/apps/examples).
 
 ## License
 
-[MIT](https://github.com/ScaleDockHQ/better-supabase/blob/main/LICENSE)
+[MIT](https://github.com/ScaleDockHQ/better-supabase/blob/main/LICENSE) © 2026 ScaleDock

package/dist/actor-DaJjqD5R.d.ts

@@ -0,0 +1,43 @@
+//#region src/auth/actor.d.ts
+/** One level of an RFC 8693 `act` chain: who acts, and who acted before it. */
+interface ActClaim {
+  readonly sub: string;
+  readonly act?: ActClaim;
+  readonly [claim: string]: unknown;
+}
+/**
+ * Who acts for the user, from the outermost level of the RFC 8693 `act`
+ * claim, by its `kind`:
+ *
+ * - `oauth-client`: an `act` without `kind` (prior actors stay on `chain`),
+ *   else the OAuth `client_id` of a Supabase OAuth server token. Only this
+ *   kind is limited to the scopes the user delegated.
+ * - `support`: an admin in a support session (`act.kind: "support"`, from
+ *   `supportClaims`). An `act` without `kind` but with `session_id`, as
+ *   0.5.0 minted it, counts as one until 0.6.
+ * - `impersonation`: an admin acting as the user (`act.kind:
+ *   "impersonation"`, from `actClaim`).
+ */
+type SessionActor = {
+  readonly kind: "oauth-client";
+  readonly id: string;
+  readonly chain?: ActClaim;
+} | {
+  readonly kind: "support";
+  readonly id: string;
+  readonly sessionId: string;
+  /** `act.read_only`; a support token without it is read-only. */
+  readonly readOnly: boolean;
+  readonly reason?: string;
+} | {
+  readonly kind: "impersonation";
+  readonly id: string;
+  readonly reason?: string;
+};
+/** What the user delegated to the actor: the token's OAuth `scope`. */
+interface SessionDelegation {
+  readonly scopes: readonly string[];
+  readonly chain?: ActClaim;
+}
+//#endregion
+export { SessionActor as n, SessionDelegation as r, ActClaim as t };

package/dist/channel-FQW-CnGR.d.ts

@@ -0,0 +1,70 @@
+/// <reference lib="esnext.temporal" />
+//#region src/notifications/types.d.ts
+/** A subject a notification is about, e.g. `{ type: 'task', id: '42' }`. */
+interface NotificationSubject {
+  readonly type: string;
+  readonly id: string;
+  /** Shown in the list, e.g. the task title, kept as it was at send time. */
+  readonly label?: string;
+}
+/** One notification as its recipient sees it. */
+interface NotificationItem<K extends string = string, D = unknown> {
+  /** The recipient row id: pass it to `markRead` and `dismiss`. */
+  readonly id: string;
+  /** The shared event id, the same for every recipient. */
+  readonly eventId: string;
+  readonly type: K;
+  readonly data: D;
+  readonly tenant: string | null;
+  readonly actorId: string | null;
+  readonly subject: NotificationSubject | null;
+  readonly summary: string | null;
+  readonly actionPath: string | null;
+  readonly priority: string | null;
+  readonly createdAt: Temporal.Instant;
+  readonly readAt: Temporal.Instant | null;
+  readonly resolvedAt: Temporal.Instant | null;
+}
+/** What `render` returns: the text for one notification, in one locale. */
+interface RenderedText {
+  readonly title: string;
+  readonly body?: string;
+}
+//#endregion
+//#region src/notifications/channel.d.ts
+/** One pending delivery a channel sends: the notification and who gets it. */
+interface NotificationMessage {
+  readonly deliveryId: string;
+  /** The channel name, e.g. `email`. */
+  readonly channel: string;
+  /** 1 on the first try. */
+  readonly attempts: number;
+  readonly userId: string;
+  /** The recipient's `auth.users` email, for email channels. */
+  readonly email: string | null;
+  readonly notification: NotificationItem;
+  /** What `render` returned for it, when `createNotifications` has one. */
+  readonly text?: RenderedText;
+}
+interface NotificationSendResult {
+  /** `skipped` when the channel decided not to send. Defaults to `sent`. */
+  readonly status?: "sent" | "skipped";
+  /** The provider's name, e.g. `resend` or `fcm`. */
+  readonly provider?: string;
+  /** The provider's id for the message, kept for support and webhooks. */
+  readonly providerMessageId?: string;
+}
+/**
+ * Sends notifications on one channel (email, push, Slack). The delivery
+ * worker (`notifications.deliver()`) claims pending deliveries for the
+ * channel's `name` and calls `send` for each. Throwing retries the delivery
+ * after its lease, up to `maxAttempts`, then marks it `failed`.
+ */
+interface NotificationChannel {
+  readonly apiVersion: 1;
+  /** Matches the `channel` the deliveries were created for. */
+  readonly name: string;
+  send(message: NotificationMessage): NotificationSendResult | void | Promise<NotificationSendResult | void>;
+}
+//#endregion
+export { NotificationSubject as a, NotificationItem as i, NotificationMessage as n, RenderedText as o, NotificationSendResult as r, NotificationChannel as t };

package/dist/cli/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as run } from "./run-CP20LKk_.js";
+import { i as run } from "./run-Bo_NLT5n.js";
 import { t as colorEnabled } from "./style-C0NFdJRL.js";
 import { text } from "node:stream/consumers";
 //#region src/cli/bin.ts