@htlkg/core 0.0.2 → 0.0.3

package/src/errors/index.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest";
+import {
+	AppError,
+	AuthError,
+	ValidationError,
+	NotFoundError,
+} from "./index";
+
+describe("Error Classes", () => {
+	describe("AppError", () => {
+		it("should create error with default values", () => {
+			const error = new AppError("Test error");
+
+			expect(error.message).toBe("Test error");
+			expect(error.code).toBe("APP_ERROR");
+			expect(error.statusCode).toBe(500);
+			expect(error.name).toBe("AppError");
+			expect(error.details).toBeUndefined();
+		});
+
+		it("should create error with custom values", () => {
+			const details = { userId: "123" };
+			const error = new AppError("Custom error", "CUSTOM_CODE", 400, details);
+
+			expect(error.message).toBe("Custom error");
+			expect(error.code).toBe("CUSTOM_CODE");
+			expect(error.statusCode).toBe(400);
+			expect(error.details).toEqual(details);
+		});
+
+		it("should be instanceof Error", () => {
+			const error = new AppError("Test");
+			expect(error).toBeInstanceOf(Error);
+		});
+
+		it("should convert to JSON", () => {
+			const error = new AppError("Test", "CODE", 400, { key: "value" });
+			const json = error.toJSON();
+
+			expect(json).toEqual({
+				name: "AppError",
+				message: "Test",
+				code: "CODE",
+				statusCode: 400,
+				details: { key: "value" },
+			});
+		});
+	});
+
+	describe("AuthError", () => {
+		it("should create auth error with default values", () => {
+			const error = new AuthError("Unauthorized");
+
+			expect(error.message).toBe("Unauthorized");
+			expect(error.code).toBe("AUTH_ERROR");
+			expect(error.statusCode).toBe(401);
+			expect(error.name).toBe("AuthError");
+		});
+
+		it("should create auth error with custom values", () => {
+			const error = new AuthError("Invalid token", "INVALID_TOKEN", 403);
+
+			expect(error.message).toBe("Invalid token");
+			expect(error.code).toBe("INVALID_TOKEN");
+			expect(error.statusCode).toBe(403);
+		});
+
+		it("should be instanceof AppError", () => {
+			const error = new AuthError("Test");
+			expect(error).toBeInstanceOf(AppError);
+		});
+	});
+
+	describe("ValidationError", () => {
+		it("should create validation error with default values", () => {
+			const error = new ValidationError("Validation failed");
+
+			expect(error.message).toBe("Validation failed");
+			expect(error.code).toBe("VALIDATION_ERROR");
+			expect(error.statusCode).toBe(400);
+			expect(error.name).toBe("ValidationError");
+			expect(error.errors).toEqual([]);
+		});
+
+		it("should create validation error with field errors", () => {
+			const fieldErrors = [
+				{ field: "email", message: "Invalid email" },
+				{ field: "password", message: "Too short" },
+			];
+			const error = new ValidationError("Validation failed", fieldErrors);
+
+			expect(error.errors).toEqual(fieldErrors);
+			expect(error.details).toEqual({ errors: fieldErrors });
+		});
+
+		it("should convert to JSON with errors", () => {
+			const fieldErrors = [{ field: "email", message: "Invalid" }];
+			const error = new ValidationError("Failed", fieldErrors);
+			const json = error.toJSON();
+
+			expect(json.errors).toEqual(fieldErrors);
+			expect(json.name).toBe("ValidationError");
+		});
+
+		it("should be instanceof AppError", () => {
+			const error = new ValidationError("Test");
+			expect(error).toBeInstanceOf(AppError);
+		});
+	});
+
+	describe("NotFoundError", () => {
+		it("should create not found error with resource only", () => {
+			const error = new NotFoundError("User");
+
+			expect(error.message).toBe("User not found");
+			expect(error.code).toBe("NOT_FOUND");
+			expect(error.statusCode).toBe(404);
+			expect(error.name).toBe("NotFoundError");
+			expect(error.resource).toBe("User");
+			expect(error.resourceId).toBeUndefined();
+		});
+
+		it("should create not found error with resource and ID", () => {
+			const error = new NotFoundError("User", "123");
+
+			expect(error.message).toBe("User with id '123' not found");
+			expect(error.resource).toBe("User");
+			expect(error.resourceId).toBe("123");
+		});
+
+		it("should create not found error with custom message", () => {
+			const error = new NotFoundError("User", "123", "Custom not found message");
+
+			expect(error.message).toBe("Custom not found message");
+			expect(error.resource).toBe("User");
+			expect(error.resourceId).toBe("123");
+		});
+
+		it("should convert to JSON with resource info", () => {
+			const error = new NotFoundError("Brand", "456");
+			const json = error.toJSON();
+
+			expect(json.resource).toBe("Brand");
+			expect(json.resourceId).toBe("456");
+			expect(json.name).toBe("NotFoundError");
+		});
+
+		it("should be instanceof AppError", () => {
+			const error = new NotFoundError("Test");
+			expect(error).toBeInstanceOf(AppError);
+		});
+	});
+});

package/src/errors/index.ts

@@ -0,0 +1,134 @@
+/**
+ * @htlkg/core/errors
+ * Core error classes for Hotelinking applications
+ */
+
+/**
+ * Base application error class
+ */
+export class AppError extends Error {
+	public readonly code: string;
+	public readonly statusCode: number;
+	public readonly details?: Record<string, any>;
+
+	constructor(
+		message: string,
+		code = "APP_ERROR",
+		statusCode = 500,
+		details?: Record<string, any>,
+	) {
+		super(message);
+		this.name = "AppError";
+		this.code = code;
+		this.statusCode = statusCode;
+		this.details = details;
+
+		// Maintains proper stack trace for where our error was thrown (only available on V8)
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, AppError);
+		}
+	}
+
+	/**
+	 * Convert error to JSON representation
+	 */
+	toJSON(): Record<string, any> {
+		return {
+			name: this.name,
+			message: this.message,
+			code: this.code,
+			statusCode: this.statusCode,
+			details: this.details,
+		};
+	}
+}
+
+/**
+ * Authentication error class
+ */
+export class AuthError extends AppError {
+	constructor(
+		message: string,
+		code = "AUTH_ERROR",
+		statusCode = 401,
+		details?: Record<string, any>,
+	) {
+		super(message, code, statusCode, details);
+		this.name = "AuthError";
+
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, AuthError);
+		}
+	}
+}
+
+/**
+ * Validation error class
+ */
+export class ValidationError extends AppError {
+	public readonly errors: Array<{ field: string; message: string }>;
+
+	constructor(
+		message: string,
+		errors: Array<{ field: string; message: string }> = [],
+		code = "VALIDATION_ERROR",
+		statusCode = 400,
+	) {
+		super(message, code, statusCode, { errors });
+		this.name = "ValidationError";
+		this.errors = errors;
+
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, ValidationError);
+		}
+	}
+
+	/**
+	 * Convert error to JSON representation
+	 */
+	toJSON(): Record<string, any> {
+		return {
+			...super.toJSON(),
+			errors: this.errors,
+		};
+	}
+}
+
+/**
+ * Not found error class
+ */
+export class NotFoundError extends AppError {
+	public readonly resource: string;
+	public readonly resourceId?: string;
+
+	constructor(
+		resource: string,
+		resourceId?: string,
+		message?: string,
+		code = "NOT_FOUND",
+		statusCode = 404,
+	) {
+		const defaultMessage = resourceId
+			? `${resource} with id '${resourceId}' not found`
+			: `${resource} not found`;
+		super(message || defaultMessage, code, statusCode, { resource, resourceId });
+		this.name = "NotFoundError";
+		this.resource = resource;
+		this.resourceId = resourceId;
+
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, NotFoundError);
+		}
+	}
+
+	/**
+	 * Convert error to JSON representation
+	 */
+	toJSON(): Record<string, any> {
+		return {
+			...super.toJSON(),
+			resource: this.resource,
+			resourceId: this.resourceId,
+		};
+	}
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @htlkg/core
+ * Core utilities, types, and authentication for Hotelinking applications
+ */
+
+// Auth exports
+export {
+	getUser,
+	getClientUser,
+	hasAccessToBrand,
+	hasAccessToAccount,
+	isAdminUser,
+	isSuperAdminUser,
+	requireAuth,
+	requireAdminAccess,
+	requireBrandAccess,
+	type User,
+	type APIContext,
+} from "./auth/index.js";
+
+// Type exports
+export type {
+	Brand,
+	Account,
+	Product,
+	ProductInstance,
+	BrandUser,
+} from "./types/index.js";
+
+// Utility exports
+export {
+	formatDate,
+	truncateText,
+	groupBy,
+	debounce,
+	throttle,
+} from "./utils/index.js";
+
+// Constants exports
+export { ROUTES, PRODUCTS, PERMISSIONS, USER_ROLES } from "./constants/index.js";
+
+// Error exports
+export {
+	AppError,
+	AuthError,
+	ValidationError,
+	NotFoundError,
+} from "./errors/index.js";
+
+// Type-safe routes
+export {
+	routes,
+	adminRoutes,
+	portalRoutes,
+	authRoutes,
+	apiRoutes,
+	createRoute,
+	matchesRoute,
+	extractRouteParams,
+	navigateTo,
+	buildUrl,
+	type Route,
+	type RouteParams,
+	type Routes,
+} from "./routes/index.js";

package/src/routes/index.ts

@@ -0,0 +1,225 @@
+/**
+ * Type-Safe Routes
+ *
+ * Centralized route definitions with type safety and parameter interpolation.
+ * Eliminates string literals scattered across the codebase.
+ */
+
+/**
+ * Route parameters type
+ */
+export type RouteParams = Record<string, string | number>;
+
+/**
+ * Route function interface - can be called with params or used as path
+ */
+export interface Route<TParams extends RouteParams = RouteParams> {
+	/** Base path of the route */
+	readonly path: string;
+	/** Generate URL with interpolated parameters */
+	(params?: TParams): string;
+}
+
+/**
+ * Create a route with optional parameters
+ *
+ * @example
+ * ```typescript
+ * const userRoute = createRoute<{ id: string }>('/users/:id');
+ * userRoute({ id: '123' }); // "/users/123"
+ * userRoute.path; // "/users/:id"
+ * ```
+ */
+export function createRoute<TParams extends RouteParams = Record<string, never>>(path: string): Route<TParams> {
+	const routeFn = (params?: TParams): string => {
+		if (!params) return path;
+
+		let result = path;
+		for (const [key, value] of Object.entries(params)) {
+			result = result.replace(`:${key}`, String(value));
+		}
+		return result;
+	};
+
+	// Add path as a property
+	Object.defineProperty(routeFn, "path", {
+		value: path,
+		writable: false,
+		enumerable: true,
+	});
+
+	return routeFn as Route<TParams>;
+}
+
+/**
+ * Admin routes
+ */
+export const adminRoutes = {
+	/** Dashboard */
+	dashboard: createRoute("/admin"),
+
+	/** Accounts list */
+	accounts: createRoute("/admin/accounts"),
+
+	/** Account detail */
+	account: createRoute<{ id: string | number }>("/admin/accounts/:id"),
+
+	/** Account brands */
+	accountBrands: createRoute<{ id: string | number }>("/admin/accounts/:id/brands"),
+
+	/** Brands list */
+	brands: createRoute("/admin/brands"),
+
+	/** Brand detail */
+	brand: createRoute<{ id: string | number }>("/admin/brands/:id"),
+
+	/** Brand settings */
+	brandSettings: createRoute<{ id: string | number }>("/admin/brands/:id/settings"),
+
+	/** Users list */
+	users: createRoute("/admin/users"),
+
+	/** User detail */
+	user: createRoute<{ id: string }>("/admin/users/:id"),
+
+	/** Current user profile */
+	profile: createRoute("/admin/user"),
+
+	/** Analytics */
+	analytics: createRoute("/admin/analytics"),
+} as const;
+
+/**
+ * Portal routes (customer-facing)
+ */
+export const portalRoutes = {
+	/** Portal home */
+	home: createRoute("/"),
+
+	/** Brand portal */
+	brand: createRoute<{ brandId: string | number }>("/brands/:brandId"),
+
+	/** Brand settings */
+	brandSettings: createRoute<{ brandId: string | number }>("/brands/:brandId/settings"),
+
+	/** Brand dashboard */
+	brandDashboard: createRoute<{ brandId: string | number }>("/brands/:brandId/dashboard"),
+
+	/** Brand analytics */
+	brandAnalytics: createRoute<{ brandId: string | number }>("/brands/:brandId/analytics"),
+} as const;
+
+/**
+ * Auth routes
+ */
+export const authRoutes = {
+	/** Login page */
+	login: createRoute("/login"),
+
+	/** Logout endpoint */
+	logout: createRoute("/api/auth/logout"),
+
+	/** Confirm sign in */
+	confirmSignIn: createRoute("/api/auth/confirm-signin"),
+} as const;
+
+/**
+ * API routes
+ */
+export const apiRoutes = {
+	/** Auth endpoints */
+	auth: {
+		logout: createRoute("/api/auth/logout"),
+		confirmSignIn: createRoute("/api/auth/confirm-signin"),
+	},
+} as const;
+
+/**
+ * All routes combined
+ */
+export const routes = {
+	admin: adminRoutes,
+	portal: portalRoutes,
+	auth: authRoutes,
+	api: apiRoutes,
+} as const;
+
+/**
+ * Type for all routes
+ */
+export type Routes = typeof routes;
+
+/**
+ * Helper to check if a path matches a route pattern
+ */
+export function matchesRoute(path: string, route: Route): boolean {
+	const pattern = route.path
+		.replace(/:[^/]+/g, "[^/]+") // Replace :param with regex
+		.replace(/\//g, "\\/"); // Escape slashes
+
+	const regex = new RegExp(`^${pattern}$`);
+	return regex.test(path);
+}
+
+/**
+ * Extract parameters from a path given a route pattern
+ */
+export function extractRouteParams<TParams extends RouteParams>(
+	path: string,
+	route: Route<TParams>
+): TParams | null {
+	const paramNames: string[] = [];
+	const pattern = route.path.replace(/:([^/]+)/g, (_, name) => {
+		paramNames.push(name);
+		return "([^/]+)";
+	});
+
+	const regex = new RegExp(`^${pattern}$`);
+	const match = path.match(regex);
+
+	if (!match) return null;
+
+	const params: RouteParams = {};
+	paramNames.forEach((name, index) => {
+		params[name] = match[index + 1];
+	});
+
+	return params as TParams;
+}
+
+/**
+ * Navigate to a route (client-side helper)
+ *
+ * @example
+ * ```typescript
+ * navigateTo(routes.admin.account({ id: '123' }));
+ * ```
+ */
+export function navigateTo(url: string): void {
+	if (typeof window !== "undefined") {
+		window.location.href = url;
+	}
+}
+
+/**
+ * Build a URL with query parameters
+ *
+ * @example
+ * ```typescript
+ * const url = buildUrl(routes.admin.users(), { page: 2, status: 'active' });
+ * // "/admin/users?page=2&status=active"
+ * ```
+ */
+export function buildUrl(path: string, params?: Record<string, string | number | boolean | null | undefined>): string {
+	if (!params) return path;
+
+	const searchParams = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value !== null && value !== undefined && value !== "") {
+			searchParams.set(key, String(value));
+		}
+	}
+
+	const queryString = searchParams.toString();
+	return queryString ? `${path}?${queryString}` : path;
+}