better-supabase 0.4.0 → 0.5.0

package/dist/orgs/index.d.ts

@@ -0,0 +1,132 @@
+/// <reference lib="esnext.temporal" />
+import { S as ErrorMapper, a as AsyncResult } from "../executor-BunPOO-k.js";
+import { a as EventHub } from "../events-aIO7vsIk.js";
+import { g as RequestContext } from "../plugin-o144f322.js";
+import { i as sqlTransport, n as RpcClient, r as rpcTransport, t as KitTransport } from "../kit-transport-B82k1djG.js";
+//#region src/orgs/orgs.d.ts
+/**
+ * Organization columns by database name: `name`, `slug` and the columns in
+ * `kits.organizations.options.attributes`. Other keys are ignored.
+ */
+interface OrgAttributes {
+  readonly name?: string;
+  readonly slug?: string;
+  readonly [column: string]: unknown;
+}
+interface CreateOrgOptions {
+  /** The owner, when the transport runs as the service role. */
+  readonly ownerId?: string;
+}
+type SlugProblem = "invalid" | "reserved" | "taken";
+interface InviteRequest {
+  /** `null` invites to the platform (`kits.access.model: 'catalog'`). */
+  readonly organizationId: string | null;
+  readonly email: string;
+  /** A role name, or a role id or key under the catalog model. */
+  readonly role: string;
+  /** A Postgres interval such as `'3 days'`. Defaults to `options.validFor`. */
+  readonly validFor?: string;
+  /** Profile fields to fill in on sign-up. */
+  readonly prefill?: Readonly<Record<string, unknown>>;
+}
+interface Invitation {
+  readonly id: string;
+  readonly organizationId: string | null;
+  readonly email: string;
+  readonly role: string;
+  readonly expiresAt: Temporal.Instant;
+  readonly invitedBy?: string;
+  readonly prefill: Readonly<Record<string, unknown>>;
+}
+/** What `onInvite` receives: the place to send the email. */
+interface InvitationSent {
+  readonly invitation: Invitation;
+  /** Put it in the accept link. It is never stored in plain text by default. */
+  readonly token: string;
+  readonly resent: boolean;
+}
+type InvitationStatus = "pending" | "accepted" | "declined" | "revoked" | "expired";
+interface InvitationPreview {
+  readonly status: InvitationStatus;
+  readonly email: string;
+  readonly role: string;
+  readonly organizationId: string | null;
+  readonly expiresAt: Temporal.Instant;
+  /** The organization columns in `options.previewColumns`. */
+  readonly organization: Readonly<Record<string, unknown>> | null;
+  readonly prefill: Readonly<Record<string, unknown>>;
+}
+interface SwitchResult {
+  readonly organizationId: string;
+  /** The active tenant is a claim: refresh the session to get it. */
+  readonly refresh: boolean;
+}
+interface OrgsOptions {
+  /** `sqlTransport(postgres.asUser(claims))` or `rpcTransport(supabase)`. */
+  readonly transport: KitTransport;
+  /**
+   * The schema holding the functions: `kits.<module>.schema` with
+   * `sqlTransport`, the exposed API schema of wrappers with `rpcTransport`.
+   * One schema for both modules, or one per module. Defaults to
+   * `better_supabase`.
+   */
+  readonly schema?: string | {
+    readonly organizations?: string;
+    readonly invitations?: string;
+  };
+  /** `betterSupabase.events`, to emit `org.*` and `invitation.*` kit events. */
+  readonly events?: EventHub;
+  /** The user acting, for event metadata. */
+  readonly actorId?: string;
+  readonly context?: RequestContext;
+  /**
+   * Runs before an invitation is created, after the database checks the
+   * caller may invite. Return `false` to refuse (seat limits, plans).
+   */
+  readonly canInvite?: (request: InviteRequest) => boolean | Promise<boolean>;
+  /**
+   * Runs after an invitation is created or resent, to send the email. When
+   * it throws, the call returns an error and the invitation stays open:
+   * call `resendInvitation` to retry.
+   */
+  readonly onInvite?: (sent: InvitationSent) => void | Promise<void>;
+  /** Run before the built-in mapping, as in `betterSupabase.mapError()`. */
+  readonly errorMappers?: readonly ErrorMapper[];
+}
+/**
+ * The `organizations` and `invitations` SQL kit modules as typed calls. Each
+ * method returns an `AsyncResult`; database errors carry the kit's error
+ * code (`ORG_FORBIDDEN`, `INVITATION_INVALID`) as `hint`.
+ */
+interface Orgs {
+  create(attributes: OrgAttributes, options?: CreateOrgOptions): AsyncResult<{
+    readonly id: string;
+  }>;
+  update(organizationId: string, attributes: OrgAttributes): AsyncResult<true>;
+  /** `false` when it did not exist (or was already soft-deleted). */
+  delete(organizationId: string): AsyncResult<boolean>;
+  /** Why a slug can't be used, or `undefined` when it can. */
+  slugProblem(slug: string, exceptOrganizationId?: string): AsyncResult<SlugProblem | undefined>;
+  updateMemberRole(organizationId: string, userId: string, role: string): AsyncResult<true>;
+  removeMember(organizationId: string, userId: string): AsyncResult<true>;
+  leave(organizationId: string): AsyncResult<true>;
+  /** `formerRole` defaults to `options.formerOwnerRole`. */
+  transferOwnership(organizationId: string, newOwnerId: string, formerRole?: string): AsyncResult<true>;
+  markUsed(organizationId: string): AsyncResult<boolean>;
+  switch(organizationId: string): AsyncResult<SwitchResult>;
+  invite(request: InviteRequest): AsyncResult<InvitationSent>;
+  resendInvitation(invitationId: string, validFor?: string): AsyncResult<InvitationSent>;
+  /** `false` when it was not open. */
+  revokeInvitation(invitationId: string): AsyncResult<boolean>;
+  declineInvitation(token: string): AsyncResult<boolean>;
+  /** `undefined` for an unknown token. Callable without a session. */
+  previewInvitation(token: string): AsyncResult<InvitationPreview | undefined>;
+  /** Returns the organization joined, `null` for a platform invitation. */
+  acceptInvitation(token: string): AsyncResult<{
+    readonly organizationId: string | null;
+  }>;
+}
+/** Calls the `organizations` and `invitations` kit functions. */
+export declare function createOrgs(options: OrgsOptions): Orgs;
+//#endregion
+export { type CreateOrgOptions, type Invitation, type InvitationPreview, type InvitationSent, type InvitationStatus, type InviteRequest, type KitTransport, type OrgAttributes, type Orgs, type OrgsOptions, type RpcClient, type SlugProblem, type SwitchResult, rpcTransport, sqlTransport };

package/dist/orgs/index.js

@@ -0,0 +1,245 @@
+import { c as mapDbError, n as dbError } from "../errors-DtwXa6b8.js";
+import { t as temporal } from "../temporal-required-CAt4Dc9Z.js";
+import { i as ok, n as err, o as toDbError, t as AsyncResult } from "../result-BKiliPY7.js";
+import { n as emitKitEvent } from "../kit-events-CTFDfSwb.js";
+import { n as rpcTransport, r as sqlTransport, t as rawError } from "../kit-transport-DJlHQUBU.js";
+//#region src/orgs/orgs.ts
+const DEFAULT_SCHEMA = "better_supabase";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => typeof value === "string" ? value : String(value);
+const optionalText = (value) => value === null || value === void 0 ? null : text(value);
+function invitationFrom(row) {
+	const invitedBy = optionalText(row["invited_by"]);
+	return {
+		id: text(row["id"]),
+		organizationId: optionalText(row["tenant"]),
+		email: text(row["email"]),
+		role: text(row["role"]),
+		expiresAt: temporal().Instant.from(text(row["expires_at"])),
+		...invitedBy === null ? {} : { invitedBy },
+		prefill: isRecord(row["prefill"]) ? row["prefill"] : {}
+	};
+}
+const STATUSES = /* @__PURE__ */ new Set([
+	"pending",
+	"accepted",
+	"declined",
+	"revoked",
+	"expired"
+]);
+function isStatus(value) {
+	return typeof value === "string" && STATUSES.has(value);
+}
+function previewFrom(row) {
+	const status = row["status"];
+	if (!isStatus(status)) throw new TypeError(`Unknown invitation status ${String(status)}`);
+	return {
+		status,
+		email: text(row["email"]),
+		role: text(row["role"]),
+		organizationId: optionalText(row["tenant"]),
+		expiresAt: temporal().Instant.from(text(row["expires_at"])),
+		organization: isRecord(row["organization"]) ? row["organization"] : null,
+		prefill: isRecord(row["prefill"]) ? row["prefill"] : {}
+	};
+}
+function recordOf(value, fn) {
+	if (!isRecord(value)) throw new TypeError(`${fn} returned ${JSON.stringify(value)}`);
+	return value;
+}
+/** Calls the `organizations` and `invitations` kit functions. */
+function createOrgs(options) {
+	const { transport } = options;
+	const schemaOf = (module) => typeof options.schema === "string" ? options.schema : options.schema?.[module] ?? DEFAULT_SCHEMA;
+	const mappers = options.errorMappers ?? [];
+	function run(module, fn, args, then) {
+		return AsyncResult.from(async () => {
+			let value;
+			try {
+				value = await transport.call(schemaOf(module), fn, args);
+			} catch (cause) {
+				const raw = rawError(cause);
+				return err(raw ? mapDbError(raw, mappers) : toDbError(cause));
+			}
+			return ok(await then(value));
+		});
+	}
+	function emit(type, data, subject, tenant) {
+		if (!options.events) return;
+		emitKitEvent(options.events, type, data, {
+			subject,
+			...tenant ? { tenant } : {},
+			...options.actorId ? { actorId: options.actorId } : {},
+			...options.context ? { context: options.context } : {}
+		});
+	}
+	const orgEvent = (type, data) => {
+		emit(type, data, `organizations/${data.organizationId}`, data.organizationId);
+	};
+	const invitationEvent = (type, data) => {
+		emit(type, data, `invitations/${data.invitationId}`, data.organizationId ?? null);
+	};
+	const sent = async (value, fn, resent) => {
+		const row = recordOf(value, fn);
+		const invitation = invitationFrom(row);
+		const result = {
+			invitation,
+			token: text(row["token"]),
+			resent
+		};
+		invitationEvent(resent ? "invitation.resent" : "invitation.created", {
+			invitationId: invitation.id,
+			...invitation.organizationId === null ? {} : { organizationId: invitation.organizationId },
+			email: invitation.email,
+			role: invitation.role
+		});
+		await options.onInvite?.(result);
+		return result;
+	};
+	return {
+		create(attributes, createOptions) {
+			return run("organizations", "create_organization", { attrs: {
+				...attributes,
+				...createOptions?.ownerId ? { owner_id: createOptions.ownerId } : {}
+			} }, (value) => {
+				const id = text(value);
+				orgEvent("org.created", {
+					organizationId: id,
+					...createOptions?.ownerId ?? options.actorId ? { userId: createOptions?.ownerId ?? options.actorId } : {}
+				});
+				return { id };
+			});
+		},
+		update(organizationId, attributes) {
+			return run("organizations", "update_organization", {
+				org: organizationId,
+				attrs: attributes
+			}, () => {
+				orgEvent("org.updated", { organizationId });
+				return true;
+			});
+		},
+		delete(organizationId) {
+			return run("organizations", "delete_organization", { org: organizationId }, (value) => {
+				if (value === true) orgEvent("org.deleted", { organizationId });
+				return value === true;
+			});
+		},
+		slugProblem(slug, exceptOrganizationId) {
+			return run("organizations", "organization_slug_problem", {
+				value: slug,
+				except_org: exceptOrganizationId
+			}, (value) => {
+				if (value === null) return;
+				if (value === "invalid" || value === "reserved" || value === "taken") return value;
+				throw new TypeError(`Unknown slug problem ${String(value)}`);
+			});
+		},
+		updateMemberRole(organizationId, userId, role) {
+			return run("organizations", "update_member_role", {
+				org: organizationId,
+				member: userId,
+				role
+			}, () => {
+				orgEvent("org.role_changed", {
+					organizationId,
+					userId,
+					role
+				});
+				return true;
+			});
+		},
+		removeMember(organizationId, userId) {
+			return run("organizations", "remove_member", {
+				org: organizationId,
+				member: userId
+			}, () => {
+				orgEvent("org.member_removed", {
+					organizationId,
+					userId
+				});
+				return true;
+			});
+		},
+		leave(organizationId) {
+			return run("organizations", "leave_organization", { org: organizationId }, () => {
+				orgEvent("org.member_left", {
+					organizationId,
+					...options.actorId ? { userId: options.actorId } : {}
+				});
+				return true;
+			});
+		},
+		transferOwnership(organizationId, newOwnerId, formerRole) {
+			return run("organizations", "transfer_ownership", {
+				org: organizationId,
+				new_owner: newOwnerId,
+				former_role: formerRole
+			}, () => {
+				orgEvent("org.ownership_transferred", {
+					organizationId,
+					userId: newOwnerId
+				});
+				return true;
+			});
+		},
+		markUsed(organizationId) {
+			return run("organizations", "mark_used", { org: organizationId }, (value) => value === true);
+		},
+		switch(organizationId) {
+			return run("organizations", "switch_organization", { org: organizationId }, (value) => {
+				const row = recordOf(value, "switch_organization");
+				orgEvent("org.switched", {
+					organizationId,
+					...options.actorId ? { userId: options.actorId } : {}
+				});
+				return {
+					organizationId: text(row["organization_id"]),
+					refresh: row["refresh"] === true
+				};
+			});
+		},
+		invite(request) {
+			return AsyncResult.from(async () => {
+				if (options.canInvite && !await options.canInvite(request)) return err(dbError("forbidden", "The invitation was refused", { hint: "INVITATION_FORBIDDEN" }));
+				return run("invitations", "invite_member", {
+					tenant: request.organizationId,
+					invitee_email: request.email,
+					invitee_role: request.role,
+					valid_for: request.validFor,
+					prefill: request.prefill
+				}, (value) => sent(value, "invite_member", false));
+			});
+		},
+		resendInvitation(invitationId, validFor) {
+			return run("invitations", "resend_invitation", {
+				invitation_id: invitationId,
+				valid_for: validFor
+			}, (value) => sent(value, "resend_invitation", true));
+		},
+		revokeInvitation(invitationId) {
+			return run("invitations", "revoke_invitation", { invitation_id: invitationId }, (value) => {
+				if (value === true) invitationEvent("invitation.revoked", { invitationId });
+				return value === true;
+			});
+		},
+		declineInvitation(token) {
+			return run("invitations", "decline_invitation", { token }, (value) => value === true);
+		},
+		previewInvitation(token) {
+			return run("invitations", "invitation_preview", { token }, (value) => value === null ? void 0 : previewFrom(recordOf(value, "invitation_preview")));
+		},
+		acceptInvitation(token) {
+			return run("invitations", "accept_invitation", { token }, (value) => {
+				const organizationId = optionalText(value);
+				if (organizationId !== null) orgEvent("org.member_added", {
+					organizationId,
+					...options.actorId ? { userId: options.actorId } : {}
+				});
+				return { organizationId };
+			});
+		}
+	};
+}
+//#endregion
+export { createOrgs, rpcTransport, sqlTransport };

package/dist/orpc/index.d.ts

@@ -1,9 +1,9 @@
-import { n as AnyModels, t as AnyFunctions } from "../types-DONv9SHN.js";
-import { o as Result, p as DbError } from "../result-CqEsbgYs.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 { r as ProblemDetails } from "../problem-U8UEKccv.js";
+import { n as AnyFunctions, r as AnyModels } from "../types-Dnf_wRDz.js";
+import { _ as DbError, u as Result } from "../executor-BunPOO-k.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 { r as ProblemDetails } from "../problem-Blxe8S31.js";
 import { DecoratedMiddleware, ORPCError } from "@orpc/server";
 //#region src/orpc/index.d.ts
 /** Initial context: pass `{ context: { request } }` to the oRPC handler. */
@@ -20,15 +20,35 @@ export interface OrpcOptions extends ServerOptions {
   /** Include internal error messages. Defaults to `NODE_ENV === 'development'`. */
   readonly exposeErrors?: boolean;
 }
+/** The part of an oRPC fetch handler (`RPCHandler`, `OpenAPIHandler`) `fetchHandler` calls. */
+export interface OrpcFetchHandler {
+  handle(request: Request, options: {
+    readonly prefix?: `/${string}`;
+    readonly context: OrpcRequestContext;
+  }): Promise<{
+    readonly matched: boolean;
+    readonly response?: Response | undefined;
+  }>;
+}
+export interface OrpcFetchOptions {
+  /** Path prefix the router is mounted under, e.g. `/rpc`. */
+  readonly prefix?: `/${string}`;
+}
 export type OrpcMiddleware<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> = DecoratedMiddleware<OrpcRequestContext, OrpcContext<M, F, E, C, P>, unknown, unknown, Record<never, never>>;
 export interface BetterOrpc<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown> extends BetterServer<M, F, E, C, P> {
   /**
    * Resolves the caller, enforces `allow` and adds `context.db`, `context.auth`
    * and `context.bs`. Thrown `DbException`s, and errors caused by a
-   * `DbError`, become `ORPCError`s. With `refresh`, pair it with
-   * `ctx.bs.resolution.apply` in the handler adapter.
+   * `DbError`, become `ORPCError`s. Serve the router with `fetchHandler` so
+   * refreshed session cookies and `bs-primary-until` reach the response.
    */
   middleware(options?: MiddlewareOptions): OrpcMiddleware<M, F, E, C, P>;
+  /**
+   * A fetch handler for an oRPC handler: passes `{ request }` as the initial
+   * context, answers 404 when no procedure matched, and applies the cookies
+   * of the request's context (`ctx.apply`).
+   */
+  fetchHandler(handler: OrpcFetchHandler, options?: OrpcFetchOptions): (request: Request) => Promise<Response>;
   /** A `Result` (or `AsyncResult`) as data, throwing an `ORPCError` on failure. */
   unwrap<T>(value: Result<T> | PromiseLike<Result<T>>): Promise<T>;
   /** Plain values pass through; thrown `DbException`s become `ORPCError`s. */

package/dist/orpc/index.js

@@ -1,6 +1,6 @@
-import { r as dbErrorOf } from "../errors-L0xK41y_.js";
-import { o as toProblem } from "../problem-BihjPR0t.js";
-import { a as guard, c as settle, i as defaultExpose, n as extendServer, t as createServer } from "../server-BA75B0mT.js";
+import { r as dbErrorOf } from "../errors-DtwXa6b8.js";
+import { o as toProblem } from "../problem-BW1KhzSG.js";
+import { d as guard, m as settle, n as createServer, r as extendServer, u as defaultExpose } from "../server-Csx2sRjg.js";
 import { COMMON_ERROR_STATUS_MAP, ORPCError, os } from "@orpc/server";
 //#region src/orpc/index.ts
 const CODES = /* @__PURE__ */ new Map(Object.entries(COMMON_ERROR_STATUS_MAP).map(([code, status]) => [status, code]));
@@ -12,6 +12,7 @@ function orpcCode(error) {
 function createOrpc(betterSupabase, options = {}) {
 	const server = createServer(betterSupabase, options);
 	const expose = options.exposeErrors ?? defaultExpose();
+	const contexts = /* @__PURE__ */ new WeakMap();
 	const toOrpcError = (error) => {
 		const problem = toProblem(error, { expose });
 		return new ORPCError(orpcCode(error), {
@@ -26,6 +27,7 @@ function createOrpc(betterSupabase, options = {}) {
 				const ctx = await server.context(context.request, { refresh: middlewareOptions.refresh ?? false });
 				const denied = guard(ctx.auth, middlewareOptions.allow, middlewareOptions.aal, middlewareOptions.scopes);
 				if (denied) throw toOrpcError(denied);
+				contexts.set(context.request, ctx);
 				try {
 					return await next({ context: {
 						bs: ctx,
@@ -39,6 +41,17 @@ function createOrpc(betterSupabase, options = {}) {
 				}
 			});
 		},
+		fetchHandler(handler, fetchOptions = {}) {
+			return async (request) => {
+				const { response } = await handler.handle(request, {
+					...fetchOptions.prefix ? { prefix: fetchOptions.prefix } : {},
+					context: { request }
+				});
+				const ctx = contexts.get(request);
+				const answer = response ?? new Response("Not found", { status: 404 });
+				return ctx ? ctx.apply(answer) : answer;
+			};
+		},
 		async unwrap(value) {
 			const settled = await settle(() => value);
 			if (!settled.ok) throw toOrpcError(settled.error);

package/dist/otel/index.d.ts

@@ -1,5 +1,5 @@
-import { a as EventHub } from "../events-B21UOhvP.js";
-import { f as Plugin } from "../plugin-bNhvJwRh.js";
+import { a as EventHub } from "../events-aIO7vsIk.js";
+import { p as Plugin } from "../plugin-o144f322.js";
 import { t as SPEC_PINS } from "../spec-pins-CqorWDnO.js";
 import { Attributes, Meter, Tracer } from "@opentelemetry/api";
 //#region src/otel/index.d.ts
@@ -13,6 +13,16 @@ export interface OtelOptions {
   readonly attributes?: Attributes;
   /** Set `false` to skip the duration histogram. */
   readonly metrics?: boolean;
+  /**
+   * The database name in `db.namespace` (`{database}|{schema}`). Supabase
+   * names it `postgres`, the default for Postgres executors.
+   */
+  readonly database?: string;
+  /** `server.address` and `server.port` on spans and metrics, e.g. the project host. */
+  readonly server?: {
+    readonly address: string;
+    readonly port?: number;
+  };
 }
 /**
  * Database client spans and metrics for every repository operation, using
@@ -31,6 +41,15 @@ export declare function otel(options?: OtelOptions): Plugin<"otel">;
 export declare function traceAuth(betterSupabase: {
   readonly events: EventHub;
 }, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
+/**
+ * Records kit events (`support.started`, `webhook.failed`, ...) with the
+ * `KIT_ATTRIBUTES` names: as an event on the active span, or as a short
+ * `kit <type>` span when there is none. Failures (`*.failed`, `*.denied`)
+ * set an error status. Returns a function that stops listening.
+ */
+export declare function traceKitEvents(betterSupabase: {
+  readonly events: EventHub;
+}, options?: Pick<OtelOptions, "tracer" | "attributes">): () => void;
 /**
  * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
  * context. Pass it to `createClient(url, key, { global: { fetch } })` so

package/dist/otel/index.js

@@ -1,11 +1,21 @@
-import { n as definePlugin } from "../plugin-BqR6wKMB.js";
+import { r as definePlugin } from "../plugin-DwARMuQp.js";
 import { t as SPEC_PINS } from "../spec-pins-C3oc-Tdp.js";
-import "../version-Bmf7_FzM.js";
+import { r as kitEventAttributes } from "../kit-events-CTFDfSwb.js";
+import "../version-DM_Roffb.js";
 import { SpanKind, SpanStatusCode, context, metrics, propagation, trace } from "@opentelemetry/api";
 //#region src/otel/index.ts
 const INSTRUMENTATION_NAME = "better-supabase";
 /** OpenTelemetry semantic conventions version the attributes follow. */
 const SEMCONV_VERSION = SPEC_PINS.otelSemconv;
+/** A five-character SQLSTATE; PostgREST's own codes (`PGRST116`) are not one. */
+const SQLSTATE = /^[0-9A-Z]{5}$/;
+function serverAttributes(server) {
+	if (!server) return {};
+	return server.port === void 0 ? { "server.address": server.address } : {
+		"server.address": server.address,
+		"server.port": server.port
+	};
+}
 const OPERATION_NAME = {
 	select: "SELECT",
 	insert: "INSERT",
@@ -30,9 +40,9 @@ function systemOf(executor) {
 * ```
 */
 function otel(options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.4.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
 	let histogram;
-	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.4.0")).createHistogram("db.client.operation.duration", {
+	if (options.metrics !== false) histogram = (options.meter ?? metrics.getMeter("better-supabase", "0.5.0")).createHistogram("db.client.operation.duration", {
 		unit: "s",
 		description: "Duration of database client operations.",
 		advice: { explicitBucketBoundaries: [
@@ -52,6 +62,8 @@ function otel(options = {}) {
 		enforce: "post",
 		wrapExecutor: (executor) => {
 			const system = systemOf(executor);
+			const database = options.database ?? (system === "postgresql" ? "postgres" : void 0);
+			const server = serverAttributes(options.server);
 			/** Span and metric attributes per table and operation, built once. */
 			const described = /* @__PURE__ */ new Map();
 			const describe = (op) => {
@@ -65,13 +77,15 @@ function otel(options = {}) {
 						attributes: {
 							...options.attributes,
 							"db.system.name": system,
-							"db.namespace": op.table.schema,
+							"db.namespace": database ? `${database}|${op.table.schema}` : op.table.schema,
 							"db.collection.name": op.table.name,
 							"db.operation.name": operation,
 							"db.query.summary": summary,
-							"better_supabase.executor": executor.name
+							"better_supabase.executor": executor.name,
+							...server
 						},
 						metric: {
+							...server,
 							"db.system.name": system,
 							"db.collection.name": op.table.name,
 							"db.operation.name": operation
@@ -106,7 +120,7 @@ function otel(options = {}) {
 							} else {
 								span.setAttributes({
 									"error.type": result.error.kind,
-									...result.error.code ? { "db.response.status_code": result.error.code } : {}
+									...result.error.code && SQLSTATE.test(result.error.code) ? { "db.response.status_code": result.error.code } : {}
 								});
 								span.setStatus({
 									code: SpanStatusCode.ERROR,
@@ -137,7 +151,7 @@ function otel(options = {}) {
 * Returns a function that stops listening.
 */
 function traceAuth(betterSupabase, options = {}) {
-	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.4.0");
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
 	const offAuth = betterSupabase.events.on("auth", (event) => {
 		const span = tracer.startSpan("auth.resolve", {
 			kind: SpanKind.INTERNAL,
@@ -169,6 +183,33 @@ function traceAuth(betterSupabase, options = {}) {
 	};
 }
 /**
+* Records kit events (`support.started`, `webhook.failed`, ...) with the
+* `KIT_ATTRIBUTES` names: as an event on the active span, or as a short
+* `kit <type>` span when there is none. Failures (`*.failed`, `*.denied`)
+* set an error status. Returns a function that stops listening.
+*/
+function traceKitEvents(betterSupabase, options = {}) {
+	const tracer = options.tracer ?? trace.getTracer("better-supabase", "0.5.0");
+	return betterSupabase.events.on("kit", (event) => {
+		const attributes = {
+			...options.attributes,
+			...kitEventAttributes(event)
+		};
+		const failed = event.type.endsWith(".failed") || event.type.endsWith(".denied");
+		const active = trace.getActiveSpan();
+		if (active) {
+			active.addEvent(event.type, attributes);
+			return;
+		}
+		const span = tracer.startSpan(`kit ${event.type}`, {
+			kind: SpanKind.INTERNAL,
+			attributes
+		});
+		if (failed) span.setStatus({ code: SpanStatusCode.ERROR });
+		span.end();
+	});
+}
+/**
 * A `fetch` that adds W3C `traceparent`/`tracestate` from the active
 * context. Pass it to `createClient(url, key, { global: { fetch } })` so
 * PostgREST, Auth and Storage calls join the trace.
@@ -186,4 +227,4 @@ function tracedFetch(base = fetch) {
 	};
 }
 //#endregion
-export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, tracedFetch };
+export { INSTRUMENTATION_NAME, SEMCONV_VERSION, otel, traceAuth, traceKitEvents, tracedFetch };

package/dist/permdock-sql-C2Inc6Xc.d.ts

@@ -0,0 +1,29 @@
+//#region src/core/permdock-sql.d.ts
+/** PermDock's default `rls.schema`, a schema the Data API does not expose. */
+declare const PERMDOCK_SCHEMA = "permdock";
+/**
+ * The part of PermDock's `permissions.catalog.json` the Storage and Realtime
+ * builders read: `import catalog from './permissions.catalog.json'`.
+ */
+interface PermdockCatalog {
+  readonly permissions: readonly {
+    readonly key: string;
+    readonly rowConditions?: boolean;
+    /** The scope PermDock declares the permission at. */
+    readonly scope?: string;
+  }[];
+}
+/**
+ * What PermDock's catalog says about a key: `scope-only` (`rowConditions:
+ * false`), `row-conditions` (`true`), `no-flag` (an entry without a boolean
+ * flag, from an older `permdock catalog`) or `missing`. Only `scope-only` is
+ * safe for the SQL helpers.
+ */
+type PermdockKeyStatus = "scope-only" | "row-conditions" | "no-flag" | "missing";
+declare function permdockKeyStatus(catalog: PermdockCatalog, key: string): PermdockKeyStatus;
+/** The keys a bucket or topic PermDock policy names. */
+declare function permdockKeys(policy: {
+  readonly permdock: object;
+}): string[];
+//#endregion
+export { permdockKeys as a, permdockKeyStatus as i, PermdockCatalog as n, PermdockKeyStatus as r, PERMDOCK_SCHEMA as t };