better-supabase 0.13.0 → 0.15.0

package/dist/approvals-Crutd4-o.d.ts

@@ -0,0 +1,129 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "./standard-DBV730sF.js";
+import { r as FieldsOf } from "./block-fields-BE7pInWZ.js";
+import { $ as RecordRef } from "./types-DFdg_4yN.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { a as BlockTenantOptions, r as BlockTemporalOptions } from "./block-helpers-CRpAHrp_.js";
+import { t as BlockTransport } from "./block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "./block-hooks-DZN2w69m.js";
+import { i as AuthorizationHooks, n as Approver } from "./authorization-hooks-Cs1vP_ej.js";
+//#region src/blocks/approvals/approvals.d.ts
+interface ApprovalsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions, BlockTenantOptions {
+  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 subject: RecordRef;
+  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 {
+  /** 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;
+  /** Only requests on this subject. */
+  readonly subject?: RecordRef;
+  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. `request` and
+ * `list` act in the block's `tenant`.
+ */
+interface Approvals<F extends object = Record<never, never>> {
+  /**
+   * Files a request on `subject` under its type's policy for the action. Keys
+   * besides the input's own are the request's extra columns.
+   */
+  request(subject: RecordRef, 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(options?: ApprovalListOptions): AsyncResult<readonly (ApprovalRequest & F)[]>;
+  /** Whether the subject's latest request for the action was approved. */
+  isApproved(subject: RecordRef, 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/assistant-CD_h8Vxx.d.ts

@@ -0,0 +1,157 @@
+import { b as DbError } from "./result-DZeA5KS6.js";
+import { i as AiMessage } from "./message-Bg4TKA12.js";
+import { E as AiRunStatus, F as AiUserMessageTrigger, _ as AiModerationAction, i as AiChat, u as AiChatRecord } from "./ai-chat-D1GuRnke.js";
+import { n as GatewayOptions } from "./gateway-options-BlVCqgb8.js";
+import { o as StreamStore } from "./store-CpheI-lN.js";
+import { i as CostBackfillPayload, t as AiUsage } from "./gateway-TD1pRfTP.js";
+import { LanguageModelUsage, ModelMessage, UIMessage, UIMessageChunk, UIMessageStreamOnEndCallback } from "ai";
+//#region src/ai-sdk/chat/assistant.d.ts
+/** Who asks, for one request. */
+interface AssistantContext {
+  /**
+   * The chat block for this request: the user's transport, and a service
+   * transport (`service`) for the writes only the server makes.
+   */
+  readonly chats: AiChat;
+  readonly userId: string;
+  readonly organizationId: string;
+  /**
+   * Keeps the function alive until the answer is stored, after the response is
+   * sent: `after` in Next.js, `ctx.waitUntil` on Workers and Vercel.
+   */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+}
+/** What `run` gets to generate one answer. */
+interface AssistantRunArgs {
+  readonly chat: AiChatRecord;
+  /** The model the request may use, after the catalog check. */
+  readonly model: string;
+  readonly messages: ModelMessage[];
+  /** The history the model sees, as UI messages. */
+  readonly uiMessages: UIMessage[];
+  /** Aborted by `stop()`; pass it to `streamText` or `agent.stream`. */
+  readonly abortSignal: AbortSignal;
+  /** Spend attribution for the AI Gateway (`gatewayOptions`). */
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+  readonly context: AssistantContext;
+}
+/** The part of a `streamText` or `agent.stream` result the assistant reads. */
+interface AssistantRunResult {
+  toUIMessageStream(options: {
+    originalMessages: UIMessage[];
+    generateMessageId: () => string;
+    onEnd: UIMessageStreamOnEndCallback<UIMessage>;
+    onError?: (error: unknown) => string;
+  }): ReadableStream<UIMessageChunk>;
+  readonly totalUsage?: PromiseLike<LanguageModelUsage>;
+  readonly providerMetadata?: PromiseLike<unknown>;
+}
+/** The verdict of a moderation hook. */
+interface AssistantModeration {
+  readonly action: AiModerationAction;
+  readonly category: string;
+  readonly score?: number;
+}
+/** What `onFinish` gets once the answer is stored. */
+interface AssistantFinish {
+  readonly chat: AiChatRecord;
+  readonly message: UIMessage;
+  readonly status: AiRunStatus;
+  readonly model: string;
+  readonly usage: AiUsage | undefined;
+  readonly context: AssistantContext;
+}
+interface AssistantOptions {
+  /** Where the answer's stream is kept, so a reload resumes it. */
+  readonly streams: StreamStore;
+  /** Starts the generation: `agent.stream(...)` or `streamText(...)`. */
+  readonly run: (args: AssistantRunArgs) => AssistantRunResult | PromiseLike<AssistantRunResult>;
+  /** The model when neither the request nor the chat names an allowed one. */
+  readonly defaultModel: string;
+  /**
+   * The quota check before a generation (`usageQuota(usage, meter)`); an error
+   * answers 429.
+   */
+  readonly quota?: (organizationId: string) => Promise<DbError | undefined>;
+  /** Checks the user's message; `block` answers 403, others are recorded. */
+  readonly moderate?: (input: {
+    readonly message: AiMessage;
+    readonly chat: AiChatRecord;
+  }) => Promise<AssistantModeration | undefined>;
+  /**
+   * Called with the cost backfill payload when the gateway hasn't reported a
+   * cost yet.
+   */
+  readonly enqueueCostBackfill?: (payload: CostBackfillPayload) => Promise<unknown>;
+  /** Called after the answer is stored, such as to record usage. */
+  readonly onFinish?: (finish: AssistantFinish) => void | Promise<void>;
+  /**
+   * What the stream is kept for: seconds or a Postgres interval. Defaults to
+   * one day.
+   */
+  readonly streamTtl?: number | string;
+  /** The `feature` tag of the gateway options. Defaults to `chat`. */
+  readonly feature?: string;
+  /** Turns a stream error into the message the client sees. */
+  readonly onError?: (error: unknown) => string;
+  /** Makes message and stream ids. Defaults to `crypto.randomUUID()`. */
+  readonly generateId?: () => string;
+}
+/** The body `useAssistant` sends. */
+interface AssistantRequestBody {
+  /** The chat id; the client may make it, and the chat is created on first use. */
+  readonly id: string;
+  readonly message: UIMessage;
+  readonly trigger?: AiUserMessageTrigger;
+  /** For `regenerate-message`, the answer to write again. */
+  readonly messageId?: string;
+  readonly model?: string;
+}
+/** A checked and stored user turn, ready for a model: what `prepare` returns. */
+interface AssistantTurn {
+  readonly chat: AiChatRecord;
+  /** The model the request may use, after the catalog check. */
+  readonly model: string;
+  /** The stored user message, which the answer is saved under. */
+  readonly parentId: string;
+  /** The history the model sees, as UI messages. */
+  readonly uiMessages: UIMessage[];
+  readonly messages: ModelMessage[];
+  /** Spend attribution for the AI Gateway (`gatewayOptions`). */
+  readonly providerOptions: {
+    readonly gateway: GatewayOptions;
+  };
+}
+interface Assistant {
+  /** Stores the user's message, starts the answer and streams it (SSE). */
+  respond(request: Request, context: AssistantContext): Promise<Response>;
+  /**
+   * The checks and writes before a generation, without one: parses the body
+   * `useAssistant` sends, creates the chat on first use, picks the model,
+   * moderates, checks the quota, stores the user's message and loads the
+   * history. Returns a problem response when one of them fails.
+   */
+  prepare(body: unknown, context: AssistantContext): Promise<AssistantTurn | Response>;
+  /** The running answer of `chatId` from the start, or 204 when none runs. */
+  resume(chatId: string, context: AssistantContext, options?: {
+    readonly fromIdx?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<Response>;
+  /**
+   * Asks the running answer to stop: 204 whether or not one runs, a problem
+   * when the user may not.
+   */
+  stop(chatId: string, context: AssistantContext): Promise<Response>;
+}
+/**
+ * A chat route for the AI SDK on the `ai-chat` block: `respond` stores the
+ * user's message, picks an allowed model, checks the quota, claims the chat's
+ * answer, runs the model and streams it while keeping a copy in the stream
+ * store; the answer and its usage are stored when it ends, even after the
+ * client left. `resume` replays it after a reload, `stop` ends it.
+ */
+declare function createAssistant(options: AssistantOptions): Assistant;
+//#endregion
+export { AssistantOptions as a, AssistantRunResult as c, AssistantModeration as i, AssistantTurn as l, AssistantContext as n, AssistantRequestBody as o, AssistantFinish as r, AssistantRunArgs as s, Assistant as t, createAssistant as u };

package/dist/astro/index.d.ts

@@ -1,10 +1,11 @@
-import { a as AnyModels, i as AnyFunctions } from "../types-DmshMaXz.js";
-import { t as BetterSupabase } from "../define-D0LSXmUP.js";
-import { M as StorageImageOptions } from "../index-CrAKHNJF.js";
-import { n as BetterServer } from "../server-types-D_cQ6OxZ.js";
-import { a as AuthorizedContext, l as Unwrapped, n as ActionParsed, o as BlockActionOptions, r as ActionResult, s as BlockRequireOptions } from "../kit-LeQGMzLH.js";
-import { t as RefusalRedirects } from "../refusal-BEyNVFy7.js";
-import { n as FrameworkOptions, r as LocalsResource, t as FrameworkLocals } from "../framework-CMeAuJts.js";
+import { O as AnyFunctions, k as AnyModels } from "../types-DFdg_4yN.js";
+import { l as PermissionRef, t as AnyAuthorizer } from "../authorizer-B6X09otb.js";
+import { t as BetterSupabase } from "../define-DFBnQyYg.js";
+import { n as BetterServer } from "../server-types-CFtehAsr.js";
+import { M as StorageImageOptions } from "../index-Do2ChN_y.js";
+import { a as AuthorizedContext, l as Unwrapped, n as ActionParsed, o as BlockActionOptions, r as ActionResult, s as BlockRequireOptions } from "../kit-DOwKpSkA.js";
+import { t as RefusalRedirects } from "../refusal-CSntB_x8.js";
+import { n as FrameworkOptions, r as LocalsResource, t as FrameworkLocals } from "../framework-BKyTeS-j.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/astro/index.d.ts
 /**
@@ -22,15 +23,15 @@ export interface AstroOptions extends FrameworkOptions {
    */
   readonly platformEnv?: (context: AstroContextLike) => unknown;
 }
-export interface BetterAstro<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown> extends BetterServer<M, F, E, C, P, B> {
+export interface BetterAstro<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string, B = unknown> extends BetterServer<M, F, E, C, P, B> {
   /**
    * Astro middleware: verifies the caller, refreshes the session cookie on
-   * navigations and form posts, and puts `db`, `bs`, `auth`, `tenant` and
+   * navigations and form posts, and puts `db`, `bsb`, `auth`, `tenant` and
    * `session` on `locals`. Response-phase entries see the page's response.
    *
    * ```ts
    * // src/middleware.ts
-   * export const onRequest = bs.onRequest;
+   * export const onRequest = bsb.onRequest;
    * ```
    */
   readonly onRequest: (context: AstroContextLike, next: () => Promise<Response>) => Promise<Response>;
@@ -43,17 +44,17 @@ export interface BetterAstro<M extends AnyModels, F extends AnyFunctions, E, C =
    *
    * ```astro
    * ---
-   * const refused = await bs.guard(Astro, { roles: ['admin'] })
+   * const refused = await bsb.guard(Astro, { roles: ['admin'] })
    * if (refused) return refused
    * ---
    * ```
    */
-  guard(context: AstroContextLike, options?: BlockRequireOptions<C, P, boolean, unknown, LocalsResource<M, F, E, C, P, B>>): Promise<Response | undefined>;
+  guard(context: AstroContextLike, options?: BlockRequireOptions<C, P, boolean, Ref, LocalsResource<M, F, E, C, P, B>>): Promise<Response | undefined>;
   /**
    * The caller, or a thrown refusal `Response`, for endpoints that return
    * whatever is thrown.
    */
-  require<R extends boolean = false>(context: AstroContextLike, options?: BlockRequireOptions<C, P, R, unknown, LocalsResource<M, F, E, C, P, B>>): Promise<FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>>;
+  require<R extends boolean = false>(context: AstroContextLike, options?: BlockRequireOptions<C, P, R, Ref, LocalsResource<M, F, E, C, P, B>>): Promise<FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>>;
   /**
    * The `handler` of `defineAction`, returning an `ActionResult`:
    *
@@ -62,17 +63,19 @@ export interface BetterAstro<M extends AnyModels, F extends AnyFunctions, E, C =
    * export const server = {
    *   addNote: defineAction({
    *     accept: "form",
-   *     handler: bs.action({ input: NoteInput }, (input, { db }) =>
+   *     handler: bsb.action({ input: NoteInput }, (input, { db }) =>
    *       db.notes.create(input),
    *     ),
    *   }),
    * };
    * ```
    */
-  action<S extends StandardSchemaV1 | undefined, T, R extends boolean = false>(options: BlockActionOptions<S, C, P, R, unknown, LocalsResource<M, F, E, C, P, B>>, fn: (input: ActionParsed<S>, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>) => T): (input: unknown, context: AstroContextLike) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
+  action<S extends StandardSchemaV1 | undefined, T, R extends boolean = false>(options: BlockActionOptions<S, C, P, R, Ref, LocalsResource<M, F, E, C, P, B>>, fn: (input: ActionParsed<S>, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>) => T): (input: unknown, context: AstroContextLike) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
 }
 /** Astro integration: middleware, page guards and Actions. */
-export declare function createAstro<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P, B>, options?: AstroOptions): BetterAstro<M, F, E, C, P, B>;
+export declare function createAstro<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, A extends AnyAuthorizer | undefined = undefined, B = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P, B>, options?: AstroOptions & {
+  readonly authorizer?: A;
+}): BetterAstro<M, F, E, C, P, PermissionRef<A>, B>;
 /** What Astro passes to an image service's `getURL`. */
 export interface AstroImageTransform {
   readonly src: string | {

package/dist/astro/index.js

@@ -1,10 +1,10 @@
 import { i as storageImageUrl } from "../image-url-_d7xYsXK.js";
-import { c as extendServer, n as flushEvents, s as createServer } from "../adapter-D8dW6p2A.js";
-import { t as defaultExpose } from "../respond-DjEmE_DN.js";
-import { i as requireCaller, o as runAction } from "../kit-BeXTrlZn.js";
+import { c as extendServer, n as flushEvents, s as createServer } from "../adapter-B0b6MXYS.js";
+import { t as defaultExpose } from "../respond-C3CcOZlA.js";
+import { i as requireCaller, o as runAction } from "../kit-5l-o8RxL.js";
 import { t as around } from "../shared-Bf-I13Ht.js";
-import { i as localsOf, r as frameworkEntry } from "../framework-BpEnOfAo.js";
-import { r as refusalResponse } from "../refusal-Ce2p81VW.js";
+import { i as localsOf, r as frameworkEntry } from "../framework-DDdkR7FX.js";
+import { r as refusalResponse } from "../refusal-ByBZcm0V.js";
 //#region src/astro/index.ts
 function runtimeEnv(locals) {
 	const runtime = "runtime" in locals ? locals.runtime : void 0;
@@ -16,14 +16,14 @@ function createAstro(betterSupabase, options = {}) {
 	const expose = options.exposeErrors ?? defaultExpose();
 	const run = around([frameworkEntry(server, options, expose)]);
 	const scopeOf = (context) => {
-		if (!("bs" in context.locals)) throw new TypeError("better-supabase: no context; export bs.onRequest from src/middleware.ts");
+		if (!("bsb" in context.locals)) throw new TypeError("better-supabase: no context; export bsb.onRequest from src/middleware.ts");
 		return context.locals;
 	};
 	const refusalOf = async (context, requireOptions) => {
 		const scope = scopeOf(context);
 		return {
 			scope,
-			caller: await requireCaller(scope.bs.auth, requireOptions, scope.tenant, options.authorizer, scope)
+			caller: await requireCaller(scope.bsb.auth, requireOptions, scope.tenant, options.authorizer, scope)
 		};
 	};
 	return extendServer(server, {
@@ -54,7 +54,7 @@ function createAstro(betterSupabase, options = {}) {
 		action(actionOptions, fn) {
 			return async (input, context) => {
 				const scope = scopeOf(context);
-				return await runAction(scope.bs.auth, actionOptions, input, scope.tenant, (parsed, caller) => fn(parsed, {
+				return await runAction(scope.bsb.auth, actionOptions, input, scope.tenant, (parsed, caller) => fn(parsed, {
 					...scope,
 					...caller
 				}), options.authorizer, scope);