better-supabase 0.13.0 → 0.14.0

package/dist/outbox-CsF_iKjx.d.ts

@@ -0,0 +1,199 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CursorPageOptions, n as BlockOptions } from "./block-helpers-BaugZlJV.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { t as BlockProblemOptions } from "./problem-DpHB7tWl.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-SPyXMdcd.js";
+import { g as SubscriberPolicy, i as AuthorizationHooks } from "./authorization-hooks-dLmUO_PZ.js";
+//#region src/blocks/outbox/outbox.d.ts
+/** One row of the outbox, as `outbox_claim` and `outbox_history` return it. */
+interface OutboxEvent {
+  /** The cursor value: increases with every event. */
+  readonly position: number;
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  /**
+   * The module or function that wrote it, e.g.
+   * `better-supabase/blocks/organizations`.
+   */
+  readonly source: string | null;
+  readonly subject: string | null;
+  readonly tenant: string | null;
+  readonly key: string | null;
+  readonly actorId: string | null;
+  readonly createdAt: Temporal.Instant;
+}
+interface EmitOptions {
+  readonly subject?: string;
+  readonly tenant?: string;
+  /** With a key, emitting again (per tenant) returns the first event. */
+  readonly key?: string;
+  readonly source?: string;
+}
+/**
+ * `transport` writes (`emit`) and reads (`history`); `service`, which defaults
+ * to `transport`, runs the consumer calls (`register`, `relay`, `consume`,
+ * `deadLetters`, `purge`), which need the service role.
+ */
+interface OutboxOptions extends BlockOptions {
+  /** CloudEvents `source` of the relayed events, e.g. `https://crm.example.com`. */
+  readonly source: string;
+  /**
+   * Prepended to each type with a dot when relaying, e.g. `com.example`.
+   * Defaults to `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /**
+   * Decides, per event, whether a consumer gets it. The consumer is the
+   * subscriber `{ principal: <consumer name>, kind: "service" }`. An event it
+   * leaves out is skipped and the cursor moves past it; a throw counts as a
+   * failed attempt. Defaults to `authorization.delivery.subscribers`.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** `server.authorization`, for its `delivery.subscribers` policy. */
+  readonly authorization?: Pick<AuthorizationHooks, "delivery">;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Outbox>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface RegisterOptions {
+  /**
+   * Type patterns such as `organization.*` or `invoice.paid`. Defaults to every
+   * event.
+   */
+  readonly types?: readonly string[];
+  /** Start at the first kept event instead of after the latest one. */
+  readonly fromStart?: boolean;
+}
+interface RelayOptions {
+  /** Events per claim and per `sink.send`. Defaults to 100. */
+  readonly batch?: number;
+  /** How long a claim holds the consumer. Defaults to `1 minute`. */
+  readonly lease?: string;
+  /** Stops claiming after this many milliseconds. */
+  readonly budgetMs?: number;
+  /** Identifies this worker in the lease. Defaults to a random id. */
+  readonly owner?: string;
+  /**
+   * Failures in a row before the event that keeps failing goes to the dead
+   * letters and the cursor moves past it. Defaults to 10.
+   */
+  readonly maxAttempts?: number;
+  /** The longest wait between failed attempts. Defaults to `10 minutes`. */
+  readonly maxBackoff?: string;
+}
+interface RelayResult {
+  /** Events handed to the sink or handler. */
+  readonly delivered: number;
+  /**
+   * Events the `subscribers` policy kept from the consumer, when there were
+   * any.
+   */
+  readonly refused?: number;
+  /**
+   * Set when the sink threw: the consumer backs off and retries the batch one
+   * event at a time.
+   */
+  readonly error?: DbError;
+  /** 1 when this run moved the failing event to the dead letters. */
+  readonly deadLettered?: number;
+}
+/** An event a consumer skipped after `maxAttempts` failures. */
+interface OutboxDeadLetter {
+  readonly consumer: string;
+  readonly event: OutboxEvent;
+  readonly attempts: number;
+  readonly error: string | null;
+  readonly deadAt: Temporal.Instant;
+}
+interface OutboxPurgeOptions {
+  /**
+   * A consumer that hasn't claimed for this long (a Postgres interval such as
+   * `30 days`) no longer holds events back. Defaults to waiting for every
+   * consumer.
+   */
+  readonly ignoreIdle?: string;
+}
+/**
+ * Takes a batch of outbox rows, with the actor and tenant that CloudEvents
+ * leave out. Throwing counts a failed attempt: the consumer backs off, then
+ * retries one event at a time until the event that fails goes to the dead
+ * letters.
+ */
+type OutboxHandler = (events: readonly OutboxEvent[]) => unknown;
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner">, BlockProblemOptions {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /**
+   * Consumer name to the sink its events go to, or a handler that takes the
+   * rows.
+   */
+  readonly consumers: Readonly<Record<string, EventSink | OutboxHandler>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter extends CursorPageOptions<number> {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly cursor?: number;
+  readonly limit?: number;
+}
+interface Outbox {
+  /** Writes an event in the current transaction and returns its id. */
+  emit(type: string, payload?: unknown, options?: EmitOptions): AsyncResult<string>;
+  /** Creates the consumer, or changes its types. Returns its cursor position. */
+  register(consumer: string, options?: RegisterOptions): AsyncResult<number>;
+  /** Removes the consumer, so purges stop waiting for it. */
+  unregister(consumer: string): AsyncResult<boolean>;
+  /**
+   * Claims the consumer's next events, sends them to `sink` as CloudEvents and
+   * moves the cursor, until none are left or the budget runs out. A sink that
+   * throws leaves the batch for a later run with backoff, so delivery is at
+   * least once; an event that fails `maxAttempts` times goes to the dead
+   * letters.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * Like `relay`, but hands `handler` the outbox rows themselves, with
+   * `actorId`, `tenant` and `key`, for consumers inside the app (search
+   * indexing, notifications) that need the actor.
+   */
+  consume(consumer: string, handler: OutboxHandler, options?: RelayOptions): Promise<RelayResult>;
+  /**
+   * A `GET`/`POST` handler for a cron that relays every consumer at once,
+   * within one budget.
+   */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /** The consumer's dead letters, newest first (default 100, at most 1000). */
+  deadLetters(consumer: string, limit?: number): AsyncResult<readonly OutboxDeadLetter[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed, and dead letters older than `olderThan`. Call it
+   * again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number, options?: OutboxPurgeOptions): AsyncResult<number>;
+}
+/**
+ * The CloudEvent for an outbox row: the row id as `id` (stable, so receivers
+ * can deduplicate), the payload as `data`, the tenant as `partitionkey` and the
+ * writing module as `producer`. The actor stays out of the context attributes,
+ * which must not carry personal data.
+ */
+declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+/**
+ * The outbox over a `BlockTransport`: `sqlTransport(postgres)` on a server
+ * connection, where `emit` joins the caller's transaction, or
+ * `rpcTransport(serviceClient)` for apps that reach the database only through
+ * the Data API, where `emit` writes in its own transaction.
+ */
+declare function createOutbox(options: OutboxOptions): Outbox;
+//#endregion
+export { OutboxEvent as a, OutboxPurgeOptions as c, RegisterOptions as d, RelayOptions as f, outboxCloudEvent as h, OutboxDeadLetter as i, OutboxRouteOptions as l, createOutbox as m, HistoryFilter as n, OutboxHandler as o, RelayResult as p, Outbox as r, OutboxOptions as s, EmitOptions as t, OutboxRouteResult as u };

package/dist/payments-BtScsgPS.js

@@ -0,0 +1,16 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { c as isMoney } from "./money-BZl985O-.js";
+//#region src/commerce/payments.ts
+/** Checks the provider's `apiVersion` before a block uses it. */
+function paymentProviderOf(provider) {
+	const version = provider.apiVersion;
+	if (version !== 1) throw new TypeError(`payments "${provider.name}" targets payment provider API ${String(version)}; this better-supabase supports 1. Upgrade better-supabase or use a release of the provider for API 1.`);
+	return provider;
+}
+/** The error for an amount a payment can't carry: not money, or not above zero. */
+function invalidPaymentAmount(amount) {
+	if (!isMoney(amount)) return dbError("invalid_input", "A payment amount is Money: a bigint of minor units and an ISO 4217 currency", { hint: "PAYMENT_AMOUNT_INVALID" });
+	if (amount.amount <= 0n) return dbError("invalid_input", "A payment amount must be more than zero", { hint: "PAYMENT_AMOUNT_INVALID" });
+}
+//#endregion
+export { paymentProviderOf as n, invalidPaymentAmount as t };

package/dist/payments-CBzQIjoX.d.ts

@@ -0,0 +1,114 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-C6jDfedy.js";
+import { n as Money } from "./money-BNRdJQzA.js";
+import { r as WebhookInput } from "./signatures-zbu6KTNQ.js";
+//#region src/commerce/payments.d.ts
+/**
+ * Where a payment stands. `requires_action`: the customer still has to act
+ * (pick a method, confirm, pass 3-D Secure). `authorized`: the funds are held
+ * and wait for `capture`.
+ */
+type PaymentStatus = "requires_action" | "processing" | "authorized" | "succeeded" | "failed" | "canceled";
+interface Payment {
+  /** The provider's id, stored with the order as its payment reference. */
+  readonly id: string;
+  /** The provider's `name`. */
+  readonly provider: string;
+  readonly status: PaymentStatus;
+  readonly amount: Money;
+  /** What was captured so far; zero until the payment succeeds. */
+  readonly captured: Money;
+  /** What was refunded so far. */
+  readonly refunded: Money;
+  /** The order or cart the payment is for, as `createPayment` got it. */
+  readonly reference: string;
+  /**
+   * The secret a client confirms the payment with (Stripe's `client_secret`).
+   * Hand it to the paying browser only; never store or log it.
+   */
+  readonly clientSecret?: string;
+  /** Where to send the customer to finish, when the provider redirects. */
+  readonly redirectUrl?: string;
+  readonly metadata: Readonly<Record<string, string>>;
+}
+interface CreatePaymentInput {
+  /** More than zero, in a currency the provider charges. */
+  readonly amount: Money;
+  /** The order or cart this pays for. Webhook events carry it back. */
+  readonly reference: string;
+  /** `manual` holds the funds until `capture`. Defaults to `automatic`. */
+  readonly capture?: "automatic" | "manual";
+  /** The provider's customer id. */
+  readonly customer?: string;
+  readonly description?: string;
+  /** Where a redirecting payment method returns the customer. */
+  readonly returnUrl?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+interface PaymentCallOptions {
+  /** The same key returns the first call's result instead of paying twice. */
+  readonly idempotencyKey?: string;
+  readonly signal?: AbortSignal;
+}
+type RefundStatus = "pending" | "succeeded" | "failed" | "canceled";
+interface Refund {
+  readonly id: string;
+  readonly paymentId: string;
+  readonly amount: Money;
+  readonly status: RefundStatus;
+}
+interface RefundInput {
+  /** Defaults to what is left of the captured amount. */
+  readonly amount?: Money;
+  readonly reason?: string;
+}
+type PaymentEventType = "payment.requires_action" | "payment.processing" | "payment.authorized" | "payment.succeeded" | "payment.failed" | "payment.canceled" | "refund.succeeded" | "refund.failed";
+/** A provider's webhook event in one shape for every provider. */
+interface PaymentEvent {
+  /**
+   * The provider's event id. A redelivered event repeats it, so key the
+   * handling on it (the webhook inbox and the `idempotency` module do).
+   */
+  readonly id: string;
+  readonly type: PaymentEventType;
+  readonly paymentId: string;
+  /** The payment's `reference`, when the event carries it. */
+  readonly reference?: string;
+  /** The payment's amount, or the refund's for `refund.*`. */
+  readonly amount?: Money;
+  readonly refundId?: string;
+  readonly occurredAt: Temporal.Instant;
+}
+/**
+ * Takes payments for orders. Versioned: a breaking change ships a new
+ * `apiVersion`. Every method returns a `Result`: `invalid_input` for an amount
+ * the provider can't charge or a refund above what was captured, `not_found`
+ * for an unknown payment, `unauthorized` for a webhook whose signature fails,
+ * and `raised` with the hint `PAYMENT_DECLINED` when the provider declines.
+ */
+interface PaymentProvider {
+  readonly apiVersion: 1;
+  readonly name: string;
+  createPayment(input: CreatePaymentInput, options?: PaymentCallOptions): AsyncResult<Payment>;
+  /** Captures an authorized payment, all of it unless `amount` is less. */
+  capture(paymentId: string, input?: {
+    readonly amount?: Money;
+  }, options?: PaymentCallOptions): AsyncResult<Payment>;
+  refund(paymentId: string, input?: RefundInput, options?: PaymentCallOptions): AsyncResult<Refund>;
+  /**
+   * Verifies a webhook delivery with the provider's secret and returns its
+   * events, none for types the contract doesn't cover.
+   */
+  parseWebhook(input: WebhookInput): AsyncResult<readonly PaymentEvent[]>;
+  /** Releases a payment that was not captured yet. */
+  cancel?(paymentId: string, options?: PaymentCallOptions): AsyncResult<Payment>;
+  get?(paymentId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<Payment>;
+}
+/** Checks the provider's `apiVersion` before a block uses it. */
+declare function paymentProviderOf(provider: PaymentProvider): PaymentProvider;
+/** The error for an amount a payment can't carry: not money, or not above zero. */
+declare function invalidPaymentAmount(amount: unknown): DbError | undefined;
+//#endregion
+export { PaymentEventType as a, Refund as c, invalidPaymentAmount as d, paymentProviderOf as f, PaymentEvent as i, RefundInput as l, Payment as n, PaymentProvider as o, PaymentCallOptions as r, PaymentStatus as s, CreatePaymentInput as t, RefundStatus as u };

package/dist/permissions-BetA_Fo_.js

@@ -0,0 +1,34 @@
+//#region src/blocks/access/permissions.ts
+/**
+* Whether a granted key covers a wanted one: the same rule as the SQL
+* `permission_matches`, where `*` grants every key and `prefix.*` every key
+* under `prefix`.
+*/
+function permissionMatches(granted, wanted) {
+	return granted === "*" || granted === wanted || granted.endsWith(".*") && wanted.startsWith(granted.slice(0, -1));
+}
+/**
+* Whether `set` holds `key`. UX only: RLS and the SQL functions check the key
+* again.
+*
+* ```ts
+* if (can(permissionSet, permissions.customers.write)) showEditButton();
+* ```
+*/
+function can(set, key) {
+	return set?.keys.some((granted) => permissionMatches(granted, key)) ?? false;
+}
+/**
+* One `can<Name>` boolean per entry of `flags`, for a payload query that
+* returns data and what the caller may do with it.
+*
+* ```ts
+* permissionFlags(set, { edit: permissions.customers.write });
+* // { canEdit: true }
+* ```
+*/
+function permissionFlags(set, flags) {
+	return Object.fromEntries(Object.entries(flags).map(([name, key]) => [`can${name.charAt(0).toUpperCase()}${name.slice(1)}`, can(set, key)]));
+}
+//#endregion
+export { permissionFlags as n, permissionMatches as r, can as t };

package/dist/plugin-Ar5546xh.d.ts

@@ -0,0 +1,202 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper } from "./result-C6jDfedy.js";
+import { N as AnyModels, _ as MutationOp, g as MutationKind, h as MutationIntent, ht as TableMeta, lt as SchemaMeta, pt as TableFlags, r as Executor, v as Operation } from "./executor-CPyrQdjh.js";
+//#region src/core/plugin.d.ts
+/** Who is making the request. */
+interface Actor {
+  readonly id: string;
+  readonly kind: "user" | "service" | "anon";
+  readonly role?: string;
+  readonly email?: string;
+  /** The admin acting as this user (the `act` claim's `sub`). */
+  readonly impersonator?: string;
+}
+/**
+ * Per-connection context. Server adapters fill it from the verified JWT;
+ * plugins read it (`tenant()` reads `tenant`, `actor()` reads `actor`).
+ */
+interface RequestContext {
+  readonly actor?: Actor;
+  readonly tenant?: string;
+  readonly claims?: Readonly<Record<string, unknown>>;
+  readonly [key: string]: unknown;
+}
+/** Plugin-specific per-call options (`withDeleted`, `hard`, ...). */
+type CallOptions = Readonly<Record<string, unknown>>;
+interface HookArgs {
+  readonly table: TableMeta;
+  readonly schema: SchemaMeta;
+  readonly context: RequestContext;
+  readonly options: CallOptions;
+  readonly now: () => Temporal.Instant;
+  /**
+   * The caller's `signal`, when it passed one. Hooks that do I/O should honor
+   * it.
+   */
+  readonly signal?: AbortSignal;
+}
+interface MutationEvent {
+  readonly table: TableMeta;
+  /** The statement that ran. */
+  readonly kind: MutationKind;
+  /**
+   * What the caller asked for; differs from `kind` when a plugin rewrote the
+   * mutation.
+   */
+  readonly intent?: MutationIntent;
+  /**
+   * App-cased rows returned by the mutation. A copy: changing it never changes
+   * the result.
+   */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * App-cased primary keys of the changed rows, when they are known: from the
+   * returned rows, or from a `where` on the primary key when nothing is
+   * returned (soft deletes, `returning: false`).
+   */
+  readonly keys?: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * The tenant of the write: `context.tenant`, which `tenant()` fills from the
+   * claims.
+   */
+  readonly tenant?: string;
+  readonly context: RequestContext;
+}
+/** Runtime handle passed to `Plugin.repository`. */
+interface RepositoryApi {
+  readonly table: TableMeta;
+  readonly base: Readonly<Record<string, (...args: never[]) => unknown>>;
+}
+/**
+ * Type-level repository extension, applied per table. Implement it as an
+ * interface that reads `this['M']` and `this['T']`:
+ *
+ * ```ts
+ * interface RestoreExtension extends RepositoryExtension {
+ *   readonly methods: HasFlag<
+ *     this["M"],
+ *     this["T"],
+ *     "softDelete"
+ *   > extends true
+ *     ? { restore(id: string): AsyncResult<unknown> }
+ *     : unknown;
+ * }
+ * ```
+ */
+interface RepositoryExtension {
+  readonly M: AnyModels;
+  readonly T: string;
+  readonly methods: unknown;
+  readonly findArgs: unknown;
+  readonly deleteArgs: unknown;
+}
+/**
+ * Applies the extensions in `E` to table `T`. `E` is a tuple of extensions (as
+ * built by `use()`) or a single extension. Each is applied on its own because
+ * indexing an intersection of `this`-typed interfaces overflows TS < 7.
+ */
+/** Default extension of plugins that add no repository types. */
+interface NoExtension extends RepositoryExtension {
+  readonly "~none": true;
+}
+type ApplyExtension<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends readonly [infer Head, ...infer Rest] ? ApplyOne<Head, M, T, K> & ApplyExtension<Rest, M, T, K> : ApplyOne<E, M, T, K>;
+type ApplyOne<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends RepositoryExtension ? (E & {
+  readonly M: M;
+  readonly T: T;
+})[K] : unknown;
+/** True when table `T` has the flag set by codegen. */
+type HasFlag<M, T, F extends string> = M extends AnyModels ? T extends keyof M ? M[T]["Flags"] extends { readonly [K in F]: unknown; } ? true : false : false : false;
+/** A parameter a plugin adds to the operations of a table in the API spec. */
+interface DescribeParameter {
+  readonly name: string;
+  readonly in: "query" | "header" | "cookie";
+  readonly required?: boolean;
+  readonly description?: string;
+  /** JSON Schema 2020-12. */
+  readonly schema: Readonly<Record<string, unknown>>;
+}
+/**
+ * What `Plugin.describe` can change in the API model `defineApi` builds. Every
+ * method ignores tables and columns the API does not serve.
+ */
+interface PluginDescribeApi {
+  readonly schema: SchemaMeta;
+  /** Prefix of generated `x-` fields, e.g. `x-better-supabase-`. */
+  readonly extensionPrefix: string;
+  /** The served tables, with the names of their operations and actions. */
+  readonly resources: readonly {
+    readonly table: TableMeta;
+    readonly operations: readonly string[];
+  }[];
+  /** Adds a parameter to the table's operations, or to the named ones. */
+  addParameter(table: string, parameter: DescribeParameter, operations?: readonly string[]): void;
+  /**
+   * Marks a column `readOnly` in the table's schemas and drops it from the
+   * required fields of request bodies. `description` is used when the column
+   * has none.
+   */
+  markReadOnly(table: string, column: string, description?: string): void;
+  /** Deep-merges JSON Schema fields into the column's schemas. */
+  describeColumn(table: string, column: string, patch: Readonly<Record<string, unknown>>): void;
+}
+declare const PLUGIN_API_VERSION = 1;
+/** Plugin API v1. Every hook is optional. Hooks run in `use()` order. */
+interface Plugin<Name extends string = string, Ext extends RepositoryExtension = NoExtension> {
+  readonly apiVersion: 1;
+  readonly name: Name;
+  /**
+   * Hook order: `first`, then `pre`, then unmarked plugins, then `post`;
+   * plugins at the same level keep `use()` order. `first` is for plugins that
+   * check the query as the caller wrote it, before a `pre` plugin rewrites it
+   * (`rules()`). Validation is `post` so it sees columns other plugins fill.
+   */
+  readonly enforce?: "first" | "pre" | "post";
+  /**
+   * The table flags whose tables this plugin's `transformQuery` filters
+   * (`tenant()` declares `['tenant']`). Read sets warn when they read such a
+   * table, because their generated SQL function runs without the plugin. `[]`
+   * means the plugin only inspects queries. A plugin with `transformQuery` that
+   * leaves this out is assumed to filter every table.
+   */
+  readonly scopes?: readonly (keyof TableFlags)[];
+  /**
+   * `context`: derive values from the connection's context once per `connect()`
+   * and `$with()`, so `db.$context` carries them (`tenant()` adds the tenant it
+   * resolved). Runs in hook order on the context the caller passed. A throw is
+   * logged and leaves the context unchanged.
+   */
+  readonly context?: (context: RequestContext, args: {
+    readonly schema: SchemaMeta;
+  }) => RequestContext;
+  /** `ir`: rewrite an operation before it runs (filters, defaults). */
+  readonly transformQuery?: (op: Operation, args: HookArgs) => Operation;
+  /** `mutation`: rewrite a mutation or reject it by throwing a `DbException`. */
+  readonly beforeMutation?: (op: MutationOp, args: HookArgs) => MutationOp | Promise<MutationOp>;
+  /** `mutation`: observe a finished mutation. Cannot change the result. */
+  readonly afterMutation?: (event: MutationEvent) => void | Promise<void>;
+  /** `execute`: wrap the executor for tracing, caching or retries. */
+  readonly wrapExecutor?: (executor: Executor) => Executor;
+  /** `errors`: map custom SQLSTATE or hint codes to `DbError`s. */
+  readonly mapError?: ErrorMapper;
+  /** `repository`: add methods to the repositories of matching tables. */
+  readonly repository?: (api: RepositoryApi) => Readonly<Record<string, (...args: never[]) => unknown>> | undefined;
+  /**
+   * `spec`: describe what the plugin does to the served tables in the API model
+   * (`defineApi`, `createOpenApi`): parameters it reads, columns it manages. A
+   * throw is reported as `plugin-describe-failed`.
+   */
+  readonly describe?: (api: PluginDescribeApi) => void;
+  /** Phantom carrying the repository extension type. */
+  readonly "~ext"?: Ext;
+}
+type AnyPlugin = Plugin<string, any>;
+/** The plugin's repository extension; `unknown` for plugins that add none. */
+type ExtensionOf<P> = P extends Plugin<string, infer E> ? E extends NoExtension ? unknown : E : never;
+/** `E` with extension `X` appended, as a tuple. */
+type WithExtension<E, X> = unknown extends X ? E : E extends readonly unknown[] ? readonly [...E, X] : unknown extends E ? readonly [X] : readonly [E, X];
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+declare function definePlugin<const Name extends string, Ext extends RepositoryExtension = NoExtension>(plugin: Omit<Plugin<Name, Ext>, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): Plugin<Name, Ext>;
+//#endregion
+export { ExtensionOf as a, MutationEvent as c, Plugin as d, RepositoryApi as f, definePlugin as g, WithExtension as h, CallOptions as i, NoExtension as l, RequestContext as m, AnyPlugin as n, HasFlag as o, RepositoryExtension as p, ApplyExtension as r, HookArgs as s, Actor as t, PLUGIN_API_VERSION as u };

package/dist/plugins/actor/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Plugin, m as RequestContext } from "../../plugin-DouW0Kvg.js";
+import { d as Plugin, m as RequestContext } from "../../plugin-Ar5546xh.js";
 //#region src/plugins/actor/index.d.ts
 export interface ActorOptions {
   /**

package/dist/plugins/actor/index.js

@@ -1,5 +1,5 @@
 import { r as definePlugin } from "../../plugin-D9bYbYli.js";
-import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-C80IHf4B.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-LmlfYPv4.js";
 //#region src/plugins/actor/index.ts
 function defaultActor(context) {
 	const actor = context.actor;

package/dist/plugins/rules/index.d.ts

@@ -1,5 +1,5 @@
-import { v as Operation } from "../../executor-C29668fO.js";
-import { d as Plugin, p as RepositoryExtension } from "../../plugin-DouW0Kvg.js";
+import { v as Operation } from "../../executor-CPyrQdjh.js";
+import { d as Plugin, p as RepositoryExtension } from "../../plugin-Ar5546xh.js";
 //#region src/plugins/rules/index.d.ts
 export type RuleLevel = "off" | "warn" | "error";
 /** A level, or a level with the rule's option: `['error', 500]`. */

package/dist/plugins/rules/index.js

@@ -1,5 +1,5 @@
-import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-D7u24ZJH.js";
+import { t as DbException } from "../../db-exception-Lngc1W49.js";
+import { n as dbError } from "../../errors-03ysrOt4.js";
 import { t as lookupOf } from "../../lookup-BaP5bI27.js";
 import { r as definePlugin } from "../../plugin-D9bYbYli.js";
 import { t as simplify } from "../../simplify-DDO0j0LI.js";

package/dist/plugins/soft-delete/index.d.ts

@@ -1,6 +1,6 @@
-import { t as AsyncResult } from "../../result-mijqfoJN.js";
-import { D as PrimaryKeyValue } from "../../types-DmshMaXz.js";
-import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-DouW0Kvg.js";
+import { t as AsyncResult } from "../../result-C6jDfedy.js";
+import { tt as PrimaryKeyValue } from "../../executor-CPyrQdjh.js";
+import { d as Plugin, o as HasFlag, p as RepositoryExtension } from "../../plugin-Ar5546xh.js";
 //#region src/plugins/soft-delete/index.d.ts
 export interface SoftDeleteFindArgs {
   /** Include soft-deleted rows of the queried table. */

package/dist/plugins/soft-delete/index.js

@@ -1,8 +1,8 @@
 import { t as and } from "../../types-R6syp1el.js";
-import { a as ok, t as AsyncResult } from "../../result-DIT_qp4G.js";
+import { a as ok, t as AsyncResult } from "../../result-B3m7xtRY.js";
 import { r as definePlugin } from "../../plugin-D9bYbYli.js";
 import { n as scopeOperation } from "../../scope-DgWjuXUw.js";
-import { a as insertsOnly, c as withDefault, i as guardManaged, o as isNotNull, s as isNull, t as dbName } from "../../shared-C80IHf4B.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, o as isNotNull, s as isNull, t as dbName } from "../../shared-LmlfYPv4.js";
 //#region src/plugins/soft-delete/index.ts
 function deletedColumn(table) {
 	return dbName(table, table.flags.softDelete);

package/dist/plugins/tenant/index.d.ts

@@ -1,5 +1,5 @@
-import { F as SchemaMeta } from "../../types-DmshMaXz.js";
-import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtension } from "../../plugin-DouW0Kvg.js";
+import { lt as SchemaMeta } from "../../executor-CPyrQdjh.js";
+import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtension } from "../../plugin-Ar5546xh.js";
 //#region src/plugins/tenant/index.d.ts
 /**
  * Dotted paths to the string claims of `C` (up to three levels), e.g.

package/dist/plugins/tenant/index.js

@@ -1,9 +1,9 @@
-import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-D7u24ZJH.js";
+import { t as DbException } from "../../db-exception-Lngc1W49.js";
+import { n as dbError } from "../../errors-03ysrOt4.js";
 import { a as spansAllTenants, r as definePlugin } from "../../plugin-D9bYbYli.js";
 import { n as scopeOperation } from "../../scope-DgWjuXUw.js";
 import { o as tenantFrom, s as tenantPathsFor } from "../../claims-Bp9My7XP.js";
-import { a as insertsOnly, n as equals, r as forbidden, t as dbName } from "../../shared-C80IHf4B.js";
+import { a as insertsOnly, n as equals, r as forbidden, t as dbName } from "../../shared-LmlfYPv4.js";
 //#region src/plugins/tenant/index.ts
 /**
 * The tenant for a request: `context.tenant`, then the configured claim.

package/dist/plugins/timestamps/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Plugin } from "../../plugin-DouW0Kvg.js";
+import { d as Plugin } from "../../plugin-Ar5546xh.js";
 //#region src/plugins/timestamps/index.d.ts
 /**
  * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,

package/dist/plugins/timestamps/index.js

@@ -1,5 +1,5 @@
 import { r as definePlugin } from "../../plugin-D9bYbYli.js";
-import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-C80IHf4B.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-LmlfYPv4.js";
 //#region src/plugins/timestamps/index.ts
 /**
 * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,