better-supabase 0.13.0 → 0.14.0

package/dist/client-Dd-a0tup.d.ts

@@ -0,0 +1,475 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { M as AnyFunctions, N as AnyModels, mt as TableKey } from "./executor-CPyrQdjh.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { n as SqlClient } from "./executor-CsTaO3AT.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-SPyXMdcd.js";
+import { kt as WhereInput, t as BetterSupabase } from "./define-Dw7pRO4h.js";
+import { i as ListDefinition } from "./list-query-BtluNnYk.js";
+import { n as Controller, t as AuthPort } from "./controller-DAD4hbl4.js";
+import { a as UndoToken } from "./undo-B696duxr.js";
+import { n as AuditCategory } from "./context-9Q23weHu.js";
+//#region src/blocks/audit/audit.d.ts
+interface PurgeAuditLogOptions extends BlockTemporalOptions {
+  /**
+   * 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. `setAuditRetention` reads the days
+   * from a column.
+   */
+  readonly retention?: (tenant: string | null) => number | undefined | Promise<number | undefined>;
+  /**
+   * The schema the functions live in, over a transport. Defaults to
+   * `better_supabase`.
+   */
+  readonly schema?: string;
+}
+type Retention = NonNullable<PurgeAuditLogOptions["retention"]>;
+/**
+ * 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.
+ */
+declare function purgeAuditLog(source: SqlClient | BlockTransport, options?: PurgeAuditLogOptions): AsyncResult<number>;
+interface AuditRetentionSource {
+  /** `schema.table` holding one row per tenant, e.g. `public.organizations`. */
+  readonly table: string;
+  /** The integer column with the days to keep; `null` uses `olderThan`. */
+  readonly column: string;
+  /** The tenant id column. Defaults to `id`. */
+  readonly key?: string;
+}
+/**
+ * A `retention` callback for `purgeAuditLog` that reads each tenant's days from
+ * a column (a plan's `audit_retention_days`, say). `purgeAuditLog` reads every
+ * tenant's days in one query; a direct call reads one tenant.
+ */
+declare function setAuditRetention(sql: SqlClient, source: AuditRetentionSource): Retention;
+/** One audit entry as `exportAuditLog` reads it. */
+interface AuditEntry {
+  readonly id: string;
+  readonly occurredAt: Temporal.Instant;
+  /**
+   * `insert`, `update` and `delete` for row changes; `event` for
+   * `audit_event()`.
+   */
+  readonly op: string;
+  readonly table?: string;
+  readonly record?: string;
+  readonly changed?: readonly string[];
+  readonly actor?: string;
+  readonly actorRole?: string;
+  readonly organizationId?: string;
+  readonly eventType?: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface OcsfProduct {
+  readonly name: string;
+  readonly vendor_name?: string;
+  readonly version?: string;
+}
+/**
+ * One entry as an OCSF event (`SPEC_PINS.ocsf`). Row changes are Entity
+ * Management (3004); semantic events are API Activity (6003), with the activity
+ * read from the event type's last segment (`deal.created` is Create).
+ */
+declare function toOcsf(entry: AuditEntry, product: OcsfProduct): Record<string, unknown>;
+interface ExportAuditLogOptions extends BlockTemporalOptions {
+  /** Only this tenant's entries. */
+  readonly organizationId: string;
+  readonly from?: Temporal.Instant;
+  /** Exclusive. */
+  readonly to?: Temporal.Instant;
+  /** `ndjson` writes entries as they are; `ocsf` maps each with `toOcsf`. */
+  readonly format?: "ndjson" | "ocsf";
+  /** Required for `ocsf`: `metadata.product`. */
+  readonly product?: OcsfProduct;
+  /** Rows per query. Defaults to 1000. */
+  readonly batch?: number;
+  /** Defaults to `better_supabase.audit_events`. */
+  readonly table?: string;
+}
+/**
+ * Streams one tenant's audit entries as newline-delimited JSON, in id order,
+ * one keyset query per batch. Run it with a member's claims (the `readPolicy`
+ * filters) or as the service role. It reads the managed module's column names;
+ * for an adopted log, the version 3 columns or CSV, use
+ * `createAudit().export()`, which reads `list_audit_events`.
+ */
+declare function exportAuditLog(sql: SqlClient, options: ExportAuditLogOptions): ReadableStream<Uint8Array>;
+type AuditSort = "newest" | "oldest";
+type AuditFacet = "table" | "record" | "op" | "actor" | "event" | "category" | "outcome" | "target";
+type AuditListDefinition<M extends AnyModels, T extends TableKey<M>, E> = ListDefinition<M, T, E, AuditSort, AuditFacet> & {
+  /** A `where` for `run(db, query, { where })`: entries in `[from, to)`. */
+  between(from?: Temporal.Instant, to?: Temporal.Instant): WhereInput<M, T>;
+};
+/**
+ * A cursor-paged list over the audit table through the Data API or `ctx.sql`
+ * (generate types for the module's schema to get it in your models; facets
+ * follow the managed column names). `createAudit().list()` reads
+ * `list_audit_events` instead, with an adopted log's columns mapped. Filtered
+ * by actor, table, record, event type, category, outcome and target, newest
+ * first. The `readPolicy` and the `restricted` table decide what a member
+ * sees.
+ */
+declare function auditListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, options?: {
+  readonly pageSize?: number;
+  readonly maxPageSize?: number;
+}): AuditListDefinition<M, T, E>;
+//#endregion
+//#region src/blocks/audit/csv.d.ts
+/** A CSV export column: a key, or a key and the header to write for it. */
+type AuditCsvColumn = string | {
+  readonly key: string;
+  readonly label: string;
+};
+/** How `export({ format: "csv" })` writes its rows. */
+interface AuditCsvOptions<Columns extends AuditColumns = AuditColumns> {
+  /**
+   * The columns, in order: a key of the record (`eventType`), `columns.<name>`
+   * for a column `metadataColumns` fills, or `restricted.<field>` (`ip`,
+   * `userAgent`, `sessionId`, `metadata`, `old`, `new` or `changes`) for a
+   * caller who may reveal the entries. A restricted column reads each page
+   * through `reveal_audit_entries`, which records `audit.revealed`, and is
+   * empty for entries the caller may not reveal. Defaults to the built-in
+   * columns.
+   */
+  readonly columns?: readonly AuditCsvColumn[];
+  /** Lines written before the header row, one cell each, such as a title. */
+  readonly preamble?: readonly string[];
+  /**
+   * The row to write, by column key. It gets the default row, the record and
+   * its restricted details (only with a restricted column).
+   */
+  readonly formatRow?: (row: Readonly<Record<string, unknown>>, record: AuditRecord<Columns>, details: AuditDetails | undefined) => Readonly<Record<string, unknown>>;
+}
+//#endregion
+//#region src/blocks/audit/sink.d.ts
+interface AuditSinkOptions {
+  /**
+   * The type prefix stripped from each event's `type`. Defaults to
+   * `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /**
+   * The category for an event type (without the prefix), from the categories
+   * the SQL modules use. Defaults to `security` for `account.*` and
+   * `support.*`, and no category for the rest.
+   */
+  readonly category?: (eventType: string) => AuditCategory | undefined;
+}
+/**
+ * The audit entry for one CloudEvent: its type without the prefix, its subject
+ * as the record, the tenant from the `tenant` or `partitionkey` extension (or
+ * `data.organizationId`), and the data as metadata. The idempotency key is the
+ * event's source and id, so a redelivery records once. A `support.*` event also
+ * fills the impersonation columns from its `sessionId`, `adminId` and
+ * `reason`.
+ */
+declare function auditEventOf(event: CloudEvent, options?: AuditSinkOptions): AuditEventInput;
+/**
+ * An `EventSink` that records CloudEvents in the audit log, one `recordMany`
+ * call per chunk of at most `MAX_BATCH` events. `send` throws the first failure
+ * once every chunk ran, so an outbox relay retries the batch; the idempotency
+ * key keeps the entries already written from repeating.
+ */
+declare function auditSink(recordMany: (events: readonly AuditEventInput[]) => AsyncResult<readonly Result<string>[]>, options?: AuditSinkOptions): EventSink;
+//#endregion
+//#region src/blocks/audit/audit-log.d.ts
+/**
+ * The adopted log's own columns, by column name, as `metadataColumns` maps
+ * them.
+ */
+type AuditColumns = Readonly<Record<string, unknown>>;
+/**
+ * One entry as `list_audit_events` returns it: the module's columns under
+ * stable keys, whatever the adopted log calls them. Fields the log doesn't
+ * have, or the caller may not read, are missing.
+ */
+interface AuditRecord<Columns extends AuditColumns = AuditColumns> {
+  readonly id: string;
+  readonly occurredAt: Temporal.Instant;
+  readonly op?: string;
+  readonly table?: string;
+  readonly record?: string;
+  readonly changed?: readonly string[];
+  readonly old?: Readonly<Record<string, unknown>>;
+  readonly new?: Readonly<Record<string, unknown>>;
+  readonly actorId?: string;
+  readonly actorRole?: string;
+  readonly actorKind?: string;
+  readonly actorLabel?: string;
+  readonly tenant?: string;
+  readonly tenantLabel?: string;
+  readonly impersonatedBy?: string;
+  readonly impersonationReason?: string;
+  readonly supportSession?: string;
+  readonly eventType?: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly targetLabel?: string;
+  readonly summary?: string;
+  readonly requestId?: string;
+  readonly correlationId?: string;
+  readonly scope?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /**
+   * The adopted log's columns that `blocks.audit.options.metadataColumns`
+   * fills, by column name. Missing without that option.
+   */
+  readonly columns?: Readonly<Partial<Columns>>;
+}
+/** Where a page ends: pass it as `before` for the next, older page. */
+interface AuditCursor {
+  readonly occurredAt: Temporal.Instant;
+  readonly id: string;
+}
+type OneOrMany = string | readonly string[];
+interface AuditListOptions {
+  readonly organizationId?: OneOrMany;
+  readonly eventType?: OneOrMany;
+  readonly actorId?: OneOrMany;
+  readonly targetType?: OneOrMany;
+  readonly record?: OneOrMany;
+  readonly category?: OneOrMany;
+  readonly outcome?: OneOrMany;
+  readonly source?: OneOrMany;
+  readonly actorKind?: OneOrMany;
+  readonly correlationId?: OneOrMany;
+  readonly search?: string;
+  readonly order?: "desc" | "asc";
+  readonly count?: boolean;
+  /** Entries at or after this instant. */
+  readonly since?: Temporal.Instant;
+  /** Entries before this instant. */
+  readonly until?: Temporal.Instant;
+  /** `page.next` of the previous page; `undefined` starts at the newest. */
+  readonly cursor?: AuditCursor | undefined;
+  /** Default 50, at most 1000. */
+  readonly limit?: number;
+  readonly offset?: number;
+}
+interface AuditPage<Columns extends AuditColumns = AuditColumns> {
+  readonly entries: readonly AuditRecord<Columns>[];
+  /** The cursor of the next page, or `undefined` on the last one. */
+  readonly next: AuditCursor | undefined;
+  readonly total?: number;
+}
+/** The restricted details `reveal` returns, when the entry has them. */
+interface AuditDetails {
+  readonly entry: string;
+  readonly old?: Readonly<Record<string, unknown>>;
+  readonly new?: Readonly<Record<string, unknown>>;
+  readonly ip?: string;
+  readonly userAgent?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly sessionId?: string;
+  readonly changes?: unknown;
+}
+interface AuditExportOptions<Columns extends AuditColumns = AuditColumns> extends Omit<AuditListOptions, "before" | "limit" | "count">, AuditCsvOptions<Columns> {
+  /**
+   * `ndjson` (default) writes the records as they are, `csv` a spreadsheet with
+   * a header row, `ocsf` each record mapped with `toOcsf`.
+   */
+  readonly format?: "ndjson" | "csv" | "ocsf";
+  /** Required for `ocsf`: `metadata.product`. */
+  readonly product?: OcsfProduct;
+  /** Entries per call. Default 500. */
+  readonly batch?: number;
+}
+/** The part of `supabase.storage.from(bucket)` an export upload uses. */
+interface AuditExportBucket {
+  upload(path: string, body: Blob, options?: {
+    contentType?: string;
+    upsert?: boolean;
+  }): PromiseLike<{
+    readonly data: unknown;
+    readonly error: unknown;
+  }>;
+  createSignedUrl?(path: string, expiresIn: number, options?: {
+    download?: string | boolean;
+  }): PromiseLike<{
+    readonly data: {
+      readonly signedUrl: string;
+    } | null;
+    readonly error: unknown;
+  }>;
+}
+interface AuditExportToStorageOptions<Columns extends AuditColumns = AuditColumns> extends AuditExportOptions<Columns> {
+  readonly storage: {
+    from(bucket: string): AuditExportBucket;
+  };
+  readonly bucket: string;
+  /** The object path, such as `{organizationId}/audit/{jobId}.csv`. */
+  readonly path: string;
+  /** Also sign a download URL that lives this many seconds. */
+  readonly signedUrlTtl?: number;
+}
+interface AuditEventInput {
+  readonly eventType: string;
+  readonly category?: string;
+  readonly outcome?: string;
+  readonly source?: string;
+  readonly targetType?: string;
+  readonly record?: string;
+  readonly organizationId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly idempotencyKey?: string;
+  readonly restricted?: Readonly<Record<string, unknown>>;
+  readonly summary?: string;
+  readonly targetLabel?: string;
+  readonly correlationId?: string;
+  readonly actorId?: string;
+  readonly actorKind?: string;
+  readonly actorLabel?: string;
+  readonly ip?: string;
+  readonly userAgent?: string;
+  readonly sessionId?: string;
+  readonly requestId?: string;
+  readonly scope?: string;
+  /**
+   * The support session the event belongs to, its admin and their reason, for
+   * the impersonation columns. Honoured for the service role; any other caller
+   * may only name itself as `impersonatedBy`, from a token without an `act`
+   * claim, and otherwise gets the claim's values.
+   */
+  readonly supportSessionId?: string;
+  readonly impersonatedBy?: string;
+  readonly impersonationReason?: string;
+}
+interface AuditLogOptions<Columns extends AuditColumns = AuditColumns> extends BlockTemporalOptions {
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<AuditLog<Columns>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /**
+   * `sqlTransport(ctx.postgres)` for members, or `rpcTransport` over an API
+   * schema.
+   */
+  readonly transport: BlockTransport;
+  /** The audit module's schema, or its API schema. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** What `revert` did, and the token that reverts it again. */
+interface AuditReverted {
+  readonly reverted: number;
+  /** `null` when the log has no correlation id column to find the writes by. */
+  readonly undo: UndoToken | null;
+}
+interface AuditLog<Columns extends AuditColumns = AuditColumns> {
+  record(event: AuditEventInput): AsyncResult<string>;
+  /**
+   * Records up to 1000 events in one `audit_event_many` call, with `record`'s
+   * checks per event: one `Result` per event, in order, so a bad event never
+   * drops the others. The outer result fails only when the call itself does
+   * (more than 1000 events, the network).
+   */
+  recordMany(events: readonly AuditEventInput[]): AsyncResult<readonly Result<string>[]>;
+  /** A page of the entries the caller can read, newest first. */
+  list(options?: AuditListOptions): AsyncResult<AuditPage<Columns>>;
+  /**
+   * The restricted details of one entry for a caller with the reveal permission
+   * in its tenant (or platform staff); the reveal is itself recorded as
+   * `audit.revealed`. `not_found` otherwise.
+   */
+  reveal(entryId: string): AsyncResult<AuditDetails>;
+  /**
+   * Writes the old values of row changes back as the caller, newest entry
+   * first, all or nothing, with `audit.revert` in each entry's tenant. `raised`
+   * with code `ROW_CHANGED_SINCE` when a row no longer holds what the entry
+   * wrote. The undo token reverts the revert.
+   */
+  revert(entryIds: readonly string[]): AsyncResult<AuditReverted>;
+  /**
+   * Every matching entry as NDJSON, CSV or OCSF, read page by page as the
+   * caller.
+   */
+  export(options?: AuditExportOptions<Columns>): ReadableStream<Uint8Array>;
+  /**
+   * Writes an export to a Storage object, for a job that runs it in the
+   * background (the data lifecycle export bucket, say), and returns the path
+   * and a signed URL when `signedUrlTtl` is set.
+   */
+  exportToStorage(options: AuditExportToStorageOptions<Columns>): AsyncResult<{
+    readonly path: string;
+    readonly url: string | undefined;
+  }>;
+  /**
+   * An `EventSink` that records CloudEvents, for `forwardBlockEvents`,
+   * `forwardMutations`, an outbox relay or the server's `audit` option. Build
+   * the log on a service-role transport so the event's actor counts.
+   */
+  sink(options?: AuditSinkOptions): EventSink;
+}
+/**
+ * The audit log over the `audit` module's functions, as the caller: the read
+ * policy decides what `list` and `export` return, and column mappings of an
+ * adopted log are already applied.
+ */
+declare function createAudit<Columns extends AuditColumns = AuditColumns>(options: AuditLogOptions<Columns>): AuditLog<Columns>;
+//#endregion
+//#region src/blocks/audit/client.d.ts
+/** What an audit table filters by; an empty value matches every entry. */
+interface AuditFilters {
+  /** One actor's entries, by user id. */
+  readonly actorId?: string | undefined;
+  /** One action's entries, by event type such as `invitation.created`. */
+  readonly eventType?: string | undefined;
+  /** Text in the summary, the labels or the event type. */
+  readonly search?: string | undefined;
+}
+interface AuditLogControllerOptions {
+  readonly client: Pick<AuditLog, "list">;
+  readonly auth: AuthPort;
+  /** The organization; the table waits without one. */
+  readonly organizationId: string | null;
+  /** The filters of the first page. */
+  readonly filters?: AuditFilters;
+  /** Entries per page, default 50, at most 1000. */
+  readonly limit?: number;
+}
+interface AuditLogSnapshot {
+  /** The pages loaded so far, newest first; `undefined` until the first one. */
+  readonly entries: readonly AuditRecord[] | undefined;
+  readonly filters: AuditFilters;
+  /** Whether a page is loading. */
+  readonly loading: boolean;
+  /** Whether `loadMore` has older entries to load. */
+  readonly hasMore: boolean;
+  readonly error: DbError | undefined;
+}
+interface AuditLogActions {
+  /** Replaces the filters and loads the first page again. */
+  readonly setFilters: (filters: AuditFilters) => Promise<void>;
+  /** Appends the next, older page. */
+  readonly loadMore: () => Promise<void>;
+  /** Loads the first page again with the current filters. */
+  readonly refresh: () => Promise<void>;
+}
+type AuditLogController = Controller<AuditLogSnapshot, AuditLogActions>;
+/**
+ * One organization's audit trail for an audit table: the newest page as the
+ * caller may read it, `setFilters` to narrow it by actor, action or text, and
+ * `loadMore` for older pages.
+ */
+declare function createAuditLogController(options: AuditLogControllerOptions): AuditLogController;
+//#endregion
+export { AuditSort as A, auditSink as C, AuditFacet as D, AuditEntry as E, exportAuditLog as F, purgeAuditLog as I, setAuditRetention as L, OcsfProduct as M, PurgeAuditLogOptions as N, AuditListDefinition as O, auditListQuery as P, toOcsf as R, auditEventOf as S, AuditCsvOptions as T, AuditPage as _, AuditLogSnapshot as a, createAudit as b, AuditCursor as c, AuditExportBucket as d, AuditExportOptions as f, AuditLogOptions as g, AuditLog as h, AuditLogControllerOptions as i, ExportAuditLogOptions as j, AuditRetentionSource as k, AuditDetails as l, AuditListOptions as m, AuditLogActions as n, createAuditLogController as o, AuditExportToStorageOptions as p, AuditLogController as r, AuditColumns as s, AuditFilters as t, AuditEventInput as u, AuditRecord as v, AuditCsvColumn as w, AuditSinkOptions as x, AuditReverted as y };