better-supabase 0.12.0 → 0.13.0

package/dist/client-BU5Yd0yO.d.ts

@@ -0,0 +1,103 @@
+import { p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+import { n as TopicPort } from "./watch-topic-CloXeDTO.js";
+import { l as StoragePort } from "./ports-n3ZWSS_I.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+//#region src/blocks/inbox/client.d.ts
+/** Loads one list, e.g. a server action that calls `inbox.conversations.list()`. */
+type InboxSource<T> = () => Promise<readonly T[]>;
+interface InboxListSnapshot<T> {
+  /** `undefined` until the first load. */
+  readonly items: readonly T[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: unknown;
+}
+interface InboxListActions {
+  readonly refresh: () => Promise<void>;
+}
+interface Ports {
+  readonly topic: TopicPort;
+}
+interface InboxControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports;
+  /** The organization; the controller joins `inbox:org:<id>`. `null` waits. */
+  readonly organizationId: string | null;
+  readonly load: InboxSource<T>;
+  /**
+   * `blockConfig.inbox.options.topic` from `blocks.generated.ts`. Defaults to
+   * `inbox`.
+   */
+  readonly topic?: string;
+  /** Runs for each broadcast, e.g. to show a toast for `message`. */
+  readonly onMessage?: (event: string, payload: unknown) => void;
+}
+type InboxController<T> = Controller<InboxListSnapshot<T>, InboxListActions>;
+/**
+ * The staff view of an organization's conversations, kept current: loads, then
+ * loads again after each ping on `inbox:org:<id>` and on rejoin.
+ */
+declare function createInboxController<T>(options: InboxControllerOptions<T>): InboxController<T>;
+interface ConversationSnapshot<T> extends InboxListSnapshot<T> {
+  /** User ids typing now, the caller left out. */
+  readonly typing: readonly string[];
+}
+interface ConversationActions extends InboxListActions {
+  /** Tells the others the caller is typing; call it on input, throttled. */
+  readonly setTyping: (typing: boolean) => void;
+}
+interface ConversationControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports;
+  /** `null` waits, e.g. before the widget opens a conversation. */
+  readonly conversationId: string | null;
+  /** The messages, oldest first. */
+  readonly load: InboxSource<T>;
+  readonly topic?: string;
+  /** How long a typing ping counts. Defaults to 5000 ms. */
+  readonly typingMs?: number;
+}
+type ConversationController<T> = Controller<ConversationSnapshot<T>, ConversationActions>;
+/**
+ * One conversation's messages, kept current over `inbox:<id>`, with typing
+ * pings between staff and the contact. Notes never reach this topic.
+ */
+declare function createConversationController<T>(options: ConversationControllerOptions<T>): ConversationController<T>;
+interface InboxWidgetControllerOptions<T> {
+  readonly auth: AuthPort;
+  readonly ports: Ports & {
+    readonly storage?: StoragePort;
+  };
+  /**
+   * Opens the visitor's conversation, e.g. a server action that calls
+   * `inbox.conversations.open(inboxId, { message })` with the visitor's
+   * transport. Returns its id.
+   */
+  readonly open: (message: string) => Promise<string>;
+  /** Sends into the open conversation. */
+  readonly send: (conversationId: string, message: string) => Promise<void>;
+  readonly load: (conversationId: string) => Promise<readonly T[]>;
+  /**
+   * Remembers the conversation across reloads in the storage port. Defaults to
+   * `better-supabase:inbox-widget`; `null` forgets it.
+   */
+  readonly storageKey?: string | null;
+  readonly topic?: string;
+}
+interface InboxWidgetSnapshot<T> extends ConversationSnapshot<T> {
+  readonly conversationId: string | null;
+}
+interface InboxWidgetActions extends ConversationActions {
+  /** Opens the conversation with the first message, or sends into it. */
+  readonly submit: (message: string) => Promise<void>;
+  /** Forgets the conversation, so the next message opens a new one. */
+  readonly reset: () => void;
+}
+type InboxWidgetController<T> = Controller<InboxWidgetSnapshot<T>, InboxWidgetActions>;
+/**
+ * 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.
+ */
+declare function createInboxWidgetController<T>(options: InboxWidgetControllerOptions<T>): InboxWidgetController<T>;
+//#endregion
+export { InboxController as a, InboxListSnapshot as c, InboxWidgetController as d, InboxWidgetControllerOptions as f, createInboxWidgetController as g, createInboxController as h, ConversationSnapshot as i, InboxSource as l, createConversationController as m, ConversationController as n, InboxControllerOptions as o, InboxWidgetSnapshot as p, ConversationControllerOptions as r, InboxListActions as s, ConversationActions as t, InboxWidgetActions as u };

package/dist/client-Bb_Pj9wL.js

@@ -0,0 +1,137 @@
+import { n as dbError } from "./errors-D7u24ZJH.js";
+import { r as err } from "./result-DIT_qp4G.js";
+import { n as isRecord, t as isList } from "./guards-6F2bCtQR.js";
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+//#region src/blocks/settings/client.ts
+const isConverter = (value) => isRecord(value) && typeof value["input"] === "function";
+const jsonSchemaOf = (entry) => {
+	const standard = entry.schema["~standard"];
+	const converter = isRecord(standard) ? standard["jsonSchema"] : void 0;
+	if (!isConverter(converter)) return;
+	try {
+		const converted = converter.input({ target: "draft-2020-12" });
+		return isRecord(converted) ? converted : void 0;
+	} catch {
+		return;
+	}
+};
+const kindOfValue = (value) => typeof value === "boolean" ? "boolean" : typeof value === "number" ? "number" : typeof value === "string" ? "text" : "json";
+const text = (value) => typeof value === "string" ? value : void 0;
+function fieldOf(key, entry) {
+	const schema = jsonSchemaOf(entry);
+	const values = schema?.["enum"];
+	const choices = isList(values) ? values.filter((value) => typeof value === "string" || typeof value === "number") : [];
+	const type = schema?.["type"];
+	return {
+		key,
+		kind: choices.length > 0 ? "choice" : type === "boolean" ? "boolean" : type === "number" || type === "integer" ? "number" : type === "string" ? "text" : type === void 0 ? kindOfValue(entry.default) : "json",
+		choices,
+		title: text(schema?.["title"]),
+		description: text(schema?.["description"]),
+		default: entry.default
+	};
+}
+/**
+* The form fields of one scope of a settings definition, in declaration order:
+* `settingFields(settings.schemas.organization)`.
+*/
+function settingFields(entries) {
+	const fields = [];
+	for (const key of Object.keys(entries)) {
+		const entry = entries[key];
+		if (!entry) continue;
+		fields.push(fieldOf(key, entry));
+	}
+	return fields;
+}
+function storeOf(options) {
+	const { user, organization } = options;
+	if (user) return {
+		get: () => user.getUser(),
+		set: (key, value) => user.setUser(key, value),
+		reset: (key) => user.resetUser(key)
+	};
+	if (!organization) throw new TypeError("better-supabase: createSettingsController needs `user` or `organization`");
+	const organizationId = options.organizationId ?? null;
+	if (organizationId === null) return;
+	return {
+		get: () => organization.getOrganization(organizationId),
+		set: (key, value) => organization.setOrganization(organizationId, key, value),
+		reset: (key) => organization.resetOrganization(organizationId, key)
+	};
+}
+/**
+* One scope of the app's settings for a settings page: the form fields
+* generated from the definition, the stored values over the defaults, and `set`
+* and `reset` per key.
+*/
+function createSettingsController(options) {
+	const store = storeOf(options);
+	return defineController({
+		fields: settingFields(options.entries),
+		values: void 0,
+		saving: void 0,
+		error: void 0
+	}, (state) => {
+		const refresh = async () => {
+			if (!store) return;
+			const run = state.run();
+			const result = await store.get();
+			if (run !== state.run()) return;
+			state.set(result.ok ? {
+				values: result.data,
+				error: void 0
+			} : { error: result.error });
+		};
+		const waiting = () => err(dbError("invalid_input", "No organization to save the setting for"));
+		const set = async (key, value) => {
+			if (!store) return waiting();
+			state.set({
+				saving: key,
+				error: void 0
+			});
+			const result = await store.set(key, value);
+			if (!result.ok) {
+				state.set({
+					saving: void 0,
+					error: result.error
+				});
+				return result;
+			}
+			state.set((current) => ({
+				saving: void 0,
+				...current.values === void 0 ? {} : { values: {
+					...current.values,
+					[key]: result.data
+				} }
+			}));
+			return result;
+		};
+		return {
+			actions: {
+				refresh,
+				set,
+				setField: (key, value) => set(key, value),
+				reset: async (key) => {
+					if (!store) return waiting();
+					state.set({
+						saving: key,
+						error: void 0
+					});
+					const result = await store.reset(key);
+					state.set(result.ok ? { saving: void 0 } : {
+						saving: void 0,
+						error: result.error
+					});
+					if (result.ok) await refresh();
+					return result;
+				}
+			},
+			start: () => store ? whileSignedIn(options.auth, () => {
+				refresh();
+			}) : void 0
+		};
+	});
+}
+//#endregion
+export { settingFields as n, createSettingsController as t };

package/dist/client-BkH-Vh3s.d.ts

@@ -0,0 +1,112 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, t as AsyncResult } from "./result-mijqfoJN.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as BlockTransport } from "./block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "./block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "./block-hooks-BadAniNI.js";
+import { p as SubscriptionStatus } from "./topic-CZvLXFND.js";
+import { n as TopicPort } from "./watch-topic-CloXeDTO.js";
+import { n as Controller, t as AuthPort } from "./controller-lWRcKqCl.js";
+//#region src/blocks/reactions/reactions.d.ts
+interface ReactionsOptions extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: BlockHooks<Reactions>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+}
+/** One emoji on a subject. */
+interface ReactionCount {
+  /** The emoji, or a custom emoji's `:shortcode:`. */
+  readonly emoji: string;
+  readonly count: number;
+  /** Whether the signed-in user reacted with it. */
+  readonly reacted: boolean;
+  /** The first ten actors (user ids, or names the service passed), oldest first. */
+  readonly actors: readonly string[];
+}
+interface CustomEmoji {
+  readonly id: string;
+  /** Without the colons: `party-parrot` is used as `:party-parrot:`. */
+  readonly shortcode: string;
+  /** An attachment from the `attachments` module. */
+  readonly attachmentId?: string;
+  /** An `https://` image URL. */
+  readonly url?: string;
+  readonly createdAt: Temporal.Instant;
+}
+interface CustomEmojiInput {
+  readonly shortcode: string;
+  readonly attachmentId?: string;
+  readonly url?: string;
+}
+interface ReactOptions {
+  /** `false` removes the reaction. Default: `true`. */
+  readonly present?: boolean;
+  /** The service role reacts for this actor (default `service`). */
+  readonly actor?: string;
+}
+interface Reactions {
+  /** Adds or removes the caller's reaction; returns the subject's reactions. */
+  react(organizationId: string, subjectType: string, subjectId: string, emoji: string, options?: ReactOptions): AsyncResult<readonly ReactionCount[]>;
+  /** The reactions of up to 200 subjects of one type, by subject id. */
+  summary(organizationId: string, subjectType: string, subjectIds: readonly string[]): AsyncResult<Readonly<Record<string, readonly ReactionCount[]>>>;
+  /** The organization's custom emoji, by shortcode. */
+  customEmoji(organizationId: string): AsyncResult<readonly CustomEmoji[]>;
+  /** Adds a custom emoji, or replaces the image of an existing shortcode. */
+  saveCustomEmoji(organizationId: string, input: CustomEmojiInput): AsyncResult<CustomEmoji>;
+  /** Deletes a custom emoji and the reactions that used it. */
+  deleteCustomEmoji(id: string): AsyncResult<boolean>;
+}
+/** The topic the module broadcasts an organization's reaction changes to. */
+declare function reactionsTopic(organizationId: string, topic?: string): string;
+/** The `reactions` SQL module as typed calls. */
+declare function createReactions(options: ReactionsOptions): Reactions;
+//#endregion
+//#region src/blocks/reactions/client.d.ts
+interface ReactionsControllerOptions {
+  readonly client: Pick<Reactions, "summary" | "react">;
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  readonly organizationId: string;
+  readonly subjectType: string;
+  /** The subjects on screen, at most 200; `setSubjects` changes them. */
+  readonly subjectIds: readonly string[];
+  /**
+   * `blockConfig.reactions.options.topic` from `blocks.generated.ts`; `null`
+   * loads without listening.
+   */
+  readonly topic?: string | null;
+}
+interface ReactionsSnapshot {
+  /** Reactions by subject id; `undefined` until the first load. */
+  readonly reactions: Readonly<Record<string, readonly ReactionCount[]>> | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: DbError | undefined;
+}
+interface ReactionsActions {
+  /** Adds the emoji, or removes it when the user already reacted with it. */
+  readonly toggle: (subjectId: string, emoji: string) => Promise<void>;
+  readonly refresh: () => Promise<void>;
+  /**
+   * Watches other subjects, such as the rows on screen after a scroll, and
+   * loads them.
+   */
+  readonly setSubjects: (subjectIds: readonly string[]) => void;
+}
+type ReactionsController = Controller<ReactionsSnapshot, ReactionsActions>;
+/**
+ * The reactions of the subjects on screen, loaded again when anyone in the
+ * organization reacts to one of them. `toggle` feeds an emoji picker.
+ */
+declare function createReactionsController(options: ReactionsControllerOptions): ReactionsController;
+//#endregion
+export { createReactionsController as a, ReactOptions as c, ReactionsOptions as d, createReactions as f, ReactionsSnapshot as i, ReactionCount as l, ReactionsController as n, CustomEmoji as o, reactionsTopic as p, ReactionsControllerOptions as r, CustomEmojiInput as s, ReactionsActions as t, Reactions as u };

package/dist/client-BsfsRHae.d.ts

@@ -0,0 +1,136 @@
+import { D as ValidationIssue } from "./result-mijqfoJN.js";
+import { n as Controller } from "./controller-lWRcKqCl.js";
+import { a as FormDefinition, c as FormJson, d as FormStep, i as FormCondition, l as FormJsonSchema, o as FormField } from "./form-definition-DcVnFzl4.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/blocks/forms/validate.d.ts
+/** A submission's answers, by field key. */
+type FormAnswers = {
+  readonly [key: string]: FormJson;
+};
+/**
+ * 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.
+ */
+declare function validateAnswers(schema: FormJsonSchema, answers: unknown): readonly ValidationIssue[];
+/** A form version's schema as a Standard Schema, for form libraries. */
+declare function answersSchema(schema: FormJsonSchema): StandardSchemaV1<unknown, FormAnswers>;
+//#endregion
+//#region src/blocks/forms/questionnaire.d.ts
+/**
+ * Whether `condition` holds for `answers`, with the semantics of its JSON
+ * Schema `if`.
+ */
+declare function conditionHolds(condition: FormCondition | undefined, answers: FormAnswers): boolean;
+/** The steps whose `showIf` holds. */
+declare function visibleSteps(definition: FormDefinition, answers: FormAnswers): readonly FormStep[];
+/** The step's fields whose `showIf` holds. */
+declare function visibleFields(step: FormStep, answers: FormAnswers): readonly FormField[];
+/**
+ * The answers without the ones for hidden steps and fields. Removing an answer
+ * can hide a later field, so it repeats until nothing changes.
+ */
+declare function pruneAnswers(definition: FormDefinition, answers: FormAnswers): FormAnswers;
+/** The schema's issues for the fields `step` shows. */
+declare function stepIssues(schema: FormJsonSchema, step: FormStep, answers: FormAnswers): readonly ValidationIssue[];
+interface QuestionnaireState {
+  /** The step on screen, by key. */
+  readonly step: string;
+  readonly answers: FormAnswers;
+  /** The steps that passed their checks on `next`. */
+  readonly completed: readonly string[];
+  /** The issues of the step on screen after a `next` or `submit` that failed. */
+  readonly issues: readonly ValidationIssue[];
+}
+type QuestionnaireAction = {
+  readonly type: "answer";
+  readonly key: string;
+  readonly value: FormJson | undefined;
+} | {
+  readonly type: "next";
+} | {
+  readonly type: "back";
+} | {
+  readonly type: "goTo";
+  readonly step: string;
+} | {
+  readonly type: "reset";
+  readonly answers?: FormAnswers;
+};
+interface QuestionnaireForm {
+  readonly definition: FormDefinition;
+  /** The version's generated schema. */
+  readonly schema: FormJsonSchema;
+}
+/** The state before the first answer. */
+declare function initialQuestionnaire(form: QuestionnaireForm, answers?: FormAnswers): QuestionnaireState;
+/**
+ * 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.
+ */
+declare function questionnaireReducer(form: QuestionnaireForm, state: QuestionnaireState, action: QuestionnaireAction): QuestionnaireState;
+interface QuestionnaireStepView {
+  readonly key: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly fields: readonly FormField[];
+  readonly completed: boolean;
+  readonly active: boolean;
+}
+/** The visible steps with their status, in the shape a Stepper renders. */
+declare function questionnaireSteps(form: QuestionnaireForm, state: QuestionnaireState): readonly QuestionnaireStepView[];
+/** The pruned answers, or every issue when the whole form does not pass. */
+declare function finishQuestionnaire(form: QuestionnaireForm, state: QuestionnaireState): {
+  readonly ok: true;
+  readonly answers: FormAnswers;
+} | {
+  readonly ok: false;
+  readonly issues: readonly ValidationIssue[];
+};
+//#endregion
+//#region src/blocks/forms/client.d.ts
+interface QuestionnaireOptions {
+  /** A form version, or anything with its `definition` and `schema`. */
+  readonly form: QuestionnaireForm;
+  /** Answers to start from, such as a saved draft. */
+  readonly initialAnswers?: FormAnswers;
+  /** Receives the answers of the visible fields once the whole form passes. */
+  readonly onSubmit: (answers: FormAnswers) => Promise<void> | void;
+}
+interface QuestionnaireSnapshot {
+  /** The visible steps, for a Stepper's items. */
+  readonly steps: readonly QuestionnaireStepView[];
+  /** The step on screen. */
+  readonly step: QuestionnaireStepView | undefined;
+  readonly answers: FormAnswers;
+  /**
+   * Issues by field key: the step on screen's after `next`, every field's after
+   * a failed `submit`.
+   */
+  readonly issues: Readonly<Record<string, readonly string[]>>;
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+  readonly submitting: boolean;
+}
+interface QuestionnaireActions {
+  /** `undefined` removes the answer. */
+  readonly setAnswer: (key: string, value: FormJson | undefined) => void;
+  /** Checks the step and moves to the next visible one. */
+  readonly next: () => void;
+  readonly back: () => void;
+  /** Moves to a step whose earlier steps are done, for a clickable Stepper. */
+  readonly goTo: (step: string) => void;
+  /** Checks the whole form, then calls `onSubmit`. Returns whether it passed. */
+  readonly submit: () => Promise<boolean>;
+  readonly reset: (answers?: FormAnswers) => void;
+}
+type QuestionnaireController = Controller<QuestionnaireSnapshot, QuestionnaireActions>;
+/**
+ * A multi-step form over a form version: the visible steps, the answers, and
+ * per-field issues checked against the version's JSON Schema.
+ */
+declare function createQuestionnaireController(options: QuestionnaireOptions): QuestionnaireController;
+//#endregion
+export { visibleFields as _, createQuestionnaireController as a, answersSchema as b, QuestionnaireState as c, finishQuestionnaire as d, initialQuestionnaire as f, stepIssues as g, questionnaireSteps as h, QuestionnaireSnapshot as i, QuestionnaireStepView as l, questionnaireReducer as m, QuestionnaireController as n, QuestionnaireAction as o, pruneAnswers as p, QuestionnaireOptions as r, QuestionnaireForm as s, QuestionnaireActions as t, conditionHolds as u, visibleSteps as v, validateAnswers as x, FormAnswers as y };