better-supabase 0.5.0 → 0.6.0

package/dist/{resolve-C15TJq77.d.ts → resolve-KW8nCeL6.d.ts}

@@ -1,49 +1,12 @@
-import { _ as DbError } from "./executor-BunPOO-k.js";
-import { E as Logger, l as RefreshEvent } from "./events-aIO7vsIk.js";
-import { g as RequestContext } from "./plugin-o144f322.js";
-import { t as StandardSchemaV1 } from "./standard-J4YgMOLm.js";
+/// <reference lib="esnext.temporal" />
+import { b as DbError } from "./result-D7y2fT87.js";
+import { m as RequestContext } from "./plugin-FGY8UhYm.js";
+import { l as RefreshEvent } from "./events-DWDhx77e.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-CYsm7xpT.js";
 import { t as BetterSupabaseEnv } from "./index-CLg87OBW.js";
-import { CookieOptions } from "@supabase/ssr";
+import { a as CookieWrite, n as CookieOptions, r as CookieRecord, s as SessionEncoding } from "./session-ChiXDZdZ.js";
 import { JWTClaims, SupabaseEnv, UserClaims } from "@supabase/server";
-//#region src/auth/session.d.ts
-/** The session object auth-js persists (`sb-<ref>-auth-token`). */
-interface StoredSession {
-  readonly access_token: string;
-  readonly refresh_token: string;
-  readonly expires_at?: number;
-  readonly expires_in?: number;
-  readonly token_type?: string;
-  readonly user?: unknown;
-  readonly [key: string]: unknown;
-}
-interface CookieRecord {
-  readonly name: string;
-  readonly value: string;
-}
-interface CookieWrite {
-  readonly name: string;
-  readonly value: string;
-  readonly options: CookieOptions;
-}
-/** Headers that keep responses carrying session cookies out of shared caches. */
-declare const AUTH_CACHE_HEADERS: Readonly<Record<string, string>>;
-/** `sb-<first label of the hostname>-auth-token`, the supabase-js default. */
-declare function sessionCookieName(url: string): string;
-declare function parseCookies(header: string | null | undefined): CookieRecord[];
-declare function serializeCookie(write: CookieWrite): string;
-/**
- * Reads the session written by `@supabase/ssr` (plain or `base64-`, whole or
- * chunked). Mismatched chunks from a partial write read as no session.
- */
-declare function readSession(cookies: readonly CookieRecord[], name: string): StoredSession | null;
-/**
- * Cookie writes that store `session` (or clear it with `null`) exactly like
- * `@supabase/ssr`, and expire chunks the new value no longer uses.
- */
-declare function writeSession(existing: readonly CookieRecord[], name: string, session: StoredSession | null, options?: CookieOptions): CookieWrite[];
-/** Applies cookie writes to a cookie list, as the next request would see it. */
-declare function applyCookieWrites(cookies: readonly CookieRecord[], writes: readonly CookieWrite[]): CookieRecord[];
-//#endregion
 //#region src/auth/resolve.d.ts
 /**
  * Who is calling. `C` is the claims type from `betterSupabase.claims(schema)`; the
@@ -67,6 +30,19 @@ type AuthState<C = unknown, P = unknown> = {
 } | {
   readonly kind: "service";
   readonly keyName: string;
+} | {
+  readonly kind: "apiKey";
+  readonly keyId: string;
+  readonly name: string;
+  readonly organizationId?: string;
+  readonly userId?: string;
+  readonly scopes: readonly string[];
+  /** When the key was created. */
+  readonly createdAt?: Temporal.Instant;
+  /** The user who created the key, when the row records one. */
+  readonly createdBy?: string;
+  /** `sub` (the user, or the key for an organization key), `role: authenticated` and `api_key`. */
+  readonly claims: JWTClaims;
 } | {
   readonly kind: "anon";
   /** `expired`: the cookie session needs a refresh that was not allowed here (run the proxy). */
@@ -108,6 +84,7 @@ interface ResolveAuthOptions {
   readonly leeway?: number;
   /** Milliseconds before a refresh counts as a network failure. Defaults to 5000. */
   readonly refreshTimeoutMs?: number;
+  readonly checkSession?: boolean;
   /**
    * Accept `sb_secret_` keys (`apikey` header) as service callers: `true` for
    * any configured key, or the key names allowed (`['cron']`). Defaults to false.
@@ -118,6 +95,12 @@ interface ResolveAuthOptions {
   readonly cookie?: {
     readonly name?: string;
     readonly options?: CookieOptions;
+    /**
+     * The shape refreshed sessions are written in, `cookies.encode` in
+     * `@supabase/ssr`. Use the browser client's value. Defaults to
+     * `user-and-tokens`.
+     */
+    readonly encode?: SessionEncoding;
   };
   /**
    * Read the session cookie. Defaults to true. `false` suits endpoints only
@@ -164,6 +147,7 @@ interface AuthResolution<C = unknown, P = unknown> {
   readonly requestCookies: readonly CookieRecord[];
   /** Adds `cookies` and `headers` to a response. */
   apply(response: Response): Response;
+  readonly sessionEnded?: boolean;
 }
 /** The first `x-forwarded-for` hop, the client as your edge saw it. */
 declare function clientIp(request: Request): string | undefined;
@@ -179,4 +163,4 @@ declare function resolveAuth(request: Request, options: ResolveAuthOptions): Pro
 /** The repository context (`actor`, `claims`) for an auth state. */
 declare function authContext(auth: AuthState): RequestContext;
 //#endregion
-export { readSession as _, ResolveAuthOptions as a, writeSession as b, clientIp as c, CookieOptions as d, CookieRecord as f, parseCookies as g, applyCookieWrites as h, InvalidReason as i, resolveAuth as l, StoredSession as m, AuthResolver as n, ResolvedState as o, CookieWrite as p, AuthState as r, authContext as s, AuthResolution as t, AUTH_CACHE_HEADERS as u, serializeCookie as v, sessionCookieName as y };
+export { ResolveAuthOptions as a, clientIp as c, InvalidReason as i, resolveAuth as l, AuthResolver as n, ResolvedState as o, AuthState as r, authContext as s, AuthResolution as t };

package/dist/{resource-CRxxwkQq.js → resource-BsvzCMlX.js}

@@ -1,7 +1,7 @@
-import { n as dbError } from "./errors-DtwXa6b8.js";
-import { i as ok, n as err } from "./result-BKiliPY7.js";
-import { t as validate } from "./standard-D7r6dMUu.js";
-import { p as respond } from "./server-Csx2sRjg.js";
+import { n as dbError } from "./errors-B11Duf73.js";
+import { a as ok, r as err } from "./result-DzUbqgdW.js";
+import { n as validate } from "./standard-BK0cqJ7y.js";
+import { a as respond } from "./respond-BUgsXNgk.js";
 //#region src/server/resource.ts
 const INTEGER = /* @__PURE__ */ new Set([
 	"int2",

package/dist/{resource-D8iqWMr-.d.ts → resource-D6Uc7Sk7.d.ts}

@@ -1,8 +1,8 @@
-import { F as TableMeta, P as TableKey, _ as Insert, n as AnyFunctions, r as AnyModels, z as Update } from "./types-Dnf_wRDz.js";
-import { u as Result, w as ValidationIssue } from "./executor-BunPOO-k.js";
-import { t as BetterSupabase, xt as SelectArg } from "./define-Bp_BZa5h.js";
-import { i as RespondOptions } from "./respond-D2OQl62-.js";
-import { i as ResourceOperation } from "./index-C7f8cOBM.js";
+import { E as ValidationIssue, f as Result } from "./result-D7y2fT87.js";
+import { H as Update, L as TableKey, R as TableMeta, a as AnyModels, i as AnyFunctions, x as Insert } from "./types-6BdhkmZe.js";
+import { It as SelectArg, t as BetterSupabase } from "./define-CJJkkr1-.js";
+import { a as RespondOptions } from "./respond-DoBijysA.js";
+import { i as ResourceOperation } from "./index-Bxih3l0u.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/server/resource.d.ts
 /** What a resource needs from `defineListQuery`. */

package/dist/respond-BUgsXNgk.js

@@ -0,0 +1,91 @@
+import { n as dbError, o as isDbError, r as dbErrorOf } from "./errors-B11Duf73.js";
+import { s as toDbError } from "./result-DzUbqgdW.js";
+import { a as problemResponse } from "./problem-BreOl8b8.js";
+import { a as actorOf, o as delegationOf } from "./impersonation-DcqaTBHx.js";
+import { a as checkAal, t as isAnonymousUser } from "./view-BeFcRV6G.js";
+import { n as jsonResponse } from "./json-CEnpTHlZ.js";
+//#region src/server/respond.ts
+/**
+* The scopes a delegated user token lacks. Empty for the user's own session,
+* which a support or impersonated session counts as: only an `oauth-client`
+* actor is limited to what the user delegated.
+*/
+function missingScopes(auth, required) {
+	if (required.length === 0) return [];
+	const outcome = actorOf(auth.claims);
+	if (!outcome.ok || outcome.actor?.kind !== "oauth-client") return [];
+	const granted = new Set(delegationOf(auth.claims)?.scopes);
+	return required.filter((scope) => !granted.has(scope));
+}
+/** An API key's `*` scope grants every scope. */
+function missingKeyScopes(granted, required) {
+	if (granted.includes("*")) return [];
+	return required.filter((scope) => !granted.includes(scope));
+}
+/** `undefined` when `auth` may pass; otherwise the 401/403 error to send. */
+function guard(auth, allow = ["user"], aal = "aal1", scopes = []) {
+	if (auth.kind === "invalid") return auth.error;
+	const anonymous = auth.kind === "user" && isAnonymousUser(auth.claims);
+	if (anonymous ? allow.includes("anonymous") : allow.includes(auth.kind)) {
+		const denied = checkAal(auth, aal);
+		if (denied) return denied;
+		if (auth.kind !== "user" && auth.kind !== "apiKey") return void 0;
+		const missing = auth.kind === "apiKey" ? missingKeyScopes(auth.scopes, scopes) : missingScopes(auth, scopes);
+		return missing.length > 0 ? dbError("forbidden", `The token lacks the scope ${missing.join(" ")}`, {
+			code: "INSUFFICIENT_SCOPE",
+			scopes
+		}) : void 0;
+	}
+	if (anonymous) return dbError("forbidden", "Sign up to continue", { code: "ANONYMOUS_USER" });
+	return auth.kind === "anon" ? dbError("unauthorized", "Sign in to continue", { code: "MISSING_CREDENTIALS" }) : dbError("forbidden", `A ${auth.kind} caller is not allowed here`);
+}
+function isResult(value) {
+	return typeof value === "object" && value !== null && "ok" in value && "data" in value && "error" in value;
+}
+/**
+* Settles a handler's return value: `Result`s and `AsyncResult`s unwrap,
+* thrown `DbException`s (or errors whose `cause` is a `DbError`) become
+* errors, anything else is data. Other thrown
+* errors propagate.
+*/
+async function settle(run) {
+	try {
+		const value = await run();
+		if (!isResult(value)) return {
+			ok: true,
+			data: value
+		};
+		if (value.ok) return {
+			ok: true,
+			data: value.data
+		};
+		return {
+			ok: false,
+			error: isDbError(value.error) ? value.error : toDbError(value.error)
+		};
+	} catch (cause) {
+		const thrown = dbErrorOf(cause);
+		if (thrown) return {
+			ok: false,
+			error: thrown
+		};
+		throw cause;
+	}
+}
+/** A handler's value as a response: `Response` as is, data as JSON, errors as Problem Details. */
+async function respond(run, options = {}) {
+	const settled = await settle(run);
+	if (!settled.ok) return problemResponse(settled.error, options);
+	if (settled.data instanceof Response) return settled.data;
+	if (settled.data === void 0) return new Response(null, { status: 204 });
+	return jsonResponse(settled.data, { status: options.status ?? 200 });
+}
+/** Prefetching the JWKS would add a network call to every test that builds a server. */
+function defaultPrefetchJwks() {
+	return typeof process === "undefined" || process.env["NODE_ENV"] !== "test";
+}
+function defaultExpose() {
+	return typeof process !== "undefined" && process.env["NODE_ENV"] === "development";
+}
+//#endregion
+export { respond as a, isResult as i, defaultPrefetchJwks as n, settle as o, guard as r, defaultExpose as t };

package/dist/respond-DoBijysA.d.ts

@@ -0,0 +1,93 @@
+import { b as DbError } from "./result-D7y2fT87.js";
+import { r as AuthState } from "./resolve-KW8nCeL6.js";
+import { t as Aal } from "./mfa-Daak8ukG.js";
+//#region src/server/refresh.d.ts
+/** A router or browser prefetch, by its request headers. */
+declare function isPrefetch(request: Request): boolean;
+/**
+ * Whether a request should refresh an expired session cookie: page loads,
+ * client navigations (`rsc`, `x-sveltekit-*`, `_data` loaders), form posts
+ * and Server Actions. Prefetches, assets and `fetch` calls from scripts
+ * read the session as it is, so a burst of parallel requests never races
+ * on the single-use refresh token.
+ */
+declare function shouldRefresh(request: Request): boolean;
+/**
+ * Whether a request should ask the Auth server if the session still exists
+ * (`checkSession`): full page loads, and `paths` you list for client
+ * navigations. Never prefetches or mutations.
+ */
+declare function shouldCheckSession(request: Request, paths?: readonly string[]): boolean;
+/** When a session entry refreshes: always, never, on navigations, or a predicate. */
+type RefreshPolicy = boolean | "navigation" | ((request: Request) => boolean);
+/** `policy` for one request. */
+declare function refreshFor(policy: RefreshPolicy | undefined, request: Request): boolean | undefined;
+//#endregion
+//#region src/server/respond.d.ts
+type AuthKind = AuthState["kind"];
+/**
+ * An auth kind a guard lets through. `anonymous` admits users signed in with
+ * `signInAnonymously()` (`is_anonymous`); `anon` admits callers without a
+ * session only.
+ */
+type AllowedCaller = Exclude<AuthKind, "invalid"> | "anonymous";
+interface GuardOptions {
+  /**
+   * Callers allowed through. Defaults to `['user']`, which refuses anonymous
+   * sign-ins. Only `'anonymous'` admits them: `['anonymous']` alone admits
+   * anonymous sign-ins and refuses other users, and `'anon'` (no session)
+   * never admits them.
+   */
+  readonly allow?: readonly AllowedCaller[];
+  /**
+   * Assurance level user sessions need. `aal2` answers 403 with
+   * `required: 'aal2'` until the user verifies a second factor.
+   */
+  readonly aal?: Aal;
+  /**
+   * OAuth scopes a delegated token (an OAuth client or an `act` chain) or an
+   * API key needs. A missing one answers 403 with `error="insufficient_scope"`.
+   * The user's own session is not limited by scopes.
+   */
+  readonly scopes?: readonly string[];
+}
+/** Guard options for middleware and fetch handlers that resolve the caller themselves. */
+interface MiddlewareOptions extends GuardOptions {
+  /**
+   * Refresh an expired cookie session and send the new cookies. Only for
+   * routes browsers call with cookies; bearer tokens never refresh.
+   * `'navigation'` refreshes page loads and form posts only (`shouldRefresh`).
+   */
+  readonly refresh?: RefreshPolicy;
+}
+/** `undefined` when `auth` may pass; otherwise the 401/403 error to send. */
+declare function guard(auth: AuthState, allow?: GuardOptions["allow"], aal?: Aal, scopes?: readonly string[]): DbError | undefined;
+declare function isResult(value: unknown): value is {
+  ok: boolean;
+  data: unknown;
+  error: unknown;
+};
+type Settled = {
+  readonly ok: true;
+  readonly data: unknown;
+} | {
+  readonly ok: false;
+  readonly error: DbError;
+};
+/**
+ * Settles a handler's return value: `Result`s and `AsyncResult`s unwrap,
+ * thrown `DbException`s (or errors whose `cause` is a `DbError`) become
+ * errors, anything else is data. Other thrown
+ * errors propagate.
+ */
+declare function settle(run: () => unknown): Promise<Settled>;
+interface RespondOptions {
+  readonly instance?: string;
+  readonly expose?: boolean;
+  /** Status for data responses. Defaults to 200 (204 without data). */
+  readonly status?: number;
+}
+/** A handler's value as a response: `Response` as is, data as JSON, errors as Problem Details. */
+declare function respond(run: () => unknown, options?: RespondOptions): Promise<Response>;
+//#endregion
+export { RespondOptions as a, isResult as c, RefreshPolicy as d, isPrefetch as f, shouldRefresh as h, MiddlewareOptions as i, respond as l, shouldCheckSession as m, AuthKind as n, Settled as o, refreshFor as p, GuardOptions as r, guard as s, AllowedCaller as t, settle as u };

package/dist/result-D7y2fT87.d.ts

@@ -0,0 +1,282 @@
+//#region src/core/errors.d.ts
+/**
+ * Extra fields carried by each error kind. Plugins can add kinds through the
+ * `errors` extension point; apps that want the new kinds in the union can add
+ * them to this interface.
+ */
+interface DbErrorKinds {
+  not_found: Record<never, never>;
+  unauthorized: Record<never, never>;
+  /**
+   * `required`: the assurance level the route needs, when a second factor is
+   * missing. `scopes`: the OAuth scopes the route needs, when a delegated
+   * token lacks one (`INSUFFICIENT_SCOPE`).
+   */
+  forbidden: {
+    required?: "aal1" | "aal2";
+    scopes?: readonly string[];
+  };
+  conflict: {
+    constraint?: string;
+    columns?: readonly string[];
+  };
+  foreign_key: {
+    constraint?: string;
+    columns?: readonly string[];
+  };
+  check: {
+    constraint?: string;
+  };
+  not_null: {
+    column?: string;
+  };
+  exclusion: {
+    constraint?: string;
+  };
+  invalid_input: Record<never, never>;
+  /** A stored value the app type can't hold, e.g. `infinity` for a Temporal timestamp. */
+  invalid_value: {
+    column?: string;
+  };
+  raised: Record<never, never>;
+  timeout: Record<never, never>;
+  serialization: Record<never, never>;
+  network: Record<never, never>;
+  aborted: Record<never, never>;
+  invalid_request: Record<never, never>;
+  validation: {
+    issues: readonly ValidationIssue[];
+  };
+  multiple_rows: Record<never, never>;
+  stale: Record<never, never>;
+  /**
+   * An `updateMany` or `deleteMany` matched more rows than its `maxAffected`
+   * allows; nothing was written. `maxAffected`: the limit, when known.
+   */
+  max_affected: {
+    maxAffected?: number;
+  };
+  /** `retryAfter`: seconds until the window resets (the `Retry-After` header). */
+  rate_limited: {
+    retryAfter?: number;
+  };
+  /**
+   * A usage quota is used up (`consume_quota`, SQLSTATE `BSQ29`). `meter`:
+   * what was metered, `limit`: the quota, `retryAfter`: seconds until the
+   * period resets.
+   */
+  quota_exceeded: {
+    meter?: string;
+    limit?: number;
+    retryAfter?: number;
+  };
+  /** The executor or its dialect can't run this operation (an include on SQLite, say). */
+  unsupported: Record<never, never>;
+  unexpected: Record<never, never>;
+}
+type DbErrorKind = keyof DbErrorKinds;
+interface ValidationIssue {
+  readonly message: string;
+  readonly path?: readonly PropertyKey[];
+}
+interface DbErrorBase<K extends DbErrorKind> {
+  readonly kind: K;
+  readonly message: string;
+  /** SQLSTATE or PostgREST code (`23505`, `PGRST116`), when known. */
+  readonly code?: string;
+  /** Suggested HTTP status, used by the RFC 9457 mapping. */
+  readonly status: number;
+  readonly details?: string;
+  /** Postgres `HINT`. `raised` errors use it as an app-level error code. */
+  readonly hint?: string;
+  /** App-cased table key the operation ran against. */
+  readonly table?: string;
+}
+/**
+ * A database error as plain, serializable data. Safe to send across server
+ * action and RPC boundaries.
+ */
+type DbError = { [K in DbErrorKind]: DbErrorBase<K> & DbErrorKinds[K]; }[DbErrorKind];
+type DbErrorOf<K extends DbErrorKind> = Extract<DbError, {
+  kind: K;
+}>;
+declare function statusOf(kind: DbErrorKind): number;
+type ExtraOf<K extends DbErrorKind> = Record<never, never> extends DbErrorKinds[K] ? [extra?: DbErrorKinds[K] & Partial<Omit<DbErrorBase<K>, "kind">>] : [extra: DbErrorKinds[K] & Partial<Omit<DbErrorBase<K>, "kind">>];
+/** Creates a `DbError` with the default status for its kind. */
+declare function dbError<K extends DbErrorKind>(kind: K, message: string, ...[extra]: ExtraOf<K>): DbErrorOf<K>;
+declare function isDbError(value: unknown): value is DbError;
+/**
+ * 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')`.
+ */
+declare const isConflict: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"conflict"> & {
+  readonly constraint: C;
+};
+/** A CHECK violation, optionally for one constraint (`CheckConstraint`). */
+declare const isCheck: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"check"> & {
+  readonly constraint: C;
+};
+/** A foreign key violation, optionally for one constraint (`ForeignKeyConstraint`). */
+declare const isForeignKey: <C extends string = string>(error: unknown, constraint?: NoInfer<C>) => error is DbErrorOf<"foreign_key"> & {
+  readonly constraint: C;
+};
+/** Raw error shape shared by PostgREST responses and `pg` errors. */
+interface RawDbError {
+  readonly message?: string;
+  readonly code?: string;
+  readonly details?: string | null;
+  readonly hint?: string | null;
+  readonly constraint?: string;
+  readonly column?: string;
+  readonly table?: string;
+  readonly name?: string;
+}
+type ErrorMapper = (raw: RawDbError, fallback: DbError) => DbError | undefined;
+/**
+ * Maps a PostgREST or Postgres error to a `DbError`. Custom mappers run
+ * first; the first one that returns an error wins.
+ */
+declare function mapDbError(raw: RawDbError, mappers?: readonly ErrorMapper[]): DbError;
+//#endregion
+//#region src/core/result.d.ts
+/** Turns a `DbError` into the error `.orThrow()` throws; set with `betterSupabase.mapError()`. */
+type ThrowMapper = (error: DbError) => unknown;
+type Ok<T> = {
+  readonly ok: true;
+  readonly data: T;
+  readonly error: null;
+};
+type Err<E = DbError> = {
+  readonly ok: false;
+  readonly data: null;
+  readonly error: E;
+};
+type Result<T, E = DbError> = Ok<T> | Err<E>;
+declare function ok<T>(data: T): Ok<T>;
+declare function err<E = DbError>(error: E): Err<E>;
+/**
+ * A lazy-free `PromiseLike<Result<T>>` with helpers. `await` gives the
+ * `Result`; `.orThrow()` gives the data or throws a `DbException`.
+ */
+declare class AsyncResult<T> implements PromiseLike<Result<T>> {
+  #private;
+  constructor(promise: Promise<Result<T>>);
+  static from<T>(run: () => Promise<Result<T>>): AsyncResult<T>;
+  static ok<T>(data: T): AsyncResult<T>;
+  static err<T = never>(error: DbError): AsyncResult<T>;
+  then<R1 = Result<T>, R2 = never>(onfulfilled?: ((value: Result<T>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+  /**
+   * Resolves with the data, or rejects with a `DbException`. Pass `factory`
+   * to throw your own error instead, e.g. an HTTP error for your framework;
+   * without it, the mapper from `betterSupabase.mapError()` applies when one is set.
+   */
+  orThrow(factory?: (error: DbError) => unknown): Promise<T>;
+  /** Resolves with the data, or `fallback` when the result is an error. */
+  unwrapOr<F>(fallback: F): Promise<T | F>;
+  map<U>(fn: (data: T) => U): AsyncResult<U>;
+  mapError(fn: (error: DbError) => DbError): AsyncResult<T>;
+  andThen<U>(fn: (data: T) => PromiseLike<Result<U>>): AsyncResult<U>;
+}
+/** What `toBetterResult` returns: the `status`/`value`/`error` fields every better-result value has. */
+type BetterResultValue<T, E> = {
+  readonly status: "ok";
+  readonly value: T;
+} | {
+  readonly status: "error";
+  readonly error: E;
+};
+/** The part of better-result's `Result` namespace `toBetterResult` calls. */
+interface BetterResultApi<T, E> {
+  ok(value: NoInfer<T>): unknown;
+  err(error: NoInfer<E>): unknown;
+}
+/** The value type of a better-result `Result` type. */
+type BetterResultOk<R> = R extends {
+  readonly status: "ok";
+  readonly value: infer T;
+} ? T : never;
+/** The error type of a better-result `Result` type. */
+type BetterResultErr<R> = R extends {
+  readonly status: "error";
+  readonly error: infer E;
+} ? E : never;
+/**
+ * Builds a better-result value with the `Result` namespace you pass, so
+ * better-result stays your dependency. Errors go through `mapError`, or, for a
+ * result from a `db` of `betterSupabase.mapError(fn)`, through `fn` (typed `unknown`).
+ *
+ * The value is typed as better-result's `Result<T, E>` when the call has one
+ * as its expected type (an annotation or a function's return type) or as its
+ * type argument. That type is checked against the row type and `mapError`.
+ * Without one, it is a `BetterResultValue<T, E>`.
+ *
+ * ```ts
+ * import { Result } from 'better-result';
+ * const customer: Result<Customer, AppError> = toBetterResult(
+ *   await db.customers.findById(id),
+ *   Result,
+ *   toAppError,
+ * );
+ * ```
+ */
+declare function toBetterResult<R extends BetterResultValue<unknown, unknown> = never>(result: Result<BetterResultOk<R>>, api: BetterResultApi<BetterResultOk<R>, BetterResultErr<R>>, mapError: (error: DbError) => BetterResultErr<R>): R;
+declare function toBetterResult<R extends BetterResultValue<unknown, unknown> = never>(result: Result<BetterResultOk<R>> & (DbError extends BetterResultErr<R> ? unknown : never), api: BetterResultApi<BetterResultOk<R>, DbError>): R;
+declare function toBetterResult<R extends BetterResultValue<unknown, unknown> = never>(result: AsyncResult<BetterResultOk<R>>, api: BetterResultApi<BetterResultOk<R>, BetterResultErr<R>>, mapError: (error: DbError) => BetterResultErr<R>): Promise<R>;
+declare function toBetterResult<R extends BetterResultValue<unknown, unknown> = never>(result: AsyncResult<BetterResultOk<R>> & (unknown extends BetterResultErr<R> ? unknown : never), api: BetterResultApi<BetterResultOk<R>, unknown>): Promise<R>;
+declare function toBetterResult<T, E>(result: Result<T>, api: BetterResultApi<T, E>, mapError: (error: DbError) => E): BetterResultValue<T, E>;
+declare function toBetterResult<T>(result: Result<T>, api: BetterResultApi<T, DbError>): BetterResultValue<T, DbError>;
+declare function toBetterResult<T, E>(result: AsyncResult<T>, api: BetterResultApi<T, E>, mapError: (error: DbError) => E): Promise<BetterResultValue<T, E>>;
+declare function toBetterResult<T>(result: AsyncResult<T>, api: BetterResultApi<T, unknown>): Promise<BetterResultValue<T, unknown>>;
+/**
+ * An error class for one `DbError` kind. better-result's
+ * `class NotFound extends TaggedError("NotFound")<{ message: string; error: DbError }> {}`
+ * fits, as does any class whose constructor takes `{ message, error }`.
+ */
+type DbErrorClass<K extends DbErrorKind = DbErrorKind> = new (props: {
+  readonly message: string;
+  readonly error: DbErrorOf<K>;
+}) => unknown;
+/** Error classes by `DbError` kind; kinds left out use the fallback class. */
+type DbErrorClasses = { readonly [K in DbErrorKind]?: DbErrorClass<K>; };
+/** The error a `DbError` of kind `K` becomes. */
+type MappedDbError<M extends DbErrorClasses, F extends DbErrorClass, K extends DbErrorKind = DbErrorKind> = K extends keyof M ? M[K] extends (abstract new (...args: never[]) => infer I) ? I : F extends (abstract new (...args: never[]) => infer I) ? I : never : F extends (abstract new (...args: never[]) => infer I) ? I : never;
+/**
+ * Converts results with a fixed `Result` namespace and error mapping. Like
+ * `toBetterResult`, the value is typed as better-result's `Result<T, E>`
+ * when the call has one as its expected type, and `E` must accept every
+ * error the mapping returns.
+ */
+interface BetterResultErrors<M extends DbErrorClasses, F extends DbErrorClass> {
+  <R extends BetterResultValue<unknown, unknown> = never>(result: Result<BetterResultOk<R>> & (MappedDbError<M, F> extends BetterResultErr<R> ? unknown : never)): R;
+  <R extends BetterResultValue<unknown, unknown> = never>(result: AsyncResult<BetterResultOk<R>> & (MappedDbError<M, F> extends BetterResultErr<R> ? unknown : never)): Promise<R>;
+  <T>(result: Result<T>): BetterResultValue<T, MappedDbError<M, F>>;
+  <T>(result: AsyncResult<T>): Promise<BetterResultValue<T, MappedDbError<M, F>>>;
+  /** The error instance for one `DbError`, typed by its kind. */
+  map<E extends DbError>(error: E): MappedDbError<M, F, E["kind"]>;
+}
+/**
+ * A typed mapping from `DbError` kinds to error classes, usually
+ * better-result `TaggedError` classes, bound to better-result's `Result`
+ * namespace. Kinds without a class use `fallback`. Each instance gets the
+ * error's `message` and the `DbError` itself as `error`.
+ *
+ * ```ts
+ * import { Result, TaggedError } from 'better-result';
+ * class NotFound extends TaggedError('NotFound')<{ message: string; error: DbError }> {}
+ * class DbFailure extends TaggedError('DbFailure')<{ message: string; error: DbError }> {}
+ * const toResult = defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure);
+ * const customer: Result<Customer, NotFound | DbFailure> = await toResult(db.customers.findById(id));
+ * ```
+ */
+declare function defineBetterResultErrors<const M extends DbErrorClasses, F extends DbErrorClass>(api: BetterResultApi<unknown, unknown>, classes: M, fallback: F): BetterResultErrors<M, F>;
+/**
+ * Converts a better-result value back into a `Result`, by its `status`
+ * field, so it works across better-result versions. A `DbError`, or an
+ * error whose `cause` is one, is kept; others go through `mapError`
+ * (default `toDbError`).
+ */
+declare function fromBetterResult<T>(result: BetterResultValue<T, unknown>, mapError?: (error: unknown) => DbError): Result<T>;
+declare function toDbError(cause: unknown): DbError;
+//#endregion
+export { isDbError as A, DbErrorOf as C, dbError as D, ValidationIssue as E, mapDbError as M, statusOf as N, isCheck as O, DbErrorKinds as S, RawDbError as T, ok as _, BetterResultOk as a, DbError as b, DbErrorClasses as c, Ok as d, Result as f, fromBetterResult as g, err as h, BetterResultErrors as i, isForeignKey as j, isConflict as k, Err as l, defineBetterResultErrors as m, BetterResultApi as n, BetterResultValue as o, ThrowMapper as p, BetterResultErr as r, DbErrorClass as s, AsyncResult as t, MappedDbError as u, toBetterResult as v, ErrorMapper as w, DbErrorKind as x, toDbError as y };

package/dist/{result-BKiliPY7.js → result-DzUbqgdW.js}

@@ -1,4 +1,5 @@
-import { n as dbError, r as dbErrorOf, t as DbException } from "./errors-DtwXa6b8.js";
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError, r as dbErrorOf } from "./errors-B11Duf73.js";
 //#region src/core/result.ts
 const throwMappers = /* @__PURE__ */ new WeakMap();
 function inherit(from, next) {
@@ -81,6 +82,30 @@ function toBetterResult(result, api, mapError) {
 	return build(result, mapError);
 }
 /**
+* A typed mapping from `DbError` kinds to error classes, usually
+* better-result `TaggedError` classes, bound to better-result's `Result`
+* namespace. Kinds without a class use `fallback`. Each instance gets the
+* error's `message` and the `DbError` itself as `error`.
+*
+* ```ts
+* import { Result, TaggedError } from 'better-result';
+* class NotFound extends TaggedError('NotFound')<{ message: string; error: DbError }> {}
+* class DbFailure extends TaggedError('DbFailure')<{ message: string; error: DbError }> {}
+* const toResult = defineBetterResultErrors(Result, { not_found: NotFound }, DbFailure);
+* const customer: Result<Customer, NotFound | DbFailure> = await toResult(db.customers.findById(id));
+* ```
+*/
+function defineBetterResultErrors(api, classes, fallback) {
+	const map = (error) => {
+		return new (classes[error.kind] ?? fallback)({
+			message: error.message,
+			error
+		});
+	};
+	const convert = (result) => result instanceof AsyncResult ? toBetterResult(result, api, map) : toBetterResult(result, api, map);
+	return Object.assign(convert, { map });
+}
+/**
 * Converts a better-result value back into a `Result`, by its `status`
 * field, so it works across better-result versions. A `DbError`, or an
 * error whose `cause` is one, is kept; others go through `mapError`
@@ -100,4 +125,4 @@ function toDbError(cause) {
 	return dbError("unexpected", message);
 }
 //#endregion
-export { toBetterResult as a, ok as i, err as n, toDbError as o, fromBetterResult as r, withErrorMapper as s, AsyncResult as t };
+export { ok as a, withErrorMapper as c, fromBetterResult as i, defineBetterResultErrors as n, toBetterResult as o, err as r, toDbError as s, AsyncResult as t };

package/dist/run-state-CPo-1X2B.d.ts

@@ -0,0 +1,12 @@
+//#region src/core/run-state.d.ts
+/**
+ * Where a run is, in the words every block that records runs shares: ai-chat
+ * runs, ai-tasks runs and workflow runs. Each block uses the subset it needs.
+ */
+type RunState = "queued" | "running" | "waiting" | "cancel_requested" | "completed" | "failed" | "cancelled";
+/** The states a run ends in. */
+type FinalRunState = Extract<RunState, "completed" | "failed" | "cancelled">;
+/** The states a run ends in, in the order blocks list them. */
+declare const FINAL_RUN_STATES: readonly FinalRunState[];
+//#endregion
+export { FinalRunState as n, RunState as r, FINAL_RUN_STATES as t };