better-supabase 0.12.0 → 0.13.0

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

@@ -0,0 +1,281 @@
+import { D as BlockEventPattern, St as EventMapOf, T as BlockEvent, Tt as MergedEventMap, k as BlockEventsMatching, o as EventHub, wt as Events, xt as EventMap } from "./events-DhGgwqQA.js";
+import { r as CredentialProvider } from "./provider-Dmsbl8ug.js";
+import { n as BlockOptions } from "./block-helpers-DyA5BAW4.js";
+import { a as BlockTransportMiddleware, n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { t as BlockOptionsSchema } from "./options-CIf3xni7.js";
+import { i as EventSink } from "./cloud-event-CidL9jiw.js";
+import { i as PortName, t as BlockPorts } from "./ports-BltcWsHf.js";
+//#region src/core/block-names.d.ts
+/**
+ * How the SQL names the block functions: `sql.naming.tenant` and the
+ * `blocks.<name>.functions` maps, merged. `better-supabase gen` writes it to
+ * each block's `naming` in `blocks.generated.ts`.
+ */
+interface BlockNaming {
+  /** `sql.naming.tenant`, such as `workspace`. */
+  readonly tenant?: string;
+  /** Function name to the name the SQL writes it under. */
+  readonly functions?: Readonly<Record<string, string>>;
+}
+/**
+ * Transport middleware that calls each block function by the name the SQL wrote
+ * it under: `create_organization` becomes `create_workspace` with `tenant:
+ * "workspace"`, then `functions` renames single functions. Wrap a block's
+ * transport with it when the config sets `sql.naming` 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 `sql.naming` or
+   * `blocks.<module>.functions` renames them. `defineBlocks` wraps the block's
+   * transport with `blockNames(naming)`.
+   */
+  readonly naming?: 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/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;
+}
+/** 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>;
+  /** `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>;
+//#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>;
+/** What `defineBlock` takes. */
+interface BlockDefinition<Name extends string, Options, Client, M extends EventMap, C extends BlockConsumes, P extends PortName> {
+  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[];
+}
+/**
+ * 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> {
+  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[];
+  /**
+   * 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>;
+  /**
+   * 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>;
+}
+/** 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 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> = Block<Name, Parameters<Create>[0], ReturnType<Create>, M, C, P>;
+/** 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>(definition: BlockDefinition<Name, Options, Client, M, C, P>): Block<Name, Options, Client, M, C, P>;
+//#endregion
+export { BlockNaming as A, CreateBlocksOptions as C, GeneratedBlocks as D, GeneratedBlock as E, fillTopic as O, BlocksHooks as S, defineBlocks as T, BlockMap as _, BlockConsumes as a, Blocks as b, BlockOptionSchemas as c, ConsumedPorts as d, ProvidedPorts as f, BlockContext as g, BLOCK_EVENT_SOURCE as h, BlockCategory as i, blockNames as j, generatedOptions as k, BlockProvides as l, defineBlock as m, BLOCK_CATEGORIES as n, BlockDefinition as o, UsingOptions as p, Block as r, BlockOf as s, AnyBlock as t, ClientOf as u, BlockSet as v, createBlocks as w, BlocksEventMap as x, BlockSinks as y };

package/dist/delegation-DeAJehLk.js

@@ -0,0 +1,146 @@
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { n as actorOf } from "./actor-C9pwyCVz.js";
+import { n as impersonatorClaim, t as actClaim } from "./impersonation-DFfDVJHk.js";
+//#region src/auth/delegation.ts
+/**
+* The claim `forContext({ permissions })` sets: the permission keys the work
+* may use. `better_supabase.cap_allows` refuses every other key, and a job
+* queued under a cap keeps it.
+*/
+const PERMISSION_CAP_CLAIM = "bs_permission_cap";
+/**
+* The claims a delegated token adds; `contextClaims` never takes them from
+* `claimsFor`.
+*/
+const DELEGATION_CLAIMS = [
+	"act",
+	"client_id",
+	"scope",
+	"authorization_details",
+	PERMISSION_CAP_CLAIM
+];
+/**
+* `*` grants every key and `prefix.*` every key under prefix, as
+* `permission_matches` in SQL.
+*/
+function permissionMatches(granted, wanted) {
+	return granted === "*" || granted === wanted || granted.endsWith(".*") && wanted.startsWith(granted.slice(0, -1));
+}
+/**
+* The permission cap in `claims`: `undefined` without one, `false` for a cap
+* that is not a list of strings.
+*/
+function permissionCapOf(claims) {
+	const cap = claims[PERMISSION_CAP_CLAIM];
+	if (cap === void 0) return;
+	return Array.isArray(cap) && cap.every((key) => typeof key === "string") ? cap : false;
+}
+/**
+* The keys of `wanted` that `inherited` allows, so a cap only ever narrows.
+* Either side alone is the cap; neither is no cap.
+*/
+function narrowCap(inherited, wanted) {
+	if (wanted === void 0) return inherited;
+	if (inherited === void 0) return wanted;
+	return wanted.filter((key) => inherited.some((granted) => permissionMatches(granted, key)));
+}
+const INVALID = {
+	ok: false,
+	reason: "invalid-delegation"
+};
+function isDetail(value) {
+	return isRecord(value) && typeof value["type"] === "string" && value["type"] !== "";
+}
+function scopeOf(value) {
+	if (value === void 0) return;
+	const scopes = typeof value === "string" ? value.split(/\s+/u) : Array.isArray(value) && value.every((item) => typeof item === "string") ? value : void 0;
+	if (scopes === void 0) return false;
+	const joined = scopes.filter(Boolean).join(" ");
+	return joined === "" ? void 0 : joined;
+}
+/**
+* The delegation in `claims`, for a token an OAuth client or agent acts with: a
+* `client_id`, or an `act` chain that is not a support or impersonation level.
+* `{ ok: true }` without `delegation` for any other session. An invalid `act`
+* chain, a `client_id` that is not a non-empty string, a `scope` that is
+* neither a string nor a list of strings, and `authorization_details` that are
+* not objects with a `type` are `{ ok: false }`: the work must not run as the
+* user alone.
+*/
+function delegatedClaims(claims) {
+	const outcome = actorOf(claims);
+	if (!outcome.ok) return {
+		ok: false,
+		reason: "invalid-chain"
+	};
+	const client = claims["client_id"];
+	if (client !== void 0 && (typeof client !== "string" || client === "")) return INVALID;
+	const actor = outcome.actor;
+	const chain = actor?.kind === "oauth-client" || actor?.kind === "agent" ? actor.chain : void 0;
+	if (client === void 0 && chain === void 0) return { ok: true };
+	const scope = scopeOf(claims["scope"]);
+	if (scope === false) return INVALID;
+	const details = claims["authorization_details"];
+	if (details !== void 0 && !(Array.isArray(details) && details.every(isDetail))) return INVALID;
+	return {
+		ok: true,
+		delegation: {
+			...client === void 0 ? {} : { client_id: client },
+			...scope === void 0 ? {} : { scope },
+			...details === void 0 ? {} : { authorization_details: details },
+			...chain === void 0 ? {} : { act: chain }
+		}
+	};
+}
+/**
+* The SQL claims for the user in a recorded context: the user as
+* `authenticated`, the tenant as `tenant_id`, and the context's delegation, so
+* the access functions (through `cap_allows`), `token_scope_allows` and the
+* TypeScript scope checks narrow the work to what the queuing token held, and
+* to its permission cap. The `act` claim is the support session, else the OAuth
+* client chain, else the impersonating admin.
+*/
+function contextClaims(context, options = {}) {
+	const { actor, tenant } = context;
+	if (actor?.kind !== "user") return {
+		ok: false,
+		message: `forContext needs a user actor, got ${actor ? actor.kind : "none"}: use admin() for service work`
+	};
+	const claims = context.claims ?? {};
+	const recorded = actorOf(claims);
+	const delegated = delegatedClaims(claims);
+	const inherited = permissionCapOf(claims);
+	if (inherited === false) return {
+		ok: false,
+		message: "forContext got an invalid permission cap"
+	};
+	const cap = narrowCap(inherited, options.permissions);
+	if (!recorded.ok || !delegated.ok) return {
+		ok: false,
+		message: !recorded.ok || !delegated.ok && delegated.reason === "invalid-chain" ? "forContext got an invalid act claim" : "forContext got invalid delegation claims"
+	};
+	const support = recorded.actor?.kind === "support" ? recorded.actor : void 0;
+	const delegation = delegated.delegation ?? {};
+	const act = support ? impersonatorClaim(support) : delegation.act ?? (actor.impersonator ? actClaim({
+		actor: actor.impersonator,
+		reason: options.reason ?? "job"
+	}) : void 0);
+	const extra = Object.fromEntries(Object.entries(options.extra ?? {}).filter(([key]) => !DELEGATION_CLAIMS.includes(key)));
+	const impersonator = support?.id ?? actor.impersonator;
+	return {
+		ok: true,
+		claims: {
+			...extra,
+			role: "authenticated",
+			sub: actor.id,
+			...tenant === void 0 ? {} : { tenant_id: tenant },
+			...delegation,
+			...act === void 0 ? {} : { act },
+			...cap === void 0 ? {} : { [PERMISSION_CAP_CLAIM]: cap }
+		},
+		...impersonator === void 0 ? {} : { impersonator },
+		...support?.readOnly ? { readOnly: true } : {}
+	};
+}
+//#endregion
+export { narrowCap as a, delegatedClaims as i, PERMISSION_CAP_CLAIM as n, permissionCapOf as o, contextClaims as r, DELEGATION_CLAIMS as t };

package/dist/delivery-Bm0jxmzI.js

@@ -0,0 +1,29 @@
+//#region src/blocks/notifications/delivery.ts
+/**
+* The headers automated mail carries: `Auto-Submitted: auto-generated` (RFC 3834)
+* on every message, so auto-responders stay quiet, and on `notification` mail
+* with an unsubscribe target, `List-Unsubscribe` (RFC 2369).
+* `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) needs the
+* `https:` URL, so a `mailto:`-only target leaves it out. Throws a `TypeError`
+* for a URL that isn't `https:` or an address that isn't `mailto:`.
+*/
+function mailHeaders(category, unsubscribe) {
+	const headers = { "Auto-Submitted": "auto-generated" };
+	if (category !== "notification" || unsubscribe === void 0) return headers;
+	const targets = [];
+	if (unsubscribe.url !== void 0) {
+		if (!URL.canParse(unsubscribe.url)) throw new TypeError(`The unsubscribe URL "${unsubscribe.url}" is not a URL`);
+		if (new URL(unsubscribe.url).protocol !== "https:") throw new TypeError(`The unsubscribe URL "${unsubscribe.url}" must use https (RFC 8058)`);
+		targets.push(`<${unsubscribe.url}>`);
+	}
+	if (unsubscribe.mailto !== void 0) {
+		if (!/^mailto:[^\s<>]+$/i.test(unsubscribe.mailto)) throw new TypeError(`The unsubscribe address "${unsubscribe.mailto}" must be a mailto: URI`);
+		targets.push(`<${unsubscribe.mailto}>`);
+	}
+	if (targets.length === 0) return headers;
+	headers["List-Unsubscribe"] = targets.join(", ");
+	if (unsubscribe.url !== void 0) headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+	return headers;
+}
+//#endregion
+export { mailHeaders as t };

package/dist/delivery-n6lZGuGx.d.ts

@@ -0,0 +1,71 @@
+//#region src/blocks/notifications/delivery.d.ts
+/**
+ * What a message is for. `security` (sign-in codes, password resets, new-device
+ * alerts) and `approval` (a request waiting on the reader) mail never carries
+ * an unsubscribe link: the reader can't opt out of it.
+ */
+type MailCategory = "notification" | "security" | "approval";
+/** One email, ready for a provider. */
+interface EmailMessage {
+  readonly from: string;
+  readonly to: string;
+  readonly subject: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly replyTo?: string;
+  readonly category: MailCategory;
+  /**
+   * Headers the provider sends as given: `Auto-Submitted` on every message, and
+   * `List-Unsubscribe` with `List-Unsubscribe-Post` on notification mail that
+   * has an unsubscribe address.
+   */
+  readonly headers: Readonly<Record<string, string>>;
+}
+/** The message each channel's transport sends. */
+interface DeliveryMessages {
+  readonly email: EmailMessage;
+}
+type DeliveryChannel = keyof DeliveryMessages;
+interface DeliverySendOptions {
+  /**
+   * The delivery id. A provider that dedupes by key sends a retried delivery
+   * once; pass it as the provider's idempotency key.
+   */
+  readonly idempotencyKey: string;
+}
+interface DeliveryReceipt {
+  /** The provider's id for the message, kept for support and webhooks. */
+  readonly providerMessageId?: string;
+}
+/**
+ * Sends one message through a provider (Resend, Postmark, SES, SMTP). A throw
+ * retries the delivery after its lease, with the same idempotency key.
+ */
+interface DeliveryTransport<C extends DeliveryChannel = DeliveryChannel> {
+  readonly apiVersion: 1;
+  readonly channel: C;
+  /** Stored on the delivery, e.g. `resend`. */
+  readonly provider: string;
+  send(message: DeliveryMessages[C], options: DeliverySendOptions): DeliveryReceipt | void | Promise<DeliveryReceipt | void>;
+}
+/**
+ * Where a reader unsubscribes: an `https:` URL for one-click, a `mailto:`
+ * address, or both.
+ */
+interface UnsubscribeTarget {
+  /** Receives the RFC 8058 one-click `POST`; must be `https:`. */
+  readonly url?: string;
+  /** `mailto:` address, with an optional `?subject=`. */
+  readonly mailto?: string;
+}
+/**
+ * The headers automated mail carries: `Auto-Submitted: auto-generated` (RFC 3834)
+ * on every message, so auto-responders stay quiet, and on `notification` mail
+ * with an unsubscribe target, `List-Unsubscribe` (RFC 2369).
+ * `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058) needs the
+ * `https:` URL, so a `mailto:`-only target leaves it out. Throws a `TypeError`
+ * for a URL that isn't `https:` or an address that isn't `mailto:`.
+ */
+declare function mailHeaders(category: MailCategory, unsubscribe?: UnsubscribeTarget): Record<string, string>;
+//#endregion
+export { DeliveryTransport as a, UnsubscribeTarget as c, DeliverySendOptions as i, mailHeaders as l, DeliveryMessages as n, EmailMessage as o, DeliveryReceipt as r, MailCategory as s, DeliveryChannel as t };

package/dist/documents-BijGGIjr.d.ts

@@ -0,0 +1,99 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-mijqfoJN.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";
+//#region src/blocks/documents/documents.d.ts
+interface DocumentsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Documents>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** Which document to open: one per subject and name. */
+interface DocumentRef {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** Default: `body`. */
+  readonly name?: string;
+}
+/** A Yjs update and its place in the document's log. */
+interface DocumentUpdate {
+  readonly seq: number;
+  readonly update: Uint8Array;
+}
+interface DocumentInfo {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly name: string;
+  /** The private realtime topic for updates and presence. */
+  readonly topic: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What a client needs to rebuild the document. */
+interface DocumentState {
+  /** The compacted state; unset before the first compaction. */
+  readonly snapshot?: Uint8Array;
+  /** The last update the snapshot contains, `0` without one. */
+  readonly snapshotSeq: number;
+  /** The updates after the snapshot, oldest first. */
+  readonly updates: readonly DocumentUpdate[];
+}
+interface OpenedDocument extends DocumentInfo, DocumentState {
+  /** Whether the caller may push updates. */
+  readonly canWrite: boolean;
+}
+interface DocumentVersion {
+  readonly id: string;
+  readonly number: number;
+  readonly label?: string;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface Documents {
+  /** The document's state; creates it on first open for an editor. */
+  open(ref: DocumentRef): AsyncResult<OpenedDocument>;
+  /** Appends an update and returns its sequence number. */
+  push(documentId: string, update: Uint8Array): AsyncResult<number>;
+  /**
+   * Updates after `afterSeq`. When compaction dropped some of them, the result
+   * carries the snapshot to start from instead.
+   */
+  pull(documentId: string, afterSeq: number): AsyncResult<DocumentState>;
+  /**
+   * Stores `state` as the snapshot through `throughSeq` and drops those
+   * updates. Returns false when a newer snapshot exists. The service role or
+   * `documents.manage`.
+   */
+  compact(documentId: string, state: Uint8Array, throughSeq: number): AsyncResult<boolean>;
+  /** Saves the merged state as a version; needs the versions module. */
+  saveVersion(documentId: string, state: Uint8Array, label?: string): AsyncResult<{
+    readonly id: string;
+    readonly number: number;
+  }>;
+  /** Newest first; needs the versions module. */
+  versions(documentId: string): AsyncResult<readonly DocumentVersion[]>;
+  /** A saved state; needs the versions module. */
+  version(documentId: string, versionId: string): AsyncResult<Uint8Array>;
+  /** Documents with at least `minUpdates` uncompacted updates. Service role. */
+  toCompact(options?: {
+    readonly minUpdates?: number;
+    readonly limit?: number;
+  }): AsyncResult<readonly string[]>;
+}
+/** The `documents` SQL module as typed calls, with updates as bytes. */
+declare function createDocuments(options: DocumentsOptions): Documents;
+//#endregion
+export { DocumentVersion as a, OpenedDocument as c, DocumentUpdate as i, createDocuments as l, DocumentRef as n, Documents as o, DocumentState as r, DocumentsOptions as s, DocumentInfo as t };