better-supabase 0.8.0 → 0.10.0

package/dist/client-Cgxj38RS.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-CtAHxPal.js";
+import { m as RequestContext } from "./plugin-D5OIaP93.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as BlockTransport } from "./block-transport-NbUJygA7.js";
+import { r as BlockTemporalOptions } from "./block-helpers-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { i as RowFields, r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { n as Controller, t as AuthPort } from "./controller-CCb9tHw_.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-CjyTNdt1.d.ts

@@ -0,0 +1,65 @@
+import { b as DbError } from "./result-Cj3yWhjH.js";
+import { p as SubscriptionStatus } from "./topic-Dgs-eSYQ.js";
+import { n as TopicPort } from "./watch-topic-D-rpUg5n.js";
+import { a as WorkflowRunStatus, g as Workflows, n as WorkflowRun } from "./workflows-DJXoxDZH.js";
+import { n as Controller, t as AuthPort } from "./controller-CCb9tHw_.js";
+//#region src/blocks/workflows/client.d.ts
+interface WorkflowRunsControllerOptions {
+  readonly client: {
+    readonly runs: Pick<Workflows["runs"], "list">;
+  };
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The tenant whose runs to list; it also joins the tenant's `workflow-runs:<tenant>` topic. Without one, the signed-in user's own runs load once. */
+  readonly tenant?: string | null;
+  readonly definition?: string;
+  readonly status?: WorkflowRunStatus;
+  readonly limit?: number;
+}
+interface WorkflowRunsSnapshot {
+  /** `undefined` until the first load. */
+  readonly runs: readonly WorkflowRun[] | undefined;
+  readonly error: DbError | undefined;
+  readonly status: SubscriptionStatus;
+}
+interface WorkflowRunsActions {
+  readonly refresh: () => Promise<void>;
+}
+type WorkflowRunsController = Controller<WorkflowRunsSnapshot, WorkflowRunsActions>;
+/**
+ * The runs the signed-in user may read, newest first, loaded again when a
+ * run in the tenant changes status.
+ */
+declare function createWorkflowRunsController(options: WorkflowRunsControllerOptions): WorkflowRunsController;
+interface WorkflowRunControllerOptions {
+  readonly client: {
+    readonly runs: Pick<Workflows["runs"], "get" | "requestCancel">;
+  };
+  readonly auth: AuthPort;
+  readonly ports: {
+    readonly topic: TopicPort;
+  };
+  /** The run's id or its engine's id; `null` waits. */
+  readonly run: string | null;
+}
+interface WorkflowRunSnapshot {
+  /** `undefined` until the first load, and when the user may not read the run. */
+  readonly run: WorkflowRun | undefined;
+  readonly error: DbError | undefined;
+  readonly status: SubscriptionStatus;
+}
+interface WorkflowRunActions {
+  readonly refresh: () => Promise<void>;
+  /** Asks the engine to cancel the run, then loads it again. */
+  readonly cancel: () => Promise<void>;
+}
+type WorkflowRunController = Controller<WorkflowRunSnapshot, WorkflowRunActions>;
+/**
+ * One run by its id or its engine's id, loaded again on each status change
+ * broadcast on `workflow-run:<id>`.
+ */
+declare function createWorkflowRunController(options: WorkflowRunControllerOptions): WorkflowRunController;
+//#endregion
+export { WorkflowRunsActions as a, WorkflowRunsSnapshot as c, WorkflowRunSnapshot as i, createWorkflowRunController as l, WorkflowRunController as n, WorkflowRunsController as o, WorkflowRunControllerOptions as r, WorkflowRunsControllerOptions as s, WorkflowRunActions as t, createWorkflowRunsController as u };