@btst/stack 5.1.0 → 5.2.0

package/src/plugins/affiliate/api/operations.ts

@@ -0,0 +1,400 @@
+import type { DBAdapter as Adapter } from "@btst/db";
+import {
+	defineOperation,
+	definePassthroughOperation,
+	OperationHttpError,
+} from "@btst/stack/plugins/api";
+import { z } from "zod";
+import {
+	AFFILIATE_COOKIE_NAME,
+	attributionFromRequest,
+	isClickWithinWindow,
+	safeLandingPath,
+	selectAttributionClick,
+} from "../attribution";
+import { affiliatePermissions as permissions } from "../permissions";
+import {
+	affiliateListSchema,
+	applicationSchema,
+	createAffiliateSchema,
+	createConversionSchema,
+	createPayoutSchema,
+	idSchema,
+	listSchema,
+	trackClickSchema,
+	updateAffiliateSchema,
+	updateCommissionSchema,
+	updatePayoutSchema,
+	updatePortalSchema,
+} from "../schemas";
+import * as getters from "./getters";
+import * as mutations from "./mutations";
+import type { AffiliateBackendOptions } from "./plugin";
+
+function fail(status: number, message: string): never {
+	throw new OperationHttpError(status, message, "AFFILIATE_ERROR");
+}
+
+async function requireAffiliate(adapter: Adapter, id: string) {
+	return (
+		(await getters.getAffiliate(adapter, id)) ??
+		fail(404, "Affiliate not found")
+	);
+}
+
+async function affiliateFacts(adapter: Adapter, id: string) {
+	const affiliate = await requireAffiliate(adapter, id);
+	return {
+		affiliateId: affiliate.id,
+		userId: affiliate.userId,
+		status: affiliate.status,
+	};
+}
+
+function requireIdentity(identity: { readonly id: string } | null): string {
+	return identity?.id ?? fail(401, "Sign in to manage your affiliate profile");
+}
+
+function attributionCookie(request?: Request): string | undefined {
+	const value = request?.headers
+		.get("cookie")
+		?.split(";")
+		.map((entry) => entry.trim())
+		.find((entry) => entry.startsWith(`${AFFILIATE_COOKIE_NAME}=`))
+		?.slice(AFFILIATE_COOKIE_NAME.length + 1);
+	return value && /^[a-zA-Z0-9_-]{1,200}$/.test(value) ? value : undefined;
+}
+
+/** Shared validated operation inventory for HTTP, request scopes, and trusted jobs. */
+export function createAffiliateOperations(
+	adapter: Adapter,
+	options: AffiliateBackendOptions,
+) {
+	return {
+		listAffiliates: defineOperation({
+			input: affiliateListSchema,
+			permission: permissions.affiliate.read,
+			facts: () => ({ scope: "collection" as const }),
+			execute: async ({ input }) => {
+				const result = await getters.listAffiliates(adapter, input);
+				return {
+					...result,
+					items: result.items.map((affiliate) => ({ ...affiliate })),
+				};
+			},
+		}),
+		getAffiliate: defineOperation({
+			input: idSchema,
+			permission: permissions.affiliate.read,
+			facts: ({ input }) => ({
+				scope: "record" as const,
+				affiliateId: input.id,
+			}),
+			execute: async ({ input }) => ({
+				affiliate: { ...(await requireAffiliate(adapter, input.id)) },
+				stats: { ...(await getters.getAffiliateStats(adapter, input.id)) },
+			}),
+		}),
+		createAffiliate: defineOperation({
+			input: createAffiliateSchema,
+			permission: permissions.affiliate.create,
+			facts: () => undefined,
+			execute: async ({ input }) => ({
+				...(await mutations.createAffiliate(adapter, input)),
+			}),
+		}),
+		updateAffiliate: defineOperation({
+			input: idSchema.extend({ data: updateAffiliateSchema }),
+			permission: permissions.affiliate.update,
+			facts: ({ input }) => affiliateFacts(adapter, input.id),
+			before: async (context) => {
+				if (context.input.data.status === "approved")
+					await options.hooks?.onBeforeApproveAffiliate?.(
+						await requireAffiliate(adapter, context.input.id),
+						context,
+					);
+			},
+			execute: async ({ input, facts }) => ({
+				...(await mutations.updateAffiliate(adapter, input.id, input.data, {
+					id: facts.affiliateId,
+					userId: facts.userId,
+					status: facts.status,
+				})),
+			}),
+		}),
+		deleteAffiliate: defineOperation({
+			input: idSchema,
+			permission: permissions.affiliate.delete,
+			facts: ({ input }) => affiliateFacts(adapter, input.id),
+			execute: async ({ input, facts }) => {
+				await mutations.deleteAffiliate(adapter, input.id, {
+					id: facts.affiliateId,
+					userId: facts.userId,
+					status: facts.status,
+				});
+				return { success: true as const };
+			},
+		}),
+		apply: defineOperation({
+			input: applicationSchema,
+			permission: permissions.application.create,
+			facts: () => undefined,
+			execute: async ({ input, identity }) => ({
+				...(await mutations.createAffiliate(adapter, {
+					...input,
+					userId: requireIdentity(identity),
+				})),
+			}),
+		}),
+		getPortal: defineOperation({
+			input: z.object({}),
+			permission: permissions.portal.read,
+			facts: () => undefined,
+			execute: async ({ identity }) => {
+				const portal = await getters.getPortal(
+					adapter,
+					requireIdentity(identity),
+					options.marketingAssets,
+				);
+				return {
+					affiliate: portal.affiliate ? { ...portal.affiliate } : null,
+					stats: { ...portal.stats },
+					commissions: portal.commissions.map((commission) => ({
+						...commission,
+					})),
+					payouts: portal.payouts.map((payout) => ({ ...payout })),
+					assets: portal.assets.map((asset) => ({ ...asset })),
+				};
+			},
+		}),
+		updatePortal: defineOperation({
+			input: updatePortalSchema,
+			permission: permissions.portal.update,
+			facts: () => undefined,
+			execute: async ({ input, identity }) => {
+				const affiliate =
+					(await getters.getAffiliateByUserId(
+						adapter,
+						requireIdentity(identity),
+					)) ?? fail(404, "Apply to the affiliate program first");
+				const updated = await mutations.updateAffiliate(
+					adapter,
+					affiliate.id,
+					input,
+				);
+				const { notes: _notes, ...profile } = updated;
+				return profile;
+			},
+		}),
+		trackClick: definePassthroughOperation({
+			input: trackClickSchema,
+			permission: permissions.tracking.track,
+			access: "public",
+			facts: () => undefined,
+			execute: async ({ input, request }) => {
+				let landingPath: string;
+				try {
+					landingPath = safeLandingPath(input.landingPath);
+				} catch {
+					fail(400, "Landing path must be a local absolute path");
+				}
+				const destination = new URL(
+					landingPath,
+					options.siteOrigin ?? request?.url ?? "https://affiliate.invalid",
+				);
+				const click = await mutations.trackClick(adapter, {
+					...input,
+					landingPath,
+					referrer:
+						request?.headers.get("referer")?.slice(0, 2048) ?? input.referrer,
+					userAgent:
+						request?.headers.get("user-agent")?.slice(0, 2048) ??
+						input.userAgent,
+				});
+				const previousId = attributionCookie(request);
+				const previous = previousId
+					? await getters.getReferralClick(adapter, previousId)
+					: null;
+				const previousAffiliate = previous
+					? await getters.getAffiliate(adapter, previous.affiliateId)
+					: null;
+				const selected = selectAttributionClick(
+					previousAffiliate?.status === "approved" ? previous : null,
+					click,
+					options,
+				);
+				const headers = new Headers({
+					Location: options.siteOrigin
+						? destination.href
+						: destination.pathname + destination.search + destination.hash,
+					"Cache-Control": "no-store, private",
+					"Referrer-Policy": "no-referrer",
+				});
+				if (selected) {
+					const maxAge = Math.max(
+						0,
+						Math.floor(
+							(new Date(selected.createdAt).getTime() +
+								(options.attributionWindowDays ?? 30) * 86400000 -
+								Date.now()) /
+								1000,
+						),
+					);
+					headers.set(
+						"Set-Cookie",
+						`${AFFILIATE_COOKIE_NAME}=${selected.id}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${request && new URL(request.url).protocol === "https:" ? "; Secure" : ""}`,
+					);
+				}
+				return new Response(null, { status: 302, headers });
+			},
+		}),
+		createConversion: defineOperation({
+			input: createConversionSchema,
+			permission: permissions.conversion.create,
+			facts: () => undefined,
+			execute: async ({ input, request }) => {
+				let requestAttribution = request
+					? attributionFromRequest(request)
+					: undefined;
+				if (!input.attribution) {
+					const cookieId = attributionCookie(request);
+					const click = cookieId
+						? await getters.getReferralClick(adapter, cookieId)
+						: null;
+					if (
+						click &&
+						isClickWithinWindow(click, options.attributionWindowDays) &&
+						(await getters.getAffiliate(adapter, click.affiliateId))?.status ===
+							"approved"
+					)
+						requestAttribution = { clickId: click.id };
+				}
+				if (
+					!input.attribution &&
+					!createConversionSchema.shape.attribution.safeParse(
+						requestAttribution,
+					).success
+				)
+					fail(400, "Invalid referral attribution");
+				const result = await mutations.createConversion(
+					adapter,
+					{
+						...input,
+						attribution: input.attribution ?? requestAttribution,
+					},
+					options,
+				);
+				return result
+					? {
+							conversion: { ...result.conversion },
+							commission: { ...result.commission },
+						}
+					: null;
+			},
+			after: async (context) => {
+				if (context.result)
+					await options.hooks?.onAfterConversion?.(
+						context.result.conversion,
+						context.result.commission,
+						context,
+					);
+			},
+		}),
+		listCommissions: defineOperation({
+			input: listSchema,
+			permission: permissions.commission.read,
+			facts: () => undefined,
+			execute: async ({ input }) => {
+				const result = await getters.listCommissions(adapter, input);
+				return {
+					...result,
+					items: result.items.map((commission) => ({ ...commission })),
+				};
+			},
+		}),
+		updateCommission: defineOperation({
+			input: idSchema.extend({ data: updateCommissionSchema }),
+			permission: permissions.commission.update,
+			facts: async ({ input }) => {
+				const commission =
+					(await getters.getCommission(adapter, input.id)) ??
+					fail(404, "Commission not found");
+				return {
+					commissionId: commission.id,
+					affiliateId: commission.affiliateId,
+					status: commission.status,
+				};
+			},
+			execute: async ({ input, facts }) => ({
+				...(await mutations.updateCommission(adapter, input.id, input.data, {
+					id: facts.commissionId,
+					affiliateId: facts.affiliateId,
+					status: facts.status,
+				})),
+			}),
+		}),
+		listPayouts: defineOperation({
+			input: listSchema,
+			permission: permissions.payout.read,
+			facts: () => undefined,
+			execute: async ({ input }) => {
+				const result = await getters.listPayouts(adapter, input);
+				return {
+					...result,
+					items: result.items.map((payout) => ({ ...payout })),
+				};
+			},
+		}),
+		createPayout: defineOperation({
+			input: createPayoutSchema,
+			permission: permissions.payout.create,
+			facts: async ({ input }) => {
+				await requireAffiliate(adapter, input.affiliateId);
+				return { affiliateId: input.affiliateId, currency: input.currency };
+			},
+			before: (context) =>
+				options.hooks?.onBeforePayout?.(context.input, context),
+			execute: async ({ input }) => ({
+				...(await mutations.createPayout(adapter, {
+					...input,
+					commissionIds: input.commissionIds
+						? [...input.commissionIds]
+						: undefined,
+				})),
+			}),
+		}),
+		updatePayout: defineOperation({
+			input: idSchema.extend({ data: updatePayoutSchema }),
+			permission: permissions.payout.update,
+			facts: async ({ input }) => {
+				const payout =
+					(await getters.getPayout(adapter, input.id)) ??
+					fail(404, "Payout not found");
+				return {
+					payoutId: payout.id,
+					affiliateId: payout.affiliateId,
+					status: payout.status,
+				};
+			},
+			execute: async ({ input, facts }) => ({
+				...(await mutations.updatePayout(adapter, input.id, input.data, {
+					id: facts.payoutId,
+					affiliateId: facts.affiliateId,
+					status: facts.status,
+				})),
+			}),
+			after: async (context) => {
+				if (context.result.status === "sent")
+					await options.hooks?.onAfterPayout?.(context.result, context);
+			},
+		}),
+		exportPayouts: defineOperation({
+			input: listSchema,
+			permission: permissions.payout.export,
+			facts: () => undefined,
+			execute: async ({ input }) => ({
+				csv: await getters.exportPayouts(adapter, input),
+			}),
+		}),
+	};
+}

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

@@ -0,0 +1,214 @@
+import {
+	createEndpoint,
+	defineBackendPlugin,
+	type DeepReadonly,
+} from "@btst/stack/plugins/api";
+import { z } from "zod";
+import { calculateCommission } from "../commission";
+import { affiliateSchema } from "../db";
+import {
+	affiliateListSchema,
+	applicationSchema,
+	createAffiliateSchema,
+	createConversionSchema,
+	createPayoutSchema,
+	listSchema,
+	updateAffiliateSchema,
+	updateCommissionSchema,
+	updatePayoutSchema,
+	updatePortalSchema,
+} from "../schemas";
+import type {
+	Affiliate,
+	AffiliateOptions,
+	Commission,
+	Conversion,
+	CreatePayoutInput,
+	Payout,
+} from "../types";
+import { createAffiliateOperations } from "./operations";
+
+/** Authorized request context shared by affiliate lifecycle callbacks. */
+export interface AffiliateHookContext {
+	readonly request?: Request;
+	readonly identity: { readonly id: string } | null;
+}
+
+/** Lifecycle callbacks run after the operation permission is authorized. */
+export interface AffiliatePluginHooks {
+	onBeforeApproveAffiliate?: (
+		affiliate: DeepReadonly<Affiliate>,
+		context: AffiliateHookContext,
+	) => Promise<void> | void;
+	onAfterConversion?: (
+		conversion: DeepReadonly<Conversion>,
+		commission: DeepReadonly<Commission>,
+		context: AffiliateHookContext,
+	) => Promise<void> | void;
+	onBeforePayout?: (
+		batch: DeepReadonly<CreatePayoutInput>,
+		context: AffiliateHookContext,
+	) => Promise<void> | void;
+	onAfterPayout?: (
+		payout: DeepReadonly<Payout>,
+		context: AffiliateHookContext,
+	) => Promise<void> | void;
+}
+
+/** Affiliate attribution, commission rules, marketing assets, and lifecycle callbacks. */
+export interface AffiliateBackendOptions extends AffiliateOptions {
+	hooks?: AffiliatePluginHooks;
+}
+
+/** Processor-independent affiliate operations and identity-scoped portal API. */
+export const affiliateBackendPlugin = (
+	options: AffiliateBackendOptions = {},
+) => {
+	const assetURL = z.url({ protocol: /^https?$/ });
+	z.object({
+		siteOrigin: assetURL
+			.refine((value) => {
+				const url = new URL(value);
+				return (
+					!url.username &&
+					!url.password &&
+					url.pathname === "/" &&
+					!url.search &&
+					!url.hash
+				);
+			}, "siteOrigin must contain only an HTTP(S) origin")
+			.optional(),
+		attributionWindowDays: z.number().int().min(1).max(3650).optional(),
+		attributionMode: z.enum(["first_touch", "last_touch"]).optional(),
+		defaultCommissionType: z.enum(["percent", "flat"]).optional(),
+		defaultCommissionValue: z.number().finite().nonnegative().optional(),
+		marketingAssets: z
+			.array(
+				z.object({
+					name: z.string().min(1),
+					url: assetURL,
+					description: z.string().optional(),
+					bannerUrl: assetURL.optional(),
+				}),
+			)
+			.optional(),
+	}).parse(options);
+	calculateCommission(
+		0,
+		options.defaultCommissionType ?? "percent",
+		options.defaultCommissionValue ?? 20,
+	);
+	return defineBackendPlugin({
+		id: "affiliate",
+		dbPlugin: affiliateSchema,
+		operations: (adapter, context) => {
+			if (!context?.auth)
+				throw new Error(
+					"Affiliate requires a server auth adapter configured with affiliatePermissions",
+				);
+			return createAffiliateOperations(adapter, options);
+		},
+		routes: (_adapter, _context, operations) => ({
+			listAffiliates: createEndpoint(
+				"/affiliate/affiliates",
+				{ method: "GET", query: affiliateListSchema, requireRequest: true },
+				operations.listAffiliates.route((ctx) => ctx.query),
+			),
+			getAffiliate: createEndpoint(
+				"/affiliate/affiliates/:id",
+				{ method: "GET", requireRequest: true },
+				operations.getAffiliate.route((ctx) => ({ id: ctx.params.id })),
+			),
+			createAffiliate: createEndpoint(
+				"/affiliate/affiliates",
+				{ method: "POST", body: createAffiliateSchema, requireRequest: true },
+				operations.createAffiliate.route((ctx) => ctx.body),
+			),
+			updateAffiliate: createEndpoint(
+				"/affiliate/affiliates/:id",
+				{ method: "PUT", body: updateAffiliateSchema, requireRequest: true },
+				operations.updateAffiliate.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			deleteAffiliate: createEndpoint(
+				"/affiliate/affiliates/:id",
+				{ method: "DELETE", requireRequest: true },
+				operations.deleteAffiliate.route((ctx) => ({ id: ctx.params.id })),
+			),
+			apply: createEndpoint(
+				"/affiliate/apply",
+				{ method: "POST", body: applicationSchema, requireRequest: true },
+				operations.apply.route((ctx) => ctx.body),
+			),
+			getPortal: createEndpoint(
+				"/affiliate/portal",
+				{ method: "GET", requireRequest: true },
+				operations.getPortal.route(() => ({})),
+			),
+			updatePortal: createEndpoint(
+				"/affiliate/portal",
+				{ method: "PUT", body: updatePortalSchema, requireRequest: true },
+				operations.updatePortal.route((ctx) => ctx.body),
+			),
+			trackClick: createEndpoint(
+				"/affiliate/track/:code",
+				{
+					method: "GET",
+					query: z.object({ to: z.string().max(2048).optional() }),
+					requireRequest: true,
+				},
+				operations.trackClick.route((ctx) => ({
+					code: ctx.params.code,
+					landingPath: ctx.query.to,
+				})),
+			),
+			createConversion: createEndpoint(
+				"/affiliate/conversions",
+				{ method: "POST", body: createConversionSchema, requireRequest: true },
+				operations.createConversion.route((ctx) => ctx.body),
+			),
+			listCommissions: createEndpoint(
+				"/affiliate/commissions",
+				{ method: "GET", query: listSchema, requireRequest: true },
+				operations.listCommissions.route((ctx) => ctx.query),
+			),
+			updateCommission: createEndpoint(
+				"/affiliate/commissions/:id",
+				{ method: "PUT", body: updateCommissionSchema, requireRequest: true },
+				operations.updateCommission.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			listPayouts: createEndpoint(
+				"/affiliate/payouts",
+				{ method: "GET", query: listSchema, requireRequest: true },
+				operations.listPayouts.route((ctx) => ctx.query),
+			),
+			createPayout: createEndpoint(
+				"/affiliate/payouts",
+				{ method: "POST", body: createPayoutSchema, requireRequest: true },
+				operations.createPayout.route((ctx) => ctx.body),
+			),
+			updatePayout: createEndpoint(
+				"/affiliate/payouts/:id",
+				{ method: "PUT", body: updatePayoutSchema, requireRequest: true },
+				operations.updatePayout.route((ctx) => ({
+					id: ctx.params.id,
+					data: ctx.body,
+				})),
+			),
+			exportPayouts: createEndpoint(
+				"/affiliate/payouts/export",
+				{ method: "GET", query: listSchema, requireRequest: true },
+				operations.exportPayouts.route((ctx) => ctx.query),
+			),
+		}),
+	});
+};
+
+export type AffiliateApiRouter = ReturnType<
+	ReturnType<typeof affiliateBackendPlugin>["routes"]
+>;