@almadar/server 1.0.0

package/LICENSE

@@ -0,0 +1,72 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Almadar FZE
+Licensed Work:        KFlow Builder / Almadar
+                      The Licensed Work is (c) 2025-2026 Almadar FZE.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      non-commercial purposes and for internal evaluation.
+                      Production use for commercial purposes requires a
+                      commercial license from the Licensor.
+Change Date:          2030-02-01
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+---
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+ADDITIONAL TERMS:
+
+Documentation (builder/packages/website/docs/) is licensed under CC BY 4.0.
+
+TRADEMARKS:
+
+"Orbital", "KFlow", "Almadar", and the Almadar logo are trademarks of
+Almadar FZE. You may not use these trademarks without prior written
+permission from Almadar FZE.
+
+For licensing inquiries: licensing@almadar.io

package/dist/index--XhXIuTh.d.ts

@@ -0,0 +1,120 @@
+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;
+/**
+ * Simple EventBus implementation for server-side events
+ */
+declare class EventBus {
+    private handlers;
+    private debug;
+    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;
+    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 Configuration
+ *
+ * Supports both Prisma (SQL) and Firebase Admin (Firestore)
+ * Generated apps can use either depending on the database option
+ */
+
+/**
+ * Get Firestore instance
+ */
+declare function getFirestore(): admin.firestore.Firestore;
+/**
+ * Get Firebase Auth instance
+ */
+declare function getAuth(): admin.auth.Auth;
+
+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, env as a, getConnectedClientCount as b, closeWebSocketServer as c, db as d, emitEntityEvent as e, getFirestore as f, getAuth as g, getWebSocketServer as h, setupEventBroadcast as i, logger as l, serverEventBus as s };

package/dist/index-D8fohXsO.d.ts

@@ -0,0 +1,178 @@
+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

@@ -0,0 +1,9 @@
+export { E as EventBus, c as closeWebSocketServer, d as db, e as emitEntityEvent, a as env, g as getAuth, b as getConnectedClientCount, f as getFirestore, h as getWebSocketServer, l as logger, s as serverEventBus, i as setupEventBroadcast } from './index--XhXIuTh.js';
+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 { FirestoreWhereFilterOp, PaginationParams, ParsedFilter, applyFiltersToQuery, extractPaginationParams, parseQueryFilters } from './utils/index.js';
+export { default as admin } from 'firebase-admin';
+import 'ws';
+import 'http';
+import 'express';
+import 'zod';