better-supabase 0.12.0 → 0.14.0

package/dist/client-Cp79i2ZE.d.ts

@@ -0,0 +1,152 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, t as AsyncResult } from "./result-C6jDfedy.js";
+import { dt as SubjectRef } from "./executor-CPyrQdjh.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { a as BlockTenantOptions, 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 { 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/reactions/reactions.d.ts
+interface ReactionsOptions extends BlockTemporalOptions, BlockTenantOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Reactions>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** One emoji on a subject. */
+interface ReactionCount {
+  /** The emoji, or a custom emoji's `:shortcode:`. */
+  readonly emoji: string;
+  readonly count: number;
+  /** Whether the signed-in user reacted with it. */
+  readonly reacted: boolean;
+  /** The first ten actors (user ids, or names the service passed), oldest first. */
+  readonly actors: readonly string[];
+}
+/** A subject's votes. */
+interface VoteTally {
+  /** Up votes minus down votes. */
+  readonly score: number;
+  readonly up: number;
+  readonly down: number;
+  /** The signed-in user's vote: `1`, `-1`, or `0` for none. */
+  readonly vote: -1 | 0 | 1;
+}
+/** `1` votes up, `-1` down, `0` clears the vote. */
+type VoteValue = -1 | 0 | 1;
+interface VoteOptions {
+  /** The service role votes for this actor (default `service`). */
+  readonly actor?: string;
+}
+interface CustomEmoji {
+  readonly id: string;
+  /** Without the colons: `party-parrot` is used as `:party-parrot:`. */
+  readonly shortcode: string;
+  /** An attachment from the `attachments` module. */
+  readonly attachmentId?: string;
+  /** An `https://` image URL. */
+  readonly url?: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface CustomEmojiInput {
+  readonly shortcode: string;
+  readonly attachmentId?: string;
+  readonly url?: string;
+}
+interface ReactOptions {
+  /** `false` removes the reaction. Default: `true`. */
+  readonly present?: boolean;
+  /** The service role reacts for this actor (default `service`). */
+  readonly actor?: string;
+}
+/** Every method but `deleteCustomEmoji` acts in the block's `tenant`. */
+interface Reactions {
+  /** Adds or removes the caller's reaction; returns the subject's reactions. */
+  react(subject: SubjectRef, emoji: string, options?: ReactOptions): AsyncResult<readonly ReactionCount[]>;
+  /**
+   * The reactions of `subjects` (up to 200 of each type), keyed by
+   * `subjectKey(subject)` (`type:id`). Subjects without reactions may be left
+   * out.
+   */
+  summary(subjects: readonly SubjectRef[]): AsyncResult<Readonly<Record<string, readonly ReactionCount[]>>>;
+  /**
+   * Sets the caller's vote on `subject` and returns its tally. Votes use the
+   * `create` permission and the subject's read rules, like `react`.
+   */
+  vote(subject: SubjectRef, value: VoteValue, options?: VoteOptions): AsyncResult<VoteTally>;
+  /**
+   * The vote tallies of `subjects` (up to 200 of each type), keyed by
+   * `subjectKey(subject)`.
+   */
+  votes(subjects: readonly SubjectRef[]): AsyncResult<Readonly<Record<string, VoteTally>>>;
+  /** The tenant's custom emoji, by shortcode. */
+  customEmoji(): AsyncResult<readonly CustomEmoji[]>;
+  /** Adds a custom emoji, or replaces the image of an existing shortcode. */
+  saveCustomEmoji(input: CustomEmojiInput): AsyncResult<CustomEmoji>;
+  /** Deletes a custom emoji and the reactions that used it. */
+  deleteCustomEmoji(id: string): AsyncResult<boolean>;
+}
+/** The topic the module broadcasts an organization's reaction changes to. */
+declare function reactionsTopic(organizationId: string, topic?: string): string;
+/** The `reactions` SQL module as typed calls. */
+declare function createReactions(options: ReactionsOptions): Reactions;
+//#endregion
+//#region src/blocks/reactions/client.d.ts
+interface ReactionsControllerOptions {
+  readonly client: Pick<Reactions, "summary" | "react">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /**
+   * The tenant whose reaction broadcasts to hear, the client's own; the
+   * controller waits without one.
+   */
+  readonly tenant: string | null;
+  /**
+   * The subjects on screen, at most 200 of each type; `setSubjects` changes
+   * them.
+   */
+  readonly subjects: readonly SubjectRef[];
+  /**
+   * `blockConfig.reactions.options.topic` from `blocks.generated.ts`; `null`
+   * loads without listening.
+   */
+  readonly topic?: string | null;
+}
+interface ReactionsSnapshot {
+  /**
+   * Reactions keyed by `subjectKey(subject)` (`type:id`); `undefined` until the
+   * first load.
+   */
+  readonly reactions: Readonly<Record<string, readonly ReactionCount[]>> | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+interface ReactionsActions {
+  /** Adds the emoji, or removes it when the user already reacted with it. */
+  readonly toggle: (subject: SubjectRef, emoji: string) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+  /**
+   * Watches other subjects, such as the rows on screen after a scroll, and
+   * loads them.
+   */
+  readonly setSubjects: (subjects: readonly SubjectRef[]) => void;
+}
+type ReactionsController = Controller<ReactionsSnapshot, ReactionsActions>;
+/**
+ * The reactions of the subjects on screen, loaded again when anyone in the
+ * tenant reacts to one of them. `toggle` feeds an emoji picker.
+ */
+declare function createReactionsController(options: ReactionsControllerOptions): ReactionsController;
+//#endregion
+export { createReactionsController as a, ReactOptions as c, ReactionsOptions as d, VoteOptions as f, reactionsTopic as g, createReactions as h, ReactionsSnapshot as i, ReactionCount as l, VoteValue as m, ReactionsController as n, CustomEmoji as o, VoteTally as p, ReactionsControllerOptions as r, CustomEmojiInput as s, ReactionsActions as t, Reactions as u };

package/dist/client-CwKsEl6q.js

@@ -0,0 +1,99 @@
+import { s as toDbError } from "./result-B3m7xtRY.js";
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.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 () => {
+			ticket += 1;
+			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-D-LPdEDQ.d.ts

@@ -0,0 +1,43 @@
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.js";
+import { t as EntitlementClaimOptions } from "./entitlements-DDevu4ZE.js";
+//#region src/blocks/entitlements/client.d.ts
+interface FeatureGateControllerOptions {
+  readonly auth: AuthPort;
+  /** The plan feature, such as `exports`: a key of `entitlements.source.plans`. */
+  readonly feature: string;
+  /**
+   * The organization to check. Default the session's active one, from the
+   * tenant claim.
+   */
+  readonly organizationId?: string | null;
+  /**
+   * `config.claims.features` (default `features`), or `{ claim, keys }` for
+   * short codes.
+   */
+  readonly claim?: string | EntitlementClaimOptions;
+  /** The tenant claim, `config.claims.tenant` (default `tenant_id`). */
+  readonly tenantClaim?: string;
+}
+interface FeatureGateSnapshot {
+  /**
+   * `undefined` while the session loads; false when signed out or outside an
+   * organization.
+   */
+  readonly allowed: boolean | undefined;
+  /** The organization the check ran for. */
+  readonly organizationId: string | undefined;
+}
+interface FeatureGateActions {
+  /** Checks the session again, such as after a refresh the gate did not hear of. */
+  readonly recheck: () => void;
+}
+type FeatureGateController = Controller<FeatureGateSnapshot, FeatureGateActions>;
+/**
+ * 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()`.
+ */
+declare function createFeatureGateController(options: FeatureGateControllerOptions): FeatureGateController;
+//#endregion
+export { createFeatureGateController as a, FeatureGateSnapshot as i, FeatureGateController as n, FeatureGateControllerOptions as r, FeatureGateActions as t };

package/dist/client-D6gD9qt9.d.ts

@@ -0,0 +1,45 @@
+import { b as DbError } from "./result-C6jDfedy.js";
+import { n as Controller } from "./controller-DAD4hbl4.js";
+import { f as Bookings, m as PlacedBooking, r as BookingCustomer, u as BookingSlot } from "./bookings-CC7IeiRa.js";
+import { t as VisibleRange } from "./range-p5V4rBhZ.js";
+//#region src/blocks/bookings/client.d.ts
+interface AvailableSlotsOptions {
+  readonly client: Pick<Bookings, "availableSlots" | "hold"> & {
+    readonly public: Pick<Bookings["public"], "slots" | "hold">;
+  };
+  readonly serviceId: string;
+  /** The visible range; `setRange` changes it. */
+  readonly range: VisibleRange;
+  /** The zone slot times are shown in. Default each resource's. */
+  readonly tz?: string;
+  readonly resourceId?: string;
+  /** A share-link token: loads and holds slots as a guest. */
+  readonly token?: string;
+}
+interface AvailableSlotsSnapshot {
+  /** `undefined` until the first load. */
+  readonly slots: readonly BookingSlot[] | undefined;
+  /** The slots by local date (`YYYY-MM-DD`), for a day-by-day picker. */
+  readonly days: ReadonlyMap<string, readonly BookingSlot[]>;
+  readonly error: DbError | undefined;
+  /** True until the slots of the current range arrive. */
+  readonly loading: boolean;
+}
+interface AvailableSlotsActions {
+  readonly refresh: () => Promise<void>;
+  /**
+   * Holds a slot, then loads the range again. With a token, `customer` needs a
+   * name and an email.
+   */
+  readonly hold: (slot: BookingSlot, customer?: BookingCustomer) => Promise<PlacedBooking | undefined>;
+  /** Shows another range; the current slots stay until its slots arrive. */
+  readonly setRange: (range: VisibleRange) => void;
+}
+type AvailableSlotsController = Controller<AvailableSlotsSnapshot, AvailableSlotsActions>;
+/**
+ * The open slots of a service in the visible range, for a headless date and
+ * time picker.
+ */
+declare function createAvailableSlotsController(options: AvailableSlotsOptions): AvailableSlotsController;
+//#endregion
+export { createAvailableSlotsController as a, AvailableSlotsSnapshot as i, AvailableSlotsController as n, AvailableSlotsOptions as r, AvailableSlotsActions as t };

package/dist/client-DBwWXQKF.d.ts

@@ -0,0 +1,132 @@
+/// <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 { 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 { 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/announcements/announcements.d.ts
+type AnnouncementSeverity = "info" | "success" | "warning" | "critical";
+/**
+ * Who sees it: everyone, members of some tenants, members with some roles, or
+ * tenants on some plans (entitlement lookup keys, with the entitlements
+ * module).
+ */
+type AnnouncementAudience = {
+  readonly type: "all";
+} | {
+  readonly type: "tenant";
+  readonly organizationIds: readonly string[];
+} | {
+  readonly type: "role";
+  readonly roles: readonly string[];
+} | {
+  readonly type: "plan";
+  readonly plans: readonly string[];
+};
+interface Announcement {
+  readonly id: string;
+  readonly title: string;
+  readonly body: string;
+  readonly severity: AnnouncementSeverity;
+  readonly href: string | undefined;
+  readonly startsAt: Temporal.Instant;
+  readonly endsAt: Temporal.Instant | undefined;
+  readonly dismissible: boolean;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** An announcement as staff see it, with its audience. */
+interface ManagedAnnouncement extends Announcement {
+  readonly audience: AnnouncementAudience;
+  readonly createdBy: string | undefined;
+}
+interface AnnouncementInput {
+  readonly title: string;
+  /** Plain text or Markdown; the app renders it. */
+  readonly body?: string;
+  readonly severity?: AnnouncementSeverity;
+  /** A link for "Learn more": `https://` or a path. */
+  readonly href?: string | null;
+  readonly audience?: AnnouncementAudience;
+  readonly startsAt?: Temporal.Instant;
+  readonly endsAt?: Temporal.Instant | null;
+  readonly dismissible?: boolean;
+}
+interface AnnouncementsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the announcement columns the app adds
+   * (`blocks.announcements.options.extraColumns`), keyed by column name. It
+   * types and parses them on every read, and validates them on `publish` and
+   * `update`, which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Announcements<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[];
+}
+/** `F` is the extra fields `options.fields` describes. */
+interface Announcements<F extends object = Record<never, never>> {
+  /**
+   * The caller's live, undismissed announcements; pass the active tenant for
+   * tenant, role and plan audiences.
+   */
+  listActive(organizationId?: string | null): AsyncResult<readonly (Announcement & F)[]>;
+  /** Hides one for the caller; `false` when it was hidden already. */
+  dismiss(announcementId: string): AsyncResult<boolean>;
+  /** Every announcement; needs `announcements.manage` on the platform. */
+  list(): AsyncResult<readonly (ManagedAnnouncement & F)[]>;
+  /** Keys besides the input's own are the announcement's extra columns. */
+  publish(input: AnnouncementInput & Partial<F>): AsyncResult<ManagedAnnouncement & F>;
+  update(announcementId: string, input: Partial<AnnouncementInput> & Partial<F>): AsyncResult<ManagedAnnouncement & F>;
+  remove(announcementId: string): AsyncResult<boolean>;
+}
+declare function createAnnouncements<S extends StandardSchemaV1 | undefined = undefined>(options: AnnouncementsOptions<S>): Announcements<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/announcements/client.d.ts
+interface AnnouncementsControllerOptions {
+  readonly client: Pick<Announcements, "listActive" | "dismiss">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The active tenant, for tenant, role and plan audiences. */
+  readonly organizationId?: string | null;
+  /**
+   * The topic the module broadcasts to
+   * (`blockConfig.announcements.options.topic` from `blocks.generated.ts`);
+   * `null` loads once.
+   */
+  readonly topic?: string | null;
+}
+interface AnnouncementsSnapshot {
+  /** `undefined` until the first load. */
+  readonly items: readonly Announcement[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+interface AnnouncementsActions {
+  /** Hides one for the user, then drops it from `items`. */
+  readonly dismiss: (announcementId: string) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+}
+type AnnouncementsController = Controller<AnnouncementsSnapshot, AnnouncementsActions>;
+/**
+ * The signed-in user's live announcements, loaded again whenever staff publish,
+ * change or remove one.
+ */
+declare function createAnnouncementsController(options: AnnouncementsControllerOptions): AnnouncementsController;
+//#endregion
+export { createAnnouncementsController as a, AnnouncementInput as c, AnnouncementsOptions as d, ManagedAnnouncement as f, AnnouncementsSnapshot as i, AnnouncementSeverity as l, AnnouncementsController as n, Announcement as o, createAnnouncements as p, AnnouncementsControllerOptions as r, AnnouncementAudience as s, AnnouncementsActions as t, Announcements as u };

package/dist/client-DD3EcytK.js

@@ -0,0 +1,65 @@
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+import { n as watchRun, t as firstError } from "./run-watch-B-LoK5m1.js";
+//#region src/blocks/workflow-builder/client.ts
+/** The definitions the signed-in user may read and the step library. */
+function createWorkflowBuilderController(options) {
+	const tenant = options.tenant ?? null;
+	return defineController({
+		definitions: void 0,
+		steps: void 0,
+		error: void 0
+	}, (state) => {
+		const refresh = async () => {
+			const run = state.run();
+			const [listed, library] = await Promise.all([options.client.definitions.list(tenant ?? void 0), options.client.steps.list()]);
+			if (run !== state.run()) return;
+			state.set({
+				...listed.ok ? { definitions: listed.data } : {},
+				...library.ok ? { steps: library.data } : {},
+				error: firstError(listed, library)
+			});
+		};
+		return {
+			actions: { refresh },
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+const NO_NODES = {};
+/**
+* A run and the status of each of its nodes, loaded again on each message on
+* `workflow-run:<id>` (run status changes and node records).
+*/
+function createWorkflowCanvasRunController(options) {
+	const { client } = options;
+	const run = options.run ?? "";
+	return defineController({
+		run: void 0,
+		nodes: NO_NODES,
+		error: void 0,
+		status: "closed"
+	}, (state) => {
+		const watch = watchRun({
+			...options,
+			load: async () => {
+				const [found, listed] = await Promise.all([client.runs.get(run), client.nodeRuns.list(run)]);
+				return {
+					id: found.ok ? found.data?.id ?? null : null,
+					patch: {
+						...found.ok ? { run: found.data } : {},
+						...listed.ok ? { nodes: Object.fromEntries(listed.data.map((node) => [node.node, node])) } : {},
+						error: firstError(found, listed)
+					}
+				};
+			}
+		}, state);
+		return {
+			actions: { refresh: watch.refresh },
+			start: watch.start
+		};
+	});
+}
+//#endregion
+export { createWorkflowCanvasRunController as n, createWorkflowBuilderController as t };

package/dist/client-DScMvaty.js

@@ -0,0 +1,38 @@
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+//#region src/blocks/usage/client.ts
+function readingOf(status) {
+	const limit = status.unlimited ? void 0 : status.limit;
+	return {
+		...status,
+		fraction: limit === void 0 ? void 0 : limit === 0 ? 1 : Math.min(1, status.used / limit),
+		exceeded: limit !== void 0 && status.used >= limit
+	};
+}
+/** This period's usage of an organization against its plan's quotas, per meter. */
+function createUsageMeterController(options) {
+	const { client, organizationId, meters } = options;
+	const pick = (all) => meters === void 0 ? all : meters.flatMap((meter) => all.filter((each) => each.meter === meter));
+	return defineController({
+		meters: void 0,
+		error: void 0
+	}, (state) => {
+		const refresh = async () => {
+			if (organizationId === null) return;
+			const run = state.run();
+			const result = await client.overview(organizationId);
+			if (run !== state.run()) return;
+			state.set(result.ok ? {
+				meters: pick(result.data).map(readingOf),
+				error: void 0
+			} : { error: result.error });
+		};
+		return {
+			actions: { refresh },
+			start: () => organizationId === null ? void 0 : whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { createUsageMeterController as t };

package/dist/client-DT6Tvudr.d.ts

@@ -0,0 +1,54 @@
+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/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 };