better-supabase 0.7.1 → 0.9.0

package/dist/client-pxjbgOz6.js

@@ -0,0 +1,376 @@
+import { t as defineController } from "./controller-D6NyNrlZ.js";
+//#region src/blocks/forms/validate.ts
+/**
+* `email` as the HTML `<input type="email">` grammar, `date` as RFC 3339
+* `full-date`. Postgres asserts the same formats, so a value this accepts
+* can still fail there only for a mailbox the HTML grammar allows and
+* pg_jsonschema does not.
+*/
+const EMAIL = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const URI_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function schemaOf(value) {
+	return isObject(value) ? value : {};
+}
+function typeMatches(type, value) {
+	switch (type) {
+		case "string": return typeof value === "string";
+		case "number": return typeof value === "number" && Number.isFinite(value);
+		case "integer": return typeof value === "number" && Number.isInteger(value);
+		case "boolean": return typeof value === "boolean";
+		case "array": return Array.isArray(value);
+		case "object": return isObject(value);
+		case "null": return value === null;
+		default: return true;
+	}
+}
+function equal(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, i) => equal(item, b[i]));
+	if (isObject(a) && isObject(b)) {
+		const keys = Object.keys(a);
+		return keys.length === Object.keys(b).length && keys.every((key) => key in b && equal(a[key], b[key]));
+	}
+	return false;
+}
+function validDate(value) {
+	const match = DATE.exec(value);
+	if (match === null) return false;
+	const [year, month, day] = [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	];
+	const last = new Date(Date.UTC(year, month, 0)).getUTCDate();
+	return month >= 1 && month <= 12 && day >= 1 && day <= last;
+}
+function formatMatches(format, value) {
+	switch (format) {
+		case "email": return EMAIL.test(value);
+		case "date": return validDate(value);
+		case "uri": return URI_SCHEME.test(value) && URL.canParse(value);
+		default: return true;
+	}
+}
+const SURROGATE_PAIR = /[\uD800-\uDBFF][\uDC00-\uDFFF]/g;
+/** Code points, as JSON Schema counts string length. */
+const lengthOf = (value) => value.length - (value.match(SURROGATE_PAIR)?.length ?? 0);
+const items = (count) => count === 1 ? "1 item" : `${count} items`;
+function check(schema, value, path, issues) {
+	const at = (message) => issues.push({
+		message,
+		path
+	});
+	if ("type" in schema && !typeMatches(schema["type"], value)) {
+		at(`must be ${String(schema["type"])}`);
+		return;
+	}
+	if ("const" in schema && !equal(schema["const"], value)) at(`must be ${JSON.stringify(schema["const"])}`);
+	const allowed = schema["enum"];
+	if (Array.isArray(allowed) && !allowed.some((item) => equal(item, value))) at("must be one of the options");
+	if ("not" in schema) {
+		const inner = [];
+		check(schemaOf(schema["not"]), value, path, inner);
+		if (inner.length === 0) at("is required");
+	}
+	if (typeof value === "string") {
+		const { minLength, maxLength, pattern, format } = schema;
+		if (typeof minLength === "number" && lengthOf(value) < minLength) at(minLength === 1 ? "is required" : `must be at least ${minLength} characters`);
+		if (typeof maxLength === "number" && lengthOf(value) > maxLength) at(`must be at most ${maxLength} characters`);
+		if (typeof pattern === "string" && !new RegExp(pattern, "u").test(value)) at("has the wrong format");
+		if (format !== void 0 && !formatMatches(format, value)) at(`must be a valid ${String(format)}`);
+	}
+	if (typeof value === "number") {
+		const { minimum, maximum } = schema;
+		if (typeof minimum === "number" && value < minimum) at(`must be at least ${minimum}`);
+		if (typeof maximum === "number" && value > maximum) at(`must be at most ${maximum}`);
+	}
+	if (Array.isArray(value)) {
+		const { minItems, maxItems, uniqueItems } = schema;
+		const each = schema["items"];
+		if (typeof minItems === "number" && value.length < minItems) at(`must have at least ${items(minItems)}`);
+		if (typeof maxItems === "number" && value.length > maxItems) at(`must have at most ${items(maxItems)}`);
+		if (uniqueItems === true && value.some((item, i) => value.findIndex((other) => equal(item, other)) !== i)) at("must not repeat an item");
+		if (each !== void 0) value.forEach((item, i) => {
+			check(schemaOf(each), item, [...path, i], issues);
+		});
+	}
+	if (isObject(value)) {
+		const properties = schemaOf(schema["properties"]);
+		const required = schema["required"];
+		if (Array.isArray(required)) {
+			for (const key of required) if (typeof key === "string" && !(key in value)) issues.push({
+				message: "is required",
+				path: [...path, key]
+			});
+		}
+		for (const [key, item] of Object.entries(value)) if (key in properties) check(schemaOf(properties[key]), item, [...path, key], issues);
+		else if (schema["additionalProperties"] === false) issues.push({
+			message: "is not a field of this form",
+			path: [...path, key]
+		});
+	}
+	const all = schema["allOf"];
+	if (Array.isArray(all)) for (const part of all) check(schemaOf(part), value, path, issues);
+	if ("if" in schema) {
+		const condition = [];
+		check(schemaOf(schema["if"]), value, path, condition);
+		if (condition.length === 0 && "then" in schema) check(schemaOf(schema["then"]), value, path, issues);
+	}
+}
+/**
+* Checks answers against a form version's schema with the keywords the
+* generator emits, so a form can show errors before it submits. Postgres
+* checks the same schema again on submit; this is not a general JSON
+* Schema validator.
+*/
+function validateAnswers(schema, answers) {
+	const issues = [];
+	check(schema, answers, [], issues);
+	return issues;
+}
+/** A form version's schema as a Standard Schema, for form libraries. */
+function answersSchema(schema) {
+	return { "~standard": {
+		version: 1,
+		vendor: "better-supabase",
+		validate: (value) => {
+			const issues = validateAnswers(schema, value);
+			return issues.length === 0 ? { value } : { issues };
+		}
+	} };
+}
+//#endregion
+//#region src/blocks/forms/questionnaire.ts
+function same(a, b) {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+const EMPTY = /* @__PURE__ */ new Set([null, ""]);
+/** Whether `condition` holds for `answers`, with the semantics of its JSON Schema `if`. */
+function conditionHolds(condition, answers) {
+	if (condition === void 0) return true;
+	if (!(condition.field in answers)) return false;
+	const value = answers[condition.field];
+	if ("equals" in condition) return same(value, condition.equals);
+	if ("in" in condition) return condition.in.some((item) => same(value, item));
+	return !(value === void 0 || EMPTY.has(value) || Array.isArray(value) && value.length === 0);
+}
+/** The steps whose `showIf` holds. */
+function visibleSteps(definition, answers) {
+	return definition.steps.filter((step) => conditionHolds(step.showIf, answers));
+}
+/** The step's fields whose `showIf` holds. */
+function visibleFields(step, answers) {
+	return step.fields.filter((field) => conditionHolds(field.showIf, answers));
+}
+function visibleKeys(definition, answers) {
+	return new Set(visibleSteps(definition, answers).flatMap((step) => visibleFields(step, answers).map((field) => field.key)));
+}
+/**
+* The answers without the ones for hidden steps and fields. Removing an
+* answer can hide a later field, so it repeats until nothing changes.
+*/
+function pruneAnswers(definition, answers) {
+	const keep = visibleKeys(definition, answers);
+	const next = Object.fromEntries(Object.entries(answers).filter(([key]) => keep.has(key)));
+	return Object.keys(next).length === Object.keys(answers).length ? next : pruneAnswers(definition, next);
+}
+/** The schema's issues for the fields `step` shows. */
+function stepIssues(schema, step, answers) {
+	const keys = new Set(visibleFields(step, answers).map((field) => field.key));
+	return validateAnswers(schema, answers).filter((issue) => {
+		const key = issue.path?.[0];
+		return typeof key === "string" && keys.has(key);
+	});
+}
+/** The state before the first answer. */
+function initialQuestionnaire(form, answers = {}) {
+	return {
+		step: (visibleSteps(form.definition, answers)[0] ?? form.definition.steps[0])?.key ?? "",
+		answers,
+		completed: [],
+		issues: []
+	};
+}
+/** The step on screen, or the nearest visible one before it when an answer hid it. */
+function stepAfterAnswer(form, step, answers) {
+	const visible = new Set(visibleSteps(form.definition, answers).map((item) => item.key));
+	if (visible.has(step)) return step;
+	const order = form.definition.steps.map((item) => item.key);
+	return order.slice(0, Math.max(order.indexOf(step), 0)).toReversed().find((key) => visible.has(key)) ?? order.find((key) => visible.has(key)) ?? step;
+}
+/**
+* The questionnaire as a reducer: answers, the current step and the steps
+* done. `next` checks the step's fields against the version's schema and
+* stays put with `issues` when one fails; hidden steps are skipped.
+*/
+function questionnaireReducer(form, state, action) {
+	const steps = visibleSteps(form.definition, state.answers);
+	const index = steps.findIndex((step) => step.key === state.step);
+	switch (action.type) {
+		case "answer": {
+			const answers = { ...state.answers };
+			if (action.value === void 0) delete answers[action.key];
+			else answers[action.key] = action.value;
+			const issues = state.issues.filter((issue) => issue.path?.[0] !== action.key);
+			return {
+				...state,
+				step: stepAfterAnswer(form, state.step, answers),
+				answers,
+				issues
+			};
+		}
+		case "next": {
+			const current = steps[index];
+			if (current === void 0) return state;
+			const issues = stepIssues(form.schema, current, state.answers);
+			if (issues.length > 0) return {
+				...state,
+				issues
+			};
+			const completed = state.completed.includes(current.key) ? state.completed : [...state.completed, current.key];
+			const following = steps[index + 1];
+			return {
+				...state,
+				step: following?.key ?? current.key,
+				completed,
+				issues: []
+			};
+		}
+		case "back": {
+			const previous = steps[index - 1];
+			return previous === void 0 ? state : {
+				...state,
+				step: previous.key,
+				issues: []
+			};
+		}
+		case "goTo": {
+			const target = steps.findIndex((step) => step.key === action.step);
+			return target !== -1 && steps.slice(0, target).every((step) => state.completed.includes(step.key)) ? {
+				...state,
+				step: action.step,
+				issues: []
+			} : state;
+		}
+		case "reset": return initialQuestionnaire(form, action.answers);
+		default: return action;
+	}
+}
+/** The visible steps with their status, in the shape a Stepper renders. */
+function questionnaireSteps(form, state) {
+	return visibleSteps(form.definition, state.answers).map((step) => ({
+		key: step.key,
+		...step.title === void 0 ? {} : { title: step.title },
+		...step.description === void 0 ? {} : { description: step.description },
+		fields: visibleFields(step, state.answers),
+		completed: state.completed.includes(step.key),
+		active: step.key === state.step
+	}));
+}
+/** The pruned answers, or every issue when the whole form does not pass. */
+function finishQuestionnaire(form, state) {
+	const answers = pruneAnswers(form.definition, state.answers);
+	const issues = validateAnswers(form.schema, answers);
+	return issues.length === 0 ? {
+		ok: true,
+		answers
+	} : {
+		ok: false,
+		issues
+	};
+}
+//#endregion
+//#region src/blocks/forms/client.ts
+function byField(issues) {
+	const out = {};
+	for (const issue of issues) {
+		const key = issue.path?.[0];
+		const name = typeof key === "string" ? key : "";
+		(out[name] ??= []).push(issue.message);
+	}
+	return out;
+}
+function viewOf(form, current, finalIssues, submitting) {
+	const steps = questionnaireSteps(form, current);
+	const index = steps.findIndex((step) => step.active);
+	return {
+		steps,
+		step: steps[index],
+		answers: current.answers,
+		issues: byField([...current.issues, ...finalIssues]),
+		isFirst: index <= 0,
+		isLast: index === steps.length - 1,
+		submitting
+	};
+}
+/**
+* A multi-step form over a form version: the visible steps, the answers,
+* and per-field issues checked against the version's JSON Schema.
+*/
+function createQuestionnaireController(options) {
+	const { form } = options;
+	let current = initialQuestionnaire(form, options.initialAnswers);
+	let finalIssues = [];
+	let submitting = false;
+	return defineController(viewOf(form, current, finalIssues, submitting), (state) => {
+		const show = () => {
+			state.set(viewOf(form, current, finalIssues, submitting));
+		};
+		const dispatch = (action) => {
+			current = questionnaireReducer(form, current, action);
+			show();
+		};
+		return { actions: {
+			setAnswer: (key, value) => {
+				finalIssues = finalIssues.filter((issue) => issue.path?.[0] !== key);
+				dispatch({
+					type: "answer",
+					key,
+					value
+				});
+			},
+			next: () => {
+				dispatch({ type: "next" });
+			},
+			back: () => {
+				dispatch({ type: "back" });
+			},
+			goTo: (step) => {
+				dispatch({
+					type: "goTo",
+					step
+				});
+			},
+			reset: (answers) => {
+				finalIssues = [];
+				dispatch(answers === void 0 ? { type: "reset" } : {
+					type: "reset",
+					answers
+				});
+			},
+			submit: async () => {
+				const result = finishQuestionnaire(form, current);
+				if (!result.ok) {
+					finalIssues = result.issues;
+					show();
+					return false;
+				}
+				submitting = true;
+				show();
+				try {
+					await options.onSubmit(result.answers);
+				} finally {
+					submitting = false;
+					show();
+				}
+				return true;
+			}
+		} };
+	});
+}
+//#endregion
+export { pruneAnswers as a, stepIssues as c, answersSchema as d, validateAnswers as f, initialQuestionnaire as i, visibleFields as l, conditionHolds as n, questionnaireReducer as o, finishQuestionnaire as r, questionnaireSteps as s, createQuestionnaireController as t, visibleSteps as u };

package/dist/client-xkSCp9hN.d.ts

@@ -0,0 +1,101 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { n as BlockOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+//#region src/blocks/onboarding/onboarding.d.ts
+type ChecklistScope = "user" | "organization";
+/** One step. `events` completes it when the outbox records one of those types. */
+interface ChecklistStep<Id extends string = string> {
+  readonly id: Id;
+  readonly title?: string;
+  readonly description?: string;
+  /** Where the step is done in the app, for a "Start" link. */
+  readonly href?: string;
+  readonly events?: readonly string[];
+}
+interface ChecklistSpec<Id extends string, Scope extends ChecklistScope> {
+  readonly id: string;
+  /** `user` tracks each user; `organization` tracks each tenant. */
+  readonly scope: Scope;
+  readonly steps: readonly ChecklistStep<Id>[];
+}
+interface OnboardingOptions extends BlockOptions {
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Onboarding>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A step with the subject's progress. */
+interface StepProgress<Id extends string> extends ChecklistStep<Id> {
+  readonly completed: boolean;
+  readonly completedAt: Temporal.Instant | undefined;
+  readonly completedBy: string | undefined;
+}
+interface ChecklistProgress<Id extends string> {
+  readonly steps: readonly StepProgress<Id>[];
+  readonly completed: number;
+  readonly total: number;
+  /** Every step is complete. */
+  readonly done: boolean;
+  /** The first step not done yet. */
+  readonly next: StepProgress<Id> | undefined;
+}
+/** The organization for an organization checklist; nothing for a user one. */
+type ChecklistSubject<Scope extends ChecklistScope> = Scope extends "organization" ? [organizationId: string] : [];
+/** The onboarding block: progress through any checklist `defineChecklist` declared. */
+interface Onboarding {
+  /** The subject's progress: the caller's for a user checklist, the organization's otherwise. */
+  progress<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, ...subject: ChecklistSubject<Scope>): AsyncResult<ChecklistProgress<Id>>;
+  /** Marks a step done; `false` when it already was. */
+  complete<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+  /** Marks a step not done; `false` when it wasn't. */
+  reset<Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+}
+/** A checklist `defineChecklist` checked; pass it to the onboarding client's methods. */
+type Checklist<Id extends string, Scope extends ChecklistScope> = ChecklistSpec<Id, Scope>;
+/**
+ * Declares an onboarding checklist. Pass the result to
+ * `blocks.onboarding.options.checklists` so the database knows its
+ * steps, and to the methods of `createOnboarding` to read and complete them.
+ */
+declare function defineChecklist<const Id extends string, const Scope extends ChecklistScope>(spec: ChecklistSpec<Id, Scope>): Checklist<Id, Scope>;
+/**
+ * The onboarding block: reads and completes the steps of the checklists in
+ * `blocks.onboarding.options.checklists`, for the caller or an organization.
+ */
+declare function createOnboarding(options: OnboardingOptions): Onboarding;
+//#endregion
+//#region src/blocks/onboarding/client.d.ts
+/** The calls the controller makes for one checklist; `createOnboarding` fits. */
+interface OnboardingControllerClient<Id extends string, Scope extends ChecklistScope> {
+  progress(checklist: Checklist<Id, Scope>, ...subject: ChecklistSubject<Scope>): AsyncResult<ChecklistProgress<Id>>;
+  complete(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+  reset(checklist: Checklist<Id, Scope>, step: Id, ...subject: ChecklistSubject<Scope>): AsyncResult<boolean>;
+}
+interface OnboardingControllerOptions<Id extends string, Scope extends ChecklistScope> {
+  /** `createOnboarding({ transport })`. */
+  readonly client: OnboardingControllerClient<Id, Scope>;
+  /** The checklist, from `defineChecklist`. */
+  readonly checklist: Checklist<Id, Scope>;
+  readonly auth: AuthPort;
+  /** The organization, for an organization checklist; it waits without one. */
+  readonly organizationId?: string | null;
+}
+interface OnboardingSnapshot<Id extends string> {
+  /** `undefined` until the first load. */
+  readonly progress: ChecklistProgress<Id> | undefined;
+  readonly error: DbError | undefined;
+}
+interface OnboardingActions<Id extends string> {
+  /** Marks a step done, then loads the progress again. */
+  readonly complete: (step: Id) => Promise<void>;
+  readonly reset: (step: Id) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+}
+type OnboardingController<Id extends string> = Controller<OnboardingSnapshot<Id>, OnboardingActions<Id>>;
+/** A checklist's progress for the signed-in user, or for an organization. */
+declare function createOnboardingController<Id extends string, Scope extends ChecklistScope>(options: OnboardingControllerOptions<Id, Scope>): OnboardingController<Id>;
+//#endregion
+export { defineChecklist as _, OnboardingSnapshot as a, ChecklistProgress as c, ChecklistStep as d, ChecklistSubject as f, createOnboarding as g, StepProgress as h, OnboardingControllerOptions as i, ChecklistScope as l, OnboardingOptions as m, OnboardingController as n, createOnboardingController as o, Onboarding as p, OnboardingControllerClient as r, Checklist as s, OnboardingActions as t, ChecklistSpec as u };

package/dist/client-ysNShuJZ.d.ts

@@ -0,0 +1,39 @@
+import { n as Controller } from "./controller-D845qKh2.js";
+import { a as UndoToken } from "./undo-DGo0skyO.js";
+//#region src/blocks/undo/client.d.ts
+interface UndoEntry {
+  readonly id: number;
+  /** What the toast or menu shows, e.g. "Moved 3 tasks". */
+  readonly label: string;
+  readonly token: UndoToken;
+}
+interface UndoStackOptions {
+  /** Applies a token, e.g. a server action that calls `createUndo().apply(token)`. */
+  readonly apply: (token: UndoToken) => Promise<unknown>;
+  /** How many entries to keep; older ones drop off. Default 20. */
+  readonly limit?: number | undefined;
+}
+interface UndoSnapshot {
+  /** Newest last. */
+  readonly entries: readonly UndoEntry[];
+  readonly canUndo: boolean;
+  /** Whether an undo is running. */
+  readonly pending: boolean;
+  /** What the last failed undo threw; cleared by the next push or undo. */
+  readonly error: unknown;
+}
+interface UndoActions {
+  /** Adds a token; a `null` token (a change with no inverse) is ignored. */
+  readonly push: (token: UndoToken | null | undefined, label?: string) => void;
+  /**
+   * Applies the newest entry and removes it. A failed undo removes it too,
+   * since its rows changed since, and sets `error`. Resolves whether it worked.
+   */
+  readonly undo: () => Promise<boolean>;
+  readonly clear: () => void;
+}
+type UndoController = Controller<UndoSnapshot, UndoActions>;
+/** A stack of undo tokens on the client, for a toast's Undo button or a Cmd+Z handler. */
+declare function createUndoController(options: UndoStackOptions): UndoController;
+//#endregion
+export { UndoStackOptions as a, UndoSnapshot as i, UndoController as n, createUndoController as o, UndoEntry as r, UndoActions as t };

package/dist/clone-dN9XOL1K.js

@@ -0,0 +1,29 @@
+//#region src/core/clone.ts
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Copies plain objects and arrays so hooks and listeners cannot change the
+* caller's result (invariant 5). Temporal values are immutable and stay shared.
+*/
+function cloneValue(value) {
+	if (Array.isArray(value)) return value.map(cloneValue);
+	if (isPlainObject(value)) {
+		const copy = {};
+		for (const [key, item] of Object.entries(value)) copy[key] = cloneValue(item);
+		return copy;
+	}
+	return value;
+}
+/** Freezes plain objects and arrays in place, recursively, and returns the value. */
+function deepFreeze(value) {
+	if (Array.isArray(value) || isPlainObject(value)) {
+		for (const item of Object.values(value)) deepFreeze(item);
+		Object.freeze(value);
+	}
+	return value;
+}
+//#endregion
+export { deepFreeze as n, isPlainObject as r, cloneValue as t };

package/dist/cloud-event-5rCEzIgK.d.ts

@@ -0,0 +1,64 @@
+/// <reference lib="esnext.temporal" />
+import { D as BlockEventPattern, T as BlockEvent, o as EventHub } from "./events-CTreRrgP.js";
+//#region src/events/cloud-event.d.ts
+/** A CloudEvents 1.0 event. Extension attributes are lowercase alphanumerics. */
+interface CloudEvent<T = unknown> {
+  readonly specversion: "1.0";
+  readonly id: string;
+  readonly source: string;
+  readonly type: string;
+  readonly subject?: string;
+  readonly time?: string;
+  readonly datacontenttype?: string;
+  readonly dataschema?: string;
+  readonly data?: T;
+  readonly [extension: string]: unknown;
+}
+interface CloudEventOptions {
+  /** URI-reference of the producer, e.g. `https://crm.example.com` or `/crm`. */
+  readonly source: string;
+  /** Replaces the `dev.better-supabase` type prefix. */
+  readonly typePrefix?: string;
+  readonly id?: () => string;
+  readonly now?: () => Temporal.Instant;
+  /**
+   * The `dataschema` attribute: the URI (or `$id`) of the JSON Schema the
+   * event's `data` conforms to, e.g. a schema emitted next to an AsyncAPI
+   * document. A function picks one per event type and leaves it out by
+   * returning `undefined`. Defaults to none.
+   */
+  readonly dataschema?: string | ((event: DataschemaContext) => string | undefined);
+}
+/** What a `dataschema` function sees of an event. */
+interface DataschemaContext {
+  /** The CloudEvents `type`, with the configured prefix. */
+  readonly type: string;
+  /** App key of the mutated table, for row events. */
+  readonly table?: string;
+}
+/** Sends events somewhere: a queue, a bus, an outbox table, an HTTP endpoint. */
+interface EventSink {
+  send(events: readonly CloudEvent[]): void | Promise<void>;
+}
+/**
+ * A block event as a CloudEvent: `dev.better-supabase.support.started` with
+ * the event data and the actor (`actorId`) as `data` and the tenant as
+ * `partitionkey`.
+ */
+declare function blockCloudEvent(event: BlockEvent, options: CloudEventOptions): CloudEvent;
+interface ForwardBlockOptions extends CloudEventOptions {
+  /** Only forward events that match, e.g. `support.*`. Defaults to all. */
+  readonly types?: readonly BlockEventPattern[];
+  /** Sink failures never fail the block call. Defaults to the `Logger`. */
+  readonly onError?: (error: unknown, events: readonly CloudEvent[]) => void;
+}
+/**
+ * Sends a CloudEvent for every block event (`support.*`, `organization.*`, ...) to
+ * `sink`. Returns a function that stops forwarding. Like
+ * `forwardMutations`, sends are tracked on `betterSupabase.events`.
+ */
+declare function forwardBlockEvents(betterSupabase: {
+  readonly events: EventHub;
+}, sink: EventSink, options: ForwardBlockOptions): () => void;
+//#endregion
+export { ForwardBlockOptions as a, EventSink as i, CloudEventOptions as n, blockCloudEvent as o, DataschemaContext as r, forwardBlockEvents as s, CloudEvent as t };

package/dist/cloud-event-CTh9Sr5w.js

@@ -0,0 +1,60 @@
+//#region src/events/cloud-event.ts
+/** The CloudEvents type prefix when no `typePrefix` is set. */
+const DEFAULT_TYPE_PREFIX = "dev.better-supabase";
+/** `type` without `typePrefix` and its dot, as sinks store it. Other types come back unchanged. */
+function stripTypePrefix(type, typePrefix = DEFAULT_TYPE_PREFIX) {
+	const prefix = `${typePrefix.replace(/\.$/, "")}.`;
+	return type.startsWith(prefix) ? type.slice(prefix.length) : type;
+}
+/** The `dataschema` attribute for an event, or nothing. */
+function dataschemaOf(options, event) {
+	const uri = typeof options.dataschema === "function" ? options.dataschema(event) : options.dataschema;
+	return uri === void 0 ? {} : { dataschema: uri };
+}
+/**
+* A block event as a CloudEvent: `dev.better-supabase.support.started` with
+* the event data and the actor (`actorId`) as `data` and the tenant as
+* `partitionkey`.
+*/
+function blockCloudEvent(event, options) {
+	const type = `${options.typePrefix ?? "dev.better-supabase"}.${event.type}`;
+	return {
+		specversion: "1.0",
+		id: options.id?.() ?? crypto.randomUUID(),
+		source: options.source,
+		type,
+		...event.subject ? { subject: event.subject } : {},
+		time: (options.now?.() ?? event.time).toString(),
+		datacontenttype: "application/json",
+		...dataschemaOf(options, { type }),
+		data: event.actorId ? {
+			...event.data,
+			actorId: event.actorId
+		} : event.data,
+		...event.tenant ? { partitionkey: event.tenant } : {}
+	};
+}
+/**
+* Sends a CloudEvent for every block event (`support.*`, `organization.*`, ...) to
+* `sink`. Returns a function that stops forwarding. Like
+* `forwardMutations`, sends are tracked on `betterSupabase.events`.
+*/
+function forwardBlockEvents(betterSupabase, sink, options) {
+	const types = options.types;
+	return betterSupabase.events.on("block", (event) => {
+		if (types && !types.some((pattern) => pattern.endsWith(".*") ? event.type.startsWith(pattern.slice(0, -1)) : pattern === event.type)) return;
+		const events = [blockCloudEvent(event, options)];
+		const report = (error) => {
+			(options.onError ?? ((cause) => {
+				betterSupabase.events.logger.error("event sink failed", { cause });
+			}))(error, events);
+		};
+		try {
+			betterSupabase.events.track(Promise.resolve(sink.send(events)).catch(report));
+		} catch (error) {
+			report(error);
+		}
+	});
+}
+//#endregion
+export { stripTypePrefix as a, forwardBlockEvents as i, blockCloudEvent as n, dataschemaOf as r, DEFAULT_TYPE_PREFIX as t };