better-supabase 0.13.0 → 0.15.0

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

@@ -1,7 +1,142 @@
-import { r as Block } from "../../define-block-MyM4lH42.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-D2y_CfhU.js";
+/// <reference lib="esnext.temporal" />
+import { b as DbError, f as Result } from "../../result-DZeA5KS6.js";
+import { r as Block } from "../../define-block-BVcLQ3DF.js";
+import { n as Controller, t as AuthPort } from "../../controller-BrP0gn47.js";
+import { t as AuthReply } from "../../auth-reply-Dj124sbX.js";
+//#region src/blocks/sessions/client.d.ts
+/** An OAuth client as the Auth OAuth server describes it. */
+interface RawOAuthClient {
+  readonly id: string;
+  readonly name: string;
+  readonly uri?: string;
+  readonly logo_uri?: string;
+}
+/** The part of `supabase.auth.oauth` the consent controllers call. */
+interface OAuthApi {
+  getAuthorizationDetails(authorizationId: string): PromiseLike<AuthReply<{
+    readonly authorization_id: string;
+    readonly redirect_uri: string;
+    readonly client: RawOAuthClient;
+    readonly user: {
+      readonly id: string;
+      readonly email: string;
+    };
+    readonly scope: string;
+  } | {
+    readonly redirect_url: string;
+  }>>;
+  approveAuthorization(authorizationId: string, options?: {
+    skipBrowserRedirect?: boolean;
+  }): PromiseLike<AuthReply<{
+    readonly redirect_url: string;
+  }>>;
+  denyAuthorization(authorizationId: string, options?: {
+    skipBrowserRedirect?: boolean;
+  }): PromiseLike<AuthReply<{
+    readonly redirect_url: string;
+  }>>;
+  listGrants(): PromiseLike<AuthReply<readonly {
+    readonly client: RawOAuthClient;
+    readonly scopes: readonly string[];
+    readonly granted_at: string;
+  }[]>>;
+  revokeGrant(options: {
+    clientId: string;
+  }): PromiseLike<AuthReply<unknown>>;
+}
+interface OAuthClientInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly uri: string | undefined;
+  readonly logoUri: string | undefined;
+}
+/** An authorization request waiting for the user's decision. */
+interface OAuthConsentRequest {
+  readonly authorizationId: string;
+  readonly client: OAuthClientInfo;
+  readonly user: {
+    readonly id: string;
+    readonly email: string;
+  };
+  readonly scopes: readonly string[];
+  /** The redirect URI the client registered. */
+  readonly redirectUri: string;
+  /** Its host, to show where approving sends the user. */
+  readonly redirectHost: string;
+}
+interface OAuthConsentControllerOptions {
+  /** `supabase.auth.oauth` of the browser client. */
+  readonly oauth: OAuthApi;
+  readonly auth: AuthPort;
+  /** `authorization_id` from the consent page's URL; `undefined` loads nothing. */
+  readonly authorizationId: string | undefined;
+  /**
+   * Leaves for a `redirect_url` that Auth returned: after a decision, or at
+   * once for a client the user approved before. Default:
+   * `window.location.assign`.
+   */
+  readonly redirect?: (url: string) => void;
+}
+interface OAuthConsentSnapshot {
+  /**
+   * The request to approve or deny; `undefined` while it loads or after a
+   * redirect.
+   */
+  readonly request: OAuthConsentRequest | undefined;
+  /** The URL the controller sent the browser to. */
+  readonly redirectUrl: string | undefined;
+  /** The decision in flight; it stays set while the browser leaves. */
+  readonly deciding: "approve" | "deny" | undefined;
+  readonly error: DbError | undefined;
+}
+interface OAuthConsentActions {
+  /** Approves the request and goes to the client with a code. */
+  readonly approve: () => Promise<Result<string>>;
+  /** Denies the request and goes to the client with `access_denied`. */
+  readonly deny: () => Promise<Result<string>>;
+}
+type OAuthConsentController = Controller<OAuthConsentSnapshot, OAuthConsentActions>;
+/**
+ * The consent page of the Supabase Auth OAuth server: it reads the request for
+ * `authorizationId`, and `approve` or `deny` send the browser to the
+ * `redirect_url` that Auth returns, never to a URL from the page.
+ */
+export declare function createOAuthConsentController(options: OAuthConsentControllerOptions): OAuthConsentController;
+/** A client the user approved. */
+interface OAuthGrant {
+  readonly client: OAuthClientInfo;
+  readonly scopes: readonly string[];
+  readonly grantedAt: Temporal.Instant;
+}
+interface OAuthGrantsControllerOptions {
+  /** `supabase.auth.oauth` of the browser client. */
+  readonly oauth: OAuthApi;
+  readonly auth: AuthPort;
+}
+interface OAuthGrantsSnapshot {
+  /** Newest first; `undefined` until the first load. */
+  readonly grants: readonly OAuthGrant[] | undefined;
+  /** The client ids with a revoke in flight. */
+  readonly revoking: readonly string[];
+  readonly error: DbError | undefined;
+}
+interface OAuthGrantsActions {
+  /**
+   * Disconnects a client: its sessions end and its refresh tokens stop working.
+   * An access token it holds stays valid until it expires.
+   */
+  readonly revoke: (clientId: string) => Promise<Result<boolean>>;
+  readonly refresh: () => Promise<void>;
+}
+type OAuthGrantsController = Controller<OAuthGrantsSnapshot, OAuthGrantsActions>;
+/**
+ * The OAuth clients (such as MCP clients) the user approved, for a connected
+ * agents list.
+ */
+export declare function createOAuthGrantsController(options: OAuthGrantsControllerOptions): OAuthGrantsController;
+//#endregion
 //#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 };
+export type { OAuthApi, OAuthClientInfo, OAuthConsentActions, OAuthConsentController, OAuthConsentControllerOptions, OAuthConsentRequest, OAuthConsentSnapshot, OAuthGrant, OAuthGrantsActions, OAuthGrantsController, OAuthGrantsControllerOptions, OAuthGrantsSnapshot, RawOAuthClient };

package/dist/blocks/sessions/index.js

@@ -1,6 +1,177 @@
+import { n as dbError } from "../../errors-BVFgt8BZ.js";
+import { a as ok, r as err } from "../../result-ntFBW2p2.js";
 import { t as sessionsSqlOptions } from "../../options-D40CQzji.js";
-import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
-import { n as createOAuthGrantsController, t as createOAuthConsentController } from "../../client-BOuaQA0h.js";
+import { n as whileSignedIn, t as defineController } from "../../controller-BEliOBOv.js";
+import { R as toInstant } from "../../block-helpers-CtBdjgO4.js";
+import { n as defineBlock } from "../../define-block-BGqOO8B3.js";
+import { t as authResult } from "../../auth-reply-tlXB2FQ9.js";
+//#region src/blocks/sessions/client.ts
+const filled = (value) => value === null || value === void 0 || value === "" ? void 0 : value;
+const clientInfo = (raw) => ({
+	id: raw.id,
+	name: raw.name,
+	uri: filled(raw.uri),
+	logoUri: filled(raw.logo_uri)
+});
+const hostOf = (uri) => {
+	try {
+		return new URL(uri).host;
+	} catch {
+		return uri;
+	}
+};
+/**
+* Reads per authorization id. A request the user approved before is used up by
+* its first read, so a second controller for the same id (React Strict Mode
+* mounts twice) has to share the answer.
+*/
+const reads = /* @__PURE__ */ new Map();
+async function readDetails(oauth, authorizationId) {
+	const result = await authResult(() => oauth.getAuthorizationDetails(authorizationId));
+	if (!result.ok) return result;
+	const data = result.data;
+	if (!("authorization_id" in data)) return ok({ redirectUrl: data.redirect_url });
+	return ok({
+		authorizationId: data.authorization_id,
+		client: clientInfo(data.client),
+		user: data.user,
+		scopes: data.scope.split(" ").filter((scope) => scope !== ""),
+		redirectUri: data.redirect_uri,
+		redirectHost: hostOf(data.redirect_uri)
+	});
+}
+const assign = (url) => {
+	globalThis.location.assign(url);
+};
+/**
+* The consent page of the Supabase Auth OAuth server: it reads the request for
+* `authorizationId`, and `approve` or `deny` send the browser to the
+* `redirect_url` that Auth returns, never to a URL from the page.
+*/
+function createOAuthConsentController(options) {
+	const { oauth, authorizationId } = options;
+	const redirect = options.redirect ?? assign;
+	return defineController({
+		request: void 0,
+		redirectUrl: void 0,
+		deciding: void 0,
+		error: void 0
+	}, (state) => {
+		const leave = (url) => {
+			state.set({
+				request: void 0,
+				redirectUrl: url
+			});
+			redirect(url);
+		};
+		const load = async (id) => {
+			let read = reads.get(id);
+			if (read === void 0) {
+				read = readDetails(oauth, id);
+				reads.set(id, read);
+			}
+			const run = state.run();
+			const result = await read;
+			if (run !== state.run()) return;
+			if (!result.ok) {
+				reads.delete(id);
+				state.set({ error: result.error });
+				return;
+			}
+			if ("redirectUrl" in result.data) {
+				leave(result.data.redirectUrl);
+				return;
+			}
+			state.set({
+				request: result.data,
+				error: void 0
+			});
+		};
+		const decide = async (decision) => {
+			const id = state.get().request?.authorizationId;
+			if (id === void 0 || state.get().deciding !== void 0) return err(dbError("invalid_input", "No authorization request to decide"));
+			state.set({
+				deciding: decision,
+				error: void 0
+			});
+			const result = await authResult(() => decision === "approve" ? oauth.approveAuthorization(id, { skipBrowserRedirect: true }) : oauth.denyAuthorization(id, { skipBrowserRedirect: true }));
+			if (!result.ok) {
+				state.set({
+					deciding: void 0,
+					error: result.error
+				});
+				return result;
+			}
+			reads.delete(id);
+			leave(result.data.redirect_url);
+			return ok(result.data.redirect_url);
+		};
+		return {
+			actions: {
+				approve: () => decide("approve"),
+				deny: () => decide("deny")
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				if (authorizationId !== void 0) load(authorizationId);
+			})
+		};
+	});
+}
+/**
+* The OAuth clients (such as MCP clients) the user approved, for a connected
+* agents list.
+*/
+function createOAuthGrantsController(options) {
+	const { oauth } = options;
+	return defineController({
+		grants: void 0,
+		revoking: [],
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			ticket += 1;
+			const request = ticket;
+			const result = await authResult(() => oauth.listGrants());
+			if (request !== ticket) return;
+			if (!result.ok) {
+				state.set({ error: result.error });
+				return;
+			}
+			state.set({
+				grants: result.data.map((grant) => ({
+					client: clientInfo(grant.client),
+					scopes: grant.scopes,
+					grantedAt: toInstant(grant.granted_at)
+				})).toSorted((a, b) => b.grantedAt.epochMilliseconds - a.grantedAt.epochMilliseconds),
+				error: void 0
+			});
+		};
+		return {
+			actions: {
+				refresh,
+				revoke: async (clientId) => {
+					state.set((current) => ({
+						revoking: [...current.revoking, clientId],
+						error: void 0
+					}));
+					const result = await authResult(() => oauth.revokeGrant({ clientId }));
+					state.set((current) => ({
+						revoking: current.revoking.filter((each) => each !== clientId),
+						...result.ok ? {} : { error: result.error }
+					}));
+					if (!result.ok) return result;
+					await refresh();
+					return ok(true);
+				}
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
 //#region src/blocks/sessions/manifest.ts
 /** The `sessions` block's manifest (ADR 0029). */
 const sessionsBlock = defineBlock({

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

@@ -1,7 +1,105 @@
-import { rt as SettingEventData, wt as Events } from "../../events-DhGgwqQA.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DBPhgF3W.js";
-import { s as BlockOf } from "../../define-block-MyM4lH42.js";
-import { _ as createSettings, a as SettingsControllerOptions, c as settingFields, d as SettingInputs, f as SettingValues, g as SettingsSpec, h as SettingsOptions, i as SettingsController, l as SettingEntries, m as SettingsDefinition, n as SettingKind, o as SettingsSnapshot, p as Settings, r as SettingsActions, s as createSettingsController, t as SettingField, u as SettingEntry, v as defineSettings } from "../../client-nieeGXdg.js";
+import { b as DbError, f as Result, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { Ct as Events, rt as SettingEventData } from "../../events-vcqenSYU.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { n as BlockOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "../../block-hooks-DZN2w69m.js";
+import { c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+import { n as Controller, t as AuthPort } from "../../controller-BrP0gn47.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/blocks/settings/settings.d.ts
+/**
+ * One setting: its Standard Schema and the value `get` returns when none is
+ * stored.
+ */
+interface SettingEntry<S extends StandardSchemaV1 = StandardSchemaV1> {
+  readonly schema: S;
+  readonly default?: StandardSchemaV1.InferOutput<S>;
+  /**
+   * Platform settings only: the platform permission (`is_platform`) that may
+   * change this key. Default `blocks.settings.options.platform.permission`,
+   * then `settings.manage`.
+   */
+  readonly permission?: string;
+  /**
+   * Platform settings only: who reads this key, `public` (anyone, also signed
+   * out), `authenticated` (default) or `staff` (holders of its permission).
+   */
+  readonly read?: "public" | "authenticated" | "staff";
+}
+type SettingEntries = Readonly<Record<string, SettingEntry>>;
+/**
+ * The value type of each key: the schema output, or `undefined` without a
+ * default.
+ */
+type SettingValues<E extends SettingEntries> = { readonly [K in keyof E]: E[K] extends SettingEntry<infer S> ? E[K] extends {
+  readonly default: unknown;
+} ? StandardSchemaV1.InferOutput<S> : StandardSchemaV1.InferOutput<S> | undefined : never; };
+/** What a scope's `set` accepts per key: the schema input. */
+type SettingInputs<E extends SettingEntries> = { readonly [K in keyof E]: E[K] extends SettingEntry<infer S> ? StandardSchemaV1.InferInput<S> : never; };
+interface SettingsSpec<U extends SettingEntries = SettingEntries, O extends SettingEntries = SettingEntries, P extends SettingEntries = SettingEntries> {
+  readonly user?: U;
+  readonly organization?: O;
+  /** Settings for the whole product, such as an admin console edits. */
+  readonly platform?: P;
+}
+interface SettingsOptions<U extends SettingEntries = SettingEntries, O extends SettingEntries = SettingEntries, P extends SettingEntries = SettingEntries> extends BlockOptions {
+  /**
+   * The app's settings, from `defineSettings`. Without it (a block wired with
+   * no definition) every key is unknown.
+   */
+  readonly settings?: SettingsDefinition<U, O, P>;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Settings<U, O, P>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/**
+ * Typed reads and writes of the caller's settings, an organization's settings
+ * (reads need `settings.read`, writes `settings.update`) and the product-wide
+ * settings (reads follow each key's `read`, writes need its platform
+ * permission).
+ */
+interface Settings<U extends SettingEntries = SettingEntries, O extends SettingEntries = SettingEntries, P extends SettingEntries = Record<never, never>> {
+  /** Every key of the caller's settings, stored values merged over the defaults. */
+  getUser(): AsyncResult<SettingValues<U>>;
+  getUser<K extends keyof U & string>(key: K): AsyncResult<SettingValues<U>[K]>;
+  /** Validates `value` with the key's schema, then stores the output. */
+  setUser<K extends keyof U & string>(key: K, value: SettingInputs<U>[K]): AsyncResult<SettingValues<U>[K]>;
+  /** Removes the stored value, so `getUser` returns the default again. */
+  resetUser(key: keyof U & string): AsyncResult<boolean>;
+  getOrganization(organizationId: string): AsyncResult<SettingValues<O>>;
+  getOrganization<K extends keyof O & string>(organizationId: string, key: K): AsyncResult<SettingValues<O>[K]>;
+  setOrganization<K extends keyof O & string>(organizationId: string, key: K, value: SettingInputs<O>[K]): AsyncResult<SettingValues<O>[K]>;
+  resetOrganization(organizationId: string, key: keyof O & string): AsyncResult<boolean>;
+  getPlatform(): AsyncResult<SettingValues<P>>;
+  getPlatform<K extends keyof P & string>(key: K): AsyncResult<SettingValues<P>[K]>;
+  setPlatform<K extends keyof P & string>(key: K, value: SettingInputs<P>[K]): AsyncResult<SettingValues<P>[K]>;
+  resetPlatform(key: keyof P & string): AsyncResult<boolean>;
+}
+interface SettingsDefinition<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>> {
+  /**
+   * Pass as `blocks.settings.options.schemas` for the database checks, and the
+   * platform keys' permissions and read rules.
+   */
+  readonly schemas: {
+    readonly user: U;
+    readonly organization: O;
+    readonly platform: P;
+  };
+}
+/**
+ * Declares the app's settings with a Standard Schema per key. Values are
+ * validated before they are written, and stored values that no longer match
+ * their schema read as the default. Pass the result to `createSettings`.
+ */
+export declare function defineSettings<const U extends SettingEntries = Record<never, never>, const O extends SettingEntries = Record<never, never>, const P extends SettingEntries = Record<never, never>>(spec: SettingsSpec<U, O, P>): SettingsDefinition<U, O, P>;
+/**
+ * The settings block: typed `get`, `set` and `reset` over the settings module's
+ * functions.
+ */
+export declare function createSettings<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>>(options: SettingsOptions<U, O, P>): Settings<U, O, P>;
+//#endregion
 //#region src/blocks/settings/events.d.ts
 /** The events of the `settings` block: type to data. */
 type SettingsEvents = {
@@ -21,4 +119,82 @@ export declare const settingsEvents: Events<SettingsEvents>;
  */
 export declare const settingsBlock: BlockOf<"settings", typeof createSettings, SettingsEvents>;
 //#endregion
-export { type BlockTransport, type SettingEntries, type SettingEntry, type SettingField, type SettingInputs, type SettingKind, type SettingValues, type Settings, type SettingsActions, type SettingsController, type SettingsControllerOptions, type SettingsDefinition, type SettingsEvents, type SettingsOptions, type SettingsSnapshot, type SettingsSpec, createSettings, createSettingsController, dbTransport, defineSettings, rpcTransport, settingFields, sqlTransport };
+//#region src/blocks/settings/client.d.ts
+/** How a settings page renders a key. */
+type SettingKind = "boolean" | "number" | "text" | "choice" | "json";
+/**
+ * One generated form field: a key of the settings definition and what its
+ * schema says about it.
+ */
+interface SettingField<K extends string = string> {
+  readonly key: K;
+  /**
+   * From the schema's Standard JSON Schema (`type` and `enum`), or from the
+   * default's type for a schema library without it.
+   */
+  readonly kind: SettingKind;
+  /** The values a `choice` allows, from the JSON Schema `enum`. */
+  readonly choices: readonly (string | number)[];
+  /** The JSON Schema `title` and `description`, such as zod's `.meta()`. */
+  readonly title: string | undefined;
+  readonly description: string | undefined;
+  readonly default: unknown;
+}
+/**
+ * The form fields of one scope of a settings definition, in declaration order:
+ * `settingFields(settings.schemas.organization)`.
+ */
+export declare function settingFields<E extends SettingEntries>(entries: E): readonly SettingField<keyof E & string>[];
+interface SettingsControllerOptions<E extends SettingEntries> {
+  /**
+   * One scope of the definition: `settings.schemas.user` or
+   * `settings.schemas.organization`.
+   */
+  readonly entries: E;
+  readonly auth: AuthPort;
+  /**
+   * The caller's own settings: a `createSettings` client. Pass this or
+   * `organization`.
+   */
+  readonly user?: Pick<Settings<E>, "getUser" | "setUser" | "resetUser">;
+  /**
+   * An organization's settings: a `createSettings` client, with
+   * `organizationId`.
+   */
+  readonly organization?: Pick<Settings<SettingEntries, E>, "getOrganization" | "setOrganization" | "resetOrganization">;
+  /** The organization for `organization`; the page waits without one. */
+  readonly organizationId?: string | null;
+}
+interface SettingsSnapshot<E extends SettingEntries> {
+  /** The form fields, from the definition; there before the first load. */
+  readonly fields: readonly SettingField<keyof E & string>[];
+  /** Stored values over the defaults; `undefined` until the first load. */
+  readonly values: SettingValues<E> | undefined;
+  /** The key being saved. */
+  readonly saving: (keyof E & string) | undefined;
+  readonly error: DbError | undefined;
+}
+interface SettingsActions<E extends SettingEntries> {
+  /**
+   * Validates and stores one value, then shows it; a failure is also kept in
+   * `error`.
+   */
+  readonly set: <K extends keyof E & string>(key: K, value: SettingInputs<E>[K]) => Promise<Result<SettingValues<E>[K]>>;
+  /**
+   * `set` for a form generated from `fields`, whose controls produce plain
+   * values: the key's schema validates `value` before it is stored.
+   */
+  readonly setField: (key: keyof E & string, value: unknown) => Promise<Result<unknown>>;
+  /** Removes the stored value, so the key reads as its default again. */
+  readonly reset: (key: keyof E & string) => Promise<Result<boolean>>;
+  readonly refresh: () => Promise<void>;
+}
+type SettingsController<E extends SettingEntries> = Controller<SettingsSnapshot<E>, SettingsActions<E>>;
+/**
+ * One scope of the app's settings for a settings page: the form fields
+ * generated from the definition, the stored values over the defaults, and `set`
+ * and `reset` per key.
+ */
+export declare function createSettingsController<E extends SettingEntries>(options: SettingsControllerOptions<E>): SettingsController<E>;
+//#endregion
+export { type BlockTransport, type SettingEntries, type SettingEntry, type SettingField, type SettingInputs, type SettingKind, type SettingValues, type Settings, type SettingsActions, type SettingsController, type SettingsControllerOptions, type SettingsDefinition, type SettingsEvents, type SettingsOptions, type SettingsSnapshot, type SettingsSpec, dbTransport, rpcTransport, sqlTransport };