@htlkg/core 0.0.2 → 0.0.3

package/src/constants/index.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { ROUTES, PRODUCTS, PERMISSIONS, USER_ROLES } from "./index";
+
+describe("Constants", () => {
+	describe("ROUTES", () => {
+		it("should have admin routes", () => {
+			expect(ROUTES.ADMIN.HOME).toBe("/admin");
+			expect(ROUTES.ADMIN.BRANDS).toBe("/admin/brands");
+			expect(ROUTES.ADMIN.ACCOUNTS).toBe("/admin/accounts");
+			expect(ROUTES.ADMIN.USERS).toBe("/admin/users");
+			expect(ROUTES.ADMIN.PRODUCTS).toBe("/admin/products");
+			expect(ROUTES.ADMIN.SETTINGS).toBe("/admin/settings");
+		});
+
+		it("should have brand route functions", () => {
+			expect(ROUTES.BRAND.HOME("test-brand")).toBe("/test-brand");
+			expect(ROUTES.BRAND.ADMIN("test-brand")).toBe("/test-brand/admin");
+			expect(ROUTES.BRAND.TEMPLATES("test-brand")).toBe(
+				"/test-brand/admin/templates",
+			);
+			expect(ROUTES.BRAND.SETTINGS("test-brand")).toBe(
+				"/test-brand/admin/settings",
+			);
+		});
+
+		it("should have auth routes", () => {
+			expect(ROUTES.AUTH.LOGIN).toBe("/login");
+			expect(ROUTES.AUTH.LOGOUT).toBe("/logout");
+			expect(ROUTES.AUTH.SIGNUP).toBe("/signup");
+			expect(ROUTES.AUTH.FORGOT_PASSWORD).toBe("/forgot-password");
+		});
+
+		it("should be defined as const", () => {
+			// Note: TypeScript 'as const' provides compile-time immutability
+			// but doesn't prevent runtime mutations. This test just verifies the structure exists.
+			expect(ROUTES.ADMIN).toBeDefined();
+		});
+	});
+
+	describe("PRODUCTS", () => {
+		it("should have WiFi Portal product", () => {
+			expect(PRODUCTS.WIFI_PORTAL.id).toBe("wifi-portal");
+			expect(PRODUCTS.WIFI_PORTAL.name).toBe("WiFi Portal");
+			expect(PRODUCTS.WIFI_PORTAL.description).toContain("Captive portal");
+		});
+
+		it("should have WhatsApp CRM product", () => {
+			expect(PRODUCTS.WHATSAPP_CRM.id).toBe("whatsapp-crm");
+			expect(PRODUCTS.WHATSAPP_CRM.name).toBe("WhatsApp CRM");
+			expect(PRODUCTS.WHATSAPP_CRM.description).toContain("WhatsApp");
+		});
+
+		it("should have Analytics product", () => {
+			expect(PRODUCTS.ANALYTICS.id).toBe("analytics");
+			expect(PRODUCTS.ANALYTICS.name).toBe("Analytics");
+			expect(PRODUCTS.ANALYTICS.description).toContain("Analytics");
+		});
+
+		it("should be defined as const", () => {
+			expect(PRODUCTS.WIFI_PORTAL).toBeDefined();
+		});
+	});
+
+	describe("PERMISSIONS", () => {
+		it("should have brand permissions", () => {
+			expect(PERMISSIONS.BRAND_VIEW).toBe("brand:view");
+			expect(PERMISSIONS.BRAND_EDIT).toBe("brand:edit");
+			expect(PERMISSIONS.BRAND_DELETE).toBe("brand:delete");
+			expect(PERMISSIONS.BRAND_CREATE).toBe("brand:create");
+		});
+
+		it("should have account permissions", () => {
+			expect(PERMISSIONS.ACCOUNT_VIEW).toBe("account:view");
+			expect(PERMISSIONS.ACCOUNT_EDIT).toBe("account:edit");
+			expect(PERMISSIONS.ACCOUNT_DELETE).toBe("account:delete");
+			expect(PERMISSIONS.ACCOUNT_CREATE).toBe("account:create");
+		});
+
+		it("should have user permissions", () => {
+			expect(PERMISSIONS.USER_VIEW).toBe("user:view");
+			expect(PERMISSIONS.USER_EDIT).toBe("user:edit");
+			expect(PERMISSIONS.USER_DELETE).toBe("user:delete");
+			expect(PERMISSIONS.USER_CREATE).toBe("user:create");
+		});
+
+		it("should have product permissions", () => {
+			expect(PERMISSIONS.PRODUCT_VIEW).toBe("product:view");
+			expect(PERMISSIONS.PRODUCT_EDIT).toBe("product:edit");
+			expect(PERMISSIONS.PRODUCT_ENABLE).toBe("product:enable");
+			expect(PERMISSIONS.PRODUCT_DISABLE).toBe("product:disable");
+		});
+
+		it("should have admin permissions", () => {
+			expect(PERMISSIONS.ADMIN_ACCESS).toBe("admin:access");
+			expect(PERMISSIONS.SUPER_ADMIN_ACCESS).toBe("super_admin:access");
+		});
+
+		it("should be defined as const", () => {
+			expect(PERMISSIONS.BRAND_VIEW).toBeDefined();
+		});
+	});
+
+	describe("USER_ROLES", () => {
+		it("should have all user roles", () => {
+			expect(USER_ROLES.SUPER_ADMIN).toBe("SUPER_ADMINS");
+			expect(USER_ROLES.ADMIN).toBe("ADMINS");
+			expect(USER_ROLES.BRAND_ADMIN).toBe("BRAND_ADMINS");
+			expect(USER_ROLES.BRAND_USER).toBe("BRAND_USERS");
+			expect(USER_ROLES.USER).toBe("USERS");
+		});
+
+		it("should be defined as const", () => {
+			expect(USER_ROLES.SUPER_ADMIN).toBeDefined();
+		});
+	});
+});

package/src/constants/index.ts

@@ -0,0 +1,98 @@
+/**
+ * @htlkg/core/constants
+ * Core constants for Hotelinking applications
+ */
+
+/**
+ * Application routes
+ */
+export const ROUTES = {
+	// Admin routes
+	ADMIN: {
+		HOME: "/admin",
+		BRANDS: "/admin/brands",
+		ACCOUNTS: "/admin/accounts",
+		USERS: "/admin/users",
+		PRODUCTS: "/admin/products",
+		SETTINGS: "/admin/settings",
+	},
+	// Brand routes
+	BRAND: {
+		HOME: (brandId: string) => `/${brandId}`,
+		ADMIN: (brandId: string) => `/${brandId}/admin`,
+		TEMPLATES: (brandId: string) => `/${brandId}/admin/templates`,
+		SETTINGS: (brandId: string) => `/${brandId}/admin/settings`,
+	},
+	// Auth routes
+	AUTH: {
+		LOGIN: "/login",
+		LOGOUT: "/logout",
+		SIGNUP: "/signup",
+		FORGOT_PASSWORD: "/forgot-password",
+	},
+} as const;
+
+/**
+ * Product definitions
+ */
+export const PRODUCTS = {
+	WIFI_PORTAL: {
+		id: "wifi-portal",
+		name: "WiFi Portal",
+		description: "Captive portal for WiFi authentication",
+	},
+	WHATSAPP_CRM: {
+		id: "whatsapp-crm",
+		name: "WhatsApp CRM",
+		description: "WhatsApp integration for customer relationship management",
+	},
+	ANALYTICS: {
+		id: "analytics",
+		name: "Analytics",
+		description: "Analytics and reporting dashboard",
+	},
+} as const;
+
+/**
+ * Permission definitions
+ */
+export const PERMISSIONS = {
+	// Brand permissions
+	BRAND_VIEW: "brand:view",
+	BRAND_EDIT: "brand:edit",
+	BRAND_DELETE: "brand:delete",
+	BRAND_CREATE: "brand:create",
+
+	// Account permissions
+	ACCOUNT_VIEW: "account:view",
+	ACCOUNT_EDIT: "account:edit",
+	ACCOUNT_DELETE: "account:delete",
+	ACCOUNT_CREATE: "account:create",
+
+	// User permissions
+	USER_VIEW: "user:view",
+	USER_EDIT: "user:edit",
+	USER_DELETE: "user:delete",
+	USER_CREATE: "user:create",
+
+	// Product permissions
+	PRODUCT_VIEW: "product:view",
+	PRODUCT_EDIT: "product:edit",
+	PRODUCT_ENABLE: "product:enable",
+	PRODUCT_DISABLE: "product:disable",
+
+	// Admin permissions
+	ADMIN_ACCESS: "admin:access",
+	SUPER_ADMIN_ACCESS: "super_admin:access",
+} as const;
+
+/**
+ * User role definitions
+ */
+export const USER_ROLES = {
+	SUPER_ADMIN: "SUPER_ADMINS",
+	ADMIN: "ADMINS",
+	BRAND_ADMIN: "BRAND_ADMINS",
+	BRAND_USER: "BRAND_USERS",
+	USER: "USERS",
+} as const;

package/src/core-exports.property.test.ts

@@ -0,0 +1,186 @@
+/**
+ * Property-based tests for @htlkg/core module exports
+ * Feature: htlkg-modular-architecture, Property 1: Module exports are accessible
+ * Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5
+ */
+import { describe, it, expect } from "vitest";
+
+describe("Property 1: Module exports are accessible", () => {
+	it("should export all auth functions from main module", async () => {
+		// Import from main module
+		const mainModule = await import("./index.js");
+		expect(mainModule.getUser).toBeDefined();
+		expect(mainModule.getClientUser).toBeDefined();
+		expect(mainModule.hasAccessToBrand).toBeDefined();
+		expect(mainModule.hasAccessToAccount).toBeDefined();
+		expect(mainModule.isAdminUser).toBeDefined();
+		expect(mainModule.isSuperAdminUser).toBeDefined();
+		expect(mainModule.requireAuth).toBeDefined();
+		expect(mainModule.requireAdminAccess).toBeDefined();
+		expect(mainModule.requireBrandAccess).toBeDefined();
+	});
+
+	it("should export all auth functions from auth subpath", async () => {
+		// Import from auth subpath
+		const authModule = await import("./auth/index.js");
+		expect(authModule.getUser).toBeDefined();
+		expect(authModule.getClientUser).toBeDefined();
+		expect(authModule.hasAccessToBrand).toBeDefined();
+		expect(authModule.hasAccessToAccount).toBeDefined();
+		expect(authModule.isAdminUser).toBeDefined();
+		expect(authModule.isSuperAdminUser).toBeDefined();
+		expect(authModule.requireAuth).toBeDefined();
+		expect(authModule.requireAdminAccess).toBeDefined();
+		expect(authModule.requireBrandAccess).toBeDefined();
+	});
+
+	it("should export all utility functions from main module", async () => {
+		const mainModule = await import("./index.js");
+		expect(mainModule.formatDate).toBeDefined();
+		expect(mainModule.truncateText).toBeDefined();
+		expect(mainModule.groupBy).toBeDefined();
+		expect(mainModule.debounce).toBeDefined();
+		expect(mainModule.throttle).toBeDefined();
+	});
+
+	it("should export all utility functions from utils subpath", async () => {
+		const utilsModule = await import("./utils/index.js");
+		expect(utilsModule.formatDate).toBeDefined();
+		expect(utilsModule.truncateText).toBeDefined();
+		expect(utilsModule.groupBy).toBeDefined();
+		expect(utilsModule.debounce).toBeDefined();
+		expect(utilsModule.throttle).toBeDefined();
+	});
+
+	it("should export all constants from main module", async () => {
+		const mainModule = await import("./index.js");
+		expect(mainModule.ROUTES).toBeDefined();
+		expect(mainModule.PRODUCTS).toBeDefined();
+		expect(mainModule.PERMISSIONS).toBeDefined();
+		expect(mainModule.USER_ROLES).toBeDefined();
+	});
+
+	it("should export all constants from constants subpath", async () => {
+		const constantsModule = await import("./constants/index.js");
+		expect(constantsModule.ROUTES).toBeDefined();
+		expect(constantsModule.PRODUCTS).toBeDefined();
+		expect(constantsModule.PERMISSIONS).toBeDefined();
+		expect(constantsModule.USER_ROLES).toBeDefined();
+	});
+
+	it("should export all error classes from main module", async () => {
+		const mainModule = await import("./index.js");
+		expect(mainModule.AppError).toBeDefined();
+		expect(mainModule.AuthError).toBeDefined();
+		expect(mainModule.ValidationError).toBeDefined();
+		expect(mainModule.NotFoundError).toBeDefined();
+	});
+
+	it("should export all error classes from errors subpath", async () => {
+		const errorsModule = await import("./errors/index.js");
+		expect(errorsModule.AppError).toBeDefined();
+		expect(errorsModule.AuthError).toBeDefined();
+		expect(errorsModule.ValidationError).toBeDefined();
+		expect(errorsModule.NotFoundError).toBeDefined();
+	});
+
+	it("should have working utility functions for various inputs", async () => {
+		const { formatDate, truncateText, groupBy } = await import("./index.js");
+
+		// Test with multiple different inputs to verify the property holds
+		const testCases = [
+			{
+				date: new Date("2024-01-15"),
+				text: "Hello World",
+				items: [
+					{ id: 1, category: "A" },
+					{ id: 2, category: "B" },
+				],
+			},
+			{
+				date: new Date("2023-12-25"),
+				text: "Short",
+				items: [{ id: 1, category: "A" }],
+			},
+			{
+				date: new Date(),
+				text: "A very long text that should be truncated properly",
+				items: [],
+			},
+		];
+
+		for (const testCase of testCases) {
+			// formatDate should not throw
+			expect(() => formatDate(testCase.date)).not.toThrow();
+
+			// truncateText should not throw
+			expect(() => truncateText(testCase.text, 50)).not.toThrow();
+
+			// groupBy should not throw
+			expect(() =>
+				groupBy(testCase.items, (item) => item.category),
+			).not.toThrow();
+		}
+	});
+
+	it("should have working error classes for various inputs", async () => {
+		const { AppError, AuthError, ValidationError, NotFoundError } =
+			await import("./index.js");
+
+		const testCases = [
+			{ message: "Error 1", code: "CODE1", statusCode: 400 },
+			{ message: "Error 2", code: "CODE2", statusCode: 500 },
+			{ message: "Error 3", code: "CODE3", statusCode: 404 },
+		];
+
+		for (const testCase of testCases) {
+			// All error classes should be instantiable
+			const appError = new AppError(
+				testCase.message,
+				testCase.code,
+				testCase.statusCode,
+			);
+			expect(appError).toBeInstanceOf(Error);
+			expect(appError.message).toBe(testCase.message);
+
+			const authError = new AuthError(
+				testCase.message,
+				testCase.code,
+				testCase.statusCode,
+			);
+			expect(authError).toBeInstanceOf(Error);
+			expect(authError.message).toBe(testCase.message);
+
+			const validationError = new ValidationError(testCase.message);
+			expect(validationError).toBeInstanceOf(Error);
+			expect(validationError.message).toBe(testCase.message);
+
+			const notFoundError = new NotFoundError("Resource", "123");
+			expect(notFoundError).toBeInstanceOf(Error);
+		}
+	});
+
+	it("should have constants that are defined and accessible", async () => {
+		const { ROUTES, PRODUCTS, PERMISSIONS, USER_ROLES } = await import(
+			"./index.js"
+		);
+
+		// Constants should be defined and have expected structure
+		expect(ROUTES).toBeDefined();
+		expect(ROUTES.ADMIN).toBeDefined();
+		expect(ROUTES.BRAND).toBeDefined();
+		expect(ROUTES.AUTH).toBeDefined();
+
+		expect(PRODUCTS).toBeDefined();
+		expect(PRODUCTS.WIFI_PORTAL).toBeDefined();
+		expect(PRODUCTS.WHATSAPP_CRM).toBeDefined();
+
+		expect(PERMISSIONS).toBeDefined();
+		expect(PERMISSIONS.BRAND_VIEW).toBeDefined();
+		expect(PERMISSIONS.ADMIN_ACCESS).toBeDefined();
+
+		expect(USER_ROLES).toBeDefined();
+		expect(USER_ROLES.SUPER_ADMIN).toBeDefined();
+		expect(USER_ROLES.ADMIN).toBeDefined();
+	});
+});

package/src/errors/errors.md

@@ -0,0 +1,177 @@
+# Errors Module
+
+Standardized error classes for consistent error handling across applications.
+
+## Installation
+
+```typescript
+import { 
+  AppError, 
+  AuthError, 
+  ValidationError, 
+  NotFoundError 
+} from '@htlkg/core/errors';
+```
+
+## Error Classes
+
+### AppError
+
+Base error class for all application errors.
+
+```typescript
+class AppError extends Error {
+  code: string;
+  statusCode: number;
+  details?: Record<string, any>;
+}
+```
+
+```typescript
+throw new AppError(
+  'Something went wrong',
+  'CUSTOM_ERROR',    // code
+  500,               // statusCode
+  { context: 'data' } // details
+);
+```
+
+### AuthError
+
+Authentication and authorization errors.
+
+```typescript
+class AuthError extends AppError {
+  // Defaults: code = 'AUTH_ERROR', statusCode = 401
+}
+```
+
+```typescript
+throw new AuthError('Invalid credentials');
+throw new AuthError('Token expired', 'TOKEN_EXPIRED', 401);
+throw new AuthError('Insufficient permissions', 'FORBIDDEN', 403);
+```
+
+### ValidationError
+
+Input validation errors with field-level details.
+
+```typescript
+class ValidationError extends AppError {
+  errors: Array<{ field: string; message: string }>;
+  // Defaults: code = 'VALIDATION_ERROR', statusCode = 400
+}
+```
+
+```typescript
+throw new ValidationError('Validation failed', [
+  { field: 'email', message: 'Invalid email format' },
+  { field: 'password', message: 'Password too short' },
+]);
+```
+
+### NotFoundError
+
+Resource not found errors.
+
+```typescript
+class NotFoundError extends AppError {
+  resource: string;
+  resourceId?: string;
+  // Defaults: code = 'NOT_FOUND', statusCode = 404
+}
+```
+
+```typescript
+throw new NotFoundError('Brand', '123');
+// Message: "Brand with id '123' not found"
+
+throw new NotFoundError('User');
+// Message: "User not found"
+
+throw new NotFoundError('Brand', '123', 'Custom message');
+```
+
+## JSON Serialization
+
+All errors support `toJSON()` for API responses:
+
+```typescript
+const error = new ValidationError('Invalid input', [
+  { field: 'email', message: 'Required' }
+]);
+
+console.log(JSON.stringify(error));
+// {
+//   "name": "ValidationError",
+//   "message": "Invalid input",
+//   "code": "VALIDATION_ERROR",
+//   "statusCode": 400,
+//   "details": { "errors": [...] },
+//   "errors": [{ "field": "email", "message": "Required" }]
+// }
+```
+
+## API Route Usage
+
+```typescript
+import type { APIContext } from 'astro';
+import { NotFoundError, ValidationError, AuthError } from '@htlkg/core/errors';
+
+export async function GET({ params }: APIContext) {
+  try {
+    const brand = await getBrand(params.id);
+    
+    if (!brand) {
+      throw new NotFoundError('Brand', params.id);
+    }
+    
+    return new Response(JSON.stringify(brand));
+  } catch (error) {
+    if (error instanceof AppError) {
+      return new Response(JSON.stringify(error.toJSON()), {
+        status: error.statusCode,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    
+    // Unknown error
+    return new Response(JSON.stringify({ error: 'Internal server error' }), {
+      status: 500,
+    });
+  }
+}
+```
+
+## Error Handling Middleware
+
+```typescript
+function handleError(error: unknown): Response {
+  if (error instanceof AuthError) {
+    return new Response(JSON.stringify(error.toJSON()), { status: 401 });
+  }
+  
+  if (error instanceof ValidationError) {
+    return new Response(JSON.stringify({
+      message: error.message,
+      errors: error.errors,
+    }), { status: 400 });
+  }
+  
+  if (error instanceof NotFoundError) {
+    return new Response(JSON.stringify({
+      message: error.message,
+      resource: error.resource,
+    }), { status: 404 });
+  }
+  
+  if (error instanceof AppError) {
+    return new Response(JSON.stringify(error.toJSON()), { 
+      status: error.statusCode 
+    });
+  }
+  
+  // Fallback
+  return new Response('Internal Server Error', { status: 500 });
+}
+```