@btst/stack 5.0.0 → 5.2.0

package/src/plugins/newsletter/api/plugin.ts

@@ -0,0 +1,214 @@
+import { createEndpoint, defineBackendPlugin } from "@btst/stack/plugins/api";
+import { z } from "zod";
+import { newsletterSchema } from "../db";
+import {
+	createCampaignSchema,
+	createSubscriberSchema,
+	importSubscribersSchema,
+	listCampaignsSchema,
+	listSubscribersSchema,
+	scheduleCampaignSchema,
+	subscribeSchema,
+	testCampaignSchema,
+	tokenSchema,
+	transactionalEmailSchema,
+	updateCampaignSchema,
+	updateSubscriberSchema,
+} from "../schemas";
+import type { NewsletterPluginHooks } from "../types";
+import type { EmailAdapter } from "./email-adapter";
+import { createNewsletterOperations } from "./operations";
+
+/** Configuration for the newsletter backend plugin. */
+export interface NewsletterBackendOptions {
+	/** Email provider or custom SMTP wrapper. */
+	emailAdapter: EmailAdapter;
+	/** Absolute public API namespace, for example https://example.com/api/data/newsletter. */
+	unsubscribeBaseURL: string;
+	/** Require the subscriber to confirm ownership before campaign delivery. */
+	doubleOptIn?: boolean;
+	/** Sender for confirmation messages; required with double opt-in unless a custom hook sends them. */
+	confirmationFrom?: { email: string; name?: string };
+	/** Post-authorization lifecycle callbacks. Add public subscribe rate limits in onBeforeSubscribe. */
+	hooks?: NewsletterPluginHooks;
+}
+
+/** Subscriber management, campaigns and public bearer-token email actions. */
+export const newsletterBackendPlugin = (options: NewsletterBackendOptions) => {
+	const base = new URL(options.unsubscribeBaseURL);
+	if (
+		!["http:", "https:"].includes(base.protocol) ||
+		base.username ||
+		base.password ||
+		base.search ||
+		base.hash
+	)
+		throw new Error(
+			"unsubscribeBaseURL must be an absolute HTTP(S) API namespace without credentials, query, or fragment",
+		);
+	if (
+		options.doubleOptIn &&
+		!options.confirmationFrom &&
+		!options.hooks?.onConfirmationRequired
+	)
+		throw new Error(
+			"Double opt-in requires confirmationFrom or hooks.onConfirmationRequired",
+		);
+	if (options.confirmationFrom) {
+		z.object({
+			email: z.email(),
+			name: z
+				.string()
+				.max(200)
+				.refine((name) => !/[\r\n]/.test(name))
+				.optional(),
+		}).parse(options.confirmationFrom);
+	}
+	return defineBackendPlugin({
+		id: "newsletter",
+		dbPlugin: newsletterSchema,
+		operations: (adapter) => createNewsletterOperations(adapter, options),
+		routes: (_adapter, _context, operations) => ({
+			listSubscribers: createEndpoint(
+				"/newsletter/subscribers",
+				{ method: "GET", query: listSubscribersSchema, requireRequest: true },
+				operations.listSubscribers.route((ctx) => ctx.query),
+			),
+			getSubscriber: createEndpoint(
+				"/newsletter/subscribers/:id",
+				{ method: "GET", requireRequest: true },
+				operations.getSubscriber.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createSubscriber: createEndpoint(
+				"/newsletter/subscribers",
+				{ method: "POST", body: createSubscriberSchema, requireRequest: true },
+				operations.createSubscriber.route((ctx) => ctx.body),
+			),
+			updateSubscriber: createEndpoint(
+				"/newsletter/subscribers/:id",
+				{ method: "PUT", body: updateSubscriberSchema, requireRequest: true },
+				operations.updateSubscriber.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			deleteSubscriber: createEndpoint(
+				"/newsletter/subscribers/:id",
+				{ method: "DELETE", requireRequest: true },
+				operations.deleteSubscriber.route((ctx) => ({ id: ctx.params.id })),
+			),
+			importSubscribers: createEndpoint(
+				"/newsletter/subscribers/import",
+				{ method: "POST", body: importSubscribersSchema, requireRequest: true },
+				operations.importSubscribers.route((ctx) => ctx.body),
+			),
+			exportSubscribers: createEndpoint(
+				"/newsletter/subscribers/export",
+				{ method: "GET", requireRequest: true },
+				operations.exportSubscribers.route(() => ({})),
+			),
+			subscribe: createEndpoint(
+				"/newsletter/subscribe",
+				{ method: "POST", body: subscribeSchema, requireRequest: true },
+				operations.subscribe.route((ctx) => ctx.body),
+			),
+			confirmSubscription: createEndpoint(
+				"/newsletter/confirm",
+				{ method: "GET", query: tokenSchema, requireRequest: true },
+				operations.confirmSubscription.route((ctx) => ctx.query),
+			),
+			unsubscribe: createEndpoint(
+				"/newsletter/unsubscribe",
+				{ method: "GET", query: tokenSchema, requireRequest: true },
+				operations.unsubscribe.route((ctx) => ctx.query),
+			),
+			listCampaigns: createEndpoint(
+				"/newsletter/campaigns",
+				{ method: "GET", query: listCampaignsSchema, requireRequest: true },
+				operations.listCampaigns.route((ctx) => ctx.query),
+			),
+			getCampaign: createEndpoint(
+				"/newsletter/campaigns/:id",
+				{ method: "GET", requireRequest: true },
+				operations.getCampaign.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createCampaign: createEndpoint(
+				"/newsletter/campaigns",
+				{ method: "POST", body: createCampaignSchema, requireRequest: true },
+				operations.createCampaign.route((ctx) => ctx.body),
+			),
+			updateCampaign: createEndpoint(
+				"/newsletter/campaigns/:id",
+				{ method: "PUT", body: updateCampaignSchema, requireRequest: true },
+				operations.updateCampaign.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			deleteCampaign: createEndpoint(
+				"/newsletter/campaigns/:id",
+				{ method: "DELETE", requireRequest: true },
+				operations.deleteCampaign.route((ctx) => ({ id: ctx.params.id })),
+			),
+			sendCampaign: createEndpoint(
+				"/newsletter/campaigns/:id/send",
+				{ method: "POST", requireRequest: true },
+				operations.sendCampaign.route((ctx) => ({ id: ctx.params.id })),
+			),
+			scheduleCampaign: createEndpoint(
+				"/newsletter/campaigns/:id/schedule",
+				{ method: "POST", body: scheduleCampaignSchema, requireRequest: true },
+				operations.scheduleCampaign.route((ctx) => ({
+					id: ctx.params.id,
+					...ctx.body,
+				})),
+			),
+			sendTestEmail: createEndpoint(
+				"/newsletter/campaigns/:id/test",
+				{ method: "POST", body: testCampaignSchema, requireRequest: true },
+				operations.sendTestEmail.route((ctx) => ({
+					id: ctx.params.id,
+					...ctx.body,
+				})),
+			),
+			getCampaignStats: createEndpoint(
+				"/newsletter/campaigns/:id/stats",
+				{ method: "GET", requireRequest: true },
+				operations.getCampaignStats.route((ctx) => ({ id: ctx.params.id })),
+			),
+			getSubscriberGrowth: createEndpoint(
+				"/newsletter/growth",
+				{ method: "GET", requireRequest: true },
+				operations.getSubscriberGrowth.route(() => ({})),
+			),
+			trackOpen: createEndpoint(
+				"/newsletter/track/open",
+				{ method: "GET", query: tokenSchema, requireRequest: true },
+				operations.trackOpen.route((ctx) => ctx.query),
+			),
+			trackClick: createEndpoint(
+				"/newsletter/track/click",
+				{
+					method: "GET",
+					query: tokenSchema.extend({
+						link: z.coerce.number().int().min(0).max(10000),
+					}),
+					requireRequest: true,
+				},
+				operations.trackClick.route((ctx) => ctx.query),
+			),
+			sendTransactionalEmail: createEndpoint(
+				"/newsletter/send",
+				{
+					method: "POST",
+					body: transactionalEmailSchema,
+					requireRequest: true,
+				},
+				operations.sendTransactionalEmail.route((ctx) => ctx.body),
+			),
+		}),
+	});
+};
+export type NewsletterApiRouter = ReturnType<
+	ReturnType<typeof newsletterBackendPlugin>["routes"]
+>;

package/src/plugins/newsletter/api/serializers.ts

@@ -0,0 +1,41 @@
+import type {
+	Subscriber,
+	SubscriberRecord,
+	Campaign,
+	CampaignRecord,
+} from "../types";
+
+/** Serialize a subscriber without exposing bearer-token digests. */
+export function serializeSubscriber(record: SubscriberRecord): Subscriber {
+	return {
+		id: record.id,
+		email: record.email,
+		name: record.name,
+		status: record.status,
+		tags: JSON.parse(record.tags || "[]"),
+		confirmedAt: record.confirmedAt
+			? new Date(record.confirmedAt).toISOString()
+			: null,
+		createdAt: new Date(record.createdAt).toISOString(),
+	};
+}
+/** Serialize dates and tags for transport. */
+export function serializeCampaign(record: CampaignRecord): Campaign {
+	return {
+		id: record.id,
+		subject: record.subject,
+		fromName: record.fromName,
+		fromEmail: record.fromEmail,
+		replyTo: record.replyTo,
+		body: record.body,
+		format: record.format,
+		tags: JSON.parse(record.tags || "[]"),
+		status: record.status,
+		scheduledAt: record.scheduledAt
+			? new Date(record.scheduledAt).toISOString()
+			: null,
+		sentAt: record.sentAt ? new Date(record.sentAt).toISOString() : null,
+		createdAt: new Date(record.createdAt).toISOString(),
+		updatedAt: new Date(record.updatedAt).toISOString(),
+	};
+}

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

@@ -0,0 +1,8 @@
+export { SubscribeForm } from "./subscribe-form";
+export type { SubscribeFormProps } from "./subscribe-form";
+export {
+	SubscribersPageComponent,
+	CampaignsPageComponent,
+	EditCampaignPageComponent,
+	CampaignStatsPageComponent,
+} from "./pages";

package/src/plugins/newsletter/client/components/markdown-preview.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+export function NewsletterMarkdownPreview({ markdown }: { markdown: string }) {
+	return (
+		<div className="markdown-content">
+			<div className="markdown-inner">
+				<div className="markdown-body">
+					<ReactMarkdown skipHtml remarkPlugins={[remarkGfm]}>
+						{markdown}
+					</ReactMarkdown>
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/plugins/newsletter/client/components/pages/campaign-stats-page.internal.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useCampaign, useCampaignStats } from "../../hooks";
+import { NewsletterPage, Status } from "../shared";
+
+export function CampaignStatsPage({ id }: { id: string }) {
+	const { data: campaign } = useCampaign(id);
+	const { data: stats } = useCampaignStats(id);
+	const metrics = [
+		["Recipients", stats.recipientCount],
+		["Delivered", stats.delivered],
+		["Opened", stats.opened],
+		["Clicked", stats.clicked],
+		["Bounced", stats.bounced],
+		["Failed", stats.failed],
+	] as const;
+	return (
+		<NewsletterPage
+			title={campaign.subject}
+			description="Delivery and engagement for this campaign."
+		>
+			<div className="flex flex-wrap items-center gap-3">
+				<Status value={campaign.status} />
+				{campaign.sentAt && (
+					<p className="text-sm text-muted-foreground">
+						Sent {new Date(campaign.sentAt).toLocaleString()}
+					</p>
+				)}
+			</div>
+			<dl className="grid grid-cols-2 gap-x-8 gap-y-6 border-y py-6 sm:grid-cols-3 lg:grid-cols-6">
+				{metrics.map(([label, value]) => (
+					<div key={label} className="space-y-2">
+						<dt className="text-sm text-muted-foreground">{label}</dt>
+						<dd className="text-3xl font-semibold tabular-nums">
+							{value.toLocaleString()}
+						</dd>
+					</div>
+				))}
+			</dl>
+			<div className="grid gap-8 sm:grid-cols-2">
+				{[
+					["Open rate", stats.openRate],
+					["Click rate", stats.clickRate],
+				].map(([label, value]) => (
+					<div className="space-y-3" key={label}>
+						<div className="flex items-baseline justify-between gap-4">
+							<h2 className="font-medium">{label}</h2>
+							<p className="text-2xl font-semibold tabular-nums">
+								{(Number(value) * 100).toFixed(1)}%
+							</p>
+						</div>
+						<div
+							className="h-2 overflow-hidden rounded-full bg-muted"
+							aria-hidden="true"
+						>
+							<div
+								className="h-full rounded-full bg-primary"
+								style={{
+									width: `${Math.max(0, Math.min(100, Number(value) * 100))}%`,
+								}}
+							/>
+						</div>
+					</div>
+				))}
+			</div>
+			<p className="max-w-2xl text-sm text-muted-foreground">
+				Delivered counts messages accepted by your email provider. Opens and
+				clicks count unique recipients; email privacy settings and image
+				blocking can affect open tracking.
+			</p>
+		</NewsletterPage>
+	);
+}

package/src/plugins/newsletter/client/components/pages/campaigns-page.internal.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import { useState } from "react";
+import {
+	PermissionAccess,
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import { Button } from "@workspace/ui/components/button";
+import { useCampaigns } from "../../hooks";
+import { newsletterPermissions } from "../../../permissions";
+import { NEWSLETTER_PLUGIN_ID } from "../../constants";
+import type { NewsletterPluginOverrides } from "../../overrides";
+import { NewsletterPage, Pagination, Status } from "../shared";
+
+export function CampaignsPage() {
+	const [offset, setOffset] = useState(0);
+	const { data } = useCampaigns({ limit: 25, offset });
+	const { Link, resolve } = usePluginSiteNavigation(NEWSLETTER_PLUGIN_ID);
+	const { localization } =
+		usePluginOverrides<NewsletterPluginOverrides>(NEWSLETTER_PLUGIN_ID);
+	return (
+		<NewsletterPage
+			title={localization?.title ?? "Newsletter"}
+			description="Write to your subscribers. Follow each campaign from first draft to results."
+			action={
+				<PermissionAccess permission={newsletterPermissions.campaign.create()}>
+					<Button asChild>
+						<Link href={resolve("newsletter/campaigns/new").href}>
+							{localization?.newCampaign ?? "New campaign"}
+						</Link>
+					</Button>
+				</PermissionAccess>
+			}
+		>
+			{data.items.length === 0 ? (
+				<div className="space-y-3 py-10">
+					<h2 className="text-xl font-medium">
+						Your first newsletter starts here
+					</h2>
+					<p className="max-w-xl text-muted-foreground">
+						Create a campaign, choose your audience, and send yourself a test
+						before sharing it.
+					</p>
+				</div>
+			) : (
+				<div className="overflow-x-auto rounded-lg border">
+					<table className="w-full min-w-[600px] text-left text-sm">
+						<caption className="sr-only">Newsletter campaigns</caption>
+						<thead className="border-b bg-muted/40">
+							<tr>
+								<th className="p-4 font-medium">Subject</th>
+								<th className="p-4 font-medium">Status</th>
+								<th className="p-4 font-medium">Audience</th>
+								<th className="p-4 font-medium">Results</th>
+							</tr>
+						</thead>
+						<tbody>
+							{data.items.map((campaign) => (
+								<tr key={campaign.id} className="border-b last:border-0">
+									<td className="p-4">
+										<Link
+											className="font-medium underline-offset-4 hover:underline"
+											href={resolve(`newsletter/campaigns/${campaign.id}`).href}
+										>
+											{campaign.subject}
+										</Link>
+										<p className="mt-1 text-xs text-muted-foreground">
+											{campaign.fromName} &lt;{campaign.fromEmail}&gt;
+										</p>
+									</td>
+									<td className="p-4">
+										<Status value={campaign.status} />
+										{campaign.scheduledAt && (
+											<p className="mt-2 text-xs text-muted-foreground">
+												{new Date(campaign.scheduledAt).toLocaleString()}
+											</p>
+										)}
+									</td>
+									<td className="p-4">
+										{campaign.tags.length
+											? campaign.tags.join(", ")
+											: "All subscribers"}
+									</td>
+									<td className="p-4">
+										<PermissionAccess
+											permission={newsletterPermissions.analytics.read()}
+										>
+											<Link
+												className="underline underline-offset-4"
+												href={
+													resolve(`newsletter/campaigns/${campaign.id}/stats`)
+														.href
+												}
+											>
+												View results
+											</Link>
+										</PermissionAccess>
+									</td>
+								</tr>
+							))}
+						</tbody>
+					</table>
+				</div>
+			)}
+			<Pagination offset={offset} total={data.total} onChange={setOffset} />
+		</NewsletterPage>
+	);
+}