better-supabase 0.8.0 → 0.9.0

package/dist/client-Cmensu7l.d.ts

@@ -0,0 +1,419 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, f as Result, t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { o as EventHub } from "./events-CTreRrgP.js";
+import { m as RequestContext } from "./plugin-CDLJRFFg.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as BlockTransport } from "./block-transport-DaGGXjIw.js";
+import { r as BlockTemporalOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { i as RowFields, r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+//#region src/sql/modules/invitations-tables.d.ts
+declare const INVITATION_ERRORS: {
+  readonly INVITATION_FORBIDDEN: "42501";
+  readonly INVITATION_ROLE_FORBIDDEN: "42501";
+  readonly INVITATION_ROLE_UNKNOWN: "23514";
+  readonly INVITATION_ALREADY_MEMBER: "23505";
+  readonly INVITATION_INVALID: "P0002";
+  readonly INVITATION_EXPIRED: "P0002";
+  readonly INVITATION_VALIDITY: "22023";
+  readonly INVITATION_SIGN_IN: "42501";
+  readonly INVITATION_EMAIL_MISMATCH: "42501";
+  readonly INVITATION_EMAIL_UNCONFIRMED: "42501";
+  readonly INVITATION_SELF: "42501";
+  readonly INVITATION_INVITER_REVOKED: "42501";
+  readonly INVITATION_SCOPE_UNSUPPORTED: "0A000";
+};
+type InvitationError = keyof typeof INVITATION_ERRORS;
+//#endregion
+//#region src/blocks/organizations/organizations.d.ts
+/**
+ * Organization columns by database name: `name`, `slug`, the columns in
+ * `blocks.organizations.options.attributes` and the ones
+ * `options.extraColumns` adds. Other keys are ignored.
+ */
+interface OrganizationAttributes {
+  readonly name?: string;
+  readonly slug?: string;
+  readonly [column: string]: unknown;
+}
+interface CreateOrganizationOptions {
+  /** The owner, when the transport runs as the service role. */
+  readonly ownerId?: string;
+}
+type SlugProblem = "invalid" | "reserved" | "taken";
+interface InviteRequest<I extends object = Record<never, never>> {
+  /** `null` invites to the platform (`blocks.access.model: 'catalog'`). */
+  readonly organizationId: string | null;
+  readonly email: string;
+  /** A role name, or a role id or key under the catalog model. */
+  readonly role: string;
+  /** A Postgres interval such as `'3 days'`. Defaults to `options.validFor`. */
+  readonly validFor?: string;
+  /** Profile fields to fill in on sign-up. */
+  readonly prefill?: Readonly<Record<string, unknown>>;
+  /**
+   * Values for the invitations table's extra columns
+   * (`blocks.invitations.options.extraColumns`), checked by
+   * `options.invitationFields`.
+   */
+  readonly fields?: Partial<I> & Readonly<Record<string, unknown>>;
+}
+/** An invitation. `I` types the extra columns `options.invitationFields` describes. */
+interface Invitation<I extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string | null;
+  readonly email: string;
+  readonly role: string;
+  readonly expiresAt: Temporal.Instant;
+  /** Absent when the invitations table has no `createdAt` column. */
+  readonly createdAt?: Temporal.Instant;
+  readonly invitedBy?: string;
+  /** The organization's id and `options.previewColumns`; `null` for a platform invitation. */
+  readonly organization: Readonly<Record<string, unknown>> | null;
+  readonly prefill: Readonly<Record<string, unknown>>;
+  /**
+   * The inviter's `id` and public profile fields (`username`, `fullName`,
+   * `firstName`, `lastName`, `avatar`, as the profiles module maps them).
+   * `null` without the profiles module, an `invitedBy` column or the
+   * inviter's profile.
+   */
+  readonly inviter: Readonly<Record<string, unknown>> | null;
+  /** The keys an `invitation_preview_extra` hook added, such as a role label. */
+  readonly extra: Readonly<Record<string, unknown>>;
+  /** The extra columns of an organization invitation, by column name. */
+  readonly fields: RowFields<I>;
+}
+/** What `updateInvitation` changes; a missing key keeps the current value. */
+interface InvitationChanges {
+  readonly email?: string;
+  /** A role name, or a role id or key under the catalog model. */
+  readonly role?: string;
+  /** Replaces the profile fields to fill in on sign-up. */
+  readonly prefill?: Readonly<Record<string, unknown>>;
+}
+/** What `onInvite` receives: the place to send the email. */
+interface InvitationSent<I extends object = Record<never, never>> {
+  readonly invitation: Invitation<I>;
+  /** Put it in the accept link. It is never stored in plain text by default. */
+  readonly token: string;
+  readonly resent: boolean;
+}
+type InvitationStatus = "pending" | "accepted" | "declined" | "revoked" | "expired";
+interface InvitationPreview {
+  readonly status: InvitationStatus;
+  readonly email: string;
+  readonly role: string;
+  readonly organizationId: string | null;
+  readonly expiresAt: Temporal.Instant;
+  /** The organization columns in `options.previewColumns`. */
+  readonly organization: Readonly<Record<string, unknown>> | null;
+  readonly prefill: Readonly<Record<string, unknown>>;
+  /**
+   * The keys an `invitation_preview_extra` hook added, such as a role's
+   * display name or branding. Empty without the hook.
+   */
+  readonly extra: Readonly<Record<string, unknown>>;
+}
+interface SwitchResult {
+  readonly organizationId: string;
+  /** The active tenant is a claim: refresh the session to get it. */
+  readonly refresh: boolean;
+}
+/**
+ * A membership `list_my_organizations` returns. The attribute and extra
+ * columns follow under their database names, parsed by `options.fields`
+ * when it is set.
+ */
+interface OrganizationMembership {
+  readonly id: string;
+  readonly name: string;
+  readonly slug?: string;
+  readonly role: string;
+  readonly disabledAt?: Temporal.Instant;
+  readonly [column: string]: unknown;
+}
+/** A row `list_members` returns. */
+interface OrganizationMember {
+  readonly userId: string;
+  readonly role: string;
+  readonly disabledAt?: Temporal.Instant;
+}
+/** An open invitation `list_organization_invitations` returns. */
+interface OrganizationInvitationRow {
+  readonly id: string;
+  readonly email: string;
+  readonly role: string;
+  readonly expiresAt?: Temporal.Instant;
+}
+interface OrganizationsOptions<S extends StandardSchemaV1 | undefined = undefined, SI extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  /**
+   * A Standard Schema for the organization's extra columns
+   * (`options.attributes` and `options.extraColumns`), keyed by database
+   * name. It types and parses them on `mine()`, and validates them on
+   * `create` and `update`, which return a `validation` error for a bad value.
+   */
+  readonly fields?: S;
+  /**
+   * A Standard Schema for the invitations table's extra columns
+   * (`blocks.invitations.options.extraColumns`). It validates them on
+   * `invite` and parses them on every invitation read.
+   */
+  readonly invitationFields?: SI;
+  /** `withBlockHooks` hooks around the methods, such as a seat limit on `invite`. */
+  readonly hooks?: NoInfer<BlockHooks<Organizations<FieldsOf<S>, FieldsOf<SI>>>>;
+  /** `sqlTransport(postgres.asUser(claims))` or `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /**
+   * The schema holding the functions: `blocks.<module>.schema` with
+   * `sqlTransport`, the exposed API schema of wrappers with `rpcTransport`.
+   * One schema for both modules, or one per module. Defaults to
+   * `better_supabase`.
+   */
+  readonly schema?: string | {
+    readonly organizations?: string;
+    readonly invitations?: string;
+  };
+  /** `betterSupabase.events`, to emit `organization.*` and `invitation.*` block events. */
+  readonly events?: EventHub;
+  /** The user acting, for event metadata. */
+  readonly actorId?: string;
+  readonly context?: RequestContext;
+  /**
+   * Runs before an invitation is created, after the database checks the
+   * caller may invite. Return `false` to refuse (seat limits, plans).
+   */
+  readonly canInvite?: (request: InviteRequest<FieldsOf<SI>>) => boolean | Promise<boolean>;
+  /**
+   * Runs after an invitation is created or resent, to send the email. When
+   * it throws, the call returns an error and the invitation stays open:
+   * call `resendInvitation` to retry.
+   */
+  readonly onInvite?: (sent: InvitationSent<FieldsOf<SI>>) => void | Promise<void>;
+  /** Error mappers that run before the built-in ones, as in `betterSupabase.mapError()`. */
+  readonly mappers?: readonly ErrorMapper[];
+}
+/**
+ * The `hint` of an invitation error: `INVITATION_EXPIRED` for an open
+ * invitation past its expiry, `INVITATION_INVALID` for one that is unknown,
+ * accepted, declined or revoked, and the other `INVITATION_*` codes.
+ */
+type InvitationErrorHint = InvitationError;
+/**
+ * The `organizations` and `invitations` SQL modules as typed calls. Each
+ * method returns an `AsyncResult`; database errors carry the module's error
+ * code (`ORGANIZATION_FORBIDDEN`, `INVITATION_EXPIRED`) as `hint`. `F` is
+ * the extra fields `options.fields` describes.
+ */
+interface Organizations<F extends object = Record<never, never>, I extends object = Record<never, never>> {
+  create(attributes: OrganizationAttributes & Partial<F>, options?: CreateOrganizationOptions): AsyncResult<{
+    readonly id: string;
+  }>;
+  update(organizationId: string, attributes: OrganizationAttributes & Partial<F>): AsyncResult<true>;
+  /** `false` when it did not exist (or was already soft-deleted). */
+  delete(organizationId: string): AsyncResult<boolean>;
+  /** Why a slug can't be used, or `undefined` when it can. */
+  slugProblem(slug: string, exceptOrganizationId?: string): AsyncResult<SlugProblem | undefined>;
+  updateMemberRole(organizationId: string, userId: string, role: string): AsyncResult<true>;
+  removeMember(organizationId: string, userId: string): AsyncResult<true>;
+  suspendMember(organizationId: string, userId: string): AsyncResult<boolean>;
+  resumeMember(organizationId: string, userId: string): AsyncResult<boolean>;
+  leave(organizationId: string): AsyncResult<true>;
+  /** `formerRole` defaults to `options.formerOwnerRole`. */
+  transferOwnership(organizationId: string, newOwnerId: string, formerRole?: string): AsyncResult<true>;
+  markUsed(organizationId: string): AsyncResult<boolean>;
+  switch(organizationId: string): AsyncResult<SwitchResult>;
+  /** Organizations the caller belongs to. */
+  mine(): AsyncResult<readonly (OrganizationMembership & F)[]>;
+  members(organizationId: string): AsyncResult<readonly OrganizationMember[]>;
+  invitations(organizationId: string): AsyncResult<readonly OrganizationInvitationRow[]>;
+  invite(request: InviteRequest<I>): AsyncResult<InvitationSent<I>>;
+  resendInvitation(invitationId: string, validFor?: string): AsyncResult<InvitationSent<I>>;
+  /**
+   * A new email, role or prefill for an open invitation, with the checks
+   * `invite` makes. The token and expiry stay, so the link already sent
+   * keeps working; call `resendInvitation` to mail the new address. An
+   * expired invitation fails with `INVITATION_EXPIRED`; resend it first.
+   */
+  updateInvitation(invitationId: string, changes: InvitationChanges): AsyncResult<Invitation<I>>;
+  /** `false` when it was not open. */
+  revokeInvitation(invitationId: string): AsyncResult<boolean>;
+  declineInvitation(token: string): AsyncResult<boolean>;
+  /** `undefined` for an unknown token. Callable without a session. */
+  previewInvitation(token: string): AsyncResult<InvitationPreview | undefined>;
+  /** Returns the organization joined, `null` for a platform invitation. */
+  acceptInvitation(token: string): AsyncResult<{
+    readonly organizationId: string | null;
+  }>;
+  acceptInvitationById(invitationId: string): AsyncResult<{
+    readonly organizationId: string | null;
+  }>;
+  declineInvitationById(invitationId: string): AsyncResult<boolean>;
+  myInvitations(): AsyncResult<readonly Invitation<I>[]>;
+}
+/** Calls the `organizations` and `invitations` block functions. */
+declare function createOrganizations<S extends StandardSchemaV1 | undefined = undefined, SI extends StandardSchemaV1 | undefined = undefined>(options: OrganizationsOptions<S, SI>): Organizations<FieldsOf<S>, FieldsOf<SI>>;
+//#endregion
+//#region src/blocks/organizations/client.d.ts
+/** Loads the caller's organizations, e.g. a server action; it throws on failure. */
+type OrganizationSource<T> = () => Promise<readonly T[]>;
+interface OrganizationsControllerOptions<T extends {
+  readonly id: string;
+} = OrganizationMembership> {
+  readonly client: Pick<Organizations, "switch">;
+  readonly auth: AuthPort;
+  /** The caller's organizations, most recently used first, such as `organizations.mine()`. */
+  readonly load: OrganizationSource<T>;
+  /** Organizations a server already loaded: the first load is skipped. */
+  readonly initial?: readonly T[];
+  /** The active organization a server read from the session, used while the session has no tenant claim. */
+  readonly activeId?: string | null;
+  /** The tenant claim, `config.claims.tenant` (default `tenant_id`). */
+  readonly claim?: string;
+  /**
+   * Runs after a switch: the active organization is a claim, so with
+   * `result.refresh` the session has to be refreshed to carry it.
+   */
+  readonly onSwitched: (result: SwitchResult) => void | Promise<void>;
+}
+interface OrganizationsSnapshot<T> {
+  /** `undefined` until the first load. */
+  readonly organizations: readonly T[] | undefined;
+  /** The active organization from the session's tenant claim. */
+  readonly activeId: string | undefined;
+  /** The organization a switch is moving to. */
+  readonly switching: string | undefined;
+  readonly error: DbError | undefined;
+}
+interface OrganizationsActions {
+  /** Makes `organizationId` active, then runs `onSwitched`; a failure is also kept in `error`. */
+  readonly switchTo: (organizationId: string) => Promise<Result<SwitchResult>>;
+  readonly refresh: () => Promise<void>;
+}
+type OrganizationsController<T> = Controller<OrganizationsSnapshot<T>, OrganizationsActions>;
+/**
+ * The caller's organizations and the active one, for an organization
+ * switcher: `switchTo` switches, refreshes the session through `onSwitched`
+ * and loads the list again.
+ */
+declare function createOrganizationsController<T extends {
+  readonly id: string;
+} = OrganizationMembership>(options: OrganizationsControllerOptions<T>): OrganizationsController<T>;
+/** Loads one organization's rows, e.g. a server action; it throws on failure. */
+type OrganizationRowSource<T> = (organizationId: string) => Promise<readonly T[]>;
+/** A member change that committed, for `onChanged`. */
+type MemberChange = {
+  readonly kind: "role";
+  readonly organizationId: string;
+  readonly userId: string;
+  readonly role: string;
+} | {
+  readonly kind: "removed";
+  readonly organizationId: string;
+  readonly userId: string;
+};
+interface MembersControllerOptions<T extends {
+  readonly userId: string;
+  readonly role: string;
+} = OrganizationMember> {
+  readonly client: Pick<Organizations, "updateMemberRole" | "removeMember">;
+  readonly auth: AuthPort;
+  /** The organization; the table waits without one. */
+  readonly organizationId: string | null;
+  /** The organization's members, such as `organizations.members(id)` or a server action that adds profiles. */
+  readonly load: OrganizationRowSource<T>;
+  /** Members a server already loaded: the first load is skipped. */
+  readonly initial?: readonly T[];
+  /**
+   * Runs after a role change or a removal committed, such as a server
+   * action that refreshes the member's session. A throw is kept in `error`.
+   */
+  readonly onChanged?: (change: MemberChange) => void | Promise<void>;
+}
+interface MembersSnapshot<T> {
+  /** `undefined` until the first load. */
+  readonly members: readonly T[] | undefined;
+  /** The user ids with a role change or a removal in flight. */
+  readonly pending: readonly string[];
+  readonly error: DbError | undefined;
+}
+interface MembersActions<Role extends string = string> {
+  /** Changes a member's role, shown at once and put back when it fails. */
+  readonly setRole: (userId: string, role: Role) => Promise<Result<true>>;
+  /** Removes a member from the organization, then loads the table again. */
+  readonly remove: (userId: string) => Promise<Result<true>>;
+  readonly refresh: () => Promise<void>;
+}
+type MembersController<T extends {
+  readonly userId: string;
+  readonly role: string;
+}> = Controller<MembersSnapshot<T>, MembersActions<T["role"]>>;
+/**
+ * One organization's members for a members table: `setRole` changes a
+ * role optimistically, `remove` removes a member, and both run
+ * `onChanged` once the database committed.
+ */
+declare function createMembersController<T extends {
+  readonly userId: string;
+  readonly role: string;
+} = OrganizationMember>(options: MembersControllerOptions<T>): MembersController<T>;
+/** What `invite` takes: the organization comes from the controller. */
+type InvitationDraft = Omit<InviteRequest, "organizationId">;
+/** An invitation change that committed, for `onChanged`. */
+type InvitationChange = {
+  readonly kind: "invited";
+  readonly organizationId: string;
+  readonly sent: InvitationSent;
+} | {
+  readonly kind: "revoked";
+  readonly organizationId: string;
+  readonly invitationId: string;
+};
+interface InvitationsControllerOptions<T extends {
+  readonly id: string;
+} = OrganizationInvitationRow> {
+  readonly client: Pick<Organizations, "invite" | "revokeInvitation">;
+  readonly auth: AuthPort;
+  /** The organization; nothing loads or sends without one. */
+  readonly organizationId: string | null;
+  /** The open invitations, such as `organizations.invitations(id)`. */
+  readonly load: OrganizationRowSource<T>;
+  /** Invitations a server already loaded: the first load is skipped. */
+  readonly initial?: readonly T[];
+  /**
+   * Runs after an invitation was sent or revoked, such as a server action
+   * that completes an onboarding step. A throw is kept in `error`.
+   */
+  readonly onChanged?: (change: InvitationChange) => void | Promise<void>;
+}
+interface InvitationsSnapshot<T> {
+  /** The open invitations; `undefined` until the first load. */
+  readonly invitations: readonly T[] | undefined;
+  /** Whether an invitation is being sent. */
+  readonly inviting: boolean;
+  /** The last invitation sent, with the token for the accept link, until `clear`. */
+  readonly sent: InvitationSent | undefined;
+  /** The invitation ids with a revoke in flight. */
+  readonly revoking: readonly string[];
+  readonly error: DbError | undefined;
+}
+interface InvitationsActions {
+  /** Invites `email` with `role`, then loads the list again; a failure is also kept in `error`. */
+  readonly invite: (draft: InvitationDraft) => Promise<Result<InvitationSent>>;
+  /** Revokes an open invitation; `false` when it was not open. */
+  readonly revoke: (invitationId: string) => Promise<Result<boolean>>;
+  /** Forgets `sent` and `error`, such as when the dialog closes. */
+  readonly clear: () => void;
+  readonly refresh: () => Promise<void>;
+}
+type InvitationsController<T> = Controller<InvitationsSnapshot<T>, InvitationsActions>;
+/**
+ * One organization's open invitations for an invite dialog: `invite` sends
+ * one and keeps its token in `sent` for the accept link, `revoke` revokes
+ * one, and both load the list again.
+ */
+declare function createInvitationsController<T extends {
+  readonly id: string;
+} = OrganizationInvitationRow>(options: InvitationsControllerOptions<T>): InvitationsController<T>;
+//#endregion
+export { OrganizationInvitationRow as A, InvitationChanges as C, InvitationStatus as D, InvitationSent as E, SlugProblem as F, SwitchResult as I, createOrganizations as L, OrganizationMembership as M, Organizations as N, InviteRequest as O, OrganizationsOptions as P, Invitation as S, InvitationPreview as T, OrganizationsSnapshot as _, InvitationsControllerOptions as a, createOrganizationsController as b, MembersActions as c, MembersSnapshot as d, OrganizationRowSource as f, OrganizationsControllerOptions as g, OrganizationsController as h, InvitationsController as i, OrganizationMember as j, OrganizationAttributes as k, MembersController as l, OrganizationsActions as m, InvitationDraft as n, InvitationsSnapshot as o, OrganizationSource as p, InvitationsActions as r, MemberChange as s, InvitationChange as t, MembersControllerOptions as u, createInvitationsController as v, InvitationErrorHint as w, CreateOrganizationOptions as x, createMembersController as y };

package/dist/client-Co6BPmvr.d.ts

@@ -0,0 +1,108 @@
+import { b as DbError, f as Result, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { n as BlockOptions } from "./block-helpers-C86hPEjI.js";
+import { n as BlockHooks } from "./block-hooks-BLPWD3Jt.js";
+import { n as ExtraFields, r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { n as Controller, t as AuthPort } from "./controller-D845qKh2.js";
+import { t as RankNeighbors } from "./rank-result-Dngpt2n5.js";
+//#region src/blocks/tags/tags.d.ts
+interface TagsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the tag's extra columns
+   * (`blocks.tags.options.extraColumns`), keyed by database name. It types
+   * and parses them on reads, and validates them on `create` and `update`.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Tags<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** A tag. `F` types the extra columns the `fields` schema describes. */
+interface Tag<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string;
+  /** Its rank key among the tenant's tags of the same kind, when it has one. */
+  readonly rank?: string;
+  /** Set on the tags `list` and `forSubject` return. */
+  readonly kind?: string;
+  readonly color?: string;
+  readonly description?: string;
+  /** The extra columns, keyed by database name. */
+  readonly fields: ExtraFields<F>;
+}
+interface Tags<F extends object = Record<never, never>> {
+  /** Creates a tag; `fields` sets its extra columns. */
+  create(organizationId: string, kind: string, name: string, color?: string, description?: string, fields?: Partial<F>): AsyncResult<Tag<F>>;
+  /** Renames a tag (`name` null keeps it) and sets the extra columns `fields` names. */
+  update(id: string, name: string | null, fields?: Partial<F>): AsyncResult<boolean>;
+  /**
+   * Moves a tag between the tags with rank keys `previous` and `next`.
+   * Resolves to its new key.
+   */
+  reorder(id: string, neighbors: RankNeighbors): AsyncResult<string>;
+  delete(id: string): AsyncResult<boolean>;
+  tag(organizationId: string, subjectType: string, subjectId: string, tagId: string): AsyncResult<boolean>;
+  untag(organizationId: string, subjectType: string, subjectId: string, tagId: string): AsyncResult<boolean>;
+  /** The tenant's tags of `kind` (every kind without it), in rank order. */
+  list(organizationId: string, kind?: string): AsyncResult<readonly Tag<F>[]>;
+  /** The tags on one subject, in rank order; the caller must be able to read it. */
+  forSubject(organizationId: string, subjectType: string, subjectId: string): AsyncResult<readonly Tag<F>[]>;
+}
+/** The `tags` SQL module as typed calls. */
+declare function createTags<S extends StandardSchemaV1 | undefined = undefined>(options: TagsOptions<S>): Tags<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/tags/client.d.ts
+/** A tag change on the subject that committed, for `onChanged`. */
+type TagChange = {
+  readonly kind: "added";
+  readonly tag: Tag;
+  readonly created: boolean;
+} | {
+  readonly kind: "removed";
+  readonly tag: Tag;
+};
+interface TagInputControllerOptions {
+  readonly client: Pick<Tags, "list" | "forSubject" | "tag" | "untag" | "create">;
+  readonly auth: AuthPort;
+  /** The organization; the input waits without one. */
+  readonly organizationId: string | null;
+  readonly subjectType: string;
+  readonly subjectId: string;
+  /** The kind of tags the input offers and creates, such as `customer`. */
+  readonly kind: string;
+  /** Runs after a tag was added or removed. A throw is kept in `error`. */
+  readonly onChanged?: (change: TagChange) => void | Promise<void>;
+}
+interface TagInputSnapshot {
+  /** The subject's tags, in rank order; `undefined` until the first load. */
+  readonly tags: readonly Tag[] | undefined;
+  /** Every tag of the kind, for suggestions; `undefined` until the first load. */
+  readonly available: readonly Tag[] | undefined;
+  /** The tag ids, or the names of tags being created, with a write in flight. */
+  readonly pending: readonly string[];
+  readonly error: DbError | undefined;
+}
+interface TagInputActions {
+  /** Adds an existing tag, shown at once and taken back when it fails. */
+  readonly add: (tagId: string) => Promise<Result<Tag>>;
+  /** Removes a tag, hidden at once and put back when it fails. */
+  readonly remove: (tagId: string) => Promise<Result<boolean>>;
+  /**
+   * Adds the tag called `name`: an existing one of the kind with the same
+   * name (ignoring case), or a new one, which needs `tags.manage`.
+   */
+  readonly create: (name: string) => Promise<Result<Tag>>;
+  readonly refresh: () => Promise<void>;
+}
+type TagInputController = Controller<TagInputSnapshot, TagInputActions>;
+/**
+ * One subject's tags for a tag input: the tags on it, every tag of the
+ * kind for suggestions, and `add`, `remove` and `create`, which show the
+ * change at once.
+ */
+declare function createTagInputController(options: TagInputControllerOptions): TagInputController;
+//#endregion
+export { TagInputSnapshot as a, Tags as c, TagInputControllerOptions as i, TagsOptions as l, TagInputActions as n, createTagInputController as o, TagInputController as r, Tag as s, TagChange as t, createTags as u };

package/dist/client-CoVGPi0c.js

@@ -0,0 +1,133 @@
+import { n as whileSignedIn, t as defineController } from "./controller-D6NyNrlZ.js";
+import { A as requiredInstant, C as optionalText, D as recordOf, I as textOf, k as recordsOf, n as applyTemporal, o as blockCall } from "./block-helpers-CfG_MvDR.js";
+import { r as withBlockHooks } from "./block-hooks-BsXncUlZ.js";
+//#region src/blocks/reactions/reactions.ts
+/** The topic the module broadcasts an organization's reaction changes to. */
+function reactionsTopic(organizationId, topic = "reactions") {
+	return `${topic}:${organizationId}`;
+}
+function countsOf(value, fn) {
+	return recordsOf(value, fn).map((row) => ({
+		emoji: textOf(row["emoji"]),
+		count: Number(row["count"]),
+		reacted: row["reacted"] === true,
+		actors: Array.isArray(row["actors"]) ? row["actors"].map((actor) => textOf(actor)) : []
+	}));
+}
+function emojiOf(value, fn) {
+	const row = recordOf(value, fn);
+	const attachmentId = optionalText(row["attachmentId"]);
+	const url = optionalText(row["url"]);
+	return {
+		id: textOf(row["id"]),
+		shortcode: textOf(row["shortcode"]),
+		createdAt: requiredInstant(row["createdAt"], "createdAt"),
+		...attachmentId === void 0 ? {} : { attachmentId },
+		...url === void 0 ? {} : { url }
+	};
+}
+/** The `reactions` SQL module as typed calls. */
+function createReactions(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return withBlockHooks({
+		react: (organizationId, subjectType, subjectId, emoji, react = {}) => call("react", {
+			tenant: organizationId,
+			subject_type: subjectType,
+			subject_id: subjectId,
+			emoji,
+			present: react.present ?? true,
+			actor: react.actor ?? null
+		}, (value) => countsOf(value, "react")),
+		summary: (organizationId, subjectType, subjectIds) => call("reaction_summary", {
+			tenant: organizationId,
+			subject_type: subjectType,
+			subject_ids: [...subjectIds]
+		}, (value) => Object.fromEntries(Object.entries(recordOf(value, "reaction_summary")).map(([id, counts]) => [id, countsOf(counts, "reaction_summary")]))),
+		customEmoji: (organizationId) => call("list_custom_emoji", { tenant: organizationId }, (value) => recordsOf(value, "list_custom_emoji").map((row) => emojiOf(row, "list_custom_emoji"))),
+		saveCustomEmoji: (organizationId, input) => call("save_custom_emoji", {
+			tenant: organizationId,
+			shortcode: input.shortcode,
+			attachment_id: input.attachmentId ?? null,
+			url: input.url ?? null
+		}, (value) => emojiOf(value, "save_custom_emoji")),
+		deleteCustomEmoji: (id) => call("delete_custom_emoji", { emoji_id: id }, (value) => value === true)
+	}, options.hooks, {
+		block: "reactions",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/reactions/client.ts
+const sameIds = (a, b) => a.length === b.length && a.every((id, index) => id === b[index]);
+/**
+* The reactions of the subjects on screen, loaded again when anyone in the
+* organization reacts to one of them. `toggle` feeds an emoji picker.
+*/
+function createReactionsController(options) {
+	const { client, organizationId, subjectType } = options;
+	const topic = options.topic === void 0 ? "reactions" : options.topic;
+	let subjects = [...options.subjectIds];
+	let watching = false;
+	return defineController({
+		reactions: void 0,
+		status: "closed",
+		error: void 0
+	}, (state) => {
+		let ticket = 0;
+		const refresh = async () => {
+			const request = ++ticket;
+			const result = await client.summary(organizationId, subjectType, subjects);
+			if (request !== ticket) return;
+			state.set(result.ok ? {
+				reactions: result.data,
+				error: void 0
+			} : { error: result.error });
+		};
+		const watched = (payload) => typeof payload !== "object" || payload === null || !("subjectId" in payload) || !("subjectType" in payload) || payload.subjectType === subjectType && typeof payload.subjectId === "string" && subjects.includes(payload.subjectId);
+		return {
+			actions: {
+				refresh,
+				setSubjects: (subjectIds) => {
+					if (sameIds(subjects, subjectIds)) return;
+					subjects = [...subjectIds];
+					if (watching) refresh();
+				},
+				toggle: async (subjectId, emoji) => {
+					const present = !state.get().reactions?.[subjectId]?.some((reaction) => reaction.emoji === emoji && reaction.reacted);
+					const result = await client.react(organizationId, subjectType, subjectId, emoji, { present });
+					if (!result.ok) {
+						state.set({ error: result.error });
+						return;
+					}
+					state.set((current) => ({
+						error: void 0,
+						reactions: {
+							...current.reactions,
+							[subjectId]: result.data
+						}
+					}));
+				}
+			},
+			start: () => whileSignedIn(options.auth, () => {
+				watching = true;
+				refresh();
+				const leave = topic ? options.ports.topic(reactionsTopic(organizationId, topic), {
+					onMessage: (_event, payload) => {
+						if (watched(payload)) refresh();
+					},
+					onRejoin: () => void refresh(),
+					onStatus: (status) => {
+						state.set({ status });
+					}
+				}).leave : void 0;
+				return () => {
+					watching = false;
+					leave?.();
+				};
+			})
+		};
+	});
+}
+//#endregion
+export { createReactions as n, reactionsTopic as r, createReactionsController as t };