better-supabase 0.7.1 → 0.9.0

package/dist/blocks/search/index.d.ts

@@ -0,0 +1,31 @@
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { i as EventSink } from "../../cloud-event-5rCEzIgK.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { _ as createSearch, a as createCommandSearchController, d as Search, f as SearchHit, g as SearchUserItem, h as SearchQuery, i as CommandSearchSnapshot, l as Embedder, m as SearchOptions, n as CommandSearchController, p as SearchListOptions, r as CommandSearchOptions, t as CommandSearchActions, u as PendingEmbedding } from "../../client-ClZ0D-if.js";
+//#region src/blocks/search/sink.d.ts
+/** What an event does to the index. */
+type SearchSinkAction = "remove" | "refresh";
+/**
+ * The events a soft-delete block emits, as `searchSink` handles them by
+ * default: trashing or purging drops the subject, restoring reads it again.
+ */
+export declare const SEARCH_SINK_DEFAULTS: Readonly<Record<string, SearchSinkAction>>;
+interface SearchSinkOptions {
+  /** Event type (without `typePrefix`) to its action. Default `SEARCH_SINK_DEFAULTS`. */
+  readonly on?: Readonly<Record<string, SearchSinkAction | undefined>>;
+  /** Stripped from each event type. Defaults to `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+/**
+ * An outbox sink that keeps the index in step with soft deletes the
+ * registry's `deletedAt` column doesn't describe, such as a trash table:
+ * `outbox.relay('search', searchSink(search))`. Build `search` with a
+ * service transport. A subject type without a `search` entry is skipped.
+ */
+export declare function searchSink(search: Pick<Search, "remove" | "refresh">, options?: SearchSinkOptions): EventSink;
+//#endregion
+//#region src/blocks/search/manifest.d.ts
+/** The `search` block's manifest (ADR 0029). */
+export declare const searchBlock: BlockOf<"search", typeof createSearch, Record<never, never>, Record<never, never>, "sink">;
+//#endregion
+export { type BlockTransport, type CommandSearchActions, type CommandSearchController, type CommandSearchOptions, type CommandSearchSnapshot, type Embedder, type PendingEmbedding, type Search, type SearchHit, type SearchListOptions, type SearchOptions, type SearchQuery, type SearchSinkAction, type SearchSinkOptions, type SearchUserItem, createCommandSearchController, createSearch, dbTransport, rpcTransport, sqlTransport };

package/dist/blocks/search/index.js

@@ -0,0 +1,61 @@
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { a as stripTypePrefix } from "../../cloud-event-CTh9Sr5w.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { C as optionalText } from "../../block-helpers-CfG_MvDR.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { t as createSearch } from "../../search-B6h03cAx.js";
+import { t as createCommandSearchController } from "../../client-BfgwocyT.js";
+import { t as searchSqlOptions } from "../../options-DYBQ973I.js";
+//#region src/blocks/search/sink.ts
+/**
+* The events a soft-delete block emits, as `searchSink` handles them by
+* default: trashing or purging drops the subject, restoring reads it again.
+*/
+const SEARCH_SINK_DEFAULTS = {
+	"subject.trashed": "remove",
+	"subject.purged": "remove",
+	"subject.restored": "refresh"
+};
+function subjectOf(event) {
+	if (!isRecord(event.data)) return;
+	const type = optionalText(event.data["subjectType"]);
+	const id = optionalText(event.data["subjectId"]);
+	return type === void 0 || id === void 0 ? void 0 : {
+		type,
+		id
+	};
+}
+/**
+* An outbox sink that keeps the index in step with soft deletes the
+* registry's `deletedAt` column doesn't describe, such as a trash table:
+* `outbox.relay('search', searchSink(search))`. Build `search` with a
+* service transport. A subject type without a `search` entry is skipped.
+*/
+function searchSink(search, options = {}) {
+	const actions = options.on ?? SEARCH_SINK_DEFAULTS;
+	return { async send(events) {
+		for (const event of events) {
+			const action = actions[stripTypePrefix(event.type, options.typePrefix)];
+			if (action === void 0) continue;
+			const subject = subjectOf(event);
+			if (subject === void 0) continue;
+			const result = action === "remove" ? await search.remove(subject.type, subject.id) : await search.refresh(subject.type, subject.id);
+			if (!result.ok && result.error.hint !== "SEARCH_SUBJECT_UNKNOWN") throw new Error(`searchSink: ${action} ${subject.type}/${subject.id} failed: ${result.error.message}`);
+		}
+	} };
+}
+//#endregion
+//#region src/blocks/search/manifest.ts
+/** The `search` block's manifest (ADR 0029). */
+const searchBlock = defineBlock({
+	name: "search",
+	sql: ["search"],
+	options: { search: searchSqlOptions },
+	provides: { sink: (client) => searchSink(client) },
+	create: createSearch,
+	client: "search",
+	category: "work",
+	recipes: ["command-search"]
+});
+//#endregion
+export { SEARCH_SINK_DEFAULTS, createCommandSearchController, createSearch, dbTransport, rpcTransport, searchBlock, searchSink, sqlTransport };

package/dist/blocks/search/react/index.d.ts

@@ -0,0 +1,36 @@
+import { c as groupHits, i as CommandSearchSnapshot, o as CommandSearchGroup, s as CommandSearchItem, t as CommandSearchActions } from "../../../client-ClZ0D-if.js";
+//#region src/blocks/search/react/index.d.ts
+export interface UseCommandSearchOptions {
+  /** One tenant. Default: every tenant the caller can read. */
+  readonly organizationId?: string | null;
+  readonly types?: readonly string[];
+  /** Results per query. Default 20. */
+  readonly limit?: number;
+  /** Recents and favorites shown before the user types. Default 5. */
+  readonly listLimit?: number;
+  /** Milliseconds between the last keystroke and the query. Default 150. */
+  readonly debounceMs?: number;
+  /**
+   * Toggles the dialog on Cmd+K and Ctrl+K through the client's keyboard
+   * port (`webKeyboard()` on the web; none on React Native). Default true.
+   */
+  readonly shortcut?: boolean;
+  /** The schema the calls go to: the module schema (default `better_supabase`), or the API schema from `blocks.<module>.api`. */
+  readonly schema?: string;
+}
+export interface CommandSearchState extends CommandSearchSnapshot, CommandSearchActions {}
+/**
+ * State for a Cmd+K dialog over the `search` module: a debounced query that
+ * ignores stale responses, favorites and recents for an empty query, and
+ * `select` that records the open. Render it with any command palette.
+ *
+ * ```tsx
+ * const search = useCommandSearch({ organizationId });
+ * <CommandDialog open={search.open} onOpenChange={search.setOpen}>
+ *   <CommandInput value={search.query} onValueChange={search.setQuery} />
+ * </CommandDialog>
+ * ```
+ */
+export declare function useCommandSearch(options?: UseCommandSearchOptions): CommandSearchState;
+//#endregion
+export { type CommandSearchGroup, type CommandSearchItem, groupHits };

package/dist/blocks/search/react/index.js

@@ -0,0 +1,49 @@
+"use client";
+import { r as rpcTransport } from "../../../block-transport-G4t1umrR.js";
+import { t as useController } from "../../../react-controller-Xn-IU44p.js";
+import { t as useBlockEnv } from "../../../react-env-Cc7Vf6eb.js";
+import { t as createSearch } from "../../../search-B6h03cAx.js";
+import { t as groupHits } from "../../../groups-CxonH3u5.js";
+import { t as createCommandSearchController } from "../../../client-BfgwocyT.js";
+//#region src/blocks/search/react/index.ts
+/**
+* State for a Cmd+K dialog over the `search` module: a debounced query that
+* ignores stale responses, favorites and recents for an empty query, and
+* `select` that records the open. Render it with any command palette.
+*
+* ```tsx
+* const search = useCommandSearch({ organizationId });
+* <CommandDialog open={search.open} onOpenChange={search.setOpen}>
+*   <CommandInput value={search.query} onValueChange={search.setQuery} />
+* </CommandDialog>
+* ```
+*/
+function useCommandSearch(options = {}) {
+	const { supabase, ports } = useBlockEnv();
+	const { schema, organizationId, limit, listLimit, debounceMs } = options;
+	const keyboard = options.shortcut ?? true ? ports.keyboard : void 0;
+	const typesKey = options.types?.join("\0") ?? null;
+	return useController(() => createCommandSearchController({
+		client: createSearch({
+			transport: rpcTransport(supabase),
+			...schema === void 0 ? {} : { schema }
+		}),
+		...keyboard === void 0 ? {} : { keyboard },
+		organizationId: organizationId ?? null,
+		...typesKey === null ? {} : { types: typesKey.split("\0") },
+		...limit === void 0 ? {} : { limit },
+		...listLimit === void 0 ? {} : { listLimit },
+		...debounceMs === void 0 ? {} : { debounceMs }
+	}), [
+		supabase,
+		schema,
+		keyboard,
+		organizationId,
+		typesKey,
+		limit,
+		listLimit,
+		debounceMs
+	]).view;
+}
+//#endregion
+export { groupHits, useCommandSearch };

package/dist/blocks/search/react/server.d.ts

@@ -0,0 +1,7 @@
+import { c as groupHits, o as CommandSearchGroup, s as CommandSearchItem } from "../../../client-ClZ0D-if.js";
+import { CommandSearchState, UseCommandSearchOptions } from "./index.js";
+//#region src/blocks/search/react/server.d.ts
+/** The `react-server` build of `useCommandSearch`: call `search.search()` instead. */
+export declare const useCommandSearch: (options?: UseCommandSearchOptions) => CommandSearchState;
+//#endregion
+export { type CommandSearchGroup, type CommandSearchItem, type CommandSearchState, type UseCommandSearchOptions, groupHits };

package/dist/blocks/search/react/server.js

@@ -0,0 +1,8 @@
+import { t as groupHits } from "../../../groups-CxonH3u5.js";
+//#region src/blocks/search/react/server.ts
+/** The `react-server` build of `useCommandSearch`: call `search.search()` instead. */
+const useCommandSearch = () => {
+	throw new Error("better-supabase: useCommandSearch() runs in Client Components only. In Server Components call `search.search()` instead.");
+};
+//#endregion
+export { groupHits, useCommandSearch };

package/dist/blocks/search/solid/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SolidController } from "../../../solid-controller-DqlvYFZa.js";
+import { i as CommandSearchSnapshot, r as CommandSearchOptions, t as CommandSearchActions } from "../../../client-ClZ0D-if.js";
+//#region src/blocks/search/solid/index.d.ts
+/**
+ * `createCommandSearchController` as a Solid primitive: `state()` reads the
+ * snapshot. Call it in a component; the work starts on mount and the controller
+ * is disposed with the owner. `auth` and `ports` default to the client of
+ * `<BetterSupabaseProvider client={bs}>`.
+ */
+export declare function useCommandSearch(options: BlockOptions<CommandSearchOptions>): SolidController<CommandSearchSnapshot, CommandSearchActions>;
+//#endregion
+export type { BlockOptions, CommandSearchActions, CommandSearchOptions, CommandSearchSnapshot, SolidController };

package/dist/blocks/search/solid/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../solid-controller-DLsmrczT.js";
+import { t as createCommandSearchController } from "../../../client-BfgwocyT.js";
+//#region src/blocks/search/solid/index.ts
+/**
+* `createCommandSearchController` as a Solid primitive: `state()` reads the
+* snapshot. Call it in a component; the work starts on mount and the controller
+* is disposed with the owner. `auth` and `ports` default to the client of
+* `<BetterSupabaseProvider client={bs}>`.
+*/
+function useCommandSearch(options) {
+	return useBlockController(createCommandSearchController, options, false);
+}
+//#endregion
+export { useCommandSearch };

package/dist/blocks/search/svelte/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as SvelteController } from "../../../svelte-controller-DxxHEHxD.js";
+import { i as CommandSearchSnapshot, r as CommandSearchOptions, t as CommandSearchActions } from "../../../client-ClZ0D-if.js";
+//#region src/blocks/search/svelte/index.d.ts
+/**
+ * `createCommandSearchController` as a Svelte readable store of the snapshot,
+ * with the actions on `.actions`. Call it in a component's script; the work
+ * starts on mount and the controller is disposed with the component. `auth` and
+ * `ports` default to the client of `setBetterSupabase(bs)`.
+ */
+export declare function useCommandSearch(options: BlockOptions<CommandSearchOptions>): SvelteController<CommandSearchSnapshot, CommandSearchActions>;
+//#endregion
+export type { BlockOptions, CommandSearchActions, CommandSearchOptions, CommandSearchSnapshot, SvelteController };

package/dist/blocks/search/svelte/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../svelte-controller-CDAujo-_.js";
+import { t as createCommandSearchController } from "../../../client-BfgwocyT.js";
+//#region src/blocks/search/svelte/index.ts
+/**
+* `createCommandSearchController` as a Svelte readable store of the snapshot,
+* with the actions on `.actions`. Call it in a component's script; the work
+* starts on mount and the controller is disposed with the component. `auth` and
+* `ports` default to the client of `setBetterSupabase(bs)`.
+*/
+function useCommandSearch(options) {
+	return useBlockController(createCommandSearchController, options, false);
+}
+//#endregion
+export { useCommandSearch };

package/dist/blocks/search/vue/index.d.ts

@@ -0,0 +1,13 @@
+import { t as BlockOptions } from "../../../block-env-Dxl7rsI0.js";
+import { t as VueController } from "../../../vue-controller-HPfMTDa2.js";
+import { i as CommandSearchSnapshot, r as CommandSearchOptions, t as CommandSearchActions } from "../../../client-ClZ0D-if.js";
+//#region src/blocks/search/vue/index.d.ts
+/**
+ * `createCommandSearchController` as a Vue composable: `state` is a shallow ref
+ * of the snapshot. Call it in `setup` or an effect scope; the work starts on
+ * mount and the controller is disposed with the scope. `auth` and `ports`
+ * default to the client of `app.use(betterSupabase(bs))`.
+ */
+export declare function useCommandSearch(options: BlockOptions<CommandSearchOptions>): VueController<CommandSearchSnapshot, CommandSearchActions>;
+//#endregion
+export type { BlockOptions, CommandSearchActions, CommandSearchOptions, CommandSearchSnapshot, VueController };

package/dist/blocks/search/vue/index.js

@@ -0,0 +1,14 @@
+import { t as useBlockController } from "../../../vue-controller-C9tFzqAc.js";
+import { t as createCommandSearchController } from "../../../client-BfgwocyT.js";
+//#region src/blocks/search/vue/index.ts
+/**
+* `createCommandSearchController` as a Vue composable: `state` is a shallow ref
+* of the snapshot. Call it in `setup` or an effect scope; the work starts on
+* mount and the controller is disposed with the scope. `auth` and `ports`
+* default to the client of `app.use(betterSupabase(bs))`.
+*/
+function useCommandSearch(options) {
+	return useBlockController(createCommandSearchController, options, false);
+}
+//#endregion
+export { useCommandSearch };

package/dist/blocks/service-principals/index.d.ts

@@ -0,0 +1,126 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { $ as SaasEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "../../block-hooks-BLPWD3Jt.js";
+import { i as RowFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+//#region src/blocks/service-principals/service-principals.d.ts
+/** The `app_metadata` key that marks an `auth.users` row as a service principal. */
+export declare const SERVICE_PRINCIPAL_CLAIM = "bs_service_principal";
+/**
+ * The part of `supabase.auth.admin` the block uses, typed structurally so
+ * any Supabase client fits.
+ */
+interface ServicePrincipalAuthAdmin {
+  createUser(attributes: {
+    email: string;
+    email_confirm: boolean;
+    ban_duration: string;
+    app_metadata: Record<string, unknown>;
+    user_metadata: Record<string, unknown>;
+  }): PromiseLike<{
+    data: {
+      user: {
+        id: string;
+      } | null;
+    };
+    error: {
+      message: string;
+    } | null;
+  }>;
+  deleteUser(id: string): PromiseLike<{
+    error: {
+      message: string;
+    } | null;
+  }>;
+}
+interface ServicePrincipalsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /** A service-role transport: every function but `list` is service only. */
+  readonly transport: BlockTransport;
+  /** `supabase.auth.admin` of a service-role client. */
+  readonly admin: ServicePrincipalAuthAdmin;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<ServicePrincipals<FieldsOf<S>>>>;
+  /**
+   * A Standard Schema for the extra columns of the principals table
+   * (`blocks.service-principals.options.extraColumns`): writes are
+   * validated, reads parsed.
+   */
+  readonly fields?: S;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface ServicePrincipal<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly name: string;
+  readonly role: string;
+  readonly isDefault: boolean;
+  readonly createdBy: string | null;
+  readonly createdAt: Temporal.Instant;
+  readonly disabledAt: Temporal.Instant | null;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: RowFields<F>;
+}
+/**
+ * Who asks for a change. With `createdBy`, that member needs
+ * `service_principals.manage` and may assign the role; without it the
+ * service acts on its own.
+ */
+interface ServicePrincipalActor {
+  readonly createdBy?: string;
+}
+interface CreateServicePrincipalOptions<F extends object = Record<never, never>> extends ServicePrincipalActor {
+  /** Makes it the tenant's default, which organization-owned work runs as. */
+  readonly default?: boolean;
+  /** Values for the app's extra columns (`options.extraColumns`). */
+  readonly fields?: Partial<F> & Readonly<Record<string, unknown>>;
+}
+interface CreatedServicePrincipal<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly name: string;
+  readonly role: string;
+  readonly isDefault: boolean;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: RowFields<F>;
+}
+/** The `service-principals` SQL module as typed calls. */
+interface ServicePrincipals<F extends object = Record<never, never>> {
+  /**
+   * Creates an `auth.users` row that can't sign in (banned, no password,
+   * an address under `.invalid`), then registers it with `role` in the
+   * organization. A refused registration deletes the user again.
+   */
+  readonly create: (organizationId: string, name: string, role: string, options?: CreateServicePrincipalOptions<F>) => AsyncResult<CreatedServicePrincipal<F>>;
+  readonly setRole: (id: string, role: string, options?: ServicePrincipalActor) => AsyncResult<boolean>;
+  /** Removes its membership and default; `false` when it was already off. */
+  readonly disable: (id: string, options?: ServicePrincipalActor) => AsyncResult<boolean>;
+  /** The organization's default principal, or `null`. */
+  readonly defaultFor: (organizationId: string) => AsyncResult<string | null>;
+  /** The organization's principals, through the read policy. */
+  readonly list: (organizationId: string) => AsyncResult<readonly ServicePrincipal<F>[]>;
+}
+export declare function createServicePrincipals<S extends StandardSchemaV1 | undefined = undefined>(options: ServicePrincipalsOptions<S>): ServicePrincipals<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/service-principals/events.d.ts
+/** The events of the `service-principals` block: type to data. */
+type ServicePrincipalsEvents = {
+  readonly "service_principal.created": SaasEventData;
+  readonly "service_principal.role_changed": SaasEventData;
+  readonly "service_principal.disabled": SaasEventData;
+};
+/** The `service-principals` block's event types, for its manifest and `onBlockEvent`. */
+export declare const servicePrincipalsEvents: Events<ServicePrincipalsEvents>;
+//#endregion
+//#region src/blocks/service-principals/manifest.d.ts
+/** The `service-principals` block's manifest (ADR 0029). */
+export declare const servicePrincipalsBlock: BlockOf<"service-principals", typeof createServicePrincipals, ServicePrincipalsEvents>;
+//#endregion
+export { type BlockTransport, type CreateServicePrincipalOptions, type CreatedServicePrincipal, type ServicePrincipal, type ServicePrincipalActor, type ServicePrincipalAuthAdmin, type ServicePrincipals, type ServicePrincipalsEvents, type ServicePrincipalsOptions, dbTransport, rpcTransport, sqlTransport };

package/dist/blocks/service-principals/index.js

@@ -0,0 +1,107 @@
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-BlgnMB0H.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { A as requiredInstant, D as recordOf, I as textOf, k as recordsOf, n as applyTemporal, o as blockCall, v as nullableInstant, y as nullableText } from "../../block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { a as readAllFields, n as blockFields, o as readFields, s as rowFields } from "../../block-fields-ffD6Gxe4.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { t as servicePrincipalsSqlOptions } from "../../options-B7EJaOX-.js";
+//#region src/blocks/service-principals/service-principals.ts
+/** The `app_metadata` key that marks an `auth.users` row as a service principal. */
+const SERVICE_PRINCIPAL_CLAIM = "bs_service_principal";
+/** About 100 years: GoTrue refuses every sign-in while the user is banned. */
+const BAN_DURATION = "876000h";
+function createServicePrincipals(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "service principal fields");
+	const { admin } = options;
+	return withBlockHooks({
+		create: (organizationId, name, role, extra = {}) => AsyncResult.from(async () => {
+			const checked = extra.fields === void 0 ? ok(void 0) : await fields.write({ ...extra.fields });
+			if (!checked.ok) return checked;
+			const created = await admin.createUser({
+				email: `${crypto.randomUUID()}@service-principals.invalid`,
+				email_confirm: true,
+				ban_duration: BAN_DURATION,
+				app_metadata: {
+					[SERVICE_PRINCIPAL_CLAIM]: true,
+					organization_id: organizationId
+				},
+				user_metadata: { name }
+			});
+			const user = created.data.user;
+			if (created.error !== null || user === null) return err(dbError("unexpected", `Auth refused the service principal user: ${created.error?.message ?? "no user returned"}`));
+			const registered = await call("register_service_principal", {
+				principal: user.id,
+				tenant: organizationId,
+				name,
+				role,
+				is_default: extra.default ?? false,
+				created_by: extra.createdBy ?? null,
+				fields: checked.data
+			}, (value) => {
+				const row = recordOf(value, "register_service_principal");
+				return {
+					id: textOf(row["id"]),
+					organizationId: textOf(row["tenant"]),
+					name: textOf(row["name"]),
+					role: textOf(row["role"]),
+					isDefault: row["isDefault"] === true,
+					fields: rowFields(row["fields"])
+				};
+			});
+			if (!registered.ok) {
+				await admin.deleteUser(user.id);
+				return err(registered.error);
+			}
+			return readFields(fields, registered.data);
+		}),
+		setRole: (id, role, extra = {}) => call("set_service_principal_role", {
+			principal: id,
+			role,
+			created_by: extra.createdBy ?? null
+		}, (value) => value === true),
+		disable: (id, extra = {}) => call("disable_service_principal", {
+			principal: id,
+			created_by: extra.createdBy ?? null
+		}, (value) => value === true),
+		defaultFor: (organizationId) => call("default_service_principal", { tenant: organizationId }, (value) => nullableText(value)),
+		list: (organizationId) => call("service_principals_list", { tenant: organizationId }, (value) => recordsOf(value, "service_principals_list").map((row) => ({
+			id: textOf(row["id"]),
+			name: textOf(row["name"]),
+			role: textOf(row["role"]),
+			isDefault: row["isDefault"] === true,
+			createdBy: nullableText(row["createdBy"]),
+			createdAt: requiredInstant(row["createdAt"], "createdAt"),
+			disabledAt: nullableInstant(row["disabledAt"]),
+			fields: rowFields(row["fields"])
+		}))).andThen((principals) => readAllFields(fields, principals))
+	}, options.hooks, {
+		block: "service-principals",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/service-principals/events.ts
+/** The `service-principals` block's event types, for its manifest and `onBlockEvent`. */
+const servicePrincipalsEvents = defineEvents({
+	"service_principal.created": event(),
+	"service_principal.role_changed": event(),
+	"service_principal.disabled": event()
+});
+//#endregion
+//#region src/blocks/service-principals/manifest.ts
+/** The `service-principals` block's manifest (ADR 0029). */
+const servicePrincipalsBlock = defineBlock({
+	name: "service-principals",
+	sql: ["service-principals"],
+	options: { "service-principals": servicePrincipalsSqlOptions },
+	events: servicePrincipalsEvents,
+	create: createServicePrincipals,
+	category: "developer",
+	recipes: ["service-principals-table"]
+});
+//#endregion
+export { SERVICE_PRINCIPAL_CLAIM, createServicePrincipals, dbTransport, rpcTransport, servicePrincipalsBlock, servicePrincipalsEvents, sqlTransport };

package/dist/blocks/sessions/index.d.ts

@@ -0,0 +1,7 @@
+import { r as Block } from "../../define-block-CLZMEFeK.js";
+import { a as OAuthConsentControllerOptions, c as OAuthGrant, d as OAuthGrantsControllerOptions, f as OAuthGrantsSnapshot, h as createOAuthGrantsController, i as OAuthConsentController, l as OAuthGrantsActions, m as createOAuthConsentController, n as OAuthClientInfo, o as OAuthConsentRequest, p as RawOAuthClient, r as OAuthConsentActions, s as OAuthConsentSnapshot, t as OAuthApi, u as OAuthGrantsController } from "../../client-CzI4QpG3.js";
+//#region src/blocks/sessions/manifest.d.ts
+/** The `sessions` block's manifest (ADR 0029). */
+export declare const sessionsBlock: Block<"sessions">;
+//#endregion
+export { type OAuthApi, type OAuthClientInfo, type OAuthConsentActions, type OAuthConsentController, type OAuthConsentControllerOptions, type OAuthConsentRequest, type OAuthConsentSnapshot, type OAuthGrant, type OAuthGrantsActions, type OAuthGrantsController, type OAuthGrantsControllerOptions, type OAuthGrantsSnapshot, type RawOAuthClient, createOAuthConsentController, createOAuthGrantsController };

package/dist/blocks/sessions/index.js

@@ -0,0 +1,14 @@
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { n as createOAuthGrantsController, t as createOAuthConsentController } from "../../client-CiGjS6us.js";
+import { t as sessionsSqlOptions } from "../../options-D40CQzji.js";
+//#region src/blocks/sessions/manifest.ts
+/** The `sessions` block's manifest (ADR 0029). */
+const sessionsBlock = defineBlock({
+	name: "sessions",
+	sql: ["sessions"],
+	options: { sessions: sessionsSqlOptions },
+	category: "identity",
+	recipes: ["sessions-list"]
+});
+//#endregion
+export { createOAuthConsentController, createOAuthGrantsController, sessionsBlock };

package/dist/blocks/sessions/react/index.d.ts

@@ -0,0 +1,31 @@
+import { c as OAuthGrant, f as OAuthGrantsSnapshot, l as OAuthGrantsActions, n as OAuthClientInfo, o as OAuthConsentRequest, r as OAuthConsentActions, s as OAuthConsentSnapshot } from "../../../client-CzI4QpG3.js";
+//#region src/blocks/sessions/react/index.d.ts
+export interface UseOAuthConsentOptions {
+  /** `authorization_id` from the page's URL; `undefined` loads nothing. */
+  readonly authorizationId: string | undefined;
+  /** Leaves for the `redirect_url` Auth returned. Default: `window.location.assign`. */
+  readonly redirect?: (url: string) => void;
+}
+export interface OAuthConsentState extends OAuthConsentSnapshot, OAuthConsentActions {}
+export interface OAuthGrantsState extends OAuthGrantsSnapshot, OAuthGrantsActions {}
+/**
+ * The consent page of the Supabase Auth OAuth server: `request` holds the
+ * client and scopes, and `approve` or `deny` go to the client through the
+ * `redirect_url` Auth returns.
+ *
+ * ```tsx
+ * const { request, deciding, approve, deny } = useOAuthConsent({ authorizationId });
+ * ```
+ */
+export declare function useOAuthConsent(options: UseOAuthConsentOptions): OAuthConsentState;
+/**
+ * The OAuth clients the user approved, for a connected agents list:
+ * `revoke` disconnects one.
+ *
+ * ```tsx
+ * const { grants, revoke } = useOAuthGrants();
+ * ```
+ */
+export declare function useOAuthGrants(): OAuthGrantsState;
+//#endregion
+export type { OAuthClientInfo, OAuthConsentRequest, OAuthGrant };

package/dist/blocks/sessions/react/index.js

@@ -0,0 +1,51 @@
+"use client";
+import { n as useLatest, t as useController } from "../../../react-controller-Xn-IU44p.js";
+import { t as useBlockEnv } from "../../../react-env-Cc7Vf6eb.js";
+import { n as createOAuthGrantsController, t as createOAuthConsentController } from "../../../client-CiGjS6us.js";
+//#region src/blocks/sessions/react/index.ts
+/**
+* The consent page of the Supabase Auth OAuth server: `request` holds the
+* client and scopes, and `approve` or `deny` go to the client through the
+* `redirect_url` Auth returns.
+*
+* ```tsx
+* const { request, deciding, approve, deny } = useOAuthConsent({ authorizationId });
+* ```
+*/
+function useOAuthConsent(options) {
+	const { supabase, auth } = useBlockEnv();
+	const latest = useLatest(options);
+	const { authorizationId } = options;
+	return useController(() => createOAuthConsentController({
+		oauth: supabase.auth.oauth,
+		auth,
+		authorizationId,
+		redirect: (url) => {
+			const redirect = latest.current.redirect;
+			if (redirect) redirect(url);
+			else globalThis.location.assign(url);
+		}
+	}), [
+		supabase,
+		auth,
+		authorizationId,
+		latest
+	]).view;
+}
+/**
+* The OAuth clients the user approved, for a connected agents list:
+* `revoke` disconnects one.
+*
+* ```tsx
+* const { grants, revoke } = useOAuthGrants();
+* ```
+*/
+function useOAuthGrants() {
+	const { supabase, auth } = useBlockEnv();
+	return useController(() => createOAuthGrantsController({
+		oauth: supabase.auth.oauth,
+		auth
+	}), [supabase, auth]).view;
+}
+//#endregion
+export { useOAuthConsent, useOAuthGrants };

package/dist/blocks/sessions/react/server.d.ts

@@ -0,0 +1,9 @@
+import { c as OAuthGrant, n as OAuthClientInfo, o as OAuthConsentRequest } from "../../../client-CzI4QpG3.js";
+import { OAuthConsentState, OAuthGrantsState, UseOAuthConsentOptions } from "./index.js";
+//#region src/blocks/sessions/react/server.d.ts
+/** The `react-server` build of `useOAuthConsent`: it runs in Client Components only. */
+export declare const useOAuthConsent: (options: UseOAuthConsentOptions) => OAuthConsentState;
+/** The `react-server` build of `useOAuthGrants`: it runs in Client Components only. */
+export declare const useOAuthGrants: () => OAuthGrantsState;
+//#endregion
+export type { OAuthClientInfo, OAuthConsentRequest, OAuthConsentState, OAuthGrant, OAuthGrantsState, UseOAuthConsentOptions };