better-supabase 0.5.0 → 0.6.0

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

@@ -0,0 +1,297 @@
+/// <reference lib="esnext.temporal" />
+import { f as Result, t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { t as SqlClient } from "../../executor-DbvExCFC.js";
+import { t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { a as ProblemFormat, t as BlockProblemOptions } from "../../problem-DD8LZFjc.js";
+import { A as QueueMessageBody, C as ScheduleInfo, D as DeadJobRow, E as createJobs, F as sqlQueueBackend, M as QueueRpcClient, N as QueueStats, O as DueSchedule, P as pgmqPublicBackend, S as ScheduleFilter, T as WorkOptions, _ as QueueSchemas, a as DrainResult, b as ScheduleDefinition, c as EnqueueOptions, d as FailOptions, f as Job, g as ListDeadOptions, 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 RetryDeadOptions, w as ScheduleOptions, x as ScheduleDefinitions, y as RunSchedulesOptions } from "../../queue-CLJurhdy.js";
+//#region src/blocks/jobs/cron.d.ts
+/**
+ * Throws a `TypeError` unless `expression` is a schedule `nextCronRun`
+ * understands: five cron fields, a macro such as `@daily`, or an interval
+ * such as `30 seconds`.
+ */
+export declare function assertCron(expression: string): void;
+/**
+ * The first run of `expression` after `after`, in `timeZone`.
+ *
+ * Accepts five cron fields (lists, ranges and steps; a restricted day of
+ * month and day of week match either, as in cron), the macros `@hourly`,
+ * `@daily`, `@weekly`, `@monthly` and `@yearly`, and intervals such as
+ * `30 seconds`, `5 minutes` or `2 hours`, counted from `after`. A local time
+ * that a DST change skips runs at the same offset after the gap.
+ */
+export declare function nextCronRun(expression: string, timeZone: string, after: Temporal.Instant): Temporal.Instant;
+//#endregion
+//#region src/blocks/jobs/dev.d.ts
+interface DevDrainOptions {
+  readonly url: string | URL;
+  readonly secret: string;
+  readonly every?: number;
+  readonly fetch?: typeof fetch;
+  readonly signal?: AbortSignal;
+  readonly onError?: (message: string) => void;
+}
+interface DevDrain {
+  tick(): Promise<void>;
+  stop(): void;
+}
+export declare function devDrainSecret(env: Record<string, string | undefined>, name?: string): string;
+export declare function devDrain(options: DevDrainOptions): DevDrain;
+//#endregion
+//#region src/blocks/jobs/jobs.d.ts
+interface IdempotencyOptions 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
+   * Supabase auth cookies), so one caller never replays another's response.
+   * Pass the verified user id to keep keys across token refreshes.
+   */
+  readonly scope?: string | ((request: Request) => string);
+  /** How long a completed response is replayed. Defaults to `24 hours`. */
+  readonly ttl?: number | string;
+  /** How long a running request holds the key. Defaults to `1 minute`. */
+  readonly lock?: number | string;
+  /** Answer 400 when the header is missing. Defaults to false (run without a key). */
+  readonly required?: boolean;
+  /** Defaults to `Idempotency-Key`. */
+  readonly header?: string;
+}
+type IdempotencyState = "started" | "replay" | "running" | "mismatch";
+interface Idempotency {
+  /**
+   * Runs `handler` at most once per key: retries with the same key and body
+   * get the stored response (with `Idempotency-Replayed: true`).
+   */
+  handle(request: Request, handler: (request: Request) => Promise<Response> | Response): Promise<Response>;
+  /** The lower-level protocol, for non-HTTP callers. */
+  begin(key: string, fingerprint: string, scope?: string): AsyncResult<{
+    state: IdempotencyState;
+    status: number | null;
+    body: unknown;
+    /** The token `complete` and `release` need, when `state` is `started`. */
+    holder: string | undefined;
+  }>;
+  /**
+   * Stores the response for `holder`. `false` when the lock ran out and
+   * another caller took the key over, so the response was not stored.
+   */
+  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>;
+}
+/** HTTP idempotency keys (IETF `Idempotency-Key` header) over the `idempotency` SQL module. */
+export declare function createIdempotency(sql: SqlClient, options?: IdempotencyOptions): Idempotency;
+interface LeaseOptions {
+  /** How long the lease holds without an `extend`. Defaults to 60 seconds. */
+  readonly seconds?: number;
+  readonly scope?: string;
+}
+/** The held lease, passed to the `withLease` callback. */
+interface Lease {
+  readonly holder: string;
+  /** Moves the expiry; `false` once the lease was lost to another holder. */
+  extend(seconds?: number): AsyncResult<boolean>;
+}
+type LeaseOutcome<T> = {
+  readonly acquired: true;
+  readonly value: T;
+} | {
+  readonly acquired: false;
+};
+/**
+ * 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.
+ */
+export declare function withLease<T>(sql: SqlClient, key: string, fn: (lease: Lease) => Promise<T> | T, options?: LeaseOptions): AsyncResult<LeaseOutcome<T>>;
+interface WebhookInboxMessage<T = unknown> {
+  readonly id: number;
+  readonly source: string;
+  readonly messageId: string;
+  readonly type: string | null;
+  readonly payload: T;
+  readonly headers: Readonly<Record<string, string>>;
+  /** 1 on the first attempt. */
+  readonly attempts: number;
+  /**
+   * The source's limit when the message was stored. A handler running with
+   * `attempts === maxAttempts` is on its last attempt: when it fails, the
+   * message is marked dead.
+   */
+  readonly maxAttempts: number;
+  readonly receivedAt: Temporal.Instant;
+  /** The tenant the message was stored for, or null. */
+  readonly tenant: string | null;
+  /** Progress an earlier attempt saved with `checkpoint`, `{}` at first. */
+  readonly progress: Readonly<Record<string, unknown>>;
+  /**
+   * Saves progress mid-processing (merged into `progress`), so a retry
+   * resumes there, such as a provider's page cursor. `false` when the lease
+   * was lost. Only while the handler runs.
+   */
+  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 {
+  /** The sender's message id; the inbox stores each one once. */
+  readonly id: string;
+  readonly payload: unknown;
+  /** Defaults to `typeOf(payload)`. */
+  readonly type?: string | null;
+  /** Defaults to `tenantOf(payload)`. */
+  readonly tenant?: string | null;
+  readonly headers?: Readonly<Record<string, string>>;
+}
+interface WebhookInboxOptions extends BlockProblemOptions, BlockTemporalOptions {
+  /** Name of the sender, e.g. `stripe` or `supabase-auth`. */
+  readonly source: string;
+  /**
+   * Standard Webhooks secrets; the signature is verified before storing.
+   * Leave out `secrets` and `verify` for a source that only `store` fills
+   * (a chat or provider SDK that verifies its own requests); `receive` then
+   * throws.
+   */
+  readonly secrets?: string | readonly string[];
+  /**
+   * Custom verification for senders that don't use Standard Webhooks. It
+   * may also return the event's tenant.
+   */
+  readonly verify?: (request: Request, body: string) => Promise<Result<{
+    id: string;
+    payload: unknown;
+    tenant?: string | null;
+  }>>;
+  /** Event type from the payload. Defaults to `payload.type`. */
+  readonly typeOf?: (payload: unknown) => string | null;
+  /** The tenant a payload belongs to, for per-tenant integrations. Defaults to none. */
+  readonly tenantOf?: (payload: unknown) => string | null | undefined;
+  /** Headers kept with the message. Defaults to none. */
+  readonly keepHeaders?: readonly string[];
+  readonly worker?: string;
+  /**
+   * Attempts before a message of this source is marked dead, stored with
+   * each message as it arrives. Defaults to 8.
+   */
+  readonly maxAttempts?: number;
+  /**
+   * The largest body `receive` reads; a larger one gets 413 without being
+   * read to the end. Defaults to 1 MiB.
+   */
+  readonly maxBodyBytes?: number;
+}
+interface WebhookInboxProcessOptions {
+  /** Messages claimed at once. Defaults to 10. */
+  readonly batch?: number;
+  /**
+   * How long a claimed message stays with this worker. It is renewed when
+   * the message's turn in the batch comes and every half lease while the
+   * handler runs. Defaults to 300 seconds.
+   */
+  readonly lease?: number | string;
+  /**
+   * Stop claiming after this many ms, so a backlog can't outrun a
+   * serverless function's maximum duration; claimed messages still finish.
+   * Defaults to no limit.
+   */
+  readonly budgetMs?: number;
+}
+interface WebhookInboxListOptions {
+  readonly tenant: string;
+  /** Only this status: `pending`, `processing`, `processed` or `dead`. */
+  readonly status?: "pending" | "processing" | "processed" | "dead";
+  /** Defaults to 100, at most 1000. */
+  readonly limit?: number;
+}
+/** A stored message as `list` returns it. */
+interface WebhookInboxEntry {
+  readonly id: number;
+  readonly messageId: string;
+  readonly type: string | null;
+  readonly status: "pending" | "processing" | "processed" | "dead";
+  readonly attempts: number;
+  readonly maxAttempts: number;
+  readonly lastError: string | null;
+  readonly tenant: string | null;
+  readonly receivedAt: Temporal.Instant;
+  readonly processedAt: Temporal.Instant | null;
+}
+interface WebhookInboxPurgeOptions {
+  /** Defaults to `30 days`; `0` with `tenant` removes all of that tenant's processed messages. */
+  readonly olderThan?: number | string;
+  readonly includeDead?: boolean;
+  readonly tenant?: string;
+  readonly batch?: number;
+}
+interface WebhookInbox {
+  /**
+   * Verifies and stores a webhook; answers 202, or 200 for a duplicate
+   * delivery. Throws a `TypeError` when the inbox has neither `secrets` nor
+   * `verify`.
+   */
+  receive(request: Request): Promise<Response>;
+  /**
+   * Stores an event your code already verified (a provider SDK that
+   * verifies and parses in one call). `duplicate` when the id was stored
+   * before.
+   */
+  store(event: WebhookInboxEvent): 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.
+   */
+  process<T = unknown>(handler: (message: WebhookInboxMessage<T>) => unknown, options?: WebhookInboxProcessOptions): Promise<DrainResult>;
+  /** A tenant's messages of this source, newest first. */
+  list(options: WebhookInboxListOptions): AsyncResult<WebhookInboxEntry[]>;
+  /** Deletes old processed (and, with `includeDead`, dead) messages of this source's table; returns how many. */
+  purge(options?: WebhookInboxPurgeOptions): AsyncResult<number>;
+}
+/** Store-then-process webhooks: acknowledge fast, process with retries, never twice. */
+export declare function createWebhookInbox(sql: SqlClient, options: WebhookInboxOptions): WebhookInbox;
+//#endregion
+//#region src/blocks/jobs/rate-limit.d.ts
+/** One counted hit: whether it is allowed, and when to retry if not. */
+interface RateLimitDecision {
+  readonly allowed: boolean;
+  /** Hits left in the current window. */
+  readonly remaining: number;
+  /** Seconds until the window ends; 0 when allowed. */
+  readonly retryAfter: number;
+}
+/** A limit for one call, instead of the scope's rule from `set_rate_limit`. */
+interface RateLimitRule {
+  readonly max: number;
+  /** Seconds, or a Postgres interval such as `1 minute`. */
+  readonly period: number | string;
+}
+interface RateLimit {
+  /**
+   * Counts a hit of `key` (an API key, a public token, a tenant) against
+   * `scope`. The limit is the scope's rule (`set_rate_limit`) unless `rule`
+   * gives one.
+   */
+  check(scope: string, key: string, rule?: RateLimitRule): AsyncResult<RateLimitDecision>;
+}
+interface RateLimitOptions extends BlockTemporalOptions {
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * 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)`.
+ */
+export declare function createRateLimit(source: SqlClient | BlockTransport, 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;
+  readonly detail?: string;
+  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 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, createJobs, pgmqPublicBackend, sqlQueueBackend };