better-supabase 0.5.1 → 0.6.0

package/dist/embeddings-C9KGQnXt.d.ts

@@ -0,0 +1,68 @@
+import { n as Embedder, o as KnowledgeHit, r as Knowledge, u as KnowledgeSearchOptions } from "./knowledge-BXBbT0Tr.js";
+import { EmbeddingModel, RerankingModel, SourceDocumentUIPart, Tool, embedMany } from "ai";
+//#region src/ai-sdk/embeddings/embeddings.d.ts
+type ProviderOptions = Parameters<typeof embedMany>[0]["providerOptions"];
+interface EmbedWithOptions {
+  /** Concurrent calls when the values need more than one. Default 4. */
+  readonly maxParallelCalls?: number;
+  readonly providerOptions?: ProviderOptions;
+  /** The name stored with each embedding; the provider and model id by default. */
+  readonly name?: string;
+}
+/** The name of an SDK model: the string itself, or `provider/modelId`. */
+declare function modelName(model: string | {
+  readonly provider: string;
+  readonly modelId: string;
+}): string;
+/** An `Embedder` for the knowledge and memory blocks over `embedMany`. */
+declare function embedWith(model: EmbeddingModel, options?: EmbedWithOptions): Embedder;
+type Reranker = (query: string, hits: readonly KnowledgeHit[], options?: {
+  readonly signal?: AbortSignal;
+}) => Promise<readonly KnowledgeHit[]>;
+/** Reorders search hits with a reranking model, keeping the best `topN`. */
+declare function rerankWith(model: RerankingModel, options?: {
+  readonly topN?: number;
+}): Reranker;
+interface SearchToolOptions extends Omit<KnowledgeSearchOptions, "signal"> {
+  readonly description?: string;
+  /** Reranks the hits before the model sees them. */
+  readonly rerank?: Reranker;
+  /** Called with the hits, to stream them as source parts. */
+  readonly onHits?: (hits: readonly KnowledgeHit[]) => void;
+}
+interface SearchToolResult {
+  readonly results: readonly {
+    readonly id: string;
+    readonly title: string;
+    readonly content: string;
+  }[];
+}
+/**
+ * A tool that searches the knowledge base as the caller. Each result id
+ * is `documentId#index`, the `sourceId` that `toSourceParts` gives it.
+ */
+declare function searchTool(knowledge: Knowledge, organizationId: string, options?: SearchToolOptions): Tool<{
+  query: string;
+}, SearchToolResult>;
+/** One `source-document` part per document among the hits, in hit order. */
+declare function toSourceParts(hits: readonly KnowledgeHit[]): SourceDocumentUIPart[];
+/** `Supabase.ai.Session` in Supabase Edge Functions, typed structurally. */
+interface SupabaseAiSession {
+  run(input: string, options: {
+    readonly mean_pool: boolean;
+    readonly normalize: boolean;
+  }): Promise<unknown>;
+}
+interface SupabaseEmbedOptions {
+  /** The built-in model. Default `gte-small` (384 dimensions). */
+  readonly model?: string;
+  /** A session to use instead of `new Supabase.ai.Session(model)`. */
+  readonly session?: SupabaseAiSession;
+}
+/**
+ * An `Embedder` over the model built into Supabase Edge Functions. Set the
+ * module's `dimensions` option to the model's size (384 for `gte-small`).
+ */
+declare function supabaseEmbed(options?: SupabaseEmbedOptions): Embedder;
+//#endregion
+export { SupabaseAiSession as a, modelName as c, supabaseEmbed as d, toSourceParts as f, SearchToolResult as i, rerankWith as l, Reranker as n, SupabaseEmbedOptions as o, SearchToolOptions as r, embedWith as s, EmbedWithOptions as t, searchTool as u };

package/dist/{refresh-CFPX0Qft.d.ts → ended-jLfvw8h-.d.ts}

@@ -1,4 +1,4 @@
-import { _ as StoredSession } from "./impersonation-BmePsuxz.js";
+import { c as StoredSession, n as CookieOptions } from "./session-ChiXDZdZ.js";
 //#region src/auth/refresh.d.ts
 interface RefreshOptions {
   readonly url: string;
@@ -39,4 +39,22 @@ type RefreshOutcome = {
  */
 declare function refreshSession(refreshToken: string, options: RefreshOptions): Promise<RefreshOutcome>;
 //#endregion
-export { RefreshOutcome as n, refreshSession as r, RefreshOptions as t };
+//#region src/auth/ended.d.ts
+type SessionStatus = "active" | "ended" | "unknown";
+interface SessionStatusOptions {
+  readonly url: string;
+  readonly publishableKey: string;
+  readonly cookieName?: string;
+  readonly fetch?: typeof fetch;
+  readonly timeoutMs?: number;
+  readonly now?: () => number;
+}
+interface ClearSessionCookiesOptions {
+  readonly url: string;
+  readonly cookieName?: string;
+  readonly cookie?: CookieOptions;
+}
+declare function sessionStatus(input: Request | string, options: SessionStatusOptions): Promise<SessionStatus>;
+declare function clearSessionCookies<R extends Response>(request: Request, response: R, options: ClearSessionCookiesOptions): R;
+//#endregion
+export { sessionStatus as a, refreshSession as c, clearSessionCookies as i, SessionStatus as n, RefreshOptions as o, SessionStatusOptions as r, RefreshOutcome as s, ClearSessionCookiesOptions as t };

package/dist/{entitlements-BiJZ4t49.d.ts → entitlements-DHrY2UDZ.d.ts}

@@ -1,8 +1,8 @@
-import { t as AuthSession } from "./view-CbgObAeb.js";
+import { t as AuthSession } from "./view-DbxLNu8L.js";
 //#region src/auth/entitlements.d.ts
 /**
- * One entry of the `memberships` claim, in PermDock's shape. PermDock strips
- * `null`s, so optional fields are absent rather than `null`.
+ * One entry of the `memberships` claim when a hook writes it as a list.
+ * Hooks strip `null`s, so optional fields are absent rather than `null`.
  */
 interface MembershipClaim {
   /** The scope the membership is in, e.g. `tenant` or `organization`. */
@@ -30,13 +30,22 @@ interface MembershipClaim {
 type EntitlementKey<C> = C extends {
   readonly features?: infer F;
 } ? NonNullable<F> extends Readonly<Record<string, readonly (infer K)[]>> ? K extends string ? K : string : string : string;
+/** Where `hasEntitlement` reads the features claim, and its short codes. */
+interface EntitlementClaimOptions {
+  /** `config.claims.features`, default `features`. */
+  readonly claim?: string;
+  /** `entitlements.claim.keys`: the short code written for each feature key. */
+  readonly keys?: Readonly<Record<string, string>>;
+}
 /**
  * Whether the session's plan-features claim grants `key` in `tenantId`.
  * `claim` is `config.claims.features` (default `features`), the claim
- * `better_supabase.feature_claims()` fills. The claim is as fresh as the
+ * `better_supabase.feature_claims()` fills, or `{ claim, keys }` when
+ * `entitlements.claim.keys` writes short codes. The claim is as fresh as the
  * token: enforce it in RLS with `better_supabase.has_entitlement()`, and
- * refresh the session after checkout.
+ * refresh the session after checkout. A tenant left out by
+ * `entitlements.claim.maxTenants` reads as not granted.
  */
-declare function hasEntitlement<C>(session: AuthSession<C>, tenantId: string, key: EntitlementKey<C>, claim?: string): boolean;
+declare function hasEntitlement<C>(session: AuthSession<C>, tenantId: string, key: EntitlementKey<C>, claim?: string | EntitlementClaimOptions): boolean;
 //#endregion
-export { MembershipClaim as n, hasEntitlement as r, EntitlementKey as t };
+export { hasEntitlement as i, EntitlementKey as n, MembershipClaim as r, EntitlementClaimOptions as t };

package/dist/entitlements-DRl6ZJUm.js

@@ -0,0 +1,24 @@
+import { t as AsyncResult } from "./result-DzUbqgdW.js";
+import { C as run } from "./block-helpers-DWHxHsEQ.js";
+//#region src/blocks/entitlements/entitlements.ts
+/** The Stripe event sent when a customer's active entitlements change. */
+const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
+function stripeCustomerOf(payload) {
+	if (typeof payload !== "object" || payload === null) return void 0;
+	const customer = (payload.data?.object)?.customer;
+	if (typeof customer === "string") return customer;
+	const id = customer?.id;
+	return typeof id === "string" ? id : void 0;
+}
+/**
+* Users whose `memberships` claim carries the entitlements of the Stripe
+* customer in an `entitlements.active_entitlement_summary.updated` event, so
+* a job can invalidate their sessions. Empty for other payloads.
+*/
+function entitlementMembers(sql, payload) {
+	const customer = stripeCustomerOf(payload);
+	if (customer === void 0) return AsyncResult.ok([]);
+	return run(() => sql.queryRaw("select user_id from better_supabase.entitlement_members($1) as user_id", [customer])).map((rows) => rows.map((row) => row.user_id));
+}
+//#endregion
+export { entitlementMembers as n, ENTITLEMENTS_UPDATED as t };

package/dist/envelope-DqnYGRw7.js

@@ -0,0 +1,47 @@
+import { o as tenantFrom, s as tenantPathsFor } from "./claims-PqzCxaTD.js";
+import { n as impersonatorClaim, r as impersonatorOf } from "./impersonation-DcqaTBHx.js";
+//#region src/blocks/jobs/envelope.ts
+/** Marks a payload that carries a job context; pgmq stores it as the payload. */
+const ENVELOPE = "$bs";
+/** Wraps a payload with the actor and tenant of `context`, when it has either. */
+function withContext(payload, context) {
+	if (!context) return payload;
+	const tenant = tenantFrom(context, tenantPathsFor(void 0));
+	const impersonator = context.claims ? impersonatorOf(context.claims) : void 0;
+	const recorded = {
+		...context.actor ? { actor: context.actor } : {},
+		...tenant === void 0 ? {} : { tenant },
+		...impersonator ? { act: impersonatorClaim(impersonator) } : {}
+	};
+	if (!recorded.actor && recorded.tenant === void 0) return payload;
+	return {
+		[ENVELOPE]: 1,
+		context: recorded,
+		payload
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isActor(value) {
+	return isRecord(value) && typeof value["id"] === "string" && (value["kind"] === "user" || value["kind"] === "service" || value["kind"] === "anon");
+}
+/** Splits a stored payload into the payload and its recorded context. */
+function unwrap(stored) {
+	if (!isRecord(stored) || stored[ENVELOPE] !== 1 || !Object.hasOwn(stored, "payload")) return {
+		payload: stored,
+		context: {}
+	};
+	const { actor, tenant, act } = isRecord(stored["context"]) ? stored["context"] : {};
+	const impersonator = act === void 0 ? void 0 : impersonatorOf({ act });
+	return {
+		payload: stored["payload"],
+		context: {
+			...isActor(actor) ? { actor } : {},
+			...typeof tenant === "string" && tenant.length > 0 ? { tenant } : {},
+			...impersonator ? { claims: { act: impersonatorClaim(impersonator) } } : {}
+		}
+	};
+}
+//#endregion
+export { withContext as n, unwrap as t };

package/dist/{errors-DtwXa6b8.js → errors-B11Duf73.js}

@@ -1,3 +1,4 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
 //#region src/core/errors.ts
 const STATUS = {
 	not_found: 404,
@@ -19,7 +20,10 @@ const STATUS = {
 	validation: 422,
 	multiple_rows: 409,
 	stale: 412,
+	max_affected: 400,
 	rate_limited: 429,
+	quota_exceeded: 429,
+	unsupported: 501,
 	unexpected: 500
 };
 function statusOf(kind) {
@@ -66,26 +70,48 @@ const isConflict = constraintGuard("conflict");
 const isCheck = constraintGuard("check");
 /** A foreign key violation, optionally for one constraint (`ForeignKeyConstraint`). */
 const isForeignKey = constraintGuard("foreign_key");
-/** Thrown by `.orThrow()`. Carries the plain `DbError` as `error`. */
-var DbException = class extends Error {
-	name = "DbException";
-	error;
-	constructor(error) {
-		super(error.message);
-		this.error = error;
-	}
-	get kind() {
-		return this.error.kind;
-	}
-};
 const CONSTRAINT_IN_MESSAGE = /constraint "([^"]+)"/;
 const KEY_COLUMNS_IN_DETAILS = /^Key \(([^)]+)\)=/;
 const COLUMN_IN_MESSAGE = /column "([^"]+)"/;
 const RETRY_AFTER = /retry after (\d+)/i;
 const PERMISSION_DENIED = /^permission denied for (table|view|sequence|function|schema) (\S+)/;
+/**
+* The SQL compiler fails a write past `maxAffected` by casting this text,
+* followed by `:<rows>`, to an integer: plain SQL has no `raise`.
+*/
+const MAX_AFFECTED_MARKER = "better_supabase:max_affected";
+const MAX_AFFECTED_COUNT = /better_supabase:max_affected:(\d+)/;
 function constraintOf(raw) {
 	return raw.constraint ?? CONSTRAINT_IN_MESSAGE.exec(raw.message ?? "")?.[1];
 }
+/** The hint `better_supabase.check_json_schema()` raises with (the `jsonb-schemas` module). */
+const JSON_SCHEMA_HINT = "JSON_SCHEMA_INVALID";
+/** The prefix of the `jsonb-schemas` check constraints and triggers. */
+const JSON_SCHEMA_CONSTRAINT = "bs_json_";
+const JSON_SCHEMA_COLUMN = /^[\w$]+\.([\w$]+) does not match its JSON Schema/;
+/**
+* One issue per pg_jsonschema error in DETAIL (a JSON array of strings), at
+* the column's database name. Without the list (the check constraint itself
+* failed), one issue for the whole value.
+*/
+function jsonSchemaIssues(raw) {
+	const column = raw.column ?? JSON_SCHEMA_COLUMN.exec(raw.message ?? "")?.[1];
+	const path = column === void 0 ? {} : { path: [column] };
+	let errors;
+	try {
+		errors = JSON.parse(raw.details ?? "");
+	} catch {
+		errors = void 0;
+	}
+	const messages = Array.isArray(errors) ? errors.filter((entry) => typeof entry === "string") : [];
+	return messages.length > 0 ? messages.map((message) => ({
+		message,
+		...path
+	})) : [{
+		message: "The value does not match its JSON Schema",
+		...path
+	}];
+}
 function columnsOf(raw) {
 	return KEY_COLUMNS_IN_DETAILS.exec(raw.details ?? "")?.[1]?.split(",").map((column) => column.trim());
 }
@@ -96,6 +122,13 @@ function optional(raw) {
 	if (raw.hint) out.hint = raw.hint;
 	return out;
 }
+/** Adds the operation's limit to a `max_affected` error that doesn't name it. */
+function withMaxAffected(error, maxAffected) {
+	return error.kind === "max_affected" && maxAffected !== void 0 && error.maxAffected === void 0 ? {
+		...error,
+		maxAffected
+	} : error;
+}
 /**
 * Maps a PostgREST or Postgres error to a `DbError`. Custom mappers run
 * first; the first one that returns an error wins.
@@ -138,6 +171,10 @@ function mapBuiltin(raw) {
 		}
 		case "23514": {
 			const constraint = constraintOf(raw);
+			if (base.hint === JSON_SCHEMA_HINT || constraint?.startsWith(JSON_SCHEMA_CONSTRAINT)) return dbError("validation", message, {
+				...base,
+				issues: jsonSchemaIssues(raw)
+			});
 			return dbError("check", message, {
 				...base,
 				...constraint ? { constraint } : {}
@@ -168,6 +205,7 @@ function mapBuiltin(raw) {
 			});
 		}
 		case "P0001": return dbError("raised", message, base);
+		case "P0002": return dbError("not_found", message, base);
 		case "57014": return dbError("timeout", message, base);
 		case "40001":
 		case "40P01": return dbError("serialization", message, base);
@@ -175,6 +213,13 @@ function mapBuiltin(raw) {
 		case "PGRST301":
 		case "PGRST302":
 		case "PGRST303": return dbError("unauthorized", message, base);
+		case "PGRST124": return dbError("max_affected", message, base);
+		case "22P02":
+			if (message.includes("better_supabase:max_affected")) {
+				const affected = MAX_AFFECTED_COUNT.exec(message)?.[1];
+				return dbError("max_affected", `The write affects ${affected ?? "more"} rows, more than maxAffected allows`, { code: "22P02" });
+			}
+			break;
 		case "PGRST123": return dbError("invalid_request", message, {
 			...base,
 			hint: base.hint ?? "PostgREST aggregates are off. Run `alter role authenticator set pgrst.db_aggregates_enabled = 'true'; notify pgrst, 'reload config';` (see BS210), or use better-supabase/postgres."
@@ -187,11 +232,35 @@ function mapBuiltin(raw) {
 				...seconds ? { retryAfter: Number(seconds) } : {}
 			});
 		}
+		case "BSQ29": return dbError("quota_exceeded", message, {
+			...base,
+			...quotaDetails(raw.details)
+		});
 	}
 	if (code.startsWith("22")) return dbError("invalid_input", message, base);
 	if (code.startsWith("PGRST1") || code.startsWith("PGRST2")) return dbError("invalid_request", message, base);
 	if (code.startsWith("08") || /fetch failed|network/i.test(message)) return dbError("network", message, base);
 	return dbError("unexpected", message, base);
 }
+/** `consume_quota` puts `{ meter, limit, retry_after }` in the error's DETAIL. */
+function quotaDetails(details) {
+	let parsed;
+	try {
+		parsed = JSON.parse(details ?? "");
+	} catch {
+		return {};
+	}
+	if (typeof parsed !== "object" || parsed === null) return {};
+	const record = parsed;
+	const field = (key) => record[key];
+	const meter = field("meter");
+	const limit = field("limit");
+	const retryAfter = field("retry_after");
+	return {
+		...typeof meter === "string" ? { meter } : {},
+		...typeof limit === "number" ? { limit } : {},
+		...typeof retryAfter === "number" ? { retryAfter } : {}
+	};
+}
 //#endregion
-export { isConflict as a, mapDbError as c, isCheck as i, statusOf as l, dbError as n, isDbError as o, dbErrorOf as r, isForeignKey as s, DbException as t };
+export { isConflict as a, mapDbError as c, isCheck as i, statusOf as l, dbError as n, isDbError as o, dbErrorOf as r, isForeignKey as s, MAX_AFFECTED_MARKER as t, withMaxAffected as u };

package/dist/errors-DLjJHPLK.js

@@ -0,0 +1,44 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError, o as isDbError } from "./errors-B11Duf73.js";
+import { s as toDbError } from "./result-DzUbqgdW.js";
+//#region src/storage/errors.ts
+/** Maps a Storage error (`StorageApiError`, fetch failures) to a `DbError`. */
+function fromStorageError(raw, table) {
+	if (isDbError(raw)) return raw;
+	if (raw instanceof DbException) return raw.error;
+	if (typeof raw !== "object" || raw === null) return toDbError(raw);
+	const failure = raw;
+	if (failure.name === "AbortError") return toDbError(raw);
+	const message = failure.message ?? "Storage request failed";
+	const code = failure.code ?? failure.statusCode;
+	const base = {
+		...code ? { code } : {},
+		...table ? { table } : {}
+	};
+	const statusCode = Number(failure.statusCode);
+	const status = Number.isFinite(statusCode) && statusCode >= 400 ? statusCode : failure.status ?? 0;
+	if (code === "FeatureNotEnabled" || /^Route \S+ not found$/.test(message)) return dbError("unsupported", message, base);
+	if (/row-level security|unauthorized to|AccessDenied/i.test(`${message} ${code ?? ""}`)) return dbError("forbidden", message, base);
+	if (/already exists|duplicate/i.test(`${message} ${code ?? ""}`)) return dbError("conflict", message, base);
+	if (failure.name === "StorageUnknownError" && status === 0) return dbError("network", message, base);
+	switch (status) {
+		case 400: return dbError("invalid_request", message, base);
+		case 401: return dbError("unauthorized", message, base);
+		case 403: return dbError("forbidden", message, base);
+		case 404: return dbError("not_found", message, base);
+		case 409: return dbError("conflict", message, base);
+		case 413:
+		case 415: return dbError("invalid_input", message, {
+			...base,
+			status
+		});
+		case 408:
+		case 429: return dbError("network", message, {
+			...base,
+			status
+		});
+		default: return status >= 500 ? dbError("network", message, base) : dbError("unexpected", message, base);
+	}
+}
+//#endregion
+export { fromStorageError as t };

package/dist/escape-like-DHfx6jRr.js

@@ -0,0 +1,7 @@
+//#region src/ir/escape-like.ts
+/** Escapes LIKE wildcards so user input matches literally. */
+function escapeLike(value) {
+	return value.replaceAll(/[\\%_]/g, (char) => `\\${char}`);
+}
+//#endregion
+export { escapeLike as t };

package/dist/escape-like-ImTK0ps_.d.ts

@@ -0,0 +1,15 @@
+import { b as DbError, x as DbErrorKind } from "./result-D7y2fT87.js";
+//#region src/core/db-exception.d.ts
+/** Thrown by `.orThrow()`. Carries the plain `DbError` as `error`. */
+declare class DbException extends Error {
+  override readonly name = "DbException";
+  readonly error: DbError;
+  constructor(error: DbError);
+  get kind(): DbErrorKind;
+}
+//#endregion
+//#region src/ir/escape-like.d.ts
+/** Escapes LIKE wildcards so user input matches literally. */
+declare function escapeLike(value: string): string;
+//#endregion
+export { DbException as n, escapeLike as t };

package/dist/eve/index.d.ts

@@ -0,0 +1,220 @@
+import { a as ResolveAuthOptions, r as AuthState } from "../resolve-KW8nCeL6.js";
+import { i as CredentialRef, r as CredentialProvider } from "../provider-BH5UWZJ6.js";
+import { i as AiChat } from "../ai-chat-7amvXjmQ.js";
+import { a as Inbox } from "../inbox-i7E1ppo6.js";
+import { a as EveMemoryToolsContext, c as MemoryDocumentConflictError, d as supabaseDocumentBackend, f as supabaseMemory, i as EveMemoryTool, l as SupabaseDocumentBackendOptions, m as EveSessionContext, n as EveMemoryContext, o as EveRecallMessage, p as EveSessionAuth, r as EveMemoryProvider, s as EveRecallResult, t as EveDocumentBackend, u as SupabaseMemoryOptions } from "../eve-gT2Fpjut.js";
+//#region src/eve/auth.d.ts
+/** Thrown by `supabaseAuth` so eve answers with `response` instead of downgrading to anonymous. */
+export declare class EveAuthRejection extends Error {
+  override readonly name = "EveAuthRejection";
+  readonly response: Response;
+  constructor(message: string, status?: number);
+}
+interface SupabaseAuthOptions extends Omit<ResolveAuthOptions, "refresh" | "leeway" | "refreshTimeoutMs"> {
+  /** The tenant claim, `config.claims.tenant`. Defaults to `tenant_id`. */
+  readonly tenantClaim?: string;
+  /** The memberships claim, `config.claims.memberships`. Defaults to `memberships`. */
+  readonly membershipsClaim?: string;
+  /** Extra attributes from the verified claims, merged over the defaults. */
+  readonly attributes?: (claims: Readonly<Record<string, unknown>>) => Readonly<Record<string, string | readonly string[]>>;
+}
+/** The eve principal for a verified Supabase user, or `null` for anyone else. */
+export declare function principalOf(auth: AuthState, options?: Pick<SupabaseAuthOptions, "tenantClaim" | "membershipsClaim" | "attributes">): EveSessionAuth | null;
+/**
+ * An eve route `AuthFn` that verifies the Supabase session locally (cookie or
+ * bearer) and maps the user to a principal. Requests without a session fall
+ * through to the next entry; an invalid token is rejected with 401.
+ */
+export declare function supabaseAuth(options: SupabaseAuthOptions): (request: Request) => Promise<EveSessionAuth | null>;
+//#endregion
+//#region src/eve/connections.d.ts
+/** eve's `ConnectionAuthorizationRequiredError`, matched by name. */
+export declare class ConnectionAuthorizationRequiredError extends Error {
+  override readonly name = "ConnectionAuthorizationRequiredError";
+  readonly connectionName: string;
+  constructor(connectionName: string, options?: {
+    readonly message?: string;
+  });
+}
+/** eve's `ConnectionAuthorizationFailedError`, matched by name. */
+export declare class ConnectionAuthorizationFailedError extends Error {
+  override readonly name = "ConnectionAuthorizationFailedError";
+  readonly connectionName: string;
+  readonly reason: string;
+  readonly retryable: boolean;
+  constructor(connectionName: string, options: {
+    readonly message?: string;
+    readonly reason: string;
+    readonly retryable: boolean;
+  });
+}
+/** The identity eve resolves for a connection callback. */
+type EveConnectionPrincipal = {
+  readonly type: "app";
+} | {
+  readonly type: "user";
+  readonly id: string;
+  readonly issuer?: string;
+  readonly attributes?: Readonly<Record<string, string | readonly string[]>>;
+};
+interface EveConnectionRequest {
+  readonly principal: EveConnectionPrincipal;
+  readonly connection: {
+    readonly url: string;
+  };
+}
+interface EveTokenResult {
+  readonly token: string;
+  /** Epoch milliseconds. */
+  readonly expiresAt?: number;
+  readonly providerSubject?: string;
+}
+interface EveAuthorizationChallenge {
+  readonly challenge: {
+    readonly url?: string;
+    readonly displayName?: string;
+    readonly instructions?: string;
+  };
+}
+/** A `getToken`-only connection `auth`: eve never runs a consent flow. */
+interface EveTokenAuthorization {
+  readonly credentialOwner: "app" | "user";
+  readonly displayName?: string;
+  getToken(request: EveConnectionRequest): Promise<EveTokenResult>;
+  readonly startAuthorization?: undefined;
+  readonly completeAuthorization?: undefined;
+}
+/** An interactive connection `auth`, which eve allows only for users. */
+interface EveInteractiveAuthorization {
+  readonly principalType: "user";
+  readonly displayName?: string;
+  getToken(request: EveConnectionRequest): Promise<EveTokenResult>;
+  startAuthorization(request: EveConnectionRequest & {
+    readonly callbackUrl: string;
+  }): Promise<EveAuthorizationChallenge>;
+  completeAuthorization(request: EveConnectionRequest & {
+    readonly callbackUrl: string;
+    readonly callback: {
+      readonly params: Readonly<Record<string, string>>;
+      readonly method: string;
+    };
+  }): Promise<EveTokenResult>;
+}
+/** A connection `auth` value for eve's `defineMcpClientConnection`. */
+type EveConnectionAuthorization = EveTokenAuthorization | EveInteractiveAuthorization;
+interface CredentialAuthOptions {
+  readonly provider: CredentialProvider;
+  readonly ref: CredentialRef;
+  /** `app` uses the app's credential; `user` the principal's own. */
+  readonly owner: "app" | "user";
+  /** The connection's name in errors. Defaults to the ref's provider. */
+  readonly connection?: string;
+  readonly scopes?: readonly string[];
+  /** For `user`: let eve send the user to connect the account when the provider can. Defaults to true. */
+  readonly interactive?: boolean;
+}
+/**
+ * An eve connection `authorization` over a better-supabase
+ * `CredentialProvider` (Vault, Vercel Connect or your own): tokens come from
+ * the provider for the app or for the session's user. A user without a stored
+ * credential gets eve's authorization flow when the provider supports one.
+ */
+export declare function credentialAuth(options: CredentialAuthOptions): EveConnectionAuthorization;
+//#endregion
+//#region src/eve/ids.d.ts
+/** A UUID (version 8) from the SHA-256 of `input`, so the same input always gets the same id. */
+export declare function stableUuid(input: string): Promise<string>;
+//#endregion
+//#region src/eve/inbox.d.ts
+/** The parts of a Chat SDK thread `routeInbox` reads. */
+interface EveChatThread {
+  readonly id: string;
+  subscribe(): Promise<void>;
+}
+/** The parts of a Chat SDK message `routeInbox` reads. */
+interface EveChatMessage {
+  readonly text: string;
+}
+/**
+ * The parts of eve's `chatSdkChannel()` result `routeInbox` uses. `T` is the
+ * Chat SDK thread, so `send` gets back the thread the handler received.
+ */
+interface EveChatSdkBridge<T extends EveChatThread = EveChatThread> {
+  readonly bot: {
+    onNewMention(handler: (thread: T, message: EveChatMessage) => Promise<void>): void;
+    onSubscribedMessage(handler: (thread: T, message: EveChatMessage) => Promise<void>): void;
+  };
+  send(message: string, options: {
+    readonly thread: NoInfer<T>;
+    readonly auth: EveSessionAuth | null;
+    readonly title?: string;
+  }): Promise<unknown>;
+}
+interface RouteInboxOptions {
+  /** `createInbox` on a service transport. */
+  readonly inbox: Inbox;
+  /** The session title for a new conversation. Defaults to the conversation's subject. */
+  readonly title?: string;
+}
+/**
+ * Hands inbox conversations to eve through a `chatSdkChannel` built over
+ * `inboxAdapter`. A message reaches eve only while the conversation's
+ * `bot_mode` is `bot`, so an agent's handoff pauses the bot. The turn's
+ * principal is the contact, never a user, so contacts get no user-scoped
+ * connections.
+ */
+export declare function routeInbox<T extends EveChatThread>(bridge: EveChatSdkBridge<T>, options: RouteInboxOptions): void;
+//#endregion
+//#region src/eve/sessions.d.ts
+interface EveEvent<T> {
+  readonly type?: string;
+  readonly data: T;
+  readonly meta?: {
+    readonly id?: string;
+    readonly at?: string;
+  };
+}
+interface TurnData {
+  readonly turnId: string;
+  readonly sequence: number;
+}
+/** Hook handlers for eve's `defineHook({ events })`. */
+interface EveSessionHooks {
+  "session.started"(event: EveEvent<unknown>, ctx: EveSessionContext): Promise<void>;
+  "turn.started"(event: EveEvent<TurnData>, ctx: EveSessionContext): Promise<void>;
+  "message.received"(event: EveEvent<TurnData & {
+    readonly message: string;
+  }>, ctx: EveSessionContext): Promise<void>;
+  "message.completed"(event: EveEvent<TurnData & {
+    readonly message: string;
+    readonly stepIndex: number;
+    readonly finishReason: string;
+  }>, ctx: EveSessionContext): Promise<void>;
+  "turn.completed"(event: EveEvent<TurnData>, ctx: EveSessionContext): Promise<void>;
+  "turn.failed"(event: EveEvent<TurnData & {
+    readonly code: string;
+    readonly message: string;
+  }>, ctx: EveSessionContext): Promise<void>;
+  "turn.cancelled"(event: EveEvent<TurnData>, ctx: EveSessionContext): Promise<void>;
+}
+interface PersistSessionsOptions {
+  /** `createAiChat` on a service transport. */
+  readonly chats: AiChat;
+  /** The tenant of a principal. Defaults to `attributes.tenantId`. */
+  readonly organizationOf?: (auth: EveSessionAuth) => string | undefined;
+  readonly agentId?: string;
+  /** The title of a new chat. Defaults to `eve session`. */
+  readonly title?: string;
+}
+/** The `ai_chats` id of an eve session: the same session always maps to the same chat. */
+export declare function chatIdOf(sessionId: string): Promise<string>;
+/**
+ * Hook handlers that copy an eve session into the canonical chat tables, so
+ * the chat UI, search, memory recall and analytics read eve sessions like any
+ * other chat. Every write is keyed by the event, so eve's at-least-once
+ * delivery stores each message once. Sessions without a signed-in user and
+ * tenant are skipped.
+ */
+export declare function persistSessions(options: PersistSessionsOptions): EveSessionHooks;
+//#endregion
+export { type CredentialAuthOptions, type EveAuthorizationChallenge, type EveChatMessage, type EveChatSdkBridge, type EveChatThread, type EveConnectionAuthorization, type EveConnectionPrincipal, type EveConnectionRequest, type EveDocumentBackend, type EveInteractiveAuthorization, type EveMemoryContext, type EveMemoryProvider, type EveMemoryTool, type EveMemoryToolsContext, type EveRecallMessage, type EveRecallResult, type EveSessionAuth, type EveSessionContext, type EveSessionHooks, type EveTokenAuthorization, type EveTokenResult, MemoryDocumentConflictError, type PersistSessionsOptions, type RouteInboxOptions, type SupabaseAuthOptions, type SupabaseDocumentBackendOptions, type SupabaseMemoryOptions, supabaseDocumentBackend, supabaseMemory };