better-supabase 0.7.1 → 0.8.0

package/dist/arazzo/index.d.ts

@@ -0,0 +1,255 @@
+import { C as ModelWorkflow, E as ResourceOperation, b as ModelStep, i as JsonSchema, r as JsonObject } from "../model-OgBxvk3N.js";
+import { c as SpecDiagnostic, r as DocumentFormat } from "../format-DTXdu8ya.js";
+import { o as StandardLike } from "../resource--vTrBe6I.js";
+import { A as WorkflowSource, C as ApiSource, n as DefineApiOptions } from "../api-Dnf2q-Ht.js";
+import { t as SPEC_PINS } from "../spec-pins-CwzDY25w.js";
+//#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/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/arazzo/index.d.ts
+export 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
+export type { AnyArazzoDocument, Arazzo10Document, Arazzo11Document, ArazzoDocument, ArazzoDocuments, ArazzoFormatOptions, ArazzoInfo, ArazzoSourceDescription, ArazzoSourceOptions, ArazzoStep, ArazzoVersion, ArazzoWorkflow, AuthWorkflowOptions, BuiltinWorkflowOptions, ChannelStep, CriterionObject, ModelStep, ModelWorkflow, OperationStep, ParameterLocation, RenderedArazzo, ResourceOperationIds, StepCriterion, StepParameter, WorkflowCallStep, WorkflowInput, WorkflowSource, WorkflowStep };