better-supabase 0.8.0 → 0.9.0

package/dist/api-TG3jE5aO.d.ts

@@ -0,0 +1,411 @@
+import { P as SchemaMeta } from "./types-YfwpIE-d.js";
+import { h as MutationIntent } from "./executor-DoE-5iM8.js";
+import { xt as EventMap } from "./events-CTreRrgP.js";
+import { n as AnyPlugin } from "./plugin-CDLJRFFg.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-lUafmeBQ.js";
+import { c as SpecDiagnostic, i as DocumentOf, l as VersionOf, s as RenderedOf, t as AnyDocumentFormat } from "./format-CNwSjXUU.js";
+import { o as Authorizer } from "./authorizer-eiOjo-3l.js";
+import { a as ResourcePlan, o as StandardLike, r as ResourceDescription, t as ErrorResponse } from "./resource-B4ka8dDH.js";
+import { n as CloudEventOptions } from "./cloud-event-5rCEzIgK.js";
+import { t as RealtimeStatus } from "./realtime-status-DcsO00Gw.js";
+import { t as SPEC_PINS } from "./spec-pins-Dqpml2dZ.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#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 commentsEvents>`. `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 (`bs: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[];
+}
+/** 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. */
+  readonly resources?: Readonly<Record<string, ResourceInput<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/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/api.d.ts
+/**
+ * Applies Overlay documents in order to a rendered document and reports
+ * what it found. `better-supabase/overlay` 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;
+  /** 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 } },
+ * });
+ * const { document } = api.openapi({ version: "3.2" });
+ * ```
+ */
+declare function defineApi<Ref = string>(source: ApiSource, options: DefineApiOptions<Ref>): Api;
+//#endregion
+export { WorkflowSource as A, DEFAULT_ERRORS as B, ApiSource as C, OperationIdContext as D, EnrichHooks as E, EventsOptions as F, SecurityPreset as H, TopicInput as I, topicsFrom as L, BlockEventSchemas as M, CLOUD_EVENT_TRAIT as N, ResourceInput as O, CloudEventsInput as P, DataApiOptions as R, ApiOptions as S, ComponentNameContext as T, PROBLEM_SCHEMA as V, OpenApiDocuments as _, OverlayEngine as a, OpenApiVersion as b, defineApi as c, OpenApi30Document as d, OpenApi31Document as f, OpenApiDocument as g, OpenApiComponents as h, OpenApiRenderResult as i, BlockEventSchema as j, RouteSpec as k, AnyOpenApiDocument as l, OpenApi33PreviewDocument as m, DefineApiOptions as n, RenderOptions as o, OpenApi32Document as p, OpenApiRenderOptions as r, RenderResult as s, Api as t, OPENAPI_33_PREVIEW_VERSION as u, OpenApiInfo as v, BuiltModel as w, RenderedOpenApi as x, OpenApiSecurityRequirement as y, CustomSecurity as z };