@almadar/server 2.0.0 → 2.0.2

package/dist/lib/serviceDiscovery.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Service Discovery — Registry for service orbital instances
+ *
+ * Enables distributed event routing by tracking which services are running,
+ * what events they emit/listen for, and where they can be reached.
+ *
+ * Supports:
+ * - In-memory registry (default, single-process)
+ * - Registration/deregistration with heartbeat
+ * - Event routing: find services that listen for a given event
+ * - Health tracking via TTL-based expiry
+ *
+ * @packageDocumentation
+ */
+/** Service registration record */
+export interface ServiceRegistration {
+    /** Service name (from .orb schema name) */
+    name: string;
+    /** Unique instance ID */
+    instanceId: string;
+    /** Host where the service is running */
+    host: string;
+    /** Port number */
+    port: number;
+    /** Hash of the .orb schema for version tracking */
+    orbHash: string;
+    /** Events this service emits */
+    emits: string[];
+    /** Events this service listens for */
+    listens: string[];
+    /** Registration timestamp */
+    registeredAt: number;
+    /** Last heartbeat timestamp */
+    lastHeartbeat: number;
+    /** Service status */
+    status: 'starting' | 'ready' | 'degraded' | 'stopping';
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Options for the service registry */
+export interface ServiceRegistryOptions {
+    /** TTL for service registrations in ms (default: 60000) */
+    heartbeatTtlMs?: number;
+    /** Cleanup interval for expired registrations (default: 30000) */
+    cleanupIntervalMs?: number;
+}
+/** Service registry interface for pluggable backends */
+export interface IServiceRegistry {
+    /** Register a service */
+    register(service: ServiceRegistration): Promise<void>;
+    /** Deregister a service */
+    deregister(instanceId: string): Promise<void>;
+    /** Update heartbeat for a service */
+    heartbeat(instanceId: string): Promise<void>;
+    /** Update service status */
+    updateStatus(instanceId: string, status: ServiceRegistration['status']): Promise<void>;
+    /** Get all registered services */
+    getAll(): Promise<ServiceRegistration[]>;
+    /** Get services by name */
+    getByName(name: string): Promise<ServiceRegistration[]>;
+    /** Find services that listen for a given event */
+    findListeners(event: string): Promise<ServiceRegistration[]>;
+    /** Find services that emit a given event */
+    findEmitters(event: string): Promise<ServiceRegistration[]>;
+    /** Remove expired registrations */
+    cleanup(ttlMs: number): Promise<number>;
+}
+/**
+ * In-memory service registry for single-process and development mode.
+ */
+export declare class InMemoryServiceRegistry implements IServiceRegistry {
+    private services;
+    register(service: ServiceRegistration): Promise<void>;
+    deregister(instanceId: string): Promise<void>;
+    heartbeat(instanceId: string): Promise<void>;
+    updateStatus(instanceId: string, status: ServiceRegistration['status']): Promise<void>;
+    getAll(): Promise<ServiceRegistration[]>;
+    getByName(name: string): Promise<ServiceRegistration[]>;
+    findListeners(event: string): Promise<ServiceRegistration[]>;
+    findEmitters(event: string): Promise<ServiceRegistration[]>;
+    cleanup(ttlMs: number): Promise<number>;
+}
+/**
+ * Service discovery manager that wraps a registry backend.
+ *
+ * Usage:
+ * ```typescript
+ * const discovery = new ServiceDiscovery();
+ * discovery.startCleanup();
+ *
+ * // Register a service
+ * await discovery.register({
+ *   name: 'LLMService',
+ *   instanceId: 'llm-001',
+ *   host: 'localhost',
+ *   port: 3001,
+ *   orbHash: 'abc123',
+ *   emits: ['LLM_RESPONSE', 'LLM_READY'],
+ *   listens: ['AGENT_LLM_REQUEST'],
+ * });
+ *
+ * // Find who can handle an event
+ * const listeners = await discovery.findListeners('AGENT_LLM_REQUEST');
+ * ```
+ */
+export declare class ServiceDiscovery {
+    private registry;
+    private options;
+    private cleanupTimer;
+    constructor(options?: ServiceRegistryOptions, registry?: IServiceRegistry);
+    /**
+     * Register a service with the registry.
+     */
+    register(service: Omit<ServiceRegistration, 'registeredAt' | 'lastHeartbeat' | 'status'> & {
+        status?: ServiceRegistration['status'];
+    }): Promise<void>;
+    /**
+     * Deregister a service.
+     */
+    deregister(instanceId: string): Promise<void>;
+    /**
+     * Send heartbeat for a service.
+     */
+    heartbeat(instanceId: string): Promise<void>;
+    /**
+     * Mark a service as ready.
+     */
+    markReady(instanceId: string): Promise<void>;
+    /**
+     * Mark a service as degraded.
+     */
+    markDegraded(instanceId: string): Promise<void>;
+    /**
+     * Find all services that listen for a given event.
+     */
+    findListeners(event: string): Promise<ServiceRegistration[]>;
+    /**
+     * Find all services that emit a given event.
+     */
+    findEmitters(event: string): Promise<ServiceRegistration[]>;
+    /**
+     * Get all registered services.
+     */
+    getAll(): Promise<ServiceRegistration[]>;
+    /**
+     * Get the full event topology (who emits what, who listens for what).
+     */
+    getEventTopology(): Promise<{
+        events: Array<{
+            event: string;
+            emitters: string[];
+            listeners: string[];
+        }>;
+    }>;
+    /**
+     * Start periodic cleanup of expired services.
+     */
+    startCleanup(): void;
+    /**
+     * Stop periodic cleanup.
+     */
+    stopCleanup(): void;
+    /**
+     * Get the underlying registry (for testing).
+     */
+    getRegistry(): IServiceRegistry;
+}
+//# sourceMappingURL=serviceDiscovery.d.ts.map

package/dist/lib/serviceDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serviceDiscovery.d.ts","sourceRoot":"","sources":["../../src/lib/serviceDiscovery.ts"],"names":[],"mappings":"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"}

package/dist/lib/websocket.d.ts

@@ -0,0 +1,41 @@
+/**
+ * WebSocket Event Broadcast - Cross-client event synchronization
+ *
+ * Broadcasts server-side events to all connected clients via WebSocket.
+ * This enables real-time updates across multiple browser clients.
+ *
+ * @packageDocumentation
+ */
+import { WebSocketServer } from 'ws';
+import type { Server } from 'http';
+/**
+ * Setup WebSocket server for event broadcasting.
+ *
+ * Listens to all server events via wildcard and broadcasts to connected clients.
+ *
+ * @param server - HTTP server to attach WebSocket to
+ * @param path - WebSocket endpoint path (default: '/ws/events')
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from 'http';
+ * import { setupEventBroadcast } from '@/lib/websocket';
+ *
+ * const server = createServer(app);
+ * setupEventBroadcast(server);
+ * ```
+ */
+export declare function setupEventBroadcast(server: Server, path?: string): WebSocketServer;
+/**
+ * Get the WebSocket server instance (for testing or advanced usage)
+ */
+export declare function getWebSocketServer(): WebSocketServer | null;
+/**
+ * Close the WebSocket server
+ */
+export declare function closeWebSocketServer(): Promise<void>;
+/**
+ * Get connected client count
+ */
+export declare function getConnectedClientCount(): number;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/lib/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/lib/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAA2B,MAAM,IAAI,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAC;AAmBpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,MAAqB,GAAG,eAAe,CA8EhG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBpD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAGhD"}

package/dist/middleware/__tests__/multi-user.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Unit tests for multi-user middleware
+ * @module @almadar/server/middleware/multi-user.test
+ */
+export {};
+//# sourceMappingURL=multi-user.test.d.ts.map

package/dist/middleware/__tests__/multi-user.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-user.test.d.ts","sourceRoot":"","sources":["../../../src/middleware/__tests__/multi-user.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/middleware/authenticateFirebase.d.ts

@@ -0,0 +1,4 @@
+import { NextFunction, Request, Response } from 'express';
+export declare function authenticateFirebase(req: Request, res: Response, next: NextFunction): Promise<void | Response<any, Record<string, any>>>;
+export default authenticateFirebase;
+//# sourceMappingURL=authenticateFirebase.d.ts.map

package/dist/middleware/authenticateFirebase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticateFirebase.d.ts","sourceRoot":"","sources":["../../src/middleware/authenticateFirebase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAwB1D,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,sDA0BzF;AAED,eAAe,oBAAoB,CAAC"}

package/dist/middleware/errorHandler.d.ts

@@ -0,0 +1,53 @@
+import { Request, Response, NextFunction } from 'express';
+/**
+ * Base application error class
+ */
+export declare class AppError extends Error {
+    statusCode: number;
+    message: string;
+    code?: string | undefined;
+    constructor(statusCode: number, message: string, code?: string | undefined);
+}
+/**
+ * 404 Not Found error
+ */
+export declare class NotFoundError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * 400 Bad Request / Validation error
+ */
+export declare class ValidationError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * 401 Unauthorized error
+ */
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * 403 Forbidden error
+ */
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * 409 Conflict error
+ */
+export declare class ConflictError extends AppError {
+    constructor(message?: string);
+}
+/**
+ * Global error handler middleware
+ */
+export declare const errorHandler: (err: Error, _req: Request, res: Response, _next: NextFunction) => void;
+/**
+ * Async handler wrapper to catch errors in async route handlers
+ */
+export declare const asyncHandler: (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * 404 handler for unmatched routes
+ */
+export declare const notFoundHandler: (req: Request, res: Response) => void;
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/middleware/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../src/middleware/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI1D;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAExB,UAAU,EAAE,MAAM;IAClB,OAAO,EAAE,MAAM;IACf,IAAI,CAAC,EAAE,MAAM;gBAFb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,GAAE,MAA6B;CAGnD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,GAAE,MAA4B;CAGlD;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,GAAE,MAAuB;CAG7C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,GAAE,MAAoB;CAG1C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,GAAE,MAA4B;CAGlD;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,KAAK,EACV,MAAM,OAAO,EACb,KAAK,QAAQ,EACb,OAAO,YAAY,KAClB,IA2CF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GACtB,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,OAAO,CAAC,MACzE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,SAE/C,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,EAAE,KAAK,QAAQ,KAAG,IAM7D,CAAC"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,4 @@
+export { errorHandler, notFoundHandler, asyncHandler, AppError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError, } from './errorHandler';
+export { validateBody, validateQuery, validateParams } from './validation';
+export { authenticateFirebase } from './authenticateFirebase.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/middleware/multi-user.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Multi-User Middleware
+ *
+ * Provides user isolation and session ownership using Firebase Auth.
+ *
+ * @packageDocumentation
+ */
+import type { Request, Response, NextFunction } from 'express';
+declare global {
+    namespace Express {
+        interface Request {
+            user?: {
+                uid: string;
+                email?: string;
+                roles?: string[];
+                orgId?: string;
+            };
+            userContext?: {
+                userId: string;
+                orgId?: string;
+                roles?: string[];
+            };
+        }
+    }
+}
+/**
+ * Middleware to set up user context from Firebase Auth
+ */
+export declare function multiUserMiddleware(req: Request, res: Response, next: NextFunction): Promise<void>;
+/**
+ * Verify Firebase Auth token from Authorization header
+ */
+export declare function verifyFirebaseAuth(req: Request, res: Response, next: NextFunction): Promise<void>;
+//# sourceMappingURL=multi-user.d.ts.map

package/dist/middleware/multi-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-user.d.ts","sourceRoot":"","sources":["../../src/middleware/multi-user.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,IAAI,CAAC,EAAE;gBACL,GAAG,EAAE,MAAM,CAAC;gBACZ,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;gBACjB,KAAK,CAAC,EAAE,MAAM,CAAC;aAChB,CAAC;YACF,WAAW,CAAC,EAAE;gBACZ,MAAM,EAAE,MAAM,CAAC;gBACf,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;aAClB,CAAC;SACH;KACF;CACF;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/dist/middleware/validation.d.ts

@@ -0,0 +1,15 @@
+import { Request, Response, NextFunction } from 'express';
+import { AnyZodObject } from 'zod';
+/**
+ * Middleware to validate request body against a Zod schema
+ */
+export declare const validateBody: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Middleware to validate request query parameters against a Zod schema
+ */
+export declare const validateQuery: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Middleware to validate request params against a Zod schema
+ */
+export declare const validateParams: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/middleware/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/middleware/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAY,MAAM,KAAK,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,YAAY,GACtB,QAAQ,YAAY,MAAY,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAmB9F,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,aAAa,GACvB,QAAQ,YAAY,MAAY,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAmB9F,CAAC;AAEJ;;GAEG;AACH,eAAO,MAAM,cAAc,GACxB,QAAQ,YAAY,MAAY,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,OAAO,CAAC,IAAI,CAmB9F,CAAC"}

package/dist/routes/__tests__/observability.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Unit tests for observability routes
+ * @module @almadar/server/routes/observability.test
+ */
+export {};
+//# sourceMappingURL=observability.test.d.ts.map

package/dist/routes/__tests__/observability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.test.d.ts","sourceRoot":"","sources":["../../../src/routes/__tests__/observability.test.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/routes/observability.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Observability Routes
+ *
+ * Provides endpoints for metrics, health checks, and telemetry.
+ *
+ * @packageDocumentation
+ */
+declare const router: import("express-serve-static-core").Router;
+export default router;
+//# sourceMappingURL=observability.d.ts.map

package/dist/routes/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/routes/observability.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,QAAA,MAAM,MAAM,4CAAW,CAAC;AAyExB,eAAe,MAAM,CAAC"}

package/dist/services/DataService.d.ts

@@ -0,0 +1,66 @@
+/**
+ * DataService - Unified data access abstraction
+ *
+ * Provides a common interface for data operations that can be backed by
+ * either MockDataService (for development) or Firebase (for production).
+ *
+ * @packageDocumentation
+ */
+import { type FieldSchema } from './MockDataService.js';
+import { type ParsedFilter } from '../utils/queryFilters.js';
+interface BaseEntity {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Pagination options for list queries
+ */
+export interface PaginationOptions {
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Search term to filter results */
+    search?: string;
+    /** Fields to search in (defaults to all string fields) */
+    searchFields?: string[];
+    /** Sort field */
+    sortBy?: string;
+    /** Sort direction */
+    sortOrder?: 'asc' | 'desc';
+    /** Filters parsed from query params */
+    filters?: ParsedFilter[];
+}
+/**
+ * Paginated response structure
+ */
+export interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+export interface DataService {
+    list<T>(collection: string): Promise<T[]>;
+    listPaginated<T>(collection: string, options?: PaginationOptions): Promise<PaginatedResult<T>>;
+    getById<T>(collection: string, id: string): Promise<T | null>;
+    create<T extends BaseEntity>(collection: string, data: Partial<T>): Promise<T>;
+    update<T extends BaseEntity>(collection: string, id: string, data: Partial<T>): Promise<T | null>;
+    delete(collection: string, id: string): Promise<boolean>;
+}
+export declare function getDataService(): DataService;
+export declare function resetDataService(): void;
+export interface EntitySeedConfig {
+    name: string;
+    fields: FieldSchema[];
+    seedCount: number;
+}
+/**
+ * Seed mock data for multiple entities.
+ * Only works when USE_MOCK_DATA is enabled.
+ */
+export declare function seedMockData(entities: EntitySeedConfig[]): void;
+export {};
+//# sourceMappingURL=DataService.d.ts.map

package/dist/services/DataService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataService.d.ts","sourceRoot":"","sources":["../../src/services/DataService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,0BAA0B,CAAC;AAMlC,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,iBAAiB;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,uCAAuC;IACvC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1C,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9D,MAAM,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/E,MAAM,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1D;AAkTD,wBAAgB,cAAc,IAAI,WAAW,CAK5C;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAMD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAa/D"}

package/dist/services/MockDataService.d.ts

@@ -0,0 +1,110 @@
+/**
+ * MockDataService - In-memory data store with faker-based mock generation
+ *
+ * Provides a stateful mock data layer that supports all CRUD operations.
+ * Uses @faker-js/faker for realistic data generation based on field types.
+ *
+ * @packageDocumentation
+ */
+export interface FieldSchema {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'relation' | 'array';
+    required?: boolean;
+    enumValues?: string[];
+    min?: number;
+    max?: number;
+    fakerMethod?: string;
+    relatedEntity?: string;
+}
+export interface EntitySchema {
+    fields: FieldSchema[];
+    seedCount?: number;
+}
+interface BaseEntity {
+    id: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * In-memory mock data store with CRUD operations and faker-based seeding.
+ */
+export declare class MockDataService {
+    private stores;
+    private schemas;
+    private idCounters;
+    constructor();
+    /**
+     * Initialize store for an entity.
+     */
+    private getStore;
+    /**
+     * Generate next ID for an entity.
+     */
+    private nextId;
+    /**
+     * Register an entity schema.
+     */
+    registerSchema(entityName: string, schema: EntitySchema): void;
+    /**
+     * Seed an entity with mock data.
+     */
+    seed(entityName: string, fields: FieldSchema[], count?: number): void;
+    /**
+     * Generate a single mock item based on field schemas.
+     */
+    private generateMockItem;
+    /**
+     * Generate a mock value for a field based on its schema.
+     */
+    private generateFieldValue;
+    /**
+     * Generate a string value based on field name heuristics.
+     * Generic name/title fields use entity-aware format (e.g., "Project Name 1").
+     * Specific fields (email, phone, etc.) use faker.
+     */
+    private generateStringValue;
+    /**
+     * Capitalize first letter of a string.
+     */
+    private capitalizeFirst;
+    /**
+     * Generate a date value based on field name heuristics.
+     */
+    private generateDateValue;
+    /**
+     * List all items of an entity.
+     */
+    list<T>(entityName: string): T[];
+    /**
+     * Get a single item by ID.
+     */
+    getById<T>(entityName: string, id: string): T | null;
+    /**
+     * Create a new item.
+     */
+    create<T extends BaseEntity>(entityName: string, data: Partial<T>): T;
+    /**
+     * Update an existing item.
+     */
+    update<T extends BaseEntity>(entityName: string, id: string, data: Partial<T>): T | null;
+    /**
+     * Delete an item.
+     */
+    delete(entityName: string, id: string): boolean;
+    /**
+     * Clear all data for an entity.
+     */
+    clear(entityName: string): void;
+    /**
+     * Clear all data.
+     */
+    clearAll(): void;
+    /**
+     * Get count of items for an entity.
+     */
+    count(entityName: string): number;
+}
+export declare function getMockDataService(): MockDataService;
+export declare function resetMockDataService(): void;
+export {};
+//# sourceMappingURL=MockDataService.d.ts.map

package/dist/services/MockDataService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MockDataService.d.ts","sourceRoot":"","sources":["../../src/services/MockDataService.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAMD;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAgD;IAC9D,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,UAAU,CAAkC;;IAcpD;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,OAAO,CAAC,MAAM;IAWd;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI;IAI9D;;OAEG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,KAAK,GAAE,MAAW,GAAG,IAAI;IAYzE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAgD1B;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA0B3B;;OAEG;IACH,OAAO,CAAC,eAAe;IAIvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAoBzB;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC,EAAE;IAKhC;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAMpD;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IAgBrE;;OAEG;IACH,MAAM,CAAC,CAAC,SAAS,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI;IAmBxF;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAa/C;;OAEG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAM/B;;OAEG;IACH,QAAQ,IAAI,IAAI;IAKhB;;OAEG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAIlC;AAKD,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAG3C"}

package/dist/services/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Services barrel export
+ *
+ * @packageDocumentation
+ */
+export { MockDataService, getMockDataService, resetMockDataService, type FieldSchema, type EntitySchema } from './MockDataService.js';
+export { getDataService, resetDataService, seedMockData, type DataService, type EntitySeedConfig } from './DataService.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACtI,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}