better-supabase 0.7.1 → 0.9.0

package/dist/approvals-a2KmioBh.d.ts

@@ -0,0 +1,124 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { i as AuthorizationHooks, n as Approver } from "./authorization-hooks-DkmrnDX7.js";
+//#region src/blocks/approvals/approvals.d.ts
+interface ApprovalsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. */
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the request columns the app adds
+   * (`blocks.approvals.options.extraColumns`), keyed by column name. It
+   * types and parses them on every read, and validates them on `request`,
+   * which returns a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Approvals<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * The authorization hooks. `approverOf` sees every approve, reject and
+   * delegate with kind `<subject type>.<action>` and the subject id, after
+   * the SQL eligibility check, and can only refuse. Needs `approver`.
+   */
+  readonly authorization?: Pick<AuthorizationHooks, "approverOf">;
+  /** The signed-in user the transport runs as, for `approverOf`. */
+  readonly approver?: Approver;
+}
+type ApprovalStatus = "pending" | "approved" | "rejected" | "cancelled" | "expired";
+/** Who may decide a step. Any match is enough. */
+interface ApprovalApprovers {
+  readonly permission?: string;
+  readonly role?: string;
+  readonly team?: string;
+  readonly users?: readonly string[];
+}
+interface ApprovalStep {
+  readonly approvers: ApprovalApprovers;
+  readonly required: number;
+}
+interface ApprovalRequest {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly action: string;
+  readonly status: ApprovalStatus;
+  /** The current step, from 0. */
+  readonly step: number;
+  /** The policy's steps when the request was made. */
+  readonly steps: readonly ApprovalStep[];
+  readonly requestedBy?: string;
+  readonly reason?: string;
+  readonly payload: Readonly<Record<string, unknown>>;
+  readonly expiresAt?: Temporal.Instant;
+  readonly decidedAt?: Temporal.Instant;
+  readonly createdAt: Temporal.Instant;
+}
+interface ApprovalDecision {
+  readonly id: string;
+  readonly step: number;
+  readonly approver?: string;
+  readonly decision: "approved" | "rejected" | "delegated";
+  readonly delegateTo?: string;
+  readonly comment?: string;
+  readonly createdAt: Temporal.Instant;
+}
+/** A request with its decisions, from `get`. */
+interface ApprovalRequestDetail extends ApprovalRequest {
+  /** Whether the caller can decide the current step. */
+  readonly canDecide: boolean;
+  readonly decisions: readonly ApprovalDecision[];
+}
+interface ApprovalRequestInput {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** An action `options.policies` names for the subject type. */
+  readonly action: string;
+  readonly reason?: string;
+  /** Passed to the job the final approval enqueues. */
+  readonly payload?: Readonly<Record<string, unknown>>;
+}
+interface ApprovalListOptions {
+  /** `null` lists every status. Default: `pending`. */
+  readonly status?: ApprovalStatus | null;
+  /** Only requests whose current step the caller can decide. */
+  readonly assigned?: boolean;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly pageSize?: number;
+  /** Requests made before this time, for the next page. */
+  readonly before?: Temporal.Instant;
+}
+/** `F` is the extra request fields `options.fields` describes. */
+interface Approvals<F extends object = Record<never, never>> {
+  /** Files a request under the subject type's policy for the action. */
+  /** Keys besides the input's own are the request's extra columns. */
+  request(input: ApprovalRequestInput & Partial<F>): AsyncResult<ApprovalRequest & F>;
+  /** Approves the current step; the last step runs the policy's action. */
+  approve(id: string, comment?: string): AsyncResult<ApprovalRequest & F>;
+  /** Rejects the request. */
+  reject(id: string, comment?: string): AsyncResult<ApprovalRequest & F>;
+  /** Hands the caller's place on the current step to another member. */
+  delegate(id: string, userId: string, comment?: string): AsyncResult<ApprovalRequest & F>;
+  /** The requester or a manager closes a pending request. */
+  cancel(id: string): AsyncResult<ApprovalRequest & F>;
+  get(id: string): AsyncResult<ApprovalRequestDetail & F>;
+  /** Newest first. */
+  list(organizationId: string, options?: ApprovalListOptions): AsyncResult<readonly (ApprovalRequest & F)[]>;
+  /** Whether the subject's latest request for the action was approved. */
+  isApproved(subjectType: string, subjectId: string, action: string): AsyncResult<boolean>;
+}
+/** The `approvals` SQL module as typed calls. */
+declare function createApprovals<S extends StandardSchemaV1 | undefined = undefined>(options: ApprovalsOptions<S>): Approvals<FieldsOf<S>>;
+//#endregion
+export { ApprovalRequestDetail as a, ApprovalStep as c, createApprovals as d, ApprovalRequest as i, Approvals as l, ApprovalDecision as n, ApprovalRequestInput as o, ApprovalListOptions as r, ApprovalStatus as s, ApprovalApprovers as t, ApprovalsOptions as u };

package/dist/arazzo/index.d.ts

@@ -0,0 +1,255 @@
+import { D as ResourceOperation, a as JsonSchema, i as JsonObject, w as ModelWorkflow, x as ModelStep } from "../model-lUafmeBQ.js";
+import { c as SpecDiagnostic, r as DocumentFormat } from "../format-CNwSjXUU.js";
+import { o as StandardLike } from "../resource-B4ka8dDH.js";
+import { A as WorkflowSource, C as ApiSource, n as DefineApiOptions } from "../api-TG3jE5aO.js";
+import { t as SPEC_PINS } from "../spec-pins-Dqpml2dZ.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 };