better-supabase 0.5.0 → 0.6.0

package/dist/ai-tasks-Cd1HMFvB.d.ts

@@ -0,0 +1,131 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { m as JobHandler } from "./queue-CLJurhdy.js";
+import { r as RunState } from "./run-state-CPo-1X2B.js";
+//#region src/blocks/ai-tasks/ai-tasks.d.ts
+/** A task run's state, in the words ai-chat and workflow runs share. */
+type AiTaskRunStatus = Extract<RunState, "queued" | "running" | "completed" | "failed">;
+interface AiTaskRun {
+  readonly id: string;
+  readonly taskId: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  readonly status: AiTaskRunStatus;
+  readonly scheduledFor: Temporal.Instant;
+  readonly chatId: string | undefined;
+  readonly error: string | undefined;
+  readonly startedAt: Temporal.Instant | undefined;
+  readonly finishedAt: Temporal.Instant | undefined;
+  readonly createdAt: Temporal.Instant;
+}
+interface AiTask {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly userId: string;
+  /** The chat each run writes to; the first run's chat when unset. */
+  readonly chatId: string | undefined;
+  readonly agentId: string | undefined;
+  readonly title: string;
+  readonly prompt: string;
+  /** Five-field cron or an interval such as `30 minutes`. */
+  readonly cron: string;
+  /** An IANA time zone the cron runs in. */
+  readonly timezone: string;
+  readonly enabled: boolean;
+  readonly nextRunAt: Temporal.Instant | undefined;
+  readonly lastRunAt: Temporal.Instant | undefined;
+  /** Only `list` sets it. */
+  readonly lastRun: AiTaskRun | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface AiTaskFields {
+  readonly title?: string;
+  readonly prompt?: string;
+  readonly cron?: string;
+  readonly timezone?: string;
+  readonly chatId?: string | null;
+  readonly agentId?: string | null;
+}
+type NewAiTask = AiTaskFields & {
+  readonly title: string;
+  readonly prompt: string;
+  readonly cron: string;
+};
+/**
+ * Runs one occurrence of a task, as the task's user: sends the prompt to the
+ * assistant and returns the chat it wrote to. A throw fails the run.
+ */
+type AiTaskRunner = ((task: AiTask, run: AiTaskRun, signal: AbortSignal) => Promise<{
+  readonly chatId?: string;
+} | void>) & {
+  /** The runner contract version. Omitted means 1. */
+  readonly apiVersion?: 1;
+};
+interface AiTaskOutcome {
+  readonly task: AiTask;
+  readonly run: AiTaskRun;
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly chatId?: string;
+}
+interface AiTasksOptions extends BlockTemporalOptions {
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** Calls as the service role, for `tick`, `execute` and `runJob`. */
+  readonly service?: BlockTransport;
+  /** The module schema (`sql.modules.ai-tasks.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  readonly run?: AiTaskRunner;
+  /** Called after each run finishes, to notify the task's user. */
+  readonly notify?: (outcome: AiTaskOutcome) => unknown;
+  /** The clock, for tests. */
+  readonly now?: () => Temporal.Instant;
+}
+interface AiTasks {
+  create(organizationId: string, task: NewAiTask): AsyncResult<AiTask>;
+  update(organizationId: string, taskId: string, fields: AiTaskFields): AsyncResult<AiTask>;
+  pause(organizationId: string, taskId: string): AsyncResult<AiTask>;
+  /** Enables a task again; it runs at its next occurrence. */
+  resume(organizationId: string, taskId: string): AsyncResult<AiTask>;
+  remove(taskId: string): AsyncResult<boolean>;
+  /** The caller's tasks, or every task in the tenant with `all` and `ai.admin`. */
+  list(organizationId: string, options?: {
+    readonly all?: boolean;
+  }): AsyncResult<readonly AiTask[]>;
+  runs(taskId: string, options?: {
+    readonly limit?: number;
+  }): AsyncResult<readonly AiTaskRun[]>;
+  /**
+   * Claims due tasks (service role): queues a run for each, which the
+   * `ai_task_run` queue picks up when jobs is installed, and computes the
+   * next occurrence of every task that needs one. Returns the queued runs.
+   */
+  tick(options?: {
+    readonly batch?: number;
+  }): AsyncResult<readonly AiTaskRun[]>;
+  /** Starts, runs and finishes a queued run (service role). `false` when another worker has it. */
+  execute(runId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<boolean>;
+  /** The handler for the `ai_task_run` queue. */
+  runJob(): JobHandler<{
+    readonly run_id: string;
+  }>;
+  /**
+   * `tick` then `execute` each run in turn, without a queue. Returns how many
+   * ran. A failed run does not stop the others; when any failed, the result
+   * is the first error, with every failed run listed in `details`.
+   */
+  drain(options?: {
+    readonly batch?: number;
+    readonly signal?: AbortSignal;
+  }): AsyncResult<number>;
+}
+/** Prompts users schedule on a cron, and the scheduler that runs them. */
+declare function createAiTasks(options: AiTasksOptions): AiTasks;
+//#endregion
+export { AiTaskRunStatus as a, AiTasksOptions as c, AiTaskRun as i, NewAiTask as l, AiTaskFields as n, AiTaskRunner as o, AiTaskOutcome as r, AiTasks as s, AiTask as t, createAiTasks as u };

package/dist/announcements-CiyOs-xP.js

@@ -0,0 +1,107 @@
+import { D as stringsOf, O as textOf, h as optionalText, i as blockCall, k as toInstant, m as optionalInstant, n as applyTemporal, u as instantArg, x as recordsOf, y as recordOf } from "./block-helpers-DWHxHsEQ.js";
+//#region src/blocks/announcements/announcements.ts
+const SEVERITIES = /* @__PURE__ */ new Set([
+	"info",
+	"success",
+	"warning",
+	"critical"
+]);
+function severityOf(value) {
+	const text = textOf(value);
+	return SEVERITIES.has(text) ? text : "info";
+}
+function announcementOf(value) {
+	const row = recordOf(value, "announcements");
+	return {
+		id: textOf(row["id"]),
+		title: textOf(row["title"]),
+		body: textOf(row["body"] ?? ""),
+		severity: severityOf(row["severity"]),
+		href: optionalText(row["href"]),
+		startsAt: toInstant(textOf(row["starts_at"])),
+		endsAt: optionalInstant(row["ends_at"]),
+		dismissible: row["dismissible"] !== false,
+		createdAt: toInstant(textOf(row["created_at"])),
+		updatedAt: toInstant(textOf(row["updated_at"]))
+	};
+}
+function audienceOf(type, targets) {
+	const values = stringsOf(targets);
+	switch (type) {
+		case "tenant": return {
+			type,
+			organizationIds: values
+		};
+		case "role": return {
+			type,
+			roles: values
+		};
+		case "plan": return {
+			type,
+			plans: values
+		};
+		default: return { type: "all" };
+	}
+}
+function managedOf(value) {
+	const row = recordOf(value, "announcements");
+	return {
+		...announcementOf(row),
+		audience: audienceOf(row["audience"], row["targets"]),
+		createdBy: optionalText(row["created_by"])
+	};
+}
+function audienceFields(audience) {
+	switch (audience.type) {
+		case "all": return {
+			audience: "all",
+			targets: []
+		};
+		case "tenant": return {
+			audience: "tenant",
+			targets: audience.organizationIds
+		};
+		case "role": return {
+			audience: "role",
+			targets: audience.roles
+		};
+		case "plan": return {
+			audience: "plan",
+			targets: audience.plans
+		};
+		default: throw new TypeError(`Unknown audience ${JSON.stringify(audience)}`);
+	}
+}
+/** The columns `save_announcement` sets, from the fields the input names. */
+function fieldsOf(input) {
+	const fields = {};
+	if (input.title !== void 0) fields["title"] = input.title;
+	if (input.body !== void 0) fields["body"] = input.body;
+	if (input.severity !== void 0) fields["severity"] = input.severity;
+	if (input.href !== void 0) fields["href"] = input.href;
+	if (input.audience !== void 0) Object.assign(fields, audienceFields(input.audience));
+	if (input.startsAt !== void 0) fields["starts_at"] = instantArg(input.startsAt);
+	if (input.endsAt !== void 0) fields["ends_at"] = instantArg(input.endsAt);
+	if (input.dismissible !== void 0) fields["dismissible"] = input.dismissible;
+	return fields;
+}
+function createAnnouncements(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return {
+		listActive: (organizationId) => call("active_announcements", { tenant: organizationId ?? null }, (value) => recordsOf(value, "active_announcements").map(announcementOf)),
+		dismiss: (announcementId) => call("dismiss_announcement", { id: announcementId }, (value) => value === true),
+		list: () => call("list_announcements", {}, (value) => recordsOf(value, "list_announcements").map(managedOf)),
+		publish: (input) => call("save_announcement", {
+			id: null,
+			fields: fieldsOf(input)
+		}, managedOf),
+		update: (announcementId, input) => call("save_announcement", {
+			id: announcementId,
+			fields: fieldsOf(input)
+		}, managedOf),
+		remove: (announcementId) => call("delete_announcement", { id: announcementId }, (value) => value === true)
+	};
+}
+//#endregion
+export { createAnnouncements as t };

package/dist/announcements-ZRGnScWI.d.ts

@@ -0,0 +1,72 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.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 extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema (`sql.modules.announcements.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface Announcements {
+  /** The caller's live, undismissed announcements; pass the active tenant for tenant, role and plan audiences. */
+  listActive(organizationId?: string | null): AsyncResult<readonly Announcement[]>;
+  /** 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[]>;
+  publish(input: AnnouncementInput): AsyncResult<ManagedAnnouncement>;
+  update(announcementId: string, input: Partial<AnnouncementInput>): AsyncResult<ManagedAnnouncement>;
+  remove(announcementId: string): AsyncResult<boolean>;
+}
+declare function createAnnouncements(options: AnnouncementsOptions): Announcements;
+//#endregion
+export { Announcements as a, createAnnouncements as c, AnnouncementSeverity as i, AnnouncementAudience as n, AnnouncementsOptions as o, AnnouncementInput as r, ManagedAnnouncement as s, Announcement as t };

package/dist/api-keys-rCGtKaZA.d.ts

@@ -0,0 +1,156 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { n as AuthResolver } from "./resolve-KW8nCeL6.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+import { JWTClaims } from "@supabase/server";
+//#region src/blocks/api-keys/api-keys.d.ts
+type ApiKeyState = "active" | "grace" | "revoked" | "expired";
+interface ApiKey {
+  readonly id: string;
+  /** Set for a tenant key, and for a personal key limited to one tenant. */
+  readonly organizationId?: string;
+  /** Set for a personal key: it acts as this user. */
+  readonly userId?: string;
+  readonly name: string;
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly scopes: readonly string[];
+  /** Requests per minute, when the key has a limit. */
+  readonly rateLimit?: number;
+  readonly expiresAt?: Temporal.Instant;
+  readonly lastUsedAt?: Temporal.Instant;
+  /** In the future while a rotated key's grace period runs. */
+  readonly revokedAt?: Temporal.Instant;
+  readonly rotatedFrom?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly state: ApiKeyState;
+  readonly successorId?: string;
+}
+/** A new key. `token` is shown once: only its hash is stored. */
+interface CreatedApiKey {
+  readonly key: ApiKey;
+  readonly token: string;
+}
+interface CreateApiKeyInput {
+  readonly name: string;
+  /** The tenant the key acts in. Required unless `personal`. */
+  readonly organizationId?: string;
+  /** Acts as the signed-in user (in `organizationId` only, when set). */
+  readonly personal?: boolean;
+  /** `*` grants every scope. */
+  readonly scopes?: readonly string[];
+  readonly expiresAt?: Temporal.Instant;
+  /** Requests per minute. */
+  readonly rateLimit?: number;
+}
+type ApiKeyCheck = {
+  readonly status: "ok";
+  readonly key: ApiKey;
+} | {
+  readonly status: "invalid";
+} | {
+  readonly status: "rate_limited";
+  readonly retryAfter: number;
+};
+interface ApiKeys {
+  create(input: CreateApiKeyInput): AsyncResult<CreatedApiKey>;
+  /** A tenant's keys for its managers (the caller's own otherwise), or the caller's personal keys. */
+  list(organizationId?: string): AsyncResult<readonly ApiKey[]>;
+  revoke(id: string): AsyncResult<boolean>;
+  /** A new token for the key; the old one keeps working for `grace` (one day by default). */
+  rotate(id: string, options?: {
+    readonly grace?: Temporal.Duration;
+  }): AsyncResult<CreatedApiKey>;
+  /** Checks a presented token and counts the request. Needs a service transport. */
+  verify(token: string): AsyncResult<ApiKeyCheck>;
+}
+interface ApiKeysOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /** The token's first segment, lowercase letters and digits. Defaults to `bs`. */
+  readonly prefix?: string;
+}
+interface ParsedApiKey {
+  readonly prefix: string;
+  readonly publicId: string;
+  readonly secret: string;
+  /** Whether the token ends in a checksum; keys created before it have none. */
+  readonly checksum: boolean;
+}
+/**
+ * The CRC-32 (IEEE 802.3) of `text` as 6 base62 characters: the checksum
+ * GitHub-style tokens end in, so a secret
+ * scanner or the server rejects a mistyped key without a lookup.
+ */
+declare function apiKeyChecksum(text: string): string;
+/**
+ * Splits `<prefix>_<public id>_<secret><checksum>`: a 43-character base62
+ * secret and the 6-character checksum of everything before it. A key from
+ * before the checksum (`<prefix>_<public id>_<secret>`) still parses. A
+ * checksum that doesn't match, or anything else (a JWT, say), is
+ * `undefined`.
+ */
+declare function parseApiKey(token: string): ParsedApiKey | undefined;
+/**
+ * API keys over the `api-keys` SQL module. Members create and rotate keys
+ * with their own transport; `verify` (and `apiKeyResolver`) need one that
+ * runs as the service role.
+ */
+declare function createApiKeys(options: ApiKeysOptions): ApiKeys;
+/**
+ * A second claim for an authorization provider's SQL functions, with the
+ * field names they read. Every field but `name` is optional.
+ */
+interface ApiKeyExtraClaim {
+  /** The claim. `api_key` adds the fields to the module's own claim. */
+  readonly name: string;
+  /** The field with the permission keys, default `scopes`. */
+  readonly scopes?: string;
+  /** The field with a tenant key's tenant, default `tenant`. */
+  readonly tenant?: string;
+  /** The field with a tenant key's roles, default `roles`. */
+  readonly roles?: string;
+  /** The roles a tenant key holds in its tenant, unless `serviceRoles` in the options answers. */
+  readonly serviceRoles?: readonly string[];
+}
+interface ApiKeyClaimsOptions {
+  /**
+   * Also write the claim an authorization provider's SQL functions read:
+   * the scopes as a ceiling, and a tenant key's tenant and roles.
+   */
+  readonly claim?: ApiKeyExtraClaim;
+  /** The roles a tenant key holds in its tenant; default `claim.serviceRoles`. */
+  readonly serviceRoles?: (key: ApiKey) => readonly string[];
+  /**
+   * The permission keys `*` stands for in `claim`, which has no wildcard,
+   * so without this a key with `*` allows nothing there.
+   */
+  readonly allPermissions?: readonly string[];
+  /**
+   * The claim that narrows a provider's functions to one tenant (such as
+   * `tenant_id`), set for a personal key limited to a tenant.
+   */
+  readonly tenantClaim?: string;
+}
+interface ApiKeyResolverOptions extends ApiKeyClaimsOptions {
+  /** `createApiKeys` over a service transport. */
+  readonly keys: Pick<ApiKeys, "verify">;
+  /** The header that carries the key besides `Authorization: Bearer`. Defaults to `x-api-key`. */
+  readonly header?: string;
+}
+/**
+ * The claims queries run with for a key: `api_key` with `id`, `name`,
+ * `scopes` and `organization_id` for the module's `has_scope()` and
+ * `api_key_tenant()`, plus `options.claim`.
+ */
+declare function apiKeyClaims(key: ApiKey, options?: ApiKeyClaimsOptions): JWTClaims;
+/**
+ * Resolves `x-api-key` (or a Bearer token shaped like a key) to an `apiKey`
+ * auth state. Requests without one fall through to the JWT and cookie
+ * resolution. Pass it to `createServer({ auth: { resolvers: [...] } })`.
+ */
+declare function apiKeyResolver(options: ApiKeyResolverOptions): AuthResolver;
+//#endregion
+export { ApiKeyResolverOptions as a, ApiKeysOptions as c, ParsedApiKey as d, apiKeyChecksum as f, parseApiKey as g, createApiKeys as h, ApiKeyExtraClaim as i, CreateApiKeyInput as l, apiKeyResolver as m, ApiKeyCheck as n, ApiKeyState as o, apiKeyClaims as p, ApiKeyClaimsOptions as r, ApiKeys as s, ApiKey as t, CreatedApiKey as u };

package/dist/assistant-DwdpDH1q.d.ts

@@ -0,0 +1,147 @@
+import { b as DbError } from "./result-D7y2fT87.js";
+import { a as AiMessage } from "./message-CfDoR0Y6.js";
+import { E as AiRunStatus, F as AiUserMessageTrigger, _ as AiModerationAction, i as AiChat, u as AiChatRecord } from "./ai-chat-7amvXjmQ.js";
+import { o as StreamStore } from "./store-CGjgWu5n.js";
+import { c as GatewayOptions, i as CostBackfillPayload, t as AiUsage } from "./gateway-C1ssRHnf.js";
+import { LanguageModelUsage, ModelMessage, UIMessage, UIMessageChunk, UIMessageStreamOnEndCallback } from "ai";
+//#region src/ai-sdk/chat/assistant.d.ts
+/** Who asks, for one request. */
+interface AssistantContext {
+  /**
+   * The chat block for this request: the user's transport, and a service
+   * transport (`service`) for the writes only the server makes.
+   */
+  readonly chats: AiChat;
+  readonly userId: string;
+  readonly organizationId: string;
+  /**
+   * Keeps the function alive until the answer is stored, after the response
+   * is sent: `after` in Next.js, `ctx.waitUntil` on Workers and Vercel.
+   */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+}
+/** What `run` gets to generate one answer. */
+interface AssistantRunArgs {
+  readonly chat: AiChatRecord;
+  /** The model the request may use, after the catalog check. */
+  readonly model: string;
+  readonly messages: ModelMessage[];
+  /** The history the model sees, as UI messages. */
+  readonly uiMessages: UIMessage[];
+  /** Aborted by `stop()`; pass it to `streamText` or `agent.stream`. */
+  readonly abortSignal: AbortSignal;
+  /** Spend attribution for the AI Gateway (`gatewayOptions`). */
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+  readonly context: AssistantContext;
+}
+/** The part of a `streamText` or `agent.stream` result the assistant reads. */
+interface AssistantRunResult {
+  toUIMessageStream(options: {
+    originalMessages: UIMessage[];
+    generateMessageId: () => string;
+    onEnd: UIMessageStreamOnEndCallback<UIMessage>;
+    onError?: (error: unknown) => string;
+  }): ReadableStream<UIMessageChunk>;
+  readonly totalUsage?: PromiseLike<LanguageModelUsage>;
+  readonly providerMetadata?: PromiseLike<unknown>;
+}
+/** The verdict of a moderation hook. */
+interface AssistantModeration {
+  readonly action: AiModerationAction;
+  readonly category: string;
+  readonly score?: number;
+}
+/** What `onFinish` gets once the answer is stored. */
+interface AssistantFinish {
+  readonly chat: AiChatRecord;
+  readonly message: UIMessage;
+  readonly status: AiRunStatus;
+  readonly model: string;
+  readonly usage: AiUsage | undefined;
+  readonly context: AssistantContext;
+}
+interface AssistantOptions {
+  /** Where the answer's stream is kept, so a reload resumes it. */
+  readonly streams: StreamStore;
+  /** Starts the generation: `agent.stream(...)` or `streamText(...)`. */
+  readonly run: (args: AssistantRunArgs) => AssistantRunResult | PromiseLike<AssistantRunResult>;
+  /** The model when neither the request nor the chat names an allowed one. */
+  readonly defaultModel: string;
+  /**
+   * The quota check before a generation (`usageQuota(usage, meter)`); an
+   * error answers 429.
+   */
+  readonly quota?: (organizationId: string) => Promise<DbError | undefined>;
+  /** Checks the user's message; `block` answers 403, others are recorded. */
+  readonly moderate?: (input: {
+    readonly message: AiMessage;
+    readonly chat: AiChatRecord;
+  }) => Promise<AssistantModeration | undefined>;
+  /** Called with the cost backfill payload when the gateway hasn't reported a cost yet. */
+  readonly enqueueCostBackfill?: (payload: CostBackfillPayload) => Promise<unknown>;
+  /** Called after the answer is stored, such as to record usage. */
+  readonly onFinish?: (finish: AssistantFinish) => void | Promise<void>;
+  /** What the stream is kept for: seconds or a Postgres interval. Defaults to one day. */
+  readonly streamTtl?: number | string;
+  /** The `feature` tag of the gateway options. Defaults to `chat`. */
+  readonly feature?: string;
+  /** Turns a stream error into the message the client sees. */
+  readonly onError?: (error: unknown) => string;
+  /** Makes message and stream ids. Defaults to `crypto.randomUUID()`. */
+  readonly generateId?: () => string;
+}
+/** The body `useAssistant` sends. */
+interface AssistantRequestBody {
+  /** The chat id; the client may make it, and the chat is created on first use. */
+  readonly id: string;
+  readonly message: UIMessage;
+  readonly trigger?: AiUserMessageTrigger;
+  /** For `regenerate-message`, the answer to write again. */
+  readonly messageId?: string;
+  readonly model?: string;
+}
+/** A checked and stored user turn, ready for a model: what `prepare` returns. */
+interface AssistantTurn {
+  readonly chat: AiChatRecord;
+  /** The model the request may use, after the catalog check. */
+  readonly model: string;
+  /** The stored user message, which the answer is saved under. */
+  readonly parentId: string;
+  /** The history the model sees, as UI messages. */
+  readonly uiMessages: UIMessage[];
+  readonly messages: ModelMessage[];
+  /** Spend attribution for the AI Gateway (`gatewayOptions`). */
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+}
+interface Assistant {
+  /** Stores the user's message, starts the answer and streams it (SSE). */
+  respond(request: Request, context: AssistantContext): Promise<Response>;
+  /**
+   * The checks and writes before a generation, without one: parses the
+   * body `useAssistant` sends, creates the chat on first use, picks the
+   * model, moderates, checks the quota, stores the user's message and loads
+   * the history. Returns a problem response when one of them fails.
+   */
+  prepare(body: unknown, context: AssistantContext): Promise<AssistantTurn | Response>;
+  /** The running answer of `chatId` from the start, or 204 when none runs. */
+  resume(chatId: string, context: AssistantContext, options?: {
+    readonly fromIdx?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<Response>;
+  /** Asks the running answer to stop: 204 whether or not one runs, a problem when the user may not. */
+  stop(chatId: string, context: AssistantContext): Promise<Response>;
+}
+/**
+ * A chat route for the AI SDK on the `ai-chat` block: `respond` stores the
+ * user's message, picks an allowed model, checks the quota, claims the
+ * chat's answer, runs the model and streams it while keeping a copy in the
+ * stream store; the answer and its usage are stored when it ends, even
+ * after the client left. `resume` replays it after a reload, `stop` ends it.
+ */
+declare function createAssistant(options: AssistantOptions): Assistant;
+//#endregion
+export { AssistantOptions as a, AssistantRunResult as c, AssistantModeration as i, AssistantTurn as l, AssistantContext as n, AssistantRequestBody as o, AssistantFinish as r, AssistantRunArgs as s, Assistant as t, createAssistant as u };