better-supabase 0.12.0 → 0.13.0

package/dist/client-Dsuy9wfA.d.ts

@@ -0,0 +1,59 @@
+import { b as DbError } from "./result-mijqfoJN.js";
+import { p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+import { n as TopicPort } from "./watch-topic-CloXeDTO.js";
+import { g as Workflows, n as WorkflowRun } from "./workflows-BHyYAR6c.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+import { O as WorkflowStepInfo, T as WorkflowNodeRun, _ as WorkflowBuilder, b as WorkflowDefinition } from "./types-vVsLvOUJ.js";
+//#region src/blocks/workflow-builder/client.d.ts
+interface WorkflowBuilderControllerOptions {
+  readonly client: {
+    readonly definitions: Pick<WorkflowBuilder["definitions"], "list">;
+    readonly steps: Pick<WorkflowBuilder["steps"], "list">;
+  };
+  readonly auth: AuthPort;
+  /** The tenant whose definitions to list. */
+  readonly tenant?: string | null;
+}
+interface WorkflowBuilderSnapshot {
+  /** `undefined` until the first load. */
+  readonly definitions: readonly WorkflowDefinition[] | undefined;
+  /** The step library, the canvas's palette. */
+  readonly steps: readonly WorkflowStepInfo[] | undefined;
+  readonly error: DbError | undefined;
+}
+interface WorkflowBuilderActions {
+  readonly refresh: () => Promise<void>;
+}
+type WorkflowBuilderController = Controller<WorkflowBuilderSnapshot, WorkflowBuilderActions>;
+/** The definitions the signed-in user may read and the step library. */
+declare function createWorkflowBuilderController(options: WorkflowBuilderControllerOptions): WorkflowBuilderController;
+interface WorkflowCanvasRunControllerOptions {
+  readonly client: {
+    readonly runs: Pick<Workflows["runs"], "get">;
+    readonly nodeRuns: Pick<WorkflowBuilder["nodeRuns"], "list">;
+  };
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The run's id or its engine's id; `null` waits. */
+  readonly run: string | null;
+}
+interface WorkflowCanvasRunSnapshot {
+  readonly run: WorkflowRun | undefined;
+  /** Each node's status by node id, for the canvas overlay. */
+  readonly nodes: Readonly<Record<string, WorkflowNodeRun>>;
+  readonly error: DbError | undefined;
+  readonly status: SubscriptionStatus;
+}
+interface WorkflowCanvasRunActions {
+  readonly refresh: () => Promise<void>;
+}
+type WorkflowCanvasRunController = Controller<WorkflowCanvasRunSnapshot, WorkflowCanvasRunActions>;
+/**
+ * A run and the status of each of its nodes, loaded again on each message on
+ * `workflow-run:<id>` (run status changes and node records).
+ */
+declare function createWorkflowCanvasRunController(options: WorkflowCanvasRunControllerOptions): WorkflowCanvasRunController;
+//#endregion
+export { WorkflowCanvasRunActions as a, WorkflowCanvasRunSnapshot as c, WorkflowBuilderSnapshot as i, createWorkflowBuilderController as l, WorkflowBuilderController as n, WorkflowCanvasRunController as o, WorkflowBuilderControllerOptions as r, WorkflowCanvasRunControllerOptions as s, WorkflowBuilderActions as t, createWorkflowCanvasRunController as u };

package/dist/client-EQvEzUQg.d.ts

@@ -0,0 +1,276 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "./result-mijqfoJN.js";
+import { t as StandardSchemaV1 } from "./standard-16AIDny5.js";
+import { n as ExtraFields, r as FieldsOf } from "./block-fields-DnXkMney.js";
+import { B as TableKey, a as AnyModels, i as AnyFunctions } from "./types-DmshMaXz.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { i as EventSink, t as CloudEvent } from "./cloud-event-CidL9jiw.js";
+import { t as BetterSupabase } from "./define-D0LSXmUP.js";
+import { p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+import { n as TopicPort } from "./watch-topic-CloXeDTO.js";
+import { i as ListDefinition } from "./list-query-Dx5cAqG6.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+//#region src/blocks/comments/comments.d.ts
+interface CommentsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the comment's extra columns
+   * (`blocks.comments.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `create` and `edit`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Comments<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  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[];
+  /**
+   * The user ids a comment mentions when the call passes no `mentions`, such as
+   * the mention nodes of a rich-text `document`. Default `mentionsIn(body)`.
+   */
+  readonly mentionsOf?: (comment: {
+    readonly body: string;
+    readonly document: unknown;
+  }) => readonly string[];
+}
+/** A comment. `F` types the extra columns the `fields` schema describes. */
+interface Comment<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** `undefined` once the author's account is deleted. */
+  readonly authorId: string | undefined;
+  /** Empty for a deleted comment. */
+  readonly body: string;
+  /** The rich-text document an editor wrote, next to `body` as its plain text. */
+  readonly document: unknown;
+  readonly mentions: readonly string[];
+  readonly parentId: string | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly editedAt: Temporal.Instant | undefined;
+  readonly deletedAt: Temporal.Instant | undefined;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface NewComment<F extends object = Record<never, never>> {
+  readonly organizationId: string;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  readonly body: string;
+  /** A rich-text document (any JSON); keep `body` as its plain text. */
+  readonly document?: unknown;
+  /** User ids; default `mentionsOf`, or the ids `mentionsIn(body)` finds. */
+  readonly mentions?: readonly string[];
+  /** A reply: the parent must be on the same subject. */
+  readonly parentId?: string;
+  /** The extra columns to set, keyed by database name. */
+  readonly fields?: Partial<F>;
+}
+interface CommentEdit<F extends object = Record<never, never>> {
+  readonly body: string;
+  /**
+   * A new document; `null` removes it, and leaving it out keeps the current
+   * one.
+   */
+  readonly document?: unknown;
+  /** Default `mentionsOf`, or the ids `mentionsIn(body)` finds. */
+  readonly mentions?: readonly string[];
+  /** The extra columns to set, keyed by database name; others keep their value. */
+  readonly fields?: Partial<F>;
+}
+/**
+ * Where a timeline entry comes from: `event` for an `activity_entries` row that
+ * `activitySink()` wrote, `audit` for an audit log entry on the subject's row
+ * (with the `audit` and `subjects` modules), `delivery` for a notification
+ * delivery about the subject (with `notifications`) and `run` for a workflow
+ * run on it (with `workflows`).
+ */
+type ActivitySource = "event" | "audit" | "delivery" | "run";
+interface ActivityEntry {
+  /** An `activity_entries` id, or the audit entry's, delivery's or run's id. */
+  readonly id: string;
+  readonly source: ActivitySource;
+  readonly organizationId: string;
+  readonly type: string;
+  readonly actorId: string | undefined;
+  readonly subjectType: string | undefined;
+  readonly subjectId: string | undefined;
+  readonly summary: string | undefined;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly occurredAt: Temporal.Instant;
+}
+interface ActivityHistoryOptions extends CursorPageOptions<Temporal.Instant> {
+  /** Entries before this instant, for paging back. */
+  readonly cursor?: Temporal.Instant;
+  /** Default 50, at most 500. */
+  readonly limit?: number;
+  /** The kinds of entry to return; all of them when left out. */
+  readonly sources?: readonly ActivitySource[];
+}
+interface ListCommentsOptions extends CursorPageOptions<Temporal.Instant> {
+  /** Comments created after this instant, for polling a thread. */
+  readonly cursor?: Temporal.Instant;
+  /**
+   * The id of the last comment you have, next to `cursor`, so comments created
+   * in the same instant as it aren't skipped.
+   */
+  readonly cursorId?: string;
+  /** Default 100, at most 500. */
+  readonly limit?: number;
+  /** Comments to skip, for page-number paging. */
+  readonly offset?: number;
+}
+/** `F` is the extra fields `options.fields` describes. */
+interface Comments<F extends object = Record<never, never>> {
+  create(comment: NewComment<F>): AsyncResult<Comment<F>>;
+  /** Only the author edits; `not_found` when the caller can't see it. */
+  edit(id: string, edit: CommentEdit<F>): AsyncResult<Comment<F>>;
+  /** Soft-deletes (the author, or a member with `comments.moderate`). */
+  remove(id: string): AsyncResult<boolean>;
+  /** A subject's thread, oldest first, deleted comments as placeholders. */
+  list(organizationId: string, subjectType: string, subjectId: string, options?: ListCommentsOptions): AsyncResult<readonly Comment<F>[]>;
+  /**
+   * How many comments each subject has that the caller can read, deleted ones
+   * left out, such as for a counter on each row of a list. Subjects without
+   * comments are 0.
+   */
+  counts(organizationId: string, subjectType: string, subjectIds: readonly string[]): AsyncResult<Readonly<Record<string, number>>>;
+  /**
+   * Copies a subject's thread to another subject in the tenant, keeping
+   * authors, times and replies; returns how many comments it copied. Needs a
+   * service-role transport.
+   */
+  copy(organizationId: string, from: {
+    readonly type: string;
+    readonly id: string;
+  }, to: {
+    readonly type: string;
+    readonly id: string;
+  }): AsyncResult<number>;
+  /**
+   * The activity feed of a tenant, newest first, or one subject's timeline with
+   * `subject`. Members with `activity.read` see it. With the `subjects` module,
+   * an entry on a registered subject type needs `can_subject` read, and a
+   * subject's timeline also lists its audit log entries (`source: "audit"`)
+   * when `audit` is installed with its read policy, the deliveries of
+   * notifications about it (`source: "delivery"`, for members who also hold
+   * `notifications.send`) and its workflow runs (`source: "run"`, as the runs'
+   * read policy allows).
+   */
+  history(organizationId: string, subject?: {
+    readonly type: string;
+    readonly id: string;
+  }, options?: ActivityHistoryOptions): AsyncResult<readonly ActivityEntry[]>;
+}
+/**
+ * The user ids mentioned in a body written as `@[Ada](<user id>)`, the markup
+ * mention inputs produce, in order and without repeats.
+ */
+declare function mentionsIn(body: string): readonly string[];
+/** Comments over the `comments` module's functions, as the caller. */
+declare function createComments<S extends StandardSchemaV1 | undefined = undefined>(options: CommentsOptions<S>): Comments<FieldsOf<S>>;
+/** What an activity entry says about an event; `null` skips the event. */
+interface ActivityDescription {
+  readonly summary?: string;
+  readonly actorId?: string;
+  readonly subjectType?: string;
+  readonly subjectId?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+}
+interface ActivitySinkOptions {
+  /**
+   * A service-role transport: `record_activity()` is granted to `service_role`
+   * only.
+   */
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  /**
+   * The outbox `typePrefix`, stripped from the stored type. Default
+   * `dev.better-supabase`.
+   */
+  readonly typePrefix?: string;
+  /** Types to keep, exact or ending in `.*`. Default every event with a tenant. */
+  readonly types?: readonly string[];
+  /** Summarizes an event, or returns `null` to skip it. */
+  readonly describe?: (event: CloudEvent, type: string) => ActivityDescription | null | undefined;
+}
+/**
+ * An outbox sink that writes events into the activity feed:
+ * `outbox.relay('activity', activitySink({ transport }))`. Events without a
+ * tenant (`partitionkey`) are skipped, and a replayed event writes nothing.
+ */
+declare function activitySink(options: ActivitySinkOptions): EventSink;
+type ActivitySort = "newest" | "oldest";
+type ActivityFacet = "type" | "actor" | "subjectType" | "subjectId";
+/**
+ * A cursor-paged list over `activity_entries` (generate types for the
+ * `better_supabase` schema to get it in your models), newest first, filtered by
+ * type, actor and subject. Members with `activity.read` see their tenants'
+ * entries, less those on a registered subject that `can_subject` doesn't let
+ * them read (with the `subjects` module). It reads the table, so it lists no
+ * audit entries; `history()` does.
+ */
+declare function activityListQuery<M extends AnyModels, D, Fn extends AnyFunctions, E, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, Fn, E>, table: T, options?: {
+  readonly pageSize?: number;
+  readonly maxPageSize?: number;
+}): ListDefinition<M, T, E, ActivitySort, ActivityFacet>;
+//#endregion
+//#region src/blocks/comments/client.d.ts
+interface CommentsControllerOptions {
+  readonly client: Pick<Comments, "list" | "create" | "edit" | "remove">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The organization; the thread waits without one. */
+  readonly organizationId: string | null;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /**
+   * A private topic that hears of new comments on the subject, such as a
+   * `realtime-tables` topic on the comments table. Each message loads the
+   * thread again. Default `null`: the thread loads again after its own writes
+   * only.
+   */
+  readonly topic?: string | null;
+  /** The most comments to load, default 100, at most 500. */
+  readonly limit?: number;
+}
+interface CommentsSnapshot {
+  /**
+   * The thread, oldest first, deleted comments as placeholders; `undefined`
+   * until the first load.
+   */
+  readonly comments: readonly Comment[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+/** A reply, a rich-text document or explicit mentions for `add`. */
+type CommentDraft = Pick<NewComment, "document" | "mentions" | "parentId">;
+interface CommentsActions {
+  /** Posts a comment on the subject; a failure is also kept in `error`. */
+  readonly add: (body: string, draft?: CommentDraft) => Promise<Result<Comment>>;
+  /** Edits one of the caller's comments. */
+  readonly edit: (id: string, edit: CommentEdit) => Promise<Result<Comment>>;
+  /** Soft-deletes a comment: it stays in the thread as a placeholder. */
+  readonly remove: (id: string) => Promise<Result<boolean>>;
+  readonly refresh: () => Promise<void>;
+}
+type CommentsController = Controller<CommentsSnapshot, CommentsActions>;
+/**
+ * One subject's comment thread for the signed-in user: loads it, keeps it
+ * current after `add`, `edit` and `remove`, and loads it again for each message
+ * on `topic`.
+ */
+declare function createCommentsController(options: CommentsControllerOptions): CommentsController;
+//#endregion
+export { mentionsIn as C, createComments as S, CommentsOptions as _, CommentsSnapshot as a, activityListQuery as b, ActivityEntry as c, ActivitySinkOptions as d, ActivitySort as f, Comments as g, CommentEdit as h, CommentsControllerOptions as i, ActivityFacet as l, Comment as m, CommentsActions as n, createCommentsController as o, ActivitySource as p, CommentsController as r, ActivityDescription as s, CommentDraft as t, ActivityHistoryOptions as u, ListCommentsOptions as v, activitySink as x, NewComment as y };

package/dist/client-G7NGXZKe.d.ts

@@ -0,0 +1,43 @@
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+import { t as EntitlementClaimOptions } from "./entitlements-CMGsO4gL.js";
+//#region src/blocks/entitlements/client.d.ts
+interface FeatureGateControllerOptions {
+  readonly auth: AuthPort;
+  /** The plan feature, such as `exports`: a key of `entitlements.source.plans`. */
+  readonly feature: string;
+  /**
+   * The organization to check. Default the session's active one, from the
+   * tenant claim.
+   */
+  readonly organizationId?: string | null;
+  /**
+   * `config.claims.features` (default `features`), or `{ claim, keys }` for
+   * short codes.
+   */
+  readonly claim?: string | EntitlementClaimOptions;
+  /** The tenant claim, `config.claims.tenant` (default `tenant_id`). */
+  readonly tenantClaim?: string;
+}
+interface FeatureGateSnapshot {
+  /**
+   * `undefined` while the session loads; false when signed out or outside an
+   * organization.
+   */
+  readonly allowed: boolean | undefined;
+  /** The organization the check ran for. */
+  readonly organizationId: string | undefined;
+}
+interface FeatureGateActions {
+  /** Checks the session again, such as after a refresh the gate did not hear of. */
+  readonly recheck: () => void;
+}
+type FeatureGateController = Controller<FeatureGateSnapshot, FeatureGateActions>;
+/**
+ * Whether the active organization's plan includes `feature`, from the session's
+ * plan-features claim. It updates when the session does, so a session refresh
+ * after checkout opens the gate. UX only: enforce the feature in RLS with
+ * `better_supabase.has_entitlement()`.
+ */
+declare function createFeatureGateController(options: FeatureGateControllerOptions): FeatureGateController;
+//#endregion
+export { createFeatureGateController as a, FeatureGateSnapshot as i, FeatureGateController as n, FeatureGateControllerOptions as r, FeatureGateActions as t };

package/dist/client-OhTiAol1.js

@@ -0,0 +1,213 @@
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+//#region src/blocks/inbox/client.ts
+function loader(load, state) {
+	return async () => {
+		try {
+			state.set({
+				items: await load(),
+				error: void 0
+			});
+		} catch (cause) {
+			state.set({ error: cause });
+		}
+	};
+}
+/**
+* The staff view of an organization's conversations, kept current: loads, then
+* loads again after each ping on `inbox:org:<id>` and on rejoin.
+*/
+function createInboxController(options) {
+	const topic = options.organizationId === null ? null : `${options.topic ?? "inbox"}:org:${options.organizationId}`;
+	return defineController({
+		items: void 0,
+		status: "closed",
+		error: void 0
+	}, (state) => {
+		const refresh = loader(options.load, state);
+		return {
+			actions: { refresh },
+			start: () => {
+				if (topic === null) return;
+				return whileSignedIn(options.auth, () => {
+					refresh();
+					return options.ports.topic(topic, {
+						onMessage: (event, payload) => {
+							options.onMessage?.(event, payload);
+							refresh();
+						},
+						onRejoin: () => void refresh(),
+						onStatus: (status) => {
+							state.set({ status });
+						}
+					}).leave;
+				});
+			}
+		};
+	});
+}
+const NO_TYPERS = [];
+/**
+* One conversation's messages, kept current over `inbox:<id>`, with typing
+* pings between staff and the contact. Notes never reach this topic.
+*/
+function createConversationController(options) {
+	const typingMs = options.typingMs ?? 5e3;
+	const topic = options.conversationId === null ? null : `${options.topic ?? "inbox"}:${options.conversationId}`;
+	let joined;
+	return defineController({
+		items: void 0,
+		status: "closed",
+		error: void 0,
+		typing: NO_TYPERS
+	}, (state) => {
+		const refresh = loader(options.load, state);
+		const join = (name, userId) => {
+			const seen = /* @__PURE__ */ new Map();
+			const typer = (who, on) => {
+				const timer = seen.get(who);
+				if (timer !== void 0) clearTimeout(timer);
+				if (on) seen.set(who, setTimeout(() => {
+					typer(who, false);
+				}, typingMs));
+				else seen.delete(who);
+				state.set({ typing: [...seen.keys()] });
+			};
+			const handle = options.ports.topic(name, {
+				onMessage: (event, payload) => {
+					if (event !== "typing") {
+						refresh();
+						return;
+					}
+					if (typeof payload !== "object" || payload === null) return;
+					const who = "user_id" in payload ? String(payload.user_id) : "";
+					if (who !== "" && who !== userId) typer(who, !("typing" in payload) || payload.typing !== false);
+				},
+				onRejoin: () => void refresh(),
+				onStatus: (status) => {
+					state.set({ status });
+				}
+			});
+			joined = {
+				userId,
+				send: (on) => {
+					handle.send("typing", {
+						user_id: userId,
+						typing: on
+					});
+				}
+			};
+			return () => {
+				for (const timer of seen.values()) clearTimeout(timer);
+				joined = void 0;
+				handle.leave();
+				state.set({ typing: NO_TYPERS });
+			};
+		};
+		return {
+			actions: {
+				refresh,
+				setTyping: (on) => {
+					joined?.send(on);
+				}
+			},
+			start: () => {
+				if (topic === null) return;
+				return whileSignedIn(options.auth, (userId) => {
+					refresh();
+					return join(topic, userId);
+				});
+			}
+		};
+	});
+}
+/**
+* The visitor side of an in-app inbox: the first message opens the
+* conversation, later ones go into it, and the messages and typing pings stay
+* current. Visitors without an account sign in anonymously first.
+*/
+function createInboxWidgetController(options) {
+	const key = options.storageKey === void 0 ? "better-supabase:inbox-widget" : options.storageKey;
+	const storage = key === null ? void 0 : options.ports.storage;
+	let conversationId = null;
+	let restored = storage === void 0;
+	let active = false;
+	let inner;
+	let leaveInner;
+	return defineController({
+		items: void 0,
+		status: "closed",
+		error: void 0,
+		typing: NO_TYPERS,
+		conversationId: null
+	}, (state) => {
+		let show = () => void 0;
+		const attach = () => {
+			leaveInner?.();
+			leaveInner = active ? inner?.subscribe(show) : void 0;
+		};
+		const follow = () => {
+			const id = conversationId;
+			const current = createConversationController({
+				auth: options.auth,
+				ports: options.ports,
+				conversationId: id,
+				load: () => id === null ? Promise.resolve([]) : options.load(id),
+				...options.topic === void 0 ? {} : { topic: options.topic }
+			});
+			inner = current;
+			show = () => {
+				state.set({
+					...current.getSnapshot(),
+					conversationId: id
+				});
+			};
+			show();
+			attach();
+		};
+		const choose = (id) => {
+			if (id === conversationId) return;
+			conversationId = id;
+			follow();
+		};
+		follow();
+		return {
+			actions: {
+				refresh: () => inner?.actions.refresh() ?? Promise.resolve(),
+				setTyping: (on) => {
+					inner?.actions.setTyping(on);
+				},
+				submit: async (message) => {
+					if (conversationId === null) {
+						const id = await options.open(message);
+						if (key !== null) await storage?.set(key, id);
+						choose(id);
+						return;
+					}
+					await options.send(conversationId, message);
+					await inner?.actions.refresh();
+				},
+				reset: () => {
+					if (key !== null) storage?.remove(key);
+					choose(null);
+				}
+			},
+			start: () => {
+				active = true;
+				attach();
+				if (!restored && key !== null && storage) {
+					restored = true;
+					storage.get(key).then((stored) => {
+						if (stored !== null && conversationId === null) choose(stored);
+					});
+				}
+				return () => {
+					active = false;
+					leaveInner?.();
+					leaveInner = void 0;
+				};
+			}
+		};
+	});
+}
+//#endregion
+export { createInboxController as n, createInboxWidgetController as r, createConversationController as t };