better-supabase 0.5.0 → 0.6.0

package/dist/block-hooks-plbZ0AbJ.d.ts

@@ -0,0 +1,107 @@
+import { b as DbError, f as Result, t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockCall } from "./block-helpers-CKtbFcRv.js";
+//#region src/core/block-hooks.d.ts
+/** A block method: anything that returns an `AsyncResult`. */
+type BlockMethod = (...args: never[]) => AsyncResult<unknown>;
+/** The names of a block client's methods that return an `AsyncResult`. */
+type BlockMethodName<C> = { [K in keyof C]: C[K] extends BlockMethod ? K : never; }[keyof C] & string;
+type ArgsOf<F> = F extends ((...args: infer A) => AsyncResult<unknown>) ? A : never;
+type DataOf<F> = F extends ((...args: never[]) => AsyncResult<infer T>) ? T : never;
+/** Which call a hook runs for. */
+interface BlockHookInfo {
+  /** The block, as `createBlocks` names it, or the name `withBlockHooks` got. */
+  readonly block: string;
+  readonly method: string;
+}
+/**
+ * Hooks for one block method. `before` runs first: return nothing to keep
+ * the arguments, a new argument list to replace them, or a `DbError` to
+ * refuse the call, which then returns that error without reaching the
+ * database. `after` observes a copy of the result and can't change it; when
+ * it throws, the logger gets the error and the caller still gets the result.
+ */
+interface BlockMethodHooks<A extends readonly unknown[], T> {
+  readonly before?: (args: A, info: BlockHookInfo) => Readonly<A> | DbError | void | Promise<Readonly<A> | DbError | void>;
+  readonly after?: (result: Result<T>, args: A, info: BlockHookInfo) => void | Promise<void>;
+}
+/** Hooks keyed by the block client's method names. */
+type BlockHooks<C> = { readonly [K in BlockMethodName<C>]?: BlockMethodHooks<ArgsOf<C[K]>, DataOf<C[K]>>; };
+interface WithBlockHooksOptions {
+  /** The block's name in `BlockHookInfo` and log messages. Default `block`. */
+  readonly block?: string;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/**
+ * Runs `hooks` around a block client's methods. Use it to add a rule the
+ * block doesn't know (refuse `invite` above a seat limit), rewrite arguments
+ * (fill a default), or observe results (metrics, an audit line). Methods
+ * without hooks are unchanged.
+ *
+ * ```ts
+ * const orgs = withBlockHooks(createOrganizations(options), {
+ *   invite: { before: ([input]) => (input.role === "owner" ? dbError("forbidden", "Owners are added by support") : undefined) },
+ * });
+ * ```
+ */
+declare function withBlockHooks<C extends object>(client: C, hooks: BlockHooks<C> | undefined, options?: WithBlockHooksOptions): C;
+/** What `extendBlock` hands the builder besides the base client. */
+interface ExtendBlockTools {
+  /**
+   * Calls a SQL function in the block's schema over its transport and maps a
+   * rejection to a `DbError`, as the block's own methods do. Needs the
+   * `transport` option.
+   */
+  readonly call: BlockCall;
+}
+interface ExtendBlockOptions {
+  /** The transport `call` uses: the one the block was created with. */
+  readonly transport?: BlockTransport;
+  /** The schema `call` targets. Default `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers `call` runs before the built-in ones. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * Adds methods to a block client. The builder gets the base client, so a
+ * new method can compose existing ones, and `call` for SQL functions the
+ * app adds to the block's schema. Redefining a base method throws: wrap it
+ * with `withBlockHooks` instead.
+ *
+ * ```ts
+ * const orgs = extendBlock(createOrganizations(options), (base, { call }) => ({
+ *   archive: (id: string) => call("archive_organization", { id }, () => undefined),
+ * }), { transport: options.transport });
+ * ```
+ */
+declare function extendBlock<C extends object, X extends object>(client: C, build: (base: C, tools: ExtendBlockTools) => X, options?: ExtendBlockOptions): C & X;
+/** One transport call, as middleware sees it. */
+interface BlockTransportRequest {
+  readonly schema: string;
+  readonly fn: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+/**
+ * Runs around every call a transport makes: tracing, a statement timeout,
+ * an extra argument every function takes. Pass a changed request to `next`
+ * to rewrite it. Reject with the error `next` rejected with so the block
+ * still maps it to a `DbError`.
+ */
+interface BlockTransportMiddleware {
+  readonly apiVersion: 1;
+  readonly name: string;
+  call(request: BlockTransportRequest, next: (request: BlockTransportRequest) => Promise<unknown>): Promise<unknown>;
+}
+/** Fills in `apiVersion: 1`. */
+declare function defineTransportMiddleware(middleware: Omit<BlockTransportMiddleware, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): BlockTransportMiddleware;
+/**
+ * A transport that runs `middleware` around `transport`, the first one
+ * outermost. Throws when a middleware targets an API other than 1.
+ */
+declare function wrapTransport(transport: BlockTransport, ...middleware: readonly BlockTransportMiddleware[]): BlockTransport;
+//#endregion
+export { BlockTransportMiddleware as a, ExtendBlockTools as c, extendBlock as d, withBlockHooks as f, BlockMethodName as i, WithBlockHooksOptions as l, BlockHooks as n, BlockTransportRequest as o, wrapTransport as p, BlockMethodHooks as r, ExtendBlockOptions as s, BlockHookInfo as t, defineTransportMiddleware as u };

package/dist/{kit-transport-DJlHQUBU.js → block-transport-BLr-ZgLc.js}

@@ -1,5 +1,5 @@
-import { r as sqlIdent } from "./template-TxrGI5jR.js";
-//#region src/core/kit-transport.ts
+import { r as sqlIdent } from "./template--jDkl3UP.js";
+//#region src/core/block-transport.ts
 /**
 * Calls the functions over Postgres, as the user `client` runs as:
 * `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
@@ -14,14 +14,16 @@ function sqlTransport(client) {
 	} };
 }
 /**
-* Calls the functions over the Data API with the user's session. The kit
-* schema must be exposed (`[api] schemas` in `config.toml`), or the modules
-* installed in `public` (`kits.<module>.schema`).
+* Calls the functions over the Data API with the user's session. Pass
+* `schema` with the API schema that `sql.modules.<module>.api` writes
+* wrappers into; without it the calls go to the module schema, which then
+* has to be exposed.
 */
-function rpcTransport(client) {
+function rpcTransport(client, options = {}) {
+	const untyped = client;
 	return { async call(schema, fn, args) {
 		const defined = Object.fromEntries(Object.entries(args).filter(([, value]) => value !== void 0));
-		const { data, error } = await client.schema(schema).rpc(fn, defined);
+		const { data, error } = await untyped.schema(options.schema ?? schema).rpc(fn, defined);
 		if (error) {
 			const message = typeof error === "object" && "message" in error ? String(error.message) : String(error);
 			throw Object.assign(new Error(message), error);
@@ -49,6 +51,8 @@ function rawError(cause) {
 		const value = field(key);
 		if (value !== void 0) raw[key] = value;
 	}
+	const detail = field("detail");
+	if (raw["details"] === void 0 && detail !== void 0) raw["details"] = detail;
 	return raw;
 }
 //#endregion

package/dist/block-transport-DvaoPuZ9.d.ts

@@ -0,0 +1,48 @@
+import { t as SqlClient } from "./executor-DbvExCFC.js";
+//#region src/core/block-transport.d.ts
+/**
+ * Calls a block function as the current user and resolves with its result.
+ * Rejects with the raw database error (a `pg` error or a PostgREST error
+ * object), which the block maps to a `DbError`.
+ */
+interface BlockTransport {
+  call(schema: string, fn: string, args: Readonly<Record<string, unknown>>): Promise<unknown>;
+}
+/**
+ * Calls the functions over Postgres, as the user `client` runs as:
+ * `sqlTransport(postgres.asUser(ctx.auth.claims))`. Works for any schema.
+ */
+declare function sqlTransport(client: SqlClient): BlockTransport;
+interface RpcResponse {
+  readonly data: unknown;
+  readonly error: unknown;
+}
+/**
+ * The part of a supabase-js client `rpcTransport` uses. The parameters are
+ * `never` so a typed `SupabaseClient<Database>` fits too: its `schema` and
+ * `rpc` only take the names its `Database` declares, which never include the
+ * block functions of a schema the types leave out.
+ */
+interface RpcClient {
+  schema(name: never): {
+    rpc(fn: never, args: never): PromiseLike<RpcResponse>;
+  };
+}
+/** Options for `rpcTransport`. */
+interface RpcTransportOptions {
+  /**
+   * The exposed schema that holds the block's entry points, such as `api`
+   * from `sql.modules.<module>.api`. Every call goes there instead of the
+   * module schema, which stays out of `[api] schemas` (doctor BS312).
+   */
+  readonly schema?: string;
+}
+/**
+ * Calls the functions over the Data API with the user's session. Pass
+ * `schema` with the API schema that `sql.modules.<module>.api` writes
+ * wrappers into; without it the calls go to the module schema, which then
+ * has to be exposed.
+ */
+declare function rpcTransport(client: RpcClient, options?: RpcTransportOptions): BlockTransport;
+//#endregion
+export { sqlTransport as i, RpcClient as n, rpcTransport as r, BlockTransport as t };

package/dist/blocks/agents/index.d.ts

@@ -0,0 +1,3 @@
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { a as AgentSkill, c as AgentsOptions, i as AgentKnowledgeScope, l as NewAgent, n as AgentFields, o as AgentVisibility, r as AgentFilter, s as Agents, t as Agent, u as createAgents } from "../../agents-CVHGd7It.js";
+export { type Agent, type AgentFields, type AgentFilter, type AgentKnowledgeScope, type AgentSkill, type AgentVisibility, type Agents, type AgentsOptions, type BlockTransport, type NewAgent, createAgents, rpcTransport, sqlTransport };

package/dist/blocks/agents/index.js

@@ -0,0 +1,123 @@
+import { t as AsyncResult } from "../../result-DzUbqgdW.js";
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { D as stringsOf, O as textOf, d as isRecord, f as notFoundError, h as optionalText, i as blockCall, k as toInstant, m as optionalInstant, n as applyTemporal, x as recordsOf, y as recordOf } from "../../block-helpers-DWHxHsEQ.js";
+//#region src/blocks/agents/agents.ts
+const VISIBILITIES = /* @__PURE__ */ new Set([
+	"private",
+	"organization",
+	"public"
+]);
+const visibilityOf = (value) => {
+	const text = textOf(value);
+	return VISIBILITIES.has(text) ? text : "private";
+};
+const instant = (value) => value instanceof Date ? toInstant(value) : toInstant(textOf(value));
+function scopesOf(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isRecord).map((item) => {
+		const id = optionalText(item["id"]);
+		const scope = textOf(item["scope"]);
+		return id === void 0 ? { scope } : {
+			scope,
+			id
+		};
+	});
+}
+function skillsOf(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter(isRecord).map((item) => ({
+		id: textOf(item["id"]),
+		provider: textOf(item["provider"]),
+		reference: isRecord(item["reference"]) ? item["reference"] : {}
+	}));
+}
+function agentOf(value) {
+	const row = recordOf(value, "agents");
+	const ratingCount = Number(row["rating_count"] ?? 0);
+	const rating = row["my_rating"];
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organization_id"]),
+		ownerId: optionalText(row["owner_id"]),
+		slug: textOf(row["slug"]),
+		name: textOf(row["name"]),
+		description: textOf(row["description"] ?? ""),
+		instructions: textOf(row["instructions"] ?? ""),
+		model: optionalText(row["model"]),
+		tools: stringsOf(row["tools"]),
+		connectorIds: stringsOf(row["connector_ids"]),
+		knowledgeScopes: scopesOf(row["knowledge_scope"]),
+		starters: stringsOf(row["starters"]),
+		visibility: visibilityOf(row["visibility"]),
+		publishedAt: optionalInstant(row["published_at"]),
+		installCount: Number(row["install_count"] ?? 0),
+		ratingCount,
+		rating: ratingCount === 0 ? void 0 : Number(row["rating_sum"] ?? 0) / ratingCount,
+		installed: row["installed"] === true,
+		myRating: rating === null || rating === void 0 ? void 0 : Number(rating),
+		skills: skillsOf(row["skills"]),
+		createdAt: instant(row["created_at"]),
+		updatedAt: instant(row["updated_at"])
+	};
+}
+const notFound = () => notFoundError("No agent you can see has this id", "AGENT_NOT_FOUND");
+function fieldsArg(fields) {
+	const out = {};
+	if (fields.slug !== void 0) out["slug"] = fields.slug;
+	if (fields.name !== void 0) out["name"] = fields.name;
+	if (fields.description !== void 0) out["description"] = fields.description;
+	if (fields.instructions !== void 0) out["instructions"] = fields.instructions;
+	if (fields.model !== void 0) out["model"] = fields.model;
+	if (fields.tools !== void 0) out["tools"] = fields.tools;
+	if (fields.connectorIds !== void 0) out["connector_ids"] = fields.connectorIds;
+	if (fields.knowledgeScopes !== void 0) out["knowledge_scope"] = fields.knowledgeScopes;
+	if (fields.starters !== void 0) out["starters"] = fields.starters;
+	return out;
+}
+/** Custom assistants: build, publish to a store, install and rate. */
+function createAgents(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const found = (value) => isRecord(value) ? AsyncResult.ok(agentOf(value)) : AsyncResult.err(notFound());
+	const save = (organizationId, agentId, fields) => call("save_agent", {
+		tenant: organizationId,
+		id: agentId,
+		fields: fieldsArg(fields)
+	}, agentOf);
+	return {
+		create: (organizationId, agent) => save(organizationId, void 0, agent),
+		update: (organizationId, agentId, fields) => save(organizationId, agentId, fields),
+		get: (agentId) => call("get_agent", { id: agentId }, (value) => value).andThen(found),
+		bySlug: (organizationId, slug) => call("get_agent", {
+			tenant: organizationId,
+			slug
+		}, (value) => value).andThen(found),
+		list: (organizationId, listOptions = {}) => call("list_agents", {
+			tenant: organizationId,
+			filter: listOptions.filter,
+			search: listOptions.search,
+			max_rows: listOptions.limit
+		}, (value) => recordsOf(value, "list_agents").map(agentOf)),
+		publish: (agentId, visibility) => call("publish_agent", {
+			id: agentId,
+			visibility
+		}, agentOf),
+		install: (organizationId, agentId, installed = true) => call("install_agent", {
+			tenant: organizationId,
+			agent_id: agentId,
+			installed
+		}, (value) => value === true),
+		rate: (agentId, rating, comment) => call("rate_agent", {
+			agent_id: agentId,
+			rating,
+			comment
+		}, agentOf),
+		setSkills: (agentId, skills) => call("set_agent_skills", {
+			agent_id: agentId,
+			skills: { items: skills }
+		}, Number),
+		remove: (agentId) => call("delete_agent", { id: agentId }, (value) => value === true)
+	};
+}
+//#endregion
+export { createAgents, rpcTransport, sqlTransport };

package/dist/blocks/ai-cache/index.d.ts

@@ -0,0 +1,3 @@
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { a as AiCacheSetOptions, i as AiCacheOptions, n as AiCacheEntry, o as cacheKey, r as AiCacheKind, s as createAiCache, t as AiCache } from "../../ai-cache-DaDu_G5L.js";
+export { type AiCache, type AiCacheEntry, type AiCacheKind, type AiCacheOptions, type AiCacheSetOptions, type BlockTransport, cacheKey, createAiCache, rpcTransport, sqlTransport };

package/dist/blocks/ai-cache/index.js

@@ -0,0 +1,3 @@
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { n as createAiCache, t as cacheKey } from "../../ai-cache-CBWs1W0k.js";
+export { cacheKey, createAiCache, rpcTransport, sqlTransport };

package/dist/blocks/ai-chat/index.d.ts

@@ -0,0 +1,31 @@
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { _ as isAiMessage, a as AiMessage, c as AiMessageRole, d as AiStepPart, f as AiTextPart, g as aiMessageSchema, h as AiToolResultPart, i as AiFilePart, l as AiReasoningPart, m as AiToolCallPart, n as AI_MESSAGE_SCHEMA_ID, o as AiMessagePart, p as AiToolApprovalPart, r as AiDataPart, s as AiMessagePartType, t as AI_MESSAGE_PART_TYPES, u as AiSourcePart } from "../../message-CfDoR0Y6.js";
+import { $ as AiRunStep, A as AiStoredMessageStatus, B as AiSandbox, C as AiProject, D as AiSaveResult, E as AiRunStatus, F as AiUserMessageTrigger, G as AiHarnessSession, H as AiSandboxStopper, I as SharedAiChat, J as AiHarnessStatus, K as AiHarnessSessionPatch, L as aiChatListTopic, M as AiToolApproval, N as AiToolApprovalRequest, O as AiShareLink, P as AiToolPolicy, Q as AiRunState, R as aiChatTopic, S as AiPendingInputRequest, T as AiRunRelease, U as AiSandboxes, V as AiSandboxStatus, W as NewAiSandbox, X as AiRun, Y as AiPendingApproval, Z as AiRunQuery, _ as AiModerationAction, a as AiChatInput, b as AiModerationStage, c as AiChatPatch, d as AiChatShare, et as AiRunStepInput, f as AiChatVisibility, g as AiModelInput, h as AiModel, i as AiChat, j as AiStreamClaim, k as AiStoredMessage, l as AiChatQuery, m as AiMessageSibling, n as AiApprovalDecision, nt as AiRuns, o as AiChatOptions, p as AiFeedback, q as AiHarnessSessions, r as AiAssistantMessageOptions, rt as createHarnessSessions, s as AiChatPage, t as AiAppendResult, tt as AiRunStepStatus, u as AiChatRecord, v as AiModerationEvent, w as AiProjectInput, x as AiPendingInput, y as AiModerationInput, z as createAiChat } from "../../ai-chat-7amvXjmQ.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/blocks/ai-chat/history.d.ts
+/** What `validateMessage` returns: the message, or the schema's issues. */
+type AiMessageCheck = {
+  readonly ok: true;
+  readonly message: AiMessage;
+} | {
+  readonly ok: false;
+  readonly issues: readonly StandardSchemaV1.Issue[];
+};
+/** Checks an untrusted value (a request body) against the canonical format. */
+export declare function validateMessage(value: unknown): AiMessageCheck;
+/** A stored message with the fields the tree adds to the canonical ones. */
+interface Stored extends AiMessage {
+  readonly parentId?: string | undefined;
+}
+/** The canonical messages of a path, in order, without the tree's fields. */
+export declare function pathToHistory(path: readonly Stored[]): AiMessage[];
+/** The output a `tool-result` gets when its call never finished. */
+export declare const INTERRUPTED_TOOL_OUTPUT = "The tool call was interrupted.";
+/**
+ * Closes every tool call that has no result yet, so a provider accepts the
+ * history after a crash or a stop mid-call: each gets a `tool-result` with
+ * `isError` right after it. A call waiting for approval is left alone.
+ */
+export declare function repairDanglingToolCalls(messages: readonly AiMessage[]): AiMessage[];
+//#endregion
+export { AI_MESSAGE_PART_TYPES, AI_MESSAGE_SCHEMA_ID, type AiAppendResult, type AiApprovalDecision, type AiAssistantMessageOptions, type AiChat, type AiChatInput, type AiChatOptions, type AiChatPage, type AiChatPatch, type AiChatQuery, type AiChatRecord, type AiChatShare, type AiChatVisibility, type AiDataPart, type AiFeedback, type AiFilePart, type AiHarnessSession, type AiHarnessSessionPatch, type AiHarnessSessions, type AiHarnessStatus, type AiMessage, type AiMessageCheck, type AiMessagePart, type AiMessagePartType, type AiMessageRole, type AiMessageSibling, type AiModel, type AiModelInput, type AiModerationAction, type AiModerationEvent, type AiModerationInput, type AiModerationStage, type AiPendingApproval, type AiPendingInput, type AiPendingInputRequest, type AiProject, type AiProjectInput, type AiReasoningPart, type AiRun, type AiRunQuery, type AiRunRelease, type AiRunState, type AiRunStatus, type AiRunStep, type AiRunStepInput, type AiRunStepStatus, type AiRuns, type AiSandbox, type AiSandboxStatus, type AiSandboxStopper, type AiSandboxes, type AiSaveResult, type AiShareLink, type AiSourcePart, type AiStepPart, type AiStoredMessage, type AiStoredMessageStatus, type AiStreamClaim, type AiTextPart, type AiToolApproval, type AiToolApprovalPart, type AiToolApprovalRequest, type AiToolCallPart, type AiToolPolicy, type AiToolResultPart, type AiUserMessageTrigger, type BlockTransport, type NewAiSandbox, type SharedAiChat, aiChatListTopic, aiChatTopic, aiMessageSchema, createAiChat, createHarnessSessions, isAiMessage, rpcTransport, sqlTransport };

package/dist/blocks/ai-chat/index.js

@@ -0,0 +1,5 @@
+import { n as rpcTransport, r as sqlTransport } from "../../block-transport-BLr-ZgLc.js";
+import { i as isAiMessage, n as AI_MESSAGE_SCHEMA_ID, r as aiMessageSchema, t as AI_MESSAGE_PART_TYPES } from "../../message-CaKlqdsX.js";
+import { i as createHarnessSessions, n as aiChatTopic, r as createAiChat, t as aiChatListTopic } from "../../ai-chat-B24UI962.js";
+import { i as validateMessage, n as pathToHistory, r as repairDanglingToolCalls, t as INTERRUPTED_TOOL_OUTPUT } from "../../history-BZih6SFP.js";
+export { AI_MESSAGE_PART_TYPES, AI_MESSAGE_SCHEMA_ID, INTERRUPTED_TOOL_OUTPUT, aiChatListTopic, aiChatTopic, aiMessageSchema, createAiChat, createHarnessSessions, isAiMessage, pathToHistory, repairDanglingToolCalls, rpcTransport, sqlTransport, validateMessage };

package/dist/blocks/ai-chat/react/index.d.ts

@@ -0,0 +1,77 @@
+import { b as DbError } from "../../../result-D7y2fT87.js";
+import { O as AiShareLink, a as AiChatInput, c as AiChatPatch, d as AiChatShare, h as AiModel, k as AiStoredMessage, l as AiChatQuery, u as AiChatRecord } from "../../../ai-chat-7amvXjmQ.js";
+import { x as SubscriptionStatus } from "../../../index-DunNRdnT.js";
+//#region src/blocks/ai-chat/react/index.d.ts
+interface ClientOptions {
+  /** The schema the calls go to: the module schema (default `better_supabase`), or the API schema from `sql.modules["ai-chat"].api`. */
+  readonly schema?: string;
+}
+export interface UseAiChatsOptions extends ClientOptions, Omit<AiChatQuery, "after" | "cursor"> {
+  /** The prefix of the list topic (`sql.modules["ai-chat"].options.listTopic`); `null` loads once. */
+  readonly topic?: string | null;
+}
+export interface AiChatsState {
+  /** `undefined` until the first load. */
+  readonly items: readonly AiChatRecord[] | undefined;
+  /** Whether `loadMore` has another page. */
+  readonly hasMore: boolean;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+  readonly loadMore: () => Promise<void>;
+  readonly refresh: () => Promise<void>;
+  readonly create: (input?: AiChatInput) => Promise<AiChatRecord | undefined>;
+  readonly update: (chatId: string, patch: AiChatPatch) => Promise<AiChatRecord | undefined>;
+  readonly remove: (chatId: string) => Promise<void>;
+}
+/**
+ * The signed-in user's chats in a tenant, newest first, loaded again when
+ * any of their chats changes.
+ *
+ * ```tsx
+ * const { items, loadMore, create } = useAiChats({ organizationId });
+ * ```
+ */
+export declare function useAiChats(options?: UseAiChatsOptions): AiChatsState;
+export interface UseAiChatTreeOptions extends ClientOptions {
+  /** The prefix of the chat topic (`sql.modules["ai-chat"].options.topic`); `null` loads once. */
+  readonly topic?: string | null;
+}
+export interface AiChatTreeState {
+  /** The active branch, root first; `undefined` until the first load. */
+  readonly path: readonly AiStoredMessage[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+  readonly refresh: () => Promise<void>;
+  /** Shows the branch through `messageId`. */
+  readonly switchBranch: (messageId: string) => Promise<void>;
+  /** Shows the sibling `offset` places from `messageId` (`-1` older, `1` newer). */
+  readonly step: (messageId: string, offset: number) => Promise<void>;
+}
+/**
+ * One chat's active branch, loaded again when a message is saved or the
+ * branch changes, in this tab or another.
+ *
+ * ```tsx
+ * const { path, step } = useAiChatTree(chatId);
+ * ```
+ */
+export declare function useAiChatTree(chatId: string | null | undefined, options?: UseAiChatTreeOptions): AiChatTreeState;
+export interface AiModelsState {
+  /** `undefined` until loaded. */
+  readonly models: readonly AiModel[] | undefined;
+  readonly error: DbError | undefined;
+  readonly refresh: () => Promise<void>;
+}
+/** The models the tenant's plans allow, for a model picker. */
+export declare function useAiModels(organizationId?: string | null, options?: ClientOptions): AiModelsState;
+export interface AiShareState {
+  /** The chat's share links, newest first; `undefined` until loaded. */
+  readonly shares: readonly AiChatShare[] | undefined;
+  readonly error: DbError | undefined;
+  /** Makes a link to the active branch, or to `leafId`; the token is in the result only. */
+  readonly create: (leafId?: string) => Promise<AiShareLink | undefined>;
+  readonly revoke: (shareId: string) => Promise<void>;
+}
+/** Share links for one chat the user owns. */
+export declare function useAiShare(chatId: string | null | undefined, options?: ClientOptions): AiShareState;
+//#endregion