better-supabase 0.8.0 → 0.9.0

package/dist/client-LLmgiCwJ.d.ts

@@ -0,0 +1,135 @@
+import { b as DbError, f as Result } from "./result-Cj3yWhjH.js";
+import { t as Aal } from "./mfa-DtflCXEt.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+import { t as AuthReply } from "./auth-reply-Dj124sbX.js";
+//#region src/blocks/mfa/client.d.ts
+/** A factor as `auth.mfa.listFactors()` returns it. */
+interface RawMfaFactor {
+  readonly id: string;
+  readonly friendly_name?: string;
+  readonly factor_type: string;
+  readonly status: string;
+}
+/** The part of `supabase.auth.mfa` the MFA controllers call. */
+interface MfaApi {
+  listFactors(): PromiseLike<AuthReply<{
+    readonly all: readonly RawMfaFactor[];
+  }>>;
+  enroll(params: {
+    factorType: "totp";
+    friendlyName?: string;
+    issuer?: string;
+  }): PromiseLike<AuthReply<{
+    readonly id: string;
+    readonly totp: {
+      readonly qr_code: string;
+      readonly secret: string;
+      readonly uri: string;
+    };
+  }>>;
+  challengeAndVerify(params: {
+    factorId: string;
+    code: string;
+  }): PromiseLike<AuthReply<unknown>>;
+  unenroll(params: {
+    factorId: string;
+  }): PromiseLike<AuthReply<unknown>>;
+  getAuthenticatorAssuranceLevel(): PromiseLike<AuthReply<{
+    readonly currentLevel: string | null;
+    readonly nextLevel: string | null;
+  }>>;
+}
+interface MfaFactor {
+  readonly id: string;
+  readonly name: string | undefined;
+  /** `totp`, `phone` or `webauthn`. */
+  readonly type: string;
+  /** False for an enrolment the user hasn't confirmed with a code yet. */
+  readonly verified: boolean;
+}
+/** A TOTP factor waiting for its first code. */
+interface MfaEnrollment {
+  readonly factorId: string;
+  /** An SVG data URL of the QR code for authenticator apps. */
+  readonly qrCode: string;
+  /** The secret, for typing into an authenticator by hand. */
+  readonly secret: string;
+  readonly uri: string;
+}
+interface MfaAssurance {
+  /** The session's level; `undefined` until the first load. */
+  readonly level: Aal | undefined;
+  /** `aal2` when the user has a verified factor, so a challenge can raise the session. */
+  readonly nextLevel: Aal | undefined;
+}
+/** Whether `error` is the `INSUFFICIENT_AAL` refusal that asks for a step-up. */
+declare function needsStepUp(error: DbError | undefined): boolean;
+interface MfaControllerOptions {
+  /** `supabase.auth.mfa` of the browser client. */
+  readonly mfa: MfaApi;
+  readonly auth: AuthPort;
+  /** The issuer authenticator apps show; default: the Auth Site URL's host. */
+  readonly issuer?: string;
+}
+interface MfaSnapshot extends MfaAssurance {
+  /** Every factor, verified or not; `undefined` until the first load. */
+  readonly factors: readonly MfaFactor[] | undefined;
+  /** The TOTP factor `enroll` made, until `verify` or `cancel`. */
+  readonly enrollment: MfaEnrollment | undefined;
+  /** Whether an enrol, verify or unenrol call is in flight. */
+  readonly pending: boolean;
+  readonly error: DbError | undefined;
+}
+interface MfaActions {
+  /** Enrols a TOTP factor and keeps its QR code in `enrollment`. */
+  readonly enroll: (input?: {
+    readonly name?: string;
+  }) => Promise<Result<MfaEnrollment>>;
+  /** Confirms `enrollment` with a code from the app; the session is `aal2` after it. */
+  readonly verify: (code: string) => Promise<Result<MfaAssurance>>;
+  /** Removes the unconfirmed factor of `enrollment`. */
+  readonly cancel: () => Promise<void>;
+  /** Removes a factor; removing a verified one needs an `aal2` session. */
+  readonly unenroll: (factorId: string) => Promise<Result<boolean>>;
+  /** Forgets `error`. */
+  readonly dismiss: () => void;
+  readonly refresh: () => Promise<void>;
+}
+type MfaController = Controller<MfaSnapshot, MfaActions>;
+/**
+ * A user's MFA factors for a security settings page: `enroll` shows a QR
+ * code, `verify` confirms it with the first code, and `unenroll` removes a
+ * factor. The assurance level is read again after each change.
+ */
+declare function createMfaController(options: MfaControllerOptions): MfaController;
+interface StepUpControllerOptions {
+  /** `supabase.auth.mfa` of the browser client. */
+  readonly mfa: MfaApi;
+  readonly auth: AuthPort;
+}
+interface StepUpSnapshot extends MfaAssurance {
+  /** The verified factors a code can come from; `undefined` until the first load. */
+  readonly factors: readonly MfaFactor[] | undefined;
+  /** Whether the session is `aal2`. */
+  readonly satisfied: boolean;
+  readonly verifying: boolean;
+  readonly error: DbError | undefined;
+}
+interface StepUpActions {
+  /**
+   * Challenges a verified factor (the first one by default) with `code`,
+   * then reads the session's level again.
+   */
+  readonly verify: (code: string, factorId?: string) => Promise<Result<MfaAssurance>>;
+  readonly dismiss: () => void;
+  readonly refresh: () => Promise<void>;
+}
+type StepUpController = Controller<StepUpSnapshot, StepUpActions>;
+/**
+ * Raises the session to `aal2` before a call that `checkAal` guards: show
+ * it when an error passes `needsStepUp`, then retry the call once
+ * `satisfied` is true.
+ */
+declare function createStepUpController(options: StepUpControllerOptions): StepUpController;
+//#endregion
+export { MfaControllerOptions as a, MfaSnapshot as c, StepUpController as d, StepUpControllerOptions as f, needsStepUp as g, createStepUpController as h, MfaController as i, RawMfaFactor as l, createMfaController as m, MfaApi as n, MfaEnrollment as o, StepUpSnapshot as p, MfaAssurance as r, MfaFactor as s, MfaActions as t, StepUpActions as u };

package/dist/client-Lx3mlvKO.d.ts

@@ -0,0 +1,100 @@
+import { p as SubscriptionStatus } from "./topic-cMS7UtM1.js";
+import { n as TopicPort } from "./watch-topic-EFpOIIDE.js";
+import { l as StoragePort } from "./ports-DAdQyjZz.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+//#region src/blocks/inbox/client.d.ts
+/** Loads one list, e.g. a server action that calls `inbox.conversations.list()`. */
+type InboxSource<T> = () => Promise<readonly T[]>;
+interface InboxListSnapshot<T> {
+  /** `undefined` until the first load. */
+  readonly items: readonly T[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: unknown;
+}
+interface InboxListActions {
+  readonly refresh: () => Promise<void>;
+}
+interface Ports {
+  readonly topic: TopicPort;
+}
+interface InboxControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports;
+  /** The organization; the controller joins `inbox:org:<id>`. `null` waits. */
+  readonly organizationId: string | null;
+  readonly load: InboxSource<T>;
+  /** `blockConfig.inbox.options.topic` from `blocks.generated.ts`. Defaults to `inbox`. */
+  readonly topic?: string;
+  /** Runs for each broadcast, e.g. to show a toast for `message`. */
+  readonly onMessage?: (event: string, payload: unknown) => void;
+}
+type InboxController<T> = Controller<InboxListSnapshot<T>, InboxListActions>;
+/**
+ * The staff view of an organization's conversations, kept current: loads,
+ * then loads again after each ping on `inbox:org:<id>` and on rejoin.
+ */
+declare function createInboxController<T>(options: InboxControllerOptions<T>): InboxController<T>;
+interface ConversationSnapshot<T> extends InboxListSnapshot<T> {
+  /** User ids typing now, the caller left out. */
+  readonly typing: readonly string[];
+}
+interface ConversationActions extends InboxListActions {
+  /** Tells the others the caller is typing; call it on input, throttled. */
+  readonly setTyping: (typing: boolean) => void;
+}
+interface ConversationControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports;
+  /** `null` waits, e.g. before the widget opens a conversation. */
+  readonly conversationId: string | null;
+  /** The messages, oldest first. */
+  readonly load: InboxSource<T>;
+  readonly topic?: string;
+  /** How long a typing ping counts. Defaults to 5000 ms. */
+  readonly typingMs?: number;
+}
+type ConversationController<T> = Controller<ConversationSnapshot<T>, ConversationActions>;
+/**
+ * One conversation's messages, kept current over `inbox:<id>`, with typing
+ * pings between staff and the contact. Notes never reach this topic.
+ */
+declare function createConversationController<T>(options: ConversationControllerOptions<T>): ConversationController<T>;
+interface InboxWidgetControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports & {
+    readonly storage?: StoragePort;
+  };
+  /**
+   * Opens the visitor's conversation, e.g. a server action that calls
+   * `inbox.conversations.open(inboxId, { message })` with the visitor's
+   * transport. Returns its id.
+   */
+  readonly open: (message: string) => Promise<string>;
+  /** Sends into the open conversation. */
+  readonly send: (conversationId: string, message: string) => Promise<void>;
+  readonly load: (conversationId: string) => Promise<readonly T[]>;
+  /**
+   * Remembers the conversation across reloads in the storage port.
+   * Defaults to `better-supabase:inbox-widget`; `null` forgets it.
+   */
+  readonly storageKey?: string | null;
+  readonly topic?: string;
+}
+interface InboxWidgetSnapshot<T> extends ConversationSnapshot<T> {
+  readonly conversationId: string | null;
+}
+interface InboxWidgetActions extends ConversationActions {
+  /** Opens the conversation with the first message, or sends into it. */
+  readonly submit: (message: string) => Promise<void>;
+  /** Forgets the conversation, so the next message opens a new one. */
+  readonly reset: () => void;
+}
+type InboxWidgetController<T> = Controller<InboxWidgetSnapshot<T>, InboxWidgetActions>;
+/**
+ * The visitor side of an in-app inbox: the first message opens the
+ * conversation, later ones go into it, and the messages and typing pings
+ * stay current. Visitors without an account sign in anonymously first.
+ */
+declare function createInboxWidgetController<T>(options: InboxWidgetControllerOptions<T>): InboxWidgetController<T>;
+//#endregion
+export { InboxController as a, InboxListSnapshot as c, InboxWidgetController as d, InboxWidgetControllerOptions as f, createInboxWidgetController as g, createInboxController as h, ConversationSnapshot as i, InboxSource as l, createConversationController as m, ConversationController as n, InboxControllerOptions as o, InboxWidgetSnapshot as p, ConversationControllerOptions as r, InboxListActions as s, ConversationActions as t, InboxWidgetActions as u };

package/dist/client-PGRk3DGz.js

@@ -0,0 +1,98 @@
+import { s as toDbError } from "./result-BlgnMB0H.js";
+import { n as whileSignedIn, t as defineController } from "./controller-D6NyNrlZ.js";
+//#region src/blocks/api-keys/client.ts
+const newestFirst = (keys) => keys.toSorted((a, b) => b.createdAt.epochMilliseconds - a.createdAt.epochMilliseconds);
+/**
+* The API keys of an organization (or the caller's personal keys) for an
+* API keys table: `create` returns the token once, `revoke` revokes a key,
+* and both load the list again.
+*/
+function createApiKeysController(options) {
+	const { client, organizationId } = options;
+	return defineController({
+		keys: void 0,
+		creating: false,
+		created: void 0,
+		revoking: [],
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			const request = ++ticket;
+			const result = await client.list(organizationId ?? void 0);
+			if (request !== ticket) return;
+			state.set(result.ok ? {
+				keys: newestFirst(result.data),
+				error: void 0
+			} : { error: result.error });
+		};
+		const changed = async (change) => {
+			try {
+				await options.onChanged?.(change);
+			} catch (cause) {
+				state.set({ error: toDbError(cause) });
+			}
+		};
+		return {
+			actions: {
+				refresh,
+				dismiss: () => {
+					state.set({
+						created: void 0,
+						error: void 0
+					});
+				},
+				create: async (draft) => {
+					state.set({
+						creating: true,
+						created: void 0,
+						error: void 0
+					});
+					const result = await client.create(organizationId === null ? draft : {
+						...draft,
+						organizationId
+					});
+					state.set(result.ok ? {
+						creating: false,
+						created: result.data
+					} : {
+						creating: false,
+						error: result.error
+					});
+					if (result.ok) {
+						await refresh();
+						await changed({
+							kind: "created",
+							key: result.data.key
+						});
+					}
+					return result;
+				},
+				revoke: async (id) => {
+					state.set((current) => ({
+						revoking: [...current.revoking, id],
+						error: void 0
+					}));
+					const result = await client.revoke(id);
+					state.set((current) => ({
+						revoking: current.revoking.filter((each) => each !== id),
+						...result.ok ? {} : { error: result.error }
+					}));
+					if (result.ok) {
+						await refresh();
+						await changed({
+							kind: "revoked",
+							id
+						});
+					}
+					return result;
+				}
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { createApiKeysController as t };

package/dist/client-Tc47rlSe.d.ts

@@ -0,0 +1,350 @@
+/// <reference lib="esnext.temporal" />
+import { E as ValidationIssue, b as DbError, f as Result, t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { 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 { c as FilterFieldLabels, d as FilterLimits, h as FilterQuery, i as FilterCombinator, l as FilterFieldType, o as FilterField, r as FilterClock, s as FilterFieldInfo } from "./filter-query-BKmRYrTE.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+import { n as FilterRecordField, t as FilterEvaluation } from "./filter-evaluate-CjcFq0RT.js";
+//#region src/blocks/rules/fields.d.ts
+/** One field of `defineRuleFields`: a value rules on the subject type may test. */
+interface RuleFieldDefinition {
+  readonly type: FilterFieldType;
+  readonly label?: string;
+  readonly description?: string;
+  /** The subject record key the value is read from, dotted for a nested value. Defaults to the field id. */
+  readonly column?: string;
+  /**
+   * The Postgres type, which decides how dates compare: `date`, `timestamp`
+   * or `timestamptz` (the default for date fields).
+   */
+  readonly columnType?: string;
+  /** Whether the value may be missing, so "is not" also matches it. Default `true`. */
+  readonly nullable?: boolean;
+  /** Allowed values for `select` and `multiselect`. */
+  readonly options?: readonly (string | {
+    readonly value: string;
+    readonly label?: string;
+  })[];
+  /** A subset of the type's operators. */
+  readonly operators?: readonly string[];
+}
+/** A catalog field as `rule_fields_list` returns it. */
+interface RuleField {
+  readonly subjectType: string;
+  readonly id: string;
+  readonly label: string;
+  readonly description: string | undefined;
+  readonly type: FilterFieldType;
+  readonly column: string;
+  readonly columnType: string;
+  readonly nullable: boolean;
+  readonly options: readonly {
+    readonly value: string;
+    readonly label: string;
+  }[] | undefined;
+  readonly operators: readonly string[] | undefined;
+}
+/** The fields of one subject type, for `RulesAdmin.syncFields` and the editor. */
+interface RuleFieldCatalog<S extends string = string> {
+  readonly subjectType: S;
+  readonly fields: readonly RuleField[];
+}
+/**
+ * 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.
+ */
+declare function defineRuleFields<const S extends string>(subjectType: S, fields: Readonly<Record<string, RuleFieldDefinition>>): RuleFieldCatalog<S>;
+/** Catalog fields as list filter fields, for `evaluateFilterQuery` and `checkFilterQuery`. */
+declare function ruleFilterFieldInfo(fields: readonly RuleField[]): FilterFieldInfo[];
+/** The `fields` prop of ReUI's Filters for a rule editor. */
+declare function ruleFilterFields(fields: readonly RuleField[], labels?: FilterFieldLabels): FilterField[];
+/** The defaults of `blocks.rules.options`. */
+declare const RULE_LIMITS: FilterLimits;
+/**
+ * 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.
+ */
+declare function checkRuleConditions(conditions: FilterQuery, fields: readonly RuleField[], limits?: FilterLimits): readonly ValidationIssue[];
+//#endregion
+//#region src/blocks/rules/rules.d.ts
+/** What a rule runs when it matches: a kind the app handles and its settings. */
+interface RuleAction {
+  /** Such as `approvals.request` or `notifications.send`. */
+  readonly kind: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+interface Rule {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  /** The event type the rule is tested on, such as `expense.submitted`. */
+  readonly trigger: string;
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly enabled: boolean;
+  /** A match ends the evaluation, so later rules for the trigger don't run. */
+  readonly stopProcessing: boolean;
+  /** The rank key rules are tested in. */
+  readonly rank: string;
+  readonly version: number;
+  readonly createdBy: string | undefined;
+  readonly updatedBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** `save`'s input: left-out keys keep their value on an existing rule. */
+interface RuleInput {
+  readonly id?: string;
+  /** The version the editor read; a newer stored one fails with `RULE_CONFLICT`. */
+  readonly version?: number;
+  /** Required for a new rule; it can't change later. */
+  readonly subjectType?: string;
+  readonly trigger?: string;
+  readonly name?: string;
+  readonly description?: string | null;
+  readonly conditions?: FilterQuery;
+  readonly actions?: readonly RuleAction[];
+  /** Turning a rule on takes `rules.publish`. */
+  readonly enabled?: boolean;
+  readonly stopProcessing?: boolean;
+}
+interface RuleVersion {
+  readonly ruleId: string;
+  readonly version: number;
+  readonly name: string;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly savedBy: string | undefined;
+  readonly savedAt: Temporal.Instant;
+}
+/** A rule that matched, with the truth of every condition and group by node id. */
+interface RuleMatch {
+  readonly rule: Rule;
+  readonly results: Readonly<Record<string, boolean | null>>;
+}
+/** One entry of a rule's evaluation log. */
+interface RuleEvaluationEntry {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly ruleId: string;
+  readonly version: number;
+  readonly subjectType: string;
+  readonly subjectId: string | undefined;
+  readonly trigger: string;
+  readonly matched: boolean;
+  readonly results: Readonly<Record<string, boolean | null>>;
+  readonly mode: "live" | "test";
+  readonly evaluatedBy: string | undefined;
+  readonly evaluatedAt: Temporal.Instant;
+}
+interface RuleListOptions {
+  readonly subjectType?: string;
+  readonly trigger?: string;
+  readonly enabled?: boolean;
+}
+/** What `matching` and `run` test: one subject, as the trigger event saw it. */
+interface RuleSubject {
+  readonly subjectType: string;
+  readonly trigger: string;
+  /** The record the field catalog's columns read, such as the expense row with its submitter. */
+  readonly subject: Readonly<Record<string, unknown>>;
+  /** The IANA zone relative dates ("today") resolve in. Default `UTC`. */
+  readonly timeZone?: string;
+}
+interface RulesOptions extends BlockTemporalOptions {
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Rules>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface Rules {
+  /** The field catalog, for one subject type or all of them. */
+  fields(subjectType?: string): AsyncResult<readonly RuleField[]>;
+  /** The organization's rules in evaluation order (needs `rules.read`). */
+  list(organizationId: string, options?: RuleListOptions): AsyncResult<readonly Rule[]>;
+  /** `undefined` when the caller can't read a rule with this id. */
+  get(id: string): AsyncResult<Rule | undefined>;
+  /**
+   * Creates or changes a rule. `rules.edit` covers disabled rules;
+   * enabling a rule or changing an enabled one takes `rules.publish`.
+   */
+  save(organizationId: string, input: RuleInput): AsyncResult<Rule>;
+  /** Turns a rule on or off (needs `rules.publish`). */
+  setEnabled(id: string, enabled: boolean): AsyncResult<Rule>;
+  /** Moves a rule to a rank key from `rankBetween` over its neighbours. */
+  move(id: string, rank: string): AsyncResult<Rule>;
+  /** Removes a rule with its history (needs `rules.admin`); `false` when there is none to remove. */
+  remove(id: string): AsyncResult<boolean>;
+  /** Saved versions, newest first. */
+  versions(id: string): AsyncResult<readonly RuleVersion[]>;
+  /** The evaluation log, newest first. */
+  evaluations(id: string, options?: {
+    readonly before?: Temporal.Instant;
+    readonly pageSize?: number;
+  }): AsyncResult<readonly RuleEvaluationEntry[]>;
+  /** The enabled rules for the trigger that match, evaluated in the database. */
+  matching(organizationId: string, input: RuleSubject): AsyncResult<readonly RuleMatch[]>;
+  /**
+   * Runs a rule's stored conditions on a sample record and logs it as a test
+   * (needs `rules.edit`). Nothing runs; the result says what would match.
+   */
+  test(rule: Rule, subject: Readonly<Record<string, unknown>>, options?: {
+    readonly fields?: readonly RuleField[];
+    readonly subjectId?: string;
+    readonly clock?: FilterClock;
+  }): AsyncResult<FilterEvaluation>;
+}
+/** A rule row from the module's functions. */
+declare function ruleOf(value: unknown): Rule;
+/** Catalog fields in the shape `evaluateFilterQuery` reads. */
+declare function ruleRecordFields(fields: readonly RuleField[]): readonly FilterRecordField[];
+/**
+ * Tests a rule's conditions on one record in memory, the same way the
+ * database's `rule_evaluate` does. `fields` is the subject type's catalog.
+ */
+declare function evaluateRule(rule: Pick<Rule, "conditions">, subject: unknown, fields: readonly RuleField[], clock?: FilterClock): FilterEvaluation;
+/** Tenant rules as the caller: the catalog, the rules, their history and tests. */
+declare function createRules(options: RulesOptions): Rules;
+interface RulesAdminOptions extends BlockTemporalOptions {
+  /** A service-role transport: `sync_rule_fields` and `run_rules` are granted to `service_role` only. */
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface RulesAdmin {
+  /** Replaces the subject type's field catalog; returns how many fields it has. */
+  syncFields(catalog: RuleFieldCatalog): AsyncResult<number>;
+  /** Evaluates the enabled rules for the trigger, logs each one live and returns the matches. */
+  run(organizationId: string, input: RuleSubject & {
+    readonly subjectId?: string;
+  }): AsyncResult<readonly RuleMatch[]>;
+}
+/** The field sync and live evaluation, with a service-role client. */
+declare function createRulesAdmin(options: RulesAdminOptions): RulesAdmin;
+/** What a handler receives: the action, the rule it belongs to and the dispatch context. */
+interface RuleActionCall<C = unknown> {
+  readonly action: RuleAction;
+  readonly rule: Rule;
+  readonly results: Readonly<Record<string, boolean | null>>;
+  readonly context: C;
+}
+/** Runs one action kind. Return a `Result`; a throw becomes an `unexpected` error. */
+type RuleActionHandler<C = unknown> = (call: RuleActionCall<C>) => Result<unknown> | PromiseLike<Result<unknown>>;
+/** The outcome of one action: its value, or the error its handler returned. */
+type RuleActionOutcome = {
+  readonly ruleId: string;
+  readonly kind: string;
+  readonly ok: true;
+  readonly value: unknown;
+} | {
+  readonly ruleId: string;
+  readonly kind: string;
+  readonly ok: false;
+  readonly error: DbError;
+};
+interface RuleDispatcherOptions<C> {
+  /** A handler per action kind, such as `approvals.request`. */
+  readonly handlers: Readonly<Record<string, RuleActionHandler<C>>>;
+}
+interface RuleDispatcher<C = unknown> {
+  /**
+   * Runs the actions of `matches` in order. A failed action doesn't stop the
+   * others; each one's outcome comes back. A kind without a handler is an
+   * `invalid_request` outcome with the hint `RULE_ACTION_UNKNOWN`.
+   */
+  dispatch(matches: readonly RuleMatch[], context: C): AsyncResult<readonly RuleActionOutcome[]>;
+}
+/** Runs matched rules' actions with the app's handlers. */
+declare function createRuleDispatcher<C = unknown>(options: RuleDispatcherOptions<C>): RuleDispatcher<C>;
+//#endregion
+//#region src/blocks/rules/client.d.ts
+interface RuleBuilderControllerOptions {
+  readonly client: Pick<Rules, "fields" | "get" | "save">;
+  readonly auth: AuthPort;
+  readonly organizationId: string;
+  /** The rule to edit; `null` edits a new one. */
+  readonly rule: string | null;
+  /** The record type whose fields the rules test. */
+  readonly subjectType: string;
+  /** A new rule's trigger, such as `expense.submitted`. */
+  readonly trigger?: string;
+  /** The tree a new rule starts with, such as a fixed first condition. */
+  readonly initial?: FilterQuery;
+  /**
+   * Node ids the editor may not change, move or remove, such as the fixed
+   * first condition. Only the editor knows them; the stored rule doesn't.
+   */
+  readonly locked?: readonly string[];
+  /** Defaults to `RULE_LIMITS`. */
+  readonly limits?: FilterLimits;
+  /** Makes node ids. Defaults to `crypto.randomUUID()`. */
+  readonly newId?: () => string;
+}
+interface RuleBuilderSnapshot {
+  /** The stored rule; `undefined` for a new one or before the first load. */
+  readonly rule: Rule | undefined;
+  /** The subject type's field catalog; `undefined` until loaded. */
+  readonly fields: readonly RuleField[] | undefined;
+  readonly name: string;
+  readonly conditions: FilterQuery;
+  readonly actions: readonly RuleAction[];
+  readonly stopProcessing: boolean;
+  readonly locked: readonly string[];
+  /** Problems in the tree, checked against the fields once they load. */
+  readonly issues: readonly ValidationIssue[];
+  /** Whether the name, tree, actions or `stopProcessing` differ from the stored rule. */
+  readonly dirty: boolean;
+  readonly loading: boolean;
+  readonly saving: boolean;
+  readonly error: DbError | undefined;
+}
+interface RuleBuilderActions {
+  /** Loads the fields and the rule again, dropping unsaved edits. */
+  readonly refresh: () => Promise<void>;
+  /** Adds a condition to `group` (the root by default) and returns its id. */
+  readonly addRule: (group?: string, field?: string) => string;
+  /** Adds an empty group to `group` (the root by default) and returns its id. */
+  readonly addGroup: (group?: string, combinator?: FilterCombinator) => string;
+  readonly remove: (id: string) => void;
+  /** Moves a node into `group`, where it ends up at `index`. */
+  readonly move: (id: string, group: string, index: number) => void;
+  readonly setField: (id: string, field: string) => void;
+  /** Keeps the value when the operator takes the same kind of value. */
+  readonly setOperator: (id: string, operator: string) => void;
+  readonly setValue: (id: string, value: unknown) => void;
+  readonly setNegated: (id: string, negated: boolean) => void;
+  readonly setCombinator: (group: string, combinator: FilterCombinator) => void;
+  readonly setName: (name: string) => void;
+  readonly setActions: (actions: readonly RuleAction[]) => void;
+  readonly setStopProcessing: (stop: boolean) => void;
+  readonly lock: (id: string) => void;
+  readonly unlock: (id: string) => void;
+  /** Drops unsaved edits. */
+  readonly reset: () => void;
+  /**
+   * Saves the rule, `enabled` turning it on or off with it. The saved rule,
+   * or `undefined` with `error` set.
+   */
+  readonly save: (options?: {
+    readonly enabled?: boolean;
+  }) => Promise<Rule | undefined>;
+}
+type RuleBuilderController = Controller<RuleBuilderSnapshot, RuleBuilderActions>;
+/**
+ * The editor state of one rule: the field catalog, the condition tree and
+ * the edits to it, with validation, dirty state and save.
+ */
+declare function createRuleBuilderController(options: RuleBuilderControllerOptions): RuleBuilderController;
+//#endregion
+export { RuleField as A, createRuleDispatcher as C, ruleOf as D, evaluateRule as E, ruleFilterFieldInfo as F, ruleFilterFields as I, RuleFieldDefinition as M, checkRuleConditions as N, ruleRecordFields as O, defineRuleFields as P, RulesOptions as S, createRulesAdmin as T, RuleSubject as _, createRuleBuilderController as a, RulesAdmin as b, RuleActionCall as c, RuleDispatcher as d, RuleDispatcherOptions as f, RuleMatch as g, RuleListOptions as h, RuleBuilderSnapshot as i, RuleFieldCatalog as j, RULE_LIMITS as k, RuleActionHandler as l, RuleInput as m, RuleBuilderController as n, Rule as o, RuleEvaluationEntry as p, RuleBuilderControllerOptions as r, RuleAction as s, RuleBuilderActions as t, RuleActionOutcome as u, RuleVersion as v, createRules as w, RulesAdminOptions as x, Rules as y };