better-supabase 0.7.1 → 0.9.0

package/dist/authorization-hooks-DkmrnDX7.d.ts

@@ -0,0 +1,214 @@
+import { m as RequestContext } from "./plugin-CDLJRFFg.js";
+import { r as AuthState } from "./resolve-w9EpHzuM.js";
+//#region src/core/contracts/authorization-hooks.d.ts
+/**
+ * An email address or chat user, as a bot or a mail webhook sees it. The
+ * value is what the platform reports; it names no one until an identity
+ * link maps it to a user or a contact.
+ */
+interface IdentityRef {
+  readonly kind: "email" | "chat";
+  /** `slack`, `teams`, `whatsapp`, an email provider; unset for a plain address. */
+  readonly provider?: string;
+  /** The address (lower case) or the platform's user id. */
+  readonly value: string;
+  /** The platform workspace, such as a Slack team id. */
+  readonly workspace?: string;
+}
+/** Where an identity link points: an app user or a contact the app stores. */
+type IdentityTarget = {
+  readonly kind: "user";
+  readonly userId: string;
+} | {
+  readonly kind: "contact";
+  readonly contactId: string;
+};
+/**
+ * Looks up the verified link for an identity. `null` for an identity no
+ * signed-in link flow or verified address created; the caller then treats
+ * the author as anonymous.
+ */
+type PrincipalByIdentity = (identity: IdentityRef) => IdentityTarget | null | Promise<IdentityTarget | null>;
+/** The fields of an event a subscriber check reads. */
+interface SubscriberEvent {
+  readonly type: string;
+  readonly tenant: string | null;
+  /** The user who caused the event, or `null` for service work. */
+  readonly actorId: string | null;
+  readonly payload: unknown;
+  /** The event's subject, such as `invoices/123`, when it has one. */
+  readonly subject?: string | null;
+}
+/**
+ * A subscription a fan-out may deliver to. `principal` is the user who owns
+ * it, or the id of the service principal an organization-owned subscription
+ * runs as (`kind: "service"`).
+ */
+interface Subscriber {
+  readonly principal: string;
+  readonly kind?: "user" | "service";
+}
+/**
+ * Narrows a fan-out to the subscribers that may read the event: webhook
+ * endpoints, outbox consumers, realtime members and notification
+ * recipients. It returns a subset of `subscribers`; a subscriber it leaves
+ * out gets nothing, and a throw or rejection delivers to no one.
+ */
+type SubscriberPolicy = <S extends Subscriber>(event: SubscriberEvent, subscribers: readonly S[]) => readonly S[] | Promise<readonly S[]>;
+/** A request that waits for someone other than the requester to approve it. */
+interface ApprovalRequestRef {
+  /** `ai-tool` (an AI tool call), `support-session`, or the app's own kind. */
+  readonly kind: string;
+  /** The tool name for `ai-tool`, the request id for `support-session`. */
+  readonly subject: string;
+  readonly tenant?: string;
+  /** The user who asked; never their own approver. */
+  readonly requester?: string;
+}
+/** The signed-in user who would approve, with their verified claims. */
+interface Approver {
+  readonly userId: string;
+  readonly claims: Readonly<Record<string, unknown>>;
+}
+/**
+ * Whether `approver` may decide `request`. The SQL side is the
+ * `isApprover` template of the authorization provider; this is the same
+ * decision for server code. A throw counts as `false`, and better-supabase
+ * refuses the requester before it asks.
+ */
+type ApproverOf = (approver: Approver, request: ApprovalRequestRef) => boolean | Promise<boolean>;
+/** What `mayPublish` and `runAs` get about a published automation. */
+interface AutomationRef {
+  /** The user who published it, or `null` for an organization-owned automation. */
+  readonly publisher: string | null;
+  readonly tenant: string | null;
+  /** The permissions its nodes need, as stored at publish. */
+  readonly permissions: readonly string[];
+}
+/** How a provider decides published automations (workflow builder versions). */
+interface AutomationHooks {
+  /** Whether the publisher may publish a version whose nodes need `permissions`. */
+  readonly mayPublish?: (automation: AutomationRef & {
+    readonly claims: Readonly<Record<string, unknown>>;
+  }) => boolean | Promise<boolean>;
+  /**
+   * The claims a step of a published version runs with: the publisher's
+   * current claims narrowed to `permissions`, or the service principal's
+   * for an organization-owned automation. `null` when the publisher is
+   * gone, suspended or no longer holds a stored permission; the step then
+   * fails and never falls back to the service role.
+   */
+  readonly runAs?: (automation: AutomationRef) => Readonly<Record<string, unknown>> | null | Promise<Readonly<Record<string, unknown>> | null>;
+}
+/**
+ * Turns an opaque run ticket back into the context a job or a workflow step
+ * runs as. `null` or a throw refuses the ticket (expired, revoked, or for a
+ * principal that is gone), and the run fails instead of running as anyone
+ * else. The ticket is stored in plain text as a run attribute, so it is an
+ * id the provider looks up, never a bearer secret.
+ */
+type TicketSubject = (ticket: string) => RequestContext | null | Promise<RequestContext | null>;
+/** A delegated token, as `forContext` sees it: an OAuth client or agent acting for a user. */
+interface DelegationRef {
+  readonly userId: string;
+  readonly tenant?: string;
+  /** The OAuth client, when the token has a `client_id`. */
+  readonly clientId?: string;
+  /** The scopes the user granted, split on spaces. */
+  readonly scopes: readonly string[];
+  /** RFC 9396 `authorization_details`, when the token has them. */
+  readonly authorizationDetails?: readonly {
+    readonly type: string;
+    readonly [field: string]: unknown;
+  }[];
+}
+/**
+ * The permission keys a delegated token may use, for scopes the provider
+ * maps at runtime (`authorization.delegation.scopes` is the static form in
+ * SQL). `forContext` caps the work to them, narrowed by its own
+ * `permissions`; a throw grants nothing.
+ */
+type DelegationPermissions = (delegation: DelegationRef) => readonly string[] | Promise<readonly string[]>;
+/** A button a chat user pressed on a message the app sent. */
+interface ChatAction {
+  /** The action id the card declared, such as `approve`. */
+  readonly id: string;
+  readonly value?: string;
+  /** The chat user, as the platform reports them. */
+  readonly author: IdentityRef;
+}
+/**
+ * Decides a chat action for its linked author: `undefined` when the
+ * provider does not handle the action. An approval button is decided here,
+ * through the provider; an unlinked author is refused.
+ */
+type ChatActionHook = (action: ChatAction, author: IdentityTarget | null) => {
+  readonly allowed: boolean;
+  readonly userId?: string;
+} | undefined | Promise<{
+  readonly allowed: boolean;
+  readonly userId?: string;
+} | undefined>;
+/** A support session start the `authorize` hook decides. */
+interface SupportAuthorizeInput {
+  readonly admin: Extract<AuthState, {
+    kind: "user";
+  }>;
+  readonly targetUserId: string;
+  /** Never empty: a start without a reason is refused before `authorize` runs. */
+  readonly reason: string;
+  readonly readOnly: boolean;
+  readonly tenant?: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+/**
+ * `true` allows a support start that still needs a second approver unless
+ * approval is off; `{ approvedBy }` allows it and names the distinct approver
+ * the provider checked. `false`, a throw and an `approvedBy` equal to the
+ * admin refuse it.
+ */
+type SupportDecision = boolean | {
+  readonly approvedBy: string;
+};
+/** Decides a support session start. */
+type SupportAuthorize = (input: SupportAuthorizeInput) => SupportDecision | Promise<SupportDecision>;
+/**
+ * The runtime half of an authorization provider (`apiVersion: 1`). The
+ * `authorization` config key is plain data for SQL; these hooks decide the
+ * same things in server code, so one provider can own automations,
+ * support sessions, delivery, identity links, chat actions, approvals and
+ * delegated tokens end to end. Every hook is optional, and a slot passed to a block directly
+ * wins over the hook.
+ */
+interface AuthorizationHooks {
+  readonly apiVersion: 1;
+  /** The provider's name, for messages. */
+  readonly name: string;
+  readonly automation?: AutomationHooks;
+  readonly support?: {
+    readonly authorize: SupportAuthorize;
+  };
+  readonly delivery?: {
+    /** Webhook endpoints, outbox consumers and realtime members. */
+    readonly subscribers?: SubscriberPolicy;
+    /** Notification recipients. */
+    readonly audience?: SubscriberPolicy;
+  };
+  readonly identities?: {
+    readonly principalByIdentity: PrincipalByIdentity;
+  };
+  readonly chat?: {
+    readonly onAction?: ChatActionHook;
+  };
+  readonly approverOf?: ApproverOf;
+  readonly tickets?: {
+    readonly subject: TicketSubject;
+  };
+  readonly delegation?: {
+    readonly permissions: DelegationPermissions;
+  };
+}
+/** Types `hooks` and freezes it; better-supabase never mutates a provider. */
+declare function defineAuthorizationHooks<const H extends AuthorizationHooks>(hooks: H): H;
+//#endregion
+export { SupportAuthorize as _, AutomationHooks as a, TicketSubject as b, ChatActionHook as c, IdentityRef as d, IdentityTarget as f, SubscriberPolicy as g, SubscriberEvent as h, AuthorizationHooks as i, DelegationPermissions as l, Subscriber as m, Approver as n, AutomationRef as o, PrincipalByIdentity as p, ApproverOf as r, ChatAction as s, ApprovalRequestRef as t, DelegationRef as u, SupportAuthorizeInput as v, defineAuthorizationHooks as x, SupportDecision as y };

package/dist/authorizer-DH7DjkL3.js

@@ -0,0 +1,126 @@
+import { n as deepFreeze, r as isPlainObject, t as cloneValue } from "./clone-dN9XOL1K.js";
+import { n as dbError } from "./errors-8i6tSICm.js";
+import { a as ok, r as err } from "./result-BlgnMB0H.js";
+//#region src/core/authorizer.ts
+/** Identity helper that fixes `apiVersion` and infers `Ref`. */
+function defineAuthorizer(authorizer) {
+	return {
+		...authorizer,
+		apiVersion: 1
+	};
+}
+const ANONYMOUS = {
+	type: "anon",
+	id: "anonymous"
+};
+function scopesOf(claims) {
+	const scope = claims?.["scope"];
+	return typeof scope === "string" ? scope.split(" ").filter(Boolean) : [];
+}
+/** A frozen copy of the verified claims, so an authorizer cannot change them. */
+function claimsProperty(claims) {
+	if (!isPlainObject(claims)) return {};
+	return { claims: deepFreeze(cloneValue(claims)) };
+}
+/** The subject and context of a request, from the verified context only. */
+function requestOf(context) {
+	const actor = context?.actor;
+	const claims = context?.claims;
+	const act = claims?.["act"];
+	const subject = actor ? {
+		type: typeof act === "object" && act !== null && actor.kind === "user" ? "agent" : actor.kind,
+		id: actor.id,
+		properties: {
+			...actor.role === void 0 ? {} : { role: actor.role },
+			...actor.email === void 0 ? {} : { email: actor.email },
+			...actor.impersonator === void 0 ? {} : { impersonator: actor.impersonator },
+			...claimsProperty(claims)
+		}
+	} : ANONYMOUS;
+	const aal = claims?.["aal"];
+	return {
+		subject,
+		context: {
+			...context?.tenant === void 0 ? {} : { tenant: context.tenant },
+			...typeof aal === "string" ? { aal } : {},
+			scopes: scopesOf(claims)
+		}
+	};
+}
+function isOutcome(value) {
+	if (typeof value !== "object" || value === null || !("outcome" in value)) return false;
+	const { outcome } = value;
+	return outcome === "granted" || outcome === "denied" || outcome === "approval-required";
+}
+/** The `forbidden` error for an outcome other than `granted`, or `undefined`. */
+function outcomeError(outcome, permission) {
+	if (!isOutcome(outcome)) return dbError("forbidden", `The authorizer gave no decision for ${permission}`, {
+		code: "PERMISSION_DENIED",
+		permission
+	});
+	switch (outcome.outcome) {
+		case "granted": return;
+		case "denied": return dbError("forbidden", outcome.reason ?? `Permission ${permission} is required`, {
+			code: "PERMISSION_DENIED",
+			permission
+		});
+		case "approval-required": return dbError("forbidden", `${permission} needs an approval`, {
+			code: "APPROVAL_REQUIRED",
+			permission,
+			...outcome.approval ? { approval: { id: outcome.approval.id } } : {}
+		});
+		default: return outcome;
+	}
+}
+/**
+* Checks one permission and fails closed: a missing authorizer, a throw or
+* an unknown outcome all deny. Never throws (invariant 4).
+*/
+async function checkPermission(options) {
+	const { authorizer, permission } = options;
+	if (!authorizer) return err(dbError("forbidden", "A permission is declared, but no authorizer is set", { code: "PERMISSION_DENIED" }));
+	let key;
+	try {
+		key = authorizer.key(permission);
+	} catch {
+		return err(dbError("forbidden", "Unknown permission", { code: "PERMISSION_DENIED" }));
+	}
+	const { subject, context } = requestOf(options.context);
+	try {
+		const error = outcomeError(await authorizer.evaluate({
+			subject,
+			action: permission,
+			resource: options.resource,
+			context
+		}), key);
+		return error ? err(error) : ok(void 0);
+	} catch {
+		return err(dbError("forbidden", `The authorizer failed for ${key}`, {
+			code: "PERMISSION_DENIED",
+			permission: key
+		}));
+	}
+}
+/**
+* Checks one permission per resource, with `evaluations` when the
+* authorizer has it. Returns whether each one is granted, in order; any
+* failure denies.
+*/
+async function checkEach(authorizer, permission, resources, context) {
+	if (!authorizer || resources.length === 0) return resources.map(() => false);
+	const { subject, context: requestContext } = requestOf(context);
+	const requests = resources.map((resource) => ({
+		subject,
+		action: permission,
+		resource,
+		context: requestContext
+	}));
+	try {
+		const outcomes = authorizer.evaluations ? await authorizer.evaluations(requests) : await Promise.all(requests.map((request) => Promise.resolve(authorizer.evaluate(request))));
+		return requests.map((_, index) => isOutcome(outcomes[index]) && outcomes[index].outcome === "granted");
+	} catch {
+		return resources.map(() => false);
+	}
+}
+//#endregion
+export { requestOf as i, checkPermission as n, defineAuthorizer as r, checkEach as t };

package/dist/authorizer-eiOjo-3l.d.ts

@@ -0,0 +1,73 @@
+//#region src/core/authorizer.d.ts
+type JsonObject = Readonly<Record<string, unknown>>;
+/** Who asks (AuthZEN Subject). Always built from the verified request context. */
+interface AuthorizationSubject {
+  /** `user`, `service`, `anon`, or `agent` for a delegated token with an `act` chain. */
+  readonly type: string;
+  readonly id: string;
+  /**
+   * `role`, `email` and `impersonator` when set, and `claims`: the verified
+   * access-token claims (a frozen copy, including what a token hook wrote,
+   * such as `memberships`, `roles` and `act`). The client never supplies
+   * them. Anonymous subjects have no properties.
+   */
+  readonly properties?: JsonObject;
+}
+/** What is acted on (AuthZEN Resource): a table, a topic or an action's target. */
+interface AuthorizationResource {
+  readonly type: string;
+  readonly id?: string;
+  /** The row, for decisions that read it (`get`, `update`, `delete`). */
+  readonly properties?: JsonObject;
+}
+/**
+ * One access request, in the AuthZEN Authorization API 1.0 information
+ * model (`SPEC_PINS.authzen`): subject, action, resource and context.
+ * `action` is the permission reference the authorizer understands.
+ */
+interface AuthorizationRequest<Ref = string> {
+  readonly subject: AuthorizationSubject;
+  readonly action: Ref;
+  readonly resource: AuthorizationResource;
+  /** The tenant, assurance level and scopes of the request. */
+  readonly context: JsonObject;
+}
+type AuthorizationOutcome = {
+  readonly outcome: "granted";
+  readonly context?: JsonObject;
+} | {
+  readonly outcome: "denied";
+  readonly reason?: string;
+  readonly context?: JsonObject;
+} | {
+  readonly outcome: "approval-required";
+  readonly approval?: {
+    readonly id: string;
+  };
+  readonly context?: JsonObject;
+};
+/**
+ * A runtime authorization decision point (API v1). Authorization libraries
+ * ship an adapter that implements it; better-supabase builds every request
+ * and fails closed on anything but `granted`.
+ */
+interface Authorizer<Ref = string> {
+  readonly apiVersion: 1;
+  readonly name: string;
+  /** The stable key of a permission reference, for specs, SQL and messages. */
+  key(ref: Ref): string;
+  /** The default permission for a table operation; lets `permissions: true` work. */
+  forOperation?(table: string, operation: string): Ref | undefined;
+  evaluate(request: AuthorizationRequest<Ref>): AuthorizationOutcome | Promise<AuthorizationOutcome>;
+  /** The batch form (AuthZEN Access Evaluations); results keep the request order. */
+  evaluations?(requests: readonly AuthorizationRequest<Ref>[]): Promise<readonly AuthorizationOutcome[]>;
+}
+type AnyAuthorizer = Authorizer<any>;
+/** The permission reference type of an authorizer, `string` without one. */
+type PermissionRef<A> = A extends Authorizer<infer R> ? R : string;
+/** Identity helper that fixes `apiVersion` and infers `Ref`. */
+declare function defineAuthorizer<Ref = string>(authorizer: Omit<Authorizer<Ref>, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): Authorizer<Ref>;
+//#endregion
+export { AuthorizationSubject as a, defineAuthorizer as c, AuthorizationResource as i, AuthorizationOutcome as n, Authorizer as o, AuthorizationRequest as r, PermissionRef as s, AnyAuthorizer as t };

package/dist/base64-BmeCBgGo.js

@@ -0,0 +1,42 @@
+//#region src/core/base64.ts
+const encoder = /* @__PURE__ */ new TextEncoder();
+const decoder = /* @__PURE__ */ new TextDecoder();
+/** Standard base64 (RFC 4648 section 4) of `input`, with padding. */
+function toBase64(input) {
+	const bytes = typeof input === "string" ? encoder.encode(input) : input;
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCodePoint(byte);
+	return btoa(binary);
+}
+/** Bytes of standard or URL-safe base64, padded or not. Throws on invalid input. */
+function fromBase64(text) {
+	const base64 = text.replaceAll("-", "+").replaceAll("_", "/");
+	const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.codePointAt(index) ?? 0;
+	return bytes;
+}
+/** URL-safe base64 (RFC 4648 section 5) of `input`, without padding. */
+function toBase64Url(input) {
+	return toBase64(input).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/** UTF-8 text of base64 or base64url. Throws on invalid input. */
+function base64ToText(text) {
+	return decoder.decode(fromBase64(text));
+}
+/**
+* The payload of a JWT, decoded without verifying the signature. Only for
+* reading claims such as `exp` from a token that is verified elsewhere.
+*/
+function decodeJwtPayload(token) {
+	const part = token.split(".")[1];
+	if (!part) return;
+	try {
+		const parsed = JSON.parse(base64ToText(part));
+		return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { toBase64Url as a, toBase64 as i, decodeJwtPayload as n, fromBase64 as r, base64ToText as t };

package/dist/batch-limit-DKVQDz4o.js

@@ -0,0 +1,5 @@
+//#region src/core/batch-limit.ts
+/** The most events one batched sink call (`audit_event_many`, ...) takes. */
+const MAX_BATCH = 1e3;
+//#endregion
+export { MAX_BATCH as t };

package/dist/before-route-B98js9m_.js

@@ -0,0 +1,30 @@
+import { t as around } from "./shared-BmMcMoW9.js";
+//#region src/bridges/before-route.ts
+/**
+* Runs the entries ahead of a framework that owns the route and the
+* response (Express, Fastify, Koa, Nitro 2, SolidStart, NestJS). A short
+* circuit is the answer; otherwise the framework copies the headers and
+* hands the contributions to the route. Response-phase entries see an
+* empty response, so `withDbStats` and `withServerTiming` report nothing here.
+*/
+function beforeRoute(entries) {
+	const run = around(entries);
+	return async (request, env) => {
+		let contributions;
+		const marker = new Response(null);
+		const response = await run(request, env, (handed) => {
+			contributions = handed;
+			return Promise.resolve(marker);
+		});
+		return contributions === void 0 ? {
+			reached: false,
+			response
+		} : {
+			reached: true,
+			contributions,
+			headers: response.headers
+		};
+	};
+}
+//#endregion
+export { beforeRoute as t };

package/dist/better-result/index.d.ts

@@ -0,0 +1,118 @@
+import { b as DbError, n as BetterResultApi, t as AsyncResult } from "../result-Cj3yWhjH.js";
+import { B as TableMeta, E as PrimaryKeyValue, U as UniqueWhere, W as Update, a as AnyModels, i as AnyFunctions, x as Insert, z as TableKey } from "../types-YfwpIE-d.js";
+import { r as ApplyExtension } from "../plugin-CDLJRFFg.js";
+import { A as OverloadedName, B as UpsertArgs, Bt as WhereInput, C as ManyReturningArgs, Ct as FindOnlyArgs, D as OffsetRangeArgs, E as OffsetPageArgs, G as SearchScore, H as WriteArgs, I as Returned, It as RequestArgs, K as InferReadSetParams, L as RpcArgs, M as PlainName, N as RawRpcOptions, Nt as Payload, O as OverloadArgs, Pt as ReadArgs, R as RpcOptions, S as ManyResult, St as FindManyArgs, U as WriteManyArgs, V as UpsertManyArgs, W as SearchArgs, _ as Db, at as QuerySpec, b as DeleteExt, dt as AggregateArgs, et as ReadSetResult, g as CursorPageArgs, it as InferResult, j as PageOf, k as OverloadReturns, mt as AggregateResult, q as ReadSet, w as NoArgName, x as FindExt, xt as FindFirstArgs, y as DeleteArgs, yt as CountArgs, z as UpdateArgs } from "../define-DxHHbNEb.js";
+import { a as ListExtra, d as ListQuery, i as ListDefinition, o as ListPage, s as ListPagination } from "../list-query-PvP3pPGQ.js";
+import { Result } from "better-result";
+//#region src/better-result/better-result.d.ts
+/** better-result's `Result` namespace with the function each `DbError` goes through. */
+interface BetterResultMapping<E> {
+  readonly Result: BetterResultApi<unknown, unknown>;
+  readonly mapError: (error: DbError) => E;
+}
+/** What `withBetterResult` calls on a `defineBetterResultErrors` converter. */
+interface BetterResultErrorsLike {
+  (result: AsyncResult<unknown>): unknown;
+  map(error: DbError): unknown;
+}
+/** A `defineBetterResultErrors` converter or a `{ Result, mapError }` mapping. */
+type BetterResultConverter = BetterResultErrorsLike | BetterResultMapping<unknown>;
+/** The error type a converter produces. */
+type ConvertedError<X> = X extends BetterResultMapping<infer E> ? E : X extends {
+  map(error: DbError): infer E;
+} ? E : never;
+type Out<T, Err> = Promise<Result<T, Err>>;
+/**
+ * A repository whose reads and writes return better-result values. Its
+ * signatures mirror `Repository`, so `select` and `include` still type the rows.
+ */
+interface BetterResultRepository<M extends AnyModels, T extends TableKey<M>, E, Err> {
+  readonly $tableName: T;
+  readonly $meta: TableMeta;
+  findMany<const A extends FindManyArgs<M, T> & FindExt<E, M, T>>(args?: A): Out<Payload<M, T, A>[], Err>;
+  findFirst<const A extends FindFirstArgs<M, T> & FindExt<E, M, T>>(args?: A): Out<Payload<M, T, A> | null, Err>;
+  findOnly<const A extends FindOnlyArgs<M, T> & FindExt<E, M, T>>(args: A): Out<Payload<M, T, A> | null, Err>;
+  findUnique<const A extends ReadArgs<M, T> & {
+    readonly where: UniqueWhere<M, T>;
+  } & FindExt<E, M, T>>(args: A): Out<Payload<M, T, A> | null, Err>;
+  findById<const A extends ReadArgs<M, T> & FindExt<E, M, T>>(id: PrimaryKeyValue<M, T>, args?: A): Out<Payload<M, T, A>, Err>;
+  count(args?: CountArgs<M, T> & FindExt<E, M, T>): Out<number, Err>;
+  aggregate<const A extends AggregateArgs<M, T> & FindExt<E, M, T>>(args: A): Out<AggregateResult<M, T, A>, Err>;
+  exists(args?: RequestArgs & {
+    readonly where?: WhereInput<M, T>;
+  } & FindExt<E, M, T>): Out<boolean, Err>;
+  paginate<const A extends (OffsetPageArgs<M, T> | OffsetRangeArgs<M, T> | CursorPageArgs<M, T>) & FindExt<E, M, T>>(args: A): Out<PageOf<M, T, A>, Err>;
+  create<const A extends WriteArgs<M, T> = {}>(data: Insert<M, T>, args?: A): Out<Returned<M, T, A>, Err>;
+  createMany<const A extends WriteManyArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): Out<A extends {
+    readonly returning: false;
+  } ? {
+    count: number;
+  } : Payload<M, T, A>[], Err>;
+  update<const A extends UpdateArgs<M, T> = {}>(id: PrimaryKeyValue<M, T>, patch: Update<M, T>, args?: A): Out<Returned<M, T, A>, Err>;
+  updateMany<const A extends ManyReturningArgs<M, T> & {
+    readonly data: Update<M, T>;
+    readonly allowAll?: boolean;
+  } & FindExt<E, M, T>>(args: A): Out<ManyResult<M, T, A>, Err>;
+  upsert<const A extends UpsertArgs<M, T> = {}>(data: Insert<M, T>, args?: A): Out<A extends {
+    readonly ignoreDuplicates: true;
+  } ? Returned<M, T, A> | null : Returned<M, T, A>, Err>;
+  upsertMany<const A extends UpsertManyArgs<M, T> = {}>(rows: readonly Insert<M, T>[], args?: A): Out<A extends {
+    readonly returning: false;
+  } ? {
+    count: number;
+  } : Payload<M, T, A>[], Err>;
+  delete(id: PrimaryKeyValue<M, T>, args?: DeleteArgs & DeleteExt<E, M, T>): Out<void, Err>;
+  deleteMany<const A extends ManyReturningArgs<M, T> & DeleteExt<E, M, T> & FindExt<E, M, T>>(args: A): Out<ManyResult<M, T, A>, Err>;
+}
+/**
+ * Plugin methods that return an `AsyncResult` return a better-result value.
+ * A generic plugin method keeps its parameters but loses its type
+ * parameters; call it on `$db` and pass the result to `$from` instead.
+ */
+type BetterResultMethods<X, Err> = { readonly [K in keyof X]: X[K] extends ((...args: infer P) => AsyncResult<infer R>) ? (...args: P) => Out<R, Err> : X[K]; };
+type BetterResultRepositoryOf<M extends AnyModels, T extends TableKey<M>, E, Err> = BetterResultRepository<M, T, E, Err> & BetterResultMethods<ApplyExtension<E, M, T, "methods">, Err>;
+interface BetterResultHelpers<M extends AnyModels, F extends AnyFunctions, E, C, Err> {
+  /** The `db` this view wraps, for everything that returns plain results. */
+  readonly $db: Db<M, F, E, C>;
+  /** Converts any `AsyncResult`, such as one from a plugin method or `$with`. */
+  $from<T>(result: AsyncResult<T>): Out<T, Err>;
+  $rpc<N extends PlainName<F>>(name: N, ...rest: [...RpcArgs<F, N>, options: RawRpcOptions]): Out<unknown, Err>;
+  $rpc<N extends PlainName<F>, R = F[N]["Returns"]>(name: N, ...rest: [...RpcArgs<F, N>, options?: RpcOptions<R>]): Out<R, Err>;
+  $rpc<N extends OverloadedName<F>, const A extends F[N]["Args"]>(name: N, args: OverloadArgs<F[N], A>, options: RawRpcOptions): Out<unknown, Err>;
+  $rpc<N extends OverloadedName<F>, const A extends F[N]["Args"], R = OverloadReturns<F[N], A>>(name: N, args: OverloadArgs<F[N], A>, options?: RpcOptions<R>): Out<R, Err>;
+  $rpc<N extends NoArgName<F>>(name: N): Out<OverloadReturns<F[N], Record<never, never>>, Err>;
+  $table<T extends TableKey<M>>(name: T): BetterResultRepositoryOf<M, T, E, Err>;
+  $run<S extends QuerySpec<TableKey<M>>>(spec: S, options?: {
+    readonly signal?: AbortSignal;
+  }): Out<InferResult<S>, Err>;
+  $many<S extends ReadSet>(readSet: S, params: InferReadSetParams<S>, options?: {
+    readonly signal?: AbortSignal;
+  }): Out<ReadSetResult<S>, Err>;
+  $many<const S extends readonly QuerySpec<TableKey<M>>[]>(specs: S, options?: {
+    readonly signal?: AbortSignal;
+  }): Out<{ -readonly [K in keyof S]: InferResult<S[K]>; }, Err>;
+  $search<T extends TableKey<M>, const A extends SearchArgs<M, T>>(table: T, args: A): Out<(Payload<M, T, A> & SearchScore<A>)[], Err>;
+  /** Runs a list query (`defineListQuery`) like `list.run(db, query, extra)`. */
+  $list<T extends TableKey<M>, S extends string, LF extends string, LC extends boolean, P extends ListPagination, const A extends ListExtra<M, T> & FindExt<E, M, T>>(list: ListDefinition<M, T, E, S, LF, LC, P>, query: ListQuery<S, LF>, extra?: A): Out<ListPage<Payload<M, T, A>, LF, LC, P>, Err>;
+}
+/** A `db` whose repositories and helpers return better-result values. */
+type BetterResultDb<M extends AnyModels, F extends AnyFunctions, E, C, Err> = { readonly [T in TableKey<M>]: BetterResultRepositoryOf<M, T, E, Err>; } & BetterResultHelpers<M, F, E, C, Err>;
+/**
+ * A view of `db` whose repository methods, `$rpc`, `$run`, `$many`,
+ * `$search` and list queries (`$list`) return better-result `Result`
+ * values. `toResult` is a `defineBetterResultErrors` converter or
+ * `{ Result, mapError }`. `db` itself is unchanged, and `$db` returns it.
+ *
+ * ```ts
+ * import { Result, TaggedError } from 'better-result';
+ * import { defineBetterResultErrors } from 'better-supabase';
+ * import { withBetterResult } from 'better-supabase/better-result';
+ *
+ * const toResult = defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure);
+ * const rdb = withBetterResult(db, toResult);
+ * const customer = await rdb.customers.findById(id); // Result<Customer, NotFound | DbFailure>
+ * ```
+ */
+export declare function withBetterResult<M extends AnyModels, F extends AnyFunctions, E, C, const X extends BetterResultConverter>(db: Db<M, F, E, C>, toResult: X): BetterResultDb<M, F, E, C, ConvertedError<X>>;
+//#endregion
+export type { BetterResultConverter, BetterResultDb, BetterResultErrorsLike, BetterResultHelpers, BetterResultMapping, BetterResultMethods, BetterResultRepository, BetterResultRepositoryOf, ConvertedError };