better-supabase 0.13.0 → 0.14.0

package/dist/react-env-CfA3EdBH.js

@@ -0,0 +1,20 @@
+import { t as ClientContext } from "./context-CMxVnPMY.js";
+import { t as blockEnv } from "./block-env-DJiUu1fq.js";
+import { useContext, useMemo, useSyncExternalStore } from "react";
+//#region src/blocks/react-env.ts
+/**
+* The provider's client, session and ports; the topic port defaults to its
+* supabase-js client.
+*/
+function useBlockEnv() {
+	const value = useContext(ClientContext);
+	if (!value) throw new Error("better-supabase: wrap your app in <BetterSupabaseProvider client={bs}>");
+	const { client } = value;
+	return useMemo(() => blockEnv(client), [client]);
+}
+/** The env's tenant, rendered again when the session changes. */
+function useBlockTenant(env) {
+	return useSyncExternalStore(env.auth.subscribe, env.tenant, () => env.tenant());
+}
+//#endregion
+export { useBlockTenant as n, useBlockEnv as t };

package/dist/react-router/index.d.ts

@@ -1,9 +1,10 @@
-import { a as AnyModels, i as AnyFunctions } from "../types-DmshMaXz.js";
-import { t as BetterSupabase } from "../define-D0LSXmUP.js";
-import { n as BetterServer } from "../server-types-D_cQ6OxZ.js";
-import { a as AuthorizedContext, c as ResourceLoaderContext, i as AuthorizeOptions, l as Unwrapped, n as ActionParsed, o as BlockActionOptions, r as ActionResult, s as BlockRequireOptions } from "../kit-LeQGMzLH.js";
-import { t as RefusalRedirects } from "../refusal-BEyNVFy7.js";
-import { n as FrameworkOptions, r as LocalsResource, t as FrameworkLocals } from "../framework-CMeAuJts.js";
+import { M as AnyFunctions, N as AnyModels } from "../executor-CPyrQdjh.js";
+import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-DFP3gHv8.js";
+import { t as BetterSupabase } from "../define-Dw7pRO4h.js";
+import { n as BetterServer } from "../server-types-BOs-eFpo.js";
+import { a as AuthorizedContext, c as ResourceLoaderContext, i as AuthorizeOptions, l as Unwrapped, n as ActionParsed, o as BlockActionOptions, r as ActionResult, s as BlockRequireOptions } from "../kit-DKfbNTAA.js";
+import { t as RefusalRedirects } from "../refusal-efy5bZMd.js";
+import { n as FrameworkOptions, r as LocalsResource, t as FrameworkLocals } from "../framework-FxfJpyoF.js";
 import { t as Validated } from "../shared-CRRfQAKG.js";
 import { AnyEntry, Contributions } from "@supabase/middleware";
 import { StandardSchemaV1 } from "@standard-schema/spec";
@@ -61,7 +62,7 @@ interface ReactRouterOptions extends FrameworkOptions {
    */
   readonly platformEnv?: (args: ReactRouterArgs) => unknown;
 }
-interface BetterReactRouter<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown> extends BetterServer<M, F, E, C, P, B> {
+interface BetterReactRouter<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string, B = unknown> extends BetterServer<M, F, E, C, P, B> {
   /**
    * The context key the middleware sets: `context.get(bs.contextKey)`, or
    * `bs.locals(args)`.
@@ -80,11 +81,13 @@ interface BetterReactRouter<M extends AnyModels, F extends AnyFunctions, E, C =
    * for the `ErrorBoundary`. `Result`s unwrap, and a failed one is thrown the
    * same way.
    */
-  loader<A extends ReactRouterArgs, T, R extends boolean = false>(options: BlockRequireOptions<C, P, R, unknown, LocalsResource<M, F, E, C, P, B>>, fn: (args: A, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>) => T): (args: A) => Promise<Unwrapped<Awaited<T>>>;
+  loader<A extends ReactRouterArgs, T, R extends boolean = false>(options: BlockRequireOptions<C, P, R, Ref, LocalsResource<M, F, E, C, P, B>>, fn: (args: A, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>) => T): (args: A) => Promise<Unwrapped<Awaited<T>>>;
   /** An action returning an `ActionResult`, for `useActionData` or `useAction`. */
-  action<S extends StandardSchemaV1 | undefined, T, A extends ReactRouterArgs = ReactRouterArgs, R extends boolean = false>(options: BlockActionOptions<S, C, P, R, unknown, LocalsResource<M, F, E, C, P, B>>, fn: (input: ActionParsed<S>, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>, args: A) => T): (args: A) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
+  action<S extends StandardSchemaV1 | undefined, T, A extends ReactRouterArgs = ReactRouterArgs, R extends boolean = false>(options: BlockActionOptions<S, C, P, R, Ref, LocalsResource<M, F, E, C, P, B>>, fn: (input: ActionParsed<S>, ctx: FrameworkLocals<M, F, E, C, P, B> & AuthorizedContext<C, P, R>, args: A) => T): (args: A) => Promise<ActionResult<Unwrapped<Awaited<T>>>>;
 }
 /** React Router integration: middleware, guarded loaders and actions. */
-export declare function createReactRouter<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, B = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P, B>, options: ReactRouterOptions): BetterReactRouter<M, F, E, C, P, B>;
+export declare function createReactRouter<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, A extends AnyAuthorizer | undefined = undefined, B = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P, B>, options: ReactRouterOptions & {
+  readonly authorizer?: A;
+}): BetterReactRouter<M, F, E, C, P, PermissionRef<A>, B>;
 //#endregion
 export type { ActionResult, AuthorizeOptions, AuthorizedContext, BetterReactRouter, BlockActionOptions, BlockRequireOptions, FrameworkLocals, FrameworkOptions, ReactRouterArgs, ReactRouterContext, ReactRouterContextProvider, ReactRouterMiddleware, ReactRouterOptions, RefusalRedirects, ResourceLoaderContext, ToReactRouterOptions };

package/dist/react-router/index.js

@@ -1,10 +1,10 @@
-import { o as problemResponse } from "../problem-D0KDiYPk.js";
-import { c as extendServer, o as withFlush, s as createServer } from "../adapter-D8dW6p2A.js";
-import { o as settle, t as defaultExpose } from "../respond-DjEmE_DN.js";
-import { i as requireCaller, o as runAction } from "../kit-BeXTrlZn.js";
+import { o as problemResponse } from "../problem-BWElIgIb.js";
+import { c as extendServer, o as withFlush, s as createServer } from "../adapter-BCFAg58A.js";
+import { o as settle, t as defaultExpose } from "../respond-z_yfyitp.js";
+import { i as requireCaller, o as runAction } from "../kit-Ct4Z6GIO.js";
 import { n as bufferInPlace, t as around } from "../shared-Bf-I13Ht.js";
-import { i as localsOf, n as actionInput, r as frameworkEntry } from "../framework-BpEnOfAo.js";
-import { r as refusalResponse } from "../refusal-Ce2p81VW.js";
+import { i as localsOf, n as actionInput, r as frameworkEntry } from "../framework-CXoyWGgd.js";
+import { r as refusalResponse } from "../refusal-DXydjgsS.js";
 //#region src/bridges/react-router.ts
 /**
 * Runs an entry array as React Router server middleware. The contributions are

package/dist/read-set-BAR84kPC.js

@@ -0,0 +1,199 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { n as isQuerySpec, r as specTables } from "./spec-CoWHDoud.js";
+//#region src/core/read-set.ts
+const NAME = /^[a-z][a-z0-9_]{0,59}$/;
+const PARAM = /^[a-z_][a-z0-9_]*$/i;
+const TYPE = /^(?:[a-z_][a-z0-9_]*\.)?[a-z_][a-z0-9_]*(?:\[\])?$/;
+/** `jsonb_build_object` takes at most 100 arguments. */
+const MAX_ENTRIES = 50;
+/**
+* Placeholders are `NUL bs:<name> NUL`: no real parameter value holds a NUL.
+* Auth placeholders start with `@`, which no parameter name can.
+*/
+const NUL = "\0";
+const SENTINEL = /* @__PURE__ */ new RegExp(`${NUL}bs:(@?[a-z_][a-z0-9_]*)${NUL}`, "gi");
+const EXACT = /* @__PURE__ */ new RegExp(`^${NUL}bs:(@?[a-z_][a-z0-9_]*)${NUL}$`, "i");
+function sentinel(name) {
+	return `${NUL}bs:${name}${NUL}`;
+}
+const AUTH = { uid: sentinel("@uid") };
+function tagged(name, array) {
+	if (!name.startsWith("@")) return {
+		kind: "param",
+		name,
+		array
+	};
+	return name === "@uid" ? {
+		kind: "auth",
+		name: "uid",
+		array
+	} : void 0;
+}
+/**
+* Registers reads that run as one round trip:
+*
+* ```ts
+* export const appChrome = defineReadSet(
+*   betterSupabase,
+*   "app_chrome",
+*   { params: { userId: "uuid" } },
+*   (s, p) => ({
+*     unread: s.notifications.count({
+*       where: { userId: p.userId, readAt: null },
+*     }),
+*     me: s.profiles.findFirst({ where: { id: p.userId } }),
+*   }),
+* );
+* ```
+*
+* `p` holds placeholders, not values: pass them straight into `where` (or
+* `in`), where the function reads them from its `p jsonb` argument.
+*/
+function defineReadSet(betterSupabase, name, options, build) {
+	if (!NAME.test(name)) throw new TypeError(`better-supabase: read set name "${name}" must be snake_case and at most 60 characters`);
+	const params = options.params ?? {};
+	const placeholders = {};
+	for (const [key, type] of Object.entries(params)) {
+		if (!PARAM.test(key)) throw new TypeError(`better-supabase: read set "${name}" has an invalid parameter name "${key}"`);
+		if (!TYPE.test(type)) throw new TypeError(`better-supabase: read set "${name}" parameter "${key}" has an invalid type "${type}"`);
+		placeholders[key] = type.endsWith("[]") ? [sentinel(key)] : sentinel(key);
+	}
+	const specs = build(betterSupabase.spec, placeholders, AUTH);
+	const entries = Object.entries(specs);
+	if (entries.length === 0 || entries.length > MAX_ENTRIES) throw new TypeError(`better-supabase: read set "${name}" needs between 1 and ${MAX_ENTRIES} reads`);
+	for (const [key, spec] of entries) if (!isQuerySpec(spec)) throw new TypeError(`better-supabase: read set "${name}" entry "${key}" is not a spec from betterSupabase.spec`);
+	warnUnscopedReads(betterSupabase, name, specs);
+	return {
+		kind: "read-set",
+		name,
+		functionName: `rs_${name}`,
+		params,
+		roles: options.roles ?? ["authenticated"],
+		specs,
+		definition: betterSupabase
+	};
+}
+/**
+* The generated function runs the reads as compiled at `gen` time, without the
+* runtime's `transformQuery` plugins, so tenant and soft-delete filters that
+* only those plugins add never reach it.
+*/
+function warnUnscopedReads(betterSupabase, name, specs) {
+	const filtering = betterSupabase.plugins.filter((plugin) => plugin.transformQuery !== void 0 && plugin.scopes?.length !== 0);
+	if (filtering.length === 0) return;
+	const { meta } = betterSupabase;
+	const filters = (plugin, key) => {
+		const flags = meta.tables[key]?.flags;
+		return plugin.scopes === void 0 || plugin.scopes.some((flag) => flags?.[flag] !== void 0);
+	};
+	const tables = [...new Set(Object.values(specs).flatMap((spec) => specTables(meta, spec)))].filter((key) => filtering.some((plugin) => filters(plugin, key)));
+	if (tables.length === 0) return;
+	const scoping = filtering.filter((plugin) => tables.some((key) => filters(plugin, key))).map((plugin) => plugin.name);
+	betterSupabase.events.logger.warn(`read set "${name}" reads ${tables.join(", ")}, which ${scoping.join(", ")} scope at runtime; its generated function only sees those filters when the specs spell them out (or RLS enforces them)`, {
+		readSet: name,
+		tables,
+		plugins: scoping
+	});
+}
+function isReadSet(value) {
+	return typeof value === "object" && value !== null && value.kind === "read-set" && typeof value.name === "string";
+}
+/** The placeholder a string or array carries, if it is exactly one. */
+function placeholderOf(value) {
+	if (typeof value === "string") {
+		const match = EXACT.exec(value);
+		return match ? tagged(match[1], false) : void 0;
+	}
+	if (Array.isArray(value) && value.length === 1) {
+		const inner = placeholderOf(value[0]);
+		return inner && !inner.array ? {
+			...inner,
+			array: true
+		} : inner;
+	}
+}
+/** Splits a string around the placeholders inside it. */
+function splitPlaceholders(value) {
+	const parts = [];
+	let last = 0;
+	for (const match of value.matchAll(SENTINEL)) {
+		if (match.index > last) parts.push({ text: value.slice(last, match.index) });
+		const placeholder = tagged(match[1], false);
+		parts.push(placeholder ?? { text: match[0] });
+		last = match.index + match[0].length;
+	}
+	if (last < value.length) parts.push({ text: value.slice(last) });
+	return parts;
+}
+function hasPlaceholder(value) {
+	return value.includes(`${NUL}bs:`);
+}
+/** Whether any string inside `value` is (or holds) a placeholder. */
+function containsPlaceholder(value) {
+	if (typeof value === "string") return hasPlaceholder(value);
+	if (Array.isArray(value)) return value.some(containsPlaceholder);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(containsPlaceholder);
+	return false;
+}
+/** Whether the set's specs read the caller's identity. */
+function readSetUsesAuth(set) {
+	return Object.values(set.specs).some((spec) => usesAuth(spec.args));
+}
+function usesAuth(value) {
+	if (typeof value === "string") return [...value.matchAll(SENTINEL)].some((match) => match[1].startsWith("@"));
+	if (Array.isArray(value)) return value.some(usesAuth);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(usesAuth);
+	return false;
+}
+/** Missing or wrongly typed parameters, as messages. */
+function checkParams(set, values) {
+	const problems = [];
+	for (const [key, type] of Object.entries(set.params)) {
+		const value = values?.[key];
+		if (value === void 0 || value === null) problems.push(`missing parameter "${key}"`);
+		else if (type.endsWith("[]") !== Array.isArray(value)) problems.push(`parameter "${key}" must be ${type.endsWith("[]") ? "an array" : "a single value"}`);
+	}
+	return problems;
+}
+/**
+* The specs with every placeholder replaced by its value; `auth.uid` takes the
+* `sub` claim, which must be verified. `noCaller` is set when the set reads
+* `auth.uid` and there is no `sub`: the specs then match no user, and only the
+* function, which reads `auth.uid()` itself, can run the set.
+*/
+function bindParams(set, values, context) {
+	const sub = context.claims?.["sub"];
+	const uid = typeof sub === "string" && sub !== "" ? sub : null;
+	const valueOf = (placeholder) => placeholder.kind === "auth" ? uid : values?.[placeholder.name];
+	const bind = (value) => {
+		const placeholder = placeholderOf(value);
+		if (placeholder) {
+			const bound = valueOf(placeholder);
+			return placeholder.kind === "auth" && placeholder.array ? [bound] : bound;
+		}
+		if (typeof value === "string") {
+			if (!hasPlaceholder(value)) return value;
+			return splitPlaceholders(value).map((part) => "text" in part ? part.text : String(valueOf(part) ?? "")).join("");
+		}
+		if (Array.isArray(value)) return value.map(bind);
+		if (typeof value === "object" && value !== null) {
+			if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+			return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, bind(entry)]));
+		}
+		return value;
+	};
+	return {
+		specs: Object.fromEntries(Object.entries(set.specs).map(([key, spec]) => [key, {
+			...spec,
+			args: spec.args.map(bind)
+		}])),
+		noCaller: uid === null && readSetUsesAuth(set) ? dbError("invalid_request", `db.$many(${set.name}): the read set reads auth.uid, but this connection has no user claims. Connect with the user's verified claims ({ claims: { sub } }), or call it over PostgREST, where the function reads auth.uid().`) : void 0
+	};
+}
+/** App keys of every table the set reads. */
+function readSetTables(set, meta) {
+	const schema = meta ?? set.definition.meta;
+	return [...new Set(Object.values(set.specs).flatMap((spec) => specTables(schema, spec)))];
+}
+//#endregion
+export { hasPlaceholder as a, readSetTables as c, defineReadSet as i, splitPlaceholders as l, checkParams as n, isReadSet as o, containsPlaceholder as r, placeholderOf as s, bindParams as t };

package/dist/realtime/index.d.ts

@@ -1,8 +1,8 @@
-import { n as AccessPolicySql, r as AccessTopicPolicy } from "../types-DmshMaXz.js";
+import { A as AccessPolicySql, j as AccessTopicPolicy } from "../executor-CPyrQdjh.js";
 import { t as RealtimeStatus } from "../realtime-status-BhNkb-Ow.js";
-import { $ as TemplateValues, Q as TemplateParams } from "../bucket-DBay-ICp.js";
-import { A as TriggerTopic, C as TopicSubscription, D as TriggerLookup, E as TopicTriggerValue, F as FanOutResult, I as TopicFanOutOptions, M as defineTopic, N as rowChange, O as TriggerOptions, P as rowKeys, S as TopicSubscribeOptions, T as TopicTriggerOptions, _ as TopicMessage, a as PresenceOutput, b as TopicPermission, c as RealtimeClient, d as SubscribeOptions, f as Subscription, g as TopicHandlers, h as TopicEvent, i as PresenceOptions, j as TriggerValue, k as TriggerPayloadMode, l as RowChange, m as Topic, n as PresenceInput, o as PresenceSchema, p as SubscriptionStatus, r as PresenceMember, s as PresenceSubscription, t as EventSchemas, u as RowKeys, v as TopicOptions, w as TopicTriggerLookup, x as TopicSqlOptions, y as TopicPayload } from "../topic-CZvLXFND.js";
-import { a as watchTopic, i as topicPort, n as TopicPort, r as TopicWatch, t as TopicHandle } from "../watch-topic-CloXeDTO.js";
-import { n as subjectReaders, t as SubjectReadersOptions } from "../subject-readers-Bbq1i0Ol.js";
-import { a as LiveSource, c as liveQuery, i as LiveQueryOptions, l as liveTopic, n as LiveCountOptions, o as LiveSubscription, r as LiveCountSeed, s as liveCount, t as CountRunner } from "../index-C7-2ZS9f.js";
-export { type AccessPolicySql, type AccessTopicPolicy, type CountRunner, type EventSchemas, type FanOutResult, type LiveCountOptions, type LiveCountSeed, type LiveQueryOptions, type LiveSource, type LiveSubscription, type PresenceInput, type PresenceMember, type PresenceOptions, type PresenceOutput, type PresenceSchema, type PresenceSubscription, type RealtimeClient, type RealtimeStatus, type RowChange, type RowKeys, type SubjectReadersOptions, type SubscribeOptions, type Subscription, type SubscriptionStatus, type TemplateParams, type TemplateValues, type Topic, type TopicEvent, type TopicFanOutOptions, type TopicHandle, type TopicHandlers, type TopicMessage, type TopicOptions, type TopicPayload, type TopicPermission, type TopicPort, type TopicSqlOptions, type TopicSubscribeOptions, type TopicSubscription, type TopicTriggerLookup, type TopicTriggerOptions, type TopicTriggerValue, type TopicWatch, type TriggerLookup, type TriggerOptions, type TriggerPayloadMode, type TriggerTopic, type TriggerValue, defineTopic, liveCount, liveQuery, liveTopic, rowChange, rowKeys, subjectReaders, topicPort, watchTopic };
+import { $ as TemplateValues, Q as TemplateParams } from "../bucket-TkB7_xv8.js";
+import { A as TriggerTopic, C as TopicSubscription, D as TriggerLookup, E as TopicTriggerValue, F as FanOutResult, I as TopicFanOutOptions, M as defineTopic, N as rowChange, O as TriggerOptions, P as rowKeys, S as TopicSubscribeOptions, T as TopicTriggerOptions, _ as TopicMessage, a as PresenceOutput, b as TopicPermission, c as RealtimeClient, d as SubscribeOptions, f as Subscription, g as TopicHandlers, h as TopicEvent, i as PresenceOptions, j as TriggerValue, k as TriggerPayloadMode, l as RowChange, m as Topic, n as PresenceInput, o as PresenceSchema, p as SubscriptionStatus, r as PresenceMember, s as PresenceSubscription, t as EventSchemas, u as RowKeys, v as TopicOptions, w as TopicTriggerLookup, x as TopicSqlOptions, y as TopicPayload } from "../topic-D9j8G2dw.js";
+import { a as watchTopic, i as topicPort, n as TopicPort, r as TopicWatch, t as TopicHandle } from "../watch-topic-CIT3UlAh.js";
+import { a as LiveSource, c as liveQuery, d as SubjectPresenceTopic, f as SubjectPresenceValues, h as subjectPresenceValues, i as LiveQueryOptions, l as liveTopic, m as subjectPresenceTopic, n as LiveCountOptions, o as LiveSubscription, p as subjectPresence, r as LiveCountSeed, s as liveCount, t as CountRunner, u as SUBJECT_PRESENCE_TEMPLATE } from "../index-eTY4kJzo.js";
+import { n as subjectReaders, t as SubjectReadersOptions } from "../subject-readers-DEZ45DQF.js";
+export { type AccessPolicySql, type AccessTopicPolicy, type CountRunner, type EventSchemas, type FanOutResult, type LiveCountOptions, type LiveCountSeed, type LiveQueryOptions, type LiveSource, type LiveSubscription, type PresenceInput, type PresenceMember, type PresenceOptions, type PresenceOutput, type PresenceSchema, type PresenceSubscription, type RealtimeClient, type RealtimeStatus, type RowChange, type RowKeys, SUBJECT_PRESENCE_TEMPLATE, type SubjectPresenceTopic, type SubjectPresenceValues, type SubjectReadersOptions, type SubscribeOptions, type Subscription, type SubscriptionStatus, type TemplateParams, type TemplateValues, type Topic, type TopicEvent, type TopicFanOutOptions, type TopicHandle, type TopicHandlers, type TopicMessage, type TopicOptions, type TopicPayload, type TopicPermission, type TopicPort, type TopicSqlOptions, type TopicSubscribeOptions, type TopicSubscription, type TopicTriggerLookup, type TopicTriggerOptions, type TopicTriggerValue, type TopicWatch, type TriggerLookup, type TriggerOptions, type TriggerPayloadMode, type TriggerTopic, type TriggerValue, defineTopic, liveCount, liveQuery, liveTopic, rowChange, rowKeys, subjectPresence, subjectPresenceTopic, subjectPresenceValues, subjectReaders, topicPort, watchTopic };

package/dist/realtime/index.js

@@ -1,5 +1,37 @@
 import { n as liveQuery, r as liveTopic, t as liveCount } from "../live-CZtRMh62.js";
-import { t as subjectReaders } from "../subject-readers-BJzh7WF7.js";
 import { n as watchTopic, t as topicPort } from "../watch-topic-CuaWfCuv.js";
-import { n as rowChange, r as rowKeys, t as defineTopic } from "../topic-Cr01EHZy.js";
-export { defineTopic, liveCount, liveQuery, liveTopic, rowChange, rowKeys, subjectReaders, topicPort, watchTopic };
+import { t as subjectReaders } from "../subject-readers-CsTpx44c.js";
+import { n as rowChange, r as rowKeys, t as defineTopic } from "../topic-CPOmMgkf.js";
+//#region src/realtime/subject-presence.ts
+/** The presence topic template; the subjects module's policies authorize it. */
+const SUBJECT_PRESENCE_TEMPLATE = "presence:{subjectType}:{subjectId}";
+function subjectPresenceTopic(schema) {
+	return defineTopic(SUBJECT_PRESENCE_TEMPLATE, {
+		name: "subject_presence",
+		presence: schema ?? true,
+		tenant: false,
+		owner: false
+	});
+}
+/** `subjectPresenceTopic()` without a schema. */
+const subjectPresence = subjectPresenceTopic();
+/**
+* The topic values of a subject for `usePresence` and the bindings; `null` (no
+* subject yet) pauses the join.
+*
+* ```tsx
+* const { members } = usePresence(
+*   subjectPresence,
+*   subjectPresenceValues({ type: "conversation", id: conversationId }),
+*   { state: { name, avatarUrl } },
+* );
+* ```
+*/
+function subjectPresenceValues(subject) {
+	return subject ? {
+		subjectType: subject.type,
+		subjectId: subject.id
+	} : null;
+}
+//#endregion
+export { SUBJECT_PRESENCE_TEMPLATE, defineTopic, liveCount, liveQuery, liveTopic, rowChange, rowKeys, subjectPresence, subjectPresenceTopic, subjectPresenceValues, subjectReaders, topicPort, watchTopic };

package/dist/recordings-DgDu7AOt.d.ts

@@ -0,0 +1,119 @@
+/// <reference lib="esnext.temporal" />
+import { o as AiFile } from "./types-BEDfwXL4.js";
+//#region src/blocks/engagements/recordings.d.ts
+/** The queue a recording's transcription job goes on, with the jobs block. */
+declare const ENGAGEMENT_TRANSCRIBE_QUEUE = "engagements.transcribe";
+/** `pending` until a transcript is saved; `failed` when the transcriber gave up. */
+type EngagementRecordingStatus = "pending" | "transcribed" | "failed";
+/** A call or meeting recording: an ai-files file on an engagement. */
+interface EngagementRecording {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly engagementId: string;
+  readonly fileId: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly status: EngagementRecordingStatus;
+  /** A BCP 47 tag such as `en` or `nl-NL`, given or detected. */
+  readonly language?: string;
+  readonly durationSeconds?: number;
+  /** Why the transcriber failed. */
+  readonly error?: string;
+  /** The transcriber's model. */
+  readonly model?: string;
+  readonly segmentCount: number;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly transcribedAt?: Temporal.Instant;
+}
+/** One speaker turn of a transcript. */
+interface TranscriptSegment {
+  /** 1 for the first turn. */
+  readonly position: number;
+  /** The speaker's label, such as `Speaker 1` or a name. */
+  readonly speaker?: string;
+  /** The member who spoke, when known. */
+  readonly speakerUserId?: string;
+  /** Milliseconds from the start of the recording. */
+  readonly startMs: number;
+  readonly endMs: number;
+  readonly text: string;
+  /** Between 0 and 1. */
+  readonly confidence?: number;
+}
+type TranscriptSegmentInput = Omit<TranscriptSegment, "position">;
+/** What a transcriber returns and `saveTranscript` stores. */
+interface Transcript {
+  /** In order; `startMs` at most `endMs`. */
+  readonly segments: readonly TranscriptSegmentInput[];
+  readonly language?: string;
+  readonly durationSeconds?: number;
+}
+/** What `Transcriber.transcribe` gets for one recording. */
+interface TranscriberInput {
+  readonly file: Pick<AiFile, "id" | "filename" | "mediaType">;
+  /** A signed URL to the audio or video, for providers that fetch it. */
+  readonly url: string;
+  /** The bytes, for providers that take an upload. */
+  read(): Promise<Uint8Array>;
+  /** The language given when the recording was attached. */
+  readonly language?: string;
+}
+/**
+ * Turns a recording into speaker turns. Wrap any speech-to-text API or SDK in
+ * the app; the block imports none.
+ */
+interface Transcriber {
+  /** The transcriber contract version. Omitted means 1. */
+  readonly apiVersion?: 1;
+  readonly model: string;
+  transcribe(input: TranscriberInput, options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<Transcript>;
+}
+/** A follow-up a note names. */
+interface EngagementActionItem {
+  readonly text: string;
+  readonly ownerId?: string;
+  readonly dueAt?: Temporal.Instant;
+}
+/** What `saveNotes` stores and a note taker returns. */
+interface EngagementNotesInput {
+  readonly summary: string;
+  readonly actionItems?: readonly EngagementActionItem[];
+}
+/** The notes on an engagement: a summary and its action items. */
+interface EngagementNotes {
+  readonly engagementId: string;
+  readonly organizationId: string;
+  readonly summary: string;
+  readonly actionItems: readonly EngagementActionItem[];
+  /** The note taker's model, for notes an AI wrote. */
+  readonly model?: string;
+  /** `ai` from `summarize`, `member` when a member wrote them. */
+  readonly source: "ai" | "member";
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+/** What `NoteTaker.summarize` gets: the engagement and its transcripts. */
+interface NoteTakerInput<E> {
+  readonly engagement: E;
+  readonly transcript: readonly (TranscriptSegment & {
+    readonly recordingId: string;
+  })[];
+}
+/**
+ * Writes a summary and action items for an engagement from its transcripts.
+ * Wrap any model in the app; the block imports no AI SDK (ADR 0010).
+ */
+interface NoteTaker {
+  /** The note taker contract version. Omitted means 1. */
+  readonly apiVersion?: 1;
+  readonly model: string;
+  summarize<E>(input: NoteTakerInput<E>, options?: {
+    readonly signal?: AbortSignal;
+  }): Promise<EngagementNotesInput>;
+}
+//#endregion
+export { EngagementRecording as a, NoteTakerInput as c, Transcript as d, TranscriptSegment as f, EngagementNotesInput as i, Transcriber as l, EngagementActionItem as n, EngagementRecordingStatus as o, TranscriptSegmentInput as p, EngagementNotes as r, NoteTaker as s, ENGAGEMENT_TRANSCRIBE_QUEUE as t, TranscriberInput as u };

package/dist/records/index.d.ts

@@ -0,0 +1,83 @@
+import { b as DbError, t as AsyncResult } from "../result-C6jDfedy.js";
+import { dt as SubjectRef } from "../executor-CPyrQdjh.js";
+import { $t as sectionRowInput, Bt as SectionMap, Ft as AnySection, Gt as SectionWrite, Ht as SectionPermissions, It as AnySectionWrite, Jt as SectionWriteOutput, Kt as SectionWriteInput, Lt as Section, Qt as sectionEventMatches, Rt as SectionData, Ut as SectionResult, Vt as SectionOptions, Wt as SectionRowInput, Xt as TimelineItem, Yt as SectionWrites, Zt as defineSection, en as sectionWrite, qt as SectionWriteName, zt as SectionDefinition } from "../define-block-COpcS6aT.js";
+import { A as LoadSectionsOptions, B as PermissionFlags, C as defineRecordFeature, D as recordPermissionKeys, E as recordCan, F as SectionNamed, H as can, I as SectionSource, L as countSection, M as SectionBlocks, N as SectionCheck, O as recordSubject, P as SectionName, R as loadSections, S as SectionWritesOf, T as plainData, U as permissionFlags, V as PermissionSet, _ as PlainSections, b as RecordFeatureSpec, d as FeatureBlocks, f as FeaturePermissions, g as PlainSection, h as Plain, j as LoadedSections, k as recordWriteInput, m as FeatureWriteOutput, p as FeatureWriteInput, v as RecordCan, w as findSectionWrite, x as RecordWriteInput, y as RecordFeature, z as sectionCan } from "../index-DbXWcrOI.js";
+import { p as SubscriptionStatus } from "../topic-D9j8G2dw.js";
+import { n as TopicPort } from "../watch-topic-CIT3UlAh.js";
+import { n as Controller, t as AuthPort } from "../controller-DAD4hbl4.js";
+import { a as RecordSummaryOptions, c as Subjects, f as MyWorkKind, i as RecordSummary, n as MyWorkItem, r as MyWorkOptions } from "../subjects-DXFmanh5.js";
+import { a as timelineSections, c as RecordListCells, d as RecordListQuery, f as RecordListRow, h as defineRecordList, i as loadTimeline, l as RecordListColumn, m as RecordListSpec, n as Timeline, o as RecordList, p as RecordListSource, r as TimelineEntry, s as RecordListCell, t as LoadTimelineOptions, u as RecordListPage } from "../timeline-DUUsPLv5.js";
+import { a as EntityFormOptions, c as entityForm, i as EntityFormInput, n as EntityFormCustomField, o as EntityFormResult, r as EntityFormField, s as EntityFormValues, t as EntityForm } from "../entity-form-B67vq97h.js";
+//#region src/records/controller.d.ts
+interface RecordControllerOptions<B extends SectionBlocks, N extends SectionName<B>> extends LoadSectionsOptions<B, N> {
+  readonly source: SectionSource<B>;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The record to follow; nothing loads without one. */
+  readonly subject: SubjectRef | null;
+  readonly sections: readonly N[];
+  /**
+   * The one private topic that hears of changes to the record, such as a
+   * broadcast of its block events. A message whose event a section lists in
+   * `events` loads that section again; any other message loads every section.
+   * Default `null`: sections load again on `refresh` only.
+   */
+  readonly topic?: string | null;
+  /**
+   * The subjects client, to load `record_summary` (title, counts, unread) next
+   * to the sections.
+   */
+  readonly summary?: Pick<Subjects, "summary">;
+  readonly summaryOptions?: RecordSummaryOptions;
+}
+interface RecordSnapshot<B extends SectionBlocks, N extends string> {
+  /** Each section settled; `undefined` until the first load. */
+  readonly sections: Partial<LoadedSections<B, N>> | undefined;
+  /** The record's title, counts and unread state, with `summary`. */
+  readonly summary: RecordSummary | undefined;
+  readonly status: SubscriptionStatus;
+  /** The error of the last summary load. */
+  readonly error: DbError | undefined;
+}
+interface RecordActions<N extends string> {
+  /** Loads the named sections again, or every section and the summary. */
+  readonly refresh: (names?: readonly N[]) => Promise<void>;
+}
+type RecordController<B extends SectionBlocks, N extends string> = Controller<RecordSnapshot<B, N>, RecordActions<N>>;
+/**
+ * One record page's sections for the signed-in user over one realtime
+ * subscription (ADR 0030): it loads them with `loadSections`, and loads a
+ * section again when `topic` carries one of its events.
+ */
+export declare function createRecordController<B extends SectionBlocks, const N extends SectionName<B>>(options: RecordControllerOptions<B, N>): RecordController<B, N>;
+//#endregion
+//#region src/records/my-work.d.ts
+/** What `loadMyWork` returns: the items, grouped by kind, and their counts. */
+interface MyWork {
+  /** Every item, newest first. */
+  readonly items: readonly MyWorkItem[];
+  /** The items of each kind, newest first; an empty list for a kind with none. */
+  readonly groups: Readonly<Record<MyWorkKind, readonly MyWorkItem[]>>;
+  /** How many items of each kind the page holds, for tab badges. */
+  readonly counts: Readonly<Record<MyWorkKind, number>>;
+}
+interface LoadMyWorkOptions extends MyWorkOptions {
+  /** Only these kinds, such as `["assigned", "approval"]`. Default: all. */
+  readonly kinds?: readonly MyWorkKind[];
+}
+/**
+ * The caller's "My work" page: `my_work` across the installed blocks, grouped
+ * by kind with a count each, in one round trip.
+ *
+ * ```ts
+ * const work = await loadMyWork(blocks.subjects, {
+ *   pageSize: 100,
+ * }).orThrow();
+ * work.groups.approval; // approvals the caller can decide
+ * ```
+ */
+export declare function loadMyWork(subjects: Pick<Subjects, "myWork">, options?: LoadMyWorkOptions): AsyncResult<MyWork>;
+//#endregion
+export { type AnySection, type AnySectionWrite, type EntityForm, type EntityFormCustomField, type EntityFormField, type EntityFormInput, type EntityFormOptions, type EntityFormResult, type EntityFormValues, type FeatureBlocks, type FeaturePermissions, type FeatureWriteInput, type FeatureWriteOutput, type LoadMyWorkOptions, type LoadSectionsOptions, type LoadTimelineOptions, type LoadedSections, type MyWork, type MyWorkItem, type MyWorkKind, type MyWorkOptions, type PermissionFlags, type PermissionSet, type Plain, type PlainSection, type PlainSections, type RecordActions, type RecordCan, type RecordController, type RecordControllerOptions, type RecordFeature, type RecordFeatureSpec, type RecordList, type RecordListCell, type RecordListCells, type RecordListColumn, type RecordListPage, type RecordListQuery, type RecordListRow, type RecordListSource, type RecordListSpec, type RecordSnapshot, type RecordSummary, type RecordSummaryOptions, type RecordWriteInput, type Section, type SectionBlocks, type SectionCheck, type SectionData, type SectionDefinition, type SectionMap, type SectionName, type SectionNamed, type SectionOptions, type SectionPermissions, type SectionResult, type SectionRowInput, type SectionSource, type SectionWrite, type SectionWriteInput, type SectionWriteName, type SectionWriteOutput, type SectionWrites, type SectionWritesOf, type Timeline, type TimelineEntry, type TimelineItem, can, countSection, defineRecordFeature, defineRecordList, defineSection, entityForm, findSectionWrite, loadSections, loadTimeline, permissionFlags, plainData, recordCan, recordPermissionKeys, recordSubject, recordWriteInput, sectionCan, sectionEventMatches, sectionRowInput, sectionWrite, timelineSections };