better-supabase 0.3.0 → 0.5.0

package/dist/hono/index.d.ts

@@ -1,45 +1,49 @@
-import { N as TableKey, n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { t as BetterSupabase } from "../define-DUbydmJa.js";
-import { r as AuthState } from "../resolve-BRciX2jK.js";
-import { d as ServerContext, f as ServerOptions, l as BetterServer, n as GuardOptions } from "../respond-DAkPIdTH.js";
-import { a as ResourceRouteOptions } from "../resource-CwVgiI5q.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`. */
-export interface BetterEnv<M extends AnyModels, F extends AnyFunctions, E> {
+export interface HonoEnv<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> {
   Variables: {
-    readonly bs: ServerContext<M, F, E>;
-    readonly db: ServerContext<M, F, E>["db"];
-    readonly auth: AuthState;
+    readonly bs: ServerContext<M, F, E, C, P>;
+    readonly db: ServerContext<M, F, E, C, P>["db"];
+    readonly auth: AuthState<C, P>;
   };
 }
 export interface HonoOptions extends ServerOptions {
   /** Include error details in problem responses. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
 }
-export interface MiddlewareOptions extends GuardOptions {
+export interface BetterHono<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /**
-   * Refresh an expired cookie session and send the new cookies. Only for
-   * routes browsers call with cookies; bearer tokens never refresh.
+   * The app's Hono `Env`, for `new Hono<typeof bs.Env>()` and
+   * `Context<typeof bs.Env>`. Type only: `undefined` at runtime.
    */
-  readonly refresh?: boolean;
-}
-export interface BetterHono<M extends AnyModels, F extends AnyFunctions, E> extends BetterServer<M, F, E> {
+  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<BetterEnv<M, F, E>>;
+  middleware(options?: MiddlewareOptions): MiddlewareHandler<HonoEnv<M, F, E, C, P>>;
   /** Wraps a handler: `Result`s become JSON or Problem Details, `undefined` becomes 204. */
-  handle(handler: (c: Context<BetterEnv<M, F, E>>, ctx: ServerContext<M, F, E>) => unknown, options?: {
+  handler(fn: (c: Context<HonoEnv<M, F, E, C, P>>, ctx: ServerContext<M, F, E, C, P>) => unknown, options?: {
     readonly status?: number;
-  }): (c: Context<BetterEnv<M, F, E>>) => Promise<Response>;
-  /** `app.onError(bs.onError)`: `DbException`s (and errors caused by a `DbError`) become Problem Details, others a 500. */
-  readonly onError: ErrorHandler<BetterEnv<M, F, E>>;
+  }): (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, 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
    * `app.route('/customers', bs.resource('customers'))` behind `middleware()`.
    */
-  resource<T extends TableKey<M>>(table: T, options?: ResourceRouteOptions<M, T>): Hono<BetterEnv<M, F, E>>;
+  resource<T extends TableKey<M>>(table: T, options?: ResourceRouteOptions<M, T>): Hono<HonoEnv<M, F, E, C, P>>;
 }
 /** Hono integration: a server plus middleware, handlers and REST resources. */
-export declare function createHono<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, options?: HonoOptions): BetterHono<M, F, E>;
+export declare function createHono<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: HonoOptions): BetterHono<M, F, E, C, P>;
 //#endregion
-export type { GuardOptions, ResourceRouteOptions };
+export type { GuardOptions, MiddlewareOptions, ResourceRouteOptions };

package/dist/hono/index.js

@@ -1,19 +1,48 @@
-import { n as dbError, r as dbErrorOf } from "../errors-Bl3rkOzo.js";
-import { a as problemResponse } from "../problem-CGt1ADix.js";
-import { i as respond, n as guard, o as createServer, s as extendServer, t as defaultExpose } from "../respond-C44EZAJo.js";
-import { t as defineResource } from "../resource-D30rp0GN.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(sb, options = {}) {
-	const server = createServer(sb, options);
+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(sb, 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,21 +75,21 @@ function createHono(sb, 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);
 			};
 		},
-		handle(handler, handleOptions = {}) {
+		handler(fn, handlerOptions = {}) {
 			return (c) => {
 				const ctx = contextOf(c);
-				return respond(() => handler(c, ctx), {
+				return respond(() => fn(c, ctx), {
 					instance: new URL(c.req.url).pathname,
 					expose,
-					...handleOptions
+					...handlerOptions
 				});
 			};
 		},
 		resource(table, resourceOptions) {
-			const resource = defineResource(sb, table, resourceOptions);
+			const resource = defineResource(betterSupabase, table, resourceOptions);
 			const app = new Hono();
 			const serve = (item) => (c) => resource.handle(c.req.raw, contextOf(c).db, item ? c.req.param("id") : void 0, {
 				instance: new URL(c.req.url).pathname,

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-BNsABq7P.d.ts → index-BGdgBPdf.d.ts}

@@ -1,61 +1,59 @@
-import { p as DbError } from "./result-c2OYgCV2.js";
-import { Z as QuerySpec } from "./define-DUbydmJa.js";
-import { i as BrowserAuth, t as AuthSnapshot } from "./index-UJ-LUxtI.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-3Po_PVlr.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-QE3UPbGm.js";
-import "./entitlements-DvJXoI02.js";
-import "./react/session.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";
 import { QueryClient } from "@tanstack/query-core";
 //#region src/react/hooks.d.ts
-/** The parts of `createBrowser()` the provider needs. */
-interface BrowserLike {
-  readonly sb: LiveSource;
+/** The parts of `createClient()` the provider needs. */
+interface ClientLike {
+  readonly betterSupabase: LiveSource;
   readonly supabase: SupabaseClient;
-  readonly auth: BrowserAuth;
+  readonly auth: ClientAuth;
   readonly db: object;
   readonly queries: object;
 }
 interface BetterSupabaseProviderProps {
-  readonly browser: BrowserLike;
+  readonly client: ClientLike;
   /** better-supabase queries are removed when the user signs out or changes. */
   readonly queryClient?: QueryClient;
   readonly children?: ReactNode;
 }
-/** Provides the browser client to the hooks. */
+/** Provides the better-supabase client to the hooks. */
 declare function BetterSupabaseProvider(props: BetterSupabaseProviderProps): ReactNode;
 /** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
 declare function useAuth(): AuthSnapshot;
 declare function useSupabase(): SupabaseClient;
-interface BetterHooks<B extends BrowserLike> {
+interface BetterHooks<B extends ClientLike> {
   /** Repositories bound to the current session. Re-renders when the user changes. */
   readonly useDb: () => B["db"];
   /** TanStack Query option factories: `useQuery(useQueries().customers.findMany())`. */
   readonly useQueries: () => B["queries"];
   readonly useSupabase: () => SupabaseClient;
   readonly useAuth: () => AuthSnapshot;
-  /** `useSession()` typed by the browser's `sb.claims(schema)` and `sb.userMetadata(schema)`. */
+  /** `useSession()` typed by the client's `betterSupabase.claims(schema)` and `betterSupabase.userMetadata(schema)`. */
   readonly useSession: () => AuthSession<ClaimsOf<B>, ProfileOf<B>>;
 }
-/** The claims type of a browser's `sb.claims(schema)`, `unknown` without one. */
-type ClaimsOf<B extends BrowserLike> = B["sb"] extends {
+/** The claims type of a client's `betterSupabase.claims(schema)`, `unknown` without one. */
+type ClaimsOf<B extends ClientLike> = B["betterSupabase"] extends {
   readonly claimsSchema: StandardSchemaV1<unknown, infer C> | undefined;
 } ? C : unknown;
-/** The profile type of a browser's `sb.userMetadata(schema)`, `unknown` without one. */
-type ProfileOf<B extends BrowserLike> = B["sb"] extends {
+/** The profile type of a client's `betterSupabase.userMetadata(schema)`, `unknown` without one. */
+type ProfileOf<B extends ClientLike> = B["betterSupabase"] extends {
   readonly userMetadataSchema: StandardSchemaV1<unknown, infer P> | undefined;
 } ? P : unknown;
 /**
  * Hooks typed for your schema.
  *
  * ```ts
- * export const { useDb, useQueries, useAuth } = createHooks<typeof browser>();
+ * export const { useDb, useQueries, useAuth } = createHooks<typeof bs>();
  * ```
  */
-declare function createHooks<B extends BrowserLike>(): BetterHooks<B>;
+declare function createHooks<B extends ClientLike>(): BetterHooks<B>;
 interface BroadcastOptions extends Omit<SubscribeOptions, "onStatus"> {
   /**
    * Refetch after each message: table keys (every query that read one of
@@ -88,7 +86,7 @@ interface LiveQueryHookOptions {
  * resubscribes when the spec, tenant or user changes.
  *
  * ```ts
- * const spec = sb.spec.customers.findMany({ include: { notes: true } });
+ * const spec = betterSupabase.spec.customers.findMany({ include: { notes: true } });
  * const { data } = useQuery(q.$spec(spec));
  * useLiveQuery(spec);
  * ```
@@ -108,13 +106,56 @@ interface LiveCount {
 /**
  * A count that stays current: refetches only the `count` spec (a HEAD
  * request) after each debounced change to a table it reads, and after the
- * channel rejoins. Takes a spec or a `next.liveCount()` seed; pass `null` to
+ * channel rejoins. Takes a spec or a `bs.liveCount()` seed; pass `null` to
  * pause. Doesn't need a `QueryClient`.
  *
  * ```tsx
- * const { count } = useLiveCount(seed); // seed = await next.liveCount(spec)
+ * const { count } = useLiveCount(seed); // seed = await bs.liveCount(spec)
  * ```
  */
 declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
 //#endregion
-export { BrowserLike 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, ClaimsOf 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-qriRM9cZ.d.ts → index-C7f8cOBM.d.ts}

@@ -1,5 +1,5 @@
-import { A as SchemaMeta } from "./types-DONv9SHN.js";
-import { p as OpenApiParameter } from "./index-CADlNHK-.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";
@@ -68,13 +68,13 @@ declare const PROBLEM_SCHEMA: Json;
  * schemes and Problem Details errors.
  *
  * ```ts
- * const doc = createOpenApi(sb, {
+ * const doc = createOpenApi(betterSupabase, {
  *   info: { title: 'CRM API', version: '1.0.0' },
  *   resources: { customers: { list: customerList }, notes: { operations: ['list', 'get'] } },
  * });
  * ```
  */
-declare function createOpenApi(sb: {
+declare function createOpenApi(betterSupabase: {
   readonly meta: SchemaMeta;
 }, options: OpenApiOptions): OpenApiDocument;
 //#endregion

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-GV77NpRP.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-Do8jXh4D.js";
-import { l as MutationKind } from "./plugin-DVRB8qNE.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(sb: {
+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-CriFFJ_p.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-c2OYgCV2.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-DUbydmJa.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.
@@ -76,7 +79,7 @@ interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
 type RpcArgsOf<F extends AnyFunctions, N extends keyof F> = F[N]["Args"];
 interface QueryHelpers<M extends AnyModels, F extends AnyFunctions> {
   /** Prefix of every better-supabase key. */
-  readonly key: readonly ["bs"];
+  readonly $key: readonly ["bs"];
   /** Query options for a `QuerySpec`, for example one sent from a Server Component. */
   $spec<S extends QuerySpec<TableKey<M>>>(spec: S | SkipToken): QueryOptionsOf<InferResult<S>>;
   /** Fetches a spec into `queryClient` for server rendering and hydration. */
@@ -85,11 +88,11 @@ interface QueryHelpers<M extends AnyModels, F extends AnyFunctions> {
   $rpc<N extends Extract<keyof F, string>>(name: N, args?: RpcArgsOf<F, N> | SkipToken, options?: {
     readonly tables?: readonly TableKey<M>[];
   }): QueryOptionsOf<F[N]["Returns"]>;
-  /** Mutation options for a database function; invalidates what `sb.defineRpc` declared. */
+  /** Mutation options for a database function; invalidates what `betterSupabase.defineRpc` declared. */
   $rpcMutation<N extends Extract<keyof F, string>>(name: N): MutationOptionsOf<RpcArgsOf<F, N>, F[N]["Returns"]>;
 }
-type Queries<M extends AnyModels, E, F extends AnyFunctions = AnyFunctions> = { readonly [T in TableKey<M>]: TableQueries<M, T, E>; } & QueryHelpers<M, F>;
-interface CreateQueriesOptions {
+type BetterQueries<M extends AnyModels, E, F extends AnyFunctions = AnyFunctions> = { readonly [T in TableKey<M>]: TableQueries<M, T, E>; } & QueryHelpers<M, F>;
+interface QueriesOptions {
   /**
    * `staleTime` for every query option. Set it above zero when rendering on
    * the server so hydrated data isn't refetched on mount.
@@ -104,14 +107,37 @@ interface CreateQueriesOptions {
  * changed table.
  *
  * ```ts
- * const q = createQueries(sb, () => browser.db);
+ * const q = createQueries(betterSupabase, () => bs.db);
  * const { data } = useQuery(q.customers.findMany({ select: ['id', 'name'] }));
  * ```
  */
-declare function createQueries<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, db: Db<M, F, E, unknown> | (() => Db<M, F, E, unknown>), options?: CreateQueriesOptions): Queries<M, E, F>;
+declare function createQueries<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, db: Db<M, F, E, unknown> | (() => Db<M, F, E, unknown>), options?: QueriesOptions): BetterQueries<M, E, F>;
 /** Invalidates every query that read a table in the target. */
 declare function queryCache(client: QueryClient): CacheAdapter;
-/** Invalidates affected queries for every mutation and declared RPC `sb` performs in this runtime. */
-declare function invalidateOnMutation<M extends AnyModels, D, F extends AnyFunctions, E>(sb: BetterSupabase<M, D, F, E>, client: QueryClient): () => void;
+/** 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
+//#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 { QueryHelpers as a, TableQueries as c, queryCache as d, BetterQueryMeta as f, Queries as i, createQueries as l, InfiniteOptionsOf as n, QueryKeyOf as o, invalidateTables as p, MutationOptionsOf as r, QueryOptionsOf as s, CreateQueriesOptions as t, invalidateOnMutation as u };
+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 };