better-supabase 0.7.1 → 0.9.0

package/dist/blocks/index.d.ts

@@ -1,65 +1,10 @@
-import { i as sqlTransport, n as RpcClient, r as rpcTransport, t as BlockTransport } from "../block-transport-DvaoPuZ9.js";
-import { a as EventHub } from "../events-DWDhx77e.js";
-import { r as CredentialProvider } from "../provider-D-UEMvSD.js";
-import { i as CursorPageOptions, n as BlockOptions } from "../block-helpers-CKtbFcRv.js";
-import { f as AiFiles } from "../types-C05bxW-W.js";
+import { Ct as EventSpec, Dt as event, Et as defineEvents, Ot as mergeEvents, St as EventMapOf, bt as onBlockEvent, w as BlockEmit, wt as Events, xt as EventMap } from "../events-CTreRrgP.js";
+import { a as dbTransport, i as RpcClient, n as DbTransportOptions, o as rpcTransport, r as DbTransportSource, s as sqlTransport, t as BlockTransport } from "../block-transport-DaGGXjIw.js";
+import { i as CursorPageOptions, n as BlockOptions } from "../block-helpers-C86hPEjI.js";
+import { a as BlockTransportMiddleware, c as ExtendBlockTools, d as extendBlock, f as withBlockHooks, i as BlockMethodName, l as WithBlockHooksOptions, n as BlockHooks, o as BlockTransportRequest, p as wrapTransport, r as BlockMethodHooks, s as ExtendBlockOptions, t as BlockHookInfo, u as defineTransportMiddleware } from "../block-hooks-BLPWD3Jt.js";
+import { a as WithExtraFields, n as ExtraFields, o as blockFields, r as FieldsOf, t as BlockFields } from "../block-fields-5UA84ZUg.js";
 import { n as FinalRunState, r as RunState, t as FINAL_RUN_STATES } from "../run-state-CPo-1X2B.js";
-import { r as EventSink } from "../cloud-event-C1JCc1bH.js";
-import { r as AiTaskOutcome } from "../ai-tasks-Cd1HMFvB.js";
-import { a as BlockTransportMiddleware, c as ExtendBlockTools, d as extendBlock, f as withBlockHooks, i as BlockMethodName, l as WithBlockHooksOptions, n as BlockHooks, o as BlockTransportRequest, p as wrapTransport, r as BlockMethodHooks, s as ExtendBlockOptions, t as BlockHookInfo, u as defineTransportMiddleware } from "../block-hooks-plbZ0AbJ.js";
-import { n as FieldsOf, r as blockFields, t as BlockFields } from "../block-fields-SJ6fEf3o.js";
-//#region src/blocks/create-blocks.d.ts
-/** The CloudEvents `source` of block events that `createBlocks` forwards. */
-export declare const BLOCK_EVENT_SOURCE = "/better-supabase/blocks";
-interface CreateBlocksOptions extends BlockOptions {
-  /** Connectors, ai-providers and the builder store their secrets here. */
-  readonly credentials?: CredentialProvider;
-  /** `betterSupabase.events`, for the block events of the blocks that emit them. */
-  readonly events?: EventHub;
-  /**
-   * 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 notification type ai-tasks sends for each finished run, through the
-   * `notifications` block. Its data is `{ taskId, runId, ok, error?, chatId? }`.
-   */
-  readonly aiTaskNotification?: string;
-}
-/** What each block factory receives: the shared options and its siblings. */
-interface BlockContext extends BlockOptions {
-  readonly credentials?: CredentialProvider;
-  readonly events?: EventHub;
-  /** The `aiFiles` block, for knowledge. */
-  readonly files?: AiFiles;
-  /** Sends `aiTaskNotification` through the `notifications` block, for ai-tasks. */
-  readonly notify?: (outcome: AiTaskOutcome) => unknown;
-}
-/** Builds one block, usually a block creator such as `createOrganizations`. */
-type BlockFactory<T = unknown> = (context: BlockContext) => T;
-type BlockFactories = Readonly<Record<string, BlockFactory>> & {
-  readonly aiFiles?: BlockFactory<AiFiles>;
-};
-type BuiltBlocks<F extends BlockFactories> = { readonly [K in keyof F]: F[K] extends BlockFactory<infer T> ? T : never; };
-/** `withBlockHooks` hooks for each block, keyed by the names in `factories`. */
-type BlocksHooks<F extends BlockFactories> = { readonly [K in keyof F]?: BlockHooks<BuiltBlocks<F>[K]>; };
-type Blocks<F extends BlockFactories> = BuiltBlocks<F> & {
-  /** Stops forwarding block events to `audit`. */
-  close(): void;
-};
-/**
- * Builds the blocks in `factories` with one set of options, and wires the
- * siblings they share: the `aiFiles` block into knowledge, `credentials`
- * into connectors, ai-providers and the builder, the `notifications` block
- * into ai-tasks (with `aiTaskNotification`), and block events into `audit`.
- * Only the blocks you pass are imported, so the rest stay out of the bundle.
- * `hooks` wraps each block's methods with `withBlockHooks`, so siblings that
- * call a block (ai-tasks sending notifications) go through its hooks too.
- */
-export declare function createBlocks<const F extends BlockFactories>(options: CreateBlocksOptions & {
-  readonly hooks?: NoInfer<BlocksHooks<F>>;
-}, factories: F): Blocks<F>;
-//#endregion
-export { type BlockContext, type BlockFactories, type BlockFactory, type BlockFields, type BlockHookInfo, type BlockHooks, type BlockMethodHooks, type BlockMethodName, type BlockOptions, type BlockTransport, type BlockTransportMiddleware, type BlockTransportRequest, type Blocks, type BlocksHooks, type CreateBlocksOptions, type CursorPageOptions, type ExtendBlockOptions, type ExtendBlockTools, FINAL_RUN_STATES, type FieldsOf, type FinalRunState, type RpcClient, type RunState, type WithBlockHooksOptions, blockFields, defineTransportMiddleware, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };
+import { a as OptionKind, c as blockOptions, i as OptionInput, l as option, n as NO_OPTIONS, o as OptionSpec, r as OptionBuilders, s as OptionSpecs, t as BlockOptionsSchema, u as optionsJsonSchema } from "../options-CbSOj53r.js";
+import { A as BlockNaming, C as CreateBlocksOptions, D as GeneratedBlocks, E as GeneratedBlock, O as fillTopic, S as BlocksHooks, T as defineBlocks, _ as BlockMap, a as BlockConsumes, b as Blocks, c as BlockOptionSchemas, d as ConsumedPorts, f as ProvidedPorts, g as BlockContext, h as BLOCK_EVENT_SOURCE, i as BlockCategory, j as blockNames, k as generatedOptions, l as BlockProvides, m as defineBlock, n as BLOCK_CATEGORIES, o as BlockDefinition, p as UsingOptions, r as Block, s as BlockOf, t as AnyBlock, u as ClientOf, v as BlockSet, w as createBlocks, x as BlocksEventMap, y as BlockSinks } from "../define-block-CLZMEFeK.js";
+import { i as PortName, n as Notifier, r as NotifierInput, t as BlockPorts } from "../ports-Ca63W4cW.js";
+export { type AnyBlock, BLOCK_CATEGORIES, BLOCK_EVENT_SOURCE, type Block, type BlockCategory, type BlockConsumes, type BlockContext, type BlockDefinition, type BlockEmit, type BlockFields, type BlockHookInfo, type BlockHooks, type BlockMap, type BlockMethodHooks, type BlockMethodName, type BlockNaming, type BlockOf, type BlockOptionSchemas, type BlockOptions, type BlockOptionsSchema, type BlockPorts, type BlockProvides, type BlockSet, type BlockSinks, type BlockTransport, type BlockTransportMiddleware, type BlockTransportRequest, type Blocks, type BlocksEventMap, type BlocksHooks, type ClientOf, type ConsumedPorts, type CreateBlocksOptions, type CursorPageOptions, type DbTransportOptions, type DbTransportSource, type EventMap, type EventMapOf, type EventSpec, type Events, type ExtendBlockOptions, type ExtendBlockTools, type ExtraFields, FINAL_RUN_STATES, type FieldsOf, type FinalRunState, type GeneratedBlock, type GeneratedBlocks, NO_OPTIONS, type Notifier, type NotifierInput, type OptionBuilders, type OptionInput, type OptionKind, type OptionSpec, type OptionSpecs, type PortName, type ProvidedPorts, type RpcClient, type RunState, type UsingOptions, type WithBlockHooksOptions, type WithExtraFields, blockFields, blockNames, blockOptions, createBlocks, dbTransport, defineBlock, defineBlocks, defineEvents, defineTransportMiddleware, event, extendBlock, fillTopic, generatedOptions, mergeEvents, onBlockEvent, option, optionsJsonSchema, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/index.js

@@ -1,77 +1,213 @@
-import { n as forwardBlockEvents } from "../cloud-event-BnmD5fb9.js";
-import { n as rpcTransport, r as sqlTransport } from "../block-transport-BLr-ZgLc.js";
-import { d as isRecord } from "../block-helpers-DWHxHsEQ.js";
-import { i as wrapTransport, n as extendBlock, r as withBlockHooks, t as defineTransportMiddleware } from "../block-hooks-BmjMyXTa.js";
+import { n as isRecord } from "../guards-6F2bCtQR.js";
+import { t as tenantNames } from "../tenant-naming-Bsj3Uvap.js";
+import { i as forwardBlockEvents } from "../cloud-event-CTh9Sr5w.js";
+import { n as event, r as mergeEvents, t as defineEvents } from "../event-map-Dy2vKHai.js";
+import { o as onBlockEvent } from "../block-events-DD9Q_NUz.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../block-transport-G4t1umrR.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks, t as defineTransportMiddleware } from "../block-hooks-BsXncUlZ.js";
+import { n as blockFields } from "../block-fields-ffD6Gxe4.js";
+import { n as defineBlock, t as BLOCK_CATEGORIES } from "../define-block-B6Gjs57G.js";
+import { i as optionsJsonSchema, n as blockOptions, r as option, t as NO_OPTIONS } from "../options-BMjcVuaI.js";
 import { t as FINAL_RUN_STATES } from "../run-state-CgBKzYMW.js";
-import { t as blockFields } from "../block-fields-GFkxl4dP.js";
+//#region src/core/block-names.ts
+const TENANT_COLUMNS = ["organization_id", "active_organization_id"];
+/**
+* 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`.
+*/
+function blockNames(naming) {
+	const names = tenantNames(naming.tenant);
+	const functions = naming.functions ?? {};
+	const rename = (fn) => {
+		const renamed = names.rename(fn);
+		return functions[fn] ?? functions[renamed] ?? renamed;
+	};
+	const columns = new Map(TENANT_COLUMNS.map((column) => [names.rename(column), column]));
+	const restore = (value) => {
+		if (Array.isArray(value)) return value.map(restore);
+		if (typeof value !== "object" || value === null) return value;
+		return Object.fromEntries(Object.entries(value).map(([key, each]) => [columns.get(key) ?? key, restore(each)]));
+	};
+	return defineTransportMiddleware({
+		name: "block-names",
+		call: async (request, next) => {
+			const result = await next({
+				...request,
+				fn: rename(request.fn)
+			});
+			return names.renamed ? restore(result) : result;
+		}
+	});
+}
+//#endregion
+//#region src/blocks/block-config.ts
+/**
+* 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 })`.
+*/
+function generatedOptions(entry) {
+	return {
+		...entry.options,
+		schema: entry.api ?? entry.schema
+	};
+}
+/**
+* A realtime topic template from `blocks.generated.ts` with its
+* placeholders filled in, such as the notifications topic
+* `notifications:{userId}`.
+*/
+function fillTopic(template, values) {
+	return template.replaceAll(/\{([A-Za-z]+)\}/g, (match, name) => {
+		const value = values[name];
+		if (value === void 0) throw new TypeError(`fillTopic: no value for ${match} in "${template}"`);
+		return value;
+	});
+}
+//#endregion
 //#region src/blocks/create-blocks.ts
 /** The CloudEvents `source` of block events that `createBlocks` forwards. */
 const BLOCK_EVENT_SOURCE = "/better-supabase/blocks";
-const isNotificationSender = (value) => isRecord(value) && typeof value["send"] === "function";
 /**
-* Builds the blocks in `factories` with one set of options, and wires the
-* siblings they share: the `aiFiles` block into knowledge, `credentials`
-* into connectors, ai-providers and the builder, the `notifications` block
-* into ai-tasks (with `aiTaskNotification`), and block events into `audit`.
-* Only the blocks you pass are imported, so the rest stay out of the bundle.
-* `hooks` wraps each block's methods with `withBlockHooks`, so siblings that
-* call a block (ai-tasks sending notifications) go through its hooks too.
+* 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).
 */
-function createBlocks(options, factories) {
-	const { credentials, events, audit, aiTaskNotification, hooks, ...shared } = options;
-	if (audit !== void 0 && events === void 0) throw new TypeError("createBlocks: `audit` needs `events` to forward");
+function defineBlocks(config, blocks, ...appEvents) {
+	const events = { types: [.../* @__PURE__ */ new Set([...Object.values(blocks).flatMap((block) => block.events.types), ...appEvents.flatMap((each) => each.types)])] };
+	return {
+		blocks,
+		config,
+		events,
+		create: (options) => buildBlocks({
+			...options,
+			config
+		}, blocks),
+		on: (betterSupabase, pattern, handler) => onBlockEvent(betterSupabase, events, pattern, handler)
+	};
+}
+/**
+* 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.
+*/
+function createBlocks(options, blocks) {
+	return buildBlocks(options, blocks);
+}
+const UNIQUE_PORTS = [
+	"notifier",
+	"files",
+	"attachments",
+	"workflows"
+];
+/** `key`'s entry in `hooks`, which `BlocksHooks` keys like the blocks. */
+function hooksOf(hooks, key) {
+	if (hooks === void 0) return;
+	const entry = Object.entries(hooks).find(([name]) => name === key)?.[1];
+	return isRecord(entry) ? entry : void 0;
+}
+function buildBlocks(options, blocks) {
+	const { audit, hooks, config, ...shared } = options;
+	if (audit !== void 0 && shared.events === void 0) throw new TypeError("createBlocks: `audit` needs `events` to forward");
+	const providers = /* @__PURE__ */ new Map();
+	for (const port of UNIQUE_PORTS) {
+		const keys = Object.keys(blocks).filter((key) => blocks[key]?.provides[port] !== void 0);
+		if (keys.length > 1) throw new TypeError(`createBlocks: ${keys.map((key) => `"${key}"`).join(" and ")} both provide the ${port} port; pass one`);
+		const [key] = keys;
+		if (key !== void 0) providers.set(port, key);
+	}
+	for (const [key, block] of Object.entries(blocks)) for (const [port, need] of Object.entries(block.consumes)) if (need === "required" && !providers.has(port)) throw new TypeError(`createBlocks: "${key}" needs a block that provides the ${port} port`);
 	const built = /* @__PURE__ */ new Map();
 	const building = /* @__PURE__ */ new Set();
-	const notify = aiTaskNotification === void 0 || factories["notifications"] === void 0 ? void 0 : (outcome) => {
-		const notifications = build("notifications");
-		if (!isNotificationSender(notifications)) throw new TypeError("The notifications block has no send method");
-		return notifications.send(aiTaskNotification, {
-			recipients: [outcome.task.userId],
-			tenant: outcome.task.organizationId,
-			key: `ai-task-run:${outcome.run.id}`,
-			data: {
-				taskId: outcome.task.id,
-				runId: outcome.run.id,
-				ok: outcome.ok,
-				...outcome.error === void 0 ? {} : { error: outcome.error },
-				...outcome.chatId === void 0 ? {} : { chatId: outcome.chatId }
-			}
-		});
+	const blockOf = (key) => {
+		const block = blocks[key];
+		if (block === void 0) throw new TypeError(`No block named "${key}"`);
+		return block;
 	};
-	function contextFor(name) {
-		const files = name === "aiFiles" || factories.aiFiles === void 0 ? void 0 : build("aiFiles");
+	/**
+	* The options `key`'s creator gets: shared, then its generated config,
+	* then ports, then `with` settings.
+	*/
+	const optionsOf = (key) => {
+		const ports = {};
+		for (const port of UNIQUE_PORTS) {
+			if (blockOf(key).consumes[port] === void 0) continue;
+			const provider = providers.get(port);
+			if (provider === void 0 || provider === key) continue;
+			const value = portOf(provider, port);
+			if (value !== void 0) ports[port] = value;
+		}
+		const block = blockOf(key);
+		const entry = config?.[block.name];
 		return {
 			...shared,
-			...credentials === void 0 ? {} : { credentials },
-			...events === void 0 ? {} : { events },
-			...files === void 0 ? {} : { files },
-			...notify === void 0 ? {} : { notify }
+			...entry === void 0 ? {} : generatedOptions(entry),
+			...entry?.naming === void 0 ? {} : renamedTransports(entry.naming),
+			...ports,
+			...block.settings
 		};
+	};
+	/** `shared`'s transports, calling the block functions by the names the SQL gave them. */
+	function renamedTransports(naming) {
+		const middleware = blockNames(naming);
+		return {
+			transport: wrapTransport(shared.transport, middleware),
+			...shared.service === void 0 ? {} : { service: wrapTransport(shared.service, middleware) }
+		};
+	}
+	function portOf(key, port) {
+		const provide = blockOf(key).provides[port];
+		if (provide === void 0) return;
+		return provide(build(key), optionsOf(key));
 	}
-	function build(name) {
-		if (built.has(name)) return built.get(name);
-		const factory = factories[name];
-		if (factory === void 0) throw new TypeError(`No block named "${name}"`);
-		if (building.has(name)) throw new TypeError(`The "${name}" block depends on itself`);
-		building.add(name);
+	function build(key) {
+		if (built.has(key)) return built.get(key);
+		const block = blockOf(key);
+		if (block.create === void 0) throw new TypeError(`The "${block.name}" block has only SQL; it has no client to build`);
+		if (building.has(key)) throw new TypeError(`The "${key}" block depends on itself`);
+		building.add(key);
 		try {
-			const created = factory(contextFor(name));
-			const blockHooks = hooks?.[name];
-			const block = blockHooks !== void 0 && isRecord(created) ? withBlockHooks(created, blockHooks, {
-				block: name,
-				...events === void 0 ? {} : { logger: events.logger }
+			const create = block.create;
+			const created = create(optionsOf(key));
+			const blockHooks = hooksOf(hooks, key);
+			const client = blockHooks !== void 0 && isRecord(created) ? withBlockHooks(created, blockHooks, {
+				block: key,
+				...shared.events === void 0 ? {} : { logger: shared.events.logger }
 			}) : created;
-			built.set(name, block);
-			return block;
+			built.set(key, client);
+			return client;
 		} finally {
-			building.delete(name);
+			building.delete(key);
 		}
 	}
-	const blocks = {};
-	for (const name of Object.keys(factories)) blocks[name] = build(name);
-	const stop = audit === void 0 || events === void 0 ? void 0 : forwardBlockEvents({ events }, audit, { source: BLOCK_EVENT_SOURCE });
-	blocks["close"] = () => stop?.();
-	return blocks;
+	const result = {};
+	const sinks = {};
+	for (const [key, block] of Object.entries(blocks)) {
+		if (block.create === void 0) continue;
+		result[key] = build(key);
+		const sink = portOf(key, "sink");
+		if (sink !== void 0) sinks[key] = sink;
+	}
+	result["sinks"] = sinks;
+	const stop = audit === void 0 || shared.events === void 0 ? void 0 : forwardBlockEvents({ events: shared.events }, audit, { source: BLOCK_EVENT_SOURCE });
+	result["close"] = () => stop?.();
+	return result;
 }
 //#endregion
-export { BLOCK_EVENT_SOURCE, FINAL_RUN_STATES, blockFields, createBlocks, defineTransportMiddleware, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };
+export { BLOCK_CATEGORIES, BLOCK_EVENT_SOURCE, FINAL_RUN_STATES, NO_OPTIONS, blockFields, blockNames, blockOptions, createBlocks, dbTransport, defineBlock, defineBlocks, defineEvents, defineTransportMiddleware, event, extendBlock, fillTopic, generatedOptions, mergeEvents, onBlockEvent, option, optionsJsonSchema, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

package/dist/blocks/inventory/index.d.ts

@@ -0,0 +1,181 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult } from "../../result-Cj3yWhjH.js";
+import { M as CommerceEventData, N as CommerceSubjectEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "../../standard-C3_AAF3g.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { n as BlockOptions } from "../../block-helpers-C86hPEjI.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-BLPWD3Jt.js";
+import { r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { g as JobHandler } from "../../types-CdP0z5tS.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { n as Money } from "../../money-DFpWzQvk.js";
+//#region src/blocks/inventory/inventory.d.ts
+export declare const LOCATION_KINDS: readonly ["warehouse", "store", "virtual"];
+type LocationKind = (typeof LOCATION_KINDS)[number];
+/** The reasons `adjustStock` accepts. Counts, sales and transfers write their own. */
+export declare const ADJUST_REASONS: readonly ["adjustment", "damage", "loss", "return", "receipt"];
+type AdjustReason = (typeof ADJUST_REASONS)[number];
+export declare const PURCHASE_ORDER_STATUSES: readonly ["draft", "ordered", "partially_received", "received", "cancelled"];
+type PurchaseOrderStatus = (typeof PURCHASE_ORDER_STATUSES)[number];
+interface InventoryOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the locations' extra columns
+   * (`blocks.inventory.options.extraColumns`), keyed by column name. It
+   * types and parses `fields` on `saveLocation` and validates the ones it
+   * writes.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around any inventory method. */
+  readonly hooks?: NoInfer<BlockHooks<Inventory<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface LocationInput<F extends object = Record<never, never>> {
+  /** Updates this location; creates one when left out. */
+  readonly id?: string;
+  /** Unique within the organization, such as `WH-AMS`. */
+  readonly code: string;
+  readonly name: string;
+  /** Default `warehouse`. */
+  readonly kind?: LocationKind;
+  /** Values for the extra columns, by column name; the ones left out keep their value. */
+  readonly fields?: Partial<F> & Readonly<Record<string, unknown>>;
+}
+interface SavedLocation<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly code: string;
+  readonly active: boolean;
+  /** The app's extra columns (`options.extraColumns`), by column name; absent without any. */
+  readonly fields?: Readonly<Record<string, unknown>> & F;
+}
+interface StockChange {
+  readonly movementId: string;
+  readonly onHand: number;
+  readonly available: number;
+}
+interface StockCount {
+  /** Null when the count matched on-hand and no movement was written. */
+  readonly movementId: string | null;
+  readonly delta: number;
+  readonly onHand: number;
+}
+interface ReserveInput {
+  readonly quantity: number;
+  /** What holds the stock, such as `cart` or `order`. */
+  readonly referenceType?: string;
+  readonly referenceId?: string;
+  /** Default: 15 minutes from now. */
+  readonly expiresAt?: Temporal.Instant;
+}
+interface Reservation {
+  readonly id: string;
+  readonly expiresAt: Temporal.Instant;
+  /** Stock still available at the location after this hold. */
+  readonly available: number;
+}
+interface StockLine {
+  readonly variantId: string;
+  readonly quantity: number;
+}
+interface TransferInput {
+  readonly fromLocationId: string;
+  readonly toLocationId: string;
+  readonly lines: readonly StockLine[];
+  readonly note?: string;
+}
+interface PurchaseOrderLine extends StockLine {
+  /** The cost per unit, in the order's currency. */
+  readonly unitCost: Money;
+}
+interface PurchaseOrderInput {
+  readonly id?: string;
+  /** Where the goods arrive. */
+  readonly locationId: string;
+  /** A `config.subjects` record for the supplier, such as a company. */
+  readonly supplier?: {
+    readonly type: string;
+    readonly id: string;
+  };
+  readonly currency: string;
+  readonly expectedAt?: Temporal.Instant;
+  readonly lines: readonly PurchaseOrderLine[];
+  readonly note?: string;
+}
+interface ReceiptLine {
+  readonly lineId: string;
+  readonly quantity: number;
+}
+interface Receipt {
+  readonly status: PurchaseOrderStatus;
+  /** Units ordered and not yet received across the order. */
+  readonly backordered: number;
+}
+/** `F` types the locations' extra columns, from the `fields` schema. */
+interface Inventory<F extends object = Record<never, never>> {
+  saveLocation(organizationId: string, input: LocationInput<F>): AsyncResult<SavedLocation<F>>;
+  /** An inactive location takes no new reservations or transfers. */
+  setLocationActive(locationId: string, active: boolean): AsyncResult<boolean>;
+  /** Refused with `INVENTORY_LOCATION_IN_USE` once it has stock history. */
+  deleteLocation(locationId: string): AsyncResult<boolean>;
+  /** Writes a movement of `quantity` (negative to remove). Emits `stock.adjusted`. */
+  adjustStock(variantId: string, locationId: string, quantity: number, reason: AdjustReason, note?: string): AsyncResult<StockChange>;
+  /** Sets on-hand to a counted number and writes the difference as a `count` movement. */
+  countStock(variantId: string, locationId: string, counted: number, note?: string): AsyncResult<StockCount>;
+  /** Emits `stock.reorder_point_reached` when available stock drops to it. */
+  setReorderPoint(variantId: string, locationId: string, reorderPoint: number): AsyncResult<boolean>;
+  /** Holds stock until it is committed, released or expires. */
+  reserve(variantId: string, locationId: string, input: ReserveInput): AsyncResult<Reservation>;
+  /** Turns a hold into a `sale` movement. Resolves to the movement id. */
+  commitReservation(reservationId: string): AsyncResult<string>;
+  /** Resolves to `false` when the hold was already closed. */
+  releaseReservation(reservationId: string): AsyncResult<boolean>;
+  /** Releases expired holds. Service only. Resolves to the number released. */
+  expireReservations(maxRows?: number): AsyncResult<number>;
+  createTransfer(organizationId: string, input: TransferInput): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** Takes the stock out of the source location. */
+  shipTransfer(transferId: string): AsyncResult<boolean>;
+  /** Puts the stock into the destination location. */
+  receiveTransfer(transferId: string): AsyncResult<boolean>;
+  /** Returns shipped stock to the source location. */
+  cancelTransfer(transferId: string): AsyncResult<boolean>;
+  /** Creates or updates a draft purchase order. */
+  savePurchaseOrder(organizationId: string, input: PurchaseOrderInput): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** Marks the order as ordered and counts its lines as incoming stock. */
+  placePurchaseOrder(purchaseOrderId: string): AsyncResult<boolean>;
+  /** Receives some or all of the ordered units; the rest stay on backorder. */
+  receivePurchaseOrder(purchaseOrderId: string, lines: readonly ReceiptLine[]): AsyncResult<Receipt>;
+  cancelPurchaseOrder(purchaseOrderId: string): AsyncResult<boolean>;
+  /** The handler for a scheduled job that runs `expireReservations`. */
+  readonly job: JobHandler<unknown>;
+}
+/** Locations, a stock ledger, reservations, transfers and purchase orders over the `inventory` SQL module. */
+export declare function createInventory<S extends StandardSchemaV1 | undefined = undefined>(options: InventoryOptions<S>): Inventory<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/inventory/events.d.ts
+/** The events of the `inventory` block: type to data. */
+type InventoryEvents = {
+  readonly "stock.adjusted": CommerceEventData;
+  readonly "stock.reorder_point_reached": CommerceSubjectEventData;
+  readonly "reservation.created": CommerceEventData;
+  readonly "reservation.committed": CommerceEventData;
+  readonly "reservation.released": CommerceEventData;
+  readonly "transfer.shipped": CommerceEventData;
+  readonly "transfer.received": CommerceEventData;
+  readonly "transfer.cancelled": CommerceEventData;
+  readonly "purchase_order.placed": CommerceEventData;
+  readonly "purchase_order.received": CommerceEventData;
+  readonly "purchase_order.cancelled": CommerceEventData;
+};
+/** The `inventory` block's event types, for its manifest and `onBlockEvent`. */
+export declare const inventoryEvents: Events<InventoryEvents>;
+//#endregion
+//#region src/blocks/inventory/manifest.d.ts
+/** The `inventory` block's manifest (ADR 0029). */
+export declare const inventoryBlock: BlockOf<"inventory", typeof createInventory, InventoryEvents>;
+//#endregion
+export { type AdjustReason, type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Inventory, type InventoryEvents, type InventoryOptions, type LocationInput, type LocationKind, type PurchaseOrderInput, type PurchaseOrderLine, type PurchaseOrderStatus, type Receipt, type ReceiptLine, type Reservation, type ReserveInput, type RpcClient, type SavedLocation, type StockChange, type StockCount, type StockLine, type TransferInput, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };