better-supabase 0.13.0 → 0.14.0

package/dist/client-DmjG9PHH.js

@@ -0,0 +1,211 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { a as ok, r as err } from "./result-B3m7xtRY.js";
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+import { t as authResult } from "./auth-reply-jVKoAV6R.js";
+//#region src/blocks/mfa/client.ts
+const toAal = (level) => level === "aal2" ? "aal2" : level === "aal1" ? "aal1" : void 0;
+const toFactor = (raw) => ({
+	id: raw.id,
+	name: raw.friendly_name === "" ? void 0 : raw.friendly_name,
+	type: raw.factor_type,
+	verified: raw.status === "verified"
+});
+async function readAssurance(mfa) {
+	const result = await authResult(() => mfa.getAuthenticatorAssuranceLevel());
+	return result.ok ? ok({
+		level: toAal(result.data.currentLevel),
+		nextLevel: toAal(result.data.nextLevel)
+	}) : result;
+}
+async function readFactors(mfa) {
+	const result = await authResult(() => mfa.listFactors());
+	return result.ok ? ok(result.data.all.map(toFactor)) : result;
+}
+/** Whether `error` is the `INSUFFICIENT_AAL` refusal that asks for a step-up. */
+function needsStepUp(error) {
+	return error?.kind === "forbidden" && error.code === "INSUFFICIENT_AAL";
+}
+/**
+* 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.
+*/
+function createMfaController(options) {
+	const { mfa } = options;
+	return defineController({
+		factors: void 0,
+		level: void 0,
+		nextLevel: void 0,
+		enrollment: void 0,
+		pending: false,
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			ticket += 1;
+			const request = ticket;
+			const [factors, assurance] = await Promise.all([readFactors(mfa), readAssurance(mfa)]);
+			if (request !== ticket) return;
+			if (!factors.ok) {
+				state.set({ error: factors.error });
+				return;
+			}
+			if (!assurance.ok) {
+				state.set({ error: assurance.error });
+				return;
+			}
+			state.set({
+				factors: factors.data,
+				...assurance.data
+			});
+		};
+		const settle = async (result) => {
+			state.set(result.ok ? { pending: false } : {
+				pending: false,
+				error: result.error
+			});
+			if (result.ok) await refresh();
+			return result;
+		};
+		return {
+			actions: {
+				refresh,
+				dismiss: () => {
+					state.set({ error: void 0 });
+				},
+				enroll: async (input) => {
+					state.set({
+						pending: true,
+						error: void 0
+					});
+					const result = await authResult(() => mfa.enroll({
+						factorType: "totp",
+						...input?.name === void 0 ? {} : { friendlyName: input.name },
+						...options.issuer === void 0 ? {} : { issuer: options.issuer }
+					}));
+					const enrolled = result.ok ? ok({
+						factorId: result.data.id,
+						qrCode: result.data.totp.qr_code,
+						secret: result.data.totp.secret,
+						uri: result.data.totp.uri
+					}) : result;
+					if (enrolled.ok) state.set({ enrollment: enrolled.data });
+					return settle(enrolled);
+				},
+				verify: async (code) => {
+					const enrollment = state.get().enrollment;
+					if (enrollment === void 0) return err(dbError("invalid_input", "Enrol a factor before verifying it"));
+					state.set({
+						pending: true,
+						error: void 0
+					});
+					const verified = await authResult(() => mfa.challengeAndVerify({
+						factorId: enrollment.factorId,
+						code
+					}));
+					if (!verified.ok) return settle(err(verified.error));
+					state.set({ enrollment: void 0 });
+					return settle(await readAssurance(mfa));
+				},
+				cancel: async () => {
+					const enrollment = state.get().enrollment;
+					if (enrollment === void 0) return;
+					state.set({
+						enrollment: void 0,
+						pending: true
+					});
+					await settle(await authResult(() => mfa.unenroll({ factorId: enrollment.factorId })));
+				},
+				unenroll: async (factorId) => {
+					state.set({
+						pending: true,
+						error: void 0
+					});
+					const result = await authResult(() => mfa.unenroll({ factorId }));
+					return settle(result.ok ? ok(true) : result);
+				}
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+/**
+* 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.
+*/
+function createStepUpController(options) {
+	const { mfa } = options;
+	return defineController({
+		factors: void 0,
+		level: void 0,
+		nextLevel: void 0,
+		satisfied: false,
+		verifying: false,
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const assured = (assurance) => ({
+			...assurance,
+			satisfied: assurance.level === "aal2"
+		});
+		const refresh = async () => {
+			ticket += 1;
+			const request = ticket;
+			const [factors, assurance] = await Promise.all([readFactors(mfa), readAssurance(mfa)]);
+			if (request !== ticket) return;
+			if (!factors.ok) {
+				state.set({ error: factors.error });
+				return;
+			}
+			if (!assurance.ok) {
+				state.set({ error: assurance.error });
+				return;
+			}
+			state.set({
+				factors: factors.data.filter((factor) => factor.verified),
+				...assured(assurance.data)
+			});
+		};
+		return {
+			actions: {
+				refresh,
+				dismiss: () => {
+					state.set({ error: void 0 });
+				},
+				verify: async (code, factorId) => {
+					const id = factorId ?? state.get().factors?.[0]?.id;
+					if (id === void 0) {
+						const missing = dbError("invalid_input", "No verified factor to challenge");
+						state.set({ error: missing });
+						return err(missing);
+					}
+					state.set({
+						verifying: true,
+						error: void 0
+					});
+					const verified = await authResult(() => mfa.challengeAndVerify({
+						factorId: id,
+						code
+					}));
+					const result = verified.ok ? await readAssurance(mfa) : verified;
+					state.set(result.ok ? {
+						verifying: false,
+						...assured(result.data)
+					} : {
+						verifying: false,
+						error: result.error
+					});
+					return result;
+				}
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { createStepUpController as n, needsStepUp as r, createMfaController as t };

package/dist/client-DnUFHmje.js

@@ -0,0 +1,129 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { a as ok, r as err, s as toDbError } from "./result-B3m7xtRY.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 noSubject = () => err(dbError("invalid_input", "No subject is open"));
+/**
+* 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, subject, kind } = options;
+	return defineController({
+		tags: void 0,
+		available: void 0,
+		pending: [],
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			if (subject === null) return;
+			ticket += 1;
+			const request = ticket;
+			const [tags, available] = await Promise.all([client.forSubject(subject), client.list(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 (subject === null) return noSubject();
+			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(subject, 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 (subject === null) return noSubject();
+					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(subject, 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 (subject === null) return noSubject();
+					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(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: () => subject === null ? void 0 : whileSignedIn(options.auth, () => {
+				refresh();
+			})
+		};
+	});
+}
+//#endregion
+export { createTagInputController as t };

package/dist/client-Do5hykMK.d.ts

@@ -0,0 +1,38 @@
+import { b as DbError } from "./result-C6jDfedy.js";
+import { dt as SubjectRef } from "./executor-CPyrQdjh.js";
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.js";
+import { c as Subjects, o as ResolvedSubject } from "./subjects-DXFmanh5.js";
+//#region src/blocks/subjects/client.d.ts
+/**
+ * Joins the `resolve(refs)` calls made in the same tick into one, so a list
+ * where each row shows a subject link costs one round trip. Each caller gets
+ * back only the subjects it asked for.
+ */
+declare function batchSubjects(source: Subjects): Subjects;
+interface SubjectsControllerOptions {
+  /** `createSubjects()`, ideally through `batchSubjects`. */
+  readonly client: Pick<Subjects, "resolve">;
+  readonly auth: AuthPort;
+  /** The subjects to resolve; nothing loads while empty. */
+  readonly refs: readonly SubjectRef[];
+}
+interface SubjectsSnapshot {
+  /**
+   * The resolved subjects keyed by `subjectKey` (`type:id`); `undefined` until
+   * the first load. A subject the caller can't read is missing.
+   */
+  readonly subjects: Readonly<Record<string, ResolvedSubject>> | undefined;
+  readonly error: DbError | undefined;
+}
+interface SubjectsActions {
+  /** Resolves the subjects again, such as after a rename. */
+  readonly refresh: () => Promise<void>;
+}
+type SubjectsController = Controller<SubjectsSnapshot, SubjectsActions>;
+/**
+ * Titles and paths of `refs`, loaded for the signed-in user and again when
+ * another user signs in.
+ */
+declare function createSubjectsController(options: SubjectsControllerOptions): SubjectsController;
+//#endregion
+export { batchSubjects as a, SubjectsSnapshot as i, SubjectsController as n, createSubjectsController as o, SubjectsControllerOptions as r, SubjectsActions as t };

package/dist/client-DzOL3lsV.d.ts

@@ -0,0 +1,110 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, 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";
+//#region src/blocks/onboarding/onboarding.d.ts
+type ChecklistScope = "user" | "organization";
+/** One step. `events` completes it when the outbox records one of those types. */
+interface ChecklistStep<Id extends string = string> {
+  readonly id: Id;
+  readonly title?: string;
+  readonly description?: string;
+  /** Where the step is done in the app, for a "Start" link. */
+  readonly href?: string;
+  readonly events?: readonly string[];
+}
+interface ChecklistSpec<Id extends string, Scope extends ChecklistScope> {
+  readonly id: string;
+  /** `user` tracks each user; `organization` tracks each tenant. */
+  readonly scope: Scope;
+  readonly steps: readonly ChecklistStep<Id>[];
+}
+interface OnboardingOptions extends BlockOptions {
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Onboarding>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A step with the subject's progress. */
+interface StepProgress<Id extends string> extends ChecklistStep<Id> {
+  readonly completed: boolean;
+  readonly completedAt: Temporal.Instant | undefined;
+  readonly completedBy: string | undefined;
+}
+interface ChecklistProgress<Id extends string> {
+  readonly steps: readonly StepProgress<Id>[];
+  readonly completed: number;
+  readonly total: number;
+  /** Every step is complete. */
+  readonly done: boolean;
+  /** The first step not done yet. */
+  readonly next: StepProgress<Id> | undefined;
+}
+/** The organization for an organization checklist; nothing for a user one. */
+type ChecklistSubject<Scope extends ChecklistScope> = Scope extends "organization" ? [organizationId: string] : [];
+/**
+ * The onboarding block: progress through any checklist `defineChecklist`
+ * declared.
+ */
+interface Onboarding {
+  /**
+   * The subject's progress: the caller's for a user checklist, the
+   * organization's otherwise.
+   */
+  progress<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, ...subject: ChecklistSubject<Scope>): AsyncResult<ChecklistProgress<Id>>;
+  /** Marks a step done; `false` when it already was. */
+  complete<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+  /** Marks a step not done; `false` when it wasn't. */
+  reset<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+}
+/**
+ * A checklist `defineChecklist` checked; pass it to the onboarding client's
+ * methods.
+ */
+type Checklist<Id extends string, Scope extends ChecklistScope> = ChecklistSpec<Id, Scope>;
+/**
+ * Declares an onboarding checklist. Pass the result to
+ * `blocks.onboarding.options.checklists` so the database knows its steps, and
+ * to the methods of `createOnboarding` to read and complete them.
+ */
+declare function defineChecklist<const Id extends string, const Scope extends ChecklistScope>(spec: ChecklistSpec<Id, Scope>): Checklist<Id, Scope>;
+/**
+ * The onboarding block: reads and completes the steps of the checklists in
+ * `blocks.onboarding.options.checklists`, for the caller or an organization.
+ */
+declare function createOnboarding(options: OnboardingOptions): Onboarding;
+//#endregion
+//#region src/blocks/onboarding/client.d.ts
+/** The calls the controller makes for one checklist; `createOnboarding` fits. */
+interface OnboardingControllerClient<Id extends string, Scope extends ChecklistScope> {
+  progress(checklist: Checklist<Id, Scope>, ...subject: ChecklistSubject<Scope>): AsyncResult<ChecklistProgress<Id>>;
+  complete(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+  reset(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+}
+interface OnboardingControllerOptions<Id extends string, Scope extends ChecklistScope> {
+  /** `createOnboarding({ transport })`. */
+  readonly client: OnboardingControllerClient<Id, Scope>;
+  /** The checklist, from `defineChecklist`. */
+  readonly checklist: Checklist<Id, Scope>;
+  readonly auth: AuthPort;
+  /** The organization, for an organization checklist; it waits without one. */
+  readonly organizationId?: string | null;
+}
+interface OnboardingSnapshot<Id extends string> {
+  /** `undefined` until the first load. */
+  readonly progress: ChecklistProgress<Id> | undefined;
+  readonly error: DbError | undefined;
+}
+interface OnboardingActions<Id extends string> {
+  /** Marks a step done, then loads the progress again. */
+  readonly complete: (step: Id) => Promise<void>;
+  readonly reset: (step: Id) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+}
+type OnboardingController<Id extends string> = Controller<OnboardingSnapshot<Id>, OnboardingActions<Id>>;
+/** A checklist's progress for the signed-in user, or for an organization. */
+declare function createOnboardingController<Id extends string, Scope extends ChecklistScope>(options: OnboardingControllerOptions<Id, Scope>): OnboardingController<Id>;
+//#endregion
+export { defineChecklist as _, OnboardingSnapshot as a, ChecklistProgress as c, ChecklistStep as d, ChecklistSubject as f, createOnboarding as g, StepProgress as h, OnboardingControllerOptions as i, ChecklistScope as l, OnboardingOptions as m, OnboardingController as n, createOnboardingController as o, Onboarding as p, OnboardingControllerClient as r, Checklist as s, OnboardingActions as t, ChecklistSpec as u };

package/dist/client-DzukpHS1.d.ts

@@ -0,0 +1,165 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, 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 { i as KeyboardPort } from "./ports-DsJicwI2.js";
+import { n as Controller } from "./controller-DAD4hbl4.js";
+//#region src/blocks/search/search.d.ts
+interface SearchOptions extends Pick<BlockOptions, "transport" | "service" | "schema" | "mappers"> {
+  /** `withBlockHooks` hooks around the methods. */
+  readonly hooks?: BlockHooks<Search>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** One match, with the title and URL from `config.subjects`. */
+interface SearchHit {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly title: string | null;
+  readonly url: string | null;
+  /** A fragment of the body around the match, without markup. */
+  readonly snippet: string | null;
+  readonly score: number;
+}
+interface SearchQuery {
+  /** Subject types to search. Default: every type with a `search` entry. */
+  readonly types?: readonly string[];
+  /** One tenant. Default: every tenant the caller can read. */
+  readonly organizationId?: string | null;
+  /** At most 100. Default 20. */
+  readonly limit?: number;
+  /**
+   * The query's embedding, when the index keeps embeddings
+   * (`blocks.search.options.dimensions` and `vector-search`): the results fuse
+   * full-text and nearest-neighbour ranks.
+   */
+  readonly embedding?: readonly number[] | null;
+}
+/** A subject the caller opened or starred (the share-links per-user state). */
+interface SearchUserItem {
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly title: string | null;
+  readonly url: string | null;
+  readonly openedAt: Temporal.Instant | undefined;
+  readonly starredAt: Temporal.Instant | undefined;
+}
+interface SearchListOptions {
+  /** At most 100. Default 10. */
+  readonly limit?: number;
+  readonly types?: readonly string[];
+}
+/** A document whose text has no embedding yet. */
+interface PendingEmbedding {
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** Pass it back to `setEmbedding`, which skips text that changed since. */
+  readonly contentHash: string;
+  /** The title and body to embed. */
+  readonly text: string;
+}
+/** Embeds texts in order, one vector per text: an AI SDK `embedMany` call. */
+type Embedder = (texts: readonly string[]) => Promise<readonly (readonly number[])[]>;
+interface Search {
+  /**
+   * Searches as the caller: `websearch_to_tsquery` syntax (`"exact phrase"`,
+   * `-word`, `or`), prefixes for typeahead and trigram matches for typos. Rows
+   * the caller can't read, and trashed rows, are left out.
+   */
+  search(q: string, query?: SearchQuery): AsyncResult<readonly SearchHit[]>;
+  /** The caller's recently opened subjects, newest first. */
+  recents(options?: SearchListOptions): AsyncResult<readonly SearchUserItem[]>;
+  /** The caller's starred subjects, newest first. */
+  favorites(options?: SearchListOptions): AsyncResult<readonly SearchUserItem[]>;
+  /** Records that the caller opened a subject, for `recents`. */
+  touch(subjectType: string, subjectId: string): AsyncResult<boolean>;
+  /** Stars or unstars a subject for the caller, for `favorites`. */
+  star(subjectType: string, subjectId: string, starred?: boolean): AsyncResult<boolean>;
+  /** Reads one row into the index again. Service only. */
+  refresh(subjectType: string, subjectId: string): AsyncResult<boolean>;
+  /** Drops one subject from the index. Service only. */
+  remove(subjectType: string, subjectId: string): AsyncResult<boolean>;
+  /** Indexes every row of one type, or of all of them. Service only. */
+  reindex(subjectType?: string): AsyncResult<number>;
+  /** Documents without an embedding, oldest first. Service only. */
+  pendingEmbeddings(limit?: number): AsyncResult<readonly PendingEmbedding[]>;
+  /** Stores an embedding unless the text changed. Service only. */
+  setEmbedding(document: Pick<PendingEmbedding, "subjectType" | "subjectId" | "contentHash">, embedding: readonly number[]): AsyncResult<boolean>;
+  /**
+   * Embeds up to `limit` pending documents with `embed` and stores them. Run it
+   * from a job or cron. Service only. Resolves to the number stored.
+   */
+  embedPending(embed: Embedder, limit?: number): AsyncResult<number>;
+}
+/**
+ * The `search` SQL module as typed calls. Build it with the caller's transport
+ * for `search`, `recents` and `favorites`, and pass `service` for the index
+ * maintenance methods.
+ */
+declare function createSearch(options: SearchOptions): Search;
+//#endregion
+//#region src/blocks/search/groups.d.ts
+/** A row of the dialog: a match, a recent or a favorite. */
+interface CommandSearchItem {
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly title: string | null;
+  readonly url: string | null;
+  readonly snippet?: string | null;
+}
+/** One heading of the dialog: `favorites`, `recents`, or a subject type. */
+interface CommandSearchGroup {
+  readonly key: string;
+  readonly items: readonly CommandSearchItem[];
+}
+/** Groups matches by subject type, in the order the best match of each appears. */
+declare function groupHits(hits: readonly SearchHit[]): readonly CommandSearchGroup[];
+//#endregion
+//#region src/blocks/search/client.d.ts
+interface CommandSearchOptions {
+  readonly client: Pick<Search, "search" | "recents" | "favorites" | "touch" | "star">;
+  /** Toggles the dialog on Cmd+K and Ctrl+K. Without it there is no shortcut. */
+  readonly keyboard?: KeyboardPort;
+  /** One tenant. Default: every tenant the caller can read. */
+  readonly organizationId?: string | null;
+  readonly types?: readonly string[];
+  /** Results per query. Default 20. */
+  readonly limit?: number;
+  /** Recents and favorites shown before the user types. Default 5. */
+  readonly listLimit?: number;
+  /** Milliseconds between the last keystroke and the query. Default 150. */
+  readonly debounceMs?: number;
+}
+interface CommandSearchSnapshot {
+  readonly open: boolean;
+  readonly query: string;
+  /**
+   * Favorites and recents for an empty query, otherwise the matches by subject
+   * type.
+   */
+  readonly groups: readonly CommandSearchGroup[];
+  readonly results: readonly SearchHit[];
+  readonly recents: readonly SearchUserItem[];
+  readonly favorites: readonly SearchUserItem[];
+  /** True while a query newer than `results` is running. */
+  readonly loading: boolean;
+  readonly error: DbError | undefined;
+}
+interface CommandSearchActions {
+  readonly setOpen: (open: boolean) => void;
+  readonly setQuery: (query: string) => void;
+  /** Records the item as opened (for recents) and closes the dialog. */
+  readonly select: (item: CommandSearchItem) => Promise<void>;
+  readonly star: (item: CommandSearchItem, starred?: boolean) => Promise<void>;
+}
+type CommandSearchController = Controller<CommandSearchSnapshot, CommandSearchActions>;
+/**
+ * State for a Cmd+K dialog over the `search` module: a debounced query that
+ * ignores stale responses, favorites and recents for an empty query, and
+ * `select` that records the open.
+ */
+declare function createCommandSearchController(options: CommandSearchOptions): CommandSearchController;
+//#endregion
+export { createSearch as _, createCommandSearchController as a, groupHits as c, Search as d, SearchHit as f, SearchUserItem as g, SearchQuery as h, CommandSearchSnapshot as i, Embedder as l, SearchOptions as m, CommandSearchController as n, CommandSearchGroup as o, SearchListOptions as p, CommandSearchOptions as r, CommandSearchItem as s, CommandSearchActions as t, PendingEmbedding as u };