@almadar/server 1.4.5 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/server",
-  "version": "1.4.5",
+  "version": "2.0.0",
   "description": "Shared server infrastructure for Almadar applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,23 +39,18 @@
     "access": "public"
   },
   "dependencies": {
+    "@almadar/agent": ">=2.0.0",
+    "@almadar/core": ">=2.0.0",
     "@faker-js/faker": "^9.3.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.0",
+    "firebase-admin": "^12.0.0",
     "helmet": "^8.0.0",
     "ws": "^8.18.0",
-    "zod": "^3.24.0",
-    "@almadar/agent": "1.6.4",
-    "@almadar/core": "1.0.18"
+    "zod": "^3.24.0"
   },
   "peerDependencies": {
-    "express": "^4.0.0",
-    "firebase-admin": "^12.0.0"
-  },
-  "peerDependenciesMeta": {
-    "firebase-admin": {
-      "optional": true
-    }
+    "express": "^4.0.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",
@@ -71,7 +66,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/almadar-io/almadar.git",
-    "directory": "packages/almadar-server"
+    "directory": "docs/packages/server"
   },
   "license": "MIT",
   "keywords": [
@@ -80,6 +75,7 @@
     "express",
     "middleware"
   ],
+  "homepage": "https://github.com/almadar-io/almadar#readme",
   "scripts": {
     "build": "NODE_OPTIONS='--max-old-space-size=4096' tsup",
     "build:watch": "tsup --watch",

package/dist/deepagent/memory.d.ts

@@ -1,20 +0,0 @@
-import { MemoryManager } from '@almadar/agent';
-
-/**
- * Memory Manager Singleton
- *
- * Provides Firestore-backed memory management for DeepAgent.
- *
- * @packageDocumentation
- */
-
-/**
- * Get or create the MemoryManager singleton
- */
-declare function getMemoryManager(): MemoryManager;
-/**
- * Reset the MemoryManager (useful for testing)
- */
-declare function resetMemoryManager(): void;
-
-export { getMemoryManager, resetMemoryManager };

package/dist/deepagent/session.d.ts

@@ -1,20 +0,0 @@
-import { SessionManager } from '@almadar/agent';
-
-/**
- * Session Manager Singleton
- *
- * Provides Firestore-backed session management with full GAP features.
- *
- * @packageDocumentation
- */
-
-/**
- * Get or create the SessionManager singleton
- */
-declare function getSessionManager(): SessionManager;
-/**
- * Reset the SessionManager (useful for testing)
- */
-declare function resetSessionManager(): void;
-
-export { getSessionManager, resetSessionManager };

package/dist/deepagent/skill-agent.d.ts

@@ -1,24 +0,0 @@
-import { SkillAgentOptions, SkillAgentResult } from '@almadar/agent';
-export { getMemoryManager } from './memory.js';
-export { getSessionManager } from './session.js';
-
-/**
- * Skill Agent Factory
- *
- * Creates DeepAgent instances with full GAP feature integration.
- *
- * @packageDocumentation
- */
-
-interface ServerSkillAgentOptions extends SkillAgentOptions {
-    /** User ID from Firebase Auth */
-    userId: string;
-    /** App/Project ID for context */
-    appId?: string;
-}
-/**
- * Create a skill agent with full server-side GAP integration
- */
-declare function createServerSkillAgent(options: ServerSkillAgentOptions): Promise<SkillAgentResult>;
-
-export { createServerSkillAgent };

package/dist/index-B64ll_cY.d.ts

@@ -1,149 +0,0 @@
-import admin from 'firebase-admin';
-import { WebSocketServer } from 'ws';
-import { Server } from 'http';
-
-declare const env: {
-    NODE_ENV: "development" | "production" | "test";
-    PORT: number;
-    CORS_ORIGIN: string | string[];
-    API_PREFIX: string;
-    USE_MOCK_DATA: boolean;
-    DATABASE_URL?: string | undefined;
-    FIREBASE_PROJECT_ID?: string | undefined;
-    FIREBASE_CLIENT_EMAIL?: string | undefined;
-    FIREBASE_PRIVATE_KEY?: string | undefined;
-    FIREBASE_SERVICE_ACCOUNT_PATH?: string | undefined;
-    FIRESTORE_EMULATOR_HOST?: string | undefined;
-    FIREBASE_AUTH_EMULATOR_HOST?: string | undefined;
-    MOCK_SEED?: number | undefined;
-};
-
-declare const logger: {
-    debug: (message: string, meta?: unknown) => void;
-    info: (message: string, meta?: unknown) => void;
-    warn: (message: string, meta?: unknown) => void;
-    error: (message: string, meta?: unknown) => void;
-};
-
-/**
- * Server EventBus - Singleton for server-side cross-trait communication
- *
- * This EventBus enables:
- * - Server-side trait event emission after CRUD operations
- * - Server-side trait listeners responding to events
- * - Cross-client event broadcast via WebSocket
- *
- * @packageDocumentation
- */
-type EventHandler = (payload: unknown, meta?: Record<string, unknown>) => void;
-interface EventLogEntry {
-    event: string;
-    payload: unknown;
-    timestamp: number;
-    listenerCount: number;
-    wildcardListenerCount: number;
-}
-/**
- * Simple EventBus implementation for server-side events
- */
-declare class EventBus {
-    private handlers;
-    private debug;
-    private eventLog;
-    constructor(options?: {
-        debug?: boolean;
-    });
-    on(event: string, handler: EventHandler): () => void;
-    off(event: string, handler: EventHandler): void;
-    emit(event: string, payload?: unknown, meta?: Record<string, unknown>): void;
-    getRecentEvents(limit?: number): EventLogEntry[];
-    clearEventLog(): void;
-    getListenerCounts(): Record<string, number>;
-    clear(): void;
-}
-/**
- * Singleton EventBus instance for server-side event communication.
- */
-declare const serverEventBus: EventBus;
-/**
- * Type-safe event emission helper
- */
-declare function emitEntityEvent(entityType: string, action: 'CREATED' | 'UPDATED' | 'DELETED', payload: Record<string, unknown>): void;
-
-/**
- * Database Accessors & Initialization
- *
- * This module provides:
- * - `initializeFirebase()` — convenience function to init Firebase from env vars
- * - `getFirestore()`, `getAuth()` — accessors for Firebase services
- * - `db` — lazy Firestore proxy (no eager initialization)
- *
- * The consuming application MUST call `initializeFirebase()` or
- * `admin.initializeApp()` before using any Firebase-dependent features.
- */
-
-/**
- * Initialize Firebase Admin SDK from environment variables.
- *
- * Reads: FIREBASE_PROJECT_ID, FIREBASE_CLIENT_EMAIL, FIREBASE_PRIVATE_KEY,
- *        FIREBASE_SERVICE_ACCOUNT_PATH, FIRESTORE_EMULATOR_HOST
- *
- * Safe to call multiple times — returns existing app if already initialized.
- */
-declare function initializeFirebase(): admin.app.App;
-/**
- * Get Firestore instance from the pre-initialized Firebase app.
- */
-declare function getFirestore(): admin.firestore.Firestore;
-/**
- * Get Firebase Auth instance from the pre-initialized Firebase app.
- */
-declare function getAuth(): admin.auth.Auth;
-
-/**
- * Lazy Firestore proxy — resolves on first property access, not at import time.
- * This prevents the "Firebase not initialized" error during module loading.
- */
-declare const db: admin.firestore.Firestore;
-
-/**
- * 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
- */
-
-/**
- * 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);
- * ```
- */
-declare function setupEventBroadcast(server: Server, path?: string): WebSocketServer;
-/**
- * Get the WebSocket server instance (for testing or advanced usage)
- */
-declare function getWebSocketServer(): WebSocketServer | null;
-/**
- * Close the WebSocket server
- */
-declare function closeWebSocketServer(): Promise<void>;
-/**
- * Get connected client count
- */
-declare function getConnectedClientCount(): number;
-
-export { EventBus as E, type EventLogEntry as a, env as b, closeWebSocketServer as c, db as d, emitEntityEvent as e, getConnectedClientCount as f, getAuth as g, getFirestore as h, getWebSocketServer as i, initializeFirebase as j, setupEventBroadcast as k, logger as l, serverEventBus as s };

package/dist/index-D8fohXsO.d.ts

@@ -1,178 +0,0 @@
-import { ParsedFilter } from './utils/index.js';
-
-/**
- * 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
- */
-interface FieldSchema {
-    name: string;
-    type: 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'relation' | 'array';
-    required?: boolean;
-    enumValues?: string[];
-    min?: number;
-    max?: number;
-    fakerMethod?: string;
-    relatedEntity?: string;
-}
-interface EntitySchema {
-    fields: FieldSchema[];
-    seedCount?: number;
-}
-interface BaseEntity$1 {
-    id: string;
-    createdAt: Date;
-    updatedAt: Date;
-}
-/**
- * In-memory mock data store with CRUD operations and faker-based seeding.
- */
-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$1>(entityName: string, data: Partial<T>): T;
-    /**
-     * Update an existing item.
-     */
-    update<T extends BaseEntity$1>(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;
-}
-declare const mockDataService: MockDataService;
-
-/**
- * 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
- */
-
-interface BaseEntity {
-    id: string;
-    createdAt: Date;
-    updatedAt: Date;
-}
-/**
- * Pagination options for list queries
- */
-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
- */
-interface PaginatedResult<T> {
-    data: T[];
-    total: number;
-    page: number;
-    pageSize: number;
-    totalPages: number;
-}
-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>;
-}
-/**
- * Singleton data service instance.
- * Use this in handlers for all data operations.
- */
-declare const dataService: DataService;
-interface EntitySeedConfig {
-    name: string;
-    fields: FieldSchema[];
-    seedCount: number;
-}
-/**
- * Seed mock data for multiple entities.
- * Only works when USE_MOCK_DATA is enabled.
- */
-declare function seedMockData(entities: EntitySeedConfig[]): void;
-
-export { type DataService as D, type EntitySchema as E, type FieldSchema as F, MockDataService as M, type PaginatedResult as P, type EntitySeedConfig as a, type PaginationOptions as b, dataService as d, mockDataService as m, seedMockData as s };

package/dist/index.d.ts

@@ -1,41 +0,0 @@
-export { E as EventBus, a as EventLogEntry, c as closeWebSocketServer, d as db, e as emitEntityEvent, b as env, g as getAuth, f as getConnectedClientCount, h as getFirestore, i as getWebSocketServer, j as initializeFirebase, l as logger, s as serverEventBus, k as setupEventBroadcast } from './index-B64ll_cY.js';
-import { Router } from 'express';
-export { AppError, ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, asyncHandler, authenticateFirebase, errorHandler, notFoundHandler, validateBody, validateParams, validateQuery } from './middleware/index.js';
-export { D as DataService, E as EntitySchema, a as EntitySeedConfig, F as FieldSchema, M as MockDataService, P as PaginatedResult, b as PaginationOptions, d as dataService, m as mockDataService, s as seedMockData } from './index-D8fohXsO.js';
-export { ChangeSetStore, SchemaProtectionService, SchemaStore, SnapshotStore, ValidationStore, fromFirestoreFormat, toFirestoreFormat } from './stores/index.js';
-export { FirestoreWhereFilterOp, PaginationParams, ParsedFilter, applyFiltersToQuery, extractPaginationParams, parseQueryFilters } from './utils/index.js';
-export { getMemoryManager as getAgentMemoryManager, getMemoryManager, resetMemoryManager } from './deepagent/memory.js';
-export { getSessionManager as getAgentSessionManager, getSessionManager, resetSessionManager } from './deepagent/session.js';
-export { createServerSkillAgent } from './deepagent/skill-agent.js';
-export { multiUserMiddleware, verifyFirebaseAuth } from './middleware/multi-user.js';
-export { setupStateSyncWebSocket } from './websocket/state-sync.js';
-export { default as observabilityRouter } from './routes/observability.js';
-export { default as admin } from 'firebase-admin';
-import 'ws';
-import 'http';
-import 'zod';
-import '@almadar/core';
-import '@almadar/agent';
-import 'express-serve-static-core';
-
-/**
- * Debug Events Router
- *
- * Provides diagnostic endpoints for inspecting the server EventBus.
- * Only active when NODE_ENV=development.
- *
- * Endpoints:
- *   GET    /event-log   - Recent emitted events with listener counts
- *   DELETE /event-log   - Clear the event log
- *   GET    /listeners   - Registered listener counts per event
- *
- * @packageDocumentation
- */
-
-/**
- * Creates an Express router with debug endpoints for the server EventBus.
- * Returns a no-op router in production (no routes registered).
- */
-declare function debugEventsRouter(): Router;
-
-export { debugEventsRouter };

package/dist/lib/index.d.ts

@@ -1,4 +0,0 @@
-export { c as closeWebSocketServer, e as emitEntityEvent, b as env, g as getAuth, f as getConnectedClientCount, h as getFirestore, i as getWebSocketServer, l as logger, s as serverEventBus, k as setupEventBroadcast } from '../index-B64ll_cY.js';
-export { default as admin } from 'firebase-admin';
-import 'ws';
-import 'http';

package/dist/middleware/index.d.ts

@@ -1,71 +0,0 @@
-import { Request, Response, NextFunction } from 'express';
-import { AnyZodObject } from 'zod';
-
-/**
- * Base application error class
- */
-declare class AppError extends Error {
-    statusCode: number;
-    message: string;
-    code?: string | undefined;
-    constructor(statusCode: number, message: string, code?: string | undefined);
-}
-/**
- * 404 Not Found error
- */
-declare class NotFoundError extends AppError {
-    constructor(message?: string);
-}
-/**
- * 400 Bad Request / Validation error
- */
-declare class ValidationError extends AppError {
-    constructor(message?: string);
-}
-/**
- * 401 Unauthorized error
- */
-declare class UnauthorizedError extends AppError {
-    constructor(message?: string);
-}
-/**
- * 403 Forbidden error
- */
-declare class ForbiddenError extends AppError {
-    constructor(message?: string);
-}
-/**
- * 409 Conflict error
- */
-declare class ConflictError extends AppError {
-    constructor(message?: string);
-}
-/**
- * Global error handler middleware
- */
-declare const errorHandler: (err: Error, _req: Request, res: Response, _next: NextFunction) => void;
-/**
- * Async handler wrapper to catch errors in async route handlers
- */
-declare const asyncHandler: (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>) => (req: Request, res: Response, next: NextFunction) => void;
-/**
- * 404 handler for unmatched routes
- */
-declare const notFoundHandler: (req: Request, res: Response) => void;
-
-/**
- * Middleware to validate request body against a Zod schema
- */
-declare const validateBody: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
-/**
- * Middleware to validate request query parameters against a Zod schema
- */
-declare const validateQuery: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
-/**
- * Middleware to validate request params against a Zod schema
- */
-declare const validateParams: (schema: AnyZodObject) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
-
-declare function authenticateFirebase(req: Request, res: Response, next: NextFunction): Promise<void | Response<any, Record<string, any>>>;
-
-export { AppError, ConflictError, ForbiddenError, NotFoundError, UnauthorizedError, ValidationError, asyncHandler, authenticateFirebase, errorHandler, notFoundHandler, validateBody, validateParams, validateQuery };

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

@@ -1,37 +0,0 @@
-import { Request, Response, NextFunction } from 'express';
-
-/**
- * Multi-User Middleware
- *
- * Provides user isolation and session ownership using Firebase Auth.
- *
- * @packageDocumentation
- */
-
-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
- */
-declare function multiUserMiddleware(req: Request, res: Response, next: NextFunction): Promise<void>;
-/**
- * Verify Firebase Auth token from Authorization header
- */
-declare function verifyFirebaseAuth(req: Request, res: Response, next: NextFunction): Promise<void>;
-
-export { multiUserMiddleware, verifyFirebaseAuth };

package/dist/routes/observability.d.ts

@@ -1,12 +0,0 @@
-import * as express_serve_static_core from 'express-serve-static-core';
-
-/**
- * Observability Routes
- *
- * Provides endpoints for metrics, health checks, and telemetry.
- *
- * @packageDocumentation
- */
-declare const router: express_serve_static_core.Router;
-
-export { router as default };

package/dist/services/index.d.ts

@@ -1,2 +0,0 @@
-export { D as DataService, E as EntitySchema, a as EntitySeedConfig, F as FieldSchema, d as dataService, m as mockDataService, s as seedMockData } from '../index-D8fohXsO.js';
-import '../utils/index.js';