better-supabase 0.12.0 → 0.13.0

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-DIeYscA3.js";
-import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
+import { a as ok, t as AsyncResult } from "../../result-DIT_qp4G.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-D5Djh43x.js";
+import { a as insertsOnly, c as withDefault, i as guardManaged, o as isNotNull, s as isNull, t as dbName } from "../../shared-C80IHf4B.js";
 //#region src/plugins/soft-delete/index.ts
 function deletedColumn(table) {
 	return dbName(table, table.flags.softDelete);
@@ -14,14 +14,14 @@ function scopeFor(table) {
 /**
 * Soft delete for tables generated with `Flags.softDelete`:
 *
-* - reads, updates and deletes skip deleted rows, including inside includes
-*   and relation filters (`withDeleted` / `onlyDeleted` change the root table);
+* - Reads, updates and deletes skip deleted rows, including inside includes and
+*   relation filters (`withDeleted` / `onlyDeleted` change the root table);
 * - `delete` sets the column instead (`{ hard: true }` really deletes);
 * - `restore(key)` clears it.
 *
 * Deletes become updates without `RETURNING`, so a SELECT policy that hides
-* deleted rows does not make them fail. `deleteMany({ returning: true })`
-* keeps `RETURNING`, which needs a SELECT policy that still shows the row.
+* deleted rows does not make them fail. `deleteMany({ returning: true })` keeps
+* `RETURNING`, which needs a SELECT policy that still shows the row.
 */
 function softDelete() {
 	return definePlugin({

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

@@ -1,5 +1,5 @@
-import { F as SchemaMeta } from "../../types-BrpW5ixT.js";
-import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtension } from "../../plugin-D-95Q0w0.js";
+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";
 //#region src/plugins/tenant/index.d.ts
 /**
  * Dotted paths to the string claims of `C` (up to three levels), e.g.
@@ -7,7 +7,10 @@ import { d as Plugin, m as RequestContext, o as HasFlag, p as RepositoryExtensio
  */
 export type ClaimPath<C> = unknown extends C ? string : StringPaths<C, [1, 2, 3]>;
 type StringPaths<T, Depth extends readonly unknown[]> = T extends object ? T extends readonly unknown[] ? never : { [K in keyof T & string]-?: (NonNullable<T[K]> extends string ? K : never) | (Depth extends readonly [unknown, ...infer Rest] ? `${K}.${StringPaths<NonNullable<T[K]>, Rest>}` : never); }[keyof T & string] : never;
-/** `C` is the claims type (`betterSupabase.claims(schema)`'s output); it types `claim`. */
+/**
+ * `C` is the claims type (`betterSupabase.claims(schema)`'s output); it types
+ * `claim`.
+ */
 export interface TenantOptions<C = unknown> {
   /**
    * JWT claim path(s) holding the tenant id when `context.tenant` is not set.
@@ -19,8 +22,8 @@ export interface TenantOptions<C = unknown> {
   /** Custom resolution, e.g. from a header validated against memberships. */
   readonly resolve?: (context: RequestContext) => string | undefined;
   /**
-   * What happens on a tenant table without a tenant in the context:
-   * `error` (default) fails with `forbidden`; `skip` leaves it to RLS.
+   * What happens on a tenant table without a tenant in the context: `error`
+   * (default) fails with `forbidden`; `skip` leaves it to RLS.
    */
   readonly onMissing?: "error" | "skip";
   /**
@@ -30,7 +33,10 @@ export interface TenantOptions<C = unknown> {
   readonly header?: string;
 }
 export interface TenantFindArgs {
-  /** Skip the tenant filter for this call (admin tooling, jobs). RLS still applies. */
+  /**
+   * Skip the tenant filter for this call (admin tooling, jobs). RLS still
+   * applies.
+   */
   readonly allTenants?: boolean;
 }
 export interface TenantExtension extends RepositoryExtension {
@@ -44,11 +50,10 @@ export interface TenantExtension extends RepositoryExtension {
  */
 export declare function resolveTenant<C = unknown>(context: RequestContext, options?: TenantOptions<C>, schema?: Pick<SchemaMeta, "claims">): string | undefined;
 /**
- * Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads,
- * updates and deletes to the request's tenant (nested includes and relation
- * filters too), fills the tenant column on insert and rejects writes that
- * would move rows to another tenant. It complements RLS; it does not replace
- * it.
+ * Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads, updates
+ * and deletes to the request's tenant (nested includes and relation filters
+ * too), fills the tenant column on insert and rejects writes that would move
+ * rows to another tenant. It complements RLS; it does not replace it.
  */
 export declare function tenant<C = unknown>(options?: TenantOptions<C>): Plugin<"tenant", TenantExtension>;
 //#endregion

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-BV1SKTVs.js";
-import { a as spansAllTenants, r as definePlugin } from "../../plugin-tfXW1-qO.js";
+import { n as dbError } from "../../errors-D7u24ZJH.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-PqzCxaTD.js";
-import { a as insertsOnly, n as equals, r as forbidden, t as dbName } from "../../shared-D5Djh43x.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";
 //#region src/plugins/tenant/index.ts
 /**
 * The tenant for a request: `context.tenant`, then the configured claim.
@@ -23,11 +23,10 @@ function tenantColumn(table) {
 	return dbName(table, table.flags.tenant);
 }
 /**
-* Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads,
-* updates and deletes to the request's tenant (nested includes and relation
-* filters too), fills the tenant column on insert and rejects writes that
-* would move rows to another tenant. It complements RLS; it does not replace
-* it.
+* Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads, updates
+* and deletes to the request's tenant (nested includes and relation filters
+* too), fills the tenant column on insert and rejects writes that would move
+* rows to another tenant. It complements RLS; it does not replace it.
 */
 function tenant(options = {}) {
 	const onMissing = options.onMissing ?? "error";

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

@@ -1,11 +1,11 @@
-import { d as Plugin } from "../../plugin-D-95Q0w0.js";
+import { d as Plugin } from "../../plugin-DouW0Kvg.js";
 //#region src/plugins/timestamps/index.d.ts
 /**
  * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,
  * `updatedAt` on insert and update. A call that sets either column fails with
  * `invalid_request` unless it passes `{ override: true }`, which keeps the
- * caller's values. Pair it with
- * the `updated-at` SQL module trigger to cover writes that bypass the app.
+ * caller's values. Pair it with the `updated-at` SQL module trigger to cover
+ * writes that bypass the app.
  */
 export declare function timestamps(): Plugin<"timestamps">;
 //#endregion

package/dist/plugins/timestamps/index.js

@@ -1,12 +1,12 @@
-import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { a as insertsOnly, c as withDefault, i as guardManaged, t as dbName } from "../../shared-D5Djh43x.js";
+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";
 //#region src/plugins/timestamps/index.ts
 /**
 * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,
 * `updatedAt` on insert and update. A call that sets either column fails with
 * `invalid_request` unless it passes `{ override: true }`, which keeps the
-* caller's values. Pair it with
-* the `updated-at` SQL module trigger to cover writes that bypass the app.
+* caller's values. Pair it with the `updated-at` SQL module trigger to cover
+* writes that bypass the app.
 */
 function timestamps() {
 	return definePlugin({

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

@@ -1,5 +1,5 @@
-import { d as Plugin } from "../../plugin-D-95Q0w0.js";
-import { t as StandardSchemaV1 } from "../../standard-BcUQuUgu.js";
+import { t as StandardSchemaV1 } from "../../standard-16AIDny5.js";
+import { d as Plugin } from "../../plugin-DouW0Kvg.js";
 //#region src/plugins/validation/index.d.ts
 export interface TableValidators {
   /** Validates inserts and upserts, with app-cased keys. */
@@ -9,8 +9,8 @@ export interface TableValidators {
 }
 export interface ValidationOptions {
   /**
-   * Validators per table key. The `validators` export of a generated
-   * `zod()` or `valibot()` module fits as is.
+   * Validators per table key. The `validators` export of a generated `zod()` or
+   * `valibot()` module fits as is.
    */
   readonly schemas: Readonly<Record<string, TableValidators>>;
 }

package/dist/plugins/validation/index.js

@@ -1,8 +1,8 @@
 import { t as DbException } from "../../db-exception-CnWcYPxL.js";
-import { n as dbError } from "../../errors-BV1SKTVs.js";
-import { i as encodeValue, r as decodeValue } from "../../wire-BCJxCtHS.js";
-import { r as definePlugin } from "../../plugin-tfXW1-qO.js";
-import { n as validate } from "../../standard-B1BigegP.js";
+import { n as dbError } from "../../errors-D7u24ZJH.js";
+import { i as encodeValue, r as decodeValue } from "../../wire-BJhepFbv.js";
+import { r as definePlugin } from "../../plugin-D9bYbYli.js";
+import { n as validate } from "../../standard-l10kE0yS.js";
 import { n as toDb, t as toApp } from "../../casing-DdFWEtqr.js";
 //#region src/plugins/validation/index.ts
 /**

package/dist/pool-Bu8zXGzI.d.ts

@@ -0,0 +1,123 @@
+import { r as Executor } from "./executor-C29668fO.js";
+import { o as EventHub } from "./events-DhGgwqQA.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as SqlClient } from "./executor-DXfgDsKd.js";
+//#region src/postgres/pool.d.ts
+/** The part of a `pg` pool client `createPostgres` uses. */
+interface PgPoolClient {
+  query(text: string, values?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+  release(): void;
+}
+/** The part of a `pg.Pool` `createPostgres` uses. */
+interface PgPool {
+  connect(): Promise<PgPoolClient>;
+  end(): Promise<void>;
+  /** `pg.Pool` reports errors of idle connections here. */
+  on?(event: "error", listener: (error: Error) => void): unknown;
+}
+/** Statement timeouts in milliseconds by the role a transaction runs as. */
+interface PostgresTimeouts {
+  /**
+   * The connection-string role (`admin` and `transaction` without claims).
+   * Unset by default.
+   */
+  readonly admin?: number;
+  /** Defaults to 8000, Supabase's setting for the role. */
+  readonly authenticated?: number;
+  /** Defaults to 3000, Supabase's setting for the role. */
+  readonly anon?: number;
+}
+interface PostgresOptions {
+  /**
+   * Defaults to `$SUPABASE_DB_URL`, `$DATABASE_URL`, `$POSTGRES_URL`, then
+   * `$POSTGRES_URL_NON_POOLING`, the first one set.
+   */
+  readonly connectionString?: string;
+  /** An existing pool to run on instead of opening one. `end()` ends it. */
+  readonly pool?: PgPool;
+  readonly max?: number;
+  /**
+   * Statement timeout in milliseconds, applied per transaction: one value for
+   * every role, or one per role. `set role` doesn't apply the role's own
+   * `statement_timeout`, so `authenticated` and `anon` get Supabase's 8 s and 3
+   * s unless you set them.
+   */
+  readonly statementTimeout?: number | PostgresTimeouts;
+  /**
+   * Ends a session that stays idle inside a transaction this long, in
+   * milliseconds, so `transaction(fn)` can't hold a connection while `fn` waits
+   * on something else. Defaults to 15000; `0` turns it off. Statements outside
+   * a transaction don't set it.
+   */
+  readonly idleInTransactionTimeout?: number;
+  /** How long `connect` waits for a connection, in milliseconds. Defaults to 10000. */
+  readonly connectionTimeout?: number;
+  /** How long an unused connection stays open, in milliseconds. Defaults to 10000. */
+  readonly idleTimeout?: number;
+  /**
+   * `betterSupabase.events`: an error on an idle pooled connection arrives as
+   * an `error` event instead of crashing the process.
+   */
+  readonly events?: EventHub;
+  /**
+   * Where idle-connection errors go without `error` handlers. Defaults to the
+   * console.
+   */
+  readonly logger?: Logger;
+}
+/** JWT claims to run as. `role` must be `authenticated` or `anon`. */
+interface SqlClaims {
+  readonly sub?: string;
+  readonly role?: string;
+  readonly [claim: string]: unknown;
+}
+/** What every transaction of a user session sets besides the claims and role. */
+interface SessionOptions {
+  /**
+   * Transaction-local settings, e.g. `{ 'better_supabase.tenant': id }`. Names
+   * need a dot (custom settings); `role` and `request.jwt.claims` are set from
+   * the claims.
+   */
+  readonly settings?: Readonly<Record<string, string>>;
+  /** Runs every transaction with `begin read only`: writes fail with 25006. */
+  readonly readOnly?: boolean;
+  /**
+   * Statement timeout in milliseconds for this session's transactions, instead
+   * of the role's `statementTimeout` from `createPostgres`.
+   */
+  readonly statementTimeout?: number;
+}
+interface BetterPostgres {
+  /** Connects as the connection-string role. On Supabase that bypasses RLS. */
+  readonly admin: SqlClient;
+  /** Runs every query as the given user, with RLS, like PostgREST does. */
+  asUser(claims: SqlClaims, options?: SessionOptions): SqlClient;
+  /** Runs every query as `anon`. */
+  readonly anon: SqlClient;
+  /**
+   * Repositories' executor as the given user
+   * (`postgresExecutor(asUser(claims))`). `createServer` calls it for
+   * `ctx.sql`, so only apps that pass `postgres` bundle the SQL compiler.
+   */
+  executorFor(claims: SqlClaims, options?: SessionOptions): Executor;
+  /**
+   * Runs `fn` in one transaction. Pass claims to run it as a user; the session
+   * options apply with or without them.
+   */
+  transaction<T>(fn: (client: SqlClient) => Promise<T>, options?: {
+    readonly claims?: SqlClaims;
+  } & SessionOptions): Promise<T>;
+  end(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * A pooled Postgres connection for jobs, scripts and tests. Each query (or
+ * transaction) runs in its own transaction; claims and role are
+ * transaction-local, so nothing leaks back into the pool. An `admin` query with
+ * no timeout to set runs on its own, without `begin` and `commit`.
+ */
+declare function createPostgres(options?: PostgresOptions): BetterPostgres;
+//#endregion
+export { PostgresTimeouts as a, createPostgres as c, PostgresOptions as i, PgPool as n, SessionOptions as o, PgPoolClient as r, SqlClaims as s, BetterPostgres as t };

package/dist/pool-errors-DOZ3oDeS.js

@@ -0,0 +1,27 @@
+import { c as mapDbError } from "./errors-D7u24ZJH.js";
+import { s as toDbError } from "./result-DIT_qp4G.js";
+import { t as consoleLogger } from "./logger-glM28NVN.js";
+import { n as errorEvent } from "./events-D6IZ5CE8.js";
+import { t as fromPgError } from "./pg-error-B5QLDcbG.js";
+//#region src/postgres/pool-errors.ts
+/**
+* Listens for errors on idle pooled connections, such as a server restart or an
+* ended session. `pg.Pool` emits them as an `error` event, and Node exits on an
+* `error` event nobody listens to. The listener reports the error and never
+* throws.
+*/
+function watchPoolErrors(pool, options) {
+	pool.on?.("error", (cause) => {
+		try {
+			const raw = fromPgError(cause);
+			const error = raw ? mapDbError(raw, []) : toDbError(cause);
+			if (options.events?.has("error")) {
+				options.events.emit("error", errorEvent(error));
+				return;
+			}
+			(options.logger ?? options.events?.logger ?? consoleLogger).error("an idle Postgres connection failed", { error });
+		} catch {}
+	});
+}
+//#endregion
+export { watchPoolErrors as t };

package/dist/ports-BltcWsHf.d.ts

@@ -0,0 +1,312 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-mijqfoJN.js";
+import { t as StandardSchemaV1 } from "./standard-16AIDny5.js";
+import { r as FieldsOf } from "./block-fields-DnXkMney.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { f as AiFiles, y as UploadClaimStorage } from "./types-DYXhFhmQ.js";
+import { g as JobHandler } from "./types-CB5MvzuE.js";
+import { i as EventSink } from "./cloud-event-CidL9jiw.js";
+import { g as Workflows } from "./workflows-BHyYAR6c.js";
+//#region src/blocks/attachments/attachments.d.ts
+interface StorageReply<T> {
+  readonly data: T | null;
+  readonly error: unknown;
+}
+/** The `supabase.storage.from(bucket)` methods attachments use. */
+interface AttachmentBucket {
+  createSignedUploadUrl(path: string): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+    readonly token: string;
+  }>>;
+  createSignedUrl(path: string, expiresIn: number, options?: {
+    download?: string | boolean;
+  }): PromiseLike<StorageReply<{
+    readonly signedUrl: string;
+  }>>;
+  download(path: string): PromiseLike<StorageReply<Blob>>;
+  remove(paths: string[]): PromiseLike<StorageReply<unknown>>;
+  /** Used by `put`, which uploads from the server. */
+  upload?(path: string, body: Blob | ArrayBuffer | Uint8Array, options?: {
+    readonly contentType?: string;
+    readonly upsert?: boolean;
+  }): PromiseLike<StorageReply<unknown>>;
+}
+/** `supabase.storage`, typed structurally. */
+interface AttachmentStorage extends UploadClaimStorage {
+  from(bucket: string): AttachmentBucket;
+}
+interface AttachmentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the attachment columns the app adds
+   * (`blocks.attachments.options.extraColumns`), keyed by column name. It types
+   * and parses them on every read, and validates them on `upload` and `put`,
+   * which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Attachments<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /** The caller's `supabase.storage`, so the bucket policies apply. */
+  readonly storage: AttachmentStorage;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`. Default `better_supabase`.
+   */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /**
+   * `blocks.attachments.options.requireScan`, which `defineBlocks` passes from
+   * `blocks.generated.ts`. Default `true`.
+   */
+  readonly requireScan?: boolean;
+  /** Lifetime of a signed download URL in seconds. Default 300. */
+  readonly downloadTtl?: number;
+}
+type AttachmentStatus = "pending" | "clean" | "infected" | "failed";
+interface Attachment {
+  readonly id: string;
+  /** `undefined` for a file of a subject without a tenant (`tenant: false`). */
+  readonly organizationId: string | undefined;
+  readonly subjectType: string | undefined;
+  readonly subjectId: string | undefined;
+  readonly bucket: string;
+  /**
+   * The object path in the bucket, `{organizationId}/attachments/{id}` unless
+   * `options.path` says otherwise.
+   */
+  readonly path: string;
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly status: AttachmentStatus;
+  /** What the scanner reported, such as the signature it matched. */
+  readonly scanDetail: string | undefined;
+  /** What `upload` stored with the file; `{}` without any. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly uploadedBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** Set by `confirm()` once the object exists. */
+  readonly uploadedAt: Temporal.Instant | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+}
+interface NewAttachment {
+  /** `null` for a subject type configured with `tenant: false`. */
+  readonly organizationId: string | null;
+  readonly name: string;
+  readonly mimeType: string;
+  /** Bytes; `confirm()` replaces it with the stored size. */
+  readonly size: number;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  /**
+   * App data about the file, such as a caption or its source, kept with the
+   * record.
+   */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface AttachmentUpload<F extends object = Record<never, never>> {
+  readonly attachment: Attachment & F;
+  /**
+   * PUT the file here, or pass `token` to `uploadToSignedUrl(path, token,
+   * file)`.
+   */
+  readonly signedUrl: string;
+  readonly token: string;
+}
+interface AttachmentDownload<F extends object = Record<never, never>> {
+  readonly attachment: Attachment & F;
+  readonly signedUrl: string;
+}
+/** `F` is the extra attachment fields `options.fields` describes. */
+interface Attachments<F extends object = Record<never, never>> {
+  /**
+   * Creates the pending record and a signed upload URL for its path. When
+   * Storage refuses the URL, the record is deleted again.
+   */
+  upload(attachment: NewAttachment & Partial<F>): AsyncResult<AttachmentUpload<F>>;
+  /**
+   * Marks the upload done after the file is stored; emits
+   * `attachment.uploaded`.
+   */
+  confirm(id: string): AsyncResult<Attachment & F>;
+  get(id: string): AsyncResult<Attachment & F>;
+  list(organizationId: string | null, subject?: {
+    readonly type: string;
+    readonly id: string;
+  }): AsyncResult<readonly (Attachment & F)[]>;
+  /**
+   * A signed URL for a file the scanner passed. `invalid_request` with hint
+   * `ATTACHMENT_NOT_SCANNED` until then, and for an infected file.
+   */
+  download(id: string, options?: {
+    readonly as?: string | boolean;
+  }): AsyncResult<AttachmentDownload<F>>;
+  /** Deletes the file, then the record (the uploader, or `attachments.manage`). */
+  remove(id: string): AsyncResult<boolean>;
+  /**
+   * Creates the record, uploads `file` from the server and confirms it, for
+   * files the server makes or fetches (an export, a generated PDF, an import).
+   * Returns the confirmed attachment, which still waits for the scan when the
+   * module requires one. When Storage refuses the upload, the record is deleted
+   * again, so no pending record is left behind.
+   */
+  put(attachment: NewAttachment & Partial<F>, file: Blob | ArrayBuffer | Uint8Array): AsyncResult<Attachment & F>;
+  /**
+   * The file's bytes, for server-side processing, behind the same scan gate as
+   * `download`: `ATTACHMENT_NOT_SCANNED` until the scan passes.
+   */
+  read(id: string): AsyncResult<{
+    readonly attachment: Attachment & F;
+    readonly file: Blob;
+  }>;
+}
+declare function createAttachments<S extends StandardSchemaV1 | undefined = undefined>(options: AttachmentsOptions<S>): Attachments<FieldsOf<S>>;
+/** A scanner's verdict on one file. */
+interface ScanVerdict {
+  readonly status: "clean" | "infected";
+  /** Stored as `scan_detail`, such as the matched signature. */
+  readonly detail?: string;
+}
+interface AttachmentScannerOptions extends BlockTemporalOptions {
+  /**
+   * A service-role transport: `set_attachment_status()` is granted to
+   * `service_role` only.
+   */
+  readonly transport: BlockTransport;
+  /** A service-role `supabase.storage`, to read pending files. */
+  readonly storage: AttachmentStorage;
+  readonly schema?: string;
+  /**
+   * Scans the file (ClamAV, a scanning API). A throw records `failed` and
+   * rethrows.
+   */
+  readonly scan: (file: Blob, attachment: Attachment, signal?: AbortSignal) => ScanVerdict | Promise<ScanVerdict>;
+  /** The outbox `typePrefix`. Default `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+/** The payload `job` expects. */
+interface AttachmentScanJob {
+  readonly attachmentId: string;
+}
+interface AttachmentScanner {
+  /** Scans one uploaded file and records the verdict. */
+  scan(id: string, signal?: AbortSignal): AsyncResult<Attachment>;
+  /**
+   * A jobs handler: `queue.work('attachment-scans', scanner.job)`. A deleted
+   * attachment completes the job; other errors throw so the queue retries.
+   */
+  readonly job: JobHandler<AttachmentScanJob>;
+  /**
+   * An outbox sink that scans each `attachment.uploaded` event's file. An event
+   * for a deleted attachment is skipped, so it never holds up the events behind
+   * it; other errors throw so the relay retries the batch.
+   */
+  sink(): EventSink;
+}
+/**
+ * Scans uploaded files with the app's `scan` function and records `clean`,
+ * `infected` or `failed`. A file already clean or infected is not scanned
+ * again, so replayed events and retried jobs are safe.
+ */
+declare function createAttachmentScanner(options: AttachmentScannerOptions): AttachmentScanner;
+/** A scanned object in any bucket (`scanned_objects`). */
+interface ScannedObject {
+  readonly bucket: string;
+  readonly path: string;
+  readonly status: AttachmentStatus;
+  readonly detail: string | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+}
+interface ObjectScannerOptions extends BlockTemporalOptions {
+  /**
+   * A service-role transport: `set_object_scan()` is granted to `service_role`
+   * only.
+   */
+  readonly transport: BlockTransport;
+  /** A service-role `supabase.storage`, to read the objects. */
+  readonly storage: AttachmentStorage;
+  readonly schema?: string;
+  /** Scans the file. A throw records `failed` and rethrows. */
+  readonly scan: (file: Blob, object: {
+    readonly bucket: string;
+    readonly path: string;
+  }, signal?: AbortSignal) => ScanVerdict | Promise<ScanVerdict>;
+  /** The outbox `typePrefix`. Default `dev.better-supabase`. */
+  readonly typePrefix?: string;
+}
+/** The payload `ObjectScanner.job` expects. */
+interface ObjectScanJob {
+  readonly bucket: string;
+  readonly path: string;
+}
+interface ObjectScanner {
+  /**
+   * Scans one object and records the verdict; a clean or infected object is not
+   * scanned again.
+   */
+  scan(bucket: string, path: string, signal?: AbortSignal): AsyncResult<ScannedObject>;
+  /**
+   * A jobs handler: `queue.work('object-scans', scanner.job)`. An object
+   * deleted from storage completes the job; other errors throw.
+   */
+  readonly job: JobHandler<ObjectScanJob>;
+  /**
+   * An outbox sink that scans each `object.uploaded` event's object. An event
+   * for an object deleted from storage is skipped; other errors throw so the
+   * relay retries the batch.
+   */
+  sink(): EventSink;
+}
+/**
+ * The scan gate for objects outside the attachments table, such as a file drive
+ * or avatars: scans an object with the app's `scan` function and records the
+ * verdict in `scanned_objects`, which storage policies read with
+ * `object_clean(bucket_id, name)`. With `options.scanBuckets`, new objects in
+ * those buckets get a pending row and an `object.uploaded` event.
+ */
+declare function createObjectScanner(options: ObjectScannerOptions): ObjectScanner;
+//#endregion
+//#region src/blocks/ports.d.ts
+/** What a `notifier` port sends: one notification to its recipients. */
+interface NotifierInput {
+  readonly recipients: readonly string[];
+  readonly tenant: string;
+  /** Deduplicates retries of the same send. */
+  readonly key: string;
+  readonly subject?: {
+    readonly type: string;
+    readonly id: string;
+  };
+  readonly data: Readonly<Record<string, unknown>>;
+}
+/** Sends notifications for a block that consumes `notifier`. */
+interface Notifier {
+  send(type: string, input: NotifierInput): unknown;
+}
+/**
+ * The ports blocks provide and consume, by name. A manifest's `provides` builds
+ * a port from its client, and `createBlocks` hands it to the blocks whose
+ * `consumes` name it. Every port has one provider in a set of blocks, except
+ * `sink`: each block that provides one adds an outbox sink.
+ */
+interface BlockPorts {
+  /** The `notifications` block. */
+  readonly notifier: Notifier;
+  /** The `ai-files` block, for knowledge. */
+  readonly files: AiFiles;
+  /** The `attachments` block, for the drive's files. */
+  readonly attachments: Attachments;
+  /** The `workflows` block, for the workflow builder's schedules. */
+  readonly workflows: Workflows;
+  /** An outbox sink, for `outbox.relayRoute({ consumers: blocks.sinks })`. */
+  readonly sink: EventSink;
+}
+type PortName = keyof BlockPorts;
+//#endregion
+export { createAttachments as C, createAttachmentScanner as S, ObjectScanJob as _, Attachment as a, ScanVerdict as b, AttachmentScanJob as c, AttachmentStatus as d, AttachmentStorage as f, NewAttachment as g, AttachmentsOptions as h, PortName as i, AttachmentScanner as l, Attachments as m, Notifier as n, AttachmentBucket as o, AttachmentUpload as p, NotifierInput as r, AttachmentDownload as s, BlockPorts as t, AttachmentScannerOptions as u, ObjectScanner as v, createObjectScanner as w, ScannedObject as x, ObjectScannerOptions as y };