@btst/stack 5.0.0 → 5.2.0

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

@@ -0,0 +1,177 @@
+"use client";
+
+import type { ReactNode } from "react";
+import {
+	PermissionAccess,
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import type { FallbackProps } from "@btst/stack/client/components";
+import { Button } from "@workspace/ui/components/button";
+import { Label } from "@workspace/ui/components/label";
+import { newsletterPermissions } from "../../permissions";
+import { NEWSLETTER_PLUGIN_ID } from "../constants";
+import type { NewsletterPluginOverrides } from "../overrides";
+
+export function NewsletterPage({
+	title,
+	description,
+	action,
+	children,
+}: {
+	title: string;
+	description?: string;
+	action?: ReactNode;
+	children: ReactNode;
+}) {
+	const { Link, resolve } = usePluginSiteNavigation(NEWSLETTER_PLUGIN_ID);
+	const { localization } =
+		usePluginOverrides<NewsletterPluginOverrides>(NEWSLETTER_PLUGIN_ID);
+	return (
+		<div
+			className="container mx-auto min-w-0 max-w-6xl space-y-8 px-4 py-6 sm:px-6 sm:py-8"
+			data-testid="newsletter-page"
+		>
+			<header className="flex flex-wrap items-start justify-between gap-4">
+				<div className="min-w-0 space-y-2">
+					<h1 className="break-words text-3xl font-semibold tracking-tight">
+						{title}
+					</h1>
+					{description && (
+						<p className="max-w-2xl text-muted-foreground">{description}</p>
+					)}
+				</div>
+				{action}
+			</header>
+			<nav
+				aria-label="Newsletter"
+				className="flex gap-6 border-b pb-3 text-sm font-medium"
+			>
+				<PermissionAccess
+					permission={newsletterPermissions.campaign.read({
+						scope: "collection",
+					})}
+				>
+					<Link
+						href={resolve("newsletter/campaigns").href}
+						className="rounded-sm hover:underline focus-visible:outline-2 focus-visible:outline-ring"
+					>
+						{localization?.campaigns ?? "Campaigns"}
+					</Link>
+				</PermissionAccess>
+				<PermissionAccess
+					permission={newsletterPermissions.subscriber.read({
+						scope: "collection",
+					})}
+				>
+					<Link
+						href={resolve("newsletter/subscribers").href}
+						className="rounded-sm hover:underline focus-visible:outline-2 focus-visible:outline-ring"
+					>
+						{localization?.subscribers ?? "Subscribers"}
+					</Link>
+				</PermissionAccess>
+			</nav>
+			{children}
+		</div>
+	);
+}
+
+export function Field({
+	id,
+	label,
+	children,
+	hint,
+}: {
+	id: string;
+	label: 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 function NewsletterLoading() {
+	return (
+		<div className="p-8" role="status">
+			Loading newsletter…
+		</div>
+	);
+}
+
+export function NewsletterError({ resetErrorBoundary }: FallbackProps) {
+	return (
+		<div className="space-y-4 p-8" role="alert">
+			<h1 className="text-2xl font-semibold">Newsletter unavailable</h1>
+			<p>
+				Newsletter information could not be loaded. Check your access or try
+				again.
+			</p>
+			<Button variant="outline" onClick={resetErrorBoundary}>
+				Retry loading
+			</Button>
+		</div>
+	);
+}
+
+export function NewsletterNotFound({ message }: { message: string }) {
+	return (
+		<div className="space-y-2 p-8">
+			<h1 className="text-2xl font-semibold">Campaign not found</h1>
+			<p>{message}</p>
+		</div>
+	);
+}
+
+export function Status({ value }: { value: string }) {
+	return (
+		<span className="inline-flex rounded-md border px-2 py-1 text-xs font-medium">
+			{value.charAt(0).toUpperCase() + value.slice(1)}
+		</span>
+	);
+}
+
+export const selectClass =
+	"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 Pagination({
+	offset,
+	total,
+	onChange,
+}: {
+	offset: number;
+	total: number;
+	onChange: (offset: number) => void;
+}) {
+	return (
+		<div className="flex flex-wrap items-center justify-between gap-3 text-sm">
+			<p className="text-muted-foreground">
+				{total === 0
+					? "No results"
+					: `${offset + 1}–${Math.min(offset + 25, total)} of ${total}`}
+			</p>
+			<div className="flex gap-2">
+				<Button
+					variant="outline"
+					disabled={offset === 0}
+					onClick={() => onChange(Math.max(0, offset - 25))}
+				>
+					Previous page
+				</Button>
+				<Button
+					variant="outline"
+					disabled={offset + 25 >= total}
+					onClick={() => onChange(offset + 25)}
+				>
+					Next page
+				</Button>
+			</div>
+		</div>
+	);
+}

package/src/plugins/newsletter/client/components/subscribe-form.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import { useId, useState, type FormEvent } from "react";
+import {
+	createApiClient,
+	isErrorResponse,
+	toError,
+} from "@btst/stack/plugins/client";
+import { Button } from "@workspace/ui/components/button";
+import { Input } from "@workspace/ui/components/input";
+import { Label } from "@workspace/ui/components/label";
+
+/** Standalone public subscription form; a StackProvider is not required. */
+export interface SubscribeFormProps {
+	/** Origin of the newsletter API; an empty string uses the current origin. */
+	apiBaseURL: string;
+	/** Mount path of the backend stack, such as /api/data. */
+	apiBasePath: string;
+	/** Tags assigned to subscriptions from this form. */
+	tags?: string[];
+	/** Called after the API accepts the subscription request. */
+	onSuccess?: () => void;
+	/** Optional wrapper class for embedding in an existing page. */
+	className?: string;
+}
+
+export function SubscribeForm({
+	apiBaseURL,
+	apiBasePath,
+	tags = [],
+	onSuccess,
+	className,
+}: SubscribeFormProps) {
+	const id = useId();
+	const [pending, setPending] = useState(false);
+	const [message, setMessage] = useState("");
+	const [error, setError] = useState("");
+	const submit = async (event: FormEvent<HTMLFormElement>) => {
+		event.preventDefault();
+		const form = event.currentTarget;
+		const data = new FormData(form);
+		setPending(true);
+		setError("");
+		setMessage("");
+		try {
+			const client = createApiClient({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			});
+			const response = await client(
+				"@post/newsletter/subscribe" as never,
+				{
+					method: "POST",
+					body: {
+						email: String(data.get("email")),
+						name: String(data.get("name") || "") || undefined,
+						tags,
+					},
+				} as never,
+			);
+			if (isErrorResponse(response)) throw toError(response);
+			const result = response as unknown as { message?: string };
+			setMessage(
+				result.message ??
+					"You're subscribed. Check your inbox for any confirmation steps.",
+			);
+			form.reset();
+			onSuccess?.();
+		} catch (caught) {
+			setError(
+				caught instanceof Error
+					? caught.message
+					: "Subscription failed. Try again.",
+			);
+		} finally {
+			setPending(false);
+		}
+	};
+	return (
+		<form onSubmit={submit} className={className ?? "space-y-4"}>
+			<div className="space-y-2">
+				<Label htmlFor={`${id}-name`}>Name (optional)</Label>
+				<Input
+					id={`${id}-name`}
+					name="name"
+					autoComplete="name"
+					maxLength={200}
+				/>
+			</div>
+			<div className="space-y-2">
+				<Label htmlFor={`${id}-email`}>Email address</Label>
+				<Input
+					id={`${id}-email`}
+					name="email"
+					type="email"
+					required
+					autoComplete="email"
+					maxLength={254}
+				/>
+			</div>
+			<Button type="submit" disabled={pending}>
+				{pending ? "Subscribing…" : "Subscribe"}
+			</Button>
+			{message && (
+				<p role="status" className="text-sm">
+					{message}
+				</p>
+			)}
+			{error && (
+				<p role="alert" className="text-sm text-destructive">
+					{error}
+				</p>
+			)}
+		</form>
+	);
+}

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

@@ -0,0 +1 @@
+export const NEWSLETTER_PLUGIN_ID = "newsletter" as const;

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

@@ -0,0 +1,74 @@
+"use client";
+
+import { useIdentity, useIdentitySourceGeneration } from "@btst/stack/context";
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import {
+	newsletterResources,
+	type SubscriberListParams,
+} from "../../query-keys";
+import { NEWSLETTER_PLUGIN_ID } from "../constants";
+
+const newsletter = createResource({
+	plugin: NEWSLETTER_PLUGIN_ID,
+	resources: newsletterResources,
+});
+
+function useNewsletterIdentity() {
+	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;
+}
+
+/** Fetch one subscriber page scoped to the current identity. */
+export const useSubscribers = (params: SubscriberListParams = {}) =>
+	newsletter.newsletterSubscribers.list.useSuspense([
+		params,
+		useNewsletterIdentity(),
+	]);
+/** Fetch one campaign page scoped to the current identity. */
+export const useCampaigns = (
+	params: { limit?: number; offset?: number } = {},
+) =>
+	newsletter.newsletterCampaigns.list.useSuspense([
+		params,
+		useNewsletterIdentity(),
+	]);
+/** Fetch a campaign's editable sender, content and audience. */
+export const useCampaign = (id: string) =>
+	newsletter.newsletterCampaigns.detail.useSuspense([
+		id,
+		useNewsletterIdentity(),
+	]);
+/** Fetch unique recipient engagement for one campaign. */
+export const useCampaignStats = (id: string) =>
+	newsletter.newsletterCampaigns.stats.useSuspense([
+		id,
+		useNewsletterIdentity(),
+	]);
+/** Fetch subscriber counts and daily growth. */
+export const useSubscriberGrowth = () =>
+	newsletter.newsletterGrowth.list.useSuspense([useNewsletterIdentity()]);
+export const useCreateSubscriber = () =>
+	newsletter.newsletterSubscribers.create.use();
+export const useUpdateSubscriber = () =>
+	newsletter.newsletterSubscribers.update.use();
+export const useDeleteSubscriber = () =>
+	newsletter.newsletterSubscribers.delete.use();
+export const useImportSubscribers = () =>
+	newsletter.newsletterSubscribers.import.use();
+export const useSubscriberExport = () =>
+	newsletter.newsletterSubscribers.export.use([useNewsletterIdentity()], {
+		enabled: false,
+	});
+export const useCreateCampaign = () =>
+	newsletter.newsletterCampaigns.create.use();
+export const useUpdateCampaign = () =>
+	newsletter.newsletterCampaigns.update.use();
+export const useDeleteCampaign = () =>
+	newsletter.newsletterCampaigns.delete.use();
+export const useSendCampaign = () => newsletter.newsletterCampaigns.send.use();
+export const useTestCampaign = () => newsletter.newsletterCampaigns.test.use();
+export const useScheduleCampaign = () =>
+	newsletter.newsletterCampaigns.schedule.use();

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

@@ -0,0 +1,5 @@
+export { newsletterClientPlugin } from "./plugin";
+export type { NewsletterClientConfig, NewsletterLoaderContext } from "./plugin";
+export type { NewsletterPluginOverrides } from "./overrides";
+export { SubscribeForm } from "./components/subscribe-form";
+export type { SubscribeFormProps } from "./components/subscribe-form";

package/src/plugins/newsletter/client/overrides.ts

@@ -0,0 +1,12 @@
+/** Newsletter-specific presentation options; shared services come from StackProvider. */
+export interface NewsletterPluginOverrides {
+	/** Upload images inserted into a campaign's rich text editor. */
+	uploadImage?: (file: File) => Promise<string>;
+	/** Override navigation and page heading labels. */
+	localization?: Partial<{
+		title: string;
+		campaigns: string;
+		subscribers: string;
+		newCampaign: string;
+	}>;
+}

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

@@ -0,0 +1,194 @@
+import { lazy, type ComponentType } from "react";
+import { defineRoute, defineRoutes } from "@btst/yar";
+import {
+	createApiClient,
+	createSanitizedSSRLoaderError,
+	defineClientPlugin,
+	isConnectionError,
+} from "@btst/stack/plugins/client";
+import {
+	createNewsletterQueryKeys,
+	type NewsletterIdentityPartition,
+} from "../query-keys";
+import { NEWSLETTER_PLUGIN_ID } from "./constants";
+import type { NewsletterPluginOverrides } from "./overrides";
+
+const Subscribers = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.SubscribersPageComponent,
+	})),
+);
+const Campaigns = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CampaignsPageComponent,
+	})),
+);
+const Editor = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.EditCampaignPageComponent,
+	})),
+);
+const Stats = lazy(() =>
+	import("./components/pages").then((m) => ({
+		default: m.CampaignStatsPageComponent,
+	})),
+);
+
+/** Server loader lifecycle context for a newsletter management route. */
+export interface NewsletterLoaderContext {
+	path: string;
+	isSSR: boolean;
+}
+/** Newsletter page customization; shared API and site settings come from createClientStack. */
+export interface NewsletterClientConfig {
+	/** Match the current identity when hydrating protected server query data. */
+	identityPartition?: NewsletterIdentityPartition;
+	/** Lifecycle callbacks for server-side route prefetching. */
+	hooks?: {
+		beforeLoad?: (context: NewsletterLoaderContext) => void | Promise<void>;
+		afterLoad?: (context: NewsletterLoaderContext) => void | Promise<void>;
+		onErrorLoad?: (
+			error: Error,
+			context: NewsletterLoaderContext,
+		) => void | Promise<void>;
+	};
+	/** Replace individual built-in management pages. */
+	pageComponents?: {
+		subscribers?: ComponentType;
+		campaigns?: ComponentType;
+		newCampaign?: ComponentType;
+		editCampaign?: ComponentType<{ params: { id: string } }>;
+		campaignStats?: ComponentType<{ params: { id: string } }>;
+	};
+}
+
+/** Subscriber and campaign management routes with identity-partitioned SSR loaders. */
+export const newsletterClientPlugin = (config: NewsletterClientConfig = {}) =>
+	defineClientPlugin<NewsletterPluginOverrides>()({
+		id: NEWSLETTER_PLUGIN_ID,
+		resolve: (runtime) => {
+			const queries = createNewsletterQueryKeys(
+				createApiClient({ ...runtime.api }),
+			);
+			const preload =
+				(
+					path: string,
+					entries: {
+						queryKey: readonly unknown[];
+						queryFn: () => Promise<unknown>;
+					}[] = [],
+				) =>
+				async () => {
+					if (typeof window !== "undefined") return;
+					const context = { path, isSSR: true };
+					let error: unknown;
+					try {
+						await config.hooks?.beforeLoad?.(context);
+						await Promise.all(
+							entries.map((entry) =>
+								runtime.queryClient.prefetchQuery({ ...entry, retry: false }),
+							),
+						);
+						error = entries
+							.map(
+								(entry) =>
+									runtime.queryClient.getQueryState(entry.queryKey)?.error,
+							)
+							.find(Boolean);
+						if (!error) await config.hooks?.afterLoad?.(context);
+					} catch (caught) {
+						error = caught;
+						await Promise.all(
+							entries.map((entry) =>
+								runtime.queryClient.prefetchQuery({
+									queryKey: entry.queryKey,
+									queryFn: () => {
+										throw createSanitizedSSRLoaderError();
+									},
+									retry: false,
+									staleTime: 0,
+								}),
+							),
+						);
+					}
+					if (!error) return;
+					if (isConnectionError(error))
+						console.warn(
+							"[btst/newsletter] API unavailable during SSR prefetch.",
+						);
+					try {
+						await config.hooks?.onErrorLoad?.(
+							error instanceof Error ? error : new Error(String(error)),
+							context,
+						);
+					} catch {
+						/* Reporting cannot reject a route loader. */
+					}
+				};
+			const meta = (title: string) => [
+				{ title },
+				{ name: "robots", content: "noindex, nofollow" },
+			];
+			return {
+				routes: () =>
+					defineRoutes(
+						{
+							subscribers: defineRoute("/newsletter/subscribers", {
+								page: Subscribers,
+								loader: preload("/newsletter/subscribers", [
+									queries.newsletterSubscribers.list(
+										{ limit: 25, offset: 0 },
+										config.identityPartition,
+									),
+									queries.newsletterGrowth.list(config.identityPartition),
+								]),
+								meta: () => meta("Subscribers"),
+							}),
+							campaigns: defineRoute("/newsletter/campaigns", {
+								page: Campaigns,
+								loader: preload("/newsletter/campaigns", [
+									queries.newsletterCampaigns.list(
+										{ limit: 25, offset: 0 },
+										config.identityPartition,
+									),
+								]),
+								meta: () => meta("Newsletter campaigns"),
+							}),
+							newCampaign: defineRoute("/newsletter/campaigns/new", {
+								page: () => <Editor />,
+								loader: preload("/newsletter/campaigns/new"),
+								meta: () => meta("New campaign"),
+							}),
+							editCampaign: defineRoute("/newsletter/campaigns/:id", {
+								page: ({ params }) => <Editor id={params.id} />,
+								loader: ({ params }) =>
+									preload(`/newsletter/campaigns/${params.id}`, [
+										queries.newsletterCampaigns.detail(
+											params.id,
+											config.identityPartition,
+										),
+									])(),
+								meta: () => meta("Edit campaign"),
+							}),
+							campaignStats: defineRoute("/newsletter/campaigns/:id/stats", {
+								page: ({ params }) => <Stats id={params.id} />,
+								loader: ({ params }) =>
+									preload(`/newsletter/campaigns/${params.id}/stats`, [
+										queries.newsletterCampaigns.detail(
+											params.id,
+											config.identityPartition,
+										),
+										queries.newsletterCampaigns.stats(
+											params.id,
+											config.identityPartition,
+										),
+									])(),
+								meta: () => meta("Campaign results"),
+							}),
+						},
+						{ pages: config.pageComponents },
+					),
+				sitemap: async () => [],
+			};
+		},
+	});

package/src/plugins/newsletter/client.css

@@ -0,0 +1 @@
+@import "../../components/markdown/style.css";

package/src/plugins/newsletter/db.ts

@@ -0,0 +1,54 @@
+import { createDbPlugin } from "@btst/db";
+
+/** Isolated newsletter tables; tokens are stored as SHA-256 digests. */
+export const newsletterSchema = createDbPlugin("newsletter", {
+	subscriber: {
+		modelName: "newsletterSubscriber",
+		fields: {
+			email: { type: "string", required: true, unique: true },
+			name: { type: "string", required: false },
+			status: { type: "string", defaultValue: "subscribed" },
+			transactionOnly: { type: "boolean", defaultValue: false },
+			tags: { type: "string", defaultValue: "[]" },
+			confirmedAt: { type: "date", required: false },
+			createdAt: { type: "date", defaultValue: () => new Date() },
+			confirmationToken: { type: "string", required: false },
+			confirmationExpiresAt: { type: "date", required: false },
+			confirmationSentAt: { type: "date", required: false },
+		},
+	},
+	campaign: {
+		modelName: "newsletterCampaign",
+		fields: {
+			subject: { type: "string", required: true },
+			fromName: { type: "string", required: true },
+			fromEmail: { type: "string", required: true },
+			replyTo: { type: "string", required: false },
+			body: { type: "string", required: true },
+			format: { type: "string", defaultValue: "markdown" },
+			tags: { type: "string", defaultValue: "[]" },
+			status: { type: "string", defaultValue: "draft" },
+			scheduledAt: { type: "date", required: false },
+			sentAt: { type: "date", required: false },
+			createdAt: { type: "date", defaultValue: () => new Date() },
+			updatedAt: { type: "date", defaultValue: () => new Date() },
+		},
+	},
+	send: {
+		modelName: "newsletterSend",
+		fields: {
+			key: { type: "string", required: true, unique: true },
+			campaignId: { type: "string", required: true },
+			subscriberId: { type: "string", required: true },
+			email: { type: "string", required: true },
+			status: { type: "string", defaultValue: "pending" },
+			trackingToken: { type: "string", required: true, unique: true },
+			unsubscribeToken: { type: "string", required: true, unique: true },
+			links: { type: "string", defaultValue: "[]" },
+			messageId: { type: "string", required: false },
+			sentAt: { type: "date", required: false },
+			openedAt: { type: "date", required: false },
+			clickedAt: { type: "date", required: false },
+		},
+	},
+});

package/src/plugins/newsletter/permissions.ts

@@ -0,0 +1,47 @@
+import { definePermissions, permission } from "@btst/stack/authorization";
+import { z } from "zod";
+
+const subscriberFacts = z.object({
+	subscriberId: z.string(),
+	status: z.enum(["subscribed", "unsubscribed", "bounced"]),
+});
+const campaignFacts = z.object({
+	campaignId: z.string(),
+	status: z.enum(["draft", "scheduled", "sending", "sent"]),
+});
+/** Browser-safe management permissions. Public bearer-token operations validate their own tokens. */
+export const newsletterPermissions = definePermissions("newsletter", {
+	subscriber: {
+		read: permission(
+			z.discriminatedUnion("scope", [
+				z.object({ scope: z.literal("collection") }),
+				z.object({ scope: z.literal("record"), subscriberId: z.string() }),
+			]),
+		),
+		create: permission(),
+		update: permission(subscriberFacts),
+		delete: permission(subscriberFacts),
+		import: permission(),
+		export: permission(),
+		subscribe: permission(),
+		confirm: permission(),
+		unsubscribe: permission(),
+	},
+	campaign: {
+		read: permission(
+			z.discriminatedUnion("scope", [
+				z.object({ scope: z.literal("collection") }),
+				z.object({ scope: z.literal("record"), campaignId: z.string() }),
+			]),
+		),
+		create: permission(),
+		update: permission(campaignFacts),
+		delete: permission(campaignFacts),
+		send: permission(campaignFacts),
+		test: permission(campaignFacts),
+		schedule: permission(campaignFacts),
+	},
+	analytics: { read: permission(), track: permission() },
+	transactional: { send: permission() },
+	scheduler: { run: permission() },
+});