better-supabase 0.14.0 → 0.15.0

package/dist/api-DxAPqMrE.d.ts

@@ -0,0 +1,495 @@
+import { St as AnyPlugin, d as MutationIntent, ot as SchemaMeta } from "./types-DFdg_4yN.js";
+import { bt as EventMap } from "./events-vcqenSYU.js";
+import { o as Authorizer } from "./authorizer-B6X09otb.js";
+import { f as DbBlockSource } from "./define-DFBnQyYg.js";
+import { n as CloudEventOptions } from "./cloud-event-CzZTJkXv.js";
+import { t as RealtimeStatus } from "./realtime-status-BhNkb-Ow.js";
+import { C as ModelWebhook, E as OperationSource, O as SecurityRequirement, S as ModelTag, a as JsonSchema, b as ModelServer, d as ModelInfo, f as ModelMessage, i as JsonObject, m as ModelOperation, n as DataApiOperation, p as ModelMessageTrait, r as HttpMethod, s as ModelChannel, t as ApiModel, v as ModelSecurityProfileRequirement, w as ModelWorkflow, y as ModelSecurityScheme } from "./model-hwpvole9.js";
+import { a as ResourcePlan, o as StandardLike, r as ResourceDescription, t as ErrorResponse } from "./resource-D8pzB5Qf.js";
+import { t as SPEC_PINS } from "./spec-pins-DIx95afw.js";
+import { c as SpecDiagnostic, i as DocumentOf, l as VersionOf, s as RenderedOf, t as AnyDocumentFormat } from "./format-u-65igKI.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/openapi/types.d.ts
+type Json = Record<string, unknown>;
+/**
+ * The OpenAPI versions `openapiFormat` renders. `3.3-preview` follows the
+ * v3.3-dev branch.
+ */
+type OpenApiVersion = "3.0" | "3.1" | "3.2" | "3.3-preview";
+/** The `openapi` field `3.3-preview` emits, as in the v3.3-dev branch. */
+declare const OPENAPI_33_PREVIEW_VERSION = "3.3.0";
+interface OpenApiInfo {
+  readonly title: string;
+  readonly version: string;
+  /** OpenAPI 3.1 and later. */
+  readonly summary?: string;
+  readonly description?: string;
+  readonly termsOfService?: string;
+  readonly contact?: {
+    readonly name?: string;
+    readonly url?: string;
+    readonly email?: string;
+  };
+  readonly license?: {
+    readonly name: string;
+    /** OpenAPI 3.1 and later. */
+    readonly identifier?: string;
+    readonly url?: string;
+  };
+}
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+type OpenApiComponents = {
+  readonly schemas: Readonly<Record<string, Json>>;
+  readonly responses: Readonly<Record<string, Json>>;
+  readonly securitySchemes: Readonly<Record<string, Json>>;
+};
+interface OpenApiDocumentBase {
+  readonly info: OpenApiInfo;
+  readonly servers?: readonly Json[];
+  readonly tags: readonly Json[];
+  /** Path templates to Path Item objects. */
+  readonly paths: Readonly<Record<string, Json>>;
+  readonly components: OpenApiComponents;
+  readonly security: readonly OpenApiSecurityRequirement[];
+  readonly [extension: `x-${string}`]: unknown;
+}
+/** OpenAPI 3.0 (legacy): schemas use `nullable` and `example`, no webhooks. */
+interface OpenApi30Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi30;
+}
+/** OpenAPI 3.1: 3.2 fields travel as the registered `x-oai-*` extensions. */
+interface OpenApi31Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi31;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+}
+/**
+ * OpenAPI 3.2: native `$self`, nested tags, `itemSchema`, `oauth2MetadataUrl`
+ * and `query`.
+ */
+interface OpenApi32Document extends OpenApiDocumentBase {
+  readonly openapi: typeof SPEC_PINS.openapi32;
+  readonly $self?: string;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+}
+/**
+ * The 3.3 draft: 3.2 plus Path Item `security` and the Security Profiles
+ * proposal.
+ */
+interface OpenApi33PreviewDocument extends OpenApiDocumentBase {
+  readonly openapi: typeof OPENAPI_33_PREVIEW_VERSION;
+  readonly $self?: string;
+  readonly jsonSchemaDialect: string;
+  readonly webhooks?: Readonly<Record<string, Json>>;
+  readonly components: OpenApiComponents & {
+    readonly securityProfileRequirements?: Readonly<Record<string, Json>>;
+  };
+}
+interface OpenApiDocuments {
+  readonly "3.0": OpenApi30Document;
+  readonly "3.1": OpenApi31Document;
+  readonly "3.2": OpenApi32Document;
+  readonly "3.3-preview": OpenApi33PreviewDocument;
+}
+/** An OpenAPI document of one version; 3.1 by default. */
+type OpenApiDocument<V extends OpenApiVersion = "3.1"> = OpenApiDocuments[V];
+type AnyOpenApiDocument = OpenApiDocuments[OpenApiVersion];
+/** What an OpenAPI `transform` receives, discriminated by `version`. */
+type RenderedOpenApi = { readonly [V in OpenApiVersion]: {
+  readonly format: "openapi";
+  readonly version: V;
+  readonly document: OpenApiDocuments[V];
+}; }[OpenApiVersion];
+//#endregion
+//#region src/spec/presets.d.ts
+/** JSON Schema for RFC 9457 Problem Details as better-supabase sends them. */
+declare const PROBLEM_SCHEMA: Record<string, unknown>;
+/** The default error responses: today's Problem Details answers, 400 to 422. */
+declare const DEFAULT_ERRORS: readonly ErrorResponse[];
+/** A security scheme of your own, with the scopes its requirement asks for. */
+interface CustomSecurity {
+  /** The component name of the scheme. */
+  readonly name: string;
+  readonly scheme: ModelSecurityScheme;
+  readonly scopes?: readonly string[];
+}
+/**
+ * `bearer`: a Supabase access token (`supabaseJwt`). `oauth2`: the Supabase
+ * OAuth 2.1 server (`supabaseOAuth`, needs `supabaseUrl`). `apiKey`: the
+ * project's publishable key in the `apikey` header (`supabaseApiKey`). Each
+ * preset is one alternative requirement.
+ */
+type SecurityPreset = "bearer" | "oauth2" | "apiKey" | CustomSecurity;
+//#endregion
+//#region src/spec/data-api.d.ts
+/** Which tables and functions the Data API (PostgREST) section documents. */
+interface DataApiOptions {
+  /** Tables and views by app key, or `true` for all of them. */
+  readonly tables?: true | readonly string[];
+  /** Functions by key, or `true` for all of them, as `POST /rest/v1/rpc/<name>`. */
+  readonly functions?: true | readonly string[];
+  /**
+   * The operations per table, by app key. Defaults to all four for a table and
+   * to the ones its columns allow for a view.
+   */
+  readonly operations?: Readonly<Record<string, readonly DataApiOperation[]>>;
+  /** The tag of every Data API operation. Defaults to `Data API`. */
+  readonly tag?: string;
+}
+//#endregion
+//#region src/spec/events.d.ts
+/** A schema for a block event's data, checked against the block's event map. */
+type BlockEventSchema<T> = StandardSchemaV1<unknown, T>;
+/**
+ * Data schemas for block events, by event type, typed by an event map such as
+ * `EventMapOf<typeof messagingEvents>`. `true` documents the event with an open
+ * payload. A block can export its own map of this type.
+ */
+type BlockEventSchemas<M extends EventMap = EventMap> = { readonly [K in keyof M & string]?: true | BlockEventSchema<M[K]>; };
+/**
+ * A Realtime broadcast topic. A `defineTopic()` result fits as it is, with its
+ * event and presence schemas, `send` and `permission`; `topicsFrom()` collects
+ * them from a module.
+ */
+interface TopicInput<Ref = string> {
+  readonly template: string;
+  readonly name?: string;
+  readonly private?: boolean;
+  readonly presence?: boolean;
+  /** The schema of each tracked presence state; open when unset. */
+  readonly presenceSchema?: StandardLike | undefined;
+  /** Payload schema per broadcast event; `true` for an open payload. */
+  readonly events?: Readonly<Record<string, StandardLike | true>>;
+  /**
+   * Clients may broadcast on the topic, not only receive. Only `true` counts,
+   * so a `defineTopic()` result's `send` method is ignored.
+   */
+  readonly send?: boolean | ((...args: never[]) => unknown);
+  /** The same as `send: true`; what a `defineTopic()` result carries. */
+  readonly clientSend?: boolean;
+  readonly permission?: Ref | undefined;
+  /** Supabase's status for the topic's features. Defaults from `private`. */
+  readonly status?: RealtimeStatus;
+  readonly summary?: string;
+  readonly description?: string;
+}
+/**
+ * The `defineTopic()` results in modules or arrays, for `events.topics`. A
+ * module's topics are keyed by export name; a topic in an array by its `name`.
+ * Other values are skipped, and a topic reached twice is kept once.
+ *
+ * ```ts
+ * import * as topics from "../realtime/topics";
+ * defineApi(betterSupabase, {
+ *   info,
+ *   events: { topics: topicsFrom(topics) },
+ * });
+ * ```
+ */
+declare function topicsFrom(...sources: readonly (Readonly<Record<string, unknown>> | readonly unknown[])[]): Readonly<Record<string, TopicInput>>;
+/** CloudEvents the app sends (`forwardMutations`, `forwardBlockEvents`). */
+interface CloudEventsInput extends Pick<CloudEventOptions, "source" | "typePrefix" | "dataschema"> {
+  /** The sink's address. Defaults to `events`. */
+  readonly address?: string;
+  /** Row events for these tables (`true` for every table). Defaults to none. */
+  readonly rows?: boolean | readonly string[];
+  /** Which row events. Defaults to insert, update and delete. */
+  readonly intents?: readonly MutationIntent[];
+  /** Block events and their data schemas. */
+  readonly blocks?: BlockEventSchemas;
+}
+/** Channels and messages for AsyncAPI, built from the schema and the app. */
+interface EventsOptions<Ref = string> {
+  /**
+   * Table change signals (`bsb:t:<schema>.<table>`) for the tables in
+   * `realtime.tables`: `true` for all, or app keys. Defaults to `true`.
+   */
+  readonly tables?: boolean | readonly string[];
+  /** Realtime broadcast topics, by key. */
+  readonly topics?: Readonly<Record<string, TopicInput<Ref>>>;
+  readonly cloudEvents?: CloudEventsInput;
+}
+/** The CloudEvents attributes in HTTP binary mode (`ce-*` headers). */
+declare const CLOUD_EVENT_TRAIT: ModelMessageTrait;
+//#endregion
+//#region src/spec/options.d.ts
+/** What `defineApi` reads from a `defineSupabase()` result. */
+interface ApiSource {
+  readonly meta: SchemaMeta;
+  readonly plugins?: readonly AnyPlugin[];
+  /** The block instances `betterSupabase.blocks(set)` registered. */
+  readonly options?: {
+    readonly blocks?: DbBlockSource | undefined;
+  };
+}
+/** How `defineApi` publishes one block instance. */
+interface BlockApiDescription<Ref = string> {
+  /**
+   * The client methods to serve, contract verbs (`list`, `create`, `attach`)
+   * and domain verbs (`issue`, `approve`) alike; `chats.list` names one on a
+   * sub-client. Defaults to every method.
+   */
+  readonly verbs?: readonly string[];
+  /** Path of the instance below `basePath`. Defaults to `/<instance key>`. */
+  readonly path?: string;
+  /** Defaults to the instance key. */
+  readonly tag?: string;
+  readonly description?: string;
+  /** The permission of each verb, by the names `verbs` takes. */
+  readonly permissions?: Readonly<Record<string, Ref>>;
+  /** Overrides the model's security for this instance; `[]` makes it public. */
+  readonly security?: readonly SecurityRequirement[];
+}
+/** A block instance: its description, or `true` for the defaults. */
+type BlockApiInput<Ref = string> = BlockApiDescription<Ref> | true;
+/**
+ * A resource: its description, `true` for the defaults, or a handler that
+ * carries its plan.
+ */
+type ResourceInput<Ref = string> = ResourceDescription<Ref> | true | {
+  readonly plan: ResourcePlan<Ref>;
+};
+/** A custom route, documented from its Standard Schemas (Standard JSON Schema). */
+interface RouteSpec<Ref = string> {
+  readonly method: HttpMethod | Uppercase<HttpMethod>;
+  /** Relative to `basePath`, with `{name}` path parameters. */
+  readonly path: string;
+  readonly operationId?: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly tags?: readonly string[];
+  readonly deprecated?: boolean;
+  /** The path parameters, as an object schema. Unlisted ones are strings. */
+  readonly params?: StandardLike;
+  /** The query parameters, as an object schema. */
+  readonly query?: StandardLike;
+  /** The JSON body. */
+  readonly input?: StandardLike;
+  /** The JSON response. Without it (and without `stream`) the route answers 204. */
+  readonly output?: StandardLike;
+  /**
+   * A stream response: each item's schema (`itemSchema`), by default as
+   * `text/event-stream`.
+   */
+  readonly stream?: {
+    readonly item: StandardLike;
+    readonly contentType?: string;
+  };
+  /** Success status. Defaults to 200 with an output or stream, 204 without. */
+  readonly status?: number;
+  /** Overrides the API's security; `[]` makes the route public. */
+  readonly security?: readonly SecurityRequirement[];
+  readonly permission?: Ref;
+  /** The shared error responses. Defaults to the API's `errors`. */
+  readonly errors?: readonly ErrorResponse[];
+  /** Deep-merged into the rendered operation. */
+  readonly extend?: JsonObject;
+}
+interface OperationIdContext {
+  readonly source: OperationSource;
+  readonly method: HttpMethod;
+  readonly path: string;
+  /** The id better-supabase would use, e.g. `listCustomers`. */
+  readonly defaultId: string;
+}
+type ComponentNameContext = {
+  readonly kind: "table";
+  readonly table: string;
+  readonly variant: "Row" | "Insert" | "Update" | "Page";
+  readonly defaultName: string;
+} | {
+  readonly kind: "schema";
+  /** The name from the schema's own `$id` or `id` metadata. */
+  readonly id: string | undefined;
+  readonly schema: JsonSchema;
+  readonly role: "input" | "output" | "item";
+  readonly operationId: string;
+};
+/**
+ * Version-neutral hooks on the model. Return a replacement, or nothing to keep
+ * it.
+ */
+interface EnrichHooks {
+  readonly operation?: (operation: ModelOperation) => ModelOperation | undefined;
+  readonly schema?: (schema: JsonSchema, context: {
+    readonly name: string;
+  }) => JsonSchema | undefined;
+  readonly channel?: (channel: ModelChannel) => ModelChannel | undefined;
+  readonly message?: (message: ModelMessage, context: {
+    readonly id: string;
+  }) => ModelMessage | undefined;
+  readonly workflow?: (workflow: ModelWorkflow) => ModelWorkflow | undefined;
+}
+interface ApiOptions<Ref = string> {
+  readonly info: ModelInfo;
+  /** The document's own URL (`$self`). */
+  readonly self?: string;
+  readonly servers?: readonly ModelServer[];
+  /** Prefix for every path, e.g. `/api`. */
+  readonly basePath?: string;
+  /** Tags listed before the resource tags, with summaries and parents. */
+  readonly tags?: readonly ModelTag[];
+  /**
+   * Tables to publish, by app key. Defaults to every table with the default
+   * operations; an object publishes only the tables it lists, and `false`
+   * publishes none.
+   */
+  readonly resources?: false | Readonly<Record<string, ResourceInput<Ref>>>;
+  /**
+   * Block instances to publish, by key, each as `POST /<instance>/<verb>` per
+   * client method. Defaults to every instance `betterSupabase.blocks(set)`
+   * registered; an object publishes only the instances it lists, and `false`
+   * publishes none.
+   */
+  readonly blocks?: false | Readonly<Record<string, BlockApiInput<Ref>>>;
+  readonly routes?: readonly RouteSpec<Ref>[];
+  /**
+   * Tables and functions to document as the Supabase Data API (`/rest/v1`),
+   * with database names.
+   */
+  readonly dataApi?: DataApiOptions;
+  /** Parsed OpenAPI fragments, merged over the generated document. */
+  readonly fragments?: readonly JsonObject[];
+  /** Defaults to `['bearer']`. */
+  readonly security?: readonly SecurityPreset[];
+  /** The project URL, for the `oauth2` preset. */
+  readonly supabaseUrl?: string;
+  /** Shared error responses. Defaults to `DEFAULT_ERRORS`. */
+  readonly errors?: readonly ErrorResponse[];
+  readonly operationId?: (context: OperationIdContext) => string;
+  /**
+   * Names a component; `undefined` keeps the default (tables) or inlines it
+   * (schemas).
+   */
+  readonly componentName?: (context: ComponentNameContext) => string | undefined;
+  /** Prefix of generated `x-` fields. Defaults to `x-better-supabase-`. */
+  readonly extensionPrefix?: string;
+  /** Example rows per table (app-cased), set as the Row schema's `examples`. */
+  readonly examples?: Readonly<Record<string, readonly JsonObject[]>>;
+  readonly enrich?: EnrichHooks;
+  /** Resolves permission references to keys (`key()`) and `permissions: true`. */
+  readonly authorizer?: Authorizer<Ref>;
+  /** Report `permission-missing` for writes that declare no permission. */
+  readonly requirePermissions?: boolean;
+  /** `keys`: each permission key is also an OAuth scope of the `oauth2` preset. */
+  readonly permissionScopes?: "keys";
+  /** Security Profile Requirements (preview; only `3.3-preview` renders them). */
+  readonly securityProfileRequirements?: Readonly<Record<string, ModelSecurityProfileRequirement>>;
+  /** The Realtime websocket URL, for AsyncAPI. */
+  readonly realtimeUrl?: string;
+  readonly channels?: readonly ModelChannel[];
+  readonly messages?: Readonly<Record<string, ModelMessage>>;
+  /** Realtime tables, topics and CloudEvents, as channels and messages. */
+  readonly events?: EventsOptions<Ref>;
+  readonly webhooks?: readonly ModelWebhook[];
+  /**
+   * Workflows, or functions that build them from the operations (the Arazzo
+   * built-ins).
+   */
+  readonly workflows?: readonly (ModelWorkflow | WorkflowSource)[];
+  /** Tables with a JSON column typed in `better-supabase.config.ts`. */
+  readonly json?: Readonly<Record<string, unknown>>;
+}
+/** Builds workflows from the model's operations, after enrich hooks ran on them. */
+type WorkflowSource = (operations: readonly ModelOperation[]) => readonly ModelWorkflow[];
+interface BuiltModel {
+  readonly model: ApiModel;
+  /** Findings while building: permissions, components, schemas, plugins. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+}
+//#endregion
+//#region src/spec/api.d.ts
+/**
+ * Applies Overlay documents in order to a rendered document and reports what it
+ * found. `better-supabase/spec` provides one: `(doc, overlays) =>
+ * applyOverlays(doc, overlays, { jsonpath })`.
+ */
+type OverlayEngine = (document: unknown, overlays: readonly unknown[]) => {
+  readonly document: unknown;
+  readonly diagnostics?: readonly SpecDiagnostic[];
+};
+interface RenderOptions<F extends AnyDocumentFormat> {
+  /** Defaults to the format's default version. */
+  readonly version?: VersionOf<F>;
+  /**
+   * Last change to the lowered document, before overlays. It receives a copy,
+   * typed per version; return a replacement or change it in place.
+   */
+  readonly transform?: (rendered: RenderedOf<F>) => DocumentOf<F> | undefined;
+  readonly overlays?: readonly unknown[];
+  /** Overrides the API's `applyOverlays`. */
+  readonly applyOverlays?: OverlayEngine;
+}
+interface RenderResult<F extends AnyDocumentFormat> {
+  readonly format: F["id"];
+  readonly version: VersionOf<F>;
+  readonly document: DocumentOf<F>;
+  /** Building, lowering, overlay and lint findings, without duplicates. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+  readonly fileName: string;
+}
+interface OpenApiRenderOptions<V extends OpenApiVersion> {
+  readonly version?: V;
+  readonly transform?: (rendered: Extract<RenderedOpenApi, {
+    readonly version: V;
+  }>) => OpenApiDocuments[OpenApiVersion] | undefined;
+  readonly overlays?: readonly unknown[];
+  readonly applyOverlays?: OverlayEngine;
+}
+interface OpenApiRenderResult<V extends OpenApiVersion> {
+  readonly format: "openapi";
+  readonly version: V;
+  readonly document: OpenApiDocuments[V];
+  readonly diagnostics: readonly SpecDiagnostic[];
+  readonly fileName: string;
+}
+interface DefineApiOptions<Ref = string> extends ApiOptions<Ref> {
+  /** The default overlay engine for `overlays` in `render`. */
+  readonly applyOverlays?: OverlayEngine;
+}
+interface Api {
+  readonly model: ApiModel;
+  /** The prefix of every path, from `basePath`; `""` without one. */
+  readonly basePath: string;
+  /**
+   * The tables it publishes and how, by app key, for the server that serves
+   * them (`createOrpc().router(api)`).
+   */
+  readonly resources: Readonly<Record<string, ResourceInput<unknown>>>;
+  /** The block instances it publishes and how, by instance key. */
+  readonly blocks: Readonly<Record<string, BlockApiDescription<unknown>>>;
+  /** Findings while building the model. */
+  readonly diagnostics: readonly SpecDiagnostic[];
+  /**
+   * Lowers the model to a version of any `DocumentFormat`, then runs
+   * `transform`, overlays and the format's lint.
+   */
+  render<F extends AnyDocumentFormat>(format: F, options?: RenderOptions<F>): RenderResult<F>;
+  /** `render(openapiFormat, options)`, typed per version. Defaults to 3.1. */
+  openapi<V extends OpenApiVersion = "3.1">(options?: OpenApiRenderOptions<V>): OpenApiRenderResult<V>;
+}
+/**
+ * The API model for a `defineSupabase()` result, and the documents it renders.
+ * The model is built once per options object; each format and version is
+ * lowered once and copied for every render.
+ *
+ * ```ts
+ * const api = defineApi(betterSupabase, {
+ *   info: { title: "CRM API", version: "1.0.0" },
+ *   resources: { customers: { list: customerList } },
+ * });
+ * ```
+ *
+ * Without `resources` it publishes every table, and without `blocks` every
+ * block instance `betterSupabase.blocks(set)` registered:
+ *
+ * ```ts
+ * const api = defineApi(betterSupabase, { info, basePath: "/api" });
+ * export const { procedures } = bsb.router(api, { meta: openapi });
+ * const { document } = api.openapi({ version: "3.2" });
+ * ```
+ */
+declare function defineApi<Ref = string>(source: ApiSource, options: DefineApiOptions<Ref>): Api;
+//#endregion
+export { AnyOpenApiDocument as A, OpenApiSecurityRequirement as B, TopicInput as C, DEFAULT_ERRORS as D, CustomSecurity as E, OpenApi33PreviewDocument as F, RenderedOpenApi as H, OpenApiComponents as I, OpenApiDocument as L, OpenApi30Document as M, OpenApi31Document as N, PROBLEM_SCHEMA as O, OpenApi32Document as P, OpenApiDocuments as R, EventsOptions as S, DataApiOptions as T, OpenApiVersion as V, WorkflowSource as _, OverlayEngine as a, CLOUD_EVENT_TRAIT as b, defineApi as c, BuiltModel as d, ComponentNameContext as f, RouteSpec as g, ResourceInput as h, OpenApiRenderResult as i, OPENAPI_33_PREVIEW_VERSION as j, SecurityPreset as k, ApiOptions as l, OperationIdContext as m, DefineApiOptions as n, RenderOptions as o, EnrichHooks as p, OpenApiRenderOptions as r, RenderResult as s, Api as t, ApiSource as u, BlockEventSchema as v, topicsFrom as w, CloudEventsInput as x, BlockEventSchemas as y, OpenApiInfo as z };