better-supabase 0.13.0 → 0.15.0

package/dist/index-BxYOB1Oc.d.ts

@@ -0,0 +1,149 @@
+import { n as RouteGuardOptions } from "./refusal-CSntB_x8.js";
+import { t as Validated } from "./shared-CRRfQAKG.js";
+import { AnyEntry, Contributions } from "@supabase/middleware";
+import { IncomingMessage, ServerResponse } from "node:http";
+//#region src/node/http.d.ts
+interface WebRequestOptions {
+  /**
+   * Read the protocol and host from `x-forwarded-proto` and `x-forwarded-host`.
+   * Turn it on behind a proxy you control. Defaults to false.
+   */
+  readonly trustProxy?: boolean;
+  /** Stream the request body into the `Request`. Defaults to true. */
+  readonly body?: boolean;
+}
+/**
+ * A Node `IncomingMessage` as a Web `Request`. Express, Fastify and Koa pass
+ * theirs (`req`, `request.raw`, `ctx.req`). With `body: false` the stream stays
+ * unread, for middleware that runs before a body parser.
+ */
+declare function toWebRequest(req: IncomingMessage, options?: WebRequestOptions): Request;
+/** Writes a Web `Response` to a Node `ServerResponse`, streaming the body. */
+declare function sendWebResponse(res: ServerResponse, response: Response): Promise<void>;
+//#endregion
+//#region src/node/index.d.ts
+interface ToNodeOptions<Req = IncomingMessage> extends Omit<WebRequestOptions, "body"> {
+  /**
+   * The host's env object for `getEnv`; defaults to `process.env` through
+   * `getEnv`.
+   */
+  readonly env?: (req: Req) => unknown;
+}
+/**
+ * A `node:http` request listener running the entries around `handler`.
+ * Response-phase entries see the handler's response, so refreshed cookies and
+ * `withDbStats` totals reach the client.
+ *
+ * ```ts
+ * createServer(
+ *   toNodeHandler([withBetterSupabase(server)], (request, { db }) =>
+ *     db.notes.list(),
+ *   ),
+ * );
+ * ```
+ */
+declare function toNodeHandler<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, handler: (request: Request, contributions: Contributions<Entries>) => unknown, options?: ToNodeOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** The part of an Express response the middleware writes. */
+interface ExpressResponse extends ServerResponse {
+  /** Express's per-request locals; the contributions land here. */
+  locals: Record<string, unknown>;
+}
+/** Express (or Connect) middleware, typed structurally. */
+type ExpressMiddleware = (req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/** An Express error handler, typed structurally. */
+type ExpressErrorHandler = (error: unknown, req: IncomingMessage, res: ExpressResponse, next: (error?: unknown) => void) => void;
+/**
+ * Express middleware that puts every contribution on `res.locals`
+ * (`res.locals.db`, `res.locals.bsb`). Mount it before the routes.
+ *
+ * ```ts
+ * app.use(toExpress([withBetterSupabase(server)]));
+ * app.get("/notes", async (req, res) =>
+ *   res.json(await res.locals.db.notes.list().orThrow()),
+ * );
+ * ```
+ */
+declare function toExpress<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions): ExpressMiddleware;
+/**
+ * Express route middleware that refuses callers outside `options`: Problem
+ * Details, or a redirect to `signIn` or `mfa`. Runs after `toExpress`.
+ *
+ * ```ts
+ * app.get("/admin", guard({ roles: ["admin"] }), handler);
+ * ```
+ */
+declare function guard(options?: RouteGuardOptions): ExpressMiddleware;
+/**
+ * An Express error handler that answers thrown `DbException`s (from
+ * `.orThrow()`) with Problem Details and passes every other error on. Register
+ * it after the routes.
+ */
+declare function problemErrorHandler(options?: {
+  readonly expose?: boolean;
+}): ExpressErrorHandler;
+/** The part of a Fastify request the hook reads and writes. */
+interface FastifyRequestLike {
+  readonly raw: IncomingMessage;
+  /** The contributions land here: `request.locals.db`. */
+  locals?: Record<string, unknown>;
+}
+/** The part of a Fastify reply the hook writes. */
+interface FastifyReplyLike {
+  readonly raw: ServerResponse;
+  readonly sent: boolean;
+  code(status: number): FastifyReplyLike;
+  header(name: string, value: string | readonly string[]): FastifyReplyLike;
+  getHeader(name: string): number | string | string[] | undefined;
+  send(payload?: unknown): FastifyReplyLike;
+}
+/** A Fastify `onRequest` or `preHandler` hook, typed structurally. */
+type FastifyHook = (request: FastifyRequestLike, reply: FastifyReplyLike) => Promise<void>;
+/**
+ * A Fastify `onRequest` hook that puts every contribution on `request.locals`.
+ * Declare `locals` with `app.decorateRequest('locals', null)`.
+ *
+ * ```ts
+ * app.decorateRequest("locals", null);
+ * app.addHook("onRequest", toFastify([withBetterSupabase(server)]));
+ * app.get("/notes", (request) => request.locals.db.notes.list().orThrow());
+ * ```
+ */
+declare function toFastify<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<FastifyRequestLike>): FastifyHook;
+/**
+ * A Fastify `preHandler` hook that refuses callers outside `options`. Runs
+ * after `toFastify`.
+ */
+declare function fastifyGuard(options?: RouteGuardOptions): FastifyHook;
+/** The part of a Koa context the middleware reads and writes. */
+interface KoaContextLike {
+  readonly req: IncomingMessage;
+  readonly res: ServerResponse;
+  /** Koa's per-request state; the contributions land here. */
+  state: Record<string, unknown>;
+  status: number;
+  body: unknown;
+  set(name: string, value: string | readonly string[]): void;
+  get response(): {
+    get(name: string): string | string[] | undefined;
+  };
+}
+/** Koa middleware, typed structurally. */
+type KoaMiddleware = (ctx: KoaContextLike, next: () => Promise<unknown>) => Promise<void>;
+/**
+ * Koa middleware that puts every contribution on `ctx.state`, then awaits the
+ * rest of the chain. Thrown `DbException`s become Problem Details.
+ *
+ * ```ts
+ * app.use(toKoa([withBetterSupabase(server)]));
+ * app.use(async (ctx) => {
+ *   ctx.body = await ctx.state.db.notes.list().orThrow();
+ * });
+ * ```
+ */
+declare function toKoa<const Entries extends readonly AnyEntry[]>(entries: Entries & Validated<Entries>, options?: ToNodeOptions<KoaContextLike> & {
+  readonly expose?: boolean;
+}): KoaMiddleware;
+/** Koa middleware that refuses callers outside `options`. Runs after `toKoa`. */
+declare function koaGuard(options?: RouteGuardOptions): KoaMiddleware;
+//#endregion
+export { toNodeHandler as _, FastifyReplyLike as a, toWebRequest as b, KoaMiddleware as c, guard as d, koaGuard as f, toKoa as g, toFastify as h, FastifyHook as i, ToNodeOptions as l, toExpress as m, ExpressMiddleware as n, FastifyRequestLike as o, problemErrorHandler as p, ExpressResponse as r, KoaContextLike as s, ExpressErrorHandler as t, fastifyGuard as u, WebRequestOptions as v, sendWebResponse as y };

package/dist/index-C-qpk8EQ.d.ts

@@ -0,0 +1,262 @@
+import { $r as PresetCatalog, Nn as PresetSpec, Un as PresetName, _t as presetConfig, ar as AppColumnConfig, mr as AppTableConfig, ni as PresetGlueItem, si as Preset, sr as AppColumnType, xt as ResolvedPreset, yr as AppTablesConfig } from "./context-CEuTKrkz.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/preset/catalog.generated.d.ts
+declare const PRESET_CATALOG: PresetCatalog;
+//#endregion
+//#region src/config/app-defaults.d.ts
+/**
+ * Why `value` can't be the default of `column`, or `undefined` when it can: it
+ * must be on the `isAppDefault` allowlist, one of the column's `options`, and
+ * inside its bounds (`min`, `max`, or those of its format).
+ */
+declare function appDefaultError(column: Pick<AppColumnConfig, "type" | "options" | "min" | "max" | "format">, value: string): string | undefined;
+/** Whether `value` is a default `type` accepts; see `AppColumnConfig.default`. */
+declare function isAppDefault(type: AppColumnType, value: string): boolean;
+//#endregion
+//#region src/preset/design.d.ts
+/**
+ * A design from the `/create` canvas (ADR 0040): the preset (its name, or its
+ * conventions and blocks), tables the app owns, extra columns on block tables,
+ * and where each table sits on the canvas. It travels in the `design=`
+ * parameter of a `/create` URL, or as a design file.
+ */
+interface CreateDesign {
+  /** A preset name, or a preset object of conventions and blocks. */
+  readonly preset?: PresetName | PresetSpec;
+  /** `config.appTables`. */
+  readonly appTables?: Readonly<Record<string, AppTableConfig>>;
+  /**
+   * `blocks.<module>.options.extraColumns`: column name to SQL type, per
+   * module.
+   */
+  readonly extraColumns?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /** Canvas positions by `schema.table`, as `[x, y]`; the config ignores them. */
+  readonly positions?: Readonly<Record<string, readonly [number, number]>>;
+}
+/**
+ * The newest format of the design JSON, in its `version` key (ADR 0042). A code
+ * carries the lowest format that reads it, and none for format 0, so a design
+ * without format 1 keys still opens in an older release. Format 1 adds column
+ * `format`, `options`, `min`, `max`, `comment` and `identity`, and table `id`,
+ * `unique`, `indexes` and `comment`. Format 2 adds table `subject` (ADR 0043).
+ * Format 3 adds table `rollups` and `lookups` (ADR 0044). Format 4 adds table
+ * `events` (ADR 0048) and subject `versions`. Format 5 adds column `access`
+ * (ADR 0051). Format 6 adds column `encrypted` and table `auditReads` (ADR
+ * 0087). Format 7 adds `preset`, which replaces the 0.14 preset codes. Format 8
+ * adds the preset's `instances`.
+ */
+declare const DESIGN_FORMAT = 8;
+/** The lowest design format that reads `design`. */
+declare function designFormat(design: CreateDesign): number;
+/** The longest design code, so a `/create` URL stays under common limits. */
+declare const MAX_DESIGN_CODE_LENGTH = 6e3;
+/** The name Create gives the design file it downloads. */
+declare const DESIGN_FILE = "better-supabase.design.json";
+/**
+ * Why a design, a design code or a design file was rejected. The codes are
+ * stable; the messages may change.
+ */
+type DesignErrorCode = "invalid_design" | "unknown_key" | "unsupported_format" | "too_large" | "unknown_block" | "no_extra_columns" | "block_not_installed" | "invalid_name" | "invalid_type" | "invalid_position" | "invalid_app_table" | "invalid_code" | "too_long" | "invalid_file" | "invalid_preset";
+/** One problem with a design, as `safeParseDesign` reports it. */
+interface DesignParseIssue {
+  readonly code: DesignErrorCode;
+  /**
+   * A JSON Pointer (RFC 6901) to the key at fault in the value that was read,
+   * such as `/appTables/tasks/columns/title`. `""` is the value itself. When
+   * the key is missing, it points to the nearest parent.
+   */
+  readonly path: string;
+  readonly message: string;
+}
+/**
+ * What `parseDesign`, `decodeDesign`, `designFileSource` and `readDesignFile`
+ * throw.
+ */
+declare class DesignParseError extends TypeError implements DesignParseIssue {
+  readonly code: DesignErrorCode;
+  readonly path: string;
+  constructor(code: DesignErrorCode, path: string, message: string, options?: ErrorOptions);
+  /** The issue as a plain, serializable object. */
+  toJSON(): DesignParseIssue;
+}
+/**
+ * What `encodeDesign` throws when a valid design is too long for a URL, so a
+ * caller can offer the config download instead of a fix.
+ */
+declare class DesignTooLongError extends DesignParseError {
+  /** The length the code would have. */
+  readonly length: number;
+  constructor(length: number);
+}
+/** Whether `value` has the shape of a design code. It may still fail to decode. */
+declare function isDesignCode(value: string): boolean;
+/**
+ * Checks a design object, such as one from storage or a request body, and drops
+ * its empty parts. It runs the same checks as `decodeDesign`, without the code.
+ * Throws a `DesignParseError` naming the first problem; `safeParseDesign`
+ * returns it instead.
+ */
+declare function parseDesign(value: unknown): CreateDesign;
+/** What `safeParseDesign` and `safeDesignFileSource` return. */
+type DesignParseResult<T> = ({
+  readonly ok: true;
+} & T) | {
+  readonly ok: false;
+  readonly issues: readonly DesignParseIssue[];
+};
+/**
+ * `parseDesign` without the throw: the design, or the issue that stopped it,
+ * with a stable `code` and a JSON Pointer `path`.
+ */
+declare function safeParseDesign(value: unknown): DesignParseResult<{
+  readonly design: CreateDesign;
+}>;
+/**
+ * A Standard Schema (v1) for a design, so a form library, a router or an AI SDK
+ * tool can validate one with the same rules as `parseDesign`. The output drops
+ * the empty parts; each issue's `path` lists the keys of its JSON Pointer.
+ * `schemas/design-v1.json` is the JSON Schema of its shape.
+ */
+declare const designSchema: StandardSchemaV1<unknown, CreateDesign>;
+/**
+ * The design as a code for the `&design=` parameter: `0`, then its JSON (with
+ * `version` set to `designFormat` when it is above 0) compressed with
+ * deflate-raw, in base64url. An empty design is `""`. Throws a
+ * `DesignParseError` when the design is invalid, and a `DesignTooLongError`
+ * when the code would be longer than `MAX_DESIGN_CODE_LENGTH`.
+ */
+declare function encodeDesign(design: CreateDesign): Promise<string>;
+/** Reads a design code. Throws a `DesignParseError` when it isn't a valid one. */
+declare function decodeDesign(code: string): Promise<CreateDesign>;
+/**
+ * The design in a `/create` URL's `design=` parameter, or in a bare design
+ * code; `undefined` when `input` has neither.
+ */
+declare function designOf(input: string): Promise<CreateDesign | undefined>;
+/**
+ * The preset and design a preset name, a `/create` URL or a design code holds.
+ * The design's own `preset` comes first, then a `preset=<name>` parameter, then
+ * the default preset. A 0.14 preset code throws, naming the codemod.
+ */
+declare function presetAndDesignOf(input: string): Promise<{
+  readonly preset: Preset;
+  readonly design: CreateDesign | undefined;
+}>;
+/**
+ * The config keys a preset with a design sets: `presetConfig`, with each
+ * block's `options.extraColumns` and `appTables`. Throws a `DesignParseError`
+ * when the design adds columns to a block the preset doesn't install.
+ */
+declare function designConfig(resolved: ResolvedPreset, design: CreateDesign): ReturnType<typeof presetConfig> & {
+  readonly appTables?: AppTablesConfig;
+};
+/**
+ * The `/create` URL that reopens a preset and design: `?preset=<name>` for a
+ * named preset with no design, otherwise `?design=` with the preset inside.
+ * Throws a `DesignTooLongError` when the design is too long for a URL; write a
+ * design file (`designFileSource`) instead.
+ */
+declare function createUrl(resolved: ResolvedPreset, design?: CreateDesign): Promise<string>;
+/**
+ * `better-supabase.config.ts` for a preset and an optional design: every block
+ * with its reason, the conventions that differ from the defaults and the app
+ * tables, under a comment with the `/create` URL that reopens the canvas.
+ */
+declare function presetConfigSource(resolved: ResolvedPreset, design?: CreateDesign): Promise<string>;
+/** The command that starts a project from the preset and design. */
+declare function presetInstallCommand(resolved: ResolvedPreset, design?: CreateDesign): Promise<string>;
+/** The command that applies the preset and design to an existing project. */
+declare function presetApplyCommand(resolved: ResolvedPreset, design?: CreateDesign): Promise<string>;
+/**
+ * A design file: the design with its `preset` (ADR 0058), for a design too long
+ * for a URL. `init --preset` and `add --preset` read it from a path.
+ */
+type DesignFile = CreateDesign & {
+  readonly preset: PresetName | PresetSpec;
+  /** `designFormat`, when it is above 0. */
+  readonly version?: number;
+};
+/**
+ * The design file for a preset and design, as JSON text. Throws a
+ * `DesignParseError` when the design is invalid; `safeDesignFileSource` returns
+ * it instead. It has no length limit.
+ */
+declare function designFileSource(resolved: ResolvedPreset, design: CreateDesign): string;
+/**
+ * `designFileSource` without the throw: the file text, or the issue that
+ * stopped it. Each `path` points into the design.
+ */
+declare function safeDesignFileSource(resolved: ResolvedPreset, design: CreateDesign): DesignParseResult<{
+  readonly source: string;
+}>;
+/**
+ * Reads a design file's text into its preset and the rest of the design. Throws
+ * a `DesignParseError` naming the first problem: text that isn't JSON, a
+ * missing or invalid preset, a 0.14 file, or an invalid design.
+ */
+declare function readDesignFile(text: string): {
+  readonly preset: Preset;
+  readonly design: CreateDesign;
+};
+//#endregion
+//#region src/preset/design-diff.d.ts
+/** What changed between two sets of app tables. */
+type DesignChangeKind = "table.added" | "table.dropped" | "table.renamed" | "table.id" | "table.scope" | "table.unique" | "table.columns" | "table.changed" | "table.computed" | "table.events" | "table.versions" | "column.added" | "column.dropped" | "column.renamed" | "column.type" | "column.required" | "column.unique" | "column.options" | "column.bounds" | "column.format" | "column.reference" | "column.access" | "column.encrypted" | "column.changed";
+interface DesignChange {
+  readonly kind: DesignChangeKind;
+  readonly table: string;
+  readonly column?: string;
+  /** The old name of a renamed table or column, or the old type. */
+  readonly from?: string;
+  /** The new type of a type change. */
+  readonly to?: string;
+  /**
+   * True when existing rows or app code can break: a dropped or renamed table
+   * or column, a type change, a column made required without a default, a new
+   * or tighter constraint (unique, options, bounds, format, a reference
+   * target), tighter column access, encryption turned on or off, a new scope,
+   * or removed generated columns.
+   */
+  readonly breaking: boolean;
+  readonly summary: string;
+  /** The expand-and-contract steps that make a breaking change safe. */
+  readonly steps: readonly string[];
+}
+interface DiffOptions {
+  /**
+   * Leave out tables that `after` doesn't have, as `apply` does: it writes the
+   * tables of a design and keeps the others.
+   */
+  readonly keepMissing?: boolean;
+}
+/**
+ * What changes from `before` to `after`: each added, dropped, renamed or
+ * changed table and column, with the breaking ones marked and their
+ * expand-and-contract steps. A rename is a dropped name and an added one with
+ * the same definition.
+ */
+declare function diffAppTables(before: AppTablesConfig, after: AppTablesConfig, options?: DiffOptions): readonly DesignChange[];
+/** `diffAppTables` over the app tables of two `/create` designs. */
+declare function diffDesigns(before: CreateDesign, after: CreateDesign): readonly DesignChange[];
+//#endregion
+//#region src/preset/render.d.ts
+/** The comment a config with the provider access model gets above `blocks`. */
+declare const PROVIDER_COMMENT: readonly string[];
+/**
+ * `lib/blocks.ts`: the blocks with a TypeScript client, wired with
+ * `defineBlocks` over the Data API as the caller. Each block's schema (the API
+ * schema when `sql.api` is set) and shared options come from `blockConfig`,
+ * which `better-supabase gen` writes to `blocks.generated.ts`;
+ * `blockConfigImport` is its import path.
+ */
+declare function presetBlocksSource(resolved: ResolvedPreset, blockConfigImport?: string, catalog?: PresetCatalog): string;
+/**
+ * The registry glue for the preset's framework and platforms: each item whose
+ * blocks are all installed, except bundles and items that write
+ * `lib/blocks.ts`, which the preset writes itself.
+ */
+declare function presetGlue(resolved: ResolvedPreset, catalog?: PresetCatalog): readonly PresetGlueItem[];
+/** The shadcn command that copies glue items into the app. */
+declare function glueCommand(items: readonly PresetGlueItem[]): string;
+//#endregion
+export { presetAndDesignOf as A, designFileSource as C, encodeDesign as D, designSchema as E, safeDesignFileSource as F, safeParseDesign as I, appDefaultError as L, presetConfigSource as M, presetInstallCommand as N, isDesignCode as O, readDesignFile as P, isAppDefault as R, designConfig as S, designOf as T, DesignParseResult as _, DesignChange as a, createUrl as b, diffAppTables as c, DESIGN_FILE as d, DESIGN_FORMAT as f, DesignParseIssue as g, DesignParseError as h, presetGlue as i, presetApplyCommand as j, parseDesign as k, diffDesigns as l, DesignFile as m, glueCommand as n, DesignChangeKind as o, DesignErrorCode as p, presetBlocksSource as r, DiffOptions as s, PROVIDER_COMMENT as t, CreateDesign as u, DesignTooLongError as v, designFormat as w, decodeDesign as x, MAX_DESIGN_CODE_LENGTH as y, PRESET_CATALOG as z };