better-supabase 0.14.0 → 0.15.0

package/dist/blocks/organizations/index.d.ts

@@ -1,8 +1,274 @@
-import { Ct as Events, W as InvitationEventData, Z as OrganizationEventData } from "../../events-DbLjvxDX.js";
-import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-d53POsem.js";
-import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-CmjPKqQ_.js";
-import { c as BlockOf } from "../../define-block-COpcS6aT.js";
-import { A as OrganizationInvitationRow, C as InvitationChanges, D as InvitationStatus, E as InvitationSent, F as SlugProblem, I as SwitchResult, L as createOrganizations, M as OrganizationMembership, N as Organizations, O as InviteRequest, P as OrganizationsOptions, S as Invitation, T as InvitationPreview, _ as OrganizationsSnapshot, a as InvitationsControllerOptions, b as createOrganizationsController, c as MembersActions, d as MembersSnapshot, f as OrganizationRowSource, g as OrganizationsControllerOptions, h as OrganizationsController, i as InvitationsController, j as OrganizationMember, k as OrganizationAttributes, l as MembersController, m as OrganizationsActions, n as InvitationDraft, o as InvitationsSnapshot, p as OrganizationSource, r as InvitationsActions, s as MemberChange, t as InvitationChange, u as MembersControllerOptions, v as createInvitationsController, w as InvitationErrorHint, x as CreateOrganizationOptions, y as createMembersController } from "../../client-B2GCMvfd.js";
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, b as DbError, f as Result, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { t as StandardSchemaV1 } from "../../standard-DBV730sF.js";
+import { i as RowFields, r as FieldsOf } from "../../block-fields-BE7pInWZ.js";
+import { Ft as RequestContext } from "../../types-DFdg_4yN.js";
+import { Ct as Events, W as InvitationEventData, Z as OrganizationEventData, o as EventHub } from "../../events-vcqenSYU.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, i as RpcClient, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-DZN2w69m.js";
+import { c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+import { n as Controller, t as AuthPort } from "../../controller-BrP0gn47.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.permissions.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. */
+export 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/events.d.ts
 /** The events of the `organizations` block: type to data. */
 type OrganizationsEvents = {
@@ -31,4 +297,184 @@ export declare const organizationsEvents: Events<OrganizationsEvents>;
 /** The `organizations` block's manifest (ADR 0029). */
 export declare const organizationsBlock: BlockOf<"organizations", typeof createOrganizations, OrganizationsEvents>;
 //#endregion
-export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type CreateOrganizationOptions, type Invitation, type InvitationChange, type InvitationChanges, type InvitationDraft, type InvitationErrorHint, type InvitationPreview, type InvitationSent, type InvitationStatus, type InvitationsActions, type InvitationsController, type InvitationsControllerOptions, type InvitationsSnapshot, type InviteRequest, type MemberChange, type MembersActions, type MembersController, type MembersControllerOptions, type MembersSnapshot, type OrganizationAttributes, type OrganizationInvitationRow, type OrganizationMember, type OrganizationMembership, type OrganizationRowSource, type OrganizationSource, type Organizations, type OrganizationsActions, type OrganizationsController, type OrganizationsControllerOptions, type OrganizationsEvents, type OrganizationsOptions, type OrganizationsSnapshot, type RpcClient, type SlugProblem, type SwitchResult, createInvitationsController, createMembersController, createOrganizations, createOrganizationsController, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };
+//#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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function createInvitationsController<T extends {
+  readonly id: string;
+} = OrganizationInvitationRow>(options: InvitationsControllerOptions<T>): InvitationsController<T>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type CreateOrganizationOptions, type Invitation, type InvitationChange, type InvitationChanges, type InvitationDraft, type InvitationErrorHint, type InvitationPreview, type InvitationSent, type InvitationStatus, type InvitationsActions, type InvitationsController, type InvitationsControllerOptions, type InvitationsSnapshot, type InviteRequest, type MemberChange, type MembersActions, type MembersController, type MembersControllerOptions, type MembersSnapshot, type OrganizationAttributes, type OrganizationInvitationRow, type OrganizationMember, type OrganizationMembership, type OrganizationRowSource, type OrganizationSource, type Organizations, type OrganizationsActions, type OrganizationsController, type OrganizationsControllerOptions, type OrganizationsEvents, type OrganizationsOptions, type OrganizationsSnapshot, type RpcClient, type SlugProblem, type SwitchResult, dbTransport, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };