better-supabase 0.8.0 → 0.9.0

package/dist/blocks/deals/index.js

@@ -0,0 +1,380 @@
+import { t as temporal } from "../../temporal-required-DqRzr7i0.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-BlgnMB0H.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, I as textOf, S as optionalInstant, a as bigintOf, d as enumOrThrow, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-CfG_MvDR.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { n as blockFields } from "../../block-fields-ffD6Gxe4.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { c as isMoney, s as isCurrency } from "../../money-95Rff2vT.js";
+import { a as optionalAmountText, i as moneyOf, n as amountsError, o as optionalMoneyOf, r as currencyMismatch, s as unknownCurrency, t as amountText } from "../../money-codec-C_-K5ZUU.js";
+import { r as plainDate } from "../../sales-shared-SblIgCgI.js";
+import { r as totalsOf, t as lineArg } from "../../sales-lines-BAk8In-Z.js";
+import { t as dealsSqlOptions } from "../../options-DTDxFT6J.js";
+//#region src/blocks/deals/deals.ts
+const OUTCOMES = [
+	"open",
+	"won",
+	"lost"
+];
+const FORECASTS = [
+	"commit",
+	"best_case",
+	"pipeline",
+	"omit"
+];
+/** The fields `update` writes, by name: any other field is an extra column. */
+const BUILT_IN = /* @__PURE__ */ new Set([
+	"name",
+	"motion",
+	"priority",
+	"ownerId",
+	"product",
+	"seats",
+	"amount",
+	"existingAmount",
+	"currency",
+	"valuePeriod",
+	"amountSource",
+	"stageId",
+	"probability",
+	"forecast",
+	"closeOn",
+	"nextStep",
+	"nextAt",
+	"nextKind",
+	"flags",
+	"source",
+	"note",
+	"lostReason",
+	"company"
+]);
+const KNOWN = /* @__PURE__ */ new Set([
+	"id",
+	"tenant_id",
+	"number",
+	"identifier",
+	"name",
+	"company_type",
+	"company_id",
+	"motion",
+	"priority",
+	"owner_user_id",
+	"product",
+	"seats",
+	"amount",
+	"existing_amount",
+	"currency",
+	"value_period",
+	"amount_source",
+	"pipeline_id",
+	"stage_id",
+	"stage_entered_at",
+	"outcome",
+	"probability",
+	"forecast_category",
+	"opened_on",
+	"expected_close_on",
+	"slipped_from",
+	"push_count",
+	"closed_at",
+	"next_step",
+	"next_at",
+	"next_kind",
+	"flags",
+	"source",
+	"note",
+	"lost_reason",
+	"locked",
+	"rank",
+	"archived_at",
+	"created_by",
+	"created_at",
+	"updated_at",
+	"list_total",
+	"discount_total",
+	"subtotal",
+	"tax_total",
+	"total",
+	"contacts",
+	"members"
+]);
+const num = (value) => typeof value === "number" ? value : void 0;
+/** Drops the `undefined` properties, which `exactOptionalPropertyTypes` refuses. */
+function compact(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
+function dealOf(value) {
+	const row = recordOf(value, "deal");
+	const companyType = optionalText(row["company_type"]);
+	const companyId = optionalText(row["company_id"]);
+	const forecast = optionalText(row["forecast_category"]);
+	return compact({
+		id: textOf(row["id"]),
+		organizationId: textOf(row["tenant_id"]),
+		number: bigintOf(row["number"], "deal number"),
+		identifier: textOf(row["identifier"]),
+		name: textOf(row["name"]),
+		company: companyType === void 0 || companyId === void 0 ? void 0 : {
+			type: companyType,
+			id: companyId
+		},
+		ownerId: optionalText(row["owner_user_id"]),
+		motion: optionalText(row["motion"]),
+		priority: optionalText(row["priority"]),
+		product: optionalText(row["product"]),
+		seats: num(row["seats"]),
+		amount: moneyOf(row["amount"], row["currency"], "deal amount"),
+		existingAmount: moneyOf(row["existing_amount"], row["currency"], "deal existingAmount"),
+		currency: textOf(row["currency"]),
+		valuePeriod: enumOrThrow(row["value_period"], [
+			"one_time",
+			"monthly",
+			"annual"
+		], "deal value period"),
+		amountSource: enumOrThrow(row["amount_source"], ["manual", "line_items"], "deal amount source"),
+		pipelineId: optionalText(row["pipeline_id"]),
+		stageId: optionalText(row["stage_id"]),
+		stageEnteredAt: optionalInstant(row["stage_entered_at"]),
+		outcome: enumOrThrow(row["outcome"], OUTCOMES, "deal outcome"),
+		probability: num(row["probability"]),
+		forecast: forecast === void 0 ? void 0 : enumOrThrow(forecast, FORECASTS, "deal forecast"),
+		openedOn: plainDate(row["opened_on"]) ?? temporal().PlainDate.from("1970-01-01"),
+		closeOn: plainDate(row["expected_close_on"]) ?? temporal().PlainDate.from("1970-01-01"),
+		slippedFrom: plainDate(row["slipped_from"]),
+		pushCount: num(row["push_count"]) ?? 0,
+		closedAt: optionalInstant(row["closed_at"]),
+		nextStep: optionalText(row["next_step"]),
+		nextAt: optionalInstant(row["next_at"]),
+		nextKind: optionalText(row["next_kind"]),
+		flags: Array.isArray(row["flags"]) ? row["flags"].map(String) : [],
+		source: optionalText(row["source"]),
+		note: optionalText(row["note"]),
+		lostReason: optionalText(row["lost_reason"]),
+		locked: row["locked"] === true,
+		rank: textOf(row["rank"]),
+		totals: totalsOf(row, false),
+		contacts: recordsOf(row["contacts"], "deal contacts").map((contact) => compact({
+			type: textOf(contact["type"]),
+			id: textOf(contact["id"]),
+			role: optionalText(contact["role"]),
+			primary: contact["primary"] === true
+		})),
+		members: recordsOf(row["members"], "deal members").map((member) => compact({
+			userId: textOf(member["userId"]),
+			role: optionalText(member["role"])
+		})),
+		fields: Object.fromEntries(Object.entries(row).filter(([key]) => !KNOWN.has(key))),
+		archived: row["archived_at"] !== null && row["archived_at"] !== void 0,
+		createdAt: requiredInstant(row["created_at"], "createdAt"),
+		updatedAt: requiredInstant(row["updated_at"], "updatedAt")
+	});
+}
+/**
+* A value as the database reads it: dates as ISO, bigints and the minor units
+* of a `Money` as text.
+*/
+function valueArg(value) {
+	if (typeof value === "bigint") return value.toString();
+	if (isMoney(value)) return amountText(value);
+	if (value instanceof temporal().Instant || value instanceof temporal().PlainDate) return value.toString();
+	return value;
+}
+function sums(row, currency) {
+	const at = (key) => moneyOf(row[key], currency, `deal_forecast ${key}`);
+	return {
+		won: at("won"),
+		commit: at("commit"),
+		bestCase: at("bestCase"),
+		pipeline: at("pipeline"),
+		notCalled: at("notCalled"),
+		omit: at("omit"),
+		later: at("later")
+	};
+}
+function forecastOf(value) {
+	const row = recordOf(value, "deal_forecast");
+	const currency = textOf(row["currency"]);
+	return compact({
+		currency,
+		...sums(row, currency),
+		target: optionalMoneyOf(row["target"], currency, "deal_forecast target"),
+		attainment: num(row["attainment"]),
+		gap: optionalMoneyOf(row["gap"], currency, "deal_forecast gap"),
+		owners: recordsOf(row["owners"], "deal_forecast owners").map((owner) => compact({
+			ownerId: optionalText(owner["ownerId"]),
+			...sums(owner, currency)
+		}))
+	});
+}
+/**
+* The deals block: deals on pipelines, with batched cell edits that reject
+* per change, won and lost through the pipeline's stages, contacts, a team,
+* line items, the forecast call and the review checks.
+*/
+function createDeals(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const fields = blockFields(options.fields, "deal fields");
+	const parsed = (deal) => AsyncResult.from(() => fields.read(deal.fields)).map((value) => ({
+		...deal,
+		fields: value
+	}));
+	return withBlockHooks({
+		create: (organizationId, input, contacts) => {
+			const { fields: extra, ...rest } = input;
+			const invalid = amountsError(input.currency, [input.amount, input.existingAmount]);
+			if (invalid !== void 0) return AsyncResult.err(invalid);
+			const currency = input.currency ?? input.amount?.currency ?? input.existingAmount?.currency;
+			return AsyncResult.from(() => fields.write({ ...extra })).andThen((valid) => call("create_deal", {
+				tenant: organizationId,
+				attrs: Object.fromEntries(Object.entries({
+					...rest,
+					...currency === void 0 ? {} : { currency },
+					...valid
+				}).map(([key, value]) => [key, valueArg(value)])),
+				contacts: contacts === void 0 ? null : contacts.map((contact) => ({ ...contact }))
+			}, dealOf)).andThen(parsed);
+		},
+		update: (changes) => AsyncResult.from(async () => {
+			for (const change of changes) {
+				if (change.field === "currency" && typeof change.value === "string" && !isCurrency(change.value)) return err(unknownCurrency(change.value));
+				if (BUILT_IN.has(change.field)) continue;
+				const valid = await fields.write({ [change.field]: change.value });
+				if (!valid.ok) return valid;
+			}
+			return ok(changes);
+		}).andThen((checked) => call("update_deals", { changes: checked.map((change) => ({
+			dealId: change.dealId,
+			field: change.field,
+			value: isMoney(change.value) ? {
+				amount: amountText(change.value),
+				currency: change.value.currency
+			} : valueArg(change.value)
+		})) }, (value) => {
+			const row = recordOf(value, "update_deals");
+			return {
+				accepted: recordsOf(row["accepted"], "accepted").map((item) => ({
+					dealId: textOf(item["dealId"]),
+					field: textOf(item["field"])
+				})),
+				rejected: recordsOf(row["rejected"], "rejected").map((item) => compact({
+					dealId: textOf(item["dealId"]),
+					field: textOf(item["field"]),
+					hint: optionalText(item["hint"]),
+					reason: textOf(item["reason"])
+				}))
+			};
+		})),
+		win: (dealId, note) => call("close_deal", {
+			deal: dealId,
+			outcome: "won",
+			reason: note ?? null
+		}, dealOf).andThen(parsed),
+		lose: (dealId, reason) => call("close_deal", {
+			deal: dealId,
+			outcome: "lost",
+			reason: reason ?? null
+		}, dealOf).andThen(parsed),
+		reopen: (dealId, stageId) => call("reopen_deal", {
+			deal: dealId,
+			stage: stageId ?? null
+		}, dealOf).andThen(parsed),
+		setContacts: (dealId, contacts) => call("set_deal_contacts", {
+			deal: dealId,
+			contacts: contacts.map((contact) => ({ ...contact }))
+		}, (value) => num(value) ?? 0),
+		setMembers: (dealId, members) => call("set_deal_members", {
+			deal: dealId,
+			members: members.map((member) => ({ ...member }))
+		}, (value) => num(value) ?? 0),
+		setLines: (dealId, lines) => {
+			const invalid = currencyMismatch(void 0, lines.map((line) => line.unitAmount));
+			return invalid === void 0 ? call("set_deal_lines", {
+				parent: dealId,
+				lines: lines.map(lineArg)
+			}, (value) => totalsOf(recordOf(value, "set_deal_lines"), true)) : AsyncResult.err(invalid);
+		},
+		archive: (dealId, archived = true) => call("archive_deal", {
+			deal: dealId,
+			archived
+		}, (value) => value === true),
+		remove: (dealId) => call("delete_deal", { deal: dealId }, (value) => value === true),
+		forecast: (organizationId, period) => {
+			const invalid = amountsError(period.currency, [period.target]);
+			return invalid === void 0 ? call("deal_forecast", {
+				tenant: organizationId,
+				pipeline: period.pipelineId ?? null,
+				since: period.since.toString(),
+				until: period.until.toString(),
+				currency: period.currency,
+				target: optionalAmountText(period.target),
+				owner: period.ownerId ?? null
+			}, forecastOf) : AsyncResult.err(invalid);
+		},
+		health: (pipelineId) => call("deal_health", { pipeline: pipelineId }, (value) => recordsOf(value, "deal_health").map((row) => ({
+			dealId: textOf(row["dealId"]),
+			identifier: textOf(row["identifier"]),
+			name: textOf(row["name"]),
+			daysInStage: num(row["daysInStage"]) ?? 0,
+			rotting: row["rotting"] === true,
+			slipped: row["slipped"] === true,
+			noNextStep: row["noNextStep"] === true,
+			overdue: row["overdue"] === true
+		})))
+	}, options.hooks, {
+		block: "deals",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+/**
+* The `config.subjects` entry for deals, so comments, tags, files, rank and
+* search attach to them. The board moves a deal by its stage id.
+*/
+function dealsSubjects(options = {}) {
+	return { deal: {
+		table: `${options.schema ?? "better_supabase"}.deals`,
+		idType: "uuid",
+		tenant: "tenant_id",
+		title: "name",
+		deletedAt: "archived_at",
+		permissions: {
+			read: "deals.read",
+			write: "deals.write"
+		},
+		rank: {
+			column: "rank",
+			group: "stage_id"
+		},
+		search: {
+			title: "name",
+			body: ["identifier", "note"]
+		},
+		...options.url === void 0 ? {} : { url: options.url }
+	} };
+}
+//#endregion
+//#region src/blocks/deals/events.ts
+/** The `deals` block's event types, for its manifest and `onBlockEvent`. */
+const dealsEvents = defineEvents({
+	"deal.created": event(),
+	"deal.updated": event(),
+	"deal.closed": event(),
+	"deal.reopened": event(),
+	"deal.archived": event(),
+	"deal.deleted": event()
+});
+//#endregion
+//#region src/blocks/deals/manifest.ts
+/** The `deals` block's manifest (ADR 0029). */
+const dealsBlock = defineBlock({
+	name: "deals",
+	sql: ["deals"],
+	options: { deals: dealsSqlOptions },
+	events: dealsEvents,
+	create: createDeals,
+	category: "crm",
+	recipes: ["deal-board"]
+});
+//#endregion
+export { createDeals, dbTransport, dealsBlock, dealsEvents, dealsSubjects, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };

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

@@ -0,0 +1,17 @@
+import { L as DocumentEventData, wt as Events } from "../../events-CTreRrgP.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { a as DocumentVersion, c as OpenedDocument, i as DocumentUpdate, l as createDocuments, n as DocumentRef, o as Documents, r as DocumentState, s as DocumentsOptions, t as DocumentInfo } from "../../documents-CWn2mtYf.js";
+//#region src/blocks/documents/events.d.ts
+/** The events of the `documents` block: type to data. */
+type DocumentsEvents = {
+  readonly "document.created": DocumentEventData;
+};
+/** The `documents` block's event types, for its manifest and `onBlockEvent`. */
+export declare const documentsEvents: Events<DocumentsEvents>;
+//#endregion
+//#region src/blocks/documents/manifest.d.ts
+/** The `documents` block's manifest (ADR 0029). */
+export declare const documentsBlock: BlockOf<"documents", typeof createDocuments, DocumentsEvents>;
+//#endregion
+export { type BlockTransport, type DocumentInfo, type DocumentRef, type DocumentState, type DocumentUpdate, type DocumentVersion, type Documents, type DocumentsEvents, type DocumentsOptions, type OpenedDocument, createDocuments, dbTransport, rpcTransport, sqlTransport };

package/dist/blocks/documents/index.js

@@ -0,0 +1,118 @@
+import { i as toBase64, r as fromBase64 } from "../../base64-BmeCBgGo.js";
+import { n as event, t as defineEvents } from "../../event-map-Dy2vKHai.js";
+import { i as sqlTransport, r as rpcTransport, t as dbTransport } from "../../block-transport-G4t1umrR.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, I as textOf, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "../../block-hooks-BsXncUlZ.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { t as documentsSqlOptions } from "../../options-C3hZ1fbC.js";
+//#region src/blocks/documents/documents.ts
+function seqOf(value, name) {
+	const seq = typeof value === "string" ? Number(value) : value;
+	if (typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0) throw new TypeError(`${name} must be a sequence number`);
+	return seq;
+}
+function stateOf(value, fn) {
+	const row = recordOf(value, fn);
+	const snapshot = optionalText(row["snapshot"]);
+	return {
+		snapshotSeq: seqOf(row["snapshotSeq"] ?? 0, "snapshotSeq"),
+		updates: recordsOf(row["updates"], fn).map((item) => ({
+			seq: seqOf(item["seq"], "seq"),
+			update: fromBase64(textOf(item["update"]))
+		})),
+		...snapshot === void 0 ? {} : { snapshot: fromBase64(snapshot) }
+	};
+}
+function openedOf(value) {
+	const row = recordOf(value, "open_document");
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organizationId"]),
+		subjectType: textOf(row["subjectType"]),
+		subjectId: textOf(row["subjectId"]),
+		name: textOf(row["name"]),
+		topic: textOf(row["topic"]),
+		canWrite: row["canWrite"] === true,
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: requiredInstant(row["updatedAt"], "updatedAt"),
+		...stateOf(row, "open_document")
+	};
+}
+function versionOf(value) {
+	const label = optionalText(value["label"]);
+	const createdBy = optionalText(value["createdBy"]);
+	return {
+		id: textOf(value["id"]),
+		number: seqOf(value["number"], "number"),
+		createdAt: requiredInstant(value["createdAt"], "createdAt"),
+		...label === void 0 ? {} : { label },
+		...createdBy === void 0 ? {} : { createdBy }
+	};
+}
+/** The `documents` SQL module as typed calls, with updates as bytes. */
+function createDocuments(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return withBlockHooks({
+		open: (ref) => call("open_document", {
+			tenant: ref.organizationId,
+			subject_type: ref.subjectType,
+			subject_id: ref.subjectId,
+			name: ref.name ?? "body"
+		}, openedOf),
+		push: (documentId, update) => call("push_document_update", {
+			document_id: documentId,
+			payload: toBase64(update)
+		}, (value) => seqOf(value, "push_document_update")),
+		pull: (documentId, afterSeq) => call("pull_document_updates", {
+			document_id: documentId,
+			after_seq: afterSeq
+		}, (value) => stateOf(value, "pull_document_updates")),
+		compact: (documentId, state, throughSeq) => call("compact_document", {
+			document_id: documentId,
+			state: toBase64(state),
+			through_seq: throughSeq
+		}, (value) => value === true),
+		saveVersion: (documentId, state, label) => call("save_document_version", {
+			document_id: documentId,
+			state: toBase64(state),
+			label: label ?? null
+		}, (value) => {
+			const row = recordOf(value, "save_document_version");
+			return {
+				id: textOf(row["id"]),
+				number: seqOf(row["number"], "number")
+			};
+		}),
+		versions: (documentId) => call("list_document_versions", { document_id: documentId }, (value) => recordsOf(value, "list_document_versions").map(versionOf)),
+		version: (documentId, versionId) => call("get_document_version", {
+			document_id: documentId,
+			version_id: versionId
+		}, (value) => fromBase64(textOf(value))),
+		toCompact: (list = {}) => call("documents_to_compact", {
+			...list.minUpdates === void 0 ? {} : { min_updates: list.minUpdates },
+			...list.limit === void 0 ? {} : { max_documents: list.limit }
+		}, (value) => (Array.isArray(value) ? value : []).map((id) => textOf(id)))
+	}, options.hooks, {
+		block: "documents",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/documents/events.ts
+/** The `documents` block's event types, for its manifest and `onBlockEvent`. */
+const documentsEvents = defineEvents({ "document.created": event() });
+//#endregion
+//#region src/blocks/documents/manifest.ts
+/** The `documents` block's manifest (ADR 0029). */
+const documentsBlock = defineBlock({
+	name: "documents",
+	sql: ["documents"],
+	options: { documents: documentsSqlOptions },
+	events: documentsEvents,
+	create: createDocuments,
+	category: "content",
+	recipes: ["document-editor"]
+});
+//#endregion
+export { createDocuments, dbTransport, documentsBlock, documentsEvents, rpcTransport, sqlTransport };

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

@@ -0,0 +1,117 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { wt as Events } from "../../events-CTreRrgP.js";
+import { n as Logger } from "../../logger-DWVYUmwi.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } 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 { s as BlockOf } from "../../define-block-CLZMEFeK.js";
+import { _ as dohResolver, m as TxtResolver, t as DohResolverOptions } from "../../sso-BN0LnMqE.js";
+//#region src/blocks/domains/domains.d.ts
+/** The DNS record that proves a custom domain belongs to the organization. */
+interface HostnameRecord {
+  readonly type: "TXT";
+  readonly name: string;
+  readonly value: string;
+}
+interface Hostname {
+  readonly id: string;
+  readonly organizationId: string;
+  /** Lowercase, without a trailing dot or a port. */
+  readonly hostname: string;
+  /** `subdomain` for one label below `blocks.domains.options.platformDomain`, verified when added. */
+  readonly kind: "custom" | "subdomain";
+  readonly verifiedAt: Temporal.Instant | undefined;
+  /** The hostname the organization's other hostnames redirect to. */
+  readonly primary: boolean;
+  readonly createdBy: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  /** For a hostname not verified yet: publish this TXT record, then verify it. */
+  readonly record: HostnameRecord | undefined;
+}
+/** The organization a request's hostname belongs to. */
+interface HostnameMatch {
+  readonly organizationId: string;
+  readonly hostname: string;
+  readonly primary: boolean;
+  /** The organization's primary hostname, to redirect to when this one isn't it. */
+  readonly primaryHostname: string | undefined;
+}
+interface DomainsOptions extends BlockTemporalOptions {
+  /** The caller's transport (`rpcTransport(supabase)`). */
+  readonly transport: BlockTransport;
+  /** The module schema, or its API schema: `defineBlocks` passes it from `blocks.generated.ts`. Default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** `withBlockHooks` hooks around the client's methods, such as a rule on which hostnames a plan may add. */
+  readonly hooks?: BlockHooks<Domains>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+interface Domains {
+  /** Adds a hostname (needs `domains.manage`); a custom domain comes back with its `record`. */
+  add(organizationId: string, hostname: string): AsyncResult<Hostname>;
+  /** The organization's hostnames, primary first (needs `domains.read`). */
+  list(organizationId: string): AsyncResult<readonly Hostname[]>;
+  /** Makes a verified hostname the primary one. */
+  setPrimary(hostnameId: string): AsyncResult<Hostname>;
+  /** `false` when the caller manages no hostname with this id. */
+  remove(hostnameId: string): AsyncResult<boolean>;
+  /**
+   * The organization that serves `host`, such as a request's `Host`
+   * header (the port is ignored). `undefined` unless it is verified.
+   * Works signed out, for the proxy.
+   */
+  resolve(host: string): AsyncResult<HostnameMatch | undefined>;
+}
+/**
+ * A `Host` header as a hostname: lowercase, without the port and the
+ * trailing dot. An IPv6 literal comes back in its brackets.
+ */
+export declare function normalizeHostname(host: string): string;
+/** An organization's hostnames as the caller, and the lookup for the proxy. */
+export declare function createDomains(options: DomainsOptions): Domains;
+interface DomainsAdminOptions extends BlockTemporalOptions {
+  /** A service-role transport: `verify_hostname` is granted to `service_role` only. */
+  readonly transport: BlockTransport;
+  /** TXT lookups for `verify`. Default `dohResolver()`. */
+  readonly resolver?: TxtResolver;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface DomainsAdmin {
+  /**
+   * Looks up the hostname's TXT record and marks it verified when the
+   * token is there. With `actorId`, the database checks that they hold
+   * `domains.manage`; omit it for app-owned calls.
+   */
+  verify(hostnameId: string, options?: {
+    readonly actorId?: string;
+    readonly signal?: AbortSignal;
+  }): AsyncResult<Hostname>;
+}
+/** Hostname verification with a service-role client. */
+export declare function createDomainsAdmin(options: DomainsAdminOptions): DomainsAdmin;
+//#endregion
+//#region src/blocks/domains/events.d.ts
+/** `hostname.*`: which organization's hostname changed. */
+interface HostnameEventData {
+  readonly organizationId: string;
+  readonly hostnameId: string;
+  readonly hostname: string;
+}
+/** The events of the `domains` block: type to data. */
+type DomainsEvents = {
+  readonly "hostname.added": HostnameEventData;
+  readonly "hostname.verified": HostnameEventData;
+  readonly "hostname.primary_set": HostnameEventData;
+  readonly "hostname.removed": HostnameEventData;
+};
+/** The `domains` block's event types, for its manifest and `onBlockEvent`. */
+export declare const domainsEvents: Events<DomainsEvents>;
+//#endregion
+//#region src/blocks/domains/manifest.d.ts
+/** The `domains` block's manifest (ADR 0029). */
+export declare const domainsBlock: BlockOf<"domains", typeof createDomains, DomainsEvents>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type DohResolverOptions, type Domains, type DomainsAdmin, type DomainsAdminOptions, type DomainsEvents, type DomainsOptions, type Hostname, type HostnameEventData, type HostnameMatch, type HostnameRecord, type RpcClient, type TxtResolver, dbTransport, dohResolver, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };