better-supabase 0.5.0 → 0.6.0

package/dist/blocks/onboarding/react/index.js

@@ -0,0 +1,78 @@
+"use client";
+import { i as useAuth, l as useSupabase } from "../../../hooks-1BTCJsiw.js";
+import { n as rpcTransport } from "../../../block-transport-BLr-ZgLc.js";
+import { useCallback, useEffect, useMemo, useState } from "react";
+//#region src/blocks/onboarding/react/index.ts
+/**
+* A checklist's progress for the signed-in user, or for an organization
+* with `organizationId`, through the browser client.
+*
+* ```tsx
+* const { progress, complete } = useOnboarding(gettingStarted, { organizationId });
+* ```
+*/
+function useOnboarding(checklist, options = {}) {
+	const supabase = useSupabase();
+	const auth = useAuth();
+	const [progress, setProgress] = useState(void 0);
+	const [error, setError] = useState(void 0);
+	const organizationId = options.organizationId ?? null;
+	const schema = options.schema;
+	const ready = auth.status === "signed-in" && (checklist.scope === "user" || organizationId !== null);
+	const bound = useMemo(() => {
+		const client = checklist.connect({
+			transport: rpcTransport(supabase),
+			...schema === void 0 ? {} : { schema }
+		});
+		const subject = checklist.scope === "organization" && organizationId !== null ? [organizationId] : [];
+		return {
+			progress: () => client.progress(...subject),
+			complete: (step) => client.complete(step, ...subject),
+			reset: (step) => client.reset(step, ...subject)
+		};
+	}, [
+		checklist,
+		supabase,
+		schema,
+		organizationId
+	]);
+	const userId = auth.user?.id ?? null;
+	const apply = useCallback((result) => {
+		if (result.ok) {
+			setProgress(result.data);
+			setError(void 0);
+		} else setError(result.error);
+	}, []);
+	const refresh = useCallback(async () => {
+		apply(await bound.progress());
+	}, [bound, apply]);
+	const change = useCallback(async (action, step) => {
+		const result = await bound[action](step);
+		if (result.ok) await refresh();
+		else setError(result.error);
+	}, [bound, refresh]);
+	useEffect(() => {
+		if (!ready) return;
+		let active = true;
+		bound.progress().then((result) => {
+			if (active) apply(result);
+		});
+		return () => {
+			active = false;
+		};
+	}, [
+		bound,
+		apply,
+		ready,
+		userId
+	]);
+	return {
+		progress,
+		error,
+		complete: (step) => change("complete", step),
+		reset: (step) => change("reset", step),
+		refresh
+	};
+}
+//#endregion
+export { useOnboarding };

package/dist/blocks/onboarding/react/server.d.ts

@@ -0,0 +1,7 @@
+import { a as ChecklistScope, t as Checklist } from "../../../onboarding-BZGHYJks.js";
+import { OnboardingState, UseOnboardingOptions } from "./index.js";
+//#region src/blocks/onboarding/react/server.d.ts
+/** The `react-server` build of `useOnboarding`: call the checklist's `progress()` instead. */
+export declare const useOnboarding: <Id extends string, Scope extends ChecklistScope>(checklist: Checklist<Id, Scope>, options?: UseOnboardingOptions) => OnboardingState<Id>;
+//#endregion
+export type { OnboardingState, UseOnboardingOptions };

package/dist/blocks/onboarding/react/server.js

@@ -0,0 +1,7 @@
+//#region src/blocks/onboarding/react/server.ts
+/** The `react-server` build of `useOnboarding`: call the checklist's `progress()` instead. */
+const useOnboarding = () => {
+	throw new Error("better-supabase: useOnboarding() runs in Client Components only. In Server Components call `checklist.connect(...).progress()` instead.");
+};
+//#endregion
+export { useOnboarding };

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

@@ -0,0 +1,241 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "../../result-D7y2fT87.js";
+import { i as sqlTransport, n as RpcClient, r as rpcTransport, t as BlockTransport } from "../../block-transport-DvaoPuZ9.js";
+import { m as RequestContext } from "../../plugin-FGY8UhYm.js";
+import { a as EventHub } from "../../events-DWDhx77e.js";
+import { t as StandardSchemaV1 } from "../../standard-CYsm7xpT.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CKtbFcRv.js";
+import { a as BlockTransportMiddleware, d as extendBlock, f as withBlockHooks, n as BlockHooks, p as wrapTransport } from "../../block-hooks-plbZ0AbJ.js";
+import { n as FieldsOf } from "../../block-fields-SJ6fEf3o.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
+ * `sql.modules.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 {
+  /** `null` invites to the platform (`sql.modules.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>>;
+}
+interface Invitation {
+  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>>;
+}
+/** 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 {
+  readonly invitation: Invitation;
+  /** 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> 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;
+  /** `withBlockHooks` hooks around the methods, such as a seat limit on `invite`. */
+  readonly hooks?: NoInfer<BlockHooks<Organizations<FieldsOf<S>>>>;
+  /** `sqlTransport(postgres.asUser(claims))` or `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /**
+   * The schema holding the functions: `sql.modules.<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) => 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) => 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>> {
+  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): AsyncResult<InvitationSent>;
+  resendInvitation(invitationId: string, validFor?: string): AsyncResult<InvitationSent>;
+  /**
+   * 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>;
+  /** `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[]>;
+}
+/** Calls the `organizations` and `invitations` block functions. */
+export declare function createOrganizations<S extends StandardSchemaV1 | undefined = undefined>(options: OrganizationsOptions<S>): Organizations<FieldsOf<S>>;
+//#endregion
+export { type BlockHooks, type BlockTransport, type BlockTransportMiddleware, type CreateOrganizationOptions, type Invitation, type InvitationChanges, type InvitationErrorHint, type InvitationPreview, type InvitationSent, type InvitationStatus, type InviteRequest, type OrganizationAttributes, type OrganizationInvitationRow, type OrganizationMember, type OrganizationMembership, type Organizations, type OrganizationsOptions, type RpcClient, type SlugProblem, type SwitchResult, extendBlock, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };