better-supabase 0.13.0 → 0.15.0

package/dist/spec/index.d.ts

@@ -1,12 +1,14 @@
-import { C as TopicInput, D as DEFAULT_ERRORS, E as CustomSecurity, O as PROBLEM_SCHEMA, S as EventsOptions, T as DataApiOptions, a as OverlayEngine, c as defineApi, d as BuiltModel, f as ComponentNameContext, g as RouteSpec, h as ResourceInput, i as OpenApiRenderResult, k as SecurityPreset, l as ApiOptions, m as OperationIdContext, n as DefineApiOptions, o as RenderOptions, p as EnrichHooks, r as OpenApiRenderOptions, s as RenderResult, t as Api, u as ApiSource, w as topicsFrom } from "../api-DwLhJS1j.js";
-import { C as ModelWebhook, D as ResourceOperation, E as OperationSource, O as SecurityRequirement, S as ModelTag, T as OAuthFlow, _ as ModelResponseOrRef, a as JsonSchema, b as ModelServer, c as ModelChannelOperation, d as ModelInfo, f as ModelMessage, g as ModelResponse, h as ModelParameter, i as JsonObject, l as ModelContent, m as ModelOperation, n as DataApiOperation, o as ModelBody, p as ModelMessageTrait, r as HttpMethod, s as ModelChannel, t as ApiModel, u as ModelExample, v as ModelSecurityProfileRequirement, w as ModelWorkflow, x as ModelStep, y as ModelSecurityScheme } from "../model-Btl8X9cs.js";
-import { a as FormatVersion, c as SpecDiagnostic, d as defineDocumentFormat, i as DocumentOf, l as VersionOf, n as DiagnosticSeverity, o as LowerContext, r as DocumentFormat, s as RenderedOf, t as AnyDocumentFormat, u as VersionStatus } from "../format-AYHceC2m.js";
-import { a as ResourcePlan, r as ResourceDescription } from "../resource-DxQOPkZ5.js";
-import { t as DescribedFunction } from "../function-contract-4vfi93Y5.js";
+import { t as DescribedFunction } from "../function-contract-DxFNOmsm.js";
+import { C as ModelWebhook, D as ResourceOperation, E as OperationSource, O as SecurityRequirement, S as ModelTag, T as OAuthFlow, _ as ModelResponseOrRef, a as JsonSchema, b as ModelServer, c as ModelChannelOperation, d as ModelInfo, f as ModelMessage, g as ModelResponse, h as ModelParameter, i as JsonObject, k as TableVerb, l as ModelContent, m as ModelOperation, n as DataApiOperation, o as ModelBody, p as ModelMessageTrait, r as HttpMethod, s as ModelChannel, t as ApiModel, u as ModelExample, v as ModelSecurityProfileRequirement, w as ModelWorkflow, x as ModelStep, y as ModelSecurityScheme } from "../model-hwpvole9.js";
+import { a as ResourcePlan, o as StandardLike, r as ResourceDescription } from "../resource-D8pzB5Qf.js";
+import { t as SPEC_PINS } from "../spec-pins-DIx95afw.js";
+import { A as AnyOpenApiDocument, B as OpenApiSecurityRequirement, C as TopicInput, D as DEFAULT_ERRORS, E as CustomSecurity, F as OpenApi33PreviewDocument, H as RenderedOpenApi, I as OpenApiComponents, L as OpenApiDocument, M as OpenApi30Document, N as OpenApi31Document, O as PROBLEM_SCHEMA, P as OpenApi32Document, R as OpenApiDocuments, S as EventsOptions, T as DataApiOptions, V as OpenApiVersion, _ as WorkflowSource, a as OverlayEngine, b as CLOUD_EVENT_TRAIT, c as defineApi, d as BuiltModel, f as ComponentNameContext, g as RouteSpec, h as ResourceInput, i as OpenApiRenderResult, j as OPENAPI_33_PREVIEW_VERSION, k as SecurityPreset, l as ApiOptions, m as OperationIdContext, n as DefineApiOptions, o as RenderOptions, p as EnrichHooks, r as OpenApiRenderOptions, s as RenderResult, t as Api, u as ApiSource, v as BlockEventSchema, w as topicsFrom, x as CloudEventsInput, y as BlockEventSchemas, z as OpenApiInfo } from "../api-DxAPqMrE.js";
+import { a as FormatVersion, c as SpecDiagnostic, d as defineDocumentFormat, i as DocumentOf, l as VersionOf, n as DiagnosticSeverity, o as LowerContext, r as DocumentFormat, s as RenderedOf, t as AnyDocumentFormat, u as VersionStatus } from "../format-u-65igKI.js";
 //#region src/spec/build.d.ts
 /**
- * Builds the version-neutral API model once per metadata, plugin list and
- * options object. Formats lower it to each version; `defineApi` wraps it.
+ * Builds the version-neutral API model once per metadata, plugin list, block
+ * set and options object. Formats lower it to each version; `defineApi` wraps
+ * it.
  */
 export declare function buildApiModel<Ref = string>(source: ApiSource, options: ApiOptions<Ref>): BuiltModel;
 //#endregion
@@ -24,7 +26,7 @@ interface FunctionRouteOptions {
  * `basePath` goes in front of it like any other route.
  *
  * ```ts
- * defineApi(bs, { routes: [functionRoute("send-invite", sendInvite)] });
+ * defineApi(bsb, { routes: [functionRoute("send-invite", sendInvite)] });
  * ```
  */
 export declare function functionRoute(name: string, fn: DescribedFunction, options?: FunctionRouteOptions): RouteSpec;
@@ -165,4 +167,684 @@ interface ScalarPresetOptions {
  */
 export declare function scalarPreset<D extends object>(document: D, options?: ScalarPresetOptions): D;
 //#endregion
-export { type AnyDocumentFormat, type Api, type ApiModel, type ApiOptions, type ApiSource, type BuiltModel, type ComponentNameContext, type CustomSecurity, DEFAULT_ERRORS, type DataApiOperation, type DataApiOptions, type DefineApiOptions, type DiagnosticSeverity, type DocumentFormat, type DocumentOf, type EnrichHooks, type EventsOptions, type FormatVersion, type FunctionRouteOptions, type HttpMethod, type JsonObject, type JsonSchema, type LowerContext, type ModelBody, type ModelChannel, type ModelChannelOperation, type ModelContent, type ModelExample, type ModelInfo, type ModelMessage, type ModelMessageTrait, type ModelOperation, type ModelParameter, type ModelResponse, type ModelResponseOrRef, type ModelSecurityProfileRequirement, type ModelSecurityScheme, type ModelServer, type ModelStep, type ModelTag, type ModelWebhook, type ModelWorkflow, type OAuthFlow, type OpenApiRenderOptions, type OpenApiRenderResult, type OperationIdContext, type OperationSource, type OverlayEngine, PROBLEM_SCHEMA, type RenderOptions, type RenderResult, type RenderedOf, type ResourceDescription, type ResourceInput, type ResourceOperation, type ResourcePlan, type RouteSpec, type ScalarPresetOptions, type SecurityPreset, type SecurityRequirement, type SerializeOptions, type SpecDiagnostic, type SpecReferenceOptions, type SpecReferenceResponseOptions, type SpecResponseOptions, type SpecUi, type SpecUiAssets, type TopicInput, type VersionOf, type VersionStatus, defineApi, defineDocumentFormat, topicsFrom };
+//#region src/openapi/create.d.ts
+/** How one table is published; see `defineApi`'s `resources`. */
+type ResourceOptions<Ref = string> = ResourceDescription<Ref>;
+interface OpenApiOptions<V extends OpenApiVersion = "3.1", Ref = string> extends DefineApiOptions<Ref> {
+  /** Defaults to 3.1. `3.3-preview` follows a draft. */
+  readonly version?: V;
+  /** Last change to the document before overlays; see `RenderOptions.transform`. */
+  readonly transform?: (rendered: Extract<RenderedOpenApi, {
+    readonly version: V;
+  }>) => OpenApiDocuments[OpenApiVersion] | undefined;
+  readonly overlays?: readonly unknown[];
+  /** Hears every warning and info finding. Errors throw. */
+  readonly onDiagnostic?: (diagnostic: SpecDiagnostic) => void;
+}
+/**
+ * An OpenAPI document for REST resources over your tables, with schemas from
+ * the generated metadata, list-query parameters, Supabase security schemes and
+ * Problem Details errors. Throws when building or checking the document finds
+ * an error; use `defineApi` to read every finding instead.
+ *
+ * ```ts
+ * const doc = createOpenApi(betterSupabase, {
+ *   info: { title: "CRM API", version: "1.0.0" },
+ *   resources: {
+ *     customers: { list: customerList },
+ *     notes: { operations: ["list", "get"] },
+ *   },
+ * });
+ * ```
+ */
+export declare function createOpenApi<V extends OpenApiVersion = "3.1", Ref = string>(betterSupabase: ApiSource, options: OpenApiOptions<V, Ref>): OpenApiDocuments[V];
+//#endregion
+//#region src/openapi/format.d.ts
+/**
+ * OpenAPI as a `DocumentFormat`. 3.1 is the default; 3.0 is legacy (schemas
+ * lowered to the 3.0 Schema Object); 3.2 has native `$self`, nested tags,
+ * `itemSchema`, `oauth2MetadataUrl` and `query`; `3.3-preview` follows the
+ * v3.3-dev branch at `SPEC_PINS.openapi33Preview`, with Path Item `security`
+ * and the Security Profiles proposal. Below 3.2, the 3.2 fields travel as the
+ * registered `x-oai-*` extensions where one exists, and as the model's prefixed
+ * extensions otherwise.
+ */
+export declare const openapiFormat: DocumentFormat<"openapi", OpenApiVersion, AnyOpenApiDocument, OpenApiDocuments>;
+//#endregion
+//#region src/openapi/schema30.d.ts
+type Json$2 = Record<string, unknown>;
+/**
+ * Rewrites a JSON Schema 2020-12 schema into the OpenAPI 3.0 Schema Object:
+ * `null` in `type` or in an `anyOf`/`oneOf` becomes `nullable`, a type list
+ * becomes `anyOf`, `const` becomes a one-value `enum`, `examples` becomes
+ * `example`, numeric `exclusiveMinimum`/`exclusiveMaximum` become the boolean
+ * form, `contentEncoding: base64` becomes `format: byte`, and a `$ref` with
+ * siblings is wrapped in `allOf`. Keywords 3.0 does not have are left out. The
+ * input is not changed.
+ */
+export declare function toOpenApi30Schema(schema: Readonly<Json$2>): Json$2;
+//#endregion
+//#region src/asyncapi/types.d.ts
+type Json$1 = Record<string, unknown>;
+/** The AsyncAPI versions `asyncapiFormat` renders. */
+type AsyncApiVersion = "3.0" | "3.1";
+/**
+ * The file name `asyncapiFormat` writes; Arazzo source descriptions point at
+ * it.
+ */
+export declare const ASYNCAPI_FILE_NAME = "asyncapi.json";
+interface AsyncApiInfo {
+  readonly title: string;
+  readonly version: string;
+  readonly description?: string;
+  readonly termsOfService?: string;
+  readonly contact?: {
+    readonly name?: string;
+    readonly url?: string;
+    readonly email?: string;
+  };
+  readonly license?: {
+    readonly name: string;
+    readonly url?: string;
+  };
+}
+interface AsyncApiComponents {
+  readonly schemas?: Readonly<Record<string, Json$1>>;
+  readonly messages?: Readonly<Record<string, Json$1>>;
+  readonly messageTraits?: Readonly<Record<string, Json$1>>;
+  readonly securitySchemes?: Readonly<Record<string, Json$1>>;
+}
+interface AsyncApiDocumentBase {
+  readonly info: AsyncApiInfo;
+  readonly defaultContentType: string;
+  readonly servers?: Readonly<Record<string, Json$1>>;
+  /** Channel id to Channel Object. */
+  readonly channels: Readonly<Record<string, Json$1>>;
+  /** Operation id to Operation Object. */
+  readonly operations: Readonly<Record<string, Json$1>>;
+  readonly components: AsyncApiComponents;
+  readonly [extension: `x-${string}`]: unknown;
+}
+interface AsyncApi30Document extends AsyncApiDocumentBase {
+  readonly asyncapi: typeof SPEC_PINS.asyncapi30;
+}
+/** AsyncAPI 3.1 adds the `ros2` bindings; the rest matches 3.0. */
+interface AsyncApi31Document extends AsyncApiDocumentBase {
+  readonly asyncapi: typeof SPEC_PINS.asyncapi31;
+}
+interface AsyncApiDocuments {
+  readonly "3.0": AsyncApi30Document;
+  readonly "3.1": AsyncApi31Document;
+}
+type AsyncApiDocument<V extends AsyncApiVersion = "3.0"> = AsyncApiDocuments[V];
+type AnyAsyncApiDocument = AsyncApiDocuments[AsyncApiVersion];
+/** What an AsyncAPI `transform` receives, discriminated by `version`. */
+type RenderedAsyncApi = { readonly [V in AsyncApiVersion]: {
+  readonly format: "asyncapi";
+  readonly version: V;
+  readonly document: AsyncApiDocuments[V];
+}; }[AsyncApiVersion];
+//#endregion
+//#region src/asyncapi/create.d.ts
+interface AsyncApiOptions<V extends AsyncApiVersion = "3.0", Ref = string> extends DefineApiOptions<Ref> {
+  /** Defaults to 3.0, which more tools read; 3.1 only adds `ros2` bindings. */
+  readonly version?: V;
+  /** Last change to the document before overlays; it receives a copy. */
+  readonly transform?: (rendered: Extract<RenderedAsyncApi, {
+    readonly version: V;
+  }>) => AnyAsyncApiDocument | undefined;
+  readonly overlays?: readonly unknown[];
+  /** Hears every warning and info finding. Errors throw. */
+  readonly onDiagnostic?: (diagnostic: SpecDiagnostic) => void;
+}
+/**
+ * An AsyncAPI document for the app's events: Realtime table change signals and
+ * broadcast topics, CloudEvents for row and block events, outgoing webhooks and
+ * the events HTTP operations emit. Pass `events` (and `realtimeUrl` for the
+ * websocket server). Throws when building or checking the document finds an
+ * error; use `defineApi(...).render(asyncapiFormat)` to read every finding
+ * instead.
+ *
+ * ```ts
+ * const doc = createAsyncApi(betterSupabase, {
+ *   info: { title: "CRM events", version: "1.0.0" },
+ *   realtimeUrl: "wss://example.supabase.co/realtime/v1/websocket",
+ *   events: {
+ *     tables: ["customers"],
+ *     cloudEvents: { source: "/crm", blocks: { "support.started": true } },
+ *   },
+ * });
+ * ```
+ */
+export declare function createAsyncApi<V extends AsyncApiVersion = "3.0", Ref = string>(betterSupabase: ApiSource, options: AsyncApiOptions<V, Ref>): AsyncApiDocuments[V];
+//#endregion
+//#region src/asyncapi/format.d.ts
+/**
+ * AsyncAPI as a `DocumentFormat`, for the events the API model describes:
+ * Realtime table change signals and broadcast topics on the Supabase Realtime
+ * websocket (`ws` bindings), CloudEvents (headers as the `cloudEvent` message
+ * trait), outgoing webhooks over HTTP and the events HTTP operations emit. 3.0
+ * is the default; 3.1 only adds `ros2` bindings, so the two documents differ in
+ * the `asyncapi` field.
+ */
+export declare const asyncapiFormat: DocumentFormat<"asyncapi", AsyncApiVersion, AnyAsyncApiDocument, AsyncApiDocuments>;
+//#endregion
+//#region src/arazzo/types.d.ts
+type Json = Record<string, unknown>;
+/** The Arazzo versions `arazzoFormat` renders. */
+type ArazzoVersion = "1.0" | "1.1";
+/** A document the workflows call: the emitted OpenAPI or AsyncAPI file. */
+interface ArazzoSourceDescription {
+  readonly name: string;
+  readonly url: string;
+  readonly type: "openapi" | "asyncapi" | "arazzo";
+}
+interface ArazzoInfo {
+  readonly title: string;
+  readonly version: string;
+  readonly summary?: string;
+  readonly description?: string;
+}
+interface ArazzoStep {
+  readonly stepId: string;
+  readonly description?: string;
+  readonly operationId?: string;
+  readonly operationPath?: string;
+  /** Arazzo 1.1: a JSON Pointer to an AsyncAPI channel. */
+  readonly channelPath?: string;
+  readonly workflowId?: string;
+  /** Arazzo 1.1, AsyncAPI steps only. */
+  readonly action?: "send" | "receive";
+  /** Arazzo 1.1, AsyncAPI receive steps only. */
+  readonly correlationId?: string;
+  readonly parameters?: readonly Json[];
+  readonly requestBody?: Json;
+  readonly successCriteria?: readonly Json[];
+  readonly onSuccess?: readonly Json[];
+  readonly onFailure?: readonly Json[];
+  readonly outputs?: Readonly<Record<string, string>>;
+}
+interface ArazzoWorkflow {
+  readonly workflowId: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly inputs?: Json;
+  readonly steps: readonly ArazzoStep[];
+  readonly outputs?: Readonly<Record<string, string>>;
+}
+interface ArazzoDocumentBase {
+  readonly info: ArazzoInfo;
+  readonly sourceDescriptions: readonly ArazzoSourceDescription[];
+  readonly workflows: readonly ArazzoWorkflow[];
+  readonly components?: Json;
+  readonly [extension: `x-${string}`]: unknown;
+}
+interface Arazzo10Document extends ArazzoDocumentBase {
+  readonly arazzo: typeof SPEC_PINS.arazzo10;
+}
+/** Arazzo 1.1 adds AsyncAPI steps, action parameters and `querystring`. */
+interface Arazzo11Document extends ArazzoDocumentBase {
+  readonly arazzo: typeof SPEC_PINS.arazzo11;
+  readonly $self?: string;
+}
+interface ArazzoDocuments {
+  readonly "1.0": Arazzo10Document;
+  readonly "1.1": Arazzo11Document;
+}
+type ArazzoDocument<V extends ArazzoVersion = "1.0"> = ArazzoDocuments[V];
+type AnyArazzoDocument = ArazzoDocuments[ArazzoVersion];
+/** What an Arazzo `transform` receives, discriminated by `version`. */
+type RenderedArazzo = { readonly [V in ArazzoVersion]: {
+  readonly format: "arazzo";
+  readonly version: V;
+  readonly document: ArazzoDocuments[V];
+}; }[ArazzoVersion];
+//#endregion
+//#region src/arazzo/format.d.ts
+/** Where the workflows' source documents live. */
+interface ArazzoSourceOptions {
+  /** Defaults to `api`. */
+  readonly name?: string;
+  /** Defaults to the model's `self`, then the format's file name. */
+  readonly url?: string;
+}
+interface ArazzoFormatOptions {
+  /** The OpenAPI document; its URL defaults to `openapi.json`. */
+  readonly openapi?: ArazzoSourceOptions;
+  /**
+   * The AsyncAPI document channel steps use; defaults to `events` at
+   * `asyncapi.json`.
+   */
+  readonly asyncapi?: ArazzoSourceOptions;
+}
+/**
+ * An Arazzo format whose source descriptions point at your OpenAPI and AsyncAPI
+ * URLs. `arazzoFormat` is this with the defaults: `api` at the model's `self`
+ * or `openapi.json`, and `events` at `asyncapi.json`.
+ */
+export declare function createArazzoFormat(options?: ArazzoFormatOptions): DocumentFormat<"arazzo", ArazzoVersion, AnyArazzoDocument, ArazzoDocuments>;
+/**
+ * Arazzo as a `DocumentFormat`, for the model's `workflows`. 1.0 is the
+ * default; channel steps (AsyncAPI send and receive) and action `parameters`
+ * need 1.1.
+ */
+export declare const arazzoFormat: DocumentFormat<"arazzo", ArazzoVersion, AnyArazzoDocument, ArazzoDocuments>;
+//#endregion
+//#region src/arazzo/create.d.ts
+interface ArazzoOptions<V extends ArazzoVersion = "1.0", Ref = string> extends DefineApiOptions<Ref>, ArazzoFormatOptions {
+  /** Defaults to 1.0; channel steps and action parameters need 1.1. */
+  readonly version?: V;
+  /** Last change to the document before overlays; it receives a copy. */
+  readonly transform?: (rendered: Extract<RenderedArazzo, {
+    readonly version: V;
+  }>) => AnyArazzoDocument | undefined;
+  readonly overlays?: readonly unknown[];
+  /** Hears every warning and info finding. Errors throw. */
+  readonly onDiagnostic?: (diagnostic: SpecDiagnostic) => void;
+}
+/**
+ * An Arazzo document for the API's workflows: your `defineWorkflow` workflows
+ * and the built-ins (`paginationWorkflows()`, `createThenGetWorkflows()`,
+ * `authWorkflow()`), checked against the operations the API has. Throws when
+ * building or checking the document finds an error; use
+ * `defineApi(...).render(arazzoFormat)` to read every finding instead.
+ *
+ * ```ts
+ * const doc = createArazzo(betterSupabase, {
+ *   info: { title: "CRM workflows", version: "1.0.0" },
+ *   resources: { customers: { pagination: "cursor" } },
+ *   workflows: [paginationWorkflows(), createThenGetWorkflows()],
+ * });
+ * ```
+ */
+export declare function createArazzo<V extends ArazzoVersion = "1.0", Ref = string>(betterSupabase: ApiSource, options: ArazzoOptions<V, Ref>): ArazzoDocuments[V];
+//#endregion
+//#region src/arazzo/builtins.d.ts
+interface BuiltinWorkflowOptions {
+  /** Only these tables; defaults to every resource that qualifies. */
+  readonly tables?: readonly string[];
+}
+/**
+ * One workflow per cursor-paginated list: read the first page, then the next
+ * one from its `nextCursor` when `hasMore` is true. Repeat the second step with
+ * its own `nextCursor` to walk the rest.
+ */
+export declare function paginationWorkflows(options?: BuiltinWorkflowOptions): WorkflowSource;
+/**
+ * One workflow per resource with `create` and `get`: create a row, then read it
+ * back by its key.
+ */
+export declare function createThenGetWorkflows(options?: BuiltinWorkflowOptions): WorkflowSource;
+interface AuthWorkflowOptions {
+  /** The operationId to call once signed in. */
+  readonly call: string;
+  /**
+   * The sign-in operationId: it takes `email` and `password` and returns a
+   * token. Defaults to `signIn`.
+   */
+  readonly signIn?: string;
+  /**
+   * JSON Pointer to the access token in the sign-in response. Defaults to
+   * `/access_token`.
+   */
+  readonly tokenPointer?: string;
+  /** Defaults to `signInThen<Call>`. */
+  readonly id?: string;
+}
+/**
+ * Sign in, then call an operation with the access token as a bearer token. A
+ * 403 Problem Details answer with code `APPROVAL_REQUIRED` ends the workflow
+ * (the `approvalRequired` failure action), so a client can wait for the
+ * approval instead of retrying.
+ */
+export declare function authWorkflow(options: AuthWorkflowOptions): WorkflowSource;
+//#endregion
+//#region src/arazzo/workflow.d.ts
+type PascalWord<S extends string> = S extends `${infer Head}_${infer Tail}` ? `${Capitalize<Head>}${PascalWord<Tail>}` : S extends `${infer Head}-${infer Tail}` ? `${Capitalize<Head>}${PascalWord<Tail>}` : Capitalize<S>;
+/**
+ * The operationIds `defineApi` gives resource operations by default
+ * (`listCustomers`, `getCustomers`), for a typed `defineWorkflow`:
+ * `defineWorkflow<ResourceOperationIds<"customers" | "notes">>(...)`.
+ */
+type ResourceOperationIds<Table extends string, Op extends ResourceOperation = ResourceOperation> = Table extends string ? `${Op}${PascalWord<Table>}` : never;
+/** Where a parameter goes; inferred from the target operation when left out. */
+type ParameterLocation = "path" | "query" | "header" | "cookie";
+interface StepParameter {
+  readonly name: string;
+  readonly in?: ParameterLocation;
+  /** A literal or a runtime expression such as `$inputs.id`. */
+  readonly value: unknown;
+}
+/**
+ * An Arazzo Criterion Object; `context` is required for every `type` but
+ * `simple`.
+ */
+interface CriterionObject {
+  readonly condition: string;
+  readonly context?: string;
+  readonly type?: "simple" | "regex" | "jsonpath" | "xpath" | JsonObject;
+}
+/** A success criterion: a simple condition string, or a Criterion Object. */
+type StepCriterion = string | CriterionObject;
+interface StepBase {
+  readonly id: string;
+  readonly description?: string;
+  /** A list, or a record of name to value (the location is inferred). */
+  readonly parameters?: readonly StepParameter[] | Readonly<Record<string, unknown>>;
+  /** The request body; runtime expressions inside it are resolved. */
+  readonly requestBody?: unknown;
+  /** Defaults to the first 2xx status of the target operation. */
+  readonly successCriteria?: readonly StepCriterion[];
+  /** Output name to a runtime expression, e.g. `$response.body#/id`. */
+  readonly outputs?: Readonly<Record<string, string>>;
+  readonly onSuccess?: readonly JsonObject[];
+  readonly onFailure?: readonly JsonObject[];
+}
+interface OperationStep<Op extends string> extends StepBase {
+  readonly operationId: Op;
+  readonly workflowId?: never;
+  readonly channel?: never;
+}
+interface WorkflowCallStep extends StepBase {
+  readonly workflowId: string;
+  readonly operationId?: never;
+  readonly channel?: never;
+}
+/** Sends or receives on an AsyncAPI channel; Arazzo 1.1 only. */
+interface ChannelStep extends StepBase {
+  readonly channel: {
+    readonly id: string;
+    readonly action: "send" | "receive";
+    readonly correlationId?: string;
+  };
+  readonly operationId?: never;
+  readonly workflowId?: never;
+}
+type WorkflowStep<Op extends string = string> = OperationStep<Op> | WorkflowCallStep | ChannelStep;
+interface WorkflowInput<Op extends string = string> {
+  readonly id: string;
+  readonly summary?: string;
+  readonly description?: string;
+  /** A JSON Schema, or a Standard Schema converted through Standard JSON Schema. */
+  readonly inputs?: JsonSchema | StandardLike;
+  readonly steps: readonly WorkflowStep<Op>[];
+  /** Output name to a runtime expression, e.g. `$steps.get.outputs.row`. */
+  readonly outputs?: Readonly<Record<string, string>>;
+}
+/**
+ * A workflow for `defineApi`'s `workflows`, rendered by `arazzoFormat`. Steps
+ * name operations by operationId; pass the ids as `Op` (for example
+ * `ResourceOperationIds<"customers">`) to type them. Rendering reports unknown
+ * operationIds, steps that read outputs of later or unknown steps, and channel
+ * steps outside Arazzo 1.1.
+ *
+ * ```ts
+ * const onboarding = defineWorkflow<ResourceOperationIds<"customers">>({
+ *   id: "onboardCustomer",
+ *   inputs: { type: "object", properties: { row: { type: "object" } } },
+ *   steps: [
+ *     {
+ *       id: "create",
+ *       operationId: "createCustomers",
+ *       requestBody: "$inputs.row",
+ *       outputs: { id: "$response.body#/id" },
+ *     },
+ *     {
+ *       id: "get",
+ *       operationId: "getCustomers",
+ *       parameters: { id: "$steps.create.outputs.id" },
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export declare function defineWorkflow<const Op extends string = string>(workflow: WorkflowInput<Op>): ModelWorkflow;
+//#endregion
+//#region src/overlay/types.d.ts
+/**
+ * The Overlay versions `applyOverlay` reads. Patch versions are ignored
+ * (Overlay § 4.1).
+ */
+type OverlayVersion = "1.0.0" | "1.1.0" | "1.2.0";
+/** Specification extensions: fields that start with `x-` (Overlay 1.2 § 4.7). */
+type Extensions = {
+  readonly [key: `x-${string}`]: unknown;
+};
+type OverlayInfo = {
+  /** The purpose of the overlay. */
+  readonly title: string;
+  /** The overlay's own version, not the Overlay Specification version. */
+  readonly version: string;
+  /** CommonMark (1.1 and later). */
+  readonly description?: string;
+} & Extensions;
+/** Fields every action kind shares. */
+interface ActionFields {
+  readonly description?: string;
+  /**
+   * Merged into objects, concatenated or appended to arrays, or replaces
+   * primitives.
+   */
+  readonly update?: unknown;
+  /** When `true`, every selected node is removed. Wins over `update` and `copy`. */
+  readonly remove?: boolean;
+  /**
+   * Accept a target that selects nothing. Without it, `applyOverlay` reports
+   * `overlay-no-match` as an error.
+   */
+  readonly "x-better-supabase-allow-empty"?: boolean;
+}
+/** An Overlay 1.0 Action Object. */
+type OverlayAction10 = ActionFields & {
+  /** An RFC 9535 JSONPath query. */
+  readonly target: string;
+} & Extensions;
+/** An Overlay 1.1 and 1.2 Action Object, which adds `copy`. */
+type OverlayAction = OverlayAction10 & {
+  /** A JSONPath query that selects one node whose value is used like `update`. */
+  readonly copy?: string;
+};
+/** The fields of a reusable action (1.2): an Action Object without `target`. */
+type ReusableActionFields = Omit<OverlayAction, "target">;
+/** A Reusable Action Object (Overlay 1.2 § 4.5.5). */
+type ReusableAction = {
+  readonly description?: string;
+  readonly fields?: ReusableActionFields;
+} & Extensions;
+/**
+ * A Reusable Action Reference Object (Overlay 1.2 § 4.5.6). Its own action
+ * fields override the referenced ones for this use.
+ */
+type ReusableActionReference = Partial<Omit<OverlayAction, "target">> & {
+  /** `#/components/actions/<name>`, with the name escaped per RFC 6901. */
+  readonly $ref: `#/components/actions/${string}`;
+  readonly target: string;
+};
+interface OverlayBase {
+  readonly info: OverlayInfo;
+  /** URI of the target document, without a fragment. */
+  readonly extends?: string;
+}
+type Overlay10 = OverlayBase & {
+  readonly overlay: "1.0.0";
+  readonly actions: readonly OverlayAction10[];
+} & Extensions;
+type Overlay11 = OverlayBase & {
+  readonly overlay: "1.1.0";
+  readonly actions: readonly OverlayAction[];
+} & Extensions;
+type Overlay12 = OverlayBase & {
+  readonly overlay: "1.2.0";
+  /** URI of this overlay and its base URI, without a fragment. */
+  readonly $self?: string;
+  readonly actions: readonly (OverlayAction | ReusableActionReference)[];
+  readonly components?: {
+    readonly actions?: Readonly<Record<string, ReusableAction>>;
+  } & Extensions;
+} & Extensions;
+/** An Overlay document of any supported version. */
+type Overlay = Overlay10 | Overlay11 | Overlay12;
+/**
+ * The JSONPath engine `applyOverlay` runs targets with. `paths` returns the RFC
+ * 9535 normalized paths (`$['paths']['/a'][0]`) of the selected nodes and
+ * throws for an invalid query. `loadJsonPath()` returns the `jsonpath-rfc9535`
+ * engine; any RFC 9535 implementation fits.
+ */
+interface JsonPathEngine {
+  paths(document: unknown, expression: string): readonly string[];
+}
+interface ApplyOverlayOptions {
+  readonly jsonpath: JsonPathEngine;
+  /** Accept targets that select nothing in every action. Default `false`. */
+  readonly allowEmpty?: boolean;
+}
+interface OverlayResult<T> {
+  /** A new document; the input is never changed. */
+  readonly document: T;
+  /**
+   * Errors, warnings and notes, in action order. Callers decide what fails a
+   * build.
+   */
+  readonly diagnostics: readonly SpecDiagnostic[];
+}
+//#endregion
+//#region src/overlay/apply.d.ts
+/**
+ * Applies an Overlay 1.0, 1.1 or 1.2 document to `document` and returns a new
+ * document. The input is cloned once with `structuredClone` and never changed;
+ * each target runs once through `options.jsonpath`.
+ *
+ * Actions run in order, each on the result of the previous one (Overlay §
+ * 4.5.1.1). `update` merges objects, concatenates or appends to arrays and
+ * replaces primitives; `remove` deletes the selected nodes; `copy` (1.1 and
+ * later) uses the value of the single node its query selects. Reusable action
+ * references (1.2) are expanded, with a warning when the overlay declares 1.0
+ * or 1.1.
+ *
+ * Problems never throw: they are diagnostics, and the failing action is
+ * skipped. A target that selects nothing reports `overlay-no-match` as an error
+ * unless the action sets `x-better-supabase-allow-empty: true` or the options
+ * set `allowEmpty`. The other codes are `overlay-invalid-target`,
+ * `overlay-invalid-action`, `overlay-mixed-targets`, `overlay-merge-conflict`,
+ * `overlay-copy-source`, `overlay-ref-unresolved`, `overlay-version-feature`,
+ * `overlay-version-unsupported` and `overlay-empty-action`.
+ *
+ * The result keeps the input's type; an overlay that changes the shape needs
+ * the caller to narrow it.
+ *
+ * @example
+ *   const jsonpath = await loadJsonPath();
+ *   const { document, diagnostics } = applyOverlay(openapi, overlay, {
+ *     jsonpath,
+ *   });
+ */
+export declare function applyOverlay<T>(document: T, overlay: Overlay, options: ApplyOverlayOptions): OverlayResult<T>;
+/**
+ * Applies overlays in order, each to the result of the previous one, with a
+ * single clone of the input. Diagnostic pointers start with the overlay's index
+ * (`/1/actions/0`).
+ */
+export declare function applyOverlays<T>(document: T, overlays: readonly Overlay[], options: ApplyOverlayOptions): OverlayResult<T>;
+//#endregion
+//#region src/overlay/define.d.ts
+/**
+ * What `defineOverlay` accepts: an Overlay document whose `overlay` field is
+ * optional.
+ */
+type OverlayInput = {
+  readonly overlay?: OverlayVersion;
+  readonly info: OverlayInfo;
+  readonly extends?: string;
+  readonly $self?: string;
+  readonly actions: readonly (OverlayAction | ReusableActionReference)[];
+  readonly components?: {
+    readonly actions?: Readonly<Record<string, ReusableAction>>;
+  } & Extensions;
+} & Extensions;
+type UsesOverlay12<I extends OverlayInput> = I extends {
+  readonly components: object;
+} ? true : I extends {
+  readonly $self: string;
+} ? true : [Extract<I["actions"][number], {
+  readonly $ref: string;
+}>] extends [never] ? false : true;
+/** The document type `defineOverlay` returns for an input. */
+type DefinedOverlay<I extends OverlayInput> = I extends {
+  readonly overlay: "1.0.0";
+} ? Overlay10 : I extends {
+  readonly overlay: "1.1.0";
+} ? Overlay11 : I extends {
+  readonly overlay: "1.2.0";
+} ? Overlay12 : UsesOverlay12<I> extends true ? Overlay12 : Overlay11;
+/**
+ * Defines an Overlay document with checks a schema cannot make. `overlay`
+ * defaults to `1.1.0`, or to `1.2.0` when the input uses a 1.2 feature
+ * (`components`, `$self` or a reusable action reference), and the return type
+ * follows it.
+ *
+ * Throws a `TypeError` when there are no actions, when a feature needs a newer
+ * version than the one set (`copy` needs 1.1, reusable actions and `$self` need
+ * 1.2), when a reference names a missing reusable action, or when `extends` or
+ * `$self` contains a fragment.
+ *
+ * @example
+ *   const overlay = defineOverlay({
+ *     info: { title: "Public API", version: "1.0.0" },
+ *     actions: [
+ *       {
+ *         target: "$.paths['/customers'].get",
+ *         update: { summary: "List customers" },
+ *       },
+ *       { target: "$.paths[?@['x-internal'] == true]", remove: true },
+ *     ],
+ *   });
+ */
+export declare function defineOverlay<const I extends OverlayInput>(input: I): DefinedOverlay<I>;
+/**
+ * Turns an overlay into an equivalent Overlay 1.1 document for tools that do
+ * not read 1.2: every reusable action reference becomes a plain action, and
+ * `$self` and `components` are dropped. A reference that does not resolve is
+ * left out and reported as `overlay-ref-unresolved`.
+ */
+export declare function expandReusableActions(overlay: Overlay): {
+  readonly overlay: Overlay11;
+  readonly diagnostics: readonly SpecDiagnostic[];
+};
+//#endregion
+//#region src/overlay/diff.d.ts
+interface OverlayFromDiffOptions<V extends OverlayVersion> {
+  /** The Overlay version to write. Default `1.1.0`. */
+  readonly version?: V;
+  /** Default `{ title: "better-supabase changes", version: "1.0.0" }`. */
+  readonly info?: OverlayInfo;
+  readonly extends?: string;
+}
+type OverlayOf<V extends OverlayVersion> = V extends "1.0.0" ? Overlay10 : V extends "1.2.0" ? Overlay12 : Overlay11;
+/**
+ * Writes the Overlay that turns `base` into `enriched`, so other tools can
+ * reproduce what hooks and transforms changed. Targets use stable keys
+ * (`$.paths['/customers'].get`); array indexes appear only inside arrays of the
+ * same length.
+ *
+ * A deleted key becomes a `remove` action; added keys become one `update` on
+ * their parent; a changed primitive becomes an `update` on it (1.1 and later)
+ * or a `remove` and re-add (1.0). An array that only grew gets its new items
+ * appended; any other array change replaces the array. Applying the result to
+ * `base` gives a document equal to `enriched`, though replaced keys move to the
+ * end of their object.
+ *
+ * Throws a `TypeError` when the roots are not both objects, or when the two
+ * documents are equal (an overlay needs at least one action).
+ */
+export declare function overlayFromDiff<V extends OverlayVersion = "1.1.0">(base: unknown, enriched: unknown, options?: OverlayFromDiffOptions<V>): OverlayOf<V>;
+//#endregion
+//#region src/overlay/load.d.ts
+/**
+ * Loads the optional `jsonpath-rfc9535` peer, an RFC 9535 implementation that
+ * passes the JSONPath Compliance Test Suite, for `applyOverlay`. Rejects with
+ * an install message when the package is missing. The engine is loaded once per
+ * module; `importer` replaces the import in tests.
+ */
+export declare function loadJsonPath(importer?: () => Promise<unknown>): Promise<JsonPathEngine>;
+//#endregion
+export { type AnyArazzoDocument, type AnyAsyncApiDocument, type AnyDocumentFormat, type AnyOpenApiDocument, type Api, type ApiModel, type ApiOptions, type ApiSource, type ApplyOverlayOptions, type Arazzo10Document, type Arazzo11Document, type ArazzoDocument, type ArazzoDocuments, type ArazzoFormatOptions, type ArazzoInfo, type ArazzoOptions, type ArazzoSourceDescription, type ArazzoSourceOptions, type ArazzoStep, type ArazzoVersion, type ArazzoWorkflow, type AsyncApi30Document, type AsyncApi31Document, type AsyncApiComponents, type AsyncApiDocument, type AsyncApiDocuments, type AsyncApiInfo, type AsyncApiOptions, type AsyncApiVersion, type AuthWorkflowOptions, type BlockEventSchema, type BlockEventSchemas, type BuiltModel, type BuiltinWorkflowOptions, CLOUD_EVENT_TRAIT, type ChannelStep, type CloudEventsInput, type ComponentNameContext, type CriterionObject, type CustomSecurity, DEFAULT_ERRORS, type DataApiOperation, type DataApiOptions, type DefineApiOptions, type DefinedOverlay, type DiagnosticSeverity, type DocumentFormat, type DocumentOf, type EnrichHooks, type EventsOptions, type Extensions, type FormatVersion, type FunctionRouteOptions, type HttpMethod, type JsonObject, type JsonPathEngine, type JsonSchema, type LowerContext, type ModelBody, type ModelChannel, type ModelChannelOperation, type ModelContent, type ModelExample, type ModelInfo, type ModelMessage, type ModelMessageTrait, type ModelOperation, type ModelParameter, type ModelResponse, type ModelResponseOrRef, type ModelSecurityProfileRequirement, type ModelSecurityScheme, type ModelServer, type ModelStep, type ModelTag, type ModelWebhook, type ModelWorkflow, type OAuthFlow, OPENAPI_33_PREVIEW_VERSION, type OpenApi30Document, type OpenApi31Document, type OpenApi32Document, type OpenApi33PreviewDocument, type OpenApiComponents, type OpenApiDocument, type OpenApiDocuments, type OpenApiInfo, type OpenApiOptions, type OpenApiRenderOptions, type OpenApiRenderResult, type OpenApiSecurityRequirement, type OpenApiVersion, type OperationIdContext, type OperationSource, type OperationStep, type Overlay, type Overlay10, type Overlay11, type Overlay12, type OverlayAction, type OverlayAction10, type OverlayEngine, type OverlayFromDiffOptions, type OverlayInfo, type OverlayInput, type OverlayResult, type OverlayVersion, PROBLEM_SCHEMA, type ParameterLocation, type RenderOptions, type RenderResult, type RenderedArazzo, type RenderedAsyncApi, type RenderedOf, type RenderedOpenApi, type ResourceDescription, type ResourceInput, type ResourceOperation, type ResourceOperationIds, type ResourceOptions, type ResourcePlan, type ReusableAction, type ReusableActionFields, type ReusableActionReference, type RouteSpec, type ScalarPresetOptions, type SecurityPreset, type SecurityRequirement, type SerializeOptions, type SpecDiagnostic, type SpecReferenceOptions, type SpecReferenceResponseOptions, type SpecResponseOptions, type SpecUi, type SpecUiAssets, type StepCriterion, type StepParameter, type TableVerb, type TopicInput, type VersionOf, type VersionStatus, type WorkflowCallStep, type WorkflowInput, type WorkflowSource, type WorkflowStep, defineApi, defineDocumentFormat, topicsFrom };