better-supabase 0.5.1 → 0.6.0

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

@@ -0,0 +1,40 @@
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { i as sqlTransport, n as RpcClient, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-CYsm7xpT.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-plbZ0AbJ.js";
+import { n as FieldsOf } from "../../block-fields-SJ6fEf3o.js";
+//#region src/blocks/profiles/profiles.d.ts
+interface ProfilesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** `sql.modules.profiles.schema`, or the API schema of its wrappers. */
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the profile columns the app adds
+   * (`sql.modules.profiles.options.extraColumns`), keyed by database name.
+   * It types and parses them on `mine()`, and validates them on
+   * `updateMine`, which returns a `validation` error for a bad value. The
+   * parsed fields are merged over the row, so the other columns stay.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around `mine` and `updateMine`. */
+  readonly hooks?: NoInfer<BlockHooks<Profiles<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** Error mappers that run before the built-in ones, as in `betterSupabase.mapError()`. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** The caller's profile columns, by database name; `F` types the ones `fields` describes. */
+type Profile<F extends object = Record<never, never>> = Readonly<Record<string, unknown>> & F;
+interface Profiles<F extends object = Record<never, never>> {
+  mine(): AsyncResult<Profile<F> | undefined>;
+  updateMine(attrs: Readonly<Record<string, unknown>> & Partial<F>): AsyncResult<boolean>;
+}
+/**
+ * The `profiles` SQL module as typed calls. `mine` and `updateMine` are the
+ * functions a signed-in user runs on their own row.
+ */
+export declare function createProfiles<S extends StandardSchemaV1 | undefined = undefined>(options: ProfilesOptions<S>): Profiles<FieldsOf<S>>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Profile, type Profiles, type ProfilesOptions, type RpcClient, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/profiles/index.js

@@ -0,0 +1,28 @@
+import { a as ok, t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { d as isRecord, i as blockCall, n as applyTemporal } from "../../block-helpers-DWHxHsEQ.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BmjMyXTa.js";
+import { t as blockFields } from "../../block-fields-GFkxl4dP.js";
+//#region src/blocks/profiles/profiles.ts
+/**
+* The `profiles` SQL module as typed calls. `mine` and `updateMine` are the
+* functions a signed-in user runs on their own row.
+*/
+function createProfiles(options) {
+	applyTemporal(options);
+	const run = blockCall(options.transport, options.schema, options.mappers ?? []);
+	const fields = blockFields(options.fields, "profile fields");
+	return withBlockHooks({
+		mine() {
+			return run("my_profile", {}, (value) => isRecord(value) ? value : void 0).andThen(async (row) => row === void 0 ? ok(row) : fields.read(row));
+		},
+		updateMine(attrs) {
+			return AsyncResult.from(() => fields.write(attrs)).andThen((valid) => run("update_my_profile", { attrs: valid }, (value) => value === true));
+		}
+	}, options.hooks, {
+		block: "profiles",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+export { createProfiles, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

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

@@ -0,0 +1,185 @@
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { n as NotificationMessage, t as NotificationChannel } from "../../channel-_2Mx1Oyu.js";
+//#region src/blocks/push/push.d.ts
+type PushPlatform = "ios" | "android" | "web";
+type PushProvider = "expo" | "fcm" | "apns" | "webpush";
+interface PushDeviceInput {
+  readonly token: string;
+  readonly platform: PushPlatform;
+  /** Defaults to `expo`. */
+  readonly provider?: PushProvider;
+  readonly deviceName?: string;
+  readonly appVersion?: string;
+}
+/** One device a user gets pushes on. */
+interface PushTarget {
+  readonly userId: string;
+  readonly token: string;
+  readonly platform: PushPlatform;
+  readonly provider: PushProvider;
+}
+interface PushDevicesOptions extends BlockTemporalOptions {
+  /** `sqlTransport(postgres.asUser(claims))`, `rpcTransport(supabase)`, or over `postgres.admin` for the sender. */
+  readonly transport: BlockTransport;
+  /** `sql.modules.push.schema`. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** The `push` SQL module as typed calls. */
+interface PushDevices {
+  /** Registers the caller's device, or refreshes it; resolves with the device id. */
+  readonly register: (device: PushDeviceInput) => AsyncResult<string>;
+  /** Removes the caller's device; `false` when the caller had none with `token`. */
+  readonly unregister: (token: string) => AsyncResult<boolean>;
+  /** Service role: every device of `userIds`, newest first per user. */
+  readonly tokensFor: (userIds: readonly string[]) => AsyncResult<readonly PushTarget[]>;
+  /** Service role: deletes the devices with `tokens`; resolves with how many. */
+  readonly prune: (tokens: readonly string[]) => AsyncResult<number>;
+}
+export declare function createPushDevices(options: PushDevicesOptions): PushDevices;
+/** The part of `expo-notifications` `registerDevice` uses. */
+interface ExpoNotificationsLike {
+  getPermissionsAsync(): Promise<{
+    readonly status: string;
+  }>;
+  requestPermissionsAsync(): Promise<{
+    readonly status: string;
+  }>;
+  getExpoPushTokenAsync(options?: {
+    readonly projectId?: string;
+  }): Promise<{
+    readonly data: string;
+  }>;
+}
+interface RegisterDeviceOptions {
+  readonly notifications: ExpoNotificationsLike;
+  readonly devices: PushDevices;
+  /** `Platform.OS` from `react-native`. */
+  readonly platform: string;
+  /** `Constants.easConfig?.projectId`; Expo needs it outside Expo Go. */
+  readonly projectId?: string | undefined;
+  readonly deviceName?: string | undefined;
+  readonly appVersion?: string | undefined;
+  /** Asks for permission when it isn't granted yet. Defaults to true. */
+  readonly request?: boolean;
+}
+interface RegisteredDevice {
+  readonly deviceId: string;
+  readonly token: string;
+}
+/**
+ * Gets the Expo push token, asking for permission first, and registers the
+ * device for the signed-in user. Resolves with `null` when the user denies
+ * permission or the platform has no push.
+ *
+ * ```ts
+ * const device = await registerDevice({
+ *   notifications: Notifications,
+ *   devices: createPushDevices({ transport: rpcTransport(supabase) }),
+ *   platform: Platform.OS,
+ *   projectId: Constants.easConfig?.projectId,
+ * }).orThrow();
+ * ```
+ */
+export declare function registerDevice(options: RegisterDeviceOptions): AsyncResult<RegisteredDevice | null>;
+/**
+ * Wraps `signOut` so it first removes this device's token, while the
+ * session can still call `unregister_push_device`. A failed unregister
+ * doesn't stop the sign-out.
+ *
+ * ```ts
+ * const signOut = unregisterOnSignOut({
+ *   signOut: () => supabase.auth.signOut(),
+ *   devices,
+ *   token: () => device?.token,
+ * });
+ * ```
+ */
+export declare function unregisterOnSignOut<R>(options: {
+  readonly signOut: () => Promise<R>;
+  readonly devices: PushDevices;
+  readonly token: () => string | null | undefined;
+}): () => Promise<R>;
+/** One message for the Expo Push API; `to` is set per device. */
+interface ExpoPushMessage {
+  readonly title?: string;
+  readonly subtitle?: string;
+  readonly body?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+  readonly sound?: "default" | null;
+  readonly badge?: number;
+  readonly channelId?: string;
+  readonly categoryId?: string;
+  readonly priority?: "default" | "normal" | "high";
+  /** Seconds the push service keeps trying to deliver. */
+  readonly ttl?: number;
+  readonly mutableContent?: boolean;
+}
+/** What Expo answered for one message: an id for the receipt, or an error. */
+interface ExpoPushTicket {
+  readonly token: string;
+  readonly id?: string;
+  /** Expo's error code, e.g. `DeviceNotRegistered` or `MessageRateExceeded`. */
+  readonly error?: string;
+  readonly message?: string;
+}
+interface ExpoReceiptResult {
+  readonly delivered: number;
+  readonly failed: readonly ExpoPushTicket[];
+  /** Tokens deleted because Expo reported `DeviceNotRegistered`. */
+  readonly pruned: number;
+}
+interface ExpoPushOptions {
+  /** The Expo access token, when the project turns on push security. */
+  readonly accessToken?: string;
+  /** Prunes tokens Expo reports as `DeviceNotRegistered`. */
+  readonly devices?: PushDevices;
+  readonly fetch?: typeof fetch;
+  /** Defaults to `https://exp.host/--/api/v2/push`. */
+  readonly endpoint?: string;
+}
+interface ExpoPush {
+  /** Sends `message` to each token, 100 per request; tickets come back in token order. */
+  readonly send: (tokens: readonly string[], message: ExpoPushMessage) => Promise<readonly ExpoPushTicket[]>;
+  /**
+   * Reads the receipts for tickets that have an id, about 15 minutes after
+   * sending, and prunes the devices Expo no longer reaches.
+   */
+  readonly checkReceipts: (tickets: readonly ExpoPushTicket[]) => Promise<ExpoReceiptResult>;
+}
+/**
+ * A sender for the Expo Push API that needs only `fetch`. Tokens Expo
+ * reports as `DeviceNotRegistered`, in a ticket or a receipt, are pruned
+ * from `push_devices` when `devices` is set.
+ */
+export declare function expoPush(options?: ExpoPushOptions): ExpoPush;
+interface ExpoPushChannelOptions {
+  /** Over the service role, so `tokensFor` can read every user's devices. */
+  readonly devices: PushDevices;
+  readonly push: ExpoPush;
+  /** The delivery channel name. Defaults to `push`. */
+  readonly name?: string;
+  /** Overrides the message built from the notification and its rendered text. */
+  readonly message?: (message: NotificationMessage) => ExpoPushMessage;
+  /** Receives the tickets, to check their receipts later. */
+  readonly onTickets?: (tickets: readonly ExpoPushTicket[], message: NotificationMessage) => void | Promise<void>;
+}
+/**
+ * A notifications channel that pushes each delivery to the recipient's Expo
+ * devices. A recipient without devices is `skipped`; when every ticket
+ * fails for a reason other than an unregistered device, it throws so the
+ * delivery is retried.
+ *
+ * ```ts
+ * createNotifications({
+ *   transport,
+ *   types,
+ *   channels: [expoPushChannel({ devices, push: expoPush({ devices }) })],
+ * });
+ * ```
+ */
+export declare function expoPushChannel(options: ExpoPushChannelOptions): NotificationChannel;
+//#endregion
+export { type BlockTransport, type ExpoNotificationsLike, type ExpoPush, type ExpoPushChannelOptions, type ExpoPushMessage, type ExpoPushOptions, type ExpoPushTicket, type ExpoReceiptResult, type PushDeviceInput, type PushDevices, type PushDevicesOptions, type PushPlatform, type PushProvider, type PushTarget, type RegisterDeviceOptions, type RegisteredDevice, rpcTransport, sqlTransport };

package/dist/blocks/push/index.js

@@ -0,0 +1,258 @@
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { C as run, O as textOf, b as recordOrEmpty, i as blockCall, n as applyTemporal, x as recordsOf } from "../../block-helpers-DWHxHsEQ.js";
+//#region src/blocks/push/push.ts
+const PLATFORMS = /* @__PURE__ */ new Set([
+	"ios",
+	"android",
+	"web"
+]);
+function isPlatform(value) {
+	return PLATFORMS.has(value);
+}
+const PROVIDERS = /* @__PURE__ */ new Set([
+	"expo",
+	"fcm",
+	"apns",
+	"webpush"
+]);
+function isProvider(value) {
+	return PROVIDERS.has(value);
+}
+function targetsOf(value) {
+	return recordsOf(value, "push_tokens_for").flatMap((row) => {
+		const platform = textOf(row["platform"]);
+		const provider = textOf(row["provider"]);
+		return isPlatform(platform) && isProvider(provider) ? [{
+			userId: textOf(row["userId"]),
+			token: textOf(row["token"]),
+			platform,
+			provider
+		}] : [];
+	});
+}
+function createPushDevices(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return {
+		register: (device) => call("register_push_device", {
+			token: device.token,
+			platform: device.platform,
+			provider: device.provider ?? "expo",
+			device_name: device.deviceName,
+			app_version: device.appVersion
+		}, textOf),
+		unregister: (token) => call("unregister_push_device", { token }, (value) => value === true),
+		tokensFor: (userIds) => call("push_tokens_for", { users: [...userIds] }, targetsOf),
+		prune: (tokens) => call("prune_push_tokens", { tokens: [...tokens] }, (value) => typeof value === "number" ? value : Number(value ?? 0))
+	};
+}
+/**
+* Gets the Expo push token, asking for permission first, and registers the
+* device for the signed-in user. Resolves with `null` when the user denies
+* permission or the platform has no push.
+*
+* ```ts
+* const device = await registerDevice({
+*   notifications: Notifications,
+*   devices: createPushDevices({ transport: rpcTransport(supabase) }),
+*   platform: Platform.OS,
+*   projectId: Constants.easConfig?.projectId,
+* }).orThrow();
+* ```
+*/
+function registerDevice(options) {
+	return run(async () => {
+		const { notifications, platform } = options;
+		if (!isPlatform(platform)) return null;
+		let { status } = await notifications.getPermissionsAsync();
+		if (status !== "granted" && (options.request ?? true)) ({status} = await notifications.requestPermissionsAsync());
+		if (status !== "granted") return null;
+		const { data: token } = await notifications.getExpoPushTokenAsync(options.projectId === void 0 ? {} : { projectId: options.projectId });
+		return {
+			deviceId: await options.devices.register({
+				token,
+				platform,
+				provider: "expo",
+				...options.deviceName === void 0 ? {} : { deviceName: options.deviceName },
+				...options.appVersion === void 0 ? {} : { appVersion: options.appVersion }
+			}).orThrow(),
+			token
+		};
+	});
+}
+/**
+* Wraps `signOut` so it first removes this device's token, while the
+* session can still call `unregister_push_device`. A failed unregister
+* doesn't stop the sign-out.
+*
+* ```ts
+* const signOut = unregisterOnSignOut({
+*   signOut: () => supabase.auth.signOut(),
+*   devices,
+*   token: () => device?.token,
+* });
+* ```
+*/
+function unregisterOnSignOut(options) {
+	return async () => {
+		const token = options.token();
+		if (token) await options.devices.unregister(token);
+		return options.signOut();
+	};
+}
+const SEND_CHUNK = 100;
+const RECEIPT_CHUNK = 1e3;
+const NOT_REGISTERED = "DeviceNotRegistered";
+function chunks(items, size) {
+	const out = [];
+	for (let at = 0; at < items.length; at += size) out.push(items.slice(at, at + size));
+	return out;
+}
+function errorCode(entry) {
+	const code = recordOrEmpty(entry["details"])["error"];
+	return typeof code === "string" ? code : "Unknown";
+}
+/**
+* A sender for the Expo Push API that needs only `fetch`. Tokens Expo
+* reports as `DeviceNotRegistered`, in a ticket or a receipt, are pruned
+* from `push_devices` when `devices` is set.
+*/
+function expoPush(options = {}) {
+	const endpoint = options.endpoint ?? "https://exp.host/--/api/v2/push";
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const headers = {
+		accept: "application/json",
+		"content-type": "application/json",
+		...options.accessToken ? { authorization: `Bearer ${options.accessToken}` } : {}
+	};
+	const post = async (path, body) => {
+		const response = await doFetch(`${endpoint}/${path}`, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(body)
+		});
+		const text = await response.text();
+		if (!response.ok) throw new Error(`Expo Push API ${path} answered ${String(response.status)}: ${text.slice(0, 500)}`);
+		const parsed = text === "" ? {} : JSON.parse(text);
+		return recordOrEmpty(parsed)["data"];
+	};
+	const prune = async (tokens) => {
+		if (!options.devices || tokens.length === 0) return 0;
+		let pruned = 0;
+		for (const chunk of chunks([...new Set(tokens)], RECEIPT_CHUNK)) pruned += await options.devices.prune(chunk).orThrow();
+		return pruned;
+	};
+	return {
+		send: async (tokens, message) => {
+			const tickets = [];
+			for (const chunk of chunks(tokens, SEND_CHUNK)) {
+				const data = await post("send", chunk.map((to) => ({
+					...message,
+					to
+				})));
+				const list = Array.isArray(data) ? data : [];
+				chunk.forEach((token, at) => {
+					const entry = recordOrEmpty(list[at]);
+					const message = typeof entry["message"] === "string" ? entry["message"] : void 0;
+					tickets.push(entry["status"] === "ok" && typeof entry["id"] === "string" ? {
+						token,
+						id: entry["id"]
+					} : {
+						token,
+						error: errorCode(entry),
+						...message === void 0 ? {} : { message }
+					});
+				});
+			}
+			await prune(tickets.filter((ticket) => ticket.error === NOT_REGISTERED).map((ticket) => ticket.token));
+			return tickets;
+		},
+		checkReceipts: async (tickets) => {
+			const byId = /* @__PURE__ */ new Map();
+			for (const ticket of tickets) if (ticket.id !== void 0) byId.set(ticket.id, ticket.token);
+			let delivered = 0;
+			const failed = [];
+			for (const ids of chunks([...byId.keys()], RECEIPT_CHUNK)) {
+				const receipts = recordOrEmpty(await post("getReceipts", { ids }));
+				for (const id of ids) {
+					const receipt = receipts[id];
+					if (receipt === void 0) continue;
+					const entry = recordOrEmpty(receipt);
+					if (entry["status"] === "ok") {
+						delivered += 1;
+						continue;
+					}
+					const message = typeof entry["message"] === "string" ? entry["message"] : void 0;
+					failed.push({
+						token: byId.get(id) ?? "",
+						id,
+						error: errorCode(entry),
+						...message === void 0 ? {} : { message }
+					});
+				}
+			}
+			const pruned = await prune(failed.filter((ticket) => ticket.error === NOT_REGISTERED).map((ticket) => ticket.token));
+			return {
+				delivered,
+				failed,
+				pruned
+			};
+		}
+	};
+}
+function defaultMessage(message) {
+	const { notification, text } = message;
+	return {
+		title: text?.title ?? notification.summary ?? notification.type,
+		...text?.body === void 0 ? {} : { body: text.body },
+		sound: "default",
+		data: {
+			notificationId: notification.id,
+			type: notification.type,
+			...notification.actionPath === null ? {} : { actionPath: notification.actionPath }
+		}
+	};
+}
+/**
+* A notifications channel that pushes each delivery to the recipient's Expo
+* devices. A recipient without devices is `skipped`; when every ticket
+* fails for a reason other than an unregistered device, it throws so the
+* delivery is retried.
+*
+* ```ts
+* createNotifications({
+*   transport,
+*   types,
+*   channels: [expoPushChannel({ devices, push: expoPush({ devices }) })],
+* });
+* ```
+*/
+function expoPushChannel(options) {
+	const build = options.message ?? defaultMessage;
+	return {
+		apiVersion: 1,
+		name: options.name ?? "push",
+		async send(message) {
+			const tokens = (await options.devices.tokensFor([message.userId]).orThrow()).filter((target) => target.provider === "expo").map((target) => target.token);
+			if (tokens.length === 0) return {
+				status: "skipped",
+				provider: "expo"
+			};
+			const tickets = await options.push.send(tokens, build(message));
+			await options.onTickets?.(tickets, message);
+			const sent = tickets.find((ticket) => ticket.id !== void 0);
+			if (sent?.id !== void 0) return {
+				provider: "expo",
+				providerMessageId: sent.id
+			};
+			const retryable = tickets.find((ticket) => ticket.error !== NOT_REGISTERED);
+			if (retryable) throw new Error(`Expo rejected the push: ${retryable.error ?? "Unknown"}${retryable.message ? ` (${retryable.message})` : ""}`);
+			return {
+				status: "skipped",
+				provider: "expo"
+			};
+		}
+	};
+}
+//#endregion
+export { createPushDevices, expoPush, expoPushChannel, registerDevice, rpcTransport, sqlTransport, unregisterOnSignOut };

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

@@ -0,0 +1,89 @@
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.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 `sql.modules.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 SettingsConnectOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema (`sql.modules.settings.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** The caller's own settings. */
+interface UserSettings<E extends SettingEntries> {
+  /** Every key, stored values merged over the defaults. */
+  get(): AsyncResult<SettingValues<E>>;
+  get<K extends keyof E & string>(key: K): AsyncResult<SettingValues<E>[K]>;
+  /** Validates `value` with the key's schema, then stores the output. */
+  set<K extends keyof E & string>(key: K, value: SettingInputs<E>[K]): AsyncResult<SettingValues<E>[K]>;
+  /** Removes the stored value, so `get` returns the default again. */
+  reset(key: keyof E & string): AsyncResult<boolean>;
+}
+/** One organization's settings; reads need `settings.read`, writes `settings.update`. */
+interface OrganizationSettings<E extends SettingEntries> {
+  get(organizationId: string): AsyncResult<SettingValues<E>>;
+  get<K extends keyof E & string>(organizationId: string, key: K): AsyncResult<SettingValues<E>[K]>;
+  set<K extends keyof E & string>(organizationId: string, key: K, value: SettingInputs<E>[K]): AsyncResult<SettingValues<E>[K]>;
+  reset(organizationId: string, key: keyof E & string): AsyncResult<boolean>;
+}
+/**
+ * The product-wide settings: reads follow each key's `read`, writes need
+ * its platform permission.
+ */
+type PlatformSettings<E extends SettingEntries> = UserSettings<E>;
+interface SettingsClient<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>> {
+  readonly user: UserSettings<U>;
+  readonly organization: OrganizationSettings<O>;
+  readonly platform: PlatformSettings<P>;
+}
+interface SettingsDefinition<U extends SettingEntries, O extends SettingEntries, P extends SettingEntries = Record<never, never>> {
+  /**
+   * Pass as `sql.modules.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;
+  };
+  /** Typed `get`, `set` and `reset` over the settings module's functions. */
+  connect(options: SettingsConnectOptions): SettingsClient<U, O, 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.
+ */
+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>;
+//#endregion
+export { type BlockTransport, type OrganizationSettings, type PlatformSettings, type SettingEntries, type SettingEntry, type SettingInputs, type SettingValues, type SettingsClient, type SettingsConnectOptions, type SettingsDefinition, type SettingsSpec, type UserSettings, rpcTransport, sqlTransport };