@htlkg/core 0.0.2 → 0.0.3

package/src/routes/routes.md

@@ -0,0 +1,189 @@
+# Routes Module
+
+Type-safe route definitions with parameter interpolation. Eliminates string literals scattered across the codebase.
+
+## Installation
+
+```typescript
+import { 
+  routes,
+  adminRoutes,
+  portalRoutes,
+  authRoutes,
+  apiRoutes,
+  createRoute,
+  matchesRoute,
+  extractRouteParams,
+  navigateTo,
+  buildUrl,
+} from '@htlkg/core/routes';
+```
+
+## Route Objects
+
+### adminRoutes
+
+```typescript
+adminRoutes.dashboard()           // "/admin"
+adminRoutes.accounts()            // "/admin/accounts"
+adminRoutes.account({ id: 123 })  // "/admin/accounts/123"
+adminRoutes.accountBrands({ id: 123 }) // "/admin/accounts/123/brands"
+adminRoutes.brands()              // "/admin/brands"
+adminRoutes.brand({ id: 456 })    // "/admin/brands/456"
+adminRoutes.brandSettings({ id: 456 }) // "/admin/brands/456/settings"
+adminRoutes.users()               // "/admin/users"
+adminRoutes.user({ id: 'abc' })   // "/admin/users/abc"
+adminRoutes.profile()             // "/admin/user"
+adminRoutes.analytics()           // "/admin/analytics"
+```
+
+### portalRoutes
+
+```typescript
+portalRoutes.home()                      // "/"
+portalRoutes.brand({ brandId: 123 })     // "/brands/123"
+portalRoutes.brandSettings({ brandId: 123 })  // "/brands/123/settings"
+portalRoutes.brandDashboard({ brandId: 123 }) // "/brands/123/dashboard"
+portalRoutes.brandAnalytics({ brandId: 123 }) // "/brands/123/analytics"
+```
+
+### authRoutes
+
+```typescript
+authRoutes.login()         // "/login"
+authRoutes.logout()        // "/api/auth/logout"
+authRoutes.confirmSignIn() // "/api/auth/confirm-signin"
+```
+
+### apiRoutes
+
+```typescript
+apiRoutes.auth.logout()        // "/api/auth/logout"
+apiRoutes.auth.confirmSignIn() // "/api/auth/confirm-signin"
+```
+
+## Creating Custom Routes
+
+```typescript
+import { createRoute } from '@htlkg/core/routes';
+
+// Simple route
+const homeRoute = createRoute('/home');
+homeRoute(); // "/home"
+
+// Route with parameters
+const userRoute = createRoute<{ id: string }>('/users/:id');
+userRoute({ id: '123' }); // "/users/123"
+userRoute.path;           // "/users/:id"
+
+// Multiple parameters
+const postRoute = createRoute<{ userId: string; postId: string }>(
+  '/users/:userId/posts/:postId'
+);
+postRoute({ userId: '1', postId: '42' }); // "/users/1/posts/42"
+```
+
+## Utility Functions
+
+### matchesRoute
+
+Check if a path matches a route pattern.
+
+```typescript
+import { matchesRoute, adminRoutes } from '@htlkg/core/routes';
+
+matchesRoute('/admin/accounts/123', adminRoutes.account);  // true
+matchesRoute('/admin/users', adminRoutes.account);         // false
+```
+
+### extractRouteParams
+
+Extract parameters from a path.
+
+```typescript
+import { extractRouteParams, adminRoutes } from '@htlkg/core/routes';
+
+const params = extractRouteParams('/admin/accounts/123', adminRoutes.account);
+// { id: '123' }
+
+const noMatch = extractRouteParams('/other/path', adminRoutes.account);
+// null
+```
+
+### navigateTo
+
+Client-side navigation helper.
+
+```typescript
+import { navigateTo, adminRoutes } from '@htlkg/core/routes';
+
+// Navigate to account page
+navigateTo(adminRoutes.account({ id: 123 }));
+```
+
+### buildUrl
+
+Build URL with query parameters.
+
+```typescript
+import { buildUrl, adminRoutes } from '@htlkg/core/routes';
+
+buildUrl(adminRoutes.users(), { page: 2, status: 'active' });
+// "/admin/users?page=2&status=active"
+
+buildUrl(adminRoutes.brands(), { search: null, page: 1 });
+// "/admin/brands?page=1" (null values excluded)
+```
+
+## Combined Routes Object
+
+Access all routes through a single object:
+
+```typescript
+import { routes } from '@htlkg/core/routes';
+
+routes.admin.dashboard()
+routes.portal.brand({ brandId: 123 })
+routes.auth.login()
+routes.api.auth.logout()
+```
+
+## TypeScript Support
+
+Routes are fully typed with parameter inference:
+
+```typescript
+import { adminRoutes } from '@htlkg/core/routes';
+
+// TypeScript enforces correct parameters
+adminRoutes.account({ id: 123 });     // ✓
+adminRoutes.account({ id: '123' });   // ✓ (string | number)
+adminRoutes.account({});              // ✗ Error: missing 'id'
+adminRoutes.account({ foo: 'bar' });  // ✗ Error: unknown property
+```
+
+## Usage in Components
+
+```astro
+---
+import { adminRoutes } from '@htlkg/core/routes';
+
+const accountId = 123;
+---
+
+<a href={adminRoutes.account({ id: accountId })}>
+  View Account
+</a>
+
+<a href={adminRoutes.brands()}>
+  All Brands
+</a>
+```
+
+```typescript
+// In Vue/React components
+import { adminRoutes, buildUrl } from '@htlkg/core/routes';
+
+const accountUrl = adminRoutes.account({ id: props.accountId });
+const filteredUrl = buildUrl(adminRoutes.users(), { role: 'admin' });
+```

package/src/types/index.ts

@@ -0,0 +1,94 @@
+/**
+ * @htlkg/core/types
+ * Core TypeScript types and interfaces for Hotelinking applications
+ */
+
+/**
+ * AuthUser interface representing an authenticated user
+ * Re-exported from auth module for convenience
+ */
+export interface AuthUser {
+	username: string;
+	email: string;
+	brandIds: number[];
+	accountIds: number[];
+	isAdmin: boolean;
+	isSuperAdmin: boolean;
+	roles: string[];
+}
+
+/**
+ * Brand interface representing a hotel brand
+ */
+export interface Brand {
+	id: string;
+	name: string;
+	accountId: string;
+	logo?: string;
+	timezone: string;
+	status: "active" | "inactive" | "maintenance" | "suspended";
+	settings: Record<string, any>;
+}
+
+/**
+ * Account interface representing a customer account
+ */
+export interface Account {
+	id: string;
+	name: string;
+	logo?: string;
+	subscription: Record<string, any>;
+	settings: Record<string, any>;
+}
+
+/**
+ * Product interface representing a product definition
+ */
+export interface Product {
+	id: string;
+	name: string;
+	version: string;
+	schema: Record<string, any>;
+	uiSchema: Record<string, any>;
+	defaultConfig: Record<string, any>;
+	isActive: boolean;
+}
+
+/**
+ * ProductInstance interface representing an enabled product for a brand
+ */
+export interface ProductInstance {
+	id: string;
+	productId: string;
+	productName: string;
+	brandId: string;
+	accountId: string;
+	enabled: boolean;
+	config: Record<string, any>;
+	version: string;
+}
+
+/**
+ * User interface representing a system user
+ */
+export interface User {
+	id: string;
+	cognitoId: string;
+	email: string;
+	accountId: string;
+	brandIds?: string[];
+	roles?: string[];
+	permissions?: Record<string, any>;
+	lastLogin?: string;
+	status: "active" | "inactive" | "pending" | "suspended";
+}
+
+/**
+ * BrandUser interface representing a user associated with a brand
+ */
+export interface BrandUser {
+	userId: string;
+	brandId: string;
+	role: string;
+	permissions: string[];
+}

package/src/types/types.md

@@ -0,0 +1,144 @@
+# Types Module
+
+Core TypeScript interfaces for Hotelinking applications.
+
+## Installation
+
+```typescript
+import type { 
+  AuthUser,
+  Brand,
+  Account,
+  Product,
+  ProductInstance,
+  User,
+  BrandUser,
+} from '@htlkg/core/types';
+```
+
+## Interfaces
+
+### AuthUser
+
+Authenticated user from Cognito.
+
+```typescript
+interface AuthUser {
+  username: string;
+  email: string;
+  brandIds: number[];
+  accountIds: number[];
+  isAdmin: boolean;
+  isSuperAdmin: boolean;
+  roles: string[];
+}
+```
+
+### Brand
+
+Hotel brand entity.
+
+```typescript
+interface Brand {
+  id: string;
+  name: string;
+  accountId: string;
+  logo?: string;
+  timezone: string;
+  status: 'active' | 'inactive' | 'maintenance' | 'suspended';
+  settings: Record<string, any>;
+}
+```
+
+
+### Account
+
+Customer account entity.
+
+```typescript
+interface Account {
+  id: string;
+  name: string;
+  logo?: string;
+  subscription: Record<string, any>;
+  settings: Record<string, any>;
+}
+```
+
+### Product
+
+Product definition.
+
+```typescript
+interface Product {
+  id: string;
+  name: string;
+  version: string;
+  schema: Record<string, any>;
+  uiSchema: Record<string, any>;
+  defaultConfig: Record<string, any>;
+  isActive: boolean;
+}
+```
+
+### ProductInstance
+
+Enabled product for a brand.
+
+```typescript
+interface ProductInstance {
+  id: string;
+  productId: string;
+  productName: string;
+  brandId: string;
+  accountId: string;
+  enabled: boolean;
+  config: Record<string, any>;
+  version: string;
+}
+```
+
+### User
+
+System user entity.
+
+```typescript
+interface User {
+  id: string;
+  cognitoId: string;
+  email: string;
+  accountId: string;
+  brandIds?: string[];
+  roles?: string[];
+  permissions?: Record<string, any>;
+  lastLogin?: string;
+  status: 'active' | 'inactive' | 'pending' | 'suspended';
+}
+```
+
+### BrandUser
+
+User-brand association.
+
+```typescript
+interface BrandUser {
+  userId: string;
+  brandId: string;
+  role: string;
+  permissions: string[];
+}
+```
+
+## Usage Examples
+
+```typescript
+import type { Brand, User, ProductInstance } from '@htlkg/core/types';
+
+function getBrandProducts(brand: Brand): ProductInstance[] {
+  // ...
+}
+
+function isUserActive(user: User): boolean {
+  return user.status === 'active';
+}
+```

package/src/utils/index.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+	formatDate,
+	truncateText,
+	groupBy,
+	debounce,
+	throttle,
+} from "./index";
+
+describe("Utility Functions", () => {
+	describe("formatDate", () => {
+		it("should format Date object", () => {
+			const date = new Date("2024-01-15T10:30:00Z");
+			const result = formatDate(date);
+			expect(result).toContain("Jan");
+			expect(result).toContain("15");
+			expect(result).toContain("2024");
+		});
+
+		it("should format date string", () => {
+			const result = formatDate("2024-01-15");
+			expect(result).toContain("Jan");
+			expect(result).toContain("15");
+			expect(result).toContain("2024");
+		});
+
+		it("should format timestamp", () => {
+			const timestamp = new Date("2024-01-15").getTime();
+			const result = formatDate(timestamp);
+			expect(result).toContain("Jan");
+			expect(result).toContain("15");
+			expect(result).toContain("2024");
+		});
+
+		it("should use custom locale", () => {
+			const date = new Date("2024-01-15");
+			const result = formatDate(date, "es-ES");
+			// Spanish month abbreviation
+			expect(result).toContain("ene");
+		});
+
+		it("should use custom options", () => {
+			const date = new Date("2024-01-15T10:30:00Z");
+			const result = formatDate(date, "en-US", {
+				year: "numeric",
+				month: "long",
+				day: "numeric",
+				hour: "2-digit",
+				minute: "2-digit",
+			});
+			expect(result).toContain("January");
+		});
+	});
+
+	describe("truncateText", () => {
+		it("should not truncate short text", () => {
+			const result = truncateText("Hello", 10);
+			expect(result).toBe("Hello");
+		});
+
+		it("should truncate long text", () => {
+			const result = truncateText("Hello World", 8);
+			expect(result).toBe("Hello...");
+		});
+
+		it("should use custom suffix", () => {
+			const result = truncateText("Hello World", 8, "…");
+			expect(result).toBe("Hello W…");
+		});
+
+		it("should handle exact length", () => {
+			const result = truncateText("Hello", 5);
+			expect(result).toBe("Hello");
+		});
+
+		it("should handle empty string", () => {
+			const result = truncateText("", 10);
+			expect(result).toBe("");
+		});
+
+		it("should account for suffix length", () => {
+			const result = truncateText("Hello World", 10, "...");
+			expect(result).toBe("Hello W...");
+			expect(result.length).toBe(10);
+		});
+	});
+
+	describe("groupBy", () => {
+		it("should group items by key", () => {
+			const items = [
+				{ id: 1, category: "A" },
+				{ id: 2, category: "B" },
+				{ id: 3, category: "A" },
+			];
+			const result = groupBy(items, (item) => item.category);
+
+			expect(result).toEqual({
+				A: [
+					{ id: 1, category: "A" },
+					{ id: 3, category: "A" },
+				],
+				B: [{ id: 2, category: "B" }],
+			});
+		});
+
+		it("should handle numeric keys", () => {
+			const items = [
+				{ id: 1, value: 10 },
+				{ id: 2, value: 20 },
+				{ id: 3, value: 10 },
+			];
+			const result = groupBy(items, (item) => item.value);
+
+			expect(result).toEqual({
+				10: [
+					{ id: 1, value: 10 },
+					{ id: 3, value: 10 },
+				],
+				20: [{ id: 2, value: 20 }],
+			});
+		});
+
+		it("should handle empty array", () => {
+			const result = groupBy([], (item: any) => item.key);
+			expect(result).toEqual({});
+		});
+
+		it("should handle single item", () => {
+			const items = [{ id: 1, type: "test" }];
+			const result = groupBy(items, (item) => item.type);
+
+			expect(result).toEqual({
+				test: [{ id: 1, type: "test" }],
+			});
+		});
+	});
+
+	describe("debounce", () => {
+		beforeEach(() => {
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.restoreAllMocks();
+		});
+
+		it("should delay function execution", () => {
+			const fn = vi.fn();
+			const debounced = debounce(fn, 100);
+
+			debounced();
+			expect(fn).not.toHaveBeenCalled();
+
+			vi.advanceTimersByTime(100);
+			expect(fn).toHaveBeenCalledTimes(1);
+		});
+
+		it("should cancel previous calls", () => {
+			const fn = vi.fn();
+			const debounced = debounce(fn, 100);
+
+			debounced();
+			debounced();
+			debounced();
+
+			vi.advanceTimersByTime(100);
+			expect(fn).toHaveBeenCalledTimes(1);
+		});
+
+		it("should pass arguments to function", () => {
+			const fn = vi.fn();
+			const debounced = debounce(fn, 100);
+
+			debounced("arg1", "arg2");
+			vi.advanceTimersByTime(100);
+
+			expect(fn).toHaveBeenCalledWith("arg1", "arg2");
+		});
+
+		it("should reset timer on each call", () => {
+			const fn = vi.fn();
+			const debounced = debounce(fn, 100);
+
+			debounced();
+			vi.advanceTimersByTime(50);
+			debounced();
+			vi.advanceTimersByTime(50);
+
+			expect(fn).not.toHaveBeenCalled();
+
+			vi.advanceTimersByTime(50);
+			expect(fn).toHaveBeenCalledTimes(1);
+		});
+	});
+
+	describe("throttle", () => {
+		beforeEach(() => {
+			vi.useFakeTimers();
+		});
+
+		afterEach(() => {
+			vi.restoreAllMocks();
+		});
+
+		it("should execute function immediately", () => {
+			const fn = vi.fn();
+			const throttled = throttle(fn, 100);
+
+			throttled();
+			expect(fn).toHaveBeenCalledTimes(1);
+		});
+
+		it("should ignore calls within limit", () => {
+			const fn = vi.fn();
+			const throttled = throttle(fn, 100);
+
+			throttled();
+			throttled();
+			throttled();
+
+			expect(fn).toHaveBeenCalledTimes(1);
+		});
+
+		it("should allow calls after limit", () => {
+			const fn = vi.fn();
+			const throttled = throttle(fn, 100);
+
+			throttled();
+			expect(fn).toHaveBeenCalledTimes(1);
+
+			vi.advanceTimersByTime(100);
+			throttled();
+			expect(fn).toHaveBeenCalledTimes(2);
+		});
+
+		it("should pass arguments to function", () => {
+			const fn = vi.fn();
+			const throttled = throttle(fn, 100);
+
+			throttled("arg1", "arg2");
+			expect(fn).toHaveBeenCalledWith("arg1", "arg2");
+		});
+
+		it("should throttle multiple rapid calls", () => {
+			const fn = vi.fn();
+			const throttled = throttle(fn, 100);
+
+			throttled();
+			vi.advanceTimersByTime(50);
+			throttled();
+			vi.advanceTimersByTime(50);
+			throttled();
+
+			expect(fn).toHaveBeenCalledTimes(2);
+		});
+	});
+});