better-supabase 0.12.0 → 0.14.0

package/dist/define-block-COpcS6aT.d.ts

@@ -0,0 +1,1338 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1$1 } from "./standard-DbQsD2xZ.js";
+import { r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { dt as SubjectRef } from "./executor-CPyrQdjh.js";
+import { Ct as Events, D as BlockEventPattern, T as BlockEvent, bt as EventMap, k as BlockEventsMatching, o as EventHub, wt as MergedEventMap, xt as EventMapOf } from "./events-DbLjvxDX.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { i as CredentialRef, o as CredentialToken, r as CredentialProvider } from "./provider-DmiaI1qt.js";
+import { a as BlockTenantOptions, n as BlockOptions, r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { r as DbTransportSource, t as BlockTransport } from "./block-transport-d53POsem.js";
+import { a as BlockTransportMiddleware, n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { f as AiFiles, y as UploadClaimStorage } from "./types-BEDfwXL4.js";
+import { g as JobHandler } from "./types-CGUDoF5I.js";
+import { t as BlockOptionsSchema } from "./options-289GJc2l.js";
+import { t as Author } from "./block-authors-DzXLUiIq.js";
+import { i as EventSink } from "./cloud-event-SPyXMdcd.js";
+import { O as TtlPreset, l as ImageTransform, x as TransformOptions } from "./bucket-TkB7_xv8.js";
+import { i as FieldSpec, n as TableSchema, o as TableSchemaSpec } from "./table-schema-Cb-IV_pZ.js";
+import { g as Workflows } from "./workflows-D8U7KyXJ.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/core/entity-naming.d.ts
+/** A noun in its singular and plural snake_case forms, e.g. `work_item`. */
+interface EntityNoun {
+  readonly singular: string;
+  readonly plural: string;
+}
+/** The case forms a rename covers. */
+type EntityCase = "snake" | "kebab" | "camel" | "pascal";
+/** One noun renamed: every case form of `from` becomes the same form of `to`. */
+interface EntityRename {
+  readonly from: EntityNoun;
+  readonly to: EntityNoun;
+  /** Defaults to every case. */
+  readonly cases?: readonly EntityCase[];
+  /**
+   * Match only whole identifier segments, so `deal` leaves `ideal` and `dealer`
+   * alone. Defaults to true. The tenant rename sets false, so it renames
+   * `organization` inside any identifier, as it always has.
+   */
+  readonly bounded?: boolean;
+}
+/** Renames for a set of nouns, applied in one pass so no rename feeds another. */
+interface EntityNames {
+  readonly renames: readonly EntityRename[];
+  /** Whether any noun gets a new name. */
+  readonly renamed: boolean;
+  /** An identifier with every default noun renamed. */
+  rename(identifier: string): string;
+  /** An identifier with every new noun renamed back to its default. */
+  reverse(identifier: string): string;
+}
+/** Renames for `renames`, longest form first, in one pass. */
+declare function entityNames(renames?: readonly EntityRename[]): EntityNames;
+//#endregion
+//#region src/core/block-names.d.ts
+/**
+ * How the SQL names a block's functions and payload keys: the tenant's name
+ * (`blocks.tenant.entities.organization`), the block's renamed entities
+ * (`blocks.<name>.entities`) and the `blocks.<name>.functions` maps, merged.
+ * `better-supabase gen` writes it to each block's `names` in
+ * `blocks.generated.ts`.
+ */
+interface BlockNaming {
+  /** `blocks.tenant.entities.organization`, such as `workspace`. */
+  readonly tenant?: string;
+  /** Function name to the name the SQL writes it under. */
+  readonly functions?: Readonly<Record<string, string>>;
+  /** The block's own entities the config renames, such as `work_item` to `task`. */
+  readonly entities?: readonly EntityRename[];
+}
+/**
+ * Transport middleware that calls each block function by the name the SQL wrote
+ * it under and translates the payload keys: `create_organization` becomes
+ * `create_workspace` with `tenant: "workspace"`, `list_work_items` becomes
+ * `list_tasks` with `work_item` renamed to `task`, then `functions` renames
+ * single functions. Keys inside the arguments (`projectId`) go out renamed, and
+ * the keys of the result come back by their default names, so the block's
+ * client reads what it always has. Wrap a block's transport with it when the
+ * config sets `blocks.<name>.entities` or `blocks.<name>.functions`;
+ * `defineBlocks` does it from `blocks.generated.ts`.
+ */
+declare function blockNames(naming: BlockNaming): BlockTransportMiddleware;
+//#endregion
+//#region src/blocks/block-config.d.ts
+/**
+ * One block's entry in `blocks.generated.ts`, which `better-supabase gen`
+ * writes from the `blocks` config, so the SQL and TypeScript halves of a block
+ * read the same settings.
+ */
+interface GeneratedBlock {
+  /** The module schema (`blocks.<module>.schema`, then `sql.schema`). */
+  readonly schema: string;
+  /**
+   * The schema of the module's API wrappers (`blocks.<module>.api`, then
+   * `sql.api`).
+   */
+  readonly api?: string;
+  /**
+   * The options both halves read, with the module's defaults applied, such as
+   * `attachments.requireScan` or the notifications `topic`.
+   */
+  readonly options: Readonly<Record<string, unknown>>;
+  /**
+   * The names the SQL gives the block's functions when `blocks.<name>.entities`
+   * or `blocks.<module>.functions` renames them. `defineBlocks` wraps the
+   * block's transport with `blockNames(names)`.
+   */
+  readonly names?: BlockNaming;
+}
+/**
+ * `blocks.generated.ts`: the installed blocks' generated config, keyed by block
+ * name.
+ */
+type GeneratedBlocks = Readonly<Record<string, GeneratedBlock>>;
+/**
+ * The options a block's creator gets from its generated entry: the schema it
+ * calls (the API schema when there is one, since the wrappers there are what
+ * the caller may run) and the shared options. `defineBlocks` passes them;
+ * spread them into a creator you call yourself: `createAiChat({
+ * ...generatedOptions(blockConfig["ai-chat"]), transport })`.
+ */
+declare function generatedOptions<const E extends GeneratedBlock>(entry: E): E["options"] & {
+  readonly schema: string;
+};
+/**
+ * A realtime topic template from `blocks.generated.ts` with its placeholders
+ * filled in, such as the notifications topic `notifications:{userId}`.
+ */
+declare function fillTopic(template: string, values: Readonly<Record<string, string>>): string;
+//#endregion
+//#region src/blocks/entity-schema.d.ts
+type Nothing$1 = Record<never, never>;
+type OptionalFlag<T, K extends keyof T> = Nothing$1 extends Pick<T, K> ? {
+  readonly optional: true;
+} : {
+  readonly optional?: false;
+};
+type ArrayFlag<V> = unknown extends V ? Nothing$1 : [Exclude<V, undefined>] extends [readonly unknown[]] ? {
+  readonly array: true;
+} : {
+  readonly array?: false;
+};
+/**
+ * The fields of `entitySchema<T>`: one per key of `T`, marked `optional` when
+ * the key is and `array` when its value is a list, so the schema can't drift
+ * from the type.
+ */
+type EntityFieldSpecs<T> = { readonly [K in keyof T & string]-?: FieldSpec & OptionalFlag<T, K> & ArrayFlag<T[K]>; };
+interface EntitySchemaSpec<T> {
+  readonly title?: string;
+  readonly description?: string;
+  readonly fields: EntityFieldSpecs<T>;
+}
+/**
+ * A Standard Schema that also converts to JSON Schema (Standard JSON Schema),
+ * for one of a block's inputs, with the spec it was built from.
+ */
+interface EntitySchema<T> extends TableSchema<T> {
+  readonly spec: TableSchemaSpec;
+}
+/** What a block's client takes for one entity. */
+interface EntitySchemas {
+  /** Creating one (`WorkItemInput`). */
+  readonly input?: EntitySchema<unknown>;
+  /** Updating one (`WorkItemChange`). */
+  readonly change?: EntitySchema<unknown>;
+  /** Listing them (`WorkItemListOptions`). */
+  readonly listFilter?: EntitySchema<unknown>;
+}
+/** A block's input schemas, by entity key (its default singular noun). */
+type BlockSchemas = Readonly<Record<string, EntitySchemas>>;
+/**
+ * The Standard Schema for one of a block's input types, without a validation
+ * library: it validates like `tableSchema`, drops unknown keys, and converts to
+ * JSON Schema. The spec names every key of `T`.
+ */
+declare function entitySchema<T>(spec: EntitySchemaSpec<T>): EntitySchema<T>;
+//#endregion
+//#region src/blocks/sections.d.ts
+/**
+ * The module actions a section needs, such as `{ read: "read", write: "create"
+ * }`: the keys of `permissions.<module>` in `blocks.generated.ts`, so a renamed
+ * permission key still matches.
+ */
+interface SectionPermissions {
+  readonly read: string;
+  readonly write?: string;
+}
+/**
+ * One write a section takes on its record, such as adding a comment. Generated
+ * features turn each one into a Server Action or a mutation.
+ */
+interface SectionWrite<Client, Input, Output = unknown> {
+  /**
+   * The `permissions.<module>` action the write needs, for the `can*` flags.
+   * Default: the section's `permissions.write`. The SQL function checks the key
+   * again.
+   */
+  readonly permission?: string;
+  /** What the write takes besides the record, as a Standard Schema. */
+  readonly input: StandardSchemaV1<unknown, Input>;
+  readonly run: (client: Client, subject: SubjectRef, input: Input) => AsyncResult<Output>;
+}
+/** Any section write, for constraints. */
+interface AnySectionWrite {
+  readonly permission?: string;
+  readonly input: StandardSchemaV1;
+  readonly run: (client: never, subject: SubjectRef, input: never) => AsyncResult<unknown>;
+}
+/** A section's writes, by name. */
+type SectionWrites = Readonly<Record<string, AnySectionWrite>>;
+/**
+ * One event of a record's history that a section's rows hold, such as a comment
+ * or a saved version, for `loadTimeline`.
+ */
+interface TimelineItem<Row = unknown> {
+  /** Unique within its section. */
+  readonly id: string;
+  /** What happened, such as `comment` or `version`. */
+  readonly kind: string;
+  readonly at: Temporal.Instant;
+  /** The user who did it, when the row says. */
+  readonly actor?: string;
+  readonly row: Row;
+}
+/** What `defineSection` takes. */
+interface SectionDefinition<Client, Data, Options, Action, W extends SectionWrites = Record<never, never>> {
+  readonly permissions: SectionPermissions;
+  /**
+   * The SQL module whose permission keys `permissions` names. Default: the
+   * block's first SQL module.
+   */
+  readonly module?: string;
+  /** The section's rows for one subject. */
+  readonly load: (client: Client, subject: SubjectRef, options: Options | undefined) => AsyncResult<Data>;
+  /**
+   * How many rows each subject has, keyed by `subjectKey` (`type:id`), for a
+   * badge on each row of a list.
+   */
+  readonly count?: (client: Client, subjects: readonly SubjectRef[]) => AsyncResult<Readonly<Record<string, number>>>;
+  /**
+   * The section's value for each of many subjects, keyed by `subjectKey`
+   * (`type:id`), for a column of a record list (`defineRecordList`). Default:
+   * `count`, or else one `load` per subject.
+   */
+  readonly column?: (client: Client, subjects: readonly SubjectRef[]) => AsyncResult<Readonly<Record<string, unknown>>>;
+  /** The section's rows as timeline entries, for `loadTimeline`. */
+  readonly timeline?: (data: Data) => readonly TimelineItem[];
+  /** The block events that make the section stale; `*` ends a prefix. */
+  readonly events?: readonly string[];
+  /** A reducer for `useOptimistic`, applying a pending write to the rows. */
+  readonly optimistic?: (state: Data, action: Action) => Data;
+  /** The writes the section takes on its record, by name (`add`, `remove`). */
+  readonly writes?: W;
+}
+/**
+ * A part of a record page a block owns, such as a comment thread (an extension
+ * interface: `apiVersion: 1`). `loadSections` loads it,
+ * `createRecordController` keeps it current.
+ */
+interface Section<Client = never, Data = unknown, Options = never, Action = never, W extends SectionWrites = Record<never, never>> extends SectionDefinition<Client, Data, Options, Action, W> {
+  readonly apiVersion: 1;
+  readonly events: readonly string[];
+  readonly writes: W;
+}
+/** Any section, for constraints. */
+interface AnySection {
+  readonly apiVersion: 1;
+  readonly permissions: SectionPermissions;
+  readonly module?: string;
+  readonly load: (client: never, subject: SubjectRef, options: never) => AsyncResult<unknown>;
+  readonly count?: (client: never, subjects: readonly SubjectRef[]) => AsyncResult<Readonly<Record<string, number>>>;
+  readonly column?: (client: never, subjects: readonly SubjectRef[]) => AsyncResult<Readonly<Record<string, unknown>>>;
+  readonly timeline?: (data: never) => readonly TimelineItem[];
+  readonly events: readonly string[];
+  readonly optimistic?: (state: never, action: never) => unknown;
+  readonly writes?: SectionWrites;
+}
+/** A block's sections, by name. */
+type SectionMap = Readonly<Record<string, AnySection>>;
+/** The rows a section loads. */
+type SectionData<S> = S extends {
+  readonly load: (...args: never) => AsyncResult<infer Data>;
+} ? Data : never;
+/** The options a section's `load` takes. */
+type SectionOptions<S> = S extends {
+  readonly load: (client: never, subject: never, options: infer O) => unknown;
+} ? Exclude<O, undefined> : never;
+/** The names of a section's writes. */
+type SectionWriteName<S> = S extends {
+  readonly writes: infer W extends SectionWrites;
+} ? keyof W & string : never;
+/** What one of a section's writes resolves to. */
+type SectionWriteOutput<S, N extends string> = S extends {
+  readonly writes: infer W extends SectionWrites;
+} ? N extends keyof W ? W[N]["run"] extends ((...args: never) => AsyncResult<infer O>) ? O : never : never : never;
+/** What one of a section's writes takes besides the record. */
+type SectionWriteInput<S, N extends string> = S extends {
+  readonly writes: infer W extends SectionWrites;
+} ? N extends keyof W ? StandardSchemaV1.InferOutput<W[N]["input"]> : never : never;
+/** A section once loaded: its rows, its error, or hidden from the caller. */
+type SectionResult<Data> = {
+  readonly kind: "ok";
+  readonly data: Data;
+} | {
+  readonly kind: "error";
+  readonly error: DbError;
+} | {
+  readonly kind: "hidden";
+};
+/** Describes a section of a block's record page (`apiVersion: 1`). */
+declare function defineSection<Client, Data, Options = never, Action = never, const W extends SectionWrites = Record<never, never>>(definition: SectionDefinition<Client, Data, Options, Action, W>): Section<Client, Data, Options, Action, W>;
+/** Describes one write of a section, typed by its client and input. */
+declare function sectionWrite<Client, Input, Output>(write: SectionWrite<Client, Input, Output>): SectionWrite<Client, Input, Output>;
+/** What a write on one row of a section takes: the row's id. */
+interface SectionRowInput {
+  readonly id: string;
+}
+/** The input schema of a write on one row, such as removing a comment. */
+declare const sectionRowInput: EntitySchema<SectionRowInput>;
+/** Whether a block event type matches a section's `events` entry. */
+declare function sectionEventMatches(pattern: string, type: string): boolean;
+//#endregion
+//#region src/blocks/create-blocks.d.ts
+/** The CloudEvents `source` of block events that `createBlocks` forwards. */
+declare const BLOCK_EVENT_SOURCE = "/better-supabase/blocks";
+/**
+ * What every block's creator receives from `createBlocks`, before its ports and
+ * `with` settings.
+ */
+interface BlockContext extends BlockOptions {
+  /** Connectors, ai-providers and the workflow builder store their secrets here. */
+  readonly credentials?: CredentialProvider;
+  /** `betterSupabase.events`, for the block events of the blocks that emit them. */
+  readonly events?: EventHub;
+}
+interface CreateBlocksOptions extends Omit<BlockContext, "schema"> {
+  /**
+   * `blockConfig` from `blocks.generated.ts`: each block gets its schema (the
+   * API schema when the module has one) and the options its SQL half shares,
+   * such as `attachments.requireScan`, under its own name. Blocks without an
+   * entry use the module defaults.
+   */
+  readonly config?: GeneratedBlocks;
+  /**
+   * Where block events go, such as `auditLog.sink()`. Needs `events`; the
+   * forwarding lasts until `close()`, so build these blocks once rather than
+   * per request.
+   */
+  readonly audit?: EventSink;
+}
+/** The part of a `Db` that `createBlockClient` reads. */
+interface BlockClientSource extends DbTransportSource {
+  readonly $context?: {
+    readonly tenant?: string | undefined;
+  };
+}
+/** Options for `createBlockClient` and `BlockSet.client`. */
+interface BlockClientOptions extends Omit<CreateBlocksOptions, "transport" | "audit" | "config"> {
+  /** Default `dbTransport(db)`. */
+  readonly transport?: BlockContext["transport"];
+  /** `blockConfig` from `blocks.generated.ts`; `BlockSet.client` passes it. */
+  readonly config?: GeneratedBlocks;
+}
+/** Blocks keyed by the name the app gives each one. */
+type BlockMap = Readonly<Record<string, AnyBlock>>;
+type CreatedKeys<B extends BlockMap> = { readonly [K in keyof B]: B[K]["create"] extends undefined ? never : K; }[keyof B];
+type BuiltBlocks<B extends BlockMap> = { readonly [K in CreatedKeys<B>]: ClientOf<B[K]>; };
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends ((value: infer I) => void) ? I : never;
+/** The events of every block in `B`. */
+type BlocksEventMap<B extends BlockMap> = UnionToIntersection<EventMapOf<B[keyof B]["events"]>> extends (infer M extends EventMap) ? M : never;
+type SinkKeys<B extends BlockMap> = { readonly [K in keyof B]: "sink" extends keyof B[K]["provides"] ? K : never; }[keyof B];
+/**
+ * Outbox sinks of the blocks that provide one (`search`, `metrics`), keyed like
+ * the blocks, for `outbox.relayRoute({ consumers: { ...app.sinks } })`.
+ */
+type BlockSinks<B extends BlockMap = BlockMap> = { readonly [K in SinkKeys<B>]?: EventSink; };
+/** `withBlockHooks` hooks for each block, keyed like the blocks. */
+type BlocksHooks<B extends BlockMap> = { readonly [K in CreatedKeys<B>]?: BlockHooks<ClientOf<B[K]>>; };
+type Blocks<B extends BlockMap> = BuiltBlocks<B> & {
+  /** The outbox sinks of the blocks that provide one. */
+  readonly sinks: BlockSinks<B>;
+  /** Stops forwarding block events to `audit`. */
+  close(): void;
+};
+/** A set of blocks and the app's own events, from `defineBlocks`. */
+interface BlockSet<B extends BlockMap, M extends EventMap> {
+  readonly blocks: B;
+  /** The generated config the blocks are built with. */
+  readonly config: GeneratedBlocks;
+  /** Every block's events and the app's, typed. */
+  readonly events: Events<M>;
+  /**
+   * Builds the blocks with the generated config: `createBlocks({ ...options,
+   * config }, blocks)`.
+   */
+  create(options: Omit<CreateBlocksOptions, "config"> & {
+    readonly hooks?: BlocksHooks<B>;
+  }): Blocks<B>;
+  /**
+   * One block's client over a `Db`, built with the generated config: its calls
+   * run through `dbTransport(db)` and act in the `Db`'s tenant
+   * (`db.$context.tenant`) unless `options.tenant` names one. The blocks it
+   * consumes ports from are built on demand.
+   *
+   * ```ts
+   * const comments = blockSet.client(ctx.db, "comments");
+   * await comments.list({ type: "customer", id });
+   * ```
+   */
+  client<const K extends CreatedKeys<B>>(db: BlockClientSource, key: K, options?: BlockClientOptions & {
+    readonly hooks?: BlockHooks<ClientOf<B[K]>>;
+  }): ClientOf<B[K]>;
+  /** `onBlockEvent` typed by these blocks' events and the app's. */
+  on<const P extends BlockEventPattern<M>>(betterSupabase: {
+    readonly events: EventHub;
+  }, pattern: P, handler: (event: BlockEvent<M, BlockEventsMatching<M, P>>) => void): () => void;
+}
+/**
+ * The blocks an app uses, built with `blockConfig` from `blocks.generated.ts`
+ * (`better-supabase gen`), so each block's schema and the options its SQL half
+ * shares come from the `blocks` config, and the app's own events
+ * (`defineEvents`). The event types are the union of every block's events, so
+ * `on` and `events` type each one's data without `declare module` (invariant
+ * 2).
+ */
+declare function defineBlocks<const B extends BlockMap, const E extends readonly Events[] = []>(config: GeneratedBlocks, blocks: B, ...appEvents: E): BlockSet<B, BlocksEventMap<B> & MergedEventMap<E>>;
+/**
+ * Builds `blocks` with one set of options and wires them on their ports. Each
+ * block gets its schema and shared options from its entry in `config`
+ * (`blocks.generated.ts`), keyed by the block's name. Each block that consumes
+ * a port (`notifier`, `files`, `attachments`, `workflows`) gets it from the one
+ * block in the set that provides it, and `sinks` holds the outbox sinks the
+ * blocks provide. `credentials` reaches every block, and block events go to
+ * `audit`. Only the blocks you pass are imported, so the rest stay out of the
+ * bundle. `hooks` wraps each block's methods with `withBlockHooks`, and the
+ * ports are built from the wrapped clients, so a sibling's calls (ai-tasks
+ * sending notifications) go through the hooks too.
+ */
+declare function createBlocks<const B extends BlockMap>(options: CreateBlocksOptions & {
+  readonly hooks?: NoInfer<BlocksHooks<B>>;
+}, blocks: B): Blocks<B>;
+/**
+ * One block's client over a `Db`: its calls run through `dbTransport(db)` and
+ * act in the `Db`'s tenant (`db.$context.tenant`) unless `options.tenant` names
+ * one. Pass `config: blockConfig` so it calls the schema and function names
+ * `gen` wrote; `BlockSet.client(db, key)` does that for you.
+ *
+ * ```ts
+ * const comments = createBlockClient(ctx.db, commentsBlock, {
+ *   config: blockConfig,
+ * });
+ * ```
+ */
+declare function createBlockClient<const B extends AnyBlock>(db: BlockClientSource, block: B, options?: BlockClientOptions & {
+  readonly hooks?: NoInfer<BlockHooks<ClientOf<B>>>;
+}): ClientOf<B>;
+//#endregion
+//#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;
+    transform?: TransformOptions;
+  }): 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$1 | undefined = undefined> extends BlockTemporalOptions, BlockTenantOptions {
+  /**
+   * The subject types configured with `tenant: false`. Their files have no
+   * organization, so `upload`, `put` and `list` on such a subject send no
+   * tenant and need none.
+   */
+  readonly tenantless?: readonly string[];
+  /**
+   * 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;
+  /** `undefined` for a file uploaded without a subject. */
+  readonly subject: SubjectRef | undefined;
+  readonly bucket: string;
+  /**
+   * The current version's object path in the bucket:
+   * `{organizationId}/attachments/{id}` unless `options.path` says otherwise,
+   * with `-v<version>` from version 2 on.
+   */
+  readonly path: string;
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  /** Starts at 1; `replace` adds one, `restore` goes back to an earlier one. */
+  readonly version: number;
+  /** The image's width in pixels, as the uploader measured it. */
+  readonly width: number | undefined;
+  /** The image's height in pixels, as the uploader measured it. */
+  readonly height: number | undefined;
+  /** The document's page count, as the uploader counted it. */
+  readonly pages: number | undefined;
+  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;
+  /**
+   * The uploader's name and avatar from `profiles`, on `list()`; `undefined`
+   * without the `profiles` module or once the account is deleted.
+   */
+  readonly author: Author | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** Set by `confirm()` once the object exists. */
+  readonly uploadedAt: Temporal.Instant | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+}
+interface NewAttachment {
+  readonly name: string;
+  readonly mimeType: string;
+  /** Bytes; `confirm()` replaces it with the stored size. */
+  readonly size: number;
+  /**
+   * App data about the file, such as a caption or its source, kept with the
+   * record.
+   */
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** The image's width in pixels, for previews and layout before loading. */
+  readonly width?: number;
+  /** The image's height in pixels. */
+  readonly height?: number;
+  /** The document's page count. */
+  readonly pages?: number;
+}
+/** A new version of a file for `replace`: what changes with the bytes. */
+type AttachmentReplacement = Omit<NewAttachment, "metadata">;
+/** An earlier version of a file, kept when it was replaced. */
+interface AttachmentVersion {
+  readonly attachmentId: string;
+  readonly version: number;
+  readonly bucket: string;
+  readonly path: string;
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly width: number | undefined;
+  readonly height: number | undefined;
+  readonly pages: number | undefined;
+  readonly status: AttachmentStatus;
+  readonly scanDetail: string | undefined;
+  readonly uploadedBy: string | undefined;
+  readonly uploadedAt: Temporal.Instant | undefined;
+  readonly scannedAt: Temporal.Instant | undefined;
+  /** When the version stopped being the current one. */
+  readonly archivedAt: Temporal.Instant;
+}
+/** What `images().signedUrl` takes: `useImage` passes its options here. */
+interface AttachmentImageUrlOptions<V extends string = never> {
+  /** Seconds or a preset. Defaults to the client's `downloadTtl`. */
+  readonly ttl?: number | TtlPreset;
+  readonly transform?: ImageTransform<V>;
+}
+/**
+ * Image previews of attachments, shaped for `useImage(source, attachment,
+ * transform)` from `better-supabase/react`: a signed, resized URL per pixel
+ * density, behind the same scan gate as `download`.
+ */
+interface AttachmentImages<V extends string = never> {
+  readonly bucket: {
+    readonly id: string;
+    readonly public: false;
+    readonly variants: Readonly<Record<V, TransformOptions>>;
+  };
+  /** Attachments are private: an `invalid_request` error. */
+  publicUrl(target: Attachment | string): Result<string>;
+  /**
+   * A signed URL of the image resized by `transform`. `ATTACHMENT_NOT_SCANNED`
+   * until the scan passes, `ATTACHMENT_NOT_IMAGE` for a file that is not
+   * `image/*`. A target given by id is read first.
+   */
+  signedUrl(target: Attachment | string, options?: AttachmentImageUrlOptions<V>): AsyncResult<string>;
+}
+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. The methods
+ * that create or list files act in the block's `tenant`, except on a subject
+ * type in `options.tenantless`.
+ */
+interface Attachments<F extends object = Record<never, never>> {
+  /**
+   * Creates the pending record on `subject` (`null` for a file without one) and
+   * a signed upload URL for its path. When Storage refuses the URL, the record
+   * is deleted again.
+   */
+  upload(subject: SubjectRef | null, 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>;
+  /** The files of `subject`, or every file of the tenant without one. */
+  list(subject?: SubjectRef | null): 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;
+    /** An earlier version from `versions(id)`; default the current one. */
+    readonly version?: number;
+  }): AsyncResult<AttachmentDownload<F>>;
+  /**
+   * Deletes every version's file, then the record (the uploader, or
+   * `attachments.manage`).
+   */
+  remove(id: string): AsyncResult<boolean>;
+  /**
+   * Starts a new version of the file (its uploader with `attachments.upload`,
+   * or `attachments.manage`): the current one becomes an earlier version, and
+   * the new one waits for its upload to the signed URL, `confirm` and the scan.
+   * Emits `attachment.replaced`.
+   */
+  replace(id: string, file: AttachmentReplacement): AsyncResult<AttachmentUpload<F>>;
+  /** The file's earlier versions, newest first. */
+  versions(id: string): AsyncResult<readonly AttachmentVersion[]>;
+  /**
+   * Makes an earlier version current again; the current one becomes an earlier
+   * version. Emits `attachment.restored`.
+   */
+  restore(id: string, version: number): AsyncResult<Attachment & F>;
+  /**
+   * Image previews for `useImage`, with the app's named variants (`{ thumb: {
+   * width: 160, height: 160, resize: "cover" } }`).
+   */
+  images<V extends string = never>(variants?: Readonly<Record<V, TransformOptions>>): AttachmentImages<V>;
+  /**
+   * Creates the record on `subject` (`null` for none), 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(subject: SubjectRef | null, 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;
+  }>;
+}
+/** An `attachment_versions` row, as `list_attachment_versions` returns it. */
+declare function attachmentVersionOf(value: unknown): AttachmentVersion;
+declare function createAttachments<S extends StandardSchemaV1$1 | 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/mail-sync/providers.d.ts
+/** An address on a message, with the display name when the provider has one. */
+interface MailAddress {
+  readonly address: string;
+  readonly name?: string;
+}
+/** A message as a provider returns it, before it is stored. */
+interface MailProviderMessage {
+  /** The provider's id for the message. */
+  readonly externalId: string;
+  /** The provider's id for the thread or conversation. */
+  readonly threadId: string;
+  /** The RFC 5322 `Message-ID`, which matches a sent message to its copy. */
+  readonly messageId?: string;
+  /** Left out, it is `outbound` when `from` is the mailbox's own address. */
+  readonly direction?: "inbound" | "outbound";
+  readonly from?: MailAddress;
+  readonly to: readonly MailAddress[];
+  readonly cc: readonly MailAddress[];
+  readonly subject?: string;
+  readonly snippet?: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly sentAt: Temporal.Instant;
+}
+/** One page of a mailbox's changes since `cursor`. */
+interface MailPage {
+  readonly messages: readonly MailProviderMessage[];
+  /** Where the next page starts; the sync stores it on the mailbox. */
+  readonly cursor: string;
+  /** More changes wait behind `cursor` right now. */
+  readonly more: boolean;
+}
+/** What the block sends: the provider builds the message from it. */
+interface MailDraft {
+  readonly to: readonly MailAddress[];
+  readonly cc?: readonly MailAddress[];
+  readonly bcc?: readonly MailAddress[];
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+}
+/** The message a reply answers, in the provider's ids. */
+interface MailReplyTarget {
+  readonly threadId: string;
+  readonly externalId: string;
+  readonly messageId?: string;
+}
+/** What a provider returns for a sent message. */
+interface MailSent {
+  readonly externalId: string;
+  readonly threadId: string;
+  readonly messageId?: string;
+}
+interface MailListInput {
+  readonly token: CredentialToken;
+  /** Unset on a mailbox's first sync. */
+  readonly cursor?: string;
+  /** At most this many messages per page. */
+  readonly limit: number;
+  readonly signal?: AbortSignal;
+}
+interface MailSendInput {
+  readonly token: CredentialToken;
+  readonly from: MailAddress;
+  readonly draft: MailDraft;
+  readonly reply?: MailReplyTarget;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Reads and sends a member's mail with a token from their OAuth grant.
+ * Versioned: a breaking change to this contract ships a new `apiVersion`.
+ * Errors are `DbError`s: `unauthorized` for a token the provider refuses,
+ * `rate_limited` with `retryAfter`, `network` for a provider outage.
+ */
+interface MailProvider {
+  readonly apiVersion: 1;
+  /** The name a mailbox's `provider` column holds, such as `gmail`. */
+  readonly name: string;
+  /** The OAuth scopes the token needs, passed to `getToken`. */
+  readonly scopes?: readonly string[];
+  list(input: MailListInput): AsyncResult<MailPage>;
+  send(input: MailSendInput): AsyncResult<MailSent>;
+}
+/** Checks the provider's `apiVersion` before the block uses it. */
+declare function mailProviderOf(provider: MailProvider): MailProvider;
+interface HttpMailOptions {
+  /** Defaults to the global `fetch`. */
+  readonly fetch?: typeof fetch;
+  /** The API origin, for a proxy or a test server. */
+  readonly baseUrl?: string;
+  /** How many days of mail the first sync of a mailbox reads. Default: 30. */
+  readonly initialDays?: number;
+}
+/** Splits `Name <a@b>, "Last, First" <c@d>` into addresses. */
+declare function parseAddresses(header: string | undefined): MailAddress[];
+/**
+ * The RFC 5322 message for a draft: a `multipart/alternative` with the text and
+ * HTML parts, base64 encoded, and the reply headers when it answers one.
+ */
+declare function buildMime(input: {
+  readonly from: MailAddress;
+  readonly draft: MailDraft;
+  readonly messageId: string;
+  readonly reply?: MailReplyTarget;
+}): string;
+/** A `Message-ID` on the sender's domain. */
+declare function newMessageId(from: MailAddress): string;
+/** A Gmail API message (`format=full`) as a provider message. */
+declare function gmailMessage(value: unknown): MailProviderMessage | undefined;
+/**
+ * Gmail through its REST API with the member's OAuth token: the first sync
+ * reads the last `initialDays` of mail, later ones the history since the stored
+ * `historyId`. No Google SDK is needed.
+ */
+declare function gmailMail(options?: HttpMailOptions): MailProvider;
+/** A Microsoft Graph message as a provider message. */
+declare function outlookMessage(value: unknown, folder: string): MailProviderMessage | undefined;
+/**
+ * Outlook and Microsoft 365 through Microsoft Graph with the member's OAuth
+ * token: the inbox and sent items through delta queries, whose links are the
+ * cursor. No Microsoft SDK is needed.
+ */
+declare function outlookMail(options?: HttpMailOptions): MailProvider;
+//#endregion
+//#region src/blocks/mail-sync/mail-sync.d.ts
+/** A record a thread is linked to. */
+interface MailSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** A member's connected mailbox. */
+interface MailAccount {
+  readonly id: string;
+  readonly organizationId: string;
+  /** The member whose mailbox it is. */
+  readonly userId: string;
+  /** `gmail`, `outlook` or a custom provider's name. */
+  readonly provider: string;
+  readonly address: string;
+  /** The member's OAuth grant, resolved by the `credentials` provider. */
+  readonly credentialRef: CredentialRef;
+  /**
+   * `records`: members who can read a linked record see the thread, and it is
+   * logged as an engagement. `private`: only the member sees it.
+   */
+  readonly share: "records" | "private";
+  readonly status: "active" | "paused" | "error" | "disconnected";
+  readonly cursor?: string;
+  readonly lastSyncedAt?: Temporal.Instant;
+  readonly lastError?: string;
+  readonly createdAt: Temporal.Instant;
+}
+/** A conversation in one mailbox. */
+interface MailThread {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly accountId: string;
+  /** The mailbox's address. */
+  readonly address: string;
+  readonly externalId: string;
+  readonly subject?: string;
+  readonly snippet?: string;
+  readonly lastMessageAt?: Temporal.Instant;
+  readonly messageCount: number;
+  /** The engagement the thread is logged as, with `engagements` installed. */
+  readonly engagementId?: string;
+  readonly subjects: readonly MailSubject[];
+}
+/** A stored message. */
+interface MailMessage {
+  readonly id: string;
+  readonly threadId: string;
+  readonly accountId: string;
+  readonly externalId: string;
+  /** The RFC 5322 `Message-ID`. */
+  readonly messageId?: string;
+  readonly direction: "inbound" | "outbound";
+  readonly from?: MailAddress;
+  readonly to: readonly string[];
+  readonly cc: readonly string[];
+  readonly subject?: string;
+  readonly snippet?: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly sentAt: Temporal.Instant;
+  /** The template version a sent message was written from. */
+  readonly templateVersionId?: string;
+  /** Whether opens and clicks of a sent message are tracked. */
+  readonly tracked: boolean;
+  readonly openCount: number;
+  readonly clickCount: number;
+  /** The first open; a click counts as one. */
+  readonly openedAt?: Temporal.Instant;
+  readonly clickedAt?: Temporal.Instant;
+}
+/** How the messages sent from one template version did. */
+interface MailTemplateStats {
+  readonly templateVersionId: string;
+  readonly sent: number;
+  readonly opened: number;
+  readonly clicked: number;
+  /** Messages whose thread got an inbound message after them. */
+  readonly replied: number;
+}
+/** A thread with its messages, oldest first. */
+interface MailThreadDetail extends MailThread {
+  readonly messages: readonly MailMessage[];
+}
+/** What one sync run did. */
+interface MailSyncReport {
+  readonly accounts: number;
+  readonly stored: number;
+  /** The mailboxes that failed, marked `error` with the message. */
+  readonly failed: readonly {
+    readonly accountId: string;
+    readonly message: string;
+  }[];
+}
+interface MailSendDraft extends MailDraft {
+  /** Replies on this thread, to its latest message. */
+  readonly threadId?: string;
+  /**
+   * The template version the draft was written from, such as a `templates`
+   * version, for `templateStats`.
+   */
+  readonly templateVersionId?: string;
+  /**
+   * Tracks opens and clicks of the HTML body. Default: on when `createMailSync`
+   * has `tracking`; `true` without it is an error.
+   */
+  readonly track?: boolean;
+}
+interface MailSync {
+  /**
+   * Connects the caller's mailbox. `credentialRef` names the OAuth grant the
+   * app stored for them, with the organization as its `tenant`.
+   */
+  connect(organizationId: string, input: {
+    readonly provider: string;
+    readonly address: string;
+    readonly credentialRef: CredentialRef;
+    readonly share?: "records" | "private";
+  }): AsyncResult<MailAccount>;
+  /** Changes who sees the mailbox's threads, or pauses its sync. */
+  update(accountId: string, input: {
+    readonly share?: "records" | "private";
+    readonly paused?: boolean;
+  }): AsyncResult<MailAccount>;
+  /** Stops syncing; `purge` deletes its threads and messages too. */
+  disconnect(accountId: string, options?: {
+    readonly purge?: boolean;
+  }): AsyncResult<boolean>;
+  /** The caller's mailboxes; every member's with `mail.manage`. */
+  accounts(organizationId: string): AsyncResult<MailAccount[]>;
+  /** The threads the caller can see, the latest first (25, at most 100). */
+  threads(organizationId: string, options?: {
+    readonly accountId?: string;
+    readonly before?: Temporal.Instant;
+    readonly limit?: number;
+  }): AsyncResult<MailThread[]>;
+  /** A record's threads the caller can see, the latest first. */
+  threadsOf(subject: MailSubject, options?: {
+    readonly before?: Temporal.Instant;
+    readonly limit?: number;
+  }): AsyncResult<MailThread[]>;
+  /** A thread with its messages, or `undefined` when the caller can't see it. */
+  thread(id: string): AsyncResult<MailThreadDetail | undefined>;
+  /** Links a thread of the caller's mailbox to records by hand. */
+  link(threadId: string, subjects: readonly MailSubject[]): AsyncResult<MailThread>;
+  unlink(threadId: string, subject: MailSubject): AsyncResult<boolean>;
+  /**
+   * Sends from the caller's mailbox through its provider and stores the message
+   * on its thread. Needs `credentials` and the provider.
+   */
+  send(accountId: string, draft: MailSendDraft): AsyncResult<MailMessage>;
+  /**
+   * Pulls one mailbox's new mail into the database, page by page. Runs as the
+   * service role (a job or a cron route).
+   */
+  sync(account: MailAccount, options?: {
+    readonly pages?: number;
+    readonly limit?: number;
+  }): AsyncResult<number>;
+  /**
+   * Answers a request to the tracking route: records the open or click and
+   * returns the pixel, or a redirect to the link the message had. Service
+   * role.
+   */
+  track(request: Request): AsyncResult<Response>;
+  /** Opens, clicks and replies per template version, since a time. */
+  templateStats(organizationId: string, options?: {
+    readonly since?: Temporal.Instant;
+  }): AsyncResult<MailTemplateStats[]>;
+  /** Syncs the mailboxes not synced within `staleAfter`. Service role. */
+  syncDue(options?: {
+    /** At most this many mailboxes. Default: 25. */
+    readonly accounts?: number;
+    /** A Postgres interval. Default: `5 minutes`. */
+    readonly staleAfter?: string;
+    readonly pages?: number;
+    readonly limit?: number;
+  }): AsyncResult<MailSyncReport>;
+}
+interface MailSyncOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /** Resolves each mailbox's grant to a token, for `send` and `sync`. */
+  readonly credentials?: CredentialProvider;
+  /** The mail providers, such as `gmailMail()` and `outlookMail()`. */
+  readonly providers?: readonly MailProvider[];
+  /**
+   * Tracks opens and clicks: `url` is the public route that calls `track`, such
+   * as `https://app.example.com/api/mail/t`.
+   */
+  readonly tracking?: {
+    readonly url: string;
+  };
+  readonly hooks?: NoInfer<BlockHooks<MailSync>>;
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** A provider message as `ingest_mail` and `record_sent_mail` take it. */
+declare function messageArg(message: MailProviderMessage): Record<string, unknown>;
+/**
+ * The mail-sync block: members connect Gmail, Outlook or another provider with
+ * their own OAuth grant; a job pulls their mail into threads linked to the
+ * people and companies on them, logged as email engagements; `send` sends from
+ * the member's mailbox and stores the message.
+ */
+declare function createMailSync(options: MailSyncOptions): MailSync;
+//#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;
+  /** The `mail-sync` block, for the sequences block's email steps. */
+  readonly mailer: Pick<MailSync, "send">;
+  /** An outbox sink, for `outbox.relayRoute({ consumers: blocks.sinks })`. */
+  readonly sink: EventSink;
+}
+type PortName = keyof BlockPorts;
+//#endregion
+//#region src/blocks/define-block.d.ts
+/** Where a block sits in the catalog and in presets, in catalog order. */
+declare const BLOCK_CATEGORIES: readonly ["identity", "tenancy", "collaboration", "messaging", "growth", "crm", "work", "people", "commerce", "scheduling", "content", "ai", "automation", "developer", "admin", "database"];
+type BlockCategory = (typeof BLOCK_CATEGORIES)[number];
+/**
+ * The ports a block consumes: `required` fails `createBlocks` without a
+ * provider.
+ */
+type BlockConsumes = { readonly [P in PortName]?: "optional" | "required"; };
+/** The consumed ports, as the creator receives them. */
+type ConsumedPorts<C extends BlockConsumes> = { readonly [P in keyof C & PortName]?: BlockPorts[P]; };
+/** How a block builds each port it provides from its client and options. */
+type BlockProvides<Client, Options> = { readonly [P in PortName]?: (client: Client, options: Options) => BlockPorts[P] | undefined; };
+/**
+ * The ports a built block provides, by name. `createBlocks` calls each with the
+ * block's client and options.
+ */
+type ProvidedPorts<P extends PortName> = { readonly [K in P]: (client: never, options: never) => BlockPorts[K] | undefined; };
+/** An options schema per SQL module, keyed by module name (`blockOptions`). */
+type BlockOptionSchemas = Readonly<Record<string, BlockOptionsSchema>>;
+type Nothing = Record<never, never>;
+/** Event pattern to the read methods it makes stale. */
+type BlockInvalidates = Readonly<Record<string, readonly string[]>>;
+/** What `defineBlock` takes. */
+interface BlockDefinition<Name extends string, Options, Client, M extends EventMap, C extends BlockConsumes, P extends PortName, S extends SectionMap = Nothing> {
+  readonly name: Name;
+  /** The SQL modules (`SqlModule` keys) this block installs. */
+  readonly sql?: readonly string[];
+  /** The options of each SQL module, for `blocks.<module>.options`. */
+  readonly options?: BlockOptionSchemas;
+  /** The block's own events. */
+  readonly events?: Events<M>;
+  readonly consumes?: C;
+  readonly provides?: Pick<Required<BlockProvides<Client, Options>>, P>;
+  /** The creator, `create<Name>(options)`; absent for a block with only SQL. */
+  readonly create?: (options: Options) => Client;
+  /** The headless controller's name (ADR 0030), when the block has one. */
+  readonly client?: string;
+  readonly category: BlockCategory;
+  /** UI recipe slugs on `/recipes`. */
+  readonly recipes?: readonly string[];
+  /**
+   * Standard Schemas for what the client takes, by entity key: the create
+   * input, update change and list filter (`entitySchema`).
+   */
+  readonly schemas?: BlockSchemas;
+  /**
+   * The read methods each event pattern (`"work_item.*"`) makes stale, for
+   * `invalidateOnBlockEvents`. An event no pattern matches makes every read
+   * method of the block stale.
+   */
+  readonly invalidates?: BlockInvalidates;
+  /**
+   * The parts of a record page the block owns (`defineSection`), by name, for
+   * `loadSections` and `createRecordController`.
+   */
+  readonly sections?: S;
+}
+/**
+ * What `using` passes its creator: the shared block options and the consumed
+ * ports.
+ */
+type UsingOptions<C extends BlockConsumes> = BlockContext & ConsumedPorts<C>;
+/**
+ * One block (ADR 0029): its SQL modules, options, events, the ports it provides
+ * and consumes, and its creator. `createBlocks` wires blocks on their ports,
+ * never on their names.
+ */
+interface Block<Name extends string = string, Options = BlockContext, Client = unknown, M extends EventMap = Nothing, C extends BlockConsumes = Nothing, P extends PortName = never, S extends SectionMap = Nothing> {
+  readonly apiVersion: 1;
+  readonly name: Name;
+  readonly sql: readonly string[];
+  readonly options: BlockOptionSchemas;
+  readonly events: Events<M>;
+  readonly consumes: C;
+  readonly provides: ProvidedPorts<P>;
+  readonly create: ((options: Options) => Client) | undefined;
+  readonly client: string | undefined;
+  readonly category: BlockCategory;
+  readonly recipes: readonly string[];
+  /** Standard Schemas for what the client takes, by entity key. */
+  readonly schemas: BlockSchemas;
+  /**
+   * The read methods each event pattern (`"work_item.*"`) makes stale, for
+   * `invalidateOnBlockEvents`. An event no pattern matches makes every read
+   * method of the block stale.
+   */
+  readonly invalidates: BlockInvalidates;
+  /** The parts of a record page the block owns, by name. */
+  readonly sections: S;
+  /**
+   * The options `with` set, passed to `create` and the providers over the
+   * shared ones.
+   */
+  readonly settings: object;
+  /**
+   * This block with `settings` merged into the options `createBlocks` passes
+   * it.
+   */
+  with(settings: Partial<Options>): Block<Name, Options, Client, M, C, P, S>;
+  /**
+   * This block built by `create` instead, keeping its SQL, events and ports:
+   * for a creator's type parameters (`notificationsBlock.using((options) =>
+   * createNotifications({ ...options, types }))`) or a definition the creator
+   * needs (`settingsBlock.using((options) => createSettings({ ...options,
+   * settings }))`). The ports it provides receive the new client. Settings from
+   * an earlier `with` still reach `create` and the providers.
+   */
+  using<Next>(create: (options: UsingOptions<C>) => Next): Block<Name, UsingOptions<C>, Next, M, C, P, S>;
+}
+/** Any block, for constraints. */
+interface AnyBlock {
+  readonly apiVersion: 1;
+  readonly name: string;
+  readonly sql: readonly string[];
+  readonly options: BlockOptionSchemas;
+  readonly events: Events;
+  readonly consumes: BlockConsumes;
+  readonly provides: Partial<ProvidedPorts<PortName>>;
+  readonly create: ((options: never) => unknown) | undefined;
+  readonly client: string | undefined;
+  readonly category: BlockCategory;
+  readonly recipes: readonly string[];
+  readonly schemas?: BlockSchemas;
+  readonly invalidates?: BlockInvalidates;
+  readonly sections?: Readonly<Record<string, AnySection>>;
+  readonly settings: object;
+  with(settings: never): AnyBlock;
+  using(create: never): AnyBlock;
+}
+/**
+ * The block a creator makes, with its event map, consumed ports and provided
+ * ports.
+ */
+type BlockOf<Name extends string, Create extends (options: never) => unknown, M extends EventMap = Nothing, C extends BlockConsumes = Nothing, P extends PortName = never, S extends SectionMap = Nothing> = Block<Name, Parameters<Create>[0], ReturnType<Create>, M, C, P, S>;
+/** The client a block's creator returns. */
+type ClientOf<B> = B extends {
+  readonly create: ((options: never) => infer Client) | undefined;
+} ? Client : never;
+/** Describes a block with one manifest (ADR 0029). */
+declare function defineBlock<const Name extends string, Options = BlockContext, Client = unknown, M extends EventMap = Nothing, const C extends BlockConsumes = Nothing, P extends PortName = never, const S extends SectionMap = Nothing>(definition: BlockDefinition<Name, Options, Client, M, C, P, S>): Block<Name, Options, Client, M, C, P, S>;
+//#endregion
+export { AttachmentImageUrlOptions as $, sectionRowInput as $t, createMailSync as A, BlocksHooks as At, MailSendInput as B, SectionMap as Bt, MailSubject as C, BlockClientSource as Ct, MailTemplateStats as D, BlockSinks as Dt, MailSyncReport as E, BlockSet as Et, MailListInput as F, AnySection as Ft, mailProviderOf as G, SectionWrite as Gt, buildMime as H, SectionPermissions as Ht, MailPage as I, AnySectionWrite as It, outlookMessage as J, SectionWriteOutput as Jt, newMessageId as K, SectionWriteInput as Kt, MailProvider as L, Section as Lt, HttpMailOptions as M, createBlockClient as Mt, MailAddress as N, createBlocks as Nt, MailThread as O, Blocks as Ot, MailDraft as P, defineBlocks as Pt, AttachmentDownload as Q, sectionEventMatches as Qt, MailProviderMessage as R, SectionData as Rt, MailSendDraft as S, BlockClientOptions as St, MailSyncOptions as T, BlockMap as Tt, gmailMail as U, SectionResult as Ut, MailSent as V, SectionOptions as Vt, gmailMessage as W, SectionRowInput as Wt, Attachment as X, TimelineItem as Xt, parseAddresses as Y, SectionWrites as Yt, AttachmentBucket as Z, defineSection as Zt, Notifier as _, attachmentVersionOf as _t, BlockConsumes as a, EntitySchemas as an, AttachmentStatus as at, MailAccount as b, createObjectScanner as bt, BlockOf as c, GeneratedBlocks as cn, AttachmentVersion as ct, ClientOf as d, BlockNaming as dn, NewAttachment as dt, sectionWrite as en, AttachmentImages as et, ConsumedPorts as f, blockNames as fn, ObjectScanJob as ft, BlockPorts as g, entityNames as gn, ScannedObject as gt, defineBlock as h, EntityRename as hn, ScanVerdict as ht, BlockCategory as i, EntitySchemaSpec as in, AttachmentScannerOptions as it, messageArg as j, CreateBlocksOptions as jt, MailThreadDetail as k, BlocksEventMap as kt, BlockOptionSchemas as l, fillTopic as ln, Attachments as lt, UsingOptions as m, EntityNoun as mn, ObjectScannerOptions as mt, BLOCK_CATEGORIES as n, EntityFieldSpecs as nn, AttachmentScanJob as nt, BlockDefinition as o, entitySchema as on, AttachmentStorage as ot, ProvidedPorts as p, EntityNames as pn, ObjectScanner as pt, outlookMail as q, SectionWriteName as qt, Block as r, EntitySchema as rn, AttachmentScanner as rt, BlockInvalidates as s, GeneratedBlock as sn, AttachmentUpload as st, AnyBlock as t, BlockSchemas as tn, AttachmentReplacement as tt, BlockProvides as u, generatedOptions as un, AttachmentsOptions as ut, NotifierInput as v, createAttachmentScanner as vt, MailSync as w, BlockContext as wt, MailMessage as x, BLOCK_EVENT_SOURCE as xt, PortName as y, createAttachments as yt, MailReplyTarget as z, SectionDefinition as zt };