better-supabase 0.8.0 → 0.10.0

package/dist/client-DZXFDaQE.d.ts

@@ -0,0 +1,157 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, t as AsyncResult, w as ErrorMapper } from "./result-Cj3yWhjH.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { t as StandardSchemaV1 } from "./standard-C3_AAF3g.js";
+import { t as BlockTransport } from "./block-transport-NbUJygA7.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { n as Controller } from "./controller-CCb9tHw_.js";
+import { _ as AttendeeRole, d as OccurrenceOptions, f as OccurrenceRange, g as AttendeeResponse, l as CalendarEvent, n as EventCalendarOptions, t as EventCalendarEvent, u as CalendarOccurrence, y as CalendarEventStatus } from "./event-calendar-DJXXMJ3x.js";
+import { t as VisibleRange } from "./range-p5V4rBhZ.js";
+//#region src/blocks/calendar/calendar.d.ts
+interface CalendarOptions<S extends StandardSchemaV1 | undefined = undefined> {
+  /**
+   * A Standard Schema for the event columns the app adds
+   * (`blocks.calendar.options.extraColumns`), keyed by column name. It
+   * types and parses them on `events`, and validates them on `save` and
+   * the occurrence edits, which return a `validation` error for a bad
+   * value.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Calendar<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+  readonly transport: BlockTransport;
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface CalendarInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly tz: string;
+  readonly color?: string;
+  readonly ownerType?: string;
+  readonly ownerId?: string;
+}
+/** The fields of an event to write. Fields left out keep their value on update. */
+interface CalendarEventInput {
+  readonly title?: string;
+  readonly description?: string | null;
+  readonly location?: string | null;
+  readonly startsAt?: Temporal.Instant;
+  readonly endsAt?: Temporal.Instant;
+  readonly allDay?: boolean;
+  readonly tz?: string;
+  readonly status?: CalendarEventStatus;
+  /** An RFC 5545 `RRULE` value, or `null` to end the recurrence. */
+  readonly rrule?: string | null;
+  readonly exdates?: readonly Temporal.Instant[];
+  readonly subjectType?: string | null;
+  readonly subjectId?: string | null;
+  readonly color?: string | null;
+  /** Only on insert. Default the new id. */
+  readonly uid?: string;
+}
+interface SavedCalendarEvent {
+  readonly id: string;
+  readonly uid: string;
+  readonly created: boolean;
+}
+interface CalendarImport {
+  readonly created: number;
+  readonly updated: number;
+  /** Events without a UID or DTSTART, and overrides of an unknown series. */
+  readonly skipped: number;
+}
+/** `F` is the extra event fields `options.fields` describes. */
+interface Calendar<F extends object = Record<never, never>> {
+  createCalendar(organizationId: string, name: string, options?: {
+    readonly tz?: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
+  }): AsyncResult<{
+    readonly id: string;
+  }>;
+  deleteCalendar(id: string): AsyncResult<boolean>;
+  listCalendars(organizationId: string): AsyncResult<CalendarInfo[]>;
+  /**
+   * Inserts an event, or updates the one with `id`. Keys besides the
+   * input's own are the event's extra columns.
+   */
+  save(calendarId: string, input: CalendarEventInput & Partial<F> & {
+    readonly id?: string;
+  }): AsyncResult<SavedCalendarEvent>;
+  delete(eventId: string): AsyncResult<boolean>;
+  /** The rows that can fall in the range: events, series and their overrides. */
+  events(calendarIds: readonly string[], range: OccurrenceRange): AsyncResult<(CalendarEvent & F)[]>;
+  /** The occurrences in the range, series expanded. */
+  occurrences(calendarIds: readonly string[], range: OccurrenceRange, options?: OccurrenceOptions): AsyncResult<CalendarOccurrence[]>;
+  /** Changes one occurrence: an override for a series, else the event. */
+  editOccurrence(occurrence: CalendarOccurrence, changes: CalendarEventInput & Partial<F>): AsyncResult<SavedCalendarEvent>;
+  /**
+   * Changes an occurrence and every later one: splits the series, unless the
+   * occurrence is its first. Pass `rrule` when the change moves the weekday.
+   */
+  editFollowing(occurrence: CalendarOccurrence, changes: CalendarEventInput & Partial<F>): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** Removes one occurrence of a series (an `EXDATE`), or a single event. */
+  cancelOccurrence(occurrence: CalendarOccurrence): AsyncResult<boolean>;
+  setAttendee(eventId: string, attendee: {
+    readonly email: string;
+    readonly name?: string;
+    readonly userId?: string;
+    readonly role?: AttendeeRole;
+  }): AsyncResult<boolean>;
+  removeAttendee(eventId: string, email: string): AsyncResult<boolean>;
+  /** The signed-in user answers an invitation. */
+  respond(eventId: string, response: AttendeeResponse): AsyncResult<boolean>;
+  /** Upserts the events of an iCalendar file by UID. */
+  importIcs(calendarId: string, text: string): AsyncResult<CalendarImport>;
+  /** The calendar's events as an iCalendar file. */
+  exportIcs(calendar: CalendarInfo, range?: OccurrenceRange): AsyncResult<string>;
+  /**
+   * The iCalendar feed of a share link to a calendar (`subjectType:
+   * "calendar"`), or `null` when the token is unknown, revoked or expired.
+   */
+  feed(token: string): AsyncResult<string | null>;
+}
+/** A `list_calendar_events` or `calendar_feed` row as an event. */
+declare function calendarEventOf(value: unknown): CalendarEvent;
+declare function createCalendar<S extends StandardSchemaV1 | undefined = undefined>(options: CalendarOptions<S>): Calendar<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/calendar/client.d.ts
+interface CalendarControllerOptions extends EventCalendarOptions {
+  readonly client: Pick<Calendar, "occurrences" | "editOccurrence" | "editFollowing" | "cancelOccurrence">;
+  readonly calendarIds: readonly string[];
+  /** The visible range; `setRange` changes it. */
+  readonly range: VisibleRange;
+}
+interface CalendarSnapshot {
+  /** `undefined` until the first load. */
+  readonly occurrences: readonly CalendarOccurrence[] | undefined;
+  /** The occurrences as event calendar events (ReUI's `CalendarEvent` shape). */
+  readonly events: readonly EventCalendarEvent<CalendarOccurrence>[];
+  readonly error: DbError | undefined;
+  /** True until the occurrences of the current range arrive. */
+  readonly loading: boolean;
+}
+interface CalendarActions {
+  readonly refresh: () => Promise<void>;
+  /** Saves one occurrence's change, then loads the range again. */
+  readonly editOccurrence: (occurrence: CalendarOccurrence, changes: CalendarEventInput) => Promise<boolean>;
+  /** Saves the change for this and every later occurrence, then loads again. */
+  readonly editFollowing: (occurrence: CalendarOccurrence, changes: CalendarEventInput) => Promise<boolean>;
+  readonly cancelOccurrence: (occurrence: CalendarOccurrence) => Promise<boolean>;
+  /** Shows another range; the current occurrences stay until its own arrive. */
+  readonly setRange: (range: VisibleRange) => void;
+}
+type CalendarController = Controller<CalendarSnapshot, CalendarActions>;
+/**
+ * The occurrences of some calendars in the visible range, typed for a
+ * headless event calendar such as ReUI's Event Calendar.
+ */
+declare function createCalendarController(options: CalendarControllerOptions): CalendarController;
+//#endregion
+export { createCalendarController as a, CalendarImport as c, SavedCalendarEvent as d, calendarEventOf as f, CalendarSnapshot as i, CalendarInfo as l, CalendarController as n, Calendar as o, createCalendar as p, CalendarControllerOptions as r, CalendarEventInput as s, CalendarActions as t, CalendarOptions as u };

package/dist/client-Diu2lPbg.d.ts

@@ -0,0 +1,218 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, 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-7pMBVsE6.js";
+import { n as BlockHooks } from "./block-hooks-C_WaodoA.js";
+import { r as FieldsOf } from "./block-fields-5UA84ZUg.js";
+import { g as JobHandler } from "./types-P1S1cj6N.js";
+import { n as Controller } from "./controller-CCb9tHw_.js";
+import { t as VisibleRange } from "./range-p5V4rBhZ.js";
+//#region src/blocks/bookings/bookings.d.ts
+interface BookingsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
+  /**
+   * A Standard Schema for the booking columns the app adds
+   * (`blocks.bookings.options.extraColumns`), keyed by column name. The
+   * customer object of `hold` and `public.hold` carries them; the schema
+   * validates them there, which returns a `validation` error for a bad
+   * value, and types and parses them on every booking read.
+   */
+  readonly fields?: S;
+  /** `withBlockHooks` hooks around the client's methods. */
+  readonly hooks?: NoInfer<BlockHooks<Bookings<FieldsOf<S>>>>;
+  /** Receives the errors `after` hooks throw. Default: `console`. */
+  readonly logger?: Logger;
+}
+/** The queue each hold enqueues a job on, to expire it when its time is up. */
+declare const BOOKING_EXPIRE_QUEUE = "bookings.expire-holds";
+/** A duration as a `Temporal.Duration` or an ISO 8601 / Postgres interval string. */
+type BookingDuration = Temporal.Duration | string;
+interface BookingRange {
+  readonly from: Temporal.Instant;
+  readonly until: Temporal.Instant;
+}
+interface BookingResourceInput {
+  readonly id?: string;
+  readonly name?: string;
+  /** What the resource is, matched against a service's `resourceKinds`. Default `staff`. */
+  readonly kind?: string;
+  /** How many bookings can overlap: seats in a class, desks in a room. Default 1. */
+  readonly capacity?: number;
+  /** The IANA zone its weekly hours are in. Default `UTC`. */
+  readonly tz?: string;
+  /** The calendar confirmed bookings are copied into, when the calendar block is installed. */
+  readonly calendarId?: string | null;
+  readonly active?: boolean;
+}
+/** Weekly opening hours: `weekday` 1 is Monday, times are `HH:MM` in the resource's zone. */
+interface WeeklyHours {
+  readonly weekday: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  readonly start: string;
+  readonly end: string;
+}
+interface BookingExceptionInput {
+  readonly startsAt: Temporal.Instant;
+  readonly endsAt: Temporal.Instant;
+  /** `true` opens the resource outside its hours. Default `false`, which closes it. */
+  readonly available?: boolean;
+  readonly reason?: string;
+}
+interface BookingServiceInput {
+  readonly id?: string;
+  readonly name?: string;
+  readonly duration?: BookingDuration;
+  readonly bufferBefore?: BookingDuration;
+  readonly bufferAfter?: BookingDuration;
+  /** The resource kinds that can serve it; empty means every resource. */
+  readonly resourceKinds?: readonly string[];
+  /** The distance between slot starts. Default the duration. */
+  readonly step?: BookingDuration | null;
+  /** How far ahead a slot must start. */
+  readonly minNotice?: BookingDuration;
+  /** How long a hold keeps the slot. Default 10 minutes. */
+  readonly holdFor?: BookingDuration;
+  /** Minutes before the start that reminders go out. Default one day. */
+  readonly reminderOffsets?: readonly number[];
+  readonly active?: boolean;
+}
+interface BookingSlot {
+  readonly resourceId: string;
+  readonly startsAt: Temporal.Instant;
+  readonly endsAt: Temporal.Instant;
+  /** The start as wall-clock time in the zone asked for, else the resource's. */
+  readonly localStart: Temporal.PlainDateTime;
+  /** Free seats at this time. */
+  readonly seats: number;
+}
+interface BookingCustomer {
+  readonly name?: string;
+  readonly email?: string;
+  /** Only managers can book for another user. */
+  readonly userId?: string;
+  readonly notes?: string;
+}
+type BookingStatus = "hold" | "confirmed" | "cancelled";
+interface Booking {
+  readonly id: string;
+  readonly resourceId: string;
+  readonly serviceId: string;
+  readonly seat: number;
+  readonly startsAt: Temporal.Instant;
+  readonly endsAt: Temporal.Instant;
+  readonly status: BookingStatus;
+  readonly holdExpiresAt?: Temporal.Instant;
+  readonly customerName?: string;
+  readonly customerEmail?: string;
+  readonly customerUserId?: string;
+  readonly notes?: string;
+  readonly createdAt?: Temporal.Instant;
+  readonly cancelledAt?: Temporal.Instant;
+  readonly cancelReason?: string;
+}
+/** A new booking with the token that confirms or cancels it without signing in. Shown once. */
+interface PlacedBooking extends Booking {
+  readonly accessToken: string;
+}
+interface PublicBookingService {
+  readonly id: string;
+  readonly name: string;
+  /** The duration as Postgres prints an interval, such as `00:30:00`. */
+  readonly duration: string;
+  readonly resources: readonly {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    readonly tz: string;
+  }[];
+}
+/** The payload a hold enqueues on `bookings.expire-holds`. */
+interface BookingExpirePayload {
+  readonly bookingId?: string;
+}
+/** `F` is the extra booking fields `options.fields` describes. */
+interface Bookings<F extends object = Record<never, never>> {
+  saveResource(organizationId: string, input: BookingResourceInput): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** Replaces a resource's weekly hours. Resolves to the number of rows. */
+  setAvailability(resourceId: string, hours: readonly WeeklyHours[]): AsyncResult<number>;
+  addException(resourceId: string, exception: BookingExceptionInput): AsyncResult<{
+    readonly id: string;
+  }>;
+  deleteException(id: string): AsyncResult<boolean>;
+  saveService(organizationId: string, input: BookingServiceInput): AsyncResult<{
+    readonly id: string;
+  }>;
+  /** The open slots of a service, at most 62 days at a time. */
+  availableSlots(serviceId: string, range: BookingRange, options?: {
+    readonly tz?: string;
+    readonly resourceId?: string;
+  }): AsyncResult<BookingSlot[]>;
+  /** Holds a slot for the service's `holdFor`, or books it with `confirm`. */
+  hold(serviceId: string, resourceId: string, startsAt: Temporal.Instant, customer?: BookingCustomer & Partial<F>, options?: {
+    readonly confirm?: boolean;
+  }): AsyncResult<PlacedBooking & F>;
+  confirm(bookingId: string): AsyncResult<Booking & F>;
+  cancel(bookingId: string, reason?: string): AsyncResult<Booking & F>;
+  /** The bookings that overlap the range, as the caller's policies allow. */
+  list(organizationId: string, range: BookingRange, options?: {
+    readonly resourceId?: string;
+  }): AsyncResult<(Booking & F)[]>;
+  /** Cancels every hold whose time is up. Service only. */
+  expireHolds(): AsyncResult<number>;
+  /** The handler for the `bookings.expire-holds` queue. */
+  readonly job: JobHandler<unknown>;
+  /** The public side, through a share link to a service (`subjectType: "booking_service"`). */
+  readonly public: {
+    service(token: string): AsyncResult<PublicBookingService>;
+    slots(token: string, range: BookingRange, options?: {
+      readonly tz?: string;
+    }): AsyncResult<BookingSlot[]>;
+    /** Holds a slot for a guest, who must give a name and an email. */
+    hold(token: string, resourceId: string, startsAt: Temporal.Instant, customer: BookingCustomer & Partial<F> & {
+      readonly name: string;
+      readonly email: string;
+    }): AsyncResult<PlacedBooking & F>;
+    confirm(bookingId: string, accessToken: string): AsyncResult<Booking & F>;
+    cancel(bookingId: string, accessToken: string): AsyncResult<Booking & F>;
+  };
+}
+/** A booking row as `hold_booking`, `list_bookings` and the others return it. */
+declare function bookingOf(value: unknown): Booking;
+declare function createBookings<S extends StandardSchemaV1 | undefined = undefined>(options: BookingsOptions<S>): Bookings<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/bookings/client.d.ts
+interface AvailableSlotsOptions {
+  readonly client: Pick<Bookings, "availableSlots" | "hold"> & {
+    readonly public: Pick<Bookings["public"], "slots" | "hold">;
+  };
+  readonly serviceId: string;
+  /** The visible range; `setRange` changes it. */
+  readonly range: VisibleRange;
+  /** The zone slot times are shown in. Default each resource's. */
+  readonly tz?: string;
+  readonly resourceId?: string;
+  /** A share-link token: loads and holds slots as a guest. */
+  readonly token?: string;
+}
+interface AvailableSlotsSnapshot {
+  /** `undefined` until the first load. */
+  readonly slots: readonly BookingSlot[] | undefined;
+  /** The slots by local date (`YYYY-MM-DD`), for a day-by-day picker. */
+  readonly days: ReadonlyMap<string, readonly BookingSlot[]>;
+  readonly error: DbError | undefined;
+  /** True until the slots of the current range arrive. */
+  readonly loading: boolean;
+}
+interface AvailableSlotsActions {
+  readonly refresh: () => Promise<void>;
+  /** Holds a slot, then loads the range again. With a token, `customer` needs a name and an email. */
+  readonly hold: (slot: BookingSlot, customer?: BookingCustomer) => Promise<PlacedBooking | undefined>;
+  /** Shows another range; the current slots stay until its slots arrive. */
+  readonly setRange: (range: VisibleRange) => void;
+}
+type AvailableSlotsController = Controller<AvailableSlotsSnapshot, AvailableSlotsActions>;
+/** The open slots of a service in the visible range, for a headless date and time picker. */
+declare function createAvailableSlotsController(options: AvailableSlotsOptions): AvailableSlotsController;
+//#endregion
+export { createBookings as C, bookingOf as S, Bookings as _, createAvailableSlotsController as a, PublicBookingService as b, BookingCustomer as c, BookingExpirePayload as d, BookingRange as f, BookingStatus as g, BookingSlot as h, AvailableSlotsSnapshot as i, BookingDuration as l, BookingServiceInput as m, AvailableSlotsController as n, BOOKING_EXPIRE_QUEUE as o, BookingResourceInput as p, AvailableSlotsOptions as r, Booking as s, AvailableSlotsActions as t, BookingExceptionInput as u, BookingsOptions as v, WeeklyHours as x, PlacedBooking as y };

package/dist/client-Dk8gY9hi.d.ts

@@ -0,0 +1,34 @@
+import { n as Controller, t as AuthPort } from "./controller-CCb9tHw_.js";
+import { t as EntitlementClaimOptions } from "./entitlements-Bn7BTnbg.js";
+//#region src/blocks/entitlements/client.d.ts
+interface FeatureGateControllerOptions {
+  readonly auth: AuthPort;
+  /** The plan feature, such as `exports`: a key of `entitlements.source.plans`. */
+  readonly feature: string;
+  /** The organization to check. Default the session's active one, from the tenant claim. */
+  readonly organizationId?: string | null;
+  /** `config.claims.features` (default `features`), or `{ claim, keys }` for short codes. */
+  readonly claim?: string | EntitlementClaimOptions;
+  /** The tenant claim, `config.claims.tenant` (default `tenant_id`). */
+  readonly tenantClaim?: string;
+}
+interface FeatureGateSnapshot {
+  /** `undefined` while the session loads; false when signed out or outside an organization. */
+  readonly allowed: boolean | undefined;
+  /** The organization the check ran for. */
+  readonly organizationId: string | undefined;
+}
+interface FeatureGateActions {
+  /** Checks the session again, such as after a refresh the gate did not hear of. */
+  readonly recheck: () => void;
+}
+type FeatureGateController = Controller<FeatureGateSnapshot, FeatureGateActions>;
+/**
+ * Whether the active organization's plan includes `feature`, from the
+ * session's plan-features claim. It updates when the session does, so a
+ * session refresh after checkout opens the gate. UX only: enforce the
+ * feature in RLS with `better_supabase.has_entitlement()`.
+ */
+declare function createFeatureGateController(options: FeatureGateControllerOptions): FeatureGateController;
+//#endregion
+export { createFeatureGateController as a, FeatureGateSnapshot as i, FeatureGateController as n, FeatureGateControllerOptions as r, FeatureGateActions as t };

package/dist/client-Ezlbskjq.js

@@ -0,0 +1,60 @@
+import { t as defineController } from "./controller-D6NyNrlZ.js";
+import { t as tenantOf } from "./tenant-B-fiItlJ.js";
+//#region src/auth/entitlements.ts
+/**
+* Whether the session's plan-features claim grants `key` in `tenantId`.
+* `claim` is `config.claims.features` (default `features`), the claim
+* `better_supabase.feature_claims()` fills, or `{ claim, keys }` when
+* `entitlements.claim.keys` writes short codes. The claim is as fresh as the
+* token: enforce it in RLS with `better_supabase.has_entitlement()`, and
+* refresh the session after checkout. A tenant left out by
+* `entitlements.claim.maxTenants` reads as not granted. Takes a server
+* session or the client's `useAuth()` snapshot.
+*/
+function hasEntitlement(session, tenantId, key, claim = "features") {
+	const options = typeof claim === "string" ? { claim } : claim;
+	const claims = "kind" in session ? session.kind === "user" ? session.claims : void 0 : session.claims;
+	if (!isRecord(claims)) return false;
+	const features = claims[options.claim ?? "features"];
+	if (!isRecord(features) || !Object.hasOwn(features, tenantId)) return false;
+	const keys = features[tenantId];
+	const code = options.keys?.[key] ?? key;
+	return Array.isArray(keys) && keys.includes(code);
+}
+const isRecord = (value) => typeof value === "object" && value !== null;
+//#endregion
+//#region src/blocks/entitlements/client.ts
+/**
+* Whether the active organization's plan includes `feature`, from the
+* session's plan-features claim. It updates when the session does, so a
+* session refresh after checkout opens the gate. UX only: enforce the
+* feature in RLS with `better_supabase.has_entitlement()`.
+*/
+function createFeatureGateController(options) {
+	const read = () => {
+		const session = options.auth.current();
+		if (session.status === "loading") return {
+			allowed: void 0,
+			organizationId: void 0
+		};
+		const organizationId = options.organizationId ?? tenantOf(session, options.tenantClaim);
+		return {
+			allowed: organizationId === void 0 ? false : hasEntitlement(session, organizationId, options.feature, options.claim),
+			organizationId
+		};
+	};
+	return defineController(read(), (state) => {
+		const recheck = () => {
+			state.set(read());
+		};
+		return {
+			actions: { recheck },
+			start: () => {
+				recheck();
+				return options.auth.subscribe(recheck);
+			}
+		};
+	});
+}
+//#endregion
+export { hasEntitlement as n, createFeatureGateController as t };