better-supabase 0.8.0 → 0.10.0

package/dist/client-BGnJ5WJi.js

@@ -0,0 +1,438 @@
+import { d as toFilterFields, i as checkFilterQuery, t as FILTER_OPERATORS } from "./filter-query-B3lhckKX.js";
+import { n as whileSignedIn, t as defineController } from "./controller-D6NyNrlZ.js";
+//#region src/blocks/rules/fields.ts
+const DEFAULT_COLUMN_TYPE = {
+	text: "text",
+	number: "numeric",
+	date: "timestamptz",
+	select: "text",
+	multiselect: "jsonb",
+	boolean: "boolean",
+	relation: "uuid"
+};
+const DATE_TYPES = /* @__PURE__ */ new Set([
+	"date",
+	"timestamp",
+	"timestamptz"
+]);
+const SUBJECT_TYPE = /^[a-z][a-z0-9_]{0,62}$/;
+const FIELD_ID = /^[A-Za-z_][A-Za-z0-9_]*(?:[.][A-Za-z_][A-Za-z0-9_]*)*$/;
+function labelOf(id) {
+	const words = id.replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2").replaceAll(/[_.-]+/g, " ").trim().toLowerCase();
+	return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/**
+* Declares the fields rules on `subjectType` may test. Sync the catalog with
+* `createRulesAdmin(...).syncFields(catalog)` so the database checks and
+* evaluates trees against the same fields.
+*/
+function defineRuleFields(subjectType, fields) {
+	if (!SUBJECT_TYPE.test(subjectType)) throw new TypeError(`defineRuleFields: "${subjectType}" is not a subject type (lowercase letters, digits and underscores)`);
+	return {
+		subjectType,
+		fields: Object.entries(fields).map(([id, field]) => {
+			const column = field.column ?? id;
+			if (!FIELD_ID.test(id) || !FIELD_ID.test(column)) throw new TypeError(`defineRuleFields(${subjectType}): "${id}" needs an id and column of dotted identifiers`);
+			const allowed = new Set(FILTER_OPERATORS[field.type].map((entry) => entry.value));
+			const unknown = field.operators?.find((name) => !allowed.has(name));
+			if (unknown !== void 0) throw new TypeError(`defineRuleFields(${subjectType}.${id}): "${unknown}" is not a ${field.type} operator`);
+			const columnType = field.columnType ?? DEFAULT_COLUMN_TYPE[field.type];
+			if (field.type === "date" && !DATE_TYPES.has(columnType)) throw new TypeError(`defineRuleFields(${subjectType}.${id}): a date field's columnType is date, timestamp or timestamptz`);
+			return {
+				subjectType,
+				id,
+				label: field.label ?? labelOf(id),
+				description: field.description,
+				type: field.type,
+				column,
+				columnType,
+				nullable: field.nullable ?? true,
+				options: field.options?.map((option) => typeof option === "string" ? {
+					value: option,
+					label: labelOf(option)
+				} : {
+					value: option.value,
+					label: option.label ?? labelOf(option.value)
+				}),
+				operators: field.operators
+			};
+		})
+	};
+}
+/** Catalog fields as list filter fields, for `evaluateFilterQuery` and `checkFilterQuery`. */
+function ruleFilterFieldInfo(fields) {
+	return fields.map((field) => {
+		const allowed = field.operators;
+		return {
+			id: field.id,
+			type: field.type,
+			column: field.column,
+			columnMeta: {
+				db: field.column,
+				type: field.columnType,
+				nullable: field.nullable,
+				hasDefault: false
+			},
+			label: field.label,
+			...field.description === void 0 ? {} : { description: field.description },
+			operators: FILTER_OPERATORS[field.type].filter((entry) => allowed === void 0 || allowed.includes(entry.value)),
+			...field.options === void 0 ? {} : { options: field.options }
+		};
+	});
+}
+/** The `fields` prop of ReUI's Filters for a rule editor. */
+function ruleFilterFields(fields, labels) {
+	return toFilterFields(ruleFilterFieldInfo(fields), labels);
+}
+/** The defaults of `blocks.rules.options`. */
+const RULE_LIMITS = {
+	maxDepth: 4,
+	maxRules: 50,
+	maxValueLength: 1e4,
+	maxValues: 100
+};
+/**
+* The problems `save` would report for a tree, checked in the browser: an
+* empty list when the database will accept it. Unfinished conditions are
+* allowed; they take no part until they have an operator.
+*/
+function checkRuleConditions(conditions, fields, limits = RULE_LIMITS) {
+	const issues = [];
+	checkFilterQuery(conditions, ruleFilterFieldInfo(fields), limits, issues);
+	return issues;
+}
+//#endregion
+//#region src/blocks/rules/tree.ts
+/** The operators a field allows, in the order the editor lists them. */
+function ruleOperators(field) {
+	const allowed = field.operators;
+	return FILTER_OPERATORS[field.type].filter((entry) => allowed === void 0 || allowed.includes(entry.value));
+}
+/** An empty `and` group, the tree a new rule starts with. */
+const emptyConditions = (id = "root") => ({
+	id,
+	type: "group",
+	combinator: "and",
+	rules: []
+});
+/** The node with `id`, or `undefined`. */
+function findNode(tree, id) {
+	if (tree.id === id) return tree;
+	if (tree.type === "rule") return;
+	for (const child of tree.rules) {
+		const found = findNode(child, id);
+		if (found !== void 0) return found;
+	}
+}
+/** The group that holds `id`, or `undefined` for the root and unknown ids. */
+function parentOf(tree, id) {
+	for (const child of tree.rules) {
+		if (child.id === id) return tree;
+		if (child.type === "group") {
+			const found = parentOf(child, id);
+			if (found !== void 0) return found;
+		}
+	}
+}
+/** Whether `id` is `ancestor` or sits anywhere under it. */
+function contains(ancestor, id) {
+	return findNode(ancestor, id) !== void 0;
+}
+function mapTree(tree, visit) {
+	const walk = (node) => {
+		const next = visit(node);
+		if (next === null || next.type === "rule") return next;
+		const rules = next.rules.flatMap((child) => walk(child) ?? []);
+		return rules.length === next.rules.length && rules.every((child, index) => child === next.rules[index]) ? next : {
+			...next,
+			rules
+		};
+	};
+	const root = walk(tree);
+	return root?.type === "group" ? root : tree;
+}
+/** Replaces the node with `id` by what `change` returns. */
+function updateNode(tree, id, change) {
+	return mapTree(tree, (node) => node.id === id ? change(node) : node);
+}
+/** Drops the node with `id` and everything under it; the root stays. */
+function removeNode(tree, id) {
+	if (tree.id === id) return tree;
+	return mapTree(tree, (node) => node.id === id ? null : node);
+}
+/**
+* Adds `node` to the group `parent` at `index` (the end by default).
+* Unchanged when `parent` isn't a group in the tree.
+*/
+function insertNode(tree, parent, node, index) {
+	return mapTree(tree, (current) => {
+		if (current.id !== parent || current.type !== "group") return current;
+		const rules = [...current.rules];
+		const at = index === void 0 ? rules.length : Math.max(0, Math.min(index, rules.length));
+		rules.splice(at, 0, node);
+		return {
+			...current,
+			rules
+		};
+	});
+}
+/**
+* Moves the node with `id` into the group `parent`, where it ends up at
+* `index` (as `arrayMove` counts it). Unchanged for the root, an unknown
+* node or group, or a move into the node itself.
+*/
+function moveNode(tree, id, parent, index) {
+	const node = findNode(tree, id);
+	const target = findNode(tree, parent);
+	if (node === void 0 || parentOf(tree, id) === void 0 || target?.type !== "group" || contains(node, parent)) return tree;
+	return insertNode(removeNode(tree, id), parent, node, index);
+}
+/** Changes a group's `and` or `or`. */
+function setCombinator(tree, id, combinator) {
+	return updateNode(tree, id, (node) => node.type === "group" ? {
+		...node,
+		combinator
+	} : node);
+}
+const arityOf = (field, operator) => field === void 0 ? void 0 : FILTER_OPERATORS[field.type].find((entry) => entry.value === operator)?.arity;
+function withoutValue(rule) {
+	const { value: _value, ...rest } = rule;
+	return rest;
+}
+/**
+* Points a rule at another field. A field of the same type keeps the
+* operator it allows, and its value; another type starts at the field's
+* first operator without a value.
+*/
+function setRuleField(rule, field, previous) {
+	const operators = ruleOperators(field);
+	const keep = previous?.type === field.type && operators.some((entry) => entry.value === rule.operator);
+	const path = field.id.split(".");
+	return keep ? {
+		...rule,
+		path
+	} : withoutValue({
+		...rule,
+		path,
+		operator: operators[0]?.value ?? ""
+	});
+}
+/**
+* Changes a rule's operator. The value stays when the new operator takes
+* the same kind of value (one, many or a range), and is dropped otherwise.
+*/
+function setRuleOperator(rule, operator, field) {
+	const same = arityOf(field, rule.operator) === arityOf(field, operator);
+	const next = {
+		...rule,
+		operator
+	};
+	return same && arityOf(field, operator) !== "none" ? next : withoutValue(next);
+}
+//#endregion
+//#region src/blocks/rules/client.ts
+const draftOf = (snapshot) => JSON.stringify([
+	snapshot.name,
+	snapshot.conditions,
+	snapshot.actions,
+	snapshot.stopProcessing
+]);
+const fieldById = (fields, id) => fields?.find((field) => field.id === id);
+/**
+* The editor state of one rule: the field catalog, the condition tree and
+* the edits to it, with validation, dirty state and save.
+*/
+function createRuleBuilderController(options) {
+	const { client, organizationId } = options;
+	const limits = options.limits ?? RULE_LIMITS;
+	const newId = options.newId ?? (() => crypto.randomUUID());
+	const blank = {
+		name: "",
+		conditions: options.initial ?? emptyConditions(),
+		actions: [],
+		stopProcessing: false
+	};
+	return defineController({
+		rule: void 0,
+		fields: void 0,
+		...blank,
+		locked: options.locked ?? [],
+		issues: [],
+		dirty: false,
+		loading: true,
+		saving: false,
+		error: void 0
+	}, (state) => {
+		let baseline = draftOf(blank);
+		const issuesOf = (conditions, fields) => fields === void 0 ? [] : checkRuleConditions(conditions, fields, limits);
+		const edit = (patch) => {
+			state.set((current) => {
+				const next = {
+					...current,
+					...patch
+				};
+				return {
+					...patch,
+					issues: issuesOf(next.conditions, current.fields),
+					dirty: draftOf(next) !== baseline
+				};
+			});
+		};
+		const isLocked = (id) => state.get().locked.includes(id);
+		/** Locked nodes, and groups that hold one, stay where they are. */
+		const holdsLocked = (id) => {
+			const node = findNode(state.get().conditions, id);
+			return node !== void 0 && state.get().locked.some((locked) => findNode(node, locked) !== void 0);
+		};
+		const editTree = (id, change) => {
+			if (isLocked(id)) return;
+			edit({ conditions: change(state.get().conditions) });
+		};
+		const editRule = (id, change) => {
+			editTree(id, (tree) => updateNode(tree, id, (node) => node.type === "rule" ? change(node, state.get().fields) : node));
+		};
+		const restore = (rule) => {
+			const draft = rule === void 0 ? blank : {
+				name: rule.name,
+				conditions: rule.conditions,
+				actions: rule.actions,
+				stopProcessing: rule.stopProcessing
+			};
+			baseline = draftOf(draft);
+			state.set((current) => ({
+				rule,
+				...draft,
+				issues: issuesOf(draft.conditions, current.fields),
+				dirty: false
+			}));
+		};
+		const refresh = async () => {
+			const run = state.run();
+			state.set({ loading: true });
+			const [fields, rule] = await Promise.all([client.fields(options.subjectType), options.rule === null ? Promise.resolve(void 0) : client.get(options.rule)]);
+			if (run !== state.run()) return;
+			const failure = rule?.ok === false ? rule.error : void 0;
+			state.set({
+				loading: false,
+				error: fields.ok ? failure : fields.error,
+				...fields.ok ? { fields: fields.data } : {}
+			});
+			if (rule === void 0 || rule.ok) restore(rule?.data);
+		};
+		const addRule = (group, field) => {
+			const id = newId();
+			const target = group ?? state.get().conditions.id;
+			const chosen = field === void 0 ? void 0 : fieldById(state.get().fields, field);
+			const operator = chosen === void 0 ? "" : ruleOperators(chosen)[0]?.value ?? "";
+			edit({ conditions: insertNode(state.get().conditions, target, {
+				id,
+				type: "rule",
+				path: chosen === void 0 ? [] : chosen.id.split("."),
+				operator
+			}) });
+			return id;
+		};
+		const addGroup = (group, combinator = "and") => {
+			const id = newId();
+			const target = group ?? state.get().conditions.id;
+			edit({ conditions: insertNode(state.get().conditions, target, {
+				id,
+				type: "group",
+				combinator,
+				rules: []
+			}) });
+			return id;
+		};
+		const save = async (saveOptions = {}) => {
+			const current = state.get();
+			const run = state.run();
+			state.set({
+				saving: true,
+				error: void 0
+			});
+			const saved = await client.save(organizationId, {
+				...current.rule === void 0 ? {
+					subjectType: options.subjectType,
+					...options.trigger === void 0 ? {} : { trigger: options.trigger }
+				} : {
+					id: current.rule.id,
+					version: current.rule.version
+				},
+				name: current.name,
+				conditions: current.conditions,
+				actions: current.actions,
+				stopProcessing: current.stopProcessing,
+				...saveOptions.enabled === void 0 ? {} : { enabled: saveOptions.enabled }
+			});
+			if (run !== state.run()) return saved.ok ? saved.data : void 0;
+			state.set({ saving: false });
+			if (!saved.ok) {
+				state.set({ error: saved.error });
+				return;
+			}
+			restore(saved.data);
+			return saved.data;
+		};
+		return {
+			actions: {
+				refresh,
+				addRule,
+				addGroup,
+				remove: (id) => {
+					if (!holdsLocked(id)) edit({ conditions: removeNode(state.get().conditions, id) });
+				},
+				move: (id, group, index) => {
+					if (!holdsLocked(id)) edit({ conditions: moveNode(state.get().conditions, id, group, index) });
+				},
+				setField: (id, field) => {
+					editRule(id, (rule, fields) => {
+						const next = fieldById(fields, field);
+						return next === void 0 ? rule : setRuleField(rule, next, fieldById(fields, rule.path.join(".")));
+					});
+				},
+				setOperator: (id, operator) => {
+					editRule(id, (rule, fields) => setRuleOperator(rule, operator, fieldById(fields, rule.path.join("."))));
+				},
+				setValue: (id, value) => {
+					editRule(id, (rule) => ({
+						...rule,
+						value
+					}));
+				},
+				setNegated: (id, negated) => {
+					editRule(id, (rule) => ({
+						...rule,
+						negated
+					}));
+				},
+				setCombinator: (group, combinator) => {
+					editTree(group, (tree) => setCombinator(tree, group, combinator));
+				},
+				setName: (name) => {
+					edit({ name });
+				},
+				setActions: (actions) => {
+					edit({ actions });
+				},
+				setStopProcessing: (stopProcessing) => {
+					edit({ stopProcessing });
+				},
+				lock: (id) => {
+					if (!isLocked(id)) state.set({ locked: [...state.get().locked, id] });
+				},
+				unlock: (id) => {
+					state.set({ locked: state.get().locked.filter((locked) => locked !== id) });
+				},
+				reset: () => {
+					restore(state.get().rule);
+				},
+				save
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { ruleFilterFieldInfo as _, insertNode as a, removeNode as c, setRuleField as d, setRuleOperator as f, defineRuleFields as g, checkRuleConditions as h, findNode as i, ruleOperators as l, RULE_LIMITS as m, contains as n, moveNode as o, updateNode as p, emptyConditions as r, parentOf as s, createRuleBuilderController as t, setCombinator as u, ruleFilterFields as v };

package/dist/client-BLKpcAs0.d.ts

@@ -0,0 +1,34 @@
+import { b as DbError } from "./result-Cj3yWhjH.js";
+import { a as Usage, h as UsageStatus } from "./usage-CnQHSM_r.js";
+import { n as Controller, t as AuthPort } from "./controller-CCb9tHw_.js";
+//#region src/blocks/usage/client.d.ts
+interface UsageMeterControllerOptions {
+  /** `createUsage({ transport })`, or a `Pick` with `overview`. */
+  readonly client: Pick<Usage, "overview">;
+  readonly auth: AuthPort;
+  /** The organization whose usage to read; the meter waits without one. */
+  readonly organizationId: string | null;
+  /** Only these meters, in this order. Default every meter with usage or a quota. */
+  readonly meters?: readonly string[];
+}
+/** One meter against its quota. */
+interface MeterReading extends UsageStatus {
+  /** `used / limit` from 0 to 1, or `undefined` without a limit. */
+  readonly fraction: number | undefined;
+  /** True once the period's quota is used up. */
+  readonly exceeded: boolean;
+}
+interface UsageMeterSnapshot {
+  /** `undefined` until the first load. */
+  readonly meters: readonly MeterReading[] | undefined;
+  readonly error: DbError | undefined;
+}
+interface UsageMeterActions {
+  /** Reads the usage again, such as after the app records some. */
+  readonly refresh: () => Promise<void>;
+}
+type UsageMeterController = Controller<UsageMeterSnapshot, UsageMeterActions>;
+/** This period's usage of an organization against its plan's quotas, per meter. */
+declare function createUsageMeterController(options: UsageMeterControllerOptions): UsageMeterController;
+//#endregion
+export { UsageMeterSnapshot as a, UsageMeterControllerOptions as i, UsageMeterActions as n, createUsageMeterController as o, UsageMeterController as r, MeterReading as t };

package/dist/client-BO9fQgBB.d.ts

@@ -0,0 +1,155 @@
+import { b as DbError, f as Result, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as BlockOptions } from "./block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { n as Controller, t as AuthPort } from "./controller-CCb9tHw_.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`.
+ */
+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. */
+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/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)`.
+ */
+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.
+ */
+declare function createSettingsController<E extends SettingEntries>(options: SettingsControllerOptions<E>): SettingsController<E>;
+//#endregion
+export { createSettings as _, SettingsControllerOptions as a, settingFields as c, SettingInputs as d, SettingValues as f, SettingsSpec as g, SettingsOptions as h, SettingsController as i, SettingEntries as l, SettingsDefinition as m, SettingKind as n, SettingsSnapshot as o, Settings as p, SettingsActions as r, createSettingsController as s, SettingField as t, SettingEntry as u, defineSettings as v };