@btst/stack 5.1.0 → 5.2.0

package/src/plugins/affiliate/attribution.ts

@@ -0,0 +1,138 @@
+import type { AffiliateOptions, ReferralClick } from "./types";
+
+export const AFFILIATE_COOKIE_NAME = "btst_affiliate";
+
+/** Only local absolute paths are accepted; URL parsing also catches encoded authority paths. */
+export function safeLandingPath(value = "/"): string {
+	let decoded: string;
+	try {
+		decoded = decodeURIComponent(value);
+	} catch {
+		throw new Error("Invalid landing path");
+	}
+	if (
+		!decoded.startsWith("/") ||
+		decoded.startsWith("//") ||
+		/[\\\u0000-\u0020\u007f]/.test(decoded)
+	) {
+		throw new Error("Landing path must be a local absolute path");
+	}
+	const parsed = new URL(value, "https://affiliate.invalid");
+	if (
+		parsed.origin !== "https://affiliate.invalid" ||
+		parsed.pathname.startsWith("//") ||
+		decodeURIComponent(parsed.pathname).startsWith("//")
+	)
+		throw new Error("Invalid landing path");
+	return parsed.pathname + parsed.search + parsed.hash;
+}
+
+export function referralCodeFromURL(
+	url: string | URL,
+	parameters = ["ref", "affiliate"],
+): string | null {
+	const parsed =
+		typeof url === "string" ? new URL(url, "https://affiliate.invalid") : url;
+	for (const name of parameters) {
+		const value = parsed.searchParams.get(name);
+		if (value) return value;
+	}
+	return null;
+}
+
+export function isClickWithinWindow(
+	click: Pick<ReferralClick, "createdAt">,
+	days = 30,
+	now = new Date(),
+): boolean {
+	const age = now.getTime() - new Date(click.createdAt).getTime();
+	return Number.isFinite(age) && age >= 0 && age < days * 86400000;
+}
+
+/** The caller must load the previous opaque cookie click ID from the database first. */
+export function selectAttributionClick(
+	previous: ReferralClick | null,
+	current: ReferralClick,
+	options: AffiliateOptions = {},
+): ReferralClick {
+	return options.attributionMode === "first_touch" &&
+		previous &&
+		isClickWithinWindow(previous, options.attributionWindowDays)
+		? previous
+		: current;
+}
+
+export function createReferralLink(
+	baseURL: string,
+	code: string,
+	landingPath = "/",
+): string {
+	const base = new URL(baseURL);
+	if (!["https:", "http:"].includes(base.protocol))
+		throw new Error("Referral links require HTTP or HTTPS");
+	const url = new URL(safeLandingPath(landingPath), base.origin);
+	url.searchParams.set("ref", code);
+	return url.href;
+}
+
+/** Checkout helpers resolve query codes or opaque click IDs; timestamps always come from the database. */
+export function attributionFromRequest(
+	request: Request,
+): { code?: string; clickId?: string } | undefined {
+	const code = referralCodeFromURL(request.url);
+	if (code) return { code };
+	for (const cookie of (request.headers.get("cookie") ?? "").split(";")) {
+		const separator = cookie.indexOf("=");
+		if (
+			separator < 0 ||
+			cookie.slice(0, separator).trim() !== AFFILIATE_COOKIE_NAME
+		)
+			continue;
+		try {
+			const clickId = decodeURIComponent(cookie.slice(separator + 1).trim());
+			return clickId ? { clickId } : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+export function createTrackingLink(
+	apiBaseURL: string,
+	code: string,
+	landingPath = "/",
+): string {
+	if (
+		!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(code) ||
+		code.length < 3 ||
+		code.length > 64
+	)
+		throw new Error("Invalid affiliate code");
+	const base = new URL(apiBaseURL);
+	if (!["http:", "https:"].includes(base.protocol))
+		throw new Error("Tracking links require HTTP or HTTPS");
+	const url = new URL(
+		`${base.pathname.replace(/\/$/, "")}/affiliate/track/${encodeURIComponent(code)}`,
+		base.origin,
+	);
+	url.searchParams.set("to", safeLandingPath(landingPath));
+	return url.href;
+}
+
+/** Redirect query-param referrals through tracking once, then return to the landing page without referral params. */
+export function getReferralRedirect(
+	value: string | URL,
+	apiBaseURL: string,
+): string | null {
+	const url = new URL(value);
+	const code = referralCodeFromURL(url);
+	if (!code) return null;
+	url.searchParams.delete("ref");
+	url.searchParams.delete("affiliate");
+	return createTrackingLink(
+		apiBaseURL,
+		code,
+		url.pathname + url.search + url.hash,
+	);
+}

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

@@ -0,0 +1,8 @@
+export {
+	AffiliatesPageComponent,
+	AffiliateDetailPageComponent,
+	CommissionsPageComponent,
+	PayoutsPageComponent,
+	AffiliateApplyPageComponent,
+	AffiliatePortalPageComponent,
+} from "./pages";

package/src/plugins/affiliate/client/components/pages/affiliate-apply-page.internal.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import {
+	useIdentity,
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import { useApplyAffiliate } from "../../hooks";
+import { AFFILIATE_PLUGIN_ID } from "../../constants";
+import type { AffiliatePluginOverrides } from "../../overrides";
+import {
+	ActionNotice,
+	AffiliatePage,
+	ProfileFields,
+	readProfile,
+	useAffiliateAction,
+} from "../shared";
+
+export function AffiliateApplyPage() {
+	const { identity } = useIdentity();
+	const [applied, setApplied] = useState(false);
+	const apply = useApplyAffiliate();
+	const action = useAffiliateAction();
+	const { Link, resolve } = usePluginSiteNavigation(AFFILIATE_PLUGIN_ID);
+	const { localization } =
+		usePluginOverrides<AffiliatePluginOverrides>(AFFILIATE_PLUGIN_ID);
+	const save = (event: FormEvent<HTMLFormElement>) => {
+		event.preventDefault();
+		const fields = new FormData(event.currentTarget);
+		void action.run(async () => {
+			await apply.mutateAsync(readProfile(fields));
+			setApplied(true);
+		}, "Application submitted");
+	};
+	return (
+		<AffiliatePage
+			title={localization?.apply ?? "Become an affiliate"}
+			description="Apply for a referral code and earn commissions on attributed conversions after approval."
+			admin={false}
+		>
+			<div className="affiliate-application">
+				<ActionNotice {...action} />
+				{applied ? (
+					<section className="affiliate-stack">
+						<h2>Your application is pending review</h2>
+						<p>
+							You can view your status and update your payout details in the
+							affiliate portal.
+						</p>
+						<Link
+							className="affiliate-primary"
+							href={resolve("affiliate/portal").href}
+						>
+							Open affiliate portal
+						</Link>
+					</section>
+				) : (
+					<form className="affiliate-stack" onSubmit={save}>
+						<fieldset disabled={action.pending}>
+							<ProfileFields
+								defaults={{ name: identity?.name, email: identity?.email }}
+							/>
+							<button className="affiliate-primary" type="submit">
+								{action.pending ? "Submitting…" : "Submit application"}
+							</button>
+						</fieldset>
+					</form>
+				)}
+			</div>
+		</AffiliatePage>
+	);
+}

package/src/plugins/affiliate/client/components/pages/affiliate-detail-page.internal.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import type { FormEvent } from "react";
+import { PermissionAccess, usePluginSiteNavigation } from "@btst/stack/context";
+import { affiliatePermissions } from "../../../permissions";
+import type { AffiliateStatus, CommissionType } from "../../../types";
+import {
+	useAffiliate,
+	useDeleteAffiliate,
+	useUpdateAffiliate,
+} from "../../hooks";
+import { AFFILIATE_PLUGIN_ID } from "../../constants";
+import {
+	ActionNotice,
+	AffiliatePage,
+	ProfileFields,
+	readProfile,
+	Stats,
+	Status,
+	useAffiliateAction,
+} from "../shared";
+
+export function AffiliateDetailPage({ id }: { id: string }) {
+	const { data } = useAffiliate(id);
+	const { affiliate, stats } = data;
+	const update = useUpdateAffiliate();
+	const remove = useDeleteAffiliate();
+	const action = useAffiliateAction();
+	const { Link, resolve, navigate } =
+		usePluginSiteNavigation(AFFILIATE_PLUGIN_ID);
+	const facts = {
+		affiliateId: affiliate.id,
+		userId: affiliate.userId,
+		status: affiliate.status,
+	};
+	const save = (event: FormEvent<HTMLFormElement>) => {
+		event.preventDefault();
+		const fields = new FormData(event.currentTarget);
+		const commissionType = String(fields.get("commissionType") ?? "");
+		const commissionValue = String(fields.get("commissionValue") ?? "");
+		void action.run(async () => {
+			if (commissionType && !commissionValue.trim())
+				throw new Error(
+					"Enter a commission value or select the program default.",
+				);
+			await update.mutateAsync({
+				id,
+				data: {
+					...readProfile(fields),
+					status: String(fields.get("status")) as AffiliateStatus,
+					notes: String(fields.get("notes") ?? ""),
+					commissionType: commissionType
+						? (commissionType as CommissionType)
+						: null,
+					commissionValue: commissionType ? Number(commissionValue) : null,
+				},
+			});
+		}, "Affiliate profile saved");
+	};
+	return (
+		<AffiliatePage
+			title={affiliate.name}
+			description={affiliate.email}
+			action={<Status value={affiliate.status} />}
+		>
+			<Link href={resolve("affiliate/admin/affiliates").href}>
+				Back to affiliates
+			</Link>
+			<Stats stats={stats} />
+			<ActionNotice {...action} />
+			<PermissionAccess
+				permission={affiliatePermissions.affiliate.update(facts)}
+			>
+				<form
+					className="affiliate-stack"
+					key={affiliate.updatedAt}
+					onSubmit={save}
+				>
+					<h2>Profile and commission rule</h2>
+					<p className="affiliate-small affiliate-muted">
+						Account: {affiliate.userId}
+					</p>
+					<fieldset disabled={action.pending}>
+						<ProfileFields affiliate={affiliate} admin />
+						<div className="affiliate-actions">
+							<button className="affiliate-primary" type="submit">
+								{action.pending ? "Saving…" : "Save profile"}
+							</button>
+						</div>
+					</fieldset>
+				</form>
+			</PermissionAccess>
+			<PermissionAccess
+				permission={affiliatePermissions.affiliate.delete(facts)}
+			>
+				<section className="affiliate-section affiliate-stack">
+					<h2>Remove affiliate</h2>
+					<p className="affiliate-muted">
+						Only affiliates without conversions, commissions, or payouts can be
+						deleted. Suspend a partner to stop new referrals and preserve their
+						history.
+					</p>
+					<div>
+						<button
+							type="button"
+							disabled={action.pending}
+							onClick={() => {
+								if (
+									window.confirm(
+										`Delete ${affiliate.name}? This removes their affiliate profile.`,
+									)
+								)
+									void action.run(async () => {
+										await remove.mutateAsync(id);
+										await navigate("affiliate/admin/affiliates");
+									});
+							}}
+						>
+							Delete affiliate
+						</button>
+					</div>
+				</section>
+			</PermissionAccess>
+		</AffiliatePage>
+	);
+}

package/src/plugins/affiliate/client/components/pages/affiliate-portal-page.internal.tsx

@@ -0,0 +1,315 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import {
+	PermissionAccess,
+	usePluginOverrides,
+	usePluginSiteNavigation,
+} from "@btst/stack/context";
+import { affiliatePermissions } from "../../../permissions";
+import {
+	useAffiliateDashboard,
+	useReferralLink,
+	useUpdateAffiliateProfile,
+} from "../../hooks";
+import { AFFILIATE_PLUGIN_ID } from "../../constants";
+import type { AffiliatePluginOverrides } from "../../overrides";
+import {
+	ActionNotice,
+	AffiliatePage,
+	Field,
+	ProfileFields,
+	readProfile,
+	Stats,
+	Status,
+	date,
+	money,
+	useAffiliateAction,
+} from "../shared";
+
+function assetHref(value: string) {
+	try {
+		const url = new URL(value, window.location.origin);
+		return ["https:", "http:"].includes(url.protocol) ? url.href : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function AffiliatePortalPage() {
+	const { data } = useAffiliateDashboard();
+	const [landingPath, setLandingPath] = useState("/");
+	const [link, setLink] = useState("");
+	const [editing, setEditing] = useState(false);
+	const createLink = useReferralLink();
+	const update = useUpdateAffiliateProfile();
+	const action = useAffiliateAction();
+	const { Link, resolve } = usePluginSiteNavigation(AFFILIATE_PLUGIN_ID);
+	const { localization } =
+		usePluginOverrides<AffiliatePluginOverrides>(AFFILIATE_PLUGIN_ID);
+	const { affiliate, stats, commissions, payouts, assets } = data;
+	const save = (event: FormEvent<HTMLFormElement>) => {
+		event.preventDefault();
+		const fields = new FormData(event.currentTarget);
+		void action.run(async () => {
+			await update.mutateAsync(readProfile(fields));
+			setEditing(false);
+			setLink("");
+		}, "Profile saved");
+	};
+	if (!affiliate)
+		return (
+			<AffiliatePage
+				title={localization?.portal ?? "Affiliate portal"}
+				admin={false}
+			>
+				<section className="affiliate-stack">
+					<h2>Start with an affiliate application</h2>
+					<p>
+						Apply to receive a referral code and track your commissions here.
+					</p>
+					<div>
+						<Link
+							className="affiliate-primary"
+							href={resolve("affiliate/apply").href}
+						>
+							Apply to become an affiliate
+						</Link>
+					</div>
+				</section>
+			</AffiliatePage>
+		);
+	return (
+		<AffiliatePage
+			title={localization?.portal ?? "Affiliate portal"}
+			description={`Referral activity and earnings for ${affiliate.name}.`}
+			admin={false}
+			action={<Status value={affiliate.status} />}
+		>
+			<ActionNotice {...action} />
+			{affiliate.status !== "approved" && (
+				<p className="affiliate-notice">
+					{affiliate.status === "pending"
+						? "Your application is pending review. Referral tracking starts after approval."
+						: "Your affiliate account is suspended. New referrals are not attributed. Contact the program administrator for help."}
+				</p>
+			)}
+			<Stats stats={stats} />
+			<section className="affiliate-section affiliate-stack">
+				<h2>Your referral link</h2>
+				<p className="affiliate-muted">
+					Code: <strong>{affiliate.code}</strong>. Choose a landing page on this
+					site. Visits through your link are recorded before the visitor reaches
+					that page.
+				</p>
+				<form
+					className="affiliate-toolbar"
+					onSubmit={(event) => {
+						event.preventDefault();
+						void action.run(async () => {
+							const next = createLink(affiliate.code, landingPath);
+							setLink(next);
+						}, "Referral link generated");
+					}}
+				>
+					<Field
+						label="Landing page path"
+						hint="For example, /pricing or /products?category=books."
+					>
+						<input
+							value={landingPath}
+							onChange={(event) => {
+								setLandingPath(event.target.value);
+								setLink("");
+							}}
+							required
+							placeholder="/pricing"
+						/>
+					</Field>
+					<button
+						type="submit"
+						className="affiliate-primary"
+						disabled={affiliate.status !== "approved"}
+					>
+						Generate referral link
+					</button>
+				</form>
+				{link && (
+					<div className="affiliate-toolbar">
+						<Field label="Tracking link">
+							<input
+								readOnly
+								value={link}
+								onFocus={(event) => event.target.select()}
+							/>
+						</Field>
+						<button
+							type="button"
+							onClick={() =>
+								void action.run(async () => {
+									await navigator.clipboard.writeText(link);
+								}, "Referral link copied")
+							}
+						>
+							Copy referral link
+						</button>
+					</div>
+				)}
+			</section>
+			{assets.length > 0 && (
+				<section className="affiliate-section affiliate-stack">
+					<h2>Marketing assets</h2>
+					<ul className="affiliate-assets">
+						{assets.map((asset) => (
+							<li key={`${asset.name}-${asset.url}`}>
+								<strong>{asset.name}</strong>
+								{asset.description && (
+									<p className="affiliate-muted">{asset.description}</p>
+								)}
+								<div className="affiliate-actions">
+									{assetHref(asset.url) && (
+										<a
+											href={assetHref(asset.url)}
+											target="_blank"
+											rel="noreferrer"
+										>
+											Open link template
+										</a>
+									)}
+									{asset.bannerUrl && assetHref(asset.bannerUrl) && (
+										<a
+											href={assetHref(asset.bannerUrl)}
+											target="_blank"
+											rel="noreferrer"
+										>
+											Open banner
+										</a>
+									)}
+								</div>
+							</li>
+						))}
+					</ul>
+				</section>
+			)}
+			<section className="affiliate-section affiliate-stack">
+				<h2>Commissions</h2>
+				{commissions.length === 0 ? (
+					<p className="affiliate-muted">
+						Your commissions will appear after an attributed conversion.
+					</p>
+				) : (
+					<div
+						className="affiliate-table-scroll"
+						role="region"
+						aria-label="Your commissions"
+						tabIndex={0}
+					>
+						<table>
+							<caption className="affiliate-sr-only">
+								Your commission history
+							</caption>
+							<thead>
+								<tr>
+									<th>Date</th>
+									<th>Conversion</th>
+									<th className="affiliate-number">Amount</th>
+									<th>Status</th>
+								</tr>
+							</thead>
+							<tbody>
+								{commissions.map((commission) => (
+									<tr key={commission.id}>
+										<td>{date(commission.createdAt)}</td>
+										<td>{commission.conversionId}</td>
+										<td className="affiliate-number">
+											{money(commission.amount, commission.currency)}
+										</td>
+										<td>
+											<Status value={commission.status} />
+										</td>
+									</tr>
+								))}
+							</tbody>
+						</table>
+					</div>
+				)}
+			</section>
+			<section className="affiliate-section affiliate-stack">
+				<h2>Payout history</h2>
+				{payouts.length === 0 ? (
+					<p className="affiliate-muted">
+						Payouts appear when the program administrator creates a payment
+						batch.
+					</p>
+				) : (
+					<div
+						className="affiliate-table-scroll"
+						role="region"
+						aria-label="Your payouts"
+						tabIndex={0}
+					>
+						<table>
+							<caption className="affiliate-sr-only">
+								Your payout history
+							</caption>
+							<thead>
+								<tr>
+									<th>Date</th>
+									<th className="affiliate-number">Amount</th>
+									<th>Status</th>
+									<th>Reference</th>
+								</tr>
+							</thead>
+							<tbody>
+								{payouts.map((payout) => (
+									<tr key={payout.id}>
+										<td>{date(payout.paidAt ?? payout.createdAt)}</td>
+										<td className="affiliate-number">
+											{money(payout.amount, payout.currency)}
+										</td>
+										<td>
+											<Status value={payout.status} />
+										</td>
+										<td>{payout.reference || "No reference"}</td>
+									</tr>
+								))}
+							</tbody>
+						</table>
+					</div>
+				)}
+			</section>
+			<PermissionAccess permission={affiliatePermissions.portal.update()}>
+				<section className="affiliate-section affiliate-stack">
+					<div className="affiliate-section-heading">
+						<div>
+							<h2>Profile and payout details</h2>
+							<p className="affiliate-muted">{affiliate.email}</p>
+						</div>
+						<button type="button" onClick={() => setEditing(!editing)}>
+							{editing ? "Close profile" : "Edit profile"}
+						</button>
+					</div>
+					{editing && (
+						<form
+							key={affiliate.updatedAt}
+							className="affiliate-stack"
+							onSubmit={save}
+						>
+							<fieldset disabled={action.pending}>
+								<ProfileFields affiliate={affiliate} />
+								<div className="affiliate-actions">
+									<button type="submit" className="affiliate-primary">
+										{action.pending ? "Saving…" : "Save profile"}
+									</button>
+									<button type="button" onClick={() => setEditing(false)}>
+										Cancel
+									</button>
+								</div>
+							</fieldset>
+						</form>
+					)}
+				</section>
+			</PermissionAccess>
+		</AffiliatePage>
+	);
+}