better-supabase 0.4.0 → 0.5.1

package/dist/jobs/index.d.ts

@@ -1,108 +1,34 @@
 /// <reference lib="esnext.temporal" />
-import { o as Result, p as DbError, t as AsyncResult } from "../result-CqEsbgYs.js";
-import { t as SqlClient } from "../executor-CZ7ImRiD.js";
-import { StandardSchemaV1 } from "@standard-schema/spec";
-//#region src/jobs/jobs.d.ts
-type QueueSchemas = Readonly<Record<string, StandardSchemaV1>>;
-type PayloadIn<Q extends QueueSchemas, N extends keyof Q> = StandardSchemaV1.InferInput<Q[N]>;
-type PayloadOut<Q extends QueueSchemas, N extends keyof Q> = StandardSchemaV1.InferOutput<Q[N]>;
-interface Job<P = unknown> {
-  /** The pgmq message id. */
-  readonly id: number;
-  readonly queue: string;
-  readonly payload: P;
-  /** 1 on the first run (pgmq's `read_ct`). */
-  readonly attempts: number;
-  readonly maxAttempts: number;
-  readonly enqueuedAt: Temporal.Instant;
-  /** End of the lease: the job becomes claimable again after this. */
-  readonly visibleUntil: Temporal.Instant;
-  readonly lastError: string | null;
-}
-interface EnqueueOptions {
-  /** Run no earlier than this. */
-  readonly runAt?: Temporal.Instant;
-  /** Seconds to wait before running. */
-  readonly delay?: number;
-  /** Defaults to 5. After this many failed attempts the job is archived as dead. */
-  readonly maxAttempts?: number;
-  /**
-   * While a job with this key is waiting or running, enqueueing again returns
-   * its id. SQL connections only.
-   */
-  readonly dedupeKey?: string;
-}
-interface ClaimOptions {
-  /** Defaults to 1. */
-  readonly batch?: number;
-  /** Seconds a claimed job stays invisible to other workers. Defaults to 300. */
-  readonly lease?: number;
-}
-interface FailOptions {
-  /** Retry after this many seconds instead of the exponential backoff. SQL connections only. */
-  readonly retryIn?: number;
-}
-type JobHandler<P> = (payload: P, job: Job<P>, signal: AbortSignal) => unknown;
-interface WorkOptions extends ClaimOptions {
-  /** Jobs handled at once. Defaults to 1. */
-  readonly concurrency?: number;
-  /**
-   * First wait between polls when the queue is empty, in ms. Defaults to
-   * 1000. Each empty poll doubles the wait up to `maxPollInterval`; a claimed
-   * job resets it.
-   */
-  readonly pollInterval?: number;
-  /** Longest wait between empty polls, in ms. Defaults to 30000. */
-  readonly maxPollInterval?: number;
-  /** Stops the loop; running jobs finish first. */
-  readonly signal?: AbortSignal;
-  readonly onError?: (error: DbError, job: Job) => void;
-}
-interface DrainResult {
-  readonly succeeded: number;
-  readonly failed: number;
-}
-interface Jobs<Q extends QueueSchemas> {
-  /** Validates the payload with the queue's schema, then enqueues it. Returns the job id. */
-  enqueue<N extends Extract<keyof Q, string>>(queue: N, payload: PayloadIn<Q, N>, options?: EnqueueOptions): AsyncResult<number>;
-  claim<N extends Extract<keyof Q, string>>(queue: N, options?: ClaimOptions): AsyncResult<Job<PayloadOut<Q, N>>[]>;
-  /** Archives the job. `false` when the lease was lost (another worker claimed it since). */
-  complete(job: Job): AsyncResult<boolean>;
-  /** Returns the new state: `queued` (will retry), `dead` (archived), or `null` when the lease was lost. */
-  fail(job: Job, error: unknown, options?: FailOptions): AsyncResult<"queued" | "dead" | null>;
-  /** Pushes the lease out by `lease` seconds. `false` when it was lost or the transport can't. */
-  extend(job: Job, lease: number): AsyncResult<boolean>;
-  /**
-   * Enqueues `payload` on a cron schedule with pg_cron (`'0 3 * * *'`,
-   * `'30 seconds'`). Re-scheduling a name replaces it. SQL connections only.
-   */
-  schedule<N extends Extract<keyof Q, string>>(name: string, cron: string, queue: N, payload: PayloadIn<Q, N>): AsyncResult<void>;
-  unschedule(name: string): AsyncResult<boolean>;
-  /** Processes ready jobs until the queue is empty. For cron and edge invocations. */
-  drain<N extends Extract<keyof Q, string>>(queue: N, handler: JobHandler<PayloadOut<Q, N>>, options?: Omit<WorkOptions, "pollInterval" | "maxPollInterval" | "signal">): Promise<DrainResult>;
-  /** Polls and processes jobs until `signal` aborts. */
-  work<N extends Extract<keyof Q, string>>(queue: N, handler: JobHandler<PayloadOut<Q, N>>, options?: WorkOptions): Promise<DrainResult>;
-}
-/** A Supabase client, or anything with `.schema(name).rpc(fn, args)`. */
-interface QueueRpcClient {
-  schema(name: string): {
-    rpc(fn: string, args: Readonly<Record<string, unknown>>): PromiseLike<{
-      data: unknown;
-      error: unknown;
-    }>;
-  };
-}
+import { _ as DbError, a as AsyncResult, u as Result } from "../executor-BunPOO-k.js";
+import { t as SqlClient } from "../executor-Cghdstwu.js";
+import { r as EventSink, t as CloudEvent } from "../index-DOESKG27.js";
+import { C as sqlQueueBackend, S as pgmqPublicBackend, _ as QueueSchemas, a as DrainRouteResult, b as WorkOptions, c as FailOptions, d as JobHandler, f as Jobs, g as QueueRpcClient, h as QueueMessageRow, i as DrainRouteOptions, l as Job, m as QueueMessageBody, n as DrainOptions, o as DueSchedule, p as QueueBackend, r as DrainResult, s as EnqueueOptions, t as ClaimOptions, u as JobContext, v as RunSchedulesOptions, x as createJobs, y as ScheduleOptions } from "../queue-BYUCjr59.js";
+//#region src/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;
 /**
- * Typed jobs on Supabase Queues (pgmq), over the `jobs` SQL kit module.
+ * The first run of `expression` after `after`, in `timeZone`.
  *
- * Pass a service SQL connection (`postgres.admin`, `ctx.sql`) for the full
- * feature set, or a service-role Supabase client to go through the
- * `pgmq_public` RPCs where no direct connection exists (edge functions).
- * Queue names are lowercase letters, digits and underscores.
+ * 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 createJobs<const Q extends QueueSchemas>(source: SqlClient | QueueRpcClient, queues: Q): Jobs<Q>;
+export declare function nextCronRun(expression: string, timeZone: string, after: Temporal.Instant): Temporal.Instant;
+//#endregion
+//#region src/jobs/jobs.d.ts
 interface IdempotencyOptions {
-  /** Separates keys of different endpoints or tenants. Defaults to `''`. */
+  /**
+   * 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;
@@ -176,5 +102,125 @@ export declare const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_sum
  * a job can invalidate their sessions. Empty for other payloads.
  */
 export declare function entitlementMembers(sql: SqlClient, payload: unknown): AsyncResult<readonly string[]>;
+interface PurgeAuditLogOptions {
+  /** How long entries are kept when `retention` has no answer. Defaults to `1 year`. */
+  readonly olderThan?: number | string;
+  /** The most entries deleted per tenant in one call. Defaults to 10000. */
+  readonly batch?: number;
+  /**
+   * Days a tenant keeps its entries (a plan's retention, say); `undefined`
+   * uses `olderThan`. Called with `null` for entries without a tenant.
+   * Retention shorter than a day is not supported.
+   */
+  readonly retention?: (tenant: string | null) => number | undefined | Promise<number | undefined>;
+}
+/**
+ * Deletes audit entries past their retention and returns how many. Without
+ * `retention` it is one `purge_audit_log` call (which honours an
+ * `audit_retention` SQL hook); with it, each tenant is purged with its own
+ * interval. Run it from a schedule until it returns 0.
+ */
+export declare function purgeAuditLog(sql: SqlClient, options?: PurgeAuditLogOptions): AsyncResult<number>;
+//#endregion
+//#region src/jobs/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/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;
+}
+interface OutboxOptions {
+  /** The schema of the `outbox` module. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  /** 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;
+}
+interface RegisterOptions {
+  /** Type patterns such as `org.*` 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;
+}
+interface RelayResult {
+  readonly delivered: number;
+  /** Set when the sink threw: the batch stays unacknowledged for the next run. */
+  readonly error?: DbError;
+}
+interface OutboxRouteOptions extends Omit<RelayOptions, "owner"> {
+  /** The bearer secret, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /** Consumer name to the sink its events go to. */
+  readonly consumers: Readonly<Record<string, EventSink>>;
+  readonly onError?: (error: DbError, consumer: string) => void;
+}
+interface OutboxRouteResult {
+  readonly consumers: Readonly<Record<string, RelayResult>>;
+  readonly budgetExhausted: boolean;
+}
+interface HistoryFilter {
+  readonly subject?: string;
+  readonly type?: string;
+  /** Only events after this position. */
+  readonly after?: 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 the next run, so delivery is at least once.
+   */
+  relay(consumer: string, sink: EventSink, options?: RelayOptions): Promise<RelayResult>;
+  /** A `GET`/`POST` handler for a cron that relays every consumer in turn. */
+  relayRoute(options: OutboxRouteOptions): (request: Request) => Promise<Response>;
+  history(filter?: HistoryFilter): AsyncResult<readonly OutboxEvent[]>;
+  /**
+   * Deletes up to `batch` events (default 10,000) older than `olderThan` that
+   * every consumer has passed. Call it again while it returns `batch`.
+   */
+  purge(olderThan?: string, batch?: number): 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.
+ */
+export declare function outboxCloudEvent(event: OutboxEvent, options: Pick<OutboxOptions, "source" | "typePrefix">): CloudEvent;
+export declare function createOutbox(sql: SqlClient, options: OutboxOptions): Outbox;
 //#endregion
-export type { ClaimOptions, DrainResult, EnqueueOptions, FailOptions, Idempotency, IdempotencyOptions, IdempotencyState, Inbox, InboxMessage, InboxOptions, Job, JobHandler, Jobs, QueueRpcClient, QueueSchemas, SqlClient, WorkOptions };
+export { type ClaimOptions, type DrainOptions, type DrainResult, type DrainRouteOptions, type DrainRouteResult, type DueSchedule, type EmitOptions, type EnqueueOptions, type FailOptions, type HistoryFilter, type Idempotency, type IdempotencyOptions, type IdempotencyState, type Inbox, type InboxMessage, type InboxOptions, type Job, type JobContext, type JobHandler, type Jobs, type Outbox, type OutboxEvent, type OutboxOptions, type OutboxRouteOptions, type OutboxRouteResult, type PurgeAuditLogOptions, type QueueBackend, type QueueMessageBody, type QueueMessageRow, type QueueRpcClient, type QueueSchemas, type RegisterOptions, type RelayOptions, type RelayResult, type RunSchedulesOptions, type ScheduleOptions, type SqlClient, type WorkOptions, createJobs, pgmqPublicBackend, sqlQueueBackend };