better-supabase 0.4.0 → 0.5.0

package/dist/{result-CqEsbgYs.d.ts → executor-BunPOO-k.d.ts}

@@ -1,3 +1,163 @@
+import { E as RelationMeta, F as TableMeta, l as Codec } from "./types-Dnf_wRDz.js";
+//#region src/ir/types.d.ts
+/**
+ * The query IR. Every repository call becomes one of these operations; the
+ * executor compiles it to PostgREST or SQL. Column names in the IR are
+ * database names; `Selection` carries the app aliases.
+ */
+type ColumnOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "is" | "like" | "ilike" | "contains" | "containedBy" | "overlaps" | "fts";
+type Quantifier = "some" | "none" | "every";
+type Condition = {
+  readonly kind: "and";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "or";
+  readonly items: readonly Condition[];
+} | {
+  readonly kind: "not";
+  readonly item: Condition;
+} | {
+  readonly kind: "column";
+  readonly column: string;
+  readonly op: ColumnOp;
+  readonly value: unknown;
+  /** Full-text search configuration for `fts`. */
+  readonly config?: string;
+} | {
+  readonly kind: "relation";
+  readonly name: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly quantifier: Quantifier;
+  readonly where: Condition | undefined;
+};
+interface SelectColumn {
+  /** Key in the returned row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the column as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  /** Decodes the returned value (see `ColumnMeta.codec`). */
+  readonly codec?: Codec;
+}
+interface OrderTerm {
+  readonly column: string;
+  readonly direction: "asc" | "desc";
+  readonly nulls?: "first" | "last";
+}
+interface Include {
+  readonly alias: string;
+  readonly relation: RelationMeta;
+  readonly target: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  /** Drop parent rows without a match (`!inner`). */
+  readonly required: boolean;
+  /**
+   * `_count` include: returns the number of matching related rows instead of
+   * rows, folded into `row._count[count]` when decoded.
+   */
+  readonly count?: string;
+  /**
+   * `_sum`/`_avg`/`_min`/`_max` include: `selection.aggregate` holds the
+   * measures, folded into `row[`_${fn}`][name]` when decoded.
+   */
+  readonly aggregate?: {
+    readonly fn: AggregateFn;
+    readonly name: string;
+  };
+}
+type AggregateFn = "sum" | "avg" | "min" | "max";
+interface Measure {
+  readonly fn: AggregateFn;
+  /** Key in the returned row (`_sum_amount`, or the column alias in an include). */
+  readonly key: string;
+  /** App column name, the key under `_sum` in the decoded row. */
+  readonly alias: string;
+  /** Database column name. */
+  readonly column: string;
+  /** Read the result as text, so exact `int8`/`numeric` values survive JSON. */
+  readonly cast?: "text";
+  readonly codec?: Codec;
+}
+/**
+ * Aggregates instead of rows. `Selection.columns` become the grouping
+ * columns; without any, the result is exactly one row.
+ */
+interface Aggregation {
+  /** Also return `_count`, the number of rows in each group. */
+  readonly count: boolean;
+  readonly measures: readonly Measure[];
+}
+interface Selection {
+  readonly columns: readonly SelectColumn[];
+  readonly includes: readonly Include[];
+  readonly aggregate?: Aggregation;
+}
+type CountMode = "exact" | "planned" | "estimated";
+interface SelectOp {
+  readonly kind: "select";
+  readonly table: TableMeta;
+  readonly selection: Selection;
+  readonly where: Condition | undefined;
+  readonly orderBy: readonly OrderTerm[];
+  readonly limit: number | undefined;
+  readonly offset: number | undefined;
+  readonly count: CountMode | undefined;
+  /** Only count, return no rows. */
+  readonly head: boolean;
+  readonly single: "one" | "maybe" | undefined;
+  /** `limit` includes one row past the page, which `paginate()` reads to set `hasMore`. */
+  readonly lookAhead?: boolean;
+  /**
+   * Read from this set-returning function instead of the table (`db.$search`).
+   * Only executors with `functionSources` honor it.
+   */
+  readonly source?: FunctionSource;
+}
+/** A function returning `setof <table>`, called with named arguments. */
+interface FunctionSource {
+  readonly schema: string;
+  readonly name: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+interface InsertOp {
+  readonly kind: "insert";
+  readonly table: TableMeta;
+  /** Rows keyed by database column names. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly returning: Selection | undefined;
+  readonly onConflict: {
+    readonly columns: readonly string[];
+    readonly action: "update" | "ignore";
+  } | undefined;
+  /** Missing columns become `null` instead of their default in bulk inserts. */
+  readonly defaultToNull: boolean;
+}
+interface UpdateOp {
+  readonly kind: "update";
+  readonly table: TableMeta;
+  /** Keyed by database column names. */
+  readonly set: Readonly<Record<string, unknown>>;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+interface DeleteOp {
+  readonly kind: "delete";
+  readonly table: TableMeta;
+  readonly where: Condition | undefined;
+  readonly returning: Selection | undefined;
+}
+type Operation = SelectOp | InsertOp | UpdateOp | DeleteOp;
+type MutationOp = InsertOp | UpdateOp | DeleteOp;
+declare const and: (...items: (Condition | undefined)[]) => Condition | undefined;
+declare const or: (...items: Condition[]) => Condition;
+declare const not: (item: Condition) => Condition;
+declare const column: (name: string, op: ColumnOp, value: unknown) => Condition;
+//#endregion
 //#region src/core/errors.d.ts
 /**
  * Extra fields carried by each error kind. Plugins can add kinds through the
@@ -34,6 +194,10 @@ interface DbErrorKinds {
     constraint?: string;
   };
   invalid_input: Record<never, never>;
+  /** A stored value the app type can't hold, e.g. `infinity` for a Temporal timestamp. */
+  invalid_value: {
+    column?: string;
+  };
   raised: Record<never, never>;
   timeout: Record<never, never>;
   serialization: Record<never, never>;
@@ -200,4 +364,39 @@ declare function toBetterResult<T>(result: AsyncResult<T>, api: BetterResultApi<
 declare function fromBetterResult<T>(result: BetterResultValue<T, unknown>, mapError?: (error: unknown) => DbError): Result<T>;
 declare function toDbError(cause: unknown): DbError;
 //#endregion
-export { isConflict as C, statusOf as D, mapDbError as E, isCheck as S, isForeignKey as T, DbException as _, Ok as a, ValidationIssue as b, err as c, toBetterResult as d, toDbError as f, DbErrorOf as g, DbErrorKinds as h, Err as i, fromBetterResult as l, DbErrorKind as m, BetterResultApi as n, Result as o, DbError as p, BetterResultValue as r, ThrowMapper as s, AsyncResult as t, ok as u, ErrorMapper as v, isDbError as w, dbError as x, RawDbError as y };
+//#region src/core/executor.d.ts
+interface ExecuteContext {
+  readonly signal?: AbortSignal;
+  readonly errorMappers: readonly ErrorMapper[];
+}
+interface ExecuteResult {
+  /** Rows keyed by the aliases in the operation's selection. */
+  readonly rows: readonly Record<string, unknown>[];
+  readonly count: number | null;
+}
+/**
+ * Runs IR operations. PostgREST (`postgrestExecutor`) and SQL
+ * (`better-supabase/postgres`) are built in; any other backend can implement
+ * this interface and prove it with `testExecutor` from `better-supabase/testing`.
+ */
+interface Executor {
+  readonly name: string;
+  /** Honors `SelectOp.source`. `db.$search` fails on executors without it. */
+  readonly functionSources?: boolean;
+  execute(op: Operation, context: ExecuteContext): Promise<Result<ExecuteResult>>;
+  /** Calls a database function. Optional; `db.$rpc` fails without it. */
+  rpc?(name: string, args: Readonly<Record<string, unknown>>, context: RpcContext): Promise<Result<unknown>>;
+  /**
+   * Runs several reads together, for `db.$many`: one transaction on a SQL
+   * connection. Returns one result per operation, in order. Optional;
+   * without it `db.$many` runs the operations in parallel.
+   */
+  batch?(ops: readonly Operation[], context: ExecuteContext): Promise<readonly Result<ExecuteResult>[]>;
+}
+interface RpcContext extends ExecuteContext {
+  readonly schema: string;
+  /** The function is `stable`: send it as a GET, so read replicas can serve it. */
+  readonly get?: boolean;
+}
+//#endregion
+export { or as $, mapDbError as A, InsertOp as B, RawDbError as C, isConflict as D, isCheck as E, Condition as F, Quantifier as G, MutationOp as H, CountMode as I, Selection as J, SelectColumn as K, DeleteOp as L, AggregateFn as M, Aggregation as N, isDbError as O, ColumnOp as P, not as Q, FunctionSource as R, ErrorMapper as S, dbError as T, Operation as U, Measure as V, OrderTerm as W, and as X, UpdateOp as Y, column as Z, DbError as _, AsyncResult as a, DbErrorOf as b, Err as c, ThrowMapper as d, err as f, toDbError as g, toBetterResult as h, RpcContext as i, statusOf as j, isForeignKey as k, Ok as l, ok as m, ExecuteResult as n, BetterResultApi as o, fromBetterResult as p, SelectOp as q, Executor as r, BetterResultValue as s, ExecuteContext as t, Result as u, DbErrorKind as v, ValidationIssue as w, DbException as x, DbErrorKinds as y, Include as z };

package/dist/{executor-CZ7ImRiD.d.ts → executor-Cghdstwu.d.ts}

@@ -1,5 +1,4 @@
-import { r as Executor } from "./executor-B5IoUxLE.js";
-import { y as RawDbError } from "./result-CqEsbgYs.js";
+import { C as RawDbError, r as Executor } from "./executor-BunPOO-k.js";
 //#region src/postgres/executor.d.ts
 /**
  * Anything that runs parameterized SQL: `ctx.postgres` from

package/dist/{executor-CVt6dD0B.js → executor-XycESQPH.js}

@@ -1,6 +1,6 @@
-import { c as mapDbError, n as dbError } from "./errors-L0xK41y_.js";
-import { i as ok, n as err, o as toDbError } from "./result-Bj6yt33D.js";
-import { t as compileSql } from "./sql-B34HU2DI.js";
+import { c as mapDbError, n as dbError } from "./errors-DtwXa6b8.js";
+import { i as ok, n as err, o as toDbError } from "./result-BKiliPY7.js";
+import { t as compileSql } from "./sql-Coh6n4cC.js";
 //#region src/postgres/executor.ts
 function isPgError(value) {
 	return typeof value === "object" && value !== null && typeof value.code === "string";

package/dist/hono/index.d.ts

@@ -1,8 +1,8 @@
-import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { t as BetterSupabase } from "../define-CRS2MRV3.js";
-import { r as AuthState } from "../resolve-BAqQcwMW.js";
-import { f as ServerContext, n as GuardOptions, p as ServerOptions, r as MiddlewareOptions, u as BetterServer } from "../respond-DgIbdrt8.js";
-import { a as ResourceRouteOptions } from "../resource-BJcaIfxi.js";
+import { P as TableKey, n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
+import { t as BetterSupabase } from "../define-Bp_BZa5h.js";
+import { r as AuthState } from "../resolve-C15TJq77.js";
+import { f as ServerContext, n as GuardOptions, p as ServerOptions, r as MiddlewareOptions, u as BetterServer } from "../respond-D2OQl62-.js";
+import { a as ResourceRouteOptions } from "../resource-D8iqWMr-.js";
 import { Context, ErrorHandler, Hono, MiddlewareHandler } from "hono";
 //#region src/hono/index.d.ts
 /** Hono `Env` with the request's better-supabase context in `c.var`. */
@@ -18,13 +18,24 @@ export interface HonoOptions extends ServerOptions {
   readonly exposeErrors?: boolean;
 }
 export interface BetterHono<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
+  /**
+   * The app's Hono `Env`, for `new Hono<typeof bs.Env>()` and
+   * `Context<typeof bs.Env>`. Type only: `undefined` at runtime.
+   */
+  readonly Env: HonoEnv<M, F, E, C, P>;
+  /** `new Hono<typeof bs.Env>()` with `onError(bs.onError)` installed. */
+  app(): Hono<HonoEnv<M, F, E, C, P>>;
   /** Resolves the caller, enforces `allow` and sets `c.var.bs`, `c.var.db`, `c.var.auth`. */
   middleware(options?: MiddlewareOptions): MiddlewareHandler<HonoEnv<M, F, E, C, P>>;
   /** Wraps a handler: `Result`s become JSON or Problem Details, `undefined` becomes 204. */
   handler(fn: (c: Context<HonoEnv<M, F, E, C, P>>, ctx: ServerContext<M, F, E, C, P>) => unknown, options?: {
     readonly status?: number;
   }): (c: Context<HonoEnv<M, F, E, C, P>>) => Promise<Response>;
-  /** `app.onError(bs.onError)`: `DbException`s (and errors caused by a `DbError`) become Problem Details, others a 500. */
+  /**
+   * `app.onError(bs.onError)`: `DbException`s (and errors caused by a `DbError`)
+   * become Problem Details, Hono's `HTTPException`s keep their own response,
+   * and anything else is a 500.
+   */
   readonly onError: ErrorHandler<HonoEnv<M, F, E, C, P>>;
   /**
    * REST routes for a table matching `createOpenApi`. Mount with

package/dist/hono/index.js

@@ -1,19 +1,48 @@
-import { n as dbError, r as dbErrorOf } from "../errors-L0xK41y_.js";
-import { a as problemResponse } from "../problem-BihjPR0t.js";
-import { a as guard, i as defaultExpose, n as extendServer, s as respond, t as createServer } from "../server-BA75B0mT.js";
-import { t as defineResource } from "../resource-My_y-Syh.js";
+import { n as dbError, r as dbErrorOf } from "../errors-DtwXa6b8.js";
+import { a as problemResponse } from "../problem-BW1KhzSG.js";
+import { d as guard, i as rememberVerifiedFor, n as createServer, p as respond, r as extendServer, u as defaultExpose } from "../server-Csx2sRjg.js";
+import { t as defineResource } from "../resource-CRxxwkQq.js";
 import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 //#region src/hono/index.ts
 function contextOf(c) {
 	const ctx = c.get("bs");
 	if (!ctx) throw new TypeError("better-supabase: no context on this request; add app.use(bs.middleware()) first");
 	return ctx;
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isJwtClaims(value) {
+	return isRecord(value) && typeof value["sub"] === "string";
+}
+function isUserClaims(value) {
+	return isRecord(value) && typeof value["id"] === "string";
+}
+/**
+* The bearer token `withSupabase` from `@supabase/server/adapters/hono`
+* verified for this request, with the claims it stored in
+* `c.var.supabaseContext`.
+*/
+function verifiedBySupabase(c) {
+	const supabase = c.var["supabaseContext"];
+	if (!isRecord(supabase) || supabase["authMode"] !== "user") return void 0;
+	const { jwtClaims, userClaims } = supabase;
+	const header = c.req.header("authorization");
+	const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
+	if (!token || !isJwtClaims(jwtClaims) || !isUserClaims(userClaims)) return void 0;
+	return {
+		token,
+		claims: jwtClaims,
+		user: userClaims
+	};
+}
 /** Hono integration: a server plus middleware, handlers and REST resources. */
 function createHono(betterSupabase, options = {}) {
 	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
 	const onError = (cause, c) => {
+		if (cause instanceof HTTPException) return cause.getResponse();
 		const instance = new URL(c.req.url).pathname;
 		const thrown = dbErrorOf(cause);
 		if (thrown) return problemResponse(thrown, {
@@ -27,9 +56,15 @@ function createHono(betterSupabase, options = {}) {
 		});
 	};
 	return extendServer(server, {
+		Env: void 0,
 		onError,
+		app() {
+			return new Hono().onError(onError);
+		},
 		middleware(middlewareOptions = {}) {
 			return async (c, next) => {
+				const verified = verifiedBySupabase(c);
+				if (verified) rememberVerifiedFor(server, verified);
 				const ctx = await server.context(c.req.raw, { refresh: middlewareOptions.refresh ?? false });
 				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
 				if (denied) return ctx.resolution.apply(problemResponse(denied, {
@@ -40,7 +75,7 @@ function createHono(betterSupabase, options = {}) {
 				c.set("db", ctx.db);
 				c.set("auth", ctx.auth);
 				await next();
-				c.res = ctx.resolution.apply(c.res);
+				c.res = ctx.apply(c.res);
 			};
 		},
 		handler(fn, handlerOptions = {}) {

package/dist/impersonation-VfaGc4Q_.js

@@ -0,0 +1,41 @@
+//#region src/auth/impersonation.ts
+/** The `act` claim for an impersonated session. */
+function actClaim(options) {
+	return {
+		sub: options.actor,
+		reason: options.reason
+	};
+}
+/** The impersonator in `claims.act`, or `undefined` for a normal session. */
+function impersonatorOf(claims) {
+	const act = claims["act"];
+	if (typeof act !== "object" || act === null) return void 0;
+	const { sub, reason, session_id, read_only } = act;
+	if (typeof sub !== "string" || sub === "") return void 0;
+	return {
+		id: sub,
+		...typeof reason === "string" ? { reason } : {},
+		...typeof session_id === "string" ? { sessionId: session_id } : {},
+		...typeof read_only === "boolean" ? { readOnly: read_only } : {}
+	};
+}
+/**
+* The repository context of a signed-in user: the actor, with the
+* impersonator from `act`, and the claims. Every adapter builds it here, so
+* plugins see the same actor on the server, in middleware and in the browser.
+*/
+function userContext(user, claims) {
+	const impersonator = impersonatorOf(claims);
+	return {
+		actor: {
+			id: user.id,
+			kind: "user",
+			...user.role ? { role: user.role } : {},
+			...user.email ? { email: user.email } : {},
+			...impersonator ? { impersonator: impersonator.id } : {}
+		},
+		claims
+	};
+}
+//#endregion
+export { impersonatorOf as n, userContext as r, actClaim as t };

package/dist/{index-BBdvo-5d.d.ts → index-BGdgBPdf.d.ts}

@@ -1,9 +1,9 @@
-import { p as DbError } from "./result-CqEsbgYs.js";
-import { Z as QuerySpec } from "./define-CRS2MRV3.js";
-import { i as ClientAuth, t as AuthSnapshot } from "./index-RlLXd8dL.js";
+import { _ as DbError } from "./executor-BunPOO-k.js";
+import { Z as QuerySpec } from "./define-Bp_BZa5h.js";
+import { i as ClientAuth, t as AuthSnapshot } from "./index-DmXSxbLi.js";
 import { n as TemplateValues } from "./template-mbvlysOo.js";
-import { t as AuthSession } from "./view-B64o81wp.js";
-import { a as LiveSource, g as Topic, h as SubscriptionStatus, p as SubscribeOptions, r as LiveCountSeed, u as EventSchemas, v as TopicHandlers, y as TopicMessage } from "./live-BHakSWWo.js";
+import { t as AuthSession } from "./view-BEf0diC5.js";
+import { a as LiveSource, g as Topic, h as SubscriptionStatus, p as SubscribeOptions, r as LiveCountSeed, u as EventSchemas, v as TopicHandlers, y as TopicMessage } from "./live-D9W2M5aO.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { ReactNode } from "react";
 import { StandardSchemaV1 } from "@standard-schema/spec";
@@ -115,4 +115,47 @@ interface LiveCount {
  */
 declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
 //#endregion
-export { ClaimsOf as a, LiveCountHookOptions as c, createHooks as d, useAuth as f, useSupabase as g, useLiveQuery as h, BroadcastOptions as i, LiveQueryHookOptions as l, useLiveCount as m, BetterSupabaseProvider as n, ClientLike as o, useBroadcast as p, BetterSupabaseProviderProps as r, LiveCount as s, BetterHooks as t, ProfileOf as u };
+//#region src/react/notifications.d.ts
+/** Loads one list of items, e.g. a server action that calls `notifications.list()`. */
+type NotificationSource<T> = () => Promise<readonly T[]>;
+interface UseNotificationsOptions<T> {
+  /**
+   * The private topic the `notifications` module broadcasts to, e.g.
+   * `notifications:${userId}` (`kits.notifications.options.topic`). `null`
+   * loads once without realtime.
+   */
+  readonly topic: string | null;
+  /** The notifications, newest first. */
+  readonly load: NotificationSource<T>;
+  /** More items merged in, such as running jobs or pending approvals. */
+  readonly sources?: readonly NotificationSource<T>[];
+  /** Orders the merged list. Defaults to the order the sources return. */
+  readonly sort?: (a: T, b: T) => number;
+  /** The badge number. Defaults to the items without a `readAt`. */
+  readonly count?: (items: readonly T[]) => number;
+  /** Runs for each broadcast, e.g. to show a toast for `notification_created`. */
+  readonly onMessage?: (event: string, payload: unknown) => void;
+}
+interface NotificationsState<T> {
+  /** `undefined` until the first load. */
+  readonly items: readonly T[] | undefined;
+  readonly count: number;
+  readonly status: SubscriptionStatus;
+  readonly error: unknown;
+  /** Loads again, e.g. after marking items read. */
+  readonly refresh: () => Promise<void>;
+}
+/**
+ * The signed-in user's notifications, kept current: loads them, then loads
+ * again after each broadcast on `topic` and after the channel rejoins.
+ *
+ * ```tsx
+ * const { items, count } = useNotifications({
+ *   topic: `org:${orgId}:notifications:${userId}`,
+ *   load: () => listNotifications(orgId),
+ * });
+ * ```
+ */
+declare function useNotifications<T>(options: UseNotificationsOptions<T>): NotificationsState<T>;
+//#endregion
+export { useBroadcast as _, BetterHooks as a, useSupabase as b, BroadcastOptions as c, LiveCount as d, LiveCountHookOptions as f, useAuth as g, createHooks as h, useNotifications as i, ClaimsOf as l, ProfileOf as m, NotificationsState as n, BetterSupabaseProvider as o, LiveQueryHookOptions as p, UseNotificationsOptions as r, BetterSupabaseProviderProps as s, NotificationSource as t, ClientLike as u, useLiveCount as v, useLiveQuery as y };

package/dist/{index-BhHEC04r.d.ts → index-C7f8cOBM.d.ts}

@@ -1,5 +1,5 @@
-import { A as SchemaMeta } from "./types-DONv9SHN.js";
-import { p as OpenApiParameter } from "./index-BAy4tsAP.js";
+import { j as SchemaMeta } from "./types-Dnf_wRDz.js";
+import { p as OpenApiParameter } from "./index-fag8VJZ2.js";
 //#region src/openapi/index.d.ts
 type Json = Record<string, unknown>;
 type ResourceOperation = "list" | "get" | "create" | "update" | "delete";

package/dist/{index-Dy6kuF0P.d.ts → index-CLg87OBW.d.ts}

@@ -10,6 +10,8 @@ interface BetterSupabaseEnv {
   readonly secretKeys?: Readonly<Record<string, string>>;
   /** `SUPABASE_JWKS_URL`, or `<url>/auth/v1/.well-known/jwks.json`. */
   readonly jwksUrl: URL;
+  /** `SUPABASE_JWKS`: inline keys, used instead of fetching `jwksUrl`. */
+  readonly jwks?: InlineJwks;
   /** Direct Postgres connection string (`SUPABASE_DB_URL` / `DATABASE_URL`). */
   readonly dbUrl?: string;
   /** Project ref for hosted projects (`<ref>.supabase.co`). */
@@ -17,6 +19,8 @@ interface BetterSupabaseEnv {
   /** `SUPABASE_READ_URL`: a read replica or the `<ref>-all` load balancer, for reads. */
   readonly readUrl?: string;
 }
+/** A JSON Web Key Set, as `@supabase/server` verifies with it. */
+type InlineJwks = Exclude<SupabaseEnv["jwks"], URL | null>;
 interface PublicEnv {
   readonly url: string;
   readonly publishableKey: string;
@@ -46,6 +50,7 @@ declare const ENV_VARIABLES: {
   readonly secretKey: readonly string[];
   readonly dbUrl: readonly string[];
   readonly jwksUrl: readonly string[];
+  readonly jwks: readonly string[];
   readonly readUrl: readonly string[];
 };
 declare class EnvValidationError extends Error {
@@ -68,4 +73,4 @@ declare function publicEnv(env: BetterSupabaseEnv): PublicEnv;
 /** Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of `withSupabase`). */
 declare function toServerEnv(env: BetterSupabaseEnv): SupabaseEnv;
 //#endregion
-export { EnvResult as a, PublicEnv as c, parseEnv as d, publicEnv as f, EnvOptions as i, envSchema as l, ENV_VARIABLES as n, EnvSource as o, toServerEnv as p, EnvIssue as r, EnvValidationError as s, BetterSupabaseEnv as t, loadEnv as u };
+export { EnvResult as a, InlineJwks as c, loadEnv as d, parseEnv as f, EnvOptions as i, PublicEnv as l, toServerEnv as m, ENV_VARIABLES as n, EnvSource as o, publicEnv as p, EnvIssue as r, EnvValidationError as s, BetterSupabaseEnv as t, envSchema as u };

package/dist/{index-D5IfUIDh.d.ts → index-DOESKG27.d.ts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
-import { A as SchemaMeta } from "./types-DONv9SHN.js";
-import { a as EventHub, s as MutationNotice } from "./events-B21UOhvP.js";
-import { l as MutationKind } from "./plugin-bNhvJwRh.js";
+import { j as SchemaMeta } from "./types-Dnf_wRDz.js";
+import { a as EventHub, g as KitEventPattern, p as KitEvent, s as MutationNotice } from "./events-aIO7vsIk.js";
+import { l as MutationIntent } from "./plugin-o144f322.js";
 //#region src/events/index.d.ts
 /** A CloudEvents 1.0 event. Extension attributes are lowercase alphanumerics. */
 interface CloudEvent<T = unknown> {
@@ -16,10 +16,11 @@ interface CloudEvent<T = unknown> {
   readonly data?: T;
   readonly [extension: string]: unknown;
 }
-declare const ROW_EVENT_TYPES: { readonly [K in MutationKind]: string; };
+declare const ROW_EVENT_TYPES: { readonly [K in MutationIntent]: string; };
 interface RowEventData {
   readonly table: string;
   readonly row: Readonly<Record<string, unknown>>;
+  readonly actorId?: string;
 }
 interface CloudEventOptions {
   /** URI-reference of the producer, e.g. `https://crm.example.com` or `/crm`. */
@@ -35,8 +36,10 @@ interface EventSink {
 }
 /**
  * One CloudEvent per mutated row: `dev.better-supabase.row.created` with the
- * app-cased row as `data`, the primary key as `subject`, the tenant as
- * `partitionkey` and the actor as `actorid`.
+ * app-cased row and the actor in `data`, the primary key as `subject` and the
+ * tenant as `partitionkey`. Writes that return no rows (soft
+ * deletes, `returning: false`) send one event per known primary key, with the
+ * key as `row`.
  */
 declare function toCloudEvents(notice: MutationNotice, options: CloudEventOptions & {
   readonly meta?: SchemaMeta;
@@ -49,12 +52,34 @@ interface ForwardOptions extends CloudEventOptions {
 }
 /**
  * Sends a CloudEvent for every mutation to `sink`. Returns a function that
- * stops forwarding. Use an outbox (SQL kit) when events must not be lost.
+ * stops forwarding. Sends in flight are tracked on `betterSupabase.events`
+ * (`settled()`), which the Next adapter hands to `after()` and the edge
+ * entry to `waitUntil`. Use an outbox (SQL kit) when events must not be lost.
  */
 declare function forwardMutations(betterSupabase: {
   readonly events: EventHub;
   readonly meta: SchemaMeta;
 }, sink: EventSink, options: ForwardOptions): () => void;
+/**
+ * A kit event as a CloudEvent: `dev.better-supabase.support.started` with
+ * the event data and the actor (`actorId`) as `data` and the tenant as
+ * `partitionkey`.
+ */
+declare function kitCloudEvent(event: KitEvent, options: CloudEventOptions): CloudEvent;
+interface ForwardKitOptions extends CloudEventOptions {
+  /** Only forward events that match, e.g. `support.*`. Defaults to all. */
+  readonly types?: readonly KitEventPattern[];
+  /** Sink failures never fail the kit call. Defaults to the `Logger`. */
+  readonly onError?: (error: unknown, events: readonly CloudEvent[]) => void;
+}
+/**
+ * Sends a CloudEvent for every kit event (`support.*`, `org.*`, ...) to
+ * `sink`. Returns a function that stops forwarding. Like
+ * `forwardMutations`, sends are tracked on `betterSupabase.events`.
+ */
+declare function forwardKitEvents(betterSupabase: {
+  readonly events: EventHub;
+}, sink: EventSink, options: ForwardKitOptions): () => void;
 type HttpMode = "structured" | "binary" | "batch";
 /** The HTTP protocol binding: headers and body for one event (or a batch). */
 declare function toHttp(events: CloudEvent | readonly CloudEvent[], mode?: HttpMode): {
@@ -72,4 +97,4 @@ interface HttpSinkOptions {
 /** POSTs events to `url`. Non-2xx responses reject. */
 declare function httpSink(url: string | URL, options?: HttpSinkOptions): EventSink;
 //#endregion
-export { HttpMode as a, RowEventData as c, httpSink as d, isCloudEvent as f, ForwardOptions as i, forwardMutations as l, toHttp as m, CloudEventOptions as n, HttpSinkOptions as o, toCloudEvents as p, EventSink as r, ROW_EVENT_TYPES as s, CloudEvent as t, fromHttp as u };
+export { toHttp as _, ForwardOptions as a, ROW_EVENT_TYPES as c, forwardMutations as d, fromHttp as f, toCloudEvents as g, kitCloudEvent as h, ForwardKitOptions as i, RowEventData as l, isCloudEvent as m, CloudEventOptions as n, HttpMode as o, httpSink as p, EventSink as r, HttpSinkOptions as s, CloudEvent as t, forwardKitEvents as u };

package/dist/{index-DFmOpBGC.d.ts → index-DgILJRXj.d.ts}

@@ -1,13 +1,16 @@
-import { C as PrimaryKeyValue, L as UniqueWhere, N as TableKey, R as Update, g as Insert, n as AnyModels, t as AnyFunctions } from "./types-DONv9SHN.js";
-import { _ as DbException } from "./result-CqEsbgYs.js";
-import { C as FindExt, Ct as WhereInput, M as UpsertArgs, N as WriteArgs, S as DeleteExt, T as OffsetPageArgs, X as InferResult, Z as QuerySpec, _ as CursorPage, it as AggregateResult, j as UpdateArgs, k as Returned, l as CacheAdapter, lt as FindFirstArgs, rt as AggregateArgs, st as CountArgs, t as BetterSupabase, ut as FindManyArgs, v as CursorPageArgs, vt as Payload, w as OffsetPage, x as DeleteArgs, y as Db, yt as ReadArgs } from "./define-CRS2MRV3.js";
-import { DataTag, InfiniteData, QueryClient, SkipToken } from "@tanstack/query-core";
+import { P as TableKey, R as UniqueWhere, _ as Insert, n as AnyFunctions, r as AnyModels, w as PrimaryKeyValue, z as Update } from "./types-Dnf_wRDz.js";
+import { x as DbException } from "./executor-BunPOO-k.js";
+import { C as FindExt, Ct as WhereInput, M as UpsertArgs, N as WriteArgs, S as DeleteExt, T as OffsetPageArgs, X as InferResult, Z as QuerySpec, _ as CursorPage, it as AggregateResult, j as UpdateArgs, k as Returned, l as CacheAdapter, lt as FindFirstArgs, rt as AggregateArgs, st as CountArgs, t as BetterSupabase, ut as FindManyArgs, v as CursorPageArgs, vt as Payload, w as OffsetPage, x as DeleteArgs, y as Db, yt as ReadArgs } from "./define-Bp_BZa5h.js";
+import { DataTag, InfiniteData, QueryClient, QueryMeta, SkipToken } from "@tanstack/query-core";
 //#region src/query/invalidate.d.ts
-/** Carried by every better-supabase query: the tables whose changes make it stale. */
-interface BetterQueryMeta {
+/**
+ * Carried by every better-supabase query: the tables whose changes make it
+ * stale, on top of the app's `Register['queryMeta']`, so the options stay
+ * assignable to `useQuery` when the app narrows its query meta.
+ */
+type BetterQueryMeta = QueryMeta & {
   readonly bsTables: readonly string[];
-  readonly [key: string]: unknown;
-}
+};
 /**
  * Invalidates every query that read one of `tables`: better-supabase queries
  * by their `meta.bsTables`, and other `['bs', table, ...]` keys by prefix.
@@ -114,4 +117,27 @@ declare function queryCache(client: QueryClient): CacheAdapter;
 /** Invalidates affected queries for every mutation and declared RPC `betterSupabase` performs in this runtime. */
 declare function invalidateOnMutation<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, client: QueryClient): () => void;
 //#endregion
-export { QueryHelpers as a, TableQueries as c, queryCache as d, BetterQueryMeta as f, QueriesOptions as i, createQueries as l, InfiniteOptionsOf as n, QueryKeyOf as o, invalidateTables as p, MutationOptionsOf as r, QueryOptionsOf as s, BetterQueries as t, invalidateOnMutation as u };
+//#region src/query/user-change.d.ts
+/** The part of `createClient().auth` that `clearOnUserChange` reads. */
+interface UserChangeSource {
+  subscribe(listener: () => void): () => void;
+  current(): {
+    readonly status: string;
+    readonly user: {
+      readonly id: string;
+    } | null;
+  };
+}
+/**
+ * Removes every `['bs', ...]` query when the signed-in user changes or signs
+ * out, so the next user never sees the previous user's rows. Returns the
+ * function that stops listening. `BetterSupabaseProvider` calls it for React;
+ * call it yourself with Vue, Solid, Svelte or Angular Query.
+ *
+ * ```ts
+ * const stop = clearOnUserChange(queryClient, bs.auth);
+ * ```
+ */
+declare function clearOnUserChange(queryClient: Pick<QueryClient, "removeQueries">, auth: UserChangeSource): () => void;
+//#endregion
+export { MutationOptionsOf as a, QueryKeyOf as c, createQueries as d, invalidateOnMutation as f, invalidateTables as h, InfiniteOptionsOf as i, QueryOptionsOf as l, BetterQueryMeta as m, clearOnUserChange as n, QueriesOptions as o, queryCache as p, BetterQueries as r, QueryHelpers as s, UserChangeSource as t, TableQueries as u };

package/dist/{index-RlLXd8dL.d.ts → index-DmXSxbLi.d.ts}

@@ -1,7 +1,7 @@
-import { n as AnyModels, t as AnyFunctions } from "./types-DONv9SHN.js";
-import { t as BetterSupabase, y as Db } from "./define-CRS2MRV3.js";
-import { c as PublicEnv } from "./index-Dy6kuF0P.js";
-import { t as BetterQueries } from "./index-DFmOpBGC.js";
+import { n as AnyFunctions, r as AnyModels } from "./types-Dnf_wRDz.js";
+import { t as BetterSupabase, y as Db } from "./define-Bp_BZa5h.js";
+import { l as PublicEnv } from "./index-CLg87OBW.js";
+import { r as BetterQueries } from "./index-DgILJRXj.js";
 import { SupabaseClient } from "@supabase/supabase-js";
 //#region src/client/index.d.ts
 interface ClientOptions {