@almadar/server 1.4.4 → 2.0.0

package/LICENSE

@@ -1,72 +1,21 @@
-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
+MIT License
+
+Copyright (c) 2026 Almadar Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @almadar/server
+
+> Shared server infrastructure for Almadar applications
+
+Part of the [Almadar](https://github.com/almadar-io/almadar) platform.
+
+## Installation
+
+```bash
+npm install @almadar/server
+```
+
+## Usage
+
+```typescript
+import { /* ... */ } from '@almadar/server';
+```
+
+## API
+
+<!-- Document public exports here -->
+
+## License
+
+MIT

package/dist/index.js

@@ -176,6 +176,272 @@ function emitEntityEvent(entityType, action, payload) {
   const eventType = `${entityType.toUpperCase()}_${action}`;
   serverEventBus.emit(eventType, payload, { orbital: entityType });
 }
+
+// src/lib/eventBusTransport.ts
+var InMemoryTransport = class {
+  async publish() {
+  }
+  async subscribe() {
+  }
+  async close() {
+  }
+};
+var RedisTransport = class {
+  channel;
+  publishFn;
+  subscribeFn;
+  closeFn;
+  constructor(options) {
+    this.channel = options.channel ?? "almadar:events";
+    this.publishFn = options.publishFn;
+    this.subscribeFn = options.subscribeFn;
+    this.closeFn = options.closeFn;
+  }
+  async publish(message) {
+    const serialized = JSON.stringify(message);
+    await this.publishFn(this.channel, serialized);
+  }
+  async subscribe(receiver) {
+    await this.subscribeFn(this.channel, (raw) => {
+      try {
+        const message = JSON.parse(raw);
+        receiver(message);
+      } catch {
+        console.error("[RedisTransport] Failed to parse message:", raw);
+      }
+    });
+  }
+  async close() {
+    if (this.closeFn) {
+      await this.closeFn();
+    }
+  }
+};
+var instanceCounter = 0;
+var DistributedEventBus = class {
+  localBus;
+  transport;
+  instanceId;
+  isRelaying = false;
+  constructor(options) {
+    this.localBus = new EventBus({ debug: options?.debug });
+    this.transport = options?.transport ?? new InMemoryTransport();
+    this.instanceId = `instance_${++instanceCounter}_${Date.now()}`;
+  }
+  /**
+   * Initialize the transport subscription. Call once at startup.
+   */
+  async connect() {
+    await this.transport.subscribe((message) => {
+      if (message.sourceId === this.instanceId) {
+        return;
+      }
+      this.isRelaying = true;
+      try {
+        this.localBus.emit(message.event, message.payload, message.meta);
+      } finally {
+        this.isRelaying = false;
+      }
+    });
+  }
+  /**
+   * Emit an event locally and publish to transport for other processes.
+   */
+  emit(event, payload, meta) {
+    this.localBus.emit(event, payload, meta);
+    if (!this.isRelaying) {
+      const message = {
+        event,
+        payload,
+        meta,
+        sourceId: this.instanceId,
+        timestamp: Date.now()
+      };
+      this.transport.publish(message).catch((err) => {
+        console.error("[DistributedEventBus] Transport publish error:", err);
+      });
+    }
+  }
+  /** Subscribe to an event */
+  on(event, handler) {
+    return this.localBus.on(event, handler);
+  }
+  /** Unsubscribe from an event */
+  off(event, handler) {
+    this.localBus.off(event, handler);
+  }
+  /** Get recent events (dev diagnostics) */
+  getRecentEvents(limit) {
+    return this.localBus.getRecentEvents(limit);
+  }
+  /** Clear event log */
+  clearEventLog() {
+    this.localBus.clearEventLog();
+  }
+  /** Get listener counts */
+  getListenerCounts() {
+    return this.localBus.getListenerCounts();
+  }
+  /** Clear all listeners and log */
+  clear() {
+    this.localBus.clear();
+  }
+  /** Disconnect transport */
+  async disconnect() {
+    await this.transport.close();
+  }
+  /** Get the instance ID (for debugging) */
+  getInstanceId() {
+    return this.instanceId;
+  }
+};
+
+// src/lib/eventPersistence.ts
+var InMemoryEventStore = class {
+  events = [];
+  index = /* @__PURE__ */ new Map();
+  async store(event) {
+    this.events.push(event);
+    this.index.set(event.id, event);
+  }
+  async query(filters) {
+    let results = this.events;
+    if (filters.eventName) {
+      results = results.filter((e) => e.eventName === filters.eventName);
+    }
+    if (filters.source) {
+      results = results.filter((e) => e.source === filters.source);
+    }
+    if (filters.traceId) {
+      results = results.filter((e) => e.traceId === filters.traceId);
+    }
+    if (filters.after !== void 0) {
+      results = results.filter((e) => e.timestamp > filters.after);
+    }
+    if (filters.before !== void 0) {
+      results = results.filter((e) => e.timestamp < filters.before);
+    }
+    if (filters.order === "desc") {
+      results = [...results].reverse();
+    }
+    if (filters.limit !== void 0 && filters.limit > 0) {
+      results = results.slice(0, filters.limit);
+    }
+    return results;
+  }
+  async get(id) {
+    return this.index.get(id) ?? null;
+  }
+  async deleteOlderThan(timestamp) {
+    const before = this.events.length;
+    this.events = this.events.filter((e) => e.timestamp >= timestamp);
+    this.index.clear();
+    for (const event of this.events) {
+      this.index.set(event.id, event);
+    }
+    return before - this.events.length;
+  }
+  async count() {
+    return this.events.length;
+  }
+  async clear() {
+    this.events = [];
+    this.index.clear();
+  }
+};
+var idCounter = 0;
+var EventPersistence = class {
+  store;
+  options;
+  cleanupTimer = null;
+  constructor(options, store) {
+    this.options = {
+      enabled: options?.enabled ?? true,
+      retentionMs: options?.retentionMs ?? 24 * 60 * 60 * 1e3,
+      // 24 hours
+      maxEvents: options?.maxEvents ?? 1e4,
+      cleanupIntervalMs: options?.cleanupIntervalMs ?? 5 * 60 * 1e3,
+      // 5 minutes
+      defaultSource: options?.defaultSource ?? "unknown"
+    };
+    this.store = store ?? new InMemoryEventStore();
+  }
+  /**
+   * Persist an event.
+   */
+  async persist(eventName, payload, meta) {
+    const event = {
+      id: `evt_${++idCounter}_${Date.now()}`,
+      eventName,
+      payload,
+      source: meta?.source ?? this.options.defaultSource,
+      timestamp: Date.now(),
+      traceId: meta?.traceId ?? `trace_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      meta: meta ? { ...meta } : void 0
+    };
+    if (this.options.enabled) {
+      await this.store.store(event);
+    }
+    return event;
+  }
+  /**
+   * Replay events matching the query filters.
+   */
+  async replay(query) {
+    return this.store.query(query);
+  }
+  /**
+   * Get a single event by ID.
+   */
+  async getEvent(id) {
+    return this.store.get(id);
+  }
+  /**
+   * Get event count.
+   */
+  async getEventCount() {
+    return this.store.count();
+  }
+  /**
+   * Run cleanup — delete events older than retention period.
+   */
+  async cleanup() {
+    const cutoff = Date.now() - this.options.retentionMs;
+    return this.store.deleteOlderThan(cutoff);
+  }
+  /**
+   * Start periodic cleanup timer.
+   */
+  startCleanup() {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => {
+      this.cleanup().catch((err) => {
+        console.error("[EventPersistence] Cleanup error:", err);
+      });
+    }, this.options.cleanupIntervalMs);
+  }
+  /**
+   * Stop periodic cleanup timer.
+   */
+  stopCleanup() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  /**
+   * Clear all persisted events.
+   */
+  async clear() {
+    await this.store.clear();
+  }
+  /**
+   * Get the underlying store (for testing or custom queries).
+   */
+  getStore() {
+    return this.store;
+  }
+};
 function debugEventsRouter() {
   const router2 = Router();
   if (process.env.NODE_ENV !== "development") {
@@ -1776,6 +2042,174 @@ function setupStateSyncWebSocket(io) {
     });
   });
 }
+
+// src/lib/serviceDiscovery.ts
+var InMemoryServiceRegistry = class {
+  services = /* @__PURE__ */ new Map();
+  async register(service) {
+    this.services.set(service.instanceId, {
+      ...service,
+      registeredAt: Date.now(),
+      lastHeartbeat: Date.now()
+    });
+  }
+  async deregister(instanceId) {
+    this.services.delete(instanceId);
+  }
+  async heartbeat(instanceId) {
+    const service = this.services.get(instanceId);
+    if (service) {
+      service.lastHeartbeat = Date.now();
+    }
+  }
+  async updateStatus(instanceId, status) {
+    const service = this.services.get(instanceId);
+    if (service) {
+      service.status = status;
+    }
+  }
+  async getAll() {
+    return Array.from(this.services.values());
+  }
+  async getByName(name) {
+    return Array.from(this.services.values()).filter((s) => s.name === name);
+  }
+  async findListeners(event) {
+    return Array.from(this.services.values()).filter(
+      (s) => s.listens.includes(event) && s.status !== "stopping"
+    );
+  }
+  async findEmitters(event) {
+    return Array.from(this.services.values()).filter(
+      (s) => s.emits.includes(event) && s.status !== "stopping"
+    );
+  }
+  async cleanup(ttlMs) {
+    const cutoff = Date.now() - ttlMs;
+    let removed = 0;
+    for (const [id, service] of this.services) {
+      if (service.lastHeartbeat < cutoff) {
+        this.services.delete(id);
+        removed++;
+      }
+    }
+    return removed;
+  }
+};
+var ServiceDiscovery = class {
+  registry;
+  options;
+  cleanupTimer = null;
+  constructor(options, registry) {
+    this.options = {
+      heartbeatTtlMs: options?.heartbeatTtlMs ?? 6e4,
+      cleanupIntervalMs: options?.cleanupIntervalMs ?? 3e4
+    };
+    this.registry = registry ?? new InMemoryServiceRegistry();
+  }
+  /**
+   * Register a service with the registry.
+   */
+  async register(service) {
+    await this.registry.register({
+      ...service,
+      status: service.status ?? "starting",
+      registeredAt: Date.now(),
+      lastHeartbeat: Date.now()
+    });
+  }
+  /**
+   * Deregister a service.
+   */
+  async deregister(instanceId) {
+    await this.registry.deregister(instanceId);
+  }
+  /**
+   * Send heartbeat for a service.
+   */
+  async heartbeat(instanceId) {
+    await this.registry.heartbeat(instanceId);
+  }
+  /**
+   * Mark a service as ready.
+   */
+  async markReady(instanceId) {
+    await this.registry.updateStatus(instanceId, "ready");
+  }
+  /**
+   * Mark a service as degraded.
+   */
+  async markDegraded(instanceId) {
+    await this.registry.updateStatus(instanceId, "degraded");
+  }
+  /**
+   * Find all services that listen for a given event.
+   */
+  async findListeners(event) {
+    return this.registry.findListeners(event);
+  }
+  /**
+   * Find all services that emit a given event.
+   */
+  async findEmitters(event) {
+    return this.registry.findEmitters(event);
+  }
+  /**
+   * Get all registered services.
+   */
+  async getAll() {
+    return this.registry.getAll();
+  }
+  /**
+   * Get the full event topology (who emits what, who listens for what).
+   */
+  async getEventTopology() {
+    const services = await this.registry.getAll();
+    const eventMap = /* @__PURE__ */ new Map();
+    for (const service of services) {
+      for (const event of service.emits) {
+        if (!eventMap.has(event)) eventMap.set(event, { emitters: /* @__PURE__ */ new Set(), listeners: /* @__PURE__ */ new Set() });
+        eventMap.get(event).emitters.add(service.name);
+      }
+      for (const event of service.listens) {
+        if (!eventMap.has(event)) eventMap.set(event, { emitters: /* @__PURE__ */ new Set(), listeners: /* @__PURE__ */ new Set() });
+        eventMap.get(event).listeners.add(service.name);
+      }
+    }
+    const events = Array.from(eventMap.entries()).map(([event, { emitters, listeners }]) => ({
+      event,
+      emitters: Array.from(emitters),
+      listeners: Array.from(listeners)
+    }));
+    return { events };
+  }
+  /**
+   * Start periodic cleanup of expired services.
+   */
+  startCleanup() {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => {
+      this.registry.cleanup(this.options.heartbeatTtlMs).catch((err) => {
+        console.error("[ServiceDiscovery] Cleanup error:", err);
+      });
+    }, this.options.cleanupIntervalMs);
+  }
+  /**
+   * Stop periodic cleanup.
+   */
+  stopCleanup() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  /**
+   * Get the underlying registry (for testing).
+   */
+  getRegistry() {
+    return this.registry;
+  }
+};
 var router = Router();
 router.get("/metrics", async (req, res) => {
   try {
@@ -1831,6 +2265,6 @@ router.get("/active-sessions", async (req, res) => {
 });
 var observability_default = router;
 
-export { AppError, ChangeSetStore, ConflictError, EventBus, ForbiddenError, MockDataService, NotFoundError, SchemaProtectionService, SchemaStore, SnapshotStore, UnauthorizedError, ValidationError, ValidationStore, applyFiltersToQuery, asyncHandler, authenticateFirebase, closeWebSocketServer, createServerSkillAgent, dataService, db, debugEventsRouter, emitEntityEvent, env, errorHandler, extractPaginationParams, fromFirestoreFormat, getMemoryManager as getAgentMemoryManager, getSessionManager as getAgentSessionManager, getAuth, getConnectedClientCount, getFirestore, getMemoryManager, getSessionManager, getWebSocketServer, initializeFirebase, logger, mockDataService, multiUserMiddleware, notFoundHandler, observability_default as observabilityRouter, parseQueryFilters, resetMemoryManager, resetSessionManager, seedMockData, serverEventBus, setupEventBroadcast, setupStateSyncWebSocket, toFirestoreFormat, validateBody, validateParams, validateQuery, verifyFirebaseAuth };
+export { AppError, ChangeSetStore, ConflictError, DistributedEventBus, EventBus, EventPersistence, ForbiddenError, InMemoryEventStore, InMemoryServiceRegistry, InMemoryTransport, MockDataService, NotFoundError, RedisTransport, SchemaProtectionService, SchemaStore, ServiceDiscovery, SnapshotStore, UnauthorizedError, ValidationError, ValidationStore, applyFiltersToQuery, asyncHandler, authenticateFirebase, closeWebSocketServer, createServerSkillAgent, dataService, db, debugEventsRouter, emitEntityEvent, env, errorHandler, extractPaginationParams, fromFirestoreFormat, getMemoryManager as getAgentMemoryManager, getSessionManager as getAgentSessionManager, getAuth, getConnectedClientCount, getFirestore, getMemoryManager, getSessionManager, getWebSocketServer, initializeFirebase, logger, mockDataService, multiUserMiddleware, notFoundHandler, observability_default as observabilityRouter, parseQueryFilters, resetMemoryManager, resetSessionManager, seedMockData, serverEventBus, setupEventBroadcast, setupStateSyncWebSocket, toFirestoreFormat, validateBody, validateParams, validateQuery, verifyFirebaseAuth };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map