better-supabase 0.8.0 → 0.9.0

package/dist/blocks/jobs/index.d.ts

@@ -1,10 +1,15 @@
 /// <reference lib="esnext.temporal" />
-import { f as Result, t as AsyncResult, w as ErrorMapper } from "../../result-BchM1XZn.js";
-import { t as SqlClient } from "../../executor-ngjKL_Pe.js";
-import { t as BlockTransport } from "../../block-transport-inD4fFq-.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-C0Xj8War.js";
-import { a as ProblemFormat, t as BlockProblemOptions } from "../../problem-TvGdxO1t.js";
-import { A as QueueMessageBody, C as ScheduleFilter, D as DeadJobRow, E as WorkOptions, F as sqlQueueBackend, M as QueueRpcClient, N as QueueStats, O as DueSchedule, P as pgmqPublicBackend, S as ScheduleDefinitions, T as ScheduleOptions, _ as ListDeadOptions, a as DrainResult, b as RunSchedulesOptions, c as EnqueueOptions, d as FailOptions, f as Job, g as JobsOptions, h as Jobs, i as DrainOptions, j as QueueMessageRow, k as QueueBackend, l as EnsureSchedulesOptions, m as JobHandler, n as DeadJob, o as DrainRouteOptions, p as JobContext, r as DrainMonitor, s as DrainRouteResult, t as ClaimOptions, u as EnsureSchedulesResult, v as QueueSchemas, w as ScheduleInfo, x as ScheduleDefinition, y as RetryDeadOptions } from "../../types-D__3EN0q.js";
+import { f as Result, 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 { n as SqlClient } from "../../executor-BBHgjUJu.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { n as BlockOptions, r as BlockTemporalOptions } from "../../block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "../../block-hooks-BLPWD3Jt.js";
+import { n as ExtraFields, r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { A as DeadJobRow, B as sqlQueueBackend, C as RunSchedulesOptions, D as ScheduleInfo, E as ScheduleFilter, F as QueuePurgeArgs, I as QueueRpcClient, L as QueueStats, M as QueueBackend, N as QueueMessageBody, O as ScheduleOptions, P as QueueMessageRow, R as TransportQueueBackendOptions, S as RetryDeadOptions, T as ScheduleDefinitions, V as transportQueueBackend, _ as Jobs, a as DrainResult, b as PurgeJobsOptions, c as EnqueueOnceOptions, d as EnsureSchedulesOptions, f as EnsureSchedulesResult, g as JobHandler, h as JobContext, i as DrainOptions, j as DueSchedule, k as WorkOptions, l as EnqueueOnceResult, m as Job, n as DeadJob, o as DrainRouteOptions, p as FailOptions, r as DrainMonitor, s as DrainRouteResult, t as ClaimOptions, u as EnqueueOptions, v as JobsOptions, w as ScheduleDefinition, x as QueueSchemas, y as ListDeadOptions, z as pgmqPublicBackend } from "../../types-CdP0z5tS.js";
+import { a as ProblemFormat, t as BlockProblemOptions } from "../../problem-CEjyhV5T.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
 //#region src/blocks/jobs/cron.d.ts
 /**
  * Throws a `TypeError` unless `expression` is a schedule `nextCronRun`
@@ -40,7 +45,21 @@ export declare function devDrainSecret(env: Record<string, string | undefined>,
 export declare function devDrain(options: DevDrainOptions): DevDrain;
 //#endregion
 //#region src/blocks/jobs/idempotency.d.ts
-interface IdempotencyOptions extends BlockProblemOptions, BlockTemporalOptions {
+/** Where `createIdempotency` stores keys: a transport, or a service SQL connection. */
+type IdempotencySource = {
+  /**
+   * A service-role transport, such as `rpcTransport(adminClient, { schema: "api" })`
+   * over the wrappers `blocks.idempotency.api` writes.
+   */
+  readonly transport: BlockTransport;
+  readonly sql?: never;
+} | {
+  /** A service SQL connection: `postgres.admin` or `ctx.postgresAdmin`. */
+  readonly sql: SqlClient;
+  readonly transport?: never;
+};
+type IdempotencyOptions = IdempotencySource & IdempotencySettings;
+interface IdempotencySettings extends BlockProblemOptions, BlockTemporalOptions {
   /**
    * Separates keys of different callers, endpoints or tenants. Defaults to a
    * hash of the caller's credentials (the `Authorization` header or the
@@ -56,6 +75,14 @@ interface IdempotencyOptions extends BlockProblemOptions, BlockTemporalOptions {
   readonly required?: boolean;
   /** Defaults to `Idempotency-Key`. */
   readonly header?: string;
+  /** The schema the functions live in, over a transport. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers that run before the built-in ones, over a transport. */
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around `begin`, `extend`, `complete`, `release` and `purge`. */
+  readonly hooks?: BlockHooks<Idempotency>;
+  /** Receives the errors `after` hooks throw. */
+  readonly logger?: Logger;
 }
 type IdempotencyState = "started" | "replay" | "running" | "mismatch";
 interface Idempotency {
@@ -72,6 +99,12 @@ interface Idempotency {
     /** The token `complete` and `release` need, when `state` is `started`. */
     holder: string | undefined;
   }>;
+  /**
+   * Moves the lock of a running key `lock` further for `holder`. `false` once
+   * the lock ran out or another caller took the key over. `handle` calls it
+   * at half the lock while the handler runs.
+   */
+  extend(key: string, holder: string, scope?: string): AsyncResult<boolean>;
   /**
    * Stores the response for `holder`. `false` when the lock ran out and
    * another caller took the key over, so the response was not stored.
@@ -79,12 +112,20 @@ interface Idempotency {
   complete(key: string, holder: string, status: number, body: unknown, scope?: string): AsyncResult<boolean>;
   /** Forgets the key so it can be retried; `false` when `holder` lost it. */
   release(key: string, holder: string, scope?: string): AsyncResult<boolean>;
+  /** Deletes expired keys (`purge_idempotency_keys`); returns how many. */
+  purge(): AsyncResult<number>;
+  /** A job handler that runs `purge`; schedule it hourly. */
+  purgeJob(): JobHandler<unknown>;
 }
-/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL module. */
-export declare function createIdempotency(sql: SqlClient, options?: IdempotencyOptions): Idempotency;
+/**
+ * HTTP idempotency keys (IETF `Idempotency-Key` header) over the
+ * `idempotency` SQL module: a service SQL connection, or a service-role
+ * `rpcTransport` over the wrappers `blocks.idempotency.api` writes.
+ */
+export declare function createIdempotency(options: IdempotencyOptions): Idempotency;
 //#endregion
 //#region src/blocks/jobs/webhook-inbox.d.ts
-interface WebhookInboxMessage<T = unknown> {
+interface WebhookInboxMessage<T = unknown, F extends object = Record<never, never>> {
   readonly id: number;
   readonly source: string;
   readonly messageId: string;
@@ -104,6 +145,8 @@ interface WebhookInboxMessage<T = unknown> {
   readonly tenant: string | null;
   /** Progress an earlier attempt saved with `checkpoint`, `{}` at first. */
   readonly progress: Readonly<Record<string, unknown>>;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
   /**
    * Saves progress mid-processing (merged into `progress`), so a retry
    * resumes there, such as a provider's page cursor. `false` when the lease
@@ -112,7 +155,7 @@ interface WebhookInboxMessage<T = unknown> {
   checkpoint(fields: Readonly<Record<string, unknown>>): Promise<boolean>;
 }
 /** A verified event to store, from `verify` or from `store` for a provider SDK that verifies itself. */
-interface WebhookInboxEvent {
+interface WebhookInboxEvent<F extends object = Record<never, never>> {
   /** The sender's message id; the inbox stores each one once. */
   readonly id: string;
   readonly payload: unknown;
@@ -121,8 +164,10 @@ interface WebhookInboxEvent {
   /** Defaults to `tenantOf(payload)`. */
   readonly tenant?: string | null;
   readonly headers?: Readonly<Record<string, string>>;
+  /** The extra columns of a new message; a duplicate keeps the stored ones. */
+  readonly fields?: Partial<F>;
 }
-interface WebhookInboxOptions extends BlockProblemOptions, BlockTemporalOptions {
+interface WebhookInboxOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions, BlockProblemOptions {
   /** Name of the sender, e.g. `stripe` or `supabase-auth`. */
   readonly source: string;
   /**
@@ -158,6 +203,17 @@ interface WebhookInboxOptions extends BlockProblemOptions, BlockTemporalOptions
    * read to the end. Defaults to 1 MiB.
    */
   readonly maxBodyBytes?: number;
+  /**
+   * A Standard Schema for the message's extra columns
+   * (`blocks.webhook-inbox.options.extraColumns`), keyed by database name.
+   * It validates them on `store`, and types and parses them on `list` and
+   * on the messages `process` hands the handler.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around `store`, `list` and `purge`. */
+  readonly hooks?: NoInfer<BlockHooks<WebhookInbox<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
 }
 interface WebhookInboxProcessOptions {
   /** Messages claimed at once. Defaults to 10. */
@@ -183,7 +239,7 @@ interface WebhookInboxListOptions {
   readonly limit?: number;
 }
 /** A stored message as `list` returns it. */
-interface WebhookInboxEntry {
+interface WebhookInboxEntry<F extends object = Record<never, never>> {
   readonly id: number;
   readonly messageId: string;
   readonly type: string | null;
@@ -194,6 +250,8 @@ interface WebhookInboxEntry {
   readonly tenant: string | null;
   readonly receivedAt: Temporal.Instant;
   readonly processedAt: Temporal.Instant | null;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
 }
 interface WebhookInboxPurgeOptions {
   /** Defaults to `30 days`; `0` with `tenant` removes all of that tenant's processed messages. */
@@ -201,8 +259,15 @@ interface WebhookInboxPurgeOptions {
   readonly includeDead?: boolean;
   readonly tenant?: string;
   readonly batch?: number;
+  /** The schema the functions live in, over a transport. Defaults to `better_supabase`. */
+  readonly schema?: string;
 }
-interface WebhookInbox {
+/**
+ * Deletes processed messages from the inbox (`purge_webhooks`) over a
+ * service SQL connection or a service-role transport; returns how many.
+ */
+export declare function purgeWebhookInbox(source: SqlClient | BlockTransport, options?: WebhookInboxPurgeOptions): AsyncResult<number>;
+interface WebhookInbox<F extends object = Record<never, never>> {
   /**
    * Verifies and stores a webhook; answers 202, or 200 for a duplicate
    * delivery. Throws a `TypeError` when the inbox has neither `secrets` nor
@@ -214,29 +279,40 @@ interface WebhookInbox {
    * verifies and parses in one call). `duplicate` when the id was stored
    * before.
    */
-  store(event: WebhookInboxEvent): AsyncResult<{
+  store(event: WebhookInboxEvent<F>): AsyncResult<{
     id: number;
     duplicate: boolean;
   }>;
   /**
    * Processes stored messages until none are ready, or until `budgetMs`
    * is spent. A message whose lease another claim took over is skipped,
-   * and its outcome is not counted.
+   * and its outcome is not counted. A message whose extra columns the
+   * `fields` schema rejects fails without reaching the handler. The signal
+   * aborts when the lease can't be renewed; the message is then neither
+   * completed nor failed by this worker.
    */
-  process<T = unknown>(handler: (message: WebhookInboxMessage<T>) => unknown, options?: WebhookInboxProcessOptions): Promise<DrainResult>;
+  process<T = unknown>(handler: (message: WebhookInboxMessage<T, F>, signal: AbortSignal) => unknown, options?: WebhookInboxProcessOptions): Promise<DrainResult>;
   /** A tenant's messages of this source, newest first. */
-  list(options: WebhookInboxListOptions): AsyncResult<WebhookInboxEntry[]>;
+  list(options: WebhookInboxListOptions): AsyncResult<WebhookInboxEntry<F>[]>;
   /** Deletes old processed (and, with `includeDead`, dead) messages of this source's table; returns how many. */
   purge(options?: WebhookInboxPurgeOptions): AsyncResult<number>;
+  /** A job handler that runs `purge`; schedule it nightly. */
+  purgeJob(options?: WebhookInboxPurgeOptions): JobHandler<unknown>;
 }
-/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
-export declare function createWebhookInbox(sql: SqlClient, options: WebhookInboxOptions): WebhookInbox;
+/**
+ * Store-then-process webhooks: acknowledge fast, process with retries, never
+ * twice. Pass a service transport, `sqlTransport(postgres.admin)`: the inbox
+ * functions are granted to the service role only.
+ */
+export declare function createWebhookInbox<S extends StandardSchemaV1 | undefined = undefined>(options: WebhookInboxOptions<S>): WebhookInbox<FieldsOf<S>>;
 //#endregion
 //#region src/blocks/jobs/lease.d.ts
 interface LeaseOptions {
   /** How long the lease holds without an `extend`. Defaults to 60 seconds. */
   readonly seconds?: number;
   readonly scope?: string;
+  /** The schema the functions live in, over a transport. Defaults to `better_supabase`. */
+  readonly schema?: string;
 }
 /** The held lease, passed to the `withLease` callback. */
 interface Lease {
@@ -254,21 +330,26 @@ type LeaseOutcome<T> = {
  * Runs `fn` while holding the lease on `key`, one holder at a time, and
  * releases it afterwards, also when `fn` throws. `{ acquired: false }` while
  * another holder has it. A lease that expires mid-run is taken by the next
- * caller; call `lease.extend()` for long work.
+ * caller; call `lease.extend()` for long work. Takes a service SQL
+ * connection, or a service-role `rpcTransport` over the wrappers
+ * `blocks.idempotency.api` writes.
  */
-export declare function withLease<T>(sql: SqlClient, key: string, fn: (lease: Lease) => Promise<T> | T, options?: LeaseOptions): AsyncResult<LeaseOutcome<T>>;
+export declare function withLease<T>(source: SqlClient | BlockTransport, key: string, fn: (lease: Lease) => Promise<T> | T, options?: LeaseOptions): AsyncResult<LeaseOutcome<T>>;
 //#endregion
 //#region src/blocks/jobs/queue.d.ts
+/** What `createJobs` stores jobs through. */
+type JobsSource = SqlClient | QueueRpcClient | BlockTransport | QueueBackend;
 /**
  * Typed jobs on Supabase Queues (pgmq), over the `jobs` SQL module.
  *
  * Pass a service SQL connection (`postgres.admin`, `ctx.sql`) for the full
- * feature set, a service-role Supabase client to go through the
- * `pgmq_public` RPCs where no direct connection exists (edge functions), or
- * any `QueueBackend`. Queue names are lowercase letters, digits and
- * underscores.
+ * feature set, a service-role `rpcTransport` over the wrappers
+ * `blocks.jobs.api` writes for the same features over the Data API (or a
+ * service-role Supabase client with `schema` set to that schema), a
+ * service-role Supabase client to go through the `pgmq_public` RPCs, or any
+ * `QueueBackend`. Queue names are lowercase letters, digits and underscores.
  */
-export declare function createJobs<const Q extends QueueSchemas>(source: SqlClient | QueueRpcClient | QueueBackend, queues: Q, options?: JobsOptions): Jobs<Q>;
+export declare function createJobs<const Q extends QueueSchemas>(options: JobsOptions<Q>): Jobs<Q>;
 //#endregion
 //#region src/blocks/jobs/rate-limit.d.ts
 /** One counted hit: whether it is allowed, and when to retry if not. */
@@ -292,17 +373,49 @@ interface RateLimit {
    * gives one.
    */
   check(scope: string, key: string, rule?: RateLimitRule): AsyncResult<RateLimitDecision>;
+  /**
+   * Deletes up to `batch` counters whose window ended (`purge_rate_limits`);
+   * returns how many.
+   */
+  purge(options?: {
+    readonly batch?: number;
+  }): AsyncResult<number>;
+  /** A job handler that runs `purge`; schedule it hourly. */
+  purgeJob(options?: {
+    readonly batch?: number;
+  }): JobHandler<unknown>;
 }
-interface RateLimitOptions extends BlockTemporalOptions {
+/** Where `createRateLimit` keeps its counters: a transport or a SQL connection. */
+type RateLimitSource = {
+  /**
+   * A service-role transport, such as `rpcTransport(adminClient)`, over
+   * the `rate-limit` module's functions.
+   */
+  readonly transport: BlockTransport;
+  readonly sql?: never;
+} | {
+  /** A service SQL connection: `postgres.admin` or `ctx.postgresAdmin`. */
+  readonly sql: SqlClient;
+  readonly transport?: never;
+};
+interface RateLimitSettings extends BlockTemporalOptions {
+  /** The schema the functions live in, over a transport. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  /** Error mappers that run before the built-in ones. */
   readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<RateLimit>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
 }
+type RateLimitOptions = RateLimitSource & RateLimitSettings;
 /**
  * Fixed-window limits for keys that aren't claims, over the `rate-limit`
- * module's counters. Pass a service SQL connection (`ctx.postgresAdmin`,
- * `postgres.admin`), or a service-role `BlockTransport` such as
- * `rpcTransport(adminClient)`.
+ * module's counters. Pass `sql`, a service SQL connection
+ * (`ctx.postgresAdmin`, `postgres.admin`), or `transport`, a service-role
+ * `BlockTransport` such as `rpcTransport(adminClient)`.
  */
-export declare function createRateLimit(source: SqlClient | BlockTransport, options?: RateLimitOptions): RateLimit;
+export declare function createRateLimit(options: RateLimitOptions): RateLimit;
 /** A `problem+json` 429 with `Retry-After`, for a refused `check`. */
 export declare function rateLimited(decision: Pick<RateLimitDecision, "retryAfter">, options?: {
   readonly instance?: string;
@@ -310,4 +423,14 @@ export declare function rateLimited(decision: Pick<RateLimitDecision, "retryAfte
   readonly problem?: ProblemFormat;
 }): Response;
 //#endregion
-export { type ClaimOptions, type DeadJob, type DeadJobRow, type DevDrain, type DevDrainOptions, type DrainMonitor, type DrainOptions, type DrainResult, type DrainRouteOptions, type DrainRouteResult, type DueSchedule, type EnqueueOptions, type EnsureSchedulesOptions, type EnsureSchedulesResult, type FailOptions, type Idempotency, type IdempotencyOptions, type IdempotencyState, type Job, type JobContext, type JobHandler, type Jobs, type JobsOptions, type Lease, type LeaseOptions, type LeaseOutcome, type ListDeadOptions, type QueueBackend, type QueueMessageBody, type QueueMessageRow, type QueueRpcClient, type QueueSchemas, type QueueStats, type RateLimit, type RateLimitDecision, type RateLimitOptions, type RateLimitRule, type RetryDeadOptions, type RunSchedulesOptions, type ScheduleDefinition, type ScheduleDefinitions, type ScheduleFilter, type ScheduleInfo, type ScheduleOptions, type SqlClient, type WebhookInbox, type WebhookInboxEntry, type WebhookInboxEvent, type WebhookInboxListOptions, type WebhookInboxMessage, type WebhookInboxOptions, type WebhookInboxProcessOptions, type WebhookInboxPurgeOptions, type WorkOptions, pgmqPublicBackend, sqlQueueBackend };
+//#region src/blocks/jobs/manifest.d.ts
+/** The `jobs` block's manifest (ADR 0029). */
+export declare const jobsBlock: BlockOf<"jobs", typeof createJobs>;
+/** The `idempotency` block's manifest (ADR 0029). */
+export declare const idempotencyBlock: BlockOf<"idempotency", typeof createIdempotency>;
+/** The `rate-limit` block's manifest (ADR 0029). */
+export declare const rateLimitBlock: BlockOf<"rate-limit", typeof createRateLimit>;
+/** The `webhook-inbox` block's manifest (ADR 0029). */
+export declare const webhookInboxBlock: BlockOf<"webhook-inbox", typeof createWebhookInbox>;
+//#endregion
+export { type BlockTransport, type ClaimOptions, type DeadJob, type DeadJobRow, type DevDrain, type DevDrainOptions, type DrainMonitor, type DrainOptions, type DrainResult, type DrainRouteOptions, type DrainRouteResult, type DueSchedule, type EnqueueOnceOptions, type EnqueueOnceResult, type EnqueueOptions, type EnsureSchedulesOptions, type EnsureSchedulesResult, type FailOptions, type Idempotency, type IdempotencyOptions, type IdempotencySettings, type IdempotencySource, type IdempotencyState, type Job, type JobContext, type JobHandler, type Jobs, type JobsOptions, type JobsSource, type Lease, type LeaseOptions, type LeaseOutcome, type ListDeadOptions, type PurgeJobsOptions, type QueueBackend, type QueueMessageBody, type QueueMessageRow, type QueuePurgeArgs, type QueueRpcClient, type QueueSchemas, type QueueStats, type RateLimit, type RateLimitDecision, type RateLimitOptions, type RateLimitRule, type RateLimitSettings, type RateLimitSource, type RetryDeadOptions, type RunSchedulesOptions, type ScheduleDefinition, type ScheduleDefinitions, type ScheduleFilter, type ScheduleInfo, type ScheduleOptions, type SqlClient, type TransportQueueBackendOptions, type WebhookInbox, type WebhookInboxEntry, type WebhookInboxEvent, type WebhookInboxListOptions, type WebhookInboxMessage, type WebhookInboxOptions, type WebhookInboxProcessOptions, type WebhookInboxPurgeOptions, type WorkOptions, dbTransport, pgmqPublicBackend, rpcTransport, sqlQueueBackend, sqlTransport, transportQueueBackend };