better-supabase 0.14.0 → 0.15.0

package/dist/resource-types-DnKiH4G2.d.ts

@@ -0,0 +1,157 @@
+import { D as ValidationIssue, f as Result } from "./result-DZeA5KS6.js";
+import { Ft as RequestContext, K as Insert, dt as TableMeta, ht as Update, it as Row, k as AnyModels, ut as TableKey } from "./types-DFdg_4yN.js";
+import { Wt as SelectArg } from "./define-DFBnQyYg.js";
+import { a as RespondOptions } from "./respond-Dn1_YhC1.js";
+import { D as ResourceOperation, k as TableVerb } from "./model-hwpvole9.js";
+import { a as ResourcePlan, i as ResourcePagination, n as ResourceActionSpec, r as ResourceDescription } from "./resource-D8pzB5Qf.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/server/resource-types.d.ts
+/** What a resource needs from `defineListQuery`. */
+interface ResourceList {
+  readonly table: string;
+  readonly pagination?: ResourcePagination;
+  readonly openapi: readonly unknown[];
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+  parse(input: never): {
+    readonly ok: true;
+    readonly value: unknown;
+  } | {
+    readonly ok: false;
+    readonly issues: readonly ValidationIssue[];
+  };
+  run(db: never, query: never, extra?: never): PromiseLike<unknown>;
+}
+/** What hooks and action handlers receive. */
+interface ResourceContext<DbT = unknown> {
+  /** The repositories, bound to the caller (RLS applies). */
+  readonly db: DbT;
+  readonly table: string;
+  /** The HTTP request, when the call came from one. */
+  readonly request: Request | undefined;
+  /** The verified request context: actor, tenant and claims. */
+  readonly context: RequestContext;
+}
+type HookResult<T> = Result<T> | PromiseLike<Result<T>>;
+/**
+ * The target of an item operation or action. `row` is set when a permission
+ * check fetched it.
+ */
+interface ResourceTarget<R> {
+  readonly id?: unknown;
+  readonly data?: unknown;
+  readonly query?: unknown;
+  readonly row?: R;
+}
+/** A list response: the page's rows plus its paging fields. */
+interface ResourcePage<R> {
+  readonly items: readonly R[];
+  readonly [field: string]: unknown;
+}
+/**
+ * Business logic around the repository. Every hook returns a `Result`; an error
+ * `Result` ends the request with that error, and a throw becomes an
+ * `unexpected` error. Hooks run after the authorizer.
+ */
+interface ResourceHooks<M extends AnyModels, T extends TableKey<M>, DbT = unknown> {
+  /** Runs before every operation and action; an error denies it. */
+  authorize?(ctx: ResourceContext<DbT>, operation: ResourceOperation | (string & {}), target: ResourceTarget<Row<M, T>>): HookResult<unknown>;
+  /** Returns the values to insert. */
+  beforeCreate?(ctx: ResourceContext<DbT>, data: Insert<M, T>): HookResult<Insert<M, T>>;
+  /** Returns the values to update. */
+  beforeUpdate?(ctx: ResourceContext<DbT>, data: Update<M, T>, target: ResourceTarget<Row<M, T>>): HookResult<Update<M, T>>;
+  beforeDelete?(ctx: ResourceContext<DbT>, target: ResourceTarget<Row<M, T>>): HookResult<unknown>;
+  /** Returns the response; describe a changed shape in `output.list`. */
+  afterList?(ctx: ResourceContext<DbT>, page: ResourcePage<Row<M, T>>): HookResult<unknown>;
+  afterGet?(ctx: ResourceContext<DbT>, row: Row<M, T>): HookResult<unknown>;
+  afterCreate?(ctx: ResourceContext<DbT>, row: Row<M, T>): HookResult<unknown>;
+  afterUpdate?(ctx: ResourceContext<DbT>, row: Row<M, T>): HookResult<unknown>;
+}
+/**
+ * What an action handler receives besides the context: values already
+ * validated.
+ */
+interface ActionArgs<I = unknown, Q = unknown> {
+  /** The parsed key, for item actions (`/{id}/send`). */
+  readonly id: unknown;
+  readonly data: I;
+  readonly query: Q;
+}
+/**
+ * A custom operation (`POST /<table>/{id}/send`). The handler returns a
+ * `Result`, a plain value or a `Response`; a throw becomes an `unexpected`
+ * error.
+ */
+interface ResourceAction<Ref = string, DbT = unknown> extends ResourceActionSpec<Ref> {
+  handler(ctx: ResourceContext<DbT>, args: ActionArgs): unknown;
+}
+type Parsed<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : undefined;
+interface ResourceRouteOptions<M extends AnyModels, T extends TableKey<M>, Ref = string, DbT = unknown> extends Omit<ResourceDescription<Ref>, "list" | "input" | "actions" | "operations" | "pagination" | "maxPageSize"> {
+  /** Defaults to every operation for tables, `list` and `get` for views. */
+  readonly operations?: readonly ResourceOperation[];
+  /** Filters, search and sorts for `list`, from `defineListQuery`. */
+  readonly list?: ResourceList;
+  /** Columns returned by every operation. */
+  readonly select?: SelectArg<M, T>;
+  /** Validates request bodies before they reach the repository. */
+  readonly input?: {
+    readonly create?: StandardSchemaV1<unknown, Insert<M, T>>;
+    readonly update?: StandardSchemaV1<unknown, Update<M, T>>;
+  };
+  /**
+   * Paging of the default list: `offset` (`page` and `size`) or `cursor`
+   * (`after` and `size`, keyset). A `list` query brings its own. Defaults to
+   * `cursor`, or `offset` for a table or view without a primary key.
+   */
+  readonly pagination?: ResourcePagination;
+  /** Largest page for the default list. Defaults to 200. */
+  readonly maxPageSize?: number;
+  readonly hooks?: ResourceHooks<M, T, DbT>;
+  readonly actions?: Readonly<Record<string, ResourceAction<Ref, DbT>>>;
+}
+interface ResourceInput {
+  /** Primary key value; strings are converted for integer keys. */
+  readonly id?: unknown;
+  /** Body of `create`, `update` and actions. */
+  readonly data?: unknown;
+  /** `list` and action parameters: URL params or typed values. */
+  readonly query?: URLSearchParams | Readonly<Record<string, unknown>>;
+  /** The HTTP request, passed on to hooks and actions. */
+  readonly request?: Request;
+}
+interface ResourceHandler<Ref = string> {
+  readonly table: string;
+  readonly meta: TableMeta;
+  readonly operations: readonly ResourceOperation[];
+  /**
+   * Name of the key parameter, or `undefined` for tables without a
+   * single-column key.
+   */
+  readonly keyParam: string | undefined;
+  readonly list: ResourceList | undefined;
+  readonly pagination: ResourcePagination;
+  readonly maxPageSize: number;
+  /** What the resource serves; `defineApi` documents the same plan. */
+  readonly plan: ResourcePlan<Ref>;
+  /** Runs one operation as whoever `db` is bound to. Resolves to a `Result`. */
+  execute(db: object, operation: ResourceOperation, input?: ResourceInput): Promise<Result<unknown>>;
+  /**
+   * Runs one contract verb (`page`, `count`, `aggregate`, `upsert`) with its
+   * arguments, as `POST /<table>/<verb>` does. Resolves to a `Result`.
+   */
+  verb(db: object, verb: TableVerb, input?: ResourceInput): Promise<Result<unknown>>;
+  /** Runs one action by name. Resolves to a `Result`. */
+  action(db: object, name: string, input?: ResourceInput): Promise<Result<unknown>>;
+  /**
+   * Serves a collection request (`id` undefined) or an item request. Actions
+   * are not routed.
+   */
+  handle(request: Request, db: object, id: string | undefined, options?: RespondOptions): Promise<Response>;
+  /**
+   * Serves the collection (`[]`), an item (`[id]`), a verb (`POST ["count"]`)
+   * or an action path (`[id, "send"]`), below the resource's own path. A string
+   * is split on `/` and decoded.
+   */
+  serve(request: Request, db: object, subpath: string | readonly string[], options?: RespondOptions): Promise<Response>;
+}
+//#endregion
+export { ResourceHandler as a, ResourceList as c, ResourceContext as i, ResourceRouteOptions as l, Parsed as n, ResourceHooks as o, ResourceAction as r, ResourceInput as s, ActionArgs as t };

package/dist/resources-B9cQxhjw.d.ts

@@ -0,0 +1,7 @@
+import { k as AnyModels, ut as TableKey } from "./types-DFdg_4yN.js";
+import { l as ResourceRouteOptions } from "./resource-types-DnKiH4G2.js";
+//#region src/server/resources.d.ts
+/** Resources by table name; `true` serves a table with the defaults. */
+type ResourceMap<M extends AnyModels, Ref = string, DbT = unknown> = { readonly [T in TableKey<M>]?: ResourceRouteOptions<M, T, Ref, DbT> | true; };
+//#endregion
+export { ResourceMap as t };

package/dist/resources-C02l_YBJ.js

@@ -0,0 +1,64 @@
+import { n as dbError } from "./errors-BVFgt8BZ.js";
+import { o as problemResponse } from "./problem-Bf0cJ7tk.js";
+import { n as actionFits, t as defineResource } from "./resource-DV2GC2dB.js";
+//#region src/server/resources.ts
+function split(path) {
+	return path.split("/").filter((segment) => segment !== "");
+}
+/** Whether a resource serves this path below it, with some method. */
+function serves(handler, segments) {
+	if (segments.length === 0) return true;
+	if (handler.plan.actions.some((action) => actionFits(action, segments))) return true;
+	return segments.length === 1 && (handler.keyParam !== void 0 || handler.plan.verbs.some((verb) => verb === segments[0]));
+}
+/**
+* Matches the still encoded path segments below one resource: the decoded
+* segments, or the 404 for a path it doesn't serve (400 for a malformed
+* segment). `instance` is the request path for the problem response.
+*/
+function matchResource(handler, raw, instance) {
+	let segments;
+	try {
+		segments = raw.map((segment) => decodeURIComponent(segment));
+	} catch {
+		return problemResponse(dbError("invalid_input", `Malformed id in ${instance}`), { instance });
+	}
+	if (!serves(handler, segments)) return problemResponse(dbError("not_found", `No route for ${instance}`), { instance });
+	return {
+		handler,
+		segments,
+		instance
+	};
+}
+/**
+* Routes `basePath` plus each resource's path (`/<table>` unless `path` is set)
+* to its handler. Shared by the edge and Next.js resource routers.
+*/
+function resourceRouter(betterSupabase, map, options = {}) {
+	const base = split(options.basePath ?? "");
+	const routes = [];
+	for (const [table, resource] of Object.entries(map)) {
+		if (!resource) continue;
+		const handler = defineResource(betterSupabase, table, resource === true ? {} : resource, options.authorizer);
+		routes.push({
+			prefix: split(handler.plan.description.path ?? `/${table}`),
+			handler
+		});
+	}
+	routes.sort((a, b) => b.prefix.length - a.prefix.length);
+	return {
+		handlers: routes.map((route) => route.handler),
+		match(request) {
+			const { pathname } = new URL(request.url);
+			const notFound = () => problemResponse(dbError("not_found", `No route for ${pathname}`), { instance: pathname });
+			const raw = split(pathname);
+			if (raw.length < base.length || !base.every((segment, index) => raw[index] === segment)) return notFound();
+			const rest = raw.slice(base.length);
+			const route = routes.find(({ prefix }) => prefix.length <= rest.length && prefix.every((segment, index) => rest[index] === segment));
+			if (!route) return notFound();
+			return matchResource(route.handler, rest.slice(route.prefix.length), pathname);
+		}
+	};
+}
+//#endregion
+export { resourceRouter as n, matchResource as t };

package/dist/respond-C3CcOZlA.js

@@ -0,0 +1,100 @@
+import { n as dbError, o as isDbError, r as dbErrorOf } from "./errors-BVFgt8BZ.js";
+import { s as toDbError } from "./result-ntFBW2p2.js";
+import { o as problemResponse } from "./problem-Bf0cJ7tk.js";
+import { i as delegationOf, n as actorOf } from "./actor-go7p9-CJ.js";
+import { f as checkAal, t as isAnonymousUser } from "./view-C8Ve14ja.js";
+import { n as jsonResponse } from "./json-DaByVJpw.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: an `oauth-client` actor,
+* and an `agent` on a token with a `scope`, are limited to what the user
+* delegated.
+*/
+function missingScopes(auth, required) {
+	if (required.length === 0) return [];
+	const outcome = actorOf(auth.claims);
+	if (!outcome.ok) return [];
+	const delegation = delegationOf(auth.claims);
+	const kind = outcome.actor?.kind;
+	if (kind !== "oauth-client" && !(kind === "agent" && delegation)) return [];
+	const granted = new Set(delegation?.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;
+		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-Dn1_YhC1.d.ts

@@ -0,0 +1,106 @@
+import { b as DbError } from "./result-DZeA5KS6.js";
+import { r as AuthState } from "./resolve-CXX6DHv3.js";
+import { t as Aal } from "./mfa-oIOYTpvc.js";
+//#region src/server/refresh.d.ts
+/**
+ * A router or browser prefetch, by its request headers: Next.js route and
+ * segment prefetches (`next-router-prefetch`, `next-router-segment-prefetch`),
+ * Next's middleware prefetch (`x-middleware-prefetch`), and browser and
+ * speculation-rules prefetches (`purpose`, `sec-purpose`, `x-moz`).
+ */
+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 };