better-supabase 0.12.0 → 0.14.0

package/dist/client-C56l0MnY.d.ts

@@ -0,0 +1,177 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { n as Controller } from "./controller-DAD4hbl4.js";
+import { S as CalendarEventStatus, a as FreeBusy, b as AttendeeRole, c as WorkingHoursInput, f as CalendarEvent, h as OccurrenceRange, m as OccurrenceOptions, n as CalendarEventKind, p as CalendarOccurrence, r as CalendarTransparency, s as WorkingHours, y as AttendeeResponse } from "./availability-q3dZoZYM.js";
+import { n as EventCalendarOptions, t as EventCalendarEvent } from "./event-calendar-D3SVa3AE.js";
+import { t as VisibleRange } from "./range-p5V4rBhZ.js";
+//#region src/blocks/calendar/calendar.d.ts
+interface CalendarOptions<S extends StandardSchemaV1 | undefined = undefined> {
+  /**
+   * A Standard Schema for the event columns the app adds
+   * (`blocks.calendar.options.extraColumns`), keyed by column name. It types
+   * and parses them on `events`, and validates them on `save` and the
+   * occurrence edits, which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Calendar<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface CalendarInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly tz: string;
+  readonly color?: string;
+  readonly ownerType?: string;
+  readonly ownerId?: string;
+}
+/** The fields of an event to write. Fields left out keep their value on update. */
+interface CalendarEventInput {
+  readonly title?: string;
+  readonly description?: string | null;
+  readonly location?: string | null;
+  readonly startsAt?: Temporal.Instant;
+  readonly endsAt?: Temporal.Instant;
+  readonly allDay?: boolean;
+  readonly tz?: string;
+  readonly status?: CalendarEventStatus;
+  /** An RFC 5545 `RRULE` value, or `null` to end the recurrence. */
+  readonly rrule?: string | null;
+  readonly exdates?: readonly Temporal.Instant[];
+  readonly subjectType?: string | null;
+  readonly subjectId?: string | null;
+  readonly color?: string | null;
+  /** Default `event`. */
+  readonly kind?: CalendarEventKind;
+  /** Default `opaque`; `transparent` events don't make anyone busy. */
+  readonly transparency?: CalendarTransparency;
+  /**
+   * On an `out_of_office` or `focus_time` block: decline the owner's open
+   * invitations to single events it covers, and new ones. Default `false`.
+   */
+  readonly autoDecline?: boolean;
+  /** Only on insert. Default the new id. */
+  readonly uid?: string;
+}
+interface SavedCalendarEvent {
+  readonly id: string;
+  readonly uid: string;
+  readonly created: boolean;
+}
+interface CalendarImport {
+  readonly created: number;
+  readonly updated: number;
+  /** Events without a UID or DTSTART, and overrides of an unknown series. */
+  readonly skipped: number;
+}
+/** `F` is the extra event fields `options.fields` describes. */
+interface Calendar<F extends object = Record<never, never>> {
+  createCalendar(organizationId: string, name: string, options?: {
+    readonly tz?: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
+  }): AsyncResult<{
+    readonly id: string;
+  }>;
+  deleteCalendar(id: string): AsyncResult<boolean>;
+  listCalendars(organizationId: string): AsyncResult<CalendarInfo[]>;
+  /**
+   * Inserts an event, or updates the one with `id`. Keys besides the input's
+   * own are the event's extra columns.
+   */
+  save(calendarId: string, input: CalendarEventInput & Partial<F> & {
+    readonly id?: string;
+  }): AsyncResult<SavedCalendarEvent>;
+  delete(eventId: string): AsyncResult<boolean>;
+  /** The rows that can fall in the range: events, series and their overrides. */
+  events(calendarIds: readonly string[], range: OccurrenceRange): AsyncResult<(CalendarEvent & F)[]>;
+  /** The occurrences in the range, series expanded. */
+  occurrences(calendarIds: readonly string[], range: OccurrenceRange, options?: OccurrenceOptions): AsyncResult<CalendarOccurrence[]>;
+  /** Changes one occurrence: an override for a series, else the event. */
+  editOccurrence(occurrence: CalendarOccurrence, changes: CalendarEventInput & Partial<F>): AsyncResult<SavedCalendarEvent>;
+  /**
+   * Changes an occurrence and every later one: splits the series, unless the
+   * occurrence is its first. Pass `rrule` when the change moves the weekday.
+   */
+  editFollowing(occurrence: CalendarOccurrence, changes: CalendarEventInput & Partial<F>): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** Removes one occurrence of a series (an `EXDATE`), or a single event. */
+  cancelOccurrence(occurrence: CalendarOccurrence): AsyncResult<boolean>;
+  setAttendee(eventId: string, attendee: {
+    readonly email: string;
+    readonly name?: string;
+    readonly userId?: string;
+    readonly role?: AttendeeRole;
+  }): AsyncResult<boolean>;
+  removeAttendee(eventId: string, email: string): AsyncResult<boolean>;
+  /** The signed-in user answers an invitation. */
+  respond(eventId: string, response: AttendeeResponse): AsyncResult<boolean>;
+  /** Upserts the events of an iCalendar file by UID. */
+  importIcs(calendarId: string, text: string): AsyncResult<CalendarImport>;
+  /** The calendar's events as an iCalendar file. */
+  exportIcs(calendar: CalendarInfo, range?: OccurrenceRange): AsyncResult<string>;
+  /**
+   * The iCalendar feed of a share link to a calendar (`subjectType:
+   * "calendar"`), or `null` when the token is unknown, revoked or expired.
+   */
+  feed(token: string): AsyncResult<string | null>;
+  /** Replaces a member's weekly working hours. Returns how many stretches. */
+  setWorkingHours(organizationId: string, input: WorkingHoursInput): AsyncResult<number>;
+  /** The working hours of the members that set them (all when omitted). */
+  workingHours(organizationId: string, userIds?: readonly string[]): AsyncResult<WorkingHours[]>;
+  /**
+   * When each member is busy in the range (at most 62 days, 100 members):
+   * events on calendars they own, invitations they haven't declined,
+   * out-of-office and focus-time blocks, and approved leave. It returns ranges,
+   * never titles.
+   */
+  freeBusy(organizationId: string, userIds: readonly string[], range: OccurrenceRange): AsyncResult<FreeBusy[]>;
+}
+/** A `list_calendar_events` or `calendar_feed` row as an event. */
+declare function calendarEventOf(value: unknown): CalendarEvent;
+declare function createCalendar<S extends StandardSchemaV1 | undefined = undefined>(options: CalendarOptions<S>): Calendar<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/calendar/client.d.ts
+interface CalendarControllerOptions extends EventCalendarOptions {
+  readonly client: Pick<Calendar, "occurrences" | "editOccurrence" | "editFollowing" | "cancelOccurrence">;
+  readonly calendarIds: readonly string[];
+  /** The visible range; `setRange` changes it. */
+  readonly range: VisibleRange;
+}
+interface CalendarSnapshot {
+  /** `undefined` until the first load. */
+  readonly occurrences: readonly CalendarOccurrence[] | undefined;
+  /** The occurrences as event calendar events (ReUI's `CalendarEvent` shape). */
+  readonly events: readonly EventCalendarEvent<CalendarOccurrence>[];
+  readonly error: DbError | undefined;
+  /** True until the occurrences of the current range arrive. */
+  readonly loading: boolean;
+}
+interface CalendarActions {
+  readonly refresh: () => Promise<void>;
+  /** Saves one occurrence's change, then loads the range again. */
+  readonly editOccurrence: (occurrence: CalendarOccurrence, changes: CalendarEventInput) => Promise<boolean>;
+  /** Saves the change for this and every later occurrence, then loads again. */
+  readonly editFollowing: (occurrence: CalendarOccurrence, changes: CalendarEventInput) => Promise<boolean>;
+  readonly cancelOccurrence: (occurrence: CalendarOccurrence) => Promise<boolean>;
+  /** Shows another range; the current occurrences stay until its own arrive. */
+  readonly setRange: (range: VisibleRange) => void;
+}
+type CalendarController = Controller<CalendarSnapshot, CalendarActions>;
+/**
+ * The occurrences of some calendars in the visible range, typed for a headless
+ * event calendar such as ReUI's Event Calendar.
+ */
+declare function createCalendarController(options: CalendarControllerOptions): CalendarController;
+//#endregion
+export { createCalendarController as a, CalendarImport as c, SavedCalendarEvent as d, calendarEventOf as f, CalendarSnapshot as i, CalendarInfo as l, CalendarController as n, Calendar as o, createCalendar as p, CalendarControllerOptions as r, CalendarEventInput as s, CalendarActions as t, CalendarOptions as u };

package/dist/client-CA6KuLDu.d.ts

@@ -0,0 +1,223 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { dt as SubjectRef } from "./executor-CPyrQdjh.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { a as BlockTenantOptions, i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { c as MessageEdit, l as MessageEdition, o as Message } from "./messaging-CZ6aWb10.js";
+import { p as SubscriptionStatus } from "./topic-D9j8G2dw.js";
+import { n as TopicPort } from "./watch-topic-CIT3UlAh.js";
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.js";
+//#region src/blocks/comments/comments.d.ts
+interface CommentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions, BlockTenantOptions {
+  /**
+   * A Standard Schema for the message extra columns
+   * (`blocks.messaging.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `create` and `edit`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Comments<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * The user ids (or mention groups) a comment mentions when the call passes no
+   * `mentionIds`, such as the mention nodes of a rich-text `document`. Default
+   * `mentionsIn(body)`.
+   */
+  readonly mentionsOf?: (comment: {
+    readonly body: string;
+    readonly document: unknown;
+  }) => readonly string[];
+}
+/**
+ * A comment: a message in its record's conversation. `F` types the extra
+ * columns the `fields` schema describes.
+ */
+interface Comment<F extends object = Record<never, never>> extends Message<F> {
+  /** The record the comment is on. */
+  readonly subject: SubjectRef;
+  /** The work item `assign` turned it into, with the `work-items` block. */
+  readonly taskId: string | undefined;
+}
+interface NewComment<F extends object = Record<never, never>> {
+  /** Plain text; `@[Name](<user id>)` mentions a user. */
+  readonly body: string;
+  /** A rich-text document (any JSON); keep `body` as its plain text. */
+  readonly document?: unknown;
+  /**
+   * Where on the record the comment points, such as a text range or a field
+   * (any JSON), or a page, region or moment of a file (`fileAnchor`). Top-level
+   * comments only.
+   */
+  readonly anchor?: unknown;
+  /**
+   * User ids or mention groups (`options.mentionGroups`); default `mentionsOf`,
+   * or the ids `mentionsIn(body)` finds.
+   */
+  readonly mentionIds?: readonly string[];
+  /** A reply: with one level of threads, a reply to a reply joins the root. */
+  readonly parentId?: string;
+  /** Files the caller uploaded to the record's conversation (`attachments`). */
+  readonly attachmentIds?: readonly string[];
+  /** The extra columns to set, keyed by database name. */
+  readonly fields?: Partial<F>;
+}
+/** What `edit` takes. */
+type CommentEdit<F extends object = Record<never, never>> = MessageEdition<F>;
+/** What `assign` passes to the work item. */
+interface CommentAssignment {
+  /** Who works on it; nobody when left out. */
+  readonly assigneeId?: string;
+  /** Default the comment's first 120 characters. */
+  readonly title?: string;
+  /** Default the comment's body. */
+  readonly body?: string;
+  /** Other `create_work_item` attributes, such as `projectId` or `priority`. */
+  readonly attrs?: Readonly<Record<string, unknown>>;
+}
+interface ListCommentsOptions extends CursorPageOptions<Temporal.Instant> {
+  /** Comments sent after this instant, for polling a thread. */
+  readonly cursor?: Temporal.Instant;
+  /**
+   * The id of the last comment you have, next to `cursor`, so comments sent in
+   * the same instant as it aren't skipped.
+   */
+  readonly cursorId?: string;
+  /** Default 100, at most 500. */
+  readonly limit?: number;
+  /** Comments to skip, for page-number paging. */
+  readonly offset?: number;
+}
+/**
+ * `F` is the extra fields `options.fields` describes. Every method that takes a
+ * record acts in the block's `tenant`.
+ */
+interface Comments<F extends object = Record<never, never>> {
+  /** Posts a comment on `subject`, opening its conversation the first time. */
+  create(subject: SubjectRef, comment: NewComment<F>): AsyncResult<Comment<F>>;
+  /** One comment, or `not_found` when the caller can't read it. */
+  get(id: string): AsyncResult<Comment<F>>;
+  /** The top-level comments anchored to a file (`fileAnchor`), oldest first. */
+  anchoredTo(attachmentId: string, options?: {
+    readonly limit?: number;
+  }): AsyncResult<Comment<F>[]>;
+  /** The author edits within `editWindow`; the old version is kept. */
+  edit(id: string, edit: CommentEdit<F>): AsyncResult<Comment<F>>;
+  /** Soft-deletes (the author, or a member with `comments.moderate`). */
+  remove(id: string): AsyncResult<boolean>;
+  /** Resolves a thread by its root comment, or opens it again. */
+  resolve(id: string, resolved?: boolean): AsyncResult<Comment<F>>;
+  /** Pins a comment to the top of its record, or unpins it. */
+  pin(id: string, pinned?: boolean): AsyncResult<Comment<F>>;
+  /** The earlier versions of an edited comment, newest first. */
+  edits(id: string): AsyncResult<readonly MessageEdit[]>;
+  /**
+   * Turns a comment into a work item (with the `work-items` block) and returns
+   * its id; assigning it again returns the same one.
+   */
+  assign(id: string, assignment?: CommentAssignment): AsyncResult<string>;
+  /**
+   * A record's comments and replies, oldest first, deleted ones as
+   * placeholders.
+   */
+  list(subject: SubjectRef, options?: ListCommentsOptions): AsyncResult<readonly Comment<F>[]>;
+  /**
+   * How many comments each subject has that the caller can read, deleted ones
+   * left out, such as for a counter on each row of a list, keyed by
+   * `subjectKey(subject)` (`type:id`). Subjects without comments are 0.
+   */
+  counts(subjects: readonly SubjectRef[]): AsyncResult<Readonly<Record<string, number>>>;
+  /**
+   * Copies a subject's thread to another subject in the tenant, keeping
+   * authors, times and replies; returns how many comments it copied. Needs a
+   * service-role transport.
+   */
+  copy(from: SubjectRef, to: SubjectRef): AsyncResult<number>;
+  /**
+   * The record's conversation id, for Realtime (`conversationTopic`) and for
+   * uploads to attach (`attachments` on subject `conversation`). `open` creates
+   * it before the first comment; without it, `undefined` until then.
+   */
+  conversation(subject: SubjectRef, options?: {
+    readonly open?: boolean;
+  }): AsyncResult<string | undefined>;
+  /**
+   * Moves the caller's read marker on the record's comments forward; returns
+   * where it is, or `undefined` before the first comment.
+   */
+  markRead(subject: SubjectRef, options?: {
+    readonly readAt?: Temporal.Instant;
+  }): AsyncResult<Temporal.Instant | undefined>;
+}
+/**
+ * The user ids mentioned in a body written as `@[Ada](user:<user id>)` or
+ * `@[Ada](<user id>)`, the markup mention inputs produce, in order and without
+ * repeats.
+ */
+declare function mentionsIn(body: string): readonly string[];
+/** Comments over the messaging core, as the caller. */
+declare function createComments<S extends StandardSchemaV1 | undefined = undefined>(options: CommentsOptions<S>): Comments<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/comments/client.d.ts
+interface CommentsControllerOptions {
+  readonly client: Pick<Comments, "list" | "get" | "create" | "edit" | "remove" | "resolve" | "pin" | "conversation">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The subject whose thread to follow; the thread waits without one. */
+  readonly subject: SubjectRef | null;
+  /**
+   * `blocks.messaging.options.topic`, default `messages`: the thread joins the
+   * record conversation's private topic and fetches the comment each ping
+   * names, with its thread's root for the reply count. `null` turns Realtime
+   * off, so the thread loads again after its own writes only.
+   */
+  readonly topic?: string | null;
+  /** The most comments to load, default 100, at most 500. */
+  readonly limit?: number;
+}
+interface CommentsSnapshot {
+  /**
+   * The thread, oldest first, deleted comments as placeholders; `undefined`
+   * until the first load.
+   */
+  readonly comments: readonly Comment[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+/** A reply, a rich-text document, an anchor, mentions or files for `add`. */
+type CommentDraft = Omit<NewComment, "body">;
+interface CommentsActions {
+  /** Posts a comment on the subject; a failure is also kept in `error`. */
+  readonly add: (body: string, draft?: CommentDraft) => Promise<Result<Comment>>;
+  /** Edits one of the caller's comments. */
+  readonly edit: (id: string, edit: CommentEdit) => Promise<Result<Comment>>;
+  /** Soft-deletes a comment: it stays in the thread as a placeholder. */
+  readonly remove: (id: string) => Promise<Result<boolean>>;
+  /** Resolves a thread by its root comment, or opens it again. */
+  readonly resolve: (id: string, resolved?: boolean) => Promise<Result<Comment>>;
+  readonly pin: (id: string, pinned?: boolean) => Promise<Result<Comment>>;
+  readonly refresh: () => Promise<void>;
+}
+type CommentsController = Controller<CommentsSnapshot, CommentsActions>;
+/**
+ * One subject's comment thread for the signed-in user: loads it, keeps it
+ * current after its own writes, and fetches the one comment each ping on the
+ * record conversation's topic names (joined once the record has a
+ * conversation), so a busy thread never reloads whole.
+ */
+declare function createCommentsController(options: CommentsControllerOptions): CommentsController;
+//#endregion
+export { CommentsSnapshot as a, CommentAssignment as c, CommentsOptions as d, ListCommentsOptions as f, mentionsIn as h, CommentsControllerOptions as i, CommentEdit as l, createComments as m, CommentsActions as n, createCommentsController as o, NewComment as p, CommentsController as r, Comment as s, CommentDraft as t, Comments as u };

package/dist/client-CBcq7LBg.d.ts

@@ -0,0 +1,178 @@
+import { b as DbError, f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as BlockOptions } from "./block-helpers-BaugZlJV.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.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 };