better-supabase 0.12.0 → 0.13.0

package/dist/client-_mL998Gl.js

@@ -0,0 +1,129 @@
+import { n as dbError } from "./errors-D7u24ZJH.js";
+import { a as ok, r as err, s as toDbError } from "./result-DIT_qp4G.js";
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+//#region src/blocks/tags/client.ts
+const without = (list, id) => list.filter((each) => each !== id);
+const noOrganization = () => err(dbError("invalid_input", "No organization is active"));
+/**
+* One subject's tags for a tag input: the tags on it, every tag of the kind for
+* suggestions, and `add`, `remove` and `create`, which show the change at
+* once.
+*/
+function createTagInputController(options) {
+	const { client, organizationId, subjectType, subjectId, kind } = options;
+	return defineController({
+		tags: void 0,
+		available: void 0,
+		pending: [],
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			if (organizationId === null) return;
+			ticket += 1;
+			const request = ticket;
+			const [tags, available] = await Promise.all([client.forSubject(organizationId, subjectType, subjectId), client.list(organizationId, kind)]);
+			if (request !== ticket) return;
+			if (tags.ok && available.ok) state.set({
+				tags: tags.data,
+				available: available.data,
+				error: void 0
+			});
+			else state.set({ error: tags.error ?? available.error ?? void 0 });
+		};
+		const changed = async (change) => {
+			try {
+				await options.onChanged?.(change);
+			} catch (cause) {
+				state.set({ error: toDbError(cause) });
+			}
+		};
+		const apply = async (tag, created) => {
+			if (organizationId === null) return noOrganization();
+			ticket += 1;
+			state.set((current) => ({
+				tags: current.tags?.some((each) => each.id === tag.id) ? current.tags : [...current.tags ?? [], tag],
+				pending: [...current.pending, tag.id],
+				error: void 0
+			}));
+			const result = await client.tag(organizationId, subjectType, subjectId, tag.id);
+			state.set((current) => ({
+				pending: without(current.pending, tag.id),
+				...result.ok ? {} : {
+					error: result.error,
+					tags: current.tags?.filter((each) => each.id !== tag.id)
+				}
+			}));
+			if (!result.ok) return result;
+			await changed({
+				kind: "added",
+				tag,
+				created
+			});
+			return ok(tag);
+		};
+		return {
+			actions: {
+				refresh,
+				add: async (tagId) => {
+					const tag = state.get().available?.find((each) => each.id === tagId);
+					if (!tag) return err(dbError("not_found", "No such tag"));
+					return apply(tag, false);
+				},
+				remove: async (tagId) => {
+					if (organizationId === null) return noOrganization();
+					const tag = state.get().tags?.find((each) => each.id === tagId);
+					if (!tag) return ok(false);
+					ticket += 1;
+					state.set((current) => ({
+						tags: current.tags?.filter((each) => each.id !== tagId),
+						pending: [...current.pending, tagId],
+						error: void 0
+					}));
+					const result = await client.untag(organizationId, subjectType, subjectId, tagId);
+					state.set((current) => ({
+						pending: without(current.pending, tagId),
+						...result.ok ? {} : {
+							error: result.error,
+							tags: [...current.tags ?? [], tag]
+						}
+					}));
+					if (result.ok) await changed({
+						kind: "removed",
+						tag
+					});
+					return result;
+				},
+				create: async (name) => {
+					if (organizationId === null) return noOrganization();
+					const label = name.trim();
+					if (label === "") return err(dbError("invalid_input", "A tag needs a name"));
+					const existing = state.get().available?.find((each) => each.name.toLowerCase() === label.toLowerCase());
+					if (existing) return apply(existing, false);
+					state.set((current) => ({
+						pending: [...current.pending, label],
+						error: void 0
+					}));
+					const made = await client.create(organizationId, kind, label);
+					state.set((current) => ({
+						pending: without(current.pending, label),
+						...made.ok ? { available: [...current.available ?? [], {
+							...made.data,
+							kind
+						}] } : { error: made.error }
+					}));
+					if (!made.ok) return made;
+					return apply({
+						...made.data,
+						kind
+					}, true);
+				}
+			},
+			start: () => organizationId === null ? void 0 : whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { createTagInputController as t };

package/dist/client-i_u1e0Kf.d.ts

@@ -0,0 +1,144 @@
+import { b as DbError, f as Result } from "./result-mijqfoJN.js";
+import { t as Aal } from "./mfa-Dt8AdWht.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.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-kRvHKAKS.js

@@ -0,0 +1,60 @@
+import { t as defineController } from "./controller-BEliOBOv.js";
+import { t as tenantOf } from "./tenant-DnMqeNIM.js";
+//#region src/auth/entitlements.ts
+/**
+* Whether the session's plan-features claim grants `key` in `tenantId`. `claim`
+* is `config.claims.features` (default `features`), the claim
+* `better_supabase.feature_claims()` fills, or `{ claim, keys }` when
+* `entitlements.claim.keys` writes short codes. The claim is as fresh as the
+* token: enforce it in RLS with `better_supabase.has_entitlement()`, and
+* refresh the session after checkout. A tenant left out by
+* `entitlements.claim.maxTenants` reads as not granted. Takes a server session
+* or the client's `useAuth()` snapshot.
+*/
+function hasEntitlement(session, tenantId, key, claim = "features") {
+	const options = typeof claim === "string" ? { claim } : claim;
+	const claims = "kind" in session ? session.kind === "user" ? session.claims : void 0 : session.claims;
+	if (!isRecord(claims)) return false;
+	const features = claims[options.claim ?? "features"];
+	if (!isRecord(features) || !Object.hasOwn(features, tenantId)) return false;
+	const keys = features[tenantId];
+	const code = options.keys?.[key] ?? key;
+	return Array.isArray(keys) && keys.includes(code);
+}
+const isRecord = (value) => typeof value === "object" && value !== null;
+//#endregion
+//#region src/blocks/entitlements/client.ts
+/**
+* Whether the active organization's plan includes `feature`, from the session's
+* plan-features claim. It updates when the session does, so a session refresh
+* after checkout opens the gate. UX only: enforce the feature in RLS with
+* `better_supabase.has_entitlement()`.
+*/
+function createFeatureGateController(options) {
+	const read = () => {
+		const session = options.auth.current();
+		if (session.status === "loading") return {
+			allowed: void 0,
+			organizationId: void 0
+		};
+		const organizationId = options.organizationId ?? tenantOf(session, options.tenantClaim);
+		return {
+			allowed: organizationId === void 0 ? false : hasEntitlement(session, organizationId, options.feature, options.claim),
+			organizationId
+		};
+	};
+	return defineController(read(), (state) => {
+		const recheck = () => {
+			state.set(read());
+		};
+		return {
+			actions: { recheck },
+			start: () => {
+				recheck();
+				return options.auth.subscribe(recheck);
+			}
+		};
+	});
+}
+//#endregion
+export { hasEntitlement as n, createFeatureGateController as t };

package/dist/client-nieeGXdg.d.ts

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

package/dist/client-pxXoQOdC.js

@@ -0,0 +1,40 @@
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+//#region src/blocks/onboarding/client.ts
+/** A checklist's progress for the signed-in user, or for an organization. */
+function createOnboardingController(options) {
+	const { client, checklist } = options;
+	const organizationId = options.organizationId ?? null;
+	const ready = checklist.scope === "user" || organizationId !== null;
+	const subject = checklist.scope === "organization" && organizationId !== null ? [organizationId] : [];
+	return defineController({
+		progress: void 0,
+		error: void 0
+	}, (state) => {
+		const refresh = async () => {
+			const run = state.run();
+			const result = await client.progress(checklist, ...subject);
+			if (run !== state.run()) return;
+			state.set(result.ok ? {
+				progress: result.data,
+				error: void 0
+			} : { error: result.error });
+		};
+		const change = async (action, step) => {
+			const result = await client[action](checklist, step, ...subject);
+			if (result.ok) await refresh();
+			else state.set({ error: result.error });
+		};
+		return {
+			actions: {
+				refresh,
+				complete: (step) => change("complete", step),
+				reset: (step) => change("reset", step)
+			},
+			start: () => ready ? whileSignedIn(options.auth, () => {
+				refresh();
+			}) : void 0
+		};
+	});
+}
+//#endregion
+export { createOnboardingController as t };

package/dist/client-ysVOUgxM.d.ts

@@ -0,0 +1,54 @@
+import { p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+import { n as TopicPort } from "./watch-topic-CloXeDTO.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+//#region src/blocks/notifications/client.d.ts
+/**
+ * Loads one list of items, e.g. a server action that calls
+ * `notifications.list()`.
+ */
+type NotificationSource<T> = () => Promise<readonly T[]>;
+interface NotificationFeedOptions<T> {
+  /**
+   * The private topic the `notifications` module broadcasts to:
+   * `fillTopic(blockConfig.notifications.options.topic, { userId })` with the
+   * template from `blocks.generated.ts`. `null` loads once without realtime.
+   */
+  readonly topic: string | null;
+  /** The notifications, newest first. */
+  readonly load: NotificationSource<T>;
+  /** More items merged in, such as running jobs or pending approvals. */
+  readonly sources?: readonly NotificationSource<T>[];
+  /** Orders the merged list. Defaults to the order the sources return. */
+  readonly sort?: (a: T, b: T) => number;
+  /** The badge number. Defaults to the items without a `readAt`. */
+  readonly count?: (items: readonly T[]) => number;
+  /** Runs for each broadcast, e.g. to show a toast for `notification_created`. */
+  readonly onMessage?: (event: string, payload: unknown) => void;
+}
+interface NotificationsControllerOptions<T> extends NotificationFeedOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+}
+interface NotificationsSnapshot<T> {
+  /** `undefined` until the first load. */
+  readonly items: readonly T[] | undefined;
+  readonly count: number;
+  readonly status: SubscriptionStatus;
+  readonly error: unknown;
+}
+interface NotificationsActions {
+  /** Loads again, e.g. after marking items read. */
+  readonly refresh: () => Promise<void>;
+}
+type NotificationsController<T> = Controller<NotificationsSnapshot<T>, NotificationsActions>;
+/** The default badge number: the items whose `readAt` is `null`. */
+declare const unreadCount: (items: readonly unknown[]) => number;
+/**
+ * The signed-in user's notifications, kept current: loads them, then loads
+ * again after each broadcast on `topic` and after the channel rejoins.
+ */
+declare function createNotificationsController<T>(options: NotificationsControllerOptions<T>): NotificationsController<T>;
+//#endregion
+export { NotificationsControllerOptions as a, unreadCount as c, NotificationsController as i, NotificationSource as n, NotificationsSnapshot as o, NotificationsActions as r, createNotificationsController as s, NotificationFeedOptions as t };

package/dist/clone-CkG0-hlI.js

@@ -0,0 +1,33 @@
+//#region src/core/clone.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Copies plain objects and arrays so hooks and listeners cannot change the
+* caller's result (invariant 5). Temporal values are immutable and stay
+* shared.
+*/
+function cloneValue(value) {
+	if (Array.isArray(value)) return value.map(cloneValue);
+	if (isPlainObject(value)) {
+		const copy = {};
+		for (const [key, item] of Object.entries(value)) copy[key] = cloneValue(item);
+		return copy;
+	}
+	return value;
+}
+/**
+* Freezes plain objects and arrays in place, recursively, and returns the
+* value.
+*/
+function deepFreeze(value) {
+	if (Array.isArray(value) || isPlainObject(value)) {
+		for (const item of Object.values(value)) deepFreeze(item);
+		Object.freeze(value);
+	}
+	return value;
+}
+//#endregion
+export { deepFreeze as n, isPlainObject as r, cloneValue as t };