better-supabase 0.12.0 → 0.13.0

package/dist/ended-D_Twxl8v.d.ts

@@ -0,0 +1,76 @@
+import { m as RequestContext } from "./plugin-DouW0Kvg.js";
+import { g as StoredSession, r as AuthState, u as CookieOptions } from "./resolve-D57oDWNr.js";
+//#region src/auth/refresh.d.ts
+interface RefreshOptions {
+  readonly url: string;
+  readonly publishableKey: string;
+  /**
+   * Sends `Sb-Forwarded-For: ip` with the secret key, so Auth rate-limits the
+   * refresh by the user's IP (when IP forwarding is on for the project).
+   */
+  readonly forwardedFor?: {
+    readonly ip: string;
+    readonly secretKey: string;
+  };
+  readonly fetch?: typeof fetch;
+  /**
+   * Milliseconds before a refresh counts as a network failure (the session is
+   * kept). 5000 by default.
+   */
+  readonly timeoutMs?: number;
+  /** Epoch milliseconds, the unit JWT `exp` and `iat` math needs. */
+  readonly now?: () => number;
+}
+type RefreshOutcome = {
+  readonly ok: true;
+  readonly session: StoredSession;
+  /** Served from a concurrent or just-finished refresh of the same token. */
+  readonly shared?: boolean;
+} | {
+  readonly ok: false;
+  /**
+   * `rejected`: the refresh token is dead, sign the user out. `network`:
+   * keep the session and retry later.
+   */
+  readonly reason: "rejected" | "network";
+  /** For `network`: the fetch failed, timed out, or Auth answered 5xx or 429. */
+  readonly cause?: "fetch" | "timeout" | "status";
+  readonly status?: number;
+  /**
+   * The Auth server's `error_code`, such as `user_banned` or
+   * `refresh_token_not_found`.
+   */
+  readonly code?: string;
+  readonly message: string;
+};
+/**
+ * Exchanges a refresh token for a new session. Concurrent calls with the same
+ * token share one request, and a successful result is reused for a short window
+ * so parallel requests carrying the old cookie converge on one session.
+ */
+declare function refreshSession(refreshToken: string, options: RefreshOptions): Promise<RefreshOutcome>;
+//#endregion
+//#region src/auth/context.d.ts
+/** The repository context (`actor`, `claims`) for an auth state. */
+declare function authContext(auth: AuthState): RequestContext;
+//#endregion
+//#region src/auth/ended.d.ts
+/** `banned`: Auth rejected the token with `error_code: "user_banned"`. */
+type SessionStatus = "active" | "ended" | "banned" | "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, RefreshOutcome as c, clearSessionCookies as i, refreshSession as l, SessionStatus as n, authContext as o, SessionStatusOptions as r, RefreshOptions as s, ClearSessionCookiesOptions as t };

package/dist/entitlements-CMGsO4gL.d.ts

@@ -0,0 +1,54 @@
+import { t as AuthSnapshot } from "./bind-DcXLU1ul.js";
+import { t as AuthSession } from "./view-CKzCp8FW.js";
+//#region src/auth/entitlements.d.ts
+/**
+ * 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`. */
+  readonly scope: string;
+  readonly id: string;
+  /** Parent scopes, e.g. `{ organization: '...' }` for a project membership. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly roles: readonly string[];
+  readonly via?: string;
+  /** Unix seconds. */
+  readonly expiresAt?: number;
+  readonly grantedBy?: string;
+  readonly reason?: string;
+  readonly member?: {
+    readonly group: string;
+  };
+  readonly managedBy?: "idp";
+  /** Seats, not plan features: those are in the `features` claim. */
+  readonly entitlements?: readonly string[];
+}
+/**
+ * Entitlement keys of the `features` claim: the literal union when
+ * `betterSupabase.claims(schema)` declares one (`z.enum([...])`), otherwise
+ * `string`.
+ */
+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, 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. A tenant left out by
+ * `entitlements.claim.maxTenants` reads as not granted. Takes a server session
+ * or the client's `useAuth()` snapshot.
+ */
+declare function hasEntitlement<C>(session: AuthSession<C> | AuthSnapshot, tenantId: string, key: EntitlementKey<C>, claim?: string | EntitlementClaimOptions): boolean;
+//#endregion
+export { hasEntitlement as i, EntitlementKey as n, MembershipClaim as r, EntitlementClaimOptions as t };

package/dist/entitlements-_tw0V3BY.js

@@ -0,0 +1,45 @@
+import { t as AsyncResult } from "./result-DIT_qp4G.js";
+import { j as run, o as blockCall } from "./block-helpers-DwE32_gT.js";
+import { r as withBlockHooks } from "./block-hooks-C1r-R2r0.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;
+	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));
+}
+/**
+* Reads the caller's entitlements through the `entitlements` module's
+* `has_entitlement` and `entitlement_value`, which check membership.
+*/
+function createEntitlements(options) {
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return withBlockHooks({
+		has: (organizationId, key) => call("has_entitlement", {
+			tenant: organizationId,
+			key
+		}, (value) => value === true),
+		value: (organizationId, key) => call("entitlement_value", {
+			tenant: organizationId,
+			key
+		}, (value) => value === null ? void 0 : value)
+	}, options.hooks, {
+		block: "entitlements",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+export { createEntitlements as n, entitlementMembers as r, ENTITLEMENTS_UPDATED as t };

package/dist/env/index.d.ts

@@ -1,2 +1,2 @@
-import { a as EnvResult, c as InlineJwks, d as loadEnv, f as parseEnv, i as EnvOptions, l as PublicEnv, m as toServerEnv, n as ENV_VARIABLES, o as EnvSource, p as publicEnv, r as EnvIssue, s as EnvValidationError, t as BetterSupabaseEnv, u as envSchema } from "../index-CxmVzT-3.js";
+import { a as EnvResult, c as InlineJwks, d as loadEnv, f as parseEnv, i as EnvOptions, l as PublicEnv, m as toServerEnv, n as ENV_VARIABLES, o as EnvSource, p as publicEnv, r as EnvIssue, s as EnvValidationError, t as BetterSupabaseEnv, u as envSchema } from "../index-NRMMhhEi.js";
 export { BetterSupabaseEnv, ENV_VARIABLES, EnvIssue, EnvOptions, EnvResult, EnvSource, EnvValidationError, InlineJwks, PublicEnv, envSchema, loadEnv, parseEnv, publicEnv, toServerEnv };

package/dist/env/index.js

@@ -67,7 +67,10 @@ function preferred(keys) {
 function isJwk(value) {
 	return typeof value === "object" && value !== null && "kty" in value && typeof value.kty === "string";
 }
-/** At least one key, each an object with a string `kty`, the shape the verifier reads. */
+/**
+* At least one key, each an object with a string `kty`, the shape the verifier
+* reads.
+*/
 function isJwkList(value) {
 	return Array.isArray(value) && value.length > 0 && value.every(isJwk);
 }
@@ -207,13 +210,19 @@ function parseEnv(source, options = {}) {
 function processEnv() {
 	return globalThis.process?.env ?? {};
 }
-/** Like `parseEnv`, but throws `EnvValidationError`. Reads `process.env` by default. */
+/**
+* Like `parseEnv`, but throws `EnvValidationError`. Reads `process.env` by
+* default.
+*/
 function loadEnv(source = processEnv(), options = {}) {
 	const result = parseEnv(source, options);
 	if (!result.ok) throw new EnvValidationError(result.issues);
 	return result.env;
 }
-/** The env validator as a Standard Schema, for t3-env, framework config or any validator slot. */
+/**
+* The env validator as a Standard Schema, for t3-env, framework config or any
+* validator slot.
+*/
 function envSchema(options = {}) {
 	return { "~standard": {
 		version: 1,
@@ -236,7 +245,10 @@ function publicEnv(env) {
 		publishableKey: env.publishableKey
 	};
 }
-/** Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of `withSupabase`). */
+/**
+* Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of
+* `withSupabase`).
+*/
 function toServerEnv(env) {
 	return {
 		url: env.url,

package/dist/envelope-BDShQQ7-.js

@@ -0,0 +1,90 @@
+import { n as dbError } from "./errors-D7u24ZJH.js";
+import { a as ok, r as err } from "./result-DIT_qp4G.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { o as tenantFrom, s as tenantPathsFor } from "./claims-Bp9My7XP.js";
+import { n as impersonatorClaim, r as impersonatorOf } from "./impersonation-DFfDVJHk.js";
+import { i as delegatedClaims, n as PERMISSION_CAP_CLAIM, o as permissionCapOf, t as DELEGATION_CLAIMS } from "./delegation-DeAJehLk.js";
+//#region src/blocks/jobs/envelope.ts
+/** Marks a payload that carries a job context; pgmq stores it as the payload. */
+const ENVELOPE = "$bs";
+function ticketOf(context, options) {
+	const ticket = options.ticket ?? context?.["ticket"];
+	if (ticket === void 0) return ok(void 0);
+	if (typeof ticket === "string" && ticket !== "") return ok(ticket);
+	return err(dbError("validation", "A job ticket is a non-empty string", { issues: [{
+		message: "Expected a non-empty string",
+		path: ["ticket"]
+	}] }));
+}
+/**
+* The context a job records: the actor, the tenant, the ticket, and the `act`
+* chain and delegation of the token, so a job an OAuth or MCP client queued
+* runs with that client's scopes, never the user's full rights. An invalid
+* `act` chain or malformed delegation is `forbidden`.
+*/
+function recordContext(context, options = {}) {
+	const ticket = ticketOf(context, options);
+	if (!ticket.ok) return ticket;
+	if (!context) return ok(ticket.data === void 0 ? void 0 : { ticket: ticket.data });
+	const claims = context.claims ?? {};
+	const delegated = delegatedClaims(claims);
+	if (!delegated.ok) return err(dbError("forbidden", delegated.reason === "invalid-chain" ? "The job context has an invalid act claim" : "The job context has invalid delegation claims"));
+	const cap = permissionCapOf(claims);
+	if (cap === false) return err(dbError("forbidden", "The job context has an invalid permission cap"));
+	const tenant = tenantFrom(context, tenantPathsFor(void 0));
+	const impersonator = impersonatorOf(claims);
+	const recorded = {
+		...context.actor ? { actor: context.actor } : {},
+		...tenant === void 0 ? {} : { tenant },
+		...ticket.data === void 0 ? {} : { ticket: ticket.data },
+		...delegated.delegation,
+		...cap === void 0 ? {} : { [PERMISSION_CAP_CLAIM]: cap },
+		...impersonator ? { act: impersonatorClaim(impersonator) } : {}
+	};
+	if (!recorded.actor && recorded.tenant === void 0 && recorded.ticket === void 0) return ok(void 0);
+	return ok(recorded);
+}
+/** Wraps a payload with the recorded context of `context`, when there is one. */
+function wrapPayload(payload, context, options = {}) {
+	const recorded = recordContext(context, options);
+	if (!recorded.ok) return recorded;
+	return ok(recorded.data === void 0 ? payload : {
+		[ENVELOPE]: 1,
+		context: recorded.data,
+		payload
+	});
+}
+/** `wrapPayload` that throws a `TypeError` for a context it refuses. */
+function withContext(payload, context, options = {}) {
+	const wrapped = wrapPayload(payload, context, options);
+	if (!wrapped.ok) throw new TypeError(wrapped.error.message);
+	return wrapped.data;
+}
+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. The
+* recorded `act` and delegation claims come back as they were stored, so
+* `forContext` checks them again and refuses a malformed one.
+*/
+function unwrap(stored) {
+	if (!isRecord(stored) || stored[ENVELOPE] !== 1 || !Object.hasOwn(stored, "payload")) return {
+		payload: stored,
+		context: {}
+	};
+	const recorded = isRecord(stored["context"]) ? stored["context"] : {};
+	const { actor, tenant, ticket } = recorded;
+	const claims = Object.fromEntries(DELEGATION_CLAIMS.filter((key) => Object.hasOwn(recorded, key) && recorded[key] !== void 0).map((key) => [key, recorded[key]]));
+	return {
+		payload: stored["payload"],
+		context: {
+			...isActor(actor) ? { actor } : {},
+			...typeof tenant === "string" && tenant.length > 0 ? { tenant } : {},
+			...ticket === void 0 ? {} : { ticket },
+			...Object.keys(claims).length > 0 ? { claims } : {}
+		}
+	};
+}
+//#endregion
+export { withContext as n, wrapPayload as r, unwrap as t };

package/dist/errors-Cq72lONT.js

@@ -0,0 +1,44 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError, o as isDbError } from "./errors-D7u24ZJH.js";
+import { s as toDbError } from "./result-DIT_qp4G.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/errors-D7u24ZJH.js

@@ -0,0 +1,321 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+//#region src/core/errors.ts
+const STATUS = {
+	not_found: 404,
+	unauthorized: 401,
+	forbidden: 403,
+	conflict: 409,
+	foreign_key: 409,
+	check: 422,
+	not_null: 422,
+	exclusion: 409,
+	invalid_input: 400,
+	invalid_value: 500,
+	raised: 400,
+	timeout: 504,
+	serialization: 409,
+	network: 503,
+	aborted: 499,
+	invalid_request: 400,
+	validation: 422,
+	multiple_rows: 409,
+	stale: 412,
+	max_affected: 400,
+	rate_limited: 429,
+	quota_exceeded: 429,
+	unsupported: 501,
+	unexpected: 500
+};
+function statusOf(kind) {
+	return STATUS[kind];
+}
+/** Creates a `DbError` with the default status for its kind. */
+function dbError(kind, message, ...[extra]) {
+	const error = {
+		kind,
+		message,
+		status: STATUS[kind]
+	};
+	if (extra) {
+		for (const [key, value] of Object.entries(extra)) if (value !== void 0) error[key] = value;
+	}
+	return error;
+}
+function isDbError(value) {
+	return typeof value === "object" && value !== null && typeof value.kind === "string" && typeof value.message === "string" && typeof value.status === "number";
+}
+/**
+* The `DbError` in a `DbError`, a `DbException`, or an error whose `cause` is a
+* `DbError` (what `betterSupabase.mapError()` mappers should set).
+*/
+function dbErrorOf(value) {
+	if (value instanceof DbException) return value.error;
+	if (value instanceof Error && isDbError(value.cause)) return value.cause;
+	return isDbError(value) ? value : void 0;
+}
+function constraintGuard(kind) {
+	return (error, constraint) => {
+		const found = dbErrorOf(error);
+		if (found?.kind !== kind) return false;
+		return constraint === void 0 || found.constraint === constraint;
+	};
+}
+/**
+* A unique violation, optionally for one constraint. Accepts a `DbError` or a
+* `DbException`. Pass the generated `UniqueConstraint` type to check names:
+* `isConflict<UniqueConstraint>(error, 'customers_organization_id_kvk_key')`.
+*/
+const isConflict = constraintGuard("conflict");
+/** A CHECK violation, optionally for one constraint (`CheckConstraint`). */
+const isCheck = constraintGuard("check");
+/**
+* A foreign key violation, optionally for one constraint
+* (`ForeignKeyConstraint`).
+*/
+const isForeignKey = constraintGuard("foreign_key");
+/**
+* Builds the factory `.orThrow()` takes from handlers per error kind and per
+* SQLSTATE code. A handler that returns `undefined`, and an error no handler
+* matches, throw a `DbException`.
+*/
+function matchDbError(matchers) {
+	return (error) => {
+		return (error.code === void 0 || !matchers.codes ? void 0 : Object.hasOwn(matchers.codes, error.code) ? matchers.codes[error.code] : void 0)?.(error) ?? kindHandler(matchers, error)?.(error) ?? new DbException(error);
+	};
+}
+function kindHandler(matchers, error) {
+	if (!Object.hasOwn(matchers, error.kind)) return;
+	return matchers[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());
+}
+function optional(raw) {
+	const out = {};
+	if (raw.code) out.code = raw.code;
+	if (raw.details) out.details = raw.details;
+	if (raw.hint) out.hint = raw.hint;
+	return out;
+}
+/**
+* The `permissions` a `42501` raised with `detail = '{"permissions": [...]}'`
+* names, so a refusal from SQL carries the keys the caller lacks.
+*/
+function permissionsOf(details) {
+	if (details === void 0 || !details.startsWith("{")) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(details);
+	} catch {
+		return {};
+	}
+	if (typeof parsed !== "object" || parsed === null) return {};
+	const permissions = "permissions" in parsed ? parsed.permissions : void 0;
+	return Array.isArray(permissions) && permissions.every((key) => typeof key === "string") ? { permissions } : {};
+}
+/** 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.
+*/
+function mapDbError(raw, mappers = []) {
+	const fallback = mapBuiltin(raw);
+	for (const mapper of mappers) {
+		const mapped = mapper(raw, fallback);
+		if (mapped) return mapped;
+	}
+	return fallback;
+}
+function mapBuiltin(raw) {
+	const message = raw.message ?? "Unknown database error";
+	const base = optional(raw);
+	const code = raw.code ?? "";
+	if (raw.name === "AbortError" || code === "20" || message.startsWith("AbortError:")) return dbError("aborted", message, base);
+	switch (code) {
+		case "23505": {
+			const extra = {};
+			const constraint = constraintOf(raw);
+			const columns = columnsOf(raw);
+			if (constraint) extra.constraint = constraint;
+			if (columns) extra.columns = columns;
+			return dbError("conflict", message, {
+				...base,
+				...extra
+			});
+		}
+		case "23503": {
+			const extra = {};
+			const constraint = constraintOf(raw);
+			const columns = columnsOf(raw);
+			if (constraint) extra.constraint = constraint;
+			if (columns) extra.columns = columns;
+			return dbError("foreign_key", message, {
+				...base,
+				...extra
+			});
+		}
+		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 } : {}
+			});
+		}
+		case "23502": {
+			const column = raw.column ?? COLUMN_IN_MESSAGE.exec(message)?.[1];
+			return dbError("not_null", message, {
+				...base,
+				...column ? { column } : {}
+			});
+		}
+		case "23P01": {
+			const constraint = constraintOf(raw);
+			return dbError("exclusion", message, {
+				...base,
+				...constraint ? { constraint } : {}
+			});
+		}
+		case "42501": {
+			const object = PERMISSION_DENIED.exec(message);
+			const postgrestHint = base.hint?.startsWith("Grant the required");
+			if (!object || base.hint && !postgrestHint) return dbError("forbidden", message, {
+				...base,
+				...permissionsOf(base.details)
+			});
+			const advice = object[1] === "table" || object[1] === "view" ? `The Data API role has no grant on this ${object[1]}, as on a project with default privileges turned off: add it to \`expose\` and run \`better-supabase add grants\`. \`better-supabase doctor\` (BS106) lists every missing grant.` : `The Data API role has no ${object[1] === "function" ? "execute" : "usage"} grant on this ${object[1]}; grant it to the role that needs it.`;
+			const details = [
+				message,
+				base.details,
+				postgrestHint ? base.hint : ""
+			].filter(Boolean).join("\n");
+			return dbError("forbidden", "permission denied", {
+				...base,
+				details,
+				hint: advice
+			});
+		}
+		case "25006": return dbError("forbidden", "This connection is read-only, so the write was refused", {
+			...base,
+			details: base.details ?? message,
+			hint: base.hint ?? "The transaction is read-only, such as in a read-only support session; writes need a writable connection."
+		});
+		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);
+		case "PGRST116": return /multiple|more than one/i.test(raw.details ?? message) ? dbError("multiple_rows", message, base) : dbError("not_found", message, base);
+		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."
+		});
+		case "BS429":
+		case "PT429": {
+			const seconds = RETRY_AFTER.exec(raw.details ?? "")?.[1];
+			return dbError("rate_limited", message, {
+				...base,
+				...seconds ? { retryAfter: Number(seconds) } : {}
+			});
+		}
+		case "POSTGRES_POOL_BUSY":
+		case "POSTGRES_CONNECT_PAUSED": return dbError("network", message, {
+			...base,
+			...raw.retryAfterMs === void 0 ? {} : { retryAfter: Math.max(1, Math.ceil(raw.retryAfterMs / 1e3)) }
+		});
+		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, withMaxAffected as d, isCheck as i, matchDbError as l, dbError as n, isDbError as o, dbErrorOf as r, isForeignKey as s, MAX_AFFECTED_MARKER as t, statusOf as u };