@checodo/better-auth-referral 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,957 @@
+import { t as REFERRAL_ERROR_CODES } from "./error-codes-Bw554PRu.js";
+import { mergeSchema } from "better-auth/db";
+import { getCurrentAdapter, queueAfterTransactionHook, tryGetCurrentAuthEndpointContext } from "@better-auth/core/context";
+import { APIError, createAuthEndpoint, getOAuthState, sessionMiddleware } from "better-auth/api";
+import * as z from "zod";
+// package.json
+var version = "0.1.0";
+// ../plugin-utils/src/admin.ts
+/** Applies the defaults of `AdminOptions`. */
+function resolveAdminOptions(options) {
+	return {
+		adminRoles: options.adminRoles ?? ["admin"],
+		adminUserIds: options.adminUserIds ?? []
+	};
+}
+/**
+* Whether `user` is listed in `adminUserIds`, or has one of `adminRoles`
+* in the admin plugin's `role` field, which holds several roles
+* comma-separated (`"user, admin"`).
+*/
+function isAdmin(user, options) {
+	if (options.adminUserIds.includes(user.id)) return true;
+	if (typeof user.role !== "string") return false;
+	return user.role.split(",").some((role) => options.adminRoles.includes(role.trim()));
+}
+// ../plugin-utils/src/options.ts
+/**
+* Returns a function that throws an option error prefixed with the plugin
+* id, `[referral] "codeLength" must be ...`, for validating options at
+* plugin creation.
+*/
+function createFail(pluginId) {
+	return (message) => {
+		throw new Error(`[${pluginId}] ${message}`);
+	};
+}
+// src/options.ts
+/** The step every referral starts with. Not configurable, and not stored. */
+const SIGN_UP_STEP = "sign-up";
+/** A step the plugin records itself, when the referred user's email is verified. */
+const EMAIL_VERIFIED_STEP = "email-verified";
+const fail = createFail("referral");
+/** Resolves defaults and validates the options once, at plugin creation. */
+function resolveOptions(options) {
+	const codeLength = options.codeLength ?? 8;
+	if (!Number.isInteger(codeLength) || codeLength < 6 || codeLength > 32) fail(`"codeLength" must be an integer between 6 and 32, got ${codeLength}.`);
+	const max = options.maxReferralsPerUser;
+	if (max !== void 0 && (!Number.isInteger(max) || max < 1)) fail(`"maxReferralsPerUser" must be a positive integer, got ${max}.`);
+	const steps = [...options.steps ?? []];
+	for (const step of steps) {
+		if (!/^[a-z0-9][a-z0-9_-]*$/i.test(step) || step.length > 64) fail(`Invalid step ${JSON.stringify(step)}: use letters, digits, "-", and "_", up to 64 characters.`);
+		if (step === "sign-up") fail(`"${SIGN_UP_STEP}" is always the first step; don't list it in "steps".`);
+	}
+	if (new Set(steps).size !== steps.length) fail(`"steps" lists a step twice.`);
+	return {
+		codeLength,
+		generateCode: options.generateCode,
+		createCodeOnSignUp: options.createCodeOnSignUp ?? false,
+		steps,
+		stepsConfigured: options.steps !== void 0,
+		maxReferralsPerUser: max,
+		invalidCode: options.invalidCode ?? "ignore",
+		allowReferral: options.allowReferral,
+		onReferral: options.onReferral,
+		onStepCompleted: options.onStepCompleted,
+		onReferralCompleted: options.onReferralCompleted,
+		maskEmails: options.maskEmails ?? true,
+		hideNames: options.hideNames ?? false,
+		...resolveAdminOptions(options)
+	};
+}
+/**
+* Defaults that depend on the app's auth config, applied in the plugin's
+* `init`: without explicit `steps`, apps that send verification emails
+* require `email-verified`, so fake sign-ups don't complete referrals.
+* Warns when referrals earn rewards but complete at sign-up.
+*/
+function applyAuthDefaults(options, ctx) {
+	if (!options.stepsConfigured && ctx.options.emailVerification?.sendVerificationEmail) options.steps = [EMAIL_VERIFIED_STEP];
+	if (!options.stepsConfigured && options.steps.length === 0 && options.onReferralCompleted) ctx.logger.warn("[referral] Referrals complete at sign-up (no \"steps\"), so fake sign-ups earn rewards. Require at least \"email-verified\" (see \"Steps and rewards\" in the referral plugin docs).");
+}
+// ../plugin-utils/src/audit.ts
+/**
+* Records an event in the audit log plugin, if the app uses it. The audit
+* log is found through `getPlugin`, like official plugins find each other,
+* so it isn't a dependency. Does nothing outside a request. Never throws:
+* the audit log's `recordEvent` doesn't.
+*/
+async function recordAuditEvent(event) {
+	await (tryGetCurrentAuthEndpointContext()?.context.getPlugin("audit-log"))?.recordEvent?.(event);
+}
+// ../plugin-utils/src/callbacks.ts
+/**
+* Runs a user callback (`onJoin`, `onReferralCompleted`, ...) in the
+* background when better-auth's `advanced.backgroundTasks` is configured,
+* so response times don't depend on it, and awaits it otherwise. Errors
+* are logged as `[<pluginId>] <name> threw an error` and never reach the
+* client.
+*/
+async function runCallback(context, pluginId, name, callback) {
+	const task = (async () => {
+		try {
+			await callback();
+		} catch (error) {
+			context.logger.error(`[${pluginId}] ${name} threw an error`, error);
+		}
+	})();
+	await context.runInBackgroundOrAwait(task);
+}
+// src/store.ts
+async function findCodeByUserId(adapter, userId) {
+	return adapter.findOne({
+		model: "referralCode",
+		where: [{
+			field: "userId",
+			value: userId
+		}]
+	});
+}
+async function findCodeByCode(adapter, code) {
+	return adapter.findOne({
+		model: "referralCode",
+		where: [{
+			field: "code",
+			value: code
+		}]
+	});
+}
+async function createCode(adapter, input) {
+	return adapter.create({
+		model: "referralCode",
+		data: {
+			userId: input.userId,
+			code: input.code,
+			createdAt: /* @__PURE__ */ new Date()
+		}
+	});
+}
+async function replaceCode(adapter, id, code) {
+	return adapter.update({
+		model: "referralCode",
+		where: [{
+			field: "id",
+			value: id
+		}],
+		update: {
+			code,
+			createdAt: /* @__PURE__ */ new Date()
+		}
+	});
+}
+async function findReferralByReferredUserId(adapter, referredUserId) {
+	return adapter.findOne({
+		model: "referral",
+		where: [{
+			field: "referredUserId",
+			value: referredUserId
+		}]
+	});
+}
+async function createReferral(adapter, input) {
+	const now = /* @__PURE__ */ new Date();
+	return adapter.create({
+		model: "referral",
+		data: {
+			...input,
+			completedAt: input.status === "completed" ? now : null,
+			createdAt: now
+		}
+	});
+}
+async function deleteReferral(adapter, id) {
+	await adapter.delete({
+		model: "referral",
+		where: [{
+			field: "id",
+			value: id
+		}]
+	});
+}
+/**
+* Number of the referrer's referrals made before `referral`: earlier ones,
+* and those made in the same millisecond with a smaller id. Gives every
+* referral of a referrer a fixed place, so concurrent sign-ups agree on
+* which of them are over `maxReferralsPerUser`.
+*/
+async function countReferralsBefore(adapter, referral) {
+	const createdAt = new Date(referral.createdAt);
+	const referrer = {
+		field: "referrerUserId",
+		value: referral.referrerUserId
+	};
+	const [earlier, sameTime] = await Promise.all([adapter.count({
+		model: "referral",
+		where: [referrer, {
+			field: "createdAt",
+			value: createdAt,
+			operator: "lt"
+		}]
+	}), adapter.count({
+		model: "referral",
+		where: [
+			referrer,
+			{
+				field: "createdAt",
+				value: createdAt
+			},
+			{
+				field: "id",
+				value: referral.id,
+				operator: "lt"
+			}
+		]
+	})]);
+	return earlier + sameTime;
+}
+/**
+* Marks a pending referral completed. Returns `null` if it wasn't pending
+* (anymore), so only one caller gets to run `onReferralCompleted`.
+*/
+async function completeReferral(adapter, id) {
+	return adapter.update({
+		model: "referral",
+		where: [{
+			field: "id",
+			value: id
+		}, {
+			field: "status",
+			value: "pending"
+		}],
+		update: {
+			status: "completed",
+			completedAt: /* @__PURE__ */ new Date()
+		}
+	});
+}
+function referralFilters(input) {
+	const where = [];
+	if (input.referrerUserId) where.push({
+		field: "referrerUserId",
+		value: input.referrerUserId
+	});
+	if (input.status) where.push({
+		field: "status",
+		value: input.status
+	});
+	return where;
+}
+/** Newest first. */
+async function listReferrals(adapter, input) {
+	return adapter.findMany({
+		model: "referral",
+		where: referralFilters(input),
+		limit: input.limit,
+		offset: input.offset,
+		sortBy: {
+			field: "createdAt",
+			direction: "desc"
+		}
+	});
+}
+async function countReferrals(adapter, input) {
+	return adapter.count({
+		model: "referral",
+		where: referralFilters(input)
+	});
+}
+async function createStep(adapter, input) {
+	return adapter.create({
+		model: "referralStep",
+		data: {
+			referralId: input.referralId,
+			step: input.step,
+			metadata: input.metadata ?? null,
+			completedAt: /* @__PURE__ */ new Date()
+		}
+	});
+}
+async function findStep(adapter, referralId, step) {
+	return adapter.findOne({
+		model: "referralStep",
+		where: [{
+			field: "referralId",
+			value: referralId
+		}, {
+			field: "step",
+			value: step
+		}]
+	});
+}
+/** The completed steps of these referrals, by referral id. */
+async function stepsByReferral(adapter, referralIds) {
+	const result = new Map(referralIds.map((id) => [id, []]));
+	if (referralIds.length === 0) return result;
+	const steps = await adapter.findMany({
+		model: "referralStep",
+		where: [{
+			field: "referralId",
+			value: referralIds,
+			operator: "in"
+		}],
+		sortBy: {
+			field: "completedAt",
+			direction: "asc"
+		}
+	});
+	for (const { referralId, step } of steps) result.get(referralId)?.push(step);
+	return result;
+}
+/**
+* Whether a user can't refer anyone: deleted, or banned with better-auth's
+* `admin` plugin (until `banExpires`, if set). Without the admin plugin,
+* nobody is banned.
+*/
+async function isReferrerBlocked(adapter, userId) {
+	const user = await adapter.findOne({
+		model: "user",
+		where: [{
+			field: "id",
+			value: userId
+		}]
+	});
+	if (!user) return true;
+	if (user.banned !== true) return false;
+	return !user.banExpires || new Date(user.banExpires).getTime() > Date.now();
+}
+async function findUsers(adapter, ids) {
+	if (ids.length === 0) return /* @__PURE__ */ new Map();
+	const users = await adapter.findMany({
+		model: "user",
+		where: [{
+			field: "id",
+			value: ids,
+			operator: "in"
+		}]
+	});
+	return new Map(users.map((user) => [user.id, user]));
+}
+// src/utils/code.ts
+/**
+* Consonants and digits. No look-alikes (0/O, 1/I/L), and no vowels
+* (A, E, I, O, U, Y), so random codes can't spell words, offensive ones
+* included.
+*/
+const CODE_ALPHABET = "BCDFGHJKMNPQRSTVWXZ23456789";
+/** What a code may look like once normalized: letters, digits, `-`, `_`. */
+const CODE_PATTERN = /^[A-Z0-9_-]{4,64}$/;
+/** A random code of `length` characters from `CODE_ALPHABET`, without modulo bias. */
+function generateCode(length) {
+	const limit = 243;
+	let code = "";
+	while (code.length < length) for (const byte of crypto.getRandomValues(new Uint8Array(length * 2))) {
+		if (byte >= limit) continue;
+		code += CODE_ALPHABET[byte % 27];
+		if (code.length === length) break;
+	}
+	return code;
+}
+/** Trims and uppercases a code, the way codes are stored and compared. */
+function normalizeCode(code) {
+	return code.trim().toUpperCase();
+}
+/** Whether `code` (normalized) is a well-formed code. */
+function isWellFormedCode(code) {
+	return CODE_PATTERN.test(code);
+}
+// src/referrals.ts
+/** How often a colliding generated code is replaced before giving up. */
+const MAX_CODE_ATTEMPTS = 5;
+/** A new, unused, well-formed code from `generateCode` or the built-in generator. */
+async function newCode(adapter, options) {
+	const code = normalizeCode(options.generateCode ? await options.generateCode() : generateCode(options.codeLength));
+	if (!isWellFormedCode(code)) throw new Error(`[referral] generateCode returned ${JSON.stringify(code)}: use 4 to 64 letters, digits, "-", or "_".`);
+	return await findCodeByCode(adapter, code) ? null : code;
+}
+/**
+* The code `userId` refers with, created on first use. Safe to call
+* concurrently: a second creation hits the unique index and returns the
+* code the first one stored.
+*/
+async function getOrCreateCode(adapter, options, userId) {
+	const existing = await findCodeByUserId(adapter, userId);
+	if (existing) return existing;
+	for (let attempt = 0; attempt < MAX_CODE_ATTEMPTS; attempt++) {
+		const code = await newCode(adapter, options);
+		if (!code) continue;
+		try {
+			return await createCode(adapter, {
+				userId,
+				code
+			});
+		} catch (error) {
+			const raced = await findCodeByUserId(adapter, userId);
+			if (raced) return raced;
+			if (!await findCodeByCode(adapter, code)) throw error;
+		}
+	}
+	throw APIError.from("INTERNAL_SERVER_ERROR", REFERRAL_ERROR_CODES.CODE_GENERATION_FAILED);
+}
+/**
+* Gives `userId` a new code; the old one stops working. Referrals made
+* with the old code keep counting (they store the code they used).
+*/
+async function regenerateCode(adapter, options, userId) {
+	const existing = await findCodeByUserId(adapter, userId);
+	if (!existing) return getOrCreateCode(adapter, options, userId);
+	for (let attempt = 0; attempt < MAX_CODE_ATTEMPTS; attempt++) {
+		const code = await newCode(adapter, options);
+		if (!code) continue;
+		try {
+			return await replaceCode(adapter, existing.id, code) ?? {
+				...existing,
+				code
+			};
+		} catch (error) {
+			if (!await findCodeByCode(adapter, code)) throw error;
+		}
+	}
+	throw APIError.from("INTERNAL_SERVER_ERROR", REFERRAL_ERROR_CODES.CODE_GENERATION_FAILED);
+}
+/**
+* The stored code for `rawCode` if it can still refer someone: it exists,
+* its owner isn't banned, and hasn't reached `maxReferralsPerUser`. `null`
+* otherwise.
+*/
+async function findUsableCode(adapter, options, rawCode) {
+	const code = normalizeCode(rawCode);
+	if (!isWellFormedCode(code)) return null;
+	const stored = await findCodeByCode(adapter, code);
+	if (!stored) return null;
+	if (await isReferrerBlocked(adapter, stored.userId)) return null;
+	if (options.maxReferralsPerUser !== void 0 && await countReferrals(adapter, { referrerUserId: stored.userId }) >= options.maxReferralsPerUser) return null;
+	return stored;
+}
+/** Records a completed referral in the audit log, for the referrer it rewards. */
+function recordCompleted(referral) {
+	return recordAuditEvent({
+		type: "referral.completed",
+		severity: "medium",
+		userId: referral.referrerUserId,
+		metadata: {
+			referralId: referral.id,
+			referredUserId: referral.referredUserId
+		}
+	});
+}
+/**
+* Marks `referral` completed once all required steps are done, and runs
+* `onReferralCompleted` exactly once.
+*/
+async function completeIfDone(adapter, context, options, referral) {
+	if (referral.status === "completed") return referral;
+	const done = new Set((await stepsByReferral(adapter, [referral.id])).get(referral.id));
+	if (!options.steps.every((step) => done.has(step))) return referral;
+	const completed = await completeReferral(adapter, referral.id);
+	if (!completed) return {
+		...referral,
+		status: "completed"
+	};
+	await recordCompleted(completed);
+	const { onReferralCompleted } = options;
+	if (onReferralCompleted) await runCallback(context, "referral", "onReferralCompleted", () => onReferralCompleted(completed));
+	return completed;
+}
+/**
+* Records `step` for `referral` (once; repeating it changes nothing) and
+* completes the referral when it was the last required step.
+*/
+async function recordStep(adapter, context, options, referral, step, metadata) {
+	if (!options.steps.includes(step)) throw APIError.from("BAD_REQUEST", REFERRAL_ERROR_CODES.UNKNOWN_REFERRAL_STEP);
+	let isNew = false;
+	if (!await findStep(adapter, referral.id, step)) try {
+		await createStep(adapter, {
+			referralId: referral.id,
+			step,
+			metadata
+		});
+		isNew = true;
+	} catch (error) {
+		if (!await findStep(adapter, referral.id, step)) throw error;
+	}
+	const { onStepCompleted } = options;
+	if (isNew && onStepCompleted) await runCallback(context, "referral", "onStepCompleted", () => onStepCompleted({
+		referral,
+		step
+	}));
+	return completeIfDone(adapter, context, options, referral);
+}
+/**
+* Runs once a referral is created: `onReferral`, then `onReferralCompleted`
+* if it was created completed (no steps required).
+*/
+async function referralCreated(context, options, referral) {
+	await recordAuditEvent({
+		type: "referral.created",
+		userId: referral.referredUserId,
+		actorUserId: referral.referredUserId,
+		metadata: {
+			referralId: referral.id,
+			referrerUserId: referral.referrerUserId,
+			code: referral.code
+		}
+	});
+	if (referral.status === "completed") await recordCompleted(referral);
+	const { onReferral, onReferralCompleted } = options;
+	if (onReferral) await runCallback(context, "referral", "onReferral", () => onReferral(referral));
+	if (referral.status === "completed" && onReferralCompleted) await runCallback(context, "referral", "onReferralCompleted", () => onReferralCompleted(referral));
+}
+// src/hooks/database.ts
+const REFERRAL_CODE_HEADER = "x-referral-code";
+/** Longest code read from a request; longer values are ignored. */
+const MAX_CODE_INPUT_LENGTH = 128;
+/**
+* The referral code sent with the request that creates the user: the
+* `referralCode` field of the sign-up body, the `x-referral-code` header,
+* or `additionalData.referralCode` of a social sign-in (read on the
+* callback).
+*/
+async function readReferralCode(context) {
+	const valid = (value) => typeof value === "string" && value.trim() !== "" && value.length <= MAX_CODE_INPUT_LENGTH;
+	const body = context?.body;
+	if (valid(body?.referralCode)) return body.referralCode;
+	const header = context?.headers?.get(REFERRAL_CODE_HEADER);
+	if (valid(header)) return header;
+	try {
+		const state = await getOAuthState();
+		if (valid(state?.referralCode)) return state.referralCode;
+	} catch {}
+}
+/**
+* Attributes new users to the code they signed up with, whichever way
+* they sign up, and records the `email-verified` step. Failures after the
+* user exists are logged, never returned: a referral problem must not
+* fail a sign-up that already happened.
+*/
+function createDatabaseHooks(authContext, options) {
+	const contextFor = (context) => context?.context ?? authContext;
+	const tracksEmailVerified = options.steps.includes(EMAIL_VERIFIED_STEP);
+	/** Requests whose user update sets `emailVerified: true` (see `update.before`). */
+	const verifying = /* @__PURE__ */ new WeakSet();
+	const attribute = async (user, context) => {
+		const ctx = contextFor(context);
+		const adapter = await getCurrentAdapter(ctx.adapter);
+		if (options.createCodeOnSignUp) await getOrCreateCode(adapter, options, user.id);
+		const rawCode = await readReferralCode(context);
+		if (!rawCode) return;
+		const code = await findUsableCode(adapter, options, rawCode);
+		if (!code || code.userId === user.id) return;
+		if (options.allowReferral) {
+			let allowed = false;
+			try {
+				allowed = await options.allowReferral({
+					referrerUserId: code.userId,
+					referredUser: {
+						id: user.id,
+						email: user.email
+					},
+					code: code.code,
+					context: context ?? null
+				});
+			} catch (error) {
+				ctx.logger.error("[referral] allowReferral threw an error", error);
+			}
+			if (!allowed) return;
+		}
+		let referral;
+		try {
+			referral = await createReferral(adapter, {
+				referrerUserId: code.userId,
+				referredUserId: user.id,
+				code: code.code,
+				status: options.steps.length === 0 ? "completed" : "pending"
+			});
+		} catch (error) {
+			if (await findReferralByReferredUserId(adapter, user.id)) return;
+			throw error;
+		}
+		const settle = async () => {
+			try {
+				const max = options.maxReferralsPerUser;
+				if (max !== void 0 && await countReferralsBefore(ctx.adapter, referral) >= max) {
+					await deleteReferral(ctx.adapter, referral.id);
+					return;
+				}
+				await referralCreated(ctx, options, referral);
+				if (tracksEmailVerified && user.emailVerified) await recordStep(ctx.adapter, ctx, options, referral, EMAIL_VERIFIED_STEP);
+			} catch (error) {
+				ctx.logger.error("[referral] failed to record the referral", error);
+			}
+		};
+		if (adapter === ctx.adapter) await settle();
+		else await queueAfterTransactionHook(settle);
+	};
+	return { user: {
+		create: {
+			before: async (_user, context) => {
+				if (options.invalidCode !== "reject") return;
+				const rawCode = await readReferralCode(context);
+				if (rawCode === void 0) return;
+				if (!await findUsableCode(await getCurrentAdapter(contextFor(context).adapter), options, rawCode)) throw APIError.from("BAD_REQUEST", REFERRAL_ERROR_CODES.INVALID_REFERRAL_CODE);
+			},
+			after: async (user, context) => {
+				try {
+					await attribute(user, context);
+				} catch (error) {
+					contextFor(context).logger.error("[referral] failed to record the referral", error);
+				}
+			}
+		},
+		update: {
+			before: async (data, context) => {
+				if (tracksEmailVerified && context && data.emailVerified === true) verifying.add(context);
+			},
+			after: async (user, context) => {
+				if (!tracksEmailVerified || user.emailVerified !== true) return;
+				if (context && !verifying.delete(context)) return;
+				const ctx = contextFor(context);
+				try {
+					const adapter = await getCurrentAdapter(ctx.adapter);
+					const referral = await findReferralByReferredUserId(adapter, user.id);
+					if (referral) await recordStep(adapter, ctx, options, referral, EMAIL_VERIFIED_STEP);
+				} catch (error) {
+					ctx.logger.error("[referral] failed to record the email-verified step", error);
+				}
+			}
+		}
+	} };
+}
+// src/routes/codes.ts
+function createCodeEndpoints(options) {
+	return {
+		getReferralCode: createAuthEndpoint("/referral/get-code", {
+			method: "GET",
+			use: [sessionMiddleware],
+			metadata: { openapi: { description: "Get the signed-in user's referral code, or null if they have none" } }
+		}, async (ctx) => {
+			const code = await findCodeByUserId(ctx.context.adapter, ctx.context.session.user.id);
+			return ctx.json({ code: code?.code ?? null });
+		}),
+		createReferralCode: createAuthEndpoint("/referral/create-code", {
+			method: "POST",
+			use: [sessionMiddleware],
+			metadata: { openapi: { description: "Create the signed-in user's referral code. Returns the existing code if they already have one" } }
+		}, async (ctx) => {
+			const code = await getOrCreateCode(ctx.context.adapter, options, ctx.context.session.user.id);
+			return ctx.json({ code: code.code });
+		}),
+		regenerateReferralCode: createAuthEndpoint("/referral/regenerate-code", {
+			method: "POST",
+			use: [sessionMiddleware],
+			metadata: { openapi: { description: "Replace the signed-in user's referral code with a new one. The old code and its share links stop working; referrals made with it keep counting" } }
+		}, async (ctx) => {
+			const code = await regenerateCode(ctx.context.adapter, options, ctx.context.session.user.id);
+			return ctx.json({ code: code.code });
+		}),
+		checkReferralCode: createAuthEndpoint("/referral/check-code", {
+			method: "GET",
+			query: z.object({ code: z.string().min(1).max(128).meta({ description: "The referral code" }) }),
+			metadata: { openapi: { description: "Check whether a referral code can be used at sign-up. Doesn't reveal whose code it is" } }
+		}, async (ctx) => {
+			const code = await findUsableCode(ctx.context.adapter, options, ctx.query.code);
+			return ctx.json({ valid: code !== null });
+		})
+	};
+}
+// ../plugin-utils/src/pagination.ts
+/**
+* The `limit` and `offset` fields of a list endpoint's query, coerced from
+* query strings. Spread into the endpoint's `z.object({ ... })`.
+*/
+function paginationQuery({ defaultLimit, maxLimit }) {
+	return {
+		limit: z.coerce.number().int().min(1).max(maxLimit).default(defaultLimit).meta({ description: `How many to return, at most ${maxLimit}. Defaults to ${defaultLimit}` }),
+		offset: z.coerce.number().int().min(0).default(0).meta({ description: "How many to skip. Defaults to 0" })
+	};
+}
+// src/utils/mask.ts
+/** `ada@example.com` → `a***@example.com`. Emails without `@` become `***`. */
+function maskEmail(email) {
+	const at = email.lastIndexOf("@");
+	if (at < 1) return "***";
+	return `${email[0]}***${email.slice(at)}`;
+}
+const pageSchema = paginationQuery({
+	defaultLimit: 20,
+	maxLimit: 100
+});
+const statusSchema = z.enum(["pending", "completed"]).meta({ description: "Only referrals with this status" });
+async function withSteps(adapter, referrals) {
+	const steps = await stepsByReferral(adapter, referrals.map((referral) => referral.id));
+	return referrals.map((referral) => ({
+		...referral,
+		steps: steps.get(referral.id) ?? []
+	}));
+}
+function createReferralEndpoints(options) {
+	return {
+		listReferrals: createAuthEndpoint("/referral/list-referrals", {
+			method: "GET",
+			use: [sessionMiddleware],
+			query: z.optional(z.object({
+				status: statusSchema.optional(),
+				...pageSchema
+			})),
+			metadata: { openapi: { description: "List the users the signed-in user referred, newest first, with their steps" } }
+		}, async (ctx) => {
+			const { adapter } = ctx.context;
+			const referrerUserId = ctx.context.session.user.id;
+			const status = ctx.query?.status;
+			const [referrals, total, completed] = await Promise.all([
+				listReferrals(adapter, {
+					referrerUserId,
+					status,
+					limit: ctx.query?.limit ?? 20,
+					offset: ctx.query?.offset ?? 0
+				}),
+				countReferrals(adapter, {
+					referrerUserId,
+					status
+				}),
+				countReferrals(adapter, {
+					referrerUserId,
+					status: "completed"
+				})
+			]);
+			const [detailed, users] = await Promise.all([withSteps(adapter, referrals), findUsers(adapter, referrals.map((referral) => referral.referredUserId))]);
+			return ctx.json({
+				referrals: detailed.map((referral) => {
+					const user = users.get(referral.referredUserId);
+					return {
+						id: referral.id,
+						status: referral.status,
+						steps: referral.steps,
+						createdAt: referral.createdAt,
+						completedAt: referral.completedAt ?? null,
+						referredUser: {
+							name: options.hideNames ? null : user?.name ?? null,
+							email: user ? options.maskEmails ? maskEmail(user.email) : user.email : null
+						}
+					};
+				}),
+				total,
+				completed
+			});
+		}),
+		listAllReferrals: createAuthEndpoint("/referral/list-all-referrals", {
+			method: "GET",
+			use: [sessionMiddleware],
+			query: z.optional(z.object({
+				referrerUserId: z.string().min(1).optional().meta({ description: "Only referrals by this user" }),
+				status: statusSchema.optional(),
+				...pageSchema
+			})),
+			metadata: { openapi: { description: "List all referrals, newest first. Admins only" } }
+		}, async (ctx) => {
+			if (!isAdmin(ctx.context.session.user, options)) throw APIError.from("FORBIDDEN", REFERRAL_ERROR_CODES.YOU_ARE_NOT_ALLOWED_TO_LIST_REFERRALS);
+			const { adapter } = ctx.context;
+			const filters = {
+				referrerUserId: ctx.query?.referrerUserId,
+				status: ctx.query?.status
+			};
+			const [referrals, total] = await Promise.all([listReferrals(adapter, {
+				...filters,
+				limit: ctx.query?.limit ?? 20,
+				offset: ctx.query?.offset ?? 0
+			}), countReferrals(adapter, filters)]);
+			return ctx.json({
+				referrals: await withSteps(adapter, referrals),
+				total
+			});
+		}),
+		/**
+		* Server only (no path, so not reachable over HTTP): your backend calls
+		* `auth.api.completeReferralStep` when a referred user does something
+		* that counts, e.g. their first purchase.
+		*/
+		completeReferralStep: createAuthEndpoint({
+			method: "POST",
+			body: z.object({
+				userId: z.string().min(1).meta({ description: "The referred user" }),
+				step: z.string().min(1).max(64).meta({ description: "A step from the plugin's `steps` option" }),
+				metadata: z.record(z.string(), z.unknown()).optional().meta({ description: "Extra data to keep with the step, e.g. an order id" })
+			}),
+			metadata: { openapi: { description: "Record a step of the user's referral. Does nothing if the user wasn't referred or the step is already done" } }
+		}, async (ctx) => {
+			const { userId, step } = ctx.body;
+			const metadata = ctx.body.metadata ? JSON.stringify(ctx.body.metadata) : void 0;
+			if (metadata && metadata.length > 2e3) throw APIError.from("BAD_REQUEST", REFERRAL_ERROR_CODES.METADATA_TOO_LARGE);
+			if (!options.steps.includes(step)) throw APIError.from("BAD_REQUEST", REFERRAL_ERROR_CODES.UNKNOWN_REFERRAL_STEP);
+			const { adapter } = ctx.context;
+			const referral = await findReferralByReferredUserId(adapter, userId);
+			if (!referral) return ctx.json({ referral: null });
+			const [detailed] = await withSteps(adapter, [await recordStep(adapter, ctx.context, options, referral, step, metadata)]);
+			return ctx.json({ referral: detailed ?? null });
+		})
+	};
+}
+// src/schema.ts
+const referralSchema = {
+	/** One code per user. */
+	referralCode: {
+		fields: {
+			userId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "user",
+					field: "id",
+					onDelete: "cascade"
+				}
+			},
+			/** Uppercase. */
+			code: {
+				type: "string",
+				required: true
+			},
+			createdAt: {
+				type: "date",
+				required: true
+			}
+		},
+		indexes: [{
+			fields: ["userId"],
+			unique: true
+		}, {
+			fields: ["code"],
+			unique: true
+		}]
+	},
+	/** Who referred whom. A user is referred at most once. */
+	referral: {
+		fields: {
+			referrerUserId: {
+				type: "string",
+				required: true,
+				index: true,
+				references: {
+					model: "user",
+					field: "id",
+					onDelete: "cascade"
+				}
+			},
+			referredUserId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "user",
+					field: "id",
+					onDelete: "cascade"
+				}
+			},
+			/** The code used at sign-up, kept even if the code changes. */
+			code: {
+				type: "string",
+				required: true
+			},
+			/** "pending" | "completed" */
+			status: {
+				type: "string",
+				required: true,
+				index: true
+			},
+			completedAt: {
+				type: "date",
+				required: false
+			},
+			createdAt: {
+				type: "date",
+				required: true
+			}
+		},
+		indexes: [{
+			fields: ["referredUserId"],
+			unique: true
+		}]
+	},
+	/** Steps a referred user has completed. Each step counts once. */
+	referralStep: {
+		fields: {
+			referralId: {
+				type: "string",
+				required: true,
+				references: {
+					model: "referral",
+					field: "id",
+					onDelete: "cascade"
+				}
+			},
+			step: {
+				type: "string",
+				required: true
+			},
+			/** JSON-encoded. */
+			metadata: {
+				type: "string",
+				required: false
+			},
+			completedAt: {
+				type: "date",
+				required: true
+			}
+		},
+		indexes: [{
+			fields: ["referralId", "step"],
+			unique: true
+		}]
+	}
+};
+// src/index.ts
+/**
+* Gives users referral codes, attributes new users to the code they signed
+* up with (any sign-up method), and tracks steps a referral must complete
+* before it counts, e.g. a verified email or a first purchase.
+*
+* @example
+* ```ts
+* import { betterAuth } from "better-auth";
+* import { referral } from "@checodo/better-auth-referral";
+*
+* export const auth = betterAuth({
+*   plugins: [
+*     referral({
+*       steps: ["email-verified", "first-purchase"],
+*       onReferralCompleted: async ({ referrerUserId }) => {
+*         await grantCredit(referrerUserId);
+*       },
+*     }),
+*   ],
+* });
+* ```
+*/
+const referral = (options = {}) => {
+	const resolved = resolveOptions(options);
+	return {
+		id: "referral",
+		version,
+		init(ctx) {
+			applyAuthDefaults(resolved, ctx);
+			return { options: { databaseHooks: createDatabaseHooks(ctx, resolved) } };
+		},
+		schema: mergeSchema(structuredClone(referralSchema), options.schema),
+		endpoints: {
+			...createCodeEndpoints(resolved),
+			...createReferralEndpoints(resolved)
+		},
+		rateLimit: [{
+			pathMatcher: (path) => path === "/referral/check-code",
+			window: 60,
+			max: 5
+		}],
+		$ERROR_CODES: REFERRAL_ERROR_CODES,
+		options
+	};
+};
+export { EMAIL_VERIFIED_STEP, REFERRAL_ERROR_CODES, referral };
+
+//# sourceMappingURL=index.js.map