better-supabase 0.8.0 → 0.10.0

package/dist/blocks/drive/index.js

@@ -0,0 +1,483 @@
+import { n as dbError } from "../../errors-8i6tSICm.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-COkvI9t5.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { t as driveSqlOptions } from "../../options-DCduTMST.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, d as enumOrThrow, k as recordsOf, n as applyTemporal, o as blockCall } from "../../block-helpers-BfVCR5Fc.js";
+import { r as withBlockHooks } from "../../block-hooks-ByKlh8Qy.js";
+import { n as blockFields } from "../../block-fields-BANwJ9Y_.js";
+import { n as defineBlock } from "../../define-block-B6Gjs57G.js";
+import { a as stored, t as attachmentOf } from "../../attachments-C8FEBBKE.js";
+//#region src/blocks/drive/drive.ts
+const KINDS = ["folder", "file"];
+const PRINCIPALS = [
+	"user",
+	"team",
+	"role"
+];
+function fileOf(value) {
+	if (!isRecord(value)) return;
+	return {
+		mimeType: textOf(value["mimeType"]),
+		size: Number(value["size"]),
+		status: textOf(value["status"]),
+		uploadedAt: optionalInstant(value["uploadedAt"])
+	};
+}
+function nodeOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["organizationId"]),
+		parentId: optionalText(row["parentId"]) ?? null,
+		kind: enumOrThrow(row["kind"], KINDS, "drive node kind"),
+		name: textOf(row["name"]),
+		rank: optionalText(row["rank"]),
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		updatedAt: optionalInstant(row["updatedAt"]),
+		deletedAt: optionalInstant(row["deletedAt"]),
+		attachmentId: optionalText(row["attachmentId"]),
+		file: fileOf(row["file"]),
+		fields: isRecord(row["fields"]) ? row["fields"] : {},
+		role: optionalText(row["role"]),
+		starredAt: optionalInstant(row["starredAt"]),
+		openedAt: optionalInstant(row["openedAt"])
+	};
+}
+const nodesOf = (value, fn) => recordsOf(value, fn).map((row) => nodeOf(row, fn));
+function grantOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		id: textOf(row["id"]),
+		nodeId: textOf(row["nodeId"]),
+		principal: {
+			type: enumOrThrow(row["principalType"], PRINCIPALS, "principal type"),
+			id: textOf(row["principalId"])
+		},
+		role: textOf(row["role"]),
+		expiresAt: optionalInstant(row["expiresAt"]),
+		inherited: row["inherited"] === true
+	};
+}
+function batchOf(value, fn) {
+	const row = recordOf(value, fn);
+	return {
+		id: textOf(row["id"]),
+		batchId: textOf(row["batchId"]),
+		count: Number(row["count"])
+	};
+}
+function revisionOf(value) {
+	const row = recordOf(value, "drive_revisions");
+	return {
+		id: textOf(row["id"]),
+		number: Number(row["number"]),
+		label: optionalText(row["label"]),
+		source: textOf(row["source"]),
+		attachmentId: textOf(row["attachmentId"]),
+		name: textOf(row["name"]),
+		mimeType: textOf(row["mimeType"]),
+		size: Number(row["size"]),
+		current: row["current"] === true,
+		createdBy: optionalText(row["createdBy"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt")
+	};
+}
+function binEntryOf(value) {
+	const row = recordOf(value, "drive_bin");
+	return {
+		...batchOf(row, "drive_bin"),
+		node: nodeOf(row["node"], "drive_bin"),
+		trashedBy: optionalText(row["trashedBy"]),
+		trashedAt: requiredInstant(row["trashedAt"], "trashedAt"),
+		purgeAfter: optionalInstant(row["purgeAfter"])
+	};
+}
+function linkOf(value) {
+	const row = recordOf(value, "drive_link");
+	const link = recordOf(row["link"], "drive_link");
+	const object = isRecord(row["object"]) ? row["object"] : void 0;
+	return {
+		link: {
+			id: textOf(link["id"]),
+			role: textOf(link["role"]),
+			nodeId: textOf(link["nodeId"]),
+			expiresAt: optionalInstant(link["expiresAt"])
+		},
+		node: nodeOf(row["node"], "drive_link"),
+		children: Array.isArray(row["children"]) ? nodesOf(row["children"], "drive_link") : void 0,
+		object: object === void 0 ? void 0 : {
+			bucket: textOf(object["bucket"]),
+			path: textOf(object["path"]),
+			mimeType: textOf(object["mimeType"]),
+			status: textOf(object["status"])
+		}
+	};
+}
+function objectsOf(value) {
+	return recordsOf(value, "drive_prune").map((row) => ({
+		bucket: textOf(row["bucket"]),
+		path: textOf(row["path"])
+	}));
+}
+const noAttachments = () => dbError("invalid_request", "createDrive needs the attachments block to download files", { hint: "DRIVE_ATTACHMENTS_CLIENT" });
+const noStorage = () => dbError("invalid_request", "createDrive needs storage for files", { hint: "DRIVE_STORAGE_CLIENT" });
+/** The methods whose result holds nodes, which `fields` parses. */
+const NODE_METHODS = [
+	"createFolder",
+	"get",
+	"list",
+	"shared",
+	"rename",
+	"move",
+	"upload",
+	"uploadRevision",
+	"commit",
+	"restoreRevision",
+	"restore",
+	"bin",
+	"open",
+	"starred",
+	"recent",
+	"link"
+];
+const isNode = (value) => typeof value["kind"] === "string" && typeof value["organizationId"] === "string";
+/** `value` with the `fields` of every node in it parsed: a node, a list, or `{ node, children }`. */
+async function parseNodes(fields, value) {
+	if (Array.isArray(value)) {
+		const out = [];
+		for (const item of value) {
+			const parsed = await parseNodes(fields, item);
+			if (!parsed.ok) return parsed;
+			out.push(parsed.data);
+		}
+		return ok(out);
+	}
+	if (!isRecord(value)) return ok(value);
+	const extra = value["fields"];
+	if (isNode(value) && isRecord(extra)) {
+		const parsed = await fields.read({ ...extra });
+		return parsed.ok ? ok({
+			...value,
+			fields: parsed.data
+		}) : parsed;
+	}
+	const out = { ...value };
+	for (const key of ["node", "children"]) {
+		if (value[key] === void 0) continue;
+		const parsed = await parseNodes(fields, value[key]);
+		if (!parsed.ok) return parsed;
+		out[key] = parsed.data;
+	}
+	return ok(out);
+}
+/**
+* The client with `fields` applied: the extra fields of a new folder or
+* file are validated first, and every node it returns is parsed.
+*/
+function withFields(client, fields) {
+	const out = { ...client };
+	for (const method of NODE_METHODS) {
+		const original = client[method];
+		const wrapped = (...args) => {
+			const input = args[1];
+			const extra = (method === "createFolder" || method === "upload") && isRecord(input) ? input["fields"] : void 0;
+			return (isRecord(extra) ? AsyncResult.from(() => fields.write({ ...extra })).map(() => true) : AsyncResult.ok(true)).andThen(() => original.apply(client, args)).andThen((value) => parseNodes(fields, value));
+		};
+		Object.defineProperty(out, method, {
+			value: wrapped,
+			enumerable: true,
+			configurable: true,
+			writable: true
+		});
+	}
+	return out;
+}
+/** The `drive` SQL module as typed calls, as the caller. */
+function createDrive(options) {
+	applyTemporal(options);
+	const fields = blockFields(options.fields, "drive node fields");
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const storage = options.storage;
+	const attachments = options.attachments;
+	const signed = (fn) => (value) => {
+		const row = recordOf(value, fn);
+		return {
+			node: nodeOf(row["node"], fn),
+			attachment: attachmentOf(row["attachment"])
+		};
+	};
+	const withUploadUrl = (pending) => {
+		if (storage === void 0) return AsyncResult.err(noStorage());
+		return pending().andThen(({ node, attachment }) => stored(storage.from(attachment.bucket).createSignedUploadUrl(attachment.path)).map((url) => ({
+			node,
+			attachment,
+			signedUrl: url.signedUrl,
+			token: url.token
+		})));
+	};
+	const page = (fn, args) => call(fn, args, (value) => nodesOf(value, fn));
+	const client = {
+		createFolder: (organizationId, folder) => call("drive_create_folder", {
+			tenant: organizationId,
+			parent: folder.parentId ?? null,
+			name: folder.name,
+			conflict: folder.conflict ?? null,
+			fields: folder.fields ?? null
+		}, (value) => nodeOf(value, "drive_create_folder")),
+		get: (id) => call("drive_get", { node: id }, (value) => nodeOf(value, "drive_get")),
+		list: (organizationId, list = {}) => page("drive_list", {
+			tenant: organizationId,
+			parent: list.parentId ?? null,
+			page_size: list.pageSize ?? null,
+			skip: list.skip ?? null
+		}),
+		shared: (organizationId, list = {}) => page("drive_shared", {
+			tenant: organizationId,
+			page_size: list.pageSize ?? null
+		}),
+		path: (id) => call("drive_path", { node: id }, (value) => recordsOf(value, "drive_path").map((row) => ({
+			id: textOf(row["id"]),
+			name: textOf(row["name"]),
+			kind: enumOrThrow(row["kind"], KINDS, "drive node kind")
+		}))),
+		rename: (id, name, rename = {}) => call("drive_rename", {
+			node: id,
+			name,
+			conflict: rename.conflict ?? null
+		}, (value) => nodeOf(value, "drive_rename")),
+		move: (id, parentId, move = {}) => call("drive_move", {
+			node: id,
+			parent: parentId,
+			rank: move.rank ?? null,
+			conflict: move.conflict ?? null
+		}, (value) => nodeOf(value, "drive_move")),
+		delete: (id) => call("drive_delete", { node: id }, (value) => value === true),
+		share: (id, principal, role, share = {}) => call("drive_share", {
+			node: id,
+			principal_type: principal.type,
+			principal_id: principal.id,
+			role,
+			expires_at: share.expiresAt?.toString() ?? null
+		}, (value) => grantOf(value, "drive_share")),
+		unshare: (id, principal) => call("drive_unshare", {
+			node: id,
+			principal_type: principal.type,
+			principal_id: principal.id
+		}, (value) => value === true),
+		grants: (id) => call("drive_grants", { node: id }, (value) => recordsOf(value, "drive_grants").map((row) => grantOf(row, "drive_grants"))),
+		upload: (organizationId, file) => withUploadUrl(() => call("drive_create_file", {
+			tenant: organizationId,
+			parent: file.parentId ?? null,
+			name: file.name,
+			mime_type: file.mimeType,
+			size: file.size,
+			conflict: file.conflict ?? null,
+			fields: file.fields ?? null
+		}, signed("drive_create_file"))),
+		uploadRevision: (id, file) => withUploadUrl(() => call("drive_upload_revision", {
+			node: id,
+			mime_type: file.mimeType,
+			size: file.size
+		}, signed("drive_upload_revision"))),
+		commit: (id, attachmentId) => call("drive_commit", {
+			node: id,
+			attachment: attachmentId
+		}, (value) => nodeOf(value, "drive_commit")),
+		download: (id, download = {}) => {
+			if (attachments === void 0) return AsyncResult.err(noAttachments());
+			return client.get(id).andThen((node) => node.attachmentId === void 0 ? Promise.resolve(err(dbError("invalid_request", "This item has no content", { hint: "DRIVE_NOT_A_FILE" }))) : attachments.download(node.attachmentId, download));
+		},
+		revisions: (id) => call("drive_revisions", { node: id }, (value) => recordsOf(value, "drive_revisions").map(revisionOf)),
+		restoreRevision: (id, revisionId) => call("drive_restore_revision", {
+			node: id,
+			version: revisionId
+		}, (value) => nodeOf(value, "drive_restore_revision")),
+		trash: (id) => call("drive_trash", { node: id }, (value) => batchOf(value, "drive_trash")),
+		restore: (binId, restore = {}) => call("drive_restore", {
+			item: binId,
+			conflict: restore.conflict ?? null
+		}, (value) => ({
+			...batchOf(value, "drive_restore"),
+			node: nodeOf(recordOf(value, "drive_restore")["node"], "drive_restore")
+		})),
+		bin: (organizationId, list = {}) => call("drive_bin", {
+			tenant: organizationId,
+			page_size: list.pageSize ?? null,
+			before: list.before?.toString() ?? null
+		}, (value) => recordsOf(value, "drive_bin").map(binEntryOf)),
+		purge: (binId) => call("drive_purge", { item: binId }, Number),
+		star: (id, starred = true) => call("drive_star", {
+			node: id,
+			starred
+		}, (value) => value === true),
+		open: (id) => call("drive_open", { node: id }, (value) => nodeOf(value, "drive_open")),
+		starred: (organizationId, list = {}) => page("drive_marked", {
+			tenant: organizationId,
+			recent: false,
+			page_size: list.pageSize ?? null
+		}),
+		recent: (organizationId, list = {}) => page("drive_marked", {
+			tenant: organizationId,
+			recent: true,
+			page_size: list.pageSize ?? null
+		}),
+		link: (token, link = {}) => call("drive_link", {
+			token,
+			node: link.nodeId ?? null
+		}, linkOf),
+		prune: (prune = {}) => call("drive_prune", { max_objects: prune.maxObjects ?? null }, objectsOf).andThen(async (objects) => {
+			if (storage === void 0 || objects.length === 0) return ok(objects);
+			const buckets = Map.groupBy(objects, (object) => object.bucket);
+			for (const [bucket, inBucket] of buckets) {
+				const removed = await stored(storage.from(bucket).remove(inBucket.map((object) => object.path)));
+				if (!removed.ok) return removed;
+			}
+			return ok(objects);
+		})
+	};
+	return withBlockHooks(withFields(client, fields), options.hooks, {
+		block: "drive",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+/**
+* The `subjects.drive_node` entry for the managed tables, so comments,
+* attachments, versions, trash and search can name drive nodes. The
+* permissions are the tenant-wide floor; grants decide per node.
+*/
+function driveSubject(options = {}) {
+	return {
+		table: `${options.schema ?? "better_supabase"}.drive_nodes`,
+		idType: "uuid",
+		tenant: "tenant_id",
+		title: "name",
+		deletedAt: "deleted_at",
+		permissions: {
+			read: "drive.read",
+			write: "drive.manage"
+		},
+		search: { title: "name" }
+	};
+}
+//#endregion
+//#region src/blocks/drive/tree.ts
+const BY_EXTENSION = {
+	pdf: "pdf",
+	doc: "document",
+	docx: "document",
+	odt: "document",
+	rtf: "document",
+	pages: "document",
+	xls: "spreadsheet",
+	xlsx: "spreadsheet",
+	ods: "spreadsheet",
+	csv: "spreadsheet",
+	numbers: "spreadsheet",
+	ppt: "presentation",
+	pptx: "presentation",
+	odp: "presentation",
+	key: "presentation",
+	zip: "archive",
+	gz: "archive",
+	tar: "archive",
+	tgz: "archive",
+	rar: "archive",
+	"7z": "archive",
+	js: "code",
+	jsx: "code",
+	ts: "code",
+	tsx: "code",
+	json: "code",
+	sql: "code",
+	py: "code",
+	rb: "code",
+	go: "code",
+	rs: "code",
+	java: "code",
+	html: "code",
+	css: "code",
+	yaml: "code",
+	yml: "code",
+	sh: "code",
+	txt: "text",
+	md: "text",
+	log: "text"
+};
+const BY_MIME = [
+	[/^image\//, "image"],
+	[/^video\//, "video"],
+	[/^audio\//, "audio"],
+	[/^application\/pdf$/, "pdf"],
+	[/(spreadsheet|excel|csv)/, "spreadsheet"],
+	[/(presentation|powerpoint)/, "presentation"],
+	[/(wordprocessing|msword|opendocument\.text|rtf)/, "document"],
+	[/(zip|gzip|x-tar|x-7z|x-rar|compressed)/, "archive"],
+	[/(javascript|typescript|json|xml|x-sh|sql|yaml)/, "code"],
+	[/^text\//, "text"]
+];
+/**
+* A category for an icon or a filter, from the MIME type and then the
+* extension. Folders are `folder`; anything unknown is `other`.
+*/
+function fileTypeCategory(mimeType, name = "") {
+	const mime = (mimeType ?? "").toLowerCase().split(";")[0]?.trim() ?? "";
+	if (mime === "inode/directory") return "folder";
+	const extension = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
+	const known = extension === void 0 ? void 0 : BY_EXTENSION[extension];
+	if (mime === "" || mime === "application/octet-stream") return known ?? "other";
+	for (const [pattern, type] of BY_MIME) if (pattern.test(mime)) return type === "text" && known !== void 0 ? known : type;
+	return known ?? "other";
+}
+/** The category of a node: `folder`, or its file's type. */
+function nodeType(node) {
+	return node.kind === "folder" ? "folder" : fileTypeCategory(node.file?.mimeType, node.name);
+}
+/** The root of a `driveTree`: the drive's top level. */
+const DRIVE_ROOT = "root";
+function driveTree(nodes, rootId = null) {
+	const byId = new Map(nodes.map((node) => [node.id, node]));
+	const children = /* @__PURE__ */ new Map();
+	const root = rootId ?? "root";
+	for (const node of nodes) {
+		const parent = node.parentId ?? "root";
+		const list = children.get(parent);
+		if (list === void 0) children.set(parent, [node.id]);
+		else list.push(node.id);
+	}
+	return {
+		rootItemId: root,
+		getItem: (id) => byId.get(id),
+		getChildren: (id) => [...children.get(id) ?? []],
+		isFolder: (id) => id === root || byId.get(id)?.kind === "folder",
+		name: (id) => byId.get(id)?.name ?? ""
+	};
+}
+//#endregion
+//#region src/blocks/drive/events.ts
+/** The `drive` block's event types, for its manifest and `onBlockEvent`. */
+const driveEvents = defineEvents({
+	"drive.node_created": event(),
+	"drive.node_renamed": event(),
+	"drive.node_moved": event(),
+	"drive.node_shared": event(),
+	"drive.node_unshared": event(),
+	"drive.node_purged": event()
+});
+//#endregion
+//#region src/blocks/drive/manifest.ts
+/** The `drive` block's manifest (ADR 0029). */
+const driveBlock = defineBlock({
+	name: "drive",
+	sql: ["drive", "drive-files"],
+	options: { drive: driveSqlOptions },
+	events: driveEvents,
+	consumes: { attachments: "optional" },
+	create: createDrive,
+	category: "content",
+	recipes: ["grants-editor", "drive-explorer"]
+});
+//#endregion
+export { DRIVE_ROOT, createDrive, dbTransport, driveBlock, driveEvents, driveSubject, driveTree, fileTypeCategory, nodeType, rpcTransport, sqlTransport };

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

@@ -0,0 +1,205 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-Cj3yWhjH.js";
+import { wt as Events } from "../../events-CtAHxPal.js";
+import { g as EmployeeEventData } from "../../index-DL8z_oDo.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-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-7pMBVsE6.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-C_WaodoA.js";
+import { r as FieldsOf } from "../../block-fields-5UA84ZUg.js";
+import { s as BlockOf } from "../../define-block-BlHQxDIQ.js";
+import { t as SubjectConfig } from "../../subjects-DP-fvFkk.js";
+import { n as Money } from "../../money-DFpWzQvk.js";
+import { t as RecordRef } from "../../sales-shared-DAAGwQwN.js";
+//#region src/blocks/employees/employees.d.ts
+type EmployeeStatus = "preboarding" | "active" | "on_leave" | "offboarded";
+type SalaryPeriod = "hour" | "week" | "month" | "year";
+/** An employee. `F` types the extra columns the `fields` schema describes. */
+interface Employee<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly name: string;
+  readonly email?: string;
+  /** The account, when the employee has one; contractors and interns often don't. */
+  readonly userId?: string;
+  readonly jobTitle?: string;
+  readonly teamId?: string;
+  readonly managerId?: string;
+  readonly employmentType?: string;
+  readonly status: EmployeeStatus;
+  readonly startDate?: Temporal.PlainDate;
+  readonly endDate?: Temporal.PlainDate;
+  readonly offboardReason?: string;
+  /** The record it was made from, such as `{ type: "application", id }`. */
+  readonly origin?: RecordRef;
+  readonly createdAt?: Temporal.Instant;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: Readonly<Record<string, unknown>> & F;
+}
+/** An employee in the org chart or a manager's reports. */
+interface OrgChartEntry<F extends object = Record<never, never>> extends Employee<F> {
+  /** 0 for a root of the chart, 1 for a direct report. */
+  readonly depth: number;
+  readonly directReports: number;
+}
+interface EmployeeInput<F extends object = Record<never, never>> {
+  readonly name: string;
+  readonly email?: string;
+  readonly userId?: string;
+  readonly jobTitle?: string;
+  readonly teamId?: string;
+  readonly managerId?: string;
+  /** One of `options.employmentTypes`; the first one by default. */
+  readonly employmentType?: string;
+  /** Preboarding before the start date and active from it, by default. */
+  readonly status?: Exclude<EmployeeStatus, "offboarded">;
+  readonly startDate?: Temporal.PlainDate;
+  readonly endDate?: Temporal.PlainDate;
+  /** With an origin, creating again returns the same employee. */
+  readonly origin?: RecordRef;
+  readonly fields?: Partial<F> & Readonly<Record<string, unknown>>;
+}
+type EmployeeField = "name" | "email" | "userId" | "jobTitle" | "teamId" | "managerId" | "employmentType" | "status" | "startDate" | "endDate";
+/** One cell edit: a field above, or an extra column by name. `null` clears it. */
+interface EmployeeChange {
+  readonly employeeId: string;
+  readonly field: EmployeeField | (string & {});
+  readonly value: unknown;
+}
+interface EmployeeChangeResult {
+  readonly accepted: readonly {
+    readonly employeeId: string;
+    readonly field: string;
+  }[];
+  /** Each refused change, with the error hint and message. Others still applied. */
+  readonly rejected: readonly {
+    readonly employeeId: string;
+    readonly field: string;
+    readonly hint?: string;
+    readonly reason: string;
+  }[];
+}
+interface EmergencyContact {
+  readonly name: string;
+  readonly phone?: string;
+  readonly relation?: string;
+}
+interface PrivateDetails {
+  readonly employeeId: string;
+  readonly nationalId?: string;
+  readonly iban?: string;
+  readonly birthDate?: Temporal.PlainDate;
+  readonly personalEmail?: string;
+  readonly phone?: string;
+  readonly address?: Readonly<Record<string, unknown>>;
+  readonly emergencyContacts: readonly EmergencyContact[];
+  /** Set on offboarding, so an anonymize rule can start from it. */
+  readonly offboardedAt?: Temporal.Instant;
+  readonly anonymizedAt?: Temporal.Instant;
+}
+/** The details to save. Left out keeps the stored value; `null` clears it. */
+interface PrivateDetailsInput {
+  readonly nationalId?: string | null;
+  readonly iban?: string | null;
+  readonly birthDate?: Temporal.PlainDate | null;
+  readonly personalEmail?: string | null;
+  readonly phone?: string | null;
+  readonly address?: Readonly<Record<string, unknown>> | null;
+  readonly emergencyContacts?: readonly EmergencyContact[] | null;
+}
+/** A contract. */
+interface Contract {
+  readonly id: string;
+  readonly employeeId: string;
+  readonly startsOn: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+  readonly hoursPerWeek?: number;
+  readonly salary?: Money;
+  readonly salaryPeriod?: SalaryPeriod;
+  readonly note?: string;
+}
+interface ContractInput {
+  readonly startsOn: Temporal.PlainDate;
+  readonly endsOn?: Temporal.PlainDate;
+  readonly hoursPerWeek?: number;
+  readonly salary?: Money;
+  readonly salaryPeriod?: SalaryPeriod;
+  readonly note?: string;
+}
+interface Employees<F extends object = Record<never, never>> {
+  create(organizationId: string, input: EmployeeInput<F>): AsyncResult<Employee<F>>;
+  /** Applies each change on its own; one that fails doesn't stop the others. */
+  update(changes: readonly EmployeeChange[]): AsyncResult<EmployeeChangeResult>;
+  /** Sets the end date (today by default) and moves the reports to the employee's manager. */
+  offboard(employeeId: string, options?: {
+    readonly endDate?: Temporal.PlainDate;
+    readonly reason?: string;
+  }): AsyncResult<Employee<F>>;
+  /** The chart under `rootId`, or under everyone without a manager. */
+  orgChart(organizationId: string, rootId?: string): AsyncResult<readonly OrgChartEntry<F>[]>;
+  /** Direct reports, or everyone under the manager with `indirect`. */
+  reportsOf(managerId: string, options?: {
+    readonly indirect?: boolean;
+  }): AsyncResult<readonly OrgChartEntry<F>[]>;
+  /**
+   * The employee for a hired application (the hiring module), in
+   * preboarding, made once. `overrides` replaces what the candidate and
+   * the job give.
+   */
+  fromApplication(applicationId: string, overrides?: Partial<EmployeeInput<F>>): AsyncResult<Employee<F>>;
+  /** Needs employees.view_sensitive, or being the employee. */
+  privateDetails(employeeId: string): AsyncResult<PrivateDetails | undefined>;
+  savePrivateDetails(employeeId: string, input: PrivateDetailsInput): AsyncResult<PrivateDetails>;
+  /** The newest first. */
+  contracts(employeeId: string): AsyncResult<readonly Contract[]>;
+  /** Starts after the latest contract, which ends the day before. */
+  addContract(employeeId: string, input: ContractInput): AsyncResult<Contract>;
+}
+interface EmployeesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the extra columns
+   * (`blocks.employees.options.extraColumns`), keyed by column name.
+   * It types and parses `fields` on reads and validates them on writes.
+   */
+  readonly fields?: S;
+  readonly hooks?: NoInfer<BlockHooks<Employees<FieldsOf<S>>>>;
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * The employees block: the people an organization employs, their manager,
+ * team and status, the org chart, offboarding, and private details and
+ * contracts behind employees.view_sensitive.
+ */
+export declare function createEmployees<S extends StandardSchemaV1 | undefined = undefined>(options: EmployeesOptions<S>): Employees<FieldsOf<S>>;
+/**
+ * The `config.subjects` entry for employees, so comments, files, tags and
+ * search attach to them. Pass `schema` when the module isn't in
+ * `better_supabase`.
+ */
+export declare function employeesSubjects(options?: {
+  readonly schema?: string;
+  readonly url?: string;
+}): {
+  readonly employee: SubjectConfig;
+};
+//#endregion
+//#region src/blocks/employees/events.d.ts
+/** The events of the `employees` block: type to data. */
+type EmployeesEvents = {
+  readonly "employee.created": EmployeeEventData;
+  readonly "employee.updated": EmployeeEventData;
+  readonly "employee.offboarded": EmployeeEventData;
+  readonly "employee.manager_changed": EmployeeEventData;
+};
+/** The `employees` block's event types, for its manifest and `onBlockEvent`. */
+export declare const employeesEvents: Events<EmployeesEvents>;
+//#endregion
+//#region src/blocks/employees/manifest.d.ts
+/** The `employees` block's manifest (ADR 0029). */
+export declare const employeesBlock: BlockOf<"employees", typeof createEmployees, EmployeesEvents>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type Contract, type ContractInput, type EmergencyContact, type Employee, type EmployeeChange, type EmployeeChangeResult, type EmployeeField, type EmployeeInput, type EmployeeStatus, type Employees, type EmployeesEvents, type EmployeesOptions, type OrgChartEntry, type PrivateDetails, type PrivateDetailsInput, type RpcClient, type SalaryPeriod, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };