@hammadj/better-auth-core 1.5.0-beta.9

package/src/types/plugin-client.ts

@@ -0,0 +1,127 @@
+import type {
+	BetterFetch,
+	BetterFetchOption,
+	BetterFetchPlugin,
+} from "@better-fetch/fetch";
+import type { Atom, WritableAtom } from "nanostores";
+import type { LiteralString } from "./helper";
+import type { BetterAuthOptions } from "./init-options";
+import type { BetterAuthPlugin } from "./plugin";
+
+export interface ClientStore {
+	notify: (signal: string) => void;
+	listen: (signal: string, listener: () => void) => void;
+	atoms: Record<string, WritableAtom<any>>;
+}
+
+export type ClientAtomListener = {
+	matcher: (path: string) => boolean;
+	signal: "$sessionSignal" | Omit<string, "$sessionSignal">;
+};
+
+/**
+ * Better-Fetch options but with additional options for the auth-client.
+ */
+export type ClientFetchOption<
+	Body = any,
+	Query extends Record<string, any> = any,
+	Params extends Record<string, any> | Array<string> | undefined = any,
+	Res = any,
+> = BetterFetchOption<Body, Query, Params, Res> & {
+	/**
+	 * Certain endpoints, upon successful response, will trigger atom signals and thus rerendering all hooks related to that atom.
+	 *
+	 * This option is useful when you want to skip hook rerenders.
+	 */
+	disableSignal?: boolean | undefined;
+};
+
+export interface RevalidateOptions {
+	/**
+	 * A time interval (in seconds) after which the session will be re-fetched.
+	 * If set to `0` (default), the session is not polled.
+	 *
+	 * This helps prevent session expiry during idle periods by periodically
+	 * refreshing the session.
+	 *
+	 * @default 0
+	 */
+	refetchInterval?: number | undefined;
+	/**
+	 * Automatically refetch the session when the user switches back to the window/tab.
+	 * This option activates this behavior if set to `true` (default).
+	 *
+	 * Prevents expired sessions when users switch tabs and come back later.
+	 *
+	 * @default true
+	 */
+	refetchOnWindowFocus?: boolean | undefined;
+	/**
+	 * Set to `false` to stop polling when the device has no internet access
+	 * (determined by `navigator.onLine`).
+	 *
+	 * @default false
+	 * @see https://developer.mozilla.org/en-US/docs/Web/API/NavigatorOnLine/onLine
+	 */
+	refetchWhenOffline?: boolean | undefined;
+}
+
+export interface BetterAuthClientOptions {
+	fetchOptions?: ClientFetchOption | undefined;
+	plugins?: BetterAuthClientPlugin[] | undefined;
+	baseURL?: string | undefined;
+	basePath?: string | undefined;
+	disableDefaultFetchPlugins?: boolean | undefined;
+	$InferAuth?: BetterAuthOptions | undefined;
+	sessionOptions?: RevalidateOptions | undefined;
+}
+
+export interface BetterAuthClientPlugin {
+	id: LiteralString;
+	/**
+	 * only used for type inference. don't pass the
+	 * actual plugin
+	 */
+	$InferServerPlugin?: BetterAuthPlugin | undefined;
+	/**
+	 * Custom actions
+	 */
+	getActions?: (
+		$fetch: BetterFetch,
+		$store: ClientStore,
+		/**
+		 * better-auth client options
+		 */
+		options: BetterAuthClientOptions | undefined,
+	) => Record<string, any>;
+	/**
+	 * State atoms that'll be resolved by each framework
+	 * auth store.
+	 */
+	getAtoms?: (($fetch: BetterFetch) => Record<string, Atom<any>>) | undefined;
+	/**
+	 * specify path methods for server plugin inferred
+	 * endpoints to force a specific method.
+	 */
+	pathMethods?: Record<string, "POST" | "GET"> | undefined;
+	/**
+	 * Better fetch plugins
+	 */
+	fetchPlugins?: BetterFetchPlugin[] | undefined;
+	/**
+	 * a list of recaller based on a matcher function.
+	 * The signal name needs to match a signal in this
+	 * plugin or any plugin the user might have added.
+	 */
+	atomListeners?: ClientAtomListener[] | undefined;
+	/**
+	 * The error codes returned by the plugin
+	 */
+	$ERROR_CODES?: Record<
+		string,
+		{
+			code: string;
+			message: string;
+		}
+	>;
+}

package/src/types/plugin.ts

@@ -0,0 +1,157 @@
+import type {
+	Endpoint,
+	EndpointContext,
+	InputContext,
+	Middleware,
+} from "better-call";
+import type { Migration } from "kysely";
+import type { AuthMiddleware } from "../api";
+import type { BetterAuthPluginDBSchema } from "../db";
+import type { AuthContext } from "./context";
+import type { Awaitable, LiteralString } from "./helper";
+import type { BetterAuthOptions } from "./init-options";
+
+type DeepPartial<T> = T extends Function
+	? T
+	: T extends object
+		? { [K in keyof T]?: DeepPartial<T[K]> }
+		: T;
+
+export type HookEndpointContext = Partial<
+	EndpointContext<string, any> & Omit<InputContext<string, any>, "method">
+> & {
+	path?: string;
+	context: AuthContext & {
+		returned?: unknown | undefined;
+		responseHeaders?: Headers | undefined;
+	};
+	headers?: Headers | undefined;
+};
+
+export type BetterAuthPlugin = {
+	id: LiteralString;
+	/**
+	 * The init function is called when the plugin is initialized.
+	 * You can return a new context or modify the existing context.
+	 */
+	init?:
+		| ((ctx: AuthContext) =>
+				| Awaitable<{
+						context?: DeepPartial<Omit<AuthContext, "options">>;
+						options?: Partial<BetterAuthOptions>;
+				  }>
+				| void
+				| Promise<void>)
+		| undefined;
+	endpoints?:
+		| {
+				[key: string]: Endpoint;
+		  }
+		| undefined;
+	middlewares?:
+		| {
+				path: string;
+				middleware: Middleware;
+		  }[]
+		| undefined;
+	onRequest?:
+		| ((
+				request: Request,
+				ctx: AuthContext,
+		  ) => Promise<
+				| {
+						response: Response;
+				  }
+				| {
+						request: Request;
+				  }
+				| void
+		  >)
+		| undefined;
+	onResponse?:
+		| ((
+				response: Response,
+				ctx: AuthContext,
+		  ) => Promise<{
+				response: Response;
+		  } | void>)
+		| undefined;
+	hooks?:
+		| {
+				before?: {
+					matcher: (context: HookEndpointContext) => boolean;
+					handler: AuthMiddleware;
+				}[];
+				after?: {
+					matcher: (context: HookEndpointContext) => boolean;
+					handler: AuthMiddleware;
+				}[];
+		  }
+		| undefined;
+	/**
+	 * Schema the plugin needs
+	 *
+	 * This will also be used to migrate the database. If the fields are dynamic from the plugins
+	 * configuration each time the configuration is changed a new migration will be created.
+	 *
+	 * NOTE: If you want to create migrations manually using
+	 * migrations option or any other way you
+	 * can disable migration per table basis.
+	 *
+	 * @example
+	 * ```ts
+	 * schema: {
+	 * 	user: {
+	 * 		fields: {
+	 * 			email: {
+	 * 				 type: "string",
+	 * 			},
+	 * 			emailVerified: {
+	 * 				type: "boolean",
+	 * 				defaultValue: false,
+	 * 			},
+	 * 		},
+	 * 	}
+	 * } as AuthPluginSchema
+	 * ```
+	 */
+	schema?: BetterAuthPluginDBSchema | undefined;
+	/**
+	 * The migrations of the plugin. If you define schema that will automatically create
+	 * migrations for you.
+	 *
+	 * ⚠️ Only uses this if you dont't want to use the schema option and you disabled migrations for
+	 * the tables.
+	 */
+	migrations?: Record<string, Migration> | undefined;
+	/**
+	 * The options of the plugin
+	 */
+	options?: Record<string, any> | undefined;
+	/**
+	 * types to be inferred
+	 */
+	$Infer?: Record<string, any> | undefined;
+	/**
+	 * The rate limit rules to apply to specific paths.
+	 */
+	rateLimit?:
+		| {
+				window: number;
+				max: number;
+				pathMatcher: (path: string) => boolean;
+		  }[]
+		| undefined;
+	/**
+	 * The error codes returned by the plugin
+	 */
+	$ERROR_CODES?: Record<string, { code: string; message: string }> | undefined;
+	/**
+	 * All database operations that are performed by the plugin
+	 *
+	 * This will override the default database operations
+	 */
+	adapter?: {
+		[key: string]: (...args: any[]) => Awaitable<any>;
+	};
+};

package/src/utils/db.ts

@@ -0,0 +1,20 @@
+import type { DBFieldAttribute } from "../db";
+
+/**
+ * Filters output data by removing fields with the `returned: false` attribute.
+ * This ensures sensitive fields are not exposed in API responses.
+ */
+export function filterOutputFields<T extends Record<string, unknown> | null>(
+	data: T,
+	additionalFields: Record<string, DBFieldAttribute> | undefined,
+): T {
+	if (!data || !additionalFields) {
+		return data;
+	}
+	const returnFiltered = Object.entries(additionalFields)
+		.filter(([, { returned }]) => returned === false)
+		.map(([key]) => key);
+	return Object.entries(structuredClone(data))
+		.filter(([key]) => !returnFiltered.includes(key))
+		.reduce((acc, [key, value]) => ({ ...acc, [key]: value }), {} as T);
+}

package/src/utils/deprecate.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+import { deprecate } from "./deprecate";
+
+describe("deprecate", () => {
+	it("should warn once when called multiple times", () => {
+		const warn = vi.fn();
+		const logger = { warn } as any;
+		const fn = vi.fn();
+		const deprecatedFn = deprecate(fn, "test message", logger);
+
+		deprecatedFn();
+		deprecatedFn();
+		deprecatedFn();
+
+		expect(warn).toHaveBeenCalledTimes(1);
+		expect(warn).toHaveBeenCalledWith("[Deprecation] test message");
+		expect(fn).toHaveBeenCalledTimes(3);
+	});
+
+	it("should use provided logger if available", () => {
+		const warn = vi.fn();
+		const logger = { warn } as any;
+		const fn = vi.fn();
+		const deprecatedFn = deprecate(fn, "test message", logger);
+
+		deprecatedFn();
+
+		expect(warn).toHaveBeenCalledWith("[Deprecation] test message");
+	});
+
+	it("should fall back to console.warn if no logger provided", () => {
+		const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		const fn = vi.fn();
+		const deprecatedFn = deprecate(fn, "test message");
+
+		deprecatedFn();
+
+		expect(consoleWarn).toHaveBeenCalledWith("[Deprecation] test message");
+		consoleWarn.mockRestore();
+	});
+
+	it("should pass arguments and return value correctly", () => {
+		const fn = vi.fn((a: number, b: number) => a + b);
+		const deprecatedFn = deprecate(fn, "test message", {
+			warn: vi.fn(),
+		} as any);
+
+		const result = deprecatedFn(1, 2);
+
+		expect(result).toBe(3);
+		expect(fn).toHaveBeenCalledWith(1, 2);
+	});
+
+	it("should preserve this context", () => {
+		class TestClass {
+			value = 10;
+			method(a: number) {
+				return this.value + a;
+			}
+		}
+
+		const instance = new TestClass();
+		const originalMethod = instance.method;
+		instance.method = deprecate(originalMethod, "test message", {
+			warn: vi.fn(),
+		} as any);
+
+		const result = instance.method(5);
+
+		expect(result).toBe(15);
+	});
+});

package/src/utils/deprecate.ts

@@ -0,0 +1,21 @@
+import type { InternalLogger } from "../env";
+
+/**
+ * Wraps a function to log a deprecation warning at once.
+ */
+export function deprecate<T extends (...args: any[]) => any>(
+	fn: T,
+	message: string,
+	logger?: InternalLogger,
+): T {
+	let warned = false;
+
+	return function (this: any, ...args: Parameters<T>): ReturnType<T> {
+		if (!warned) {
+			const warn = logger?.warn ?? console.warn;
+			warn(`[Deprecation] ${message}`);
+			warned = true;
+		}
+		return fn.apply(this, args);
+	} as T;
+}

package/src/utils/error-codes.ts

@@ -0,0 +1,65 @@
+type UpperLetter =
+	| "A"
+	| "B"
+	| "C"
+	| "D"
+	| "E"
+	| "F"
+	| "G"
+	| "H"
+	| "I"
+	| "J"
+	| "K"
+	| "L"
+	| "M"
+	| "N"
+	| "O"
+	| "P"
+	| "Q"
+	| "R"
+	| "S"
+	| "T"
+	| "U"
+	| "V"
+	| "W"
+	| "X"
+	| "Y"
+	| "Z";
+type SpecialCharacter = "_";
+
+type IsValidUpperSnakeCase<S extends string> = S extends `${infer F}${infer R}`
+	? F extends UpperLetter | SpecialCharacter
+		? IsValidUpperSnakeCase<R>
+		: false
+	: true;
+
+type InvalidKeyError<K extends string> =
+	`Invalid error code key: "${K}" - must only contain uppercase letters (A-Z) and underscores (_)`;
+
+type ValidateErrorCodes<T> = {
+	[K in keyof T]: K extends string
+		? IsValidUpperSnakeCase<K> extends false
+			? InvalidKeyError<K>
+			: T[K]
+		: T[K];
+};
+
+export function defineErrorCodes<const T extends Record<string, string>>(
+	codes: ValidateErrorCodes<T>,
+): {
+	[K in keyof T]: {
+		code: K;
+		message: T[K];
+	};
+} {
+	return Object.fromEntries(
+		Object.entries(codes).map(([key, value]) => [
+			key,
+			{
+				code: key,
+				message: value,
+				toString: () => value,
+			},
+		]),
+	) as any;
+}

package/src/utils/id.ts

@@ -0,0 +1,5 @@
+import { createRandomStringGenerator } from "@better-auth/utils/random";
+
+export const generateId = (size?: number) => {
+	return createRandomStringGenerator("a-z", "A-Z", "0-9")(size || 32);
+};