@btst/stack 5.1.0 → 5.2.0

package/src/plugins/calendar/client/components/shared.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { FallbackProps } from "@btst/stack/client/components";
+import { Button } from "@workspace/ui/components/button";
+import { Label } from "@workspace/ui/components/label";
+
+export function CalendarPage({ children }: { children: ReactNode }) {
+	return (
+		<div className="container mx-auto min-w-0 max-w-5xl space-y-8 px-4 py-6 sm:px-6 sm:py-8">
+			{children}
+		</div>
+	);
+}
+
+export function CalendarLoading() {
+	return (
+		<CalendarPage>
+			<p role="status">Loading calendar…</p>
+		</CalendarPage>
+	);
+}
+
+export function CalendarError({ error, resetErrorBoundary }: FallbackProps) {
+	const message =
+		process.env.NODE_ENV === "development" && error instanceof Error
+			? error.message
+			: "Calendar information could not be loaded. Check your link or try again.";
+	return (
+		<CalendarPage>
+			<div role="alert" className="space-y-4">
+				<h1 className="text-2xl font-semibold">Calendar unavailable</h1>
+				<p>{message}</p>
+				<Button
+					className="min-h-11"
+					variant="outline"
+					onClick={resetErrorBoundary}
+				>
+					Retry loading
+				</Button>
+			</div>
+		</CalendarPage>
+	);
+}
+
+export function CalendarNotFound({ message }: { message: string }) {
+	return (
+		<CalendarPage>
+			<h1 className="text-2xl font-semibold">Booking page not found</h1>
+			<p>{message}</p>
+		</CalendarPage>
+	);
+}
+
+export function Field({
+	label,
+	id,
+	children,
+	hint,
+}: {
+	label: string;
+	id: string;
+	children: ReactNode;
+	hint?: string;
+}) {
+	return (
+		<div className="min-w-0 space-y-2">
+			<Label htmlFor={id}>{label}</Label>
+			{children}
+			{hint && <p className="text-sm text-muted-foreground">{hint}</p>}
+		</div>
+	);
+}
+
+export const calendarSelectClass =
+	"border-input bg-background min-h-11 w-full min-w-0 rounded-md border px-3 text-sm focus-visible:outline-2 focus-visible:outline-ring";
+
+export function formatCalendarTime(value: string, timezone: string) {
+	return new Intl.DateTimeFormat(undefined, {
+		dateStyle: "medium",
+		timeStyle: "short",
+		timeZone: timezone,
+	}).format(new Date(value));
+}

package/src/plugins/calendar/client/constants.ts

@@ -0,0 +1 @@
+export const CALENDAR_PLUGIN_ID = "calendar" as const;

package/src/plugins/calendar/client/hooks/index.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import { useIdentity, useIdentitySourceGeneration } from "@btst/stack/context";
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { calendarResources } from "../../query-keys";
+import { CALENDAR_PLUGIN_ID } from "../constants";
+
+const calendar = createResource({
+	plugin: CALENDAR_PLUGIN_ID,
+	resources: calendarResources,
+});
+
+function useCalendarIdentity() {
+	const { identity, isPending, error } = useIdentity();
+	const generation = useIdentitySourceGeneration();
+	if (isPending) return `pending:${generation}` as const;
+	if (error) return `error:${generation}` as const;
+	return identity ?? undefined;
+}
+
+export function useCalendarEvents() {
+	return calendar.calendarEvents.list.useSuspense([useCalendarIdentity()]);
+}
+
+export function useCalendarEvent(id: string) {
+	return calendar.calendarEvents.detail.useSuspense([
+		id,
+		useCalendarIdentity(),
+	]);
+}
+
+export function useCalendarBookings(period: "upcoming" | "past" | "all") {
+	return calendar.calendarBookings.list.useSuspense([
+		period,
+		useCalendarIdentity(),
+	]);
+}
+
+export const usePublicCalendarEvent = (slug: string) =>
+	calendar.calendarPublicEvents.detail.useSuspense([slug]);
+export const useCalendarSlots = (
+	slug: string,
+	date: string,
+	timezone: string,
+) => calendar.calendarSlots.list.use([slug, date, timezone]);
+export const useCalendarBooking = (token: string) =>
+	calendar.calendarBookings.detail.useSuspense([token]);
+export const useCreateCalendarEvent = () =>
+	calendar.calendarEvents.create.use();
+export const useUpdateCalendarEvent = () =>
+	calendar.calendarEvents.update.use();
+export const useDeleteCalendarEvent = () =>
+	calendar.calendarEvents.delete.use();
+export const useCreateCalendarBooking = () =>
+	calendar.calendarBookings.create.use();
+export const useCancelCalendarBooking = () =>
+	calendar.calendarBookings.cancel.use();
+export const useCancelHostCalendarBooking = () =>
+	calendar.calendarBookings.cancelHost.use();

package/src/plugins/calendar/client/index.ts

@@ -0,0 +1,5 @@
+export {
+	calendarClientPlugin,
+	type CalendarClientConfig,
+	type CalendarLoaderContext,
+} from "./plugin";

package/src/plugins/calendar/client/plugin.tsx

@@ -0,0 +1,218 @@
+import {
+	createApiClient,
+	createSanitizedSSRLoaderError,
+	defineClientPlugin,
+	isConnectionError,
+} from "@btst/stack/plugins/client";
+import { defineRoute, defineRoutes } from "@btst/yar";
+import { lazy, type ComponentType } from "react";
+import {
+	createCalendarQueryKeys,
+	type CalendarIdentityPartition,
+} from "../query-keys";
+import { CALENDAR_PLUGIN_ID } from "./constants";
+import type { EventType } from "../types";
+
+const Dashboard = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CalendarDashboardPageComponent,
+	})),
+);
+const Editor = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CalendarEventEditorPageComponent,
+	})),
+);
+const Booking = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CalendarBookingPageComponent,
+	})),
+);
+const Cancellation = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CalendarCancellationPageComponent,
+	})),
+);
+
+/** Server prefetch context; path excludes the site's mounting base path. */
+export interface CalendarLoaderContext {
+	path: string;
+	isSSR: boolean;
+}
+
+/** Calendar page customization; API, site and QueryClient come from the resolved stack. */
+export interface CalendarClientConfig {
+	/** Match the browser identity snapshot so protected SSR data hydrates the same cache. */
+	identityPartition?: CalendarIdentityPartition;
+	/** Server prefetch hooks. Loading errors stay in the query cache for route boundaries. */
+	hooks?: {
+		/** Runs before prefetch; throwing prevents loading the route's data. */
+		beforeLoad?: (context: CalendarLoaderContext) => void | Promise<void>;
+		/** Runs after all of the route's queries have loaded successfully. */
+		afterLoad?: (context: CalendarLoaderContext) => void | Promise<void>;
+		/** Reports a load failure once; reporting errors cannot reject the route loader. */
+		onErrorLoad?: (
+			error: Error,
+			context: CalendarLoaderContext,
+		) => void | Promise<void>;
+	};
+	/** Replace selected built-in pages; parameterized pages receive the route's params. */
+	pageComponents?: {
+		dashboard?: ComponentType;
+		newEvent?: ComponentType;
+		editEvent?: ComponentType<{ params: { id: string } }>;
+		booking?: ComponentType<{ params: { slug: string } }>;
+		cancellation?: ComponentType<{ params: { token: string } }>;
+	};
+}
+
+export const calendarClientPlugin = (config: CalendarClientConfig = {}) =>
+	defineClientPlugin({
+		id: CALENDAR_PLUGIN_ID,
+		resolve: (runtime) => {
+			const queries = createCalendarQueryKeys(
+				createApiClient({
+					baseURL: runtime.api.baseURL,
+					basePath: runtime.api.basePath,
+					headers: runtime.api.headers,
+					credentials: runtime.api.credentials,
+				}),
+			);
+			const preload =
+				(
+					path: string,
+					entries: {
+						queryKey: readonly unknown[];
+						queryFn: () => Promise<unknown>;
+					}[] = [],
+				) =>
+				async () => {
+					if (typeof window !== "undefined") return;
+					const context = { path, isSSR: true };
+					let reported = false;
+					const report = async (error: unknown) => {
+						if (reported) return;
+						reported = true;
+						if (isConnectionError(error))
+							console.warn(
+								"[btst/calendar] API unavailable during SSR prefetch.",
+							);
+						try {
+							await config.hooks?.onErrorLoad?.(
+								error instanceof Error ? error : new Error(String(error)),
+								context,
+							);
+						} catch {
+							// Error reporting cannot cause the loader to reject.
+						}
+					};
+					try {
+						await config.hooks?.beforeLoad?.(context);
+						await Promise.all(
+							entries.map((entry) =>
+								runtime.queryClient.prefetchQuery({ ...entry, retry: false }),
+							),
+						);
+						for (const entry of entries) {
+							const error = runtime.queryClient.getQueryState(
+								entry.queryKey,
+							)?.error;
+							if (error) {
+								await report(error);
+								return;
+							}
+						}
+						await config.hooks?.afterLoad?.(context);
+					} catch (error) {
+						for (const entry of entries) {
+							await runtime.queryClient.prefetchQuery({
+								queryKey: entry.queryKey,
+								queryFn: () => {
+									throw createSanitizedSSRLoaderError();
+								},
+								retry: false,
+								staleTime: 0,
+							});
+						}
+						await report(error);
+					}
+				};
+			const meta = (title: string) => [
+				{ title },
+				{ name: "robots", content: "noindex, nofollow" },
+			];
+			return {
+				routes: () =>
+					defineRoutes(
+						{
+							calendarDashboard: defineRoute("/calendar", {
+								page: Dashboard,
+								loader: preload("/calendar", [
+									queries.calendarEvents.list(config.identityPartition),
+									queries.calendarBookings.list(
+										"upcoming",
+										config.identityPartition,
+									),
+								]),
+								meta: () => meta("Calendar"),
+							}),
+							calendarNewEvent: defineRoute("/calendar/events/new", {
+								page: () => <Editor />,
+								loader: preload("/calendar/events/new"),
+								meta: () => meta("New event type"),
+							}),
+							calendarEditEvent: defineRoute("/calendar/events/:id/edit", {
+								page: ({ params }) => <Editor id={params.id} />,
+								loader: ({ params }) =>
+									preload(`/calendar/events/${params.id}/edit`, [
+										queries.calendarEvents.detail(
+											params.id,
+											config.identityPartition,
+										),
+									])(),
+								meta: () => meta("Edit event type"),
+							}),
+							calendarBooking: defineRoute("/calendar/book/:slug", {
+								page: ({ params }) => <Booking slug={params.slug} />,
+								loader: ({ params }) =>
+									preload(`/calendar/book/${params.slug}`, [
+										queries.calendarPublicEvents.detail(params.slug),
+									])(),
+								meta: ({ params }) => {
+									const event = runtime.queryClient.getQueryData<EventType>(
+										queries.calendarPublicEvents.detail(params.slug).queryKey,
+									);
+									return [
+										{ title: event?.name ?? "Book a time" },
+										{
+											name: "description",
+											content:
+												event?.description ??
+												"Choose an available time to book.",
+										},
+									];
+								},
+							}),
+							calendarCancellation: defineRoute("/calendar/cancel/:token", {
+								page: ({ params }) => <Cancellation token={params.token} />,
+								loader: ({ params }) =>
+									preload(`/calendar/cancel/${params.token}`, [
+										queries.calendarBookings.detail(params.token),
+									])(),
+								meta: () => meta("Manage booking"),
+							}),
+						},
+						{
+							pages: {
+								calendarDashboard: config.pageComponents?.dashboard,
+								calendarNewEvent: config.pageComponents?.newEvent,
+								calendarEditEvent: config.pageComponents?.editEvent,
+								calendarBooking: config.pageComponents?.booking,
+								calendarCancellation: config.pageComponents?.cancellation,
+							},
+						},
+					),
+				sitemap: async () => [],
+			};
+		},
+	});

package/src/plugins/calendar/client.css

@@ -0,0 +1 @@
+/* Calendar uses the shared UI component styles. */

package/src/plugins/calendar/db.ts

@@ -0,0 +1,46 @@
+import { createDbPlugin } from "@btst/db";
+
+export const calendarSchema = createDbPlugin("calendar", {
+	calendarHost: {
+		modelName: "calendarHost",
+		fields: {
+			hostId: { type: "string", required: true, unique: true },
+			lockVersion: { type: "string", required: true },
+		},
+	},
+	calendarEventType: {
+		modelName: "calendarEventType",
+		fields: {
+			hostId: { type: "string", required: true },
+			slug: { type: "string", required: true, unique: true },
+			name: { type: "string", required: true },
+			description: { type: "string", required: true },
+			location: { type: "string", required: true },
+			duration: { type: "number", required: true },
+			capacity: { type: "number", required: true },
+			timezone: { type: "string", required: true },
+			weeklyAvailability: { type: "string", required: true },
+			dateOverrides: { type: "string", required: true },
+			limits: { type: "string", required: true },
+			active: { type: "boolean", required: true },
+			createdAt: { type: "date", required: true },
+			updatedAt: { type: "date", required: true },
+		},
+	},
+	calendarBooking: {
+		modelName: "calendarBooking",
+		fields: {
+			eventTypeId: { type: "string", required: true },
+			hostId: { type: "string", required: true },
+			eventName: { type: "string", required: true },
+			start: { type: "date", required: true },
+			end: { type: "date", required: true },
+			timezone: { type: "string", required: true },
+			name: { type: "string", required: true },
+			email: { type: "string", required: true },
+			status: { type: "string", required: true },
+			cancelToken: { type: "string", required: true, unique: true },
+			createdAt: { type: "date", required: true },
+		},
+	},
+});

package/src/plugins/calendar/permissions.ts

@@ -0,0 +1,24 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+const eventFacts = { eventTypeId: z.string(), hostId: z.string() };
+const hostFacts = { hostId: z.string().optional() };
+const bookingFacts = { bookingId: z.string(), hostId: z.string() };
+
+export const calendarPermissions = definePermissions("calendar", {
+	eventType: {
+		list: permission(z.object(hostFacts)),
+		read: permission(z.object({ ...eventFacts, public: z.boolean() })),
+		create: permission(z.object(hostFacts)),
+		update: permission(z.object(eventFacts)),
+		delete: permission(z.object(eventFacts)),
+	},
+	availability: { read: permission(z.object(eventFacts)) },
+	booking: {
+		list: permission(z.object(hostFacts)),
+		create: permission(z.object(eventFacts)),
+		read: permission(z.object({ ...bookingFacts, tokenValid: z.boolean() })),
+		cancel: permission(z.object({ ...bookingFacts, tokenValid: z.boolean() })),
+		remind: permission(z.object(bookingFacts)),
+	},
+});

package/src/plugins/calendar/query-keys.ts

@@ -0,0 +1,172 @@
+import {
+	createResourceQueryKeys,
+	type ResourceClient,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type { StackIdentity } from "@btst/stack/context";
+import type { Availability, Booking, EventType } from "./types";
+
+/**
+ * Separates protected query caches by identity. Pending/error generations prevent
+ * an unresolved identity from reusing a previous user's management data.
+ */
+export type CalendarIdentityPartition =
+	| StackIdentity
+	| `pending:${number}`
+	| `error:${number}`;
+
+/** Full event configuration for create/update; the server supplies ownership and metadata. */
+export type CalendarEventInput = Omit<
+	EventType,
+	"id" | "hostId" | "createdAt" | "updatedAt"
+>;
+
+/** Booking page slug, selected ISO instant, and attendee details in the viewer's timezone. */
+export interface CalendarBookingInput {
+	slug: string;
+	start: string;
+	timezone: string;
+	name: string;
+	email: string;
+}
+
+/** Availability for the requested date in the viewer's timezone. */
+export type CalendarSlots = Availability;
+
+export const calendarResources = {
+	calendarEvents: {
+		queries: {
+			list: {
+				path: "/calendar/events",
+				key: (identity?: CalendarIdentityPartition) => [identity],
+				select: (data: unknown): EventType[] => data as EventType[],
+			},
+			detail: {
+				path: "/calendar/events/:id",
+				params: (id: string, _identity?: CalendarIdentityPartition) => ({ id }),
+				key: (id: string, identity?: CalendarIdentityPartition) => [
+					id,
+					identity,
+				],
+				select: (data: unknown): EventType => data as EventType,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/calendar/events",
+				method: "POST",
+				input: (data: CalendarEventInput) => ({ body: data }),
+				select: (data: unknown): EventType => data as EventType,
+				invalidates: ["calendarEvents"],
+				refresh: false,
+			},
+			update: {
+				path: "@patch/calendar/events/:id",
+				method: "PATCH",
+				input: ({ id, data }: { id: string; data: CalendarEventInput }) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: unknown): EventType => data as EventType,
+				invalidates: [
+					"calendarEvents",
+					"calendarPublicEvents",
+					"calendarSlots",
+				],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/calendar/events/:id",
+				method: "DELETE",
+				input: (id: string) => ({ params: { id } }),
+				invalidates: [
+					"calendarEvents",
+					"calendarPublicEvents",
+					"calendarSlots",
+				],
+				refresh: false,
+			},
+		},
+	},
+	calendarPublicEvents: {
+		queries: {
+			detail: {
+				path: "/calendar/book/:slug",
+				params: (slug: string) => ({ slug }),
+				select: (data: unknown): EventType => data as EventType,
+			},
+		},
+	},
+	calendarSlots: {
+		queries: {
+			list: {
+				path: "/calendar/book/:slug/slots",
+				params: (slug: string, _date: string, _timezone: string) => ({ slug }),
+				query: (_slug: string, date: string, timezone: string) => ({
+					date,
+					timezone,
+				}),
+				select: (data: unknown): CalendarSlots => data as CalendarSlots,
+			},
+		},
+	},
+	calendarBookings: {
+		queries: {
+			list: {
+				path: "/calendar/bookings",
+				query: (
+					period: "upcoming" | "past" | "all",
+					_identity?: CalendarIdentityPartition,
+				) => ({ period }),
+				key: (
+					period: "upcoming" | "past" | "all",
+					identity?: CalendarIdentityPartition,
+				) => [period, identity],
+				select: (data: unknown): Omit<Booking, "cancelToken">[] =>
+					data as Omit<Booking, "cancelToken">[],
+			},
+			detail: {
+				path: "/calendar/cancel/:token",
+				params: (token: string) => ({ token }),
+				select: (data: unknown): Booking => data as Booking,
+			},
+		},
+		mutations: {
+			create: {
+				path: "@post/calendar/book/:slug",
+				method: "POST",
+				input: ({ slug, ...body }: CalendarBookingInput) => ({
+					params: { slug },
+					body,
+				}),
+				select: (data: unknown): Booking => data as Booking,
+				invalidates: ["calendarSlots", "calendarBookings.list"],
+				refresh: false,
+			},
+			cancelHost: {
+				path: "@post/calendar/bookings/:id/cancel",
+				method: "POST",
+				input: (id: string) => ({ params: { id } }),
+				select: (data: unknown): Omit<Booking, "cancelToken"> =>
+					data as Omit<Booking, "cancelToken">,
+				invalidates: ["calendarSlots", "calendarBookings"],
+				refresh: false,
+			},
+			cancel: {
+				path: "@post/calendar/cancel/:token",
+				method: "POST",
+				input: (token: string) => ({ params: { token } }),
+				select: (data: unknown): Booking => data as Booking,
+				invalidates: ["calendarSlots", "calendarBookings"],
+				refresh: false,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+export function createCalendarQueryKeys(
+	client: ResourceClient,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, calendarResources, headers);
+}