@agentick/core 0.0.1

package/dist/channels/service.js

@@ -0,0 +1,870 @@
+import { ChannelSession, Context, } from "@agentick/kernel";
+import { NotFoundError, ValidationError } from "@agentick/shared";
+// Re-export channel types from Kernel so Engine users don't need to import from Kernel
+export { Channel, ChannelSession, } from "@agentick/kernel";
+/**
+ * Channel Service - Low-level channel infrastructure.
+ *
+ * ## Architecture
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │  Application Layer (recommended)                                    │
+ * │  └── ChannelRouter - declarative handlers, context registry,       │
+ * │                      auto-notifications, scoped publishing          │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │  Service Layer (escape hatch)                                       │
+ * │  └── ChannelService - sessions, direct publish/subscribe,          │
+ * │                       transport & adapter management                │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │  Infrastructure Layer                                               │
+ * │  ├── Transport - external communication (SSE, WebSocket)           │
+ * │  └── Adapter - multi-instance distribution (Redis pub/sub)         │
+ * └─────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Usage
+ *
+ * **Recommended:** Use `ChannelRouter` for application code.
+ * - Register routers with engine: `createEngine({ channels: { routers: [...] } })`
+ * - Handle events via `channelService.handleEvent()`
+ * - Components register via `router.registerContext()`
+ *
+ * **Escape hatch:** Direct `ChannelService` methods for advanced cases.
+ * - `subscribe()` - low-level channel subscription
+ * - `publish()` - low-level event publishing
+ *
+ * Sessions persist across multiple engine executions.
+ */
+export class ChannelService {
+    sessions = new Map();
+    sessionIdGenerator;
+    transport;
+    adapter;
+    sessionTimeout;
+    cleanupInterval;
+    adapterSubscriptions = new Map();
+    routerRegistry = new Map();
+    constructor(config = {}) {
+        this.sessionIdGenerator = config.sessionIdGenerator || ChannelSession.generateId;
+        this.transport = config.transport;
+        this.adapter = config.adapter;
+        this.sessionTimeout = config.sessionTimeout || 3600000; // 1 hour default
+        // Register channel routers
+        if (config.routers) {
+            for (const router of config.routers) {
+                if (!router.channel) {
+                    throw ValidationError.required("channel");
+                }
+                this.routerRegistry.set(router.channel, router);
+                router.setChannelService(this);
+            }
+        }
+        // Setup transport if provided
+        if (this.transport) {
+            this.setupTransport();
+        }
+        // Setup adapter if provided
+        if (this.adapter) {
+            this.setupAdapter();
+        }
+        // Start session cleanup interval
+        this.startCleanupInterval();
+    }
+    /**
+     * Get the transport adapter (for external access, e.g., HTTP routes).
+     */
+    getTransport() {
+        return this.transport;
+    }
+    /**
+     * Get a registered channel router by name.
+     */
+    getRouter(channelName) {
+        return this.routerRegistry.get(channelName);
+    }
+    /**
+     * Handle an event by delegating to the appropriate registered router.
+     * Eliminates if-else chains in HTTP routes.
+     *
+     * @param channelName - Name of the channel
+     * @param request - Event type and payload
+     * @param context - Context passed to the handler
+     * @returns Result from the handler (for HTTP response body)
+     *
+     * @example
+     * ```typescript
+     * // In HTTP route - no if-else needed
+     * const result = await engine.channels?.handleEvent('todo-list',
+     *   { type: 'create_task', payload },
+     *   { userId, broadcast: true }
+     * );
+     * res.json({ success: true, ...result });
+     * ```
+     */
+    async handleEvent(channelName, request, rawContext) {
+        const router = this.getRouter(channelName);
+        if (!router) {
+            throw new NotFoundError("channel", channelName, `Unknown channel. Available channels: ${Array.from(this.routerRegistry.keys()).join(", ")}`);
+        }
+        // Let router transform context if it has buildContext
+        const context = router.buildContext ? router.buildContext(rawContext) : rawContext;
+        const event = {
+            channel: channelName,
+            type: request.type,
+            payload: request.payload,
+            metadata: {},
+        };
+        // console.log('handleEvent', channelName, request, context, router);
+        return router.handle(event, context);
+    }
+    /**
+     * Get or create a session for the current context.
+     */
+    getSession(ctx) {
+        const sessionId = this.sessionIdGenerator(ctx);
+        if (!this.sessions.has(sessionId)) {
+            const session = new ChannelSession(sessionId);
+            this.sessions.set(sessionId, session);
+            // Connect transport if available
+            if (this.transport) {
+                this.transport.connect(sessionId).catch((err) => {
+                    console.error(`Failed to connect transport for session ${sessionId}:`, err);
+                });
+            }
+        }
+        const session = this.sessions.get(sessionId);
+        session.lastActivity = Date.now();
+        return session;
+    }
+    /**
+     * Get or create a channel within the current session.
+     */
+    getChannel(ctx, channelName) {
+        const session = this.getSession(ctx);
+        const channel = session.getChannel(channelName);
+        // Subscribe to adapter if this is a new channel
+        // Use synchronous placeholder to prevent duplicate subscriptions from concurrent calls
+        if (this.adapter && !this.adapterSubscriptions.has(channelName)) {
+            // Set placeholder immediately to prevent race condition
+            // The placeholder is a no-op function that will be replaced with the real unsubscribe
+            this.adapterSubscriptions.set(channelName, () => { });
+            this.adapter
+                .subscribe(channelName, (event) => {
+                // Only forward if event didn't originate from this instance
+                // (prevent feedback loop)
+                if (event.metadata?.source !== "local") {
+                    channel.publish(event);
+                }
+            })
+                .then((unsubscribe) => {
+                // Replace placeholder with actual unsubscribe function
+                this.adapterSubscriptions.set(channelName, unsubscribe);
+            })
+                .catch((err) => {
+                // Remove placeholder on failure so retry is possible
+                this.adapterSubscriptions.delete(channelName);
+                console.error(`Failed to subscribe adapter to channel ${channelName}:`, err);
+            });
+        }
+        return channel;
+    }
+    /**
+     * Low-level: Publish an event to a channel.
+     *
+     * **Prefer using ChannelRouter.publisher() for application code.**
+     * This is an escape hatch for advanced use cases.
+     */
+    publish(ctx, channelName, event) {
+        const session = this.getSession(ctx);
+        const channel = session.getChannel(channelName);
+        const fullEvent = {
+            ...event,
+            channel: channelName,
+            metadata: {
+                ...event.metadata,
+                executionId: ctx.traceId,
+                sessionId: session.id, // Always include sessionId in metadata
+                sourceConnectionId: session.id, // For excludeSender (broadcast) support
+            },
+        };
+        // Publish to local channel
+        channel.publish(fullEvent);
+        // Forward to transport if available
+        if (this.transport) {
+            this.transport.send(fullEvent).catch((err) => {
+                console.error(`Failed to send event via transport:`, err);
+            });
+        }
+        // Forward to adapter if available
+        if (this.adapter) {
+            this.adapter.publish(fullEvent).catch((err) => {
+                console.error(`Failed to publish event via adapter:`, err);
+            });
+        }
+    }
+    /**
+     * Low-level: Subscribe to events on a channel with a handler function.
+     *
+     * **Prefer using ChannelRouter for application code.**
+     * This is an escape hatch for advanced use cases.
+     */
+    subscribe(ctx, channelName, handler) {
+        const channel = this.getChannel(ctx, channelName);
+        return channel.subscribe(handler);
+    }
+    /**
+     * Low-level: Subscribe to multiple channels at once.
+     *
+     * **Prefer using ChannelRouter for application code.**
+     * This is an escape hatch for advanced use cases.
+     *
+     * @param ctx - Engine context
+     * @param channelNames - Array of channel names to subscribe to, or '*' for all channels
+     * @param handler - Handler function that receives events from any subscribed channel
+     * @returns Unsubscribe function
+     */
+    subscribeToChannels(ctx, channelNames, handler) {
+        const session = this.getSession(ctx);
+        const unsubscribers = [];
+        if (channelNames === "*") {
+            // Subscribe to all existing channels
+            for (const channel of session.channels.values()) {
+                unsubscribers.push(channel.subscribe(handler));
+            }
+            // For future channels, we'll subscribe when they're accessed via getChannel
+            // This is handled by subscribing to the session's channel creation
+            // Note: This is a best-effort approach - channels created outside getChannel won't be subscribed
+        }
+        else {
+            // Subscribe to specific channels
+            for (const channelName of channelNames) {
+                const channel = session.getChannel(channelName);
+                unsubscribers.push(channel.subscribe(handler));
+            }
+        }
+        // Return combined unsubscribe function
+        return () => {
+            for (const unsubscribe of unsubscribers) {
+                unsubscribe();
+            }
+        };
+    }
+    /**
+     * Low-level: Subscribe to events filtered by session ID.
+     *
+     * **Prefer using ChannelRouter for application code.**
+     * This is an escape hatch for advanced use cases.
+     *
+     * @param ctx - Engine context
+     * @param channelName - Channel name to subscribe to, or '*' for all channels
+     * @param handler - Handler function that receives filtered events
+     * @param options - Optional filter options
+     * @returns Unsubscribe function
+     */
+    subscribeFiltered(ctx, channelName, handler, options) {
+        const session = this.getSession(ctx);
+        const targetSessionId = options?.sessionId || session.id;
+        // Create filtered handler
+        const filteredHandler = (event) => {
+            // Filter by sessionId
+            const eventSessionId = event.metadata?.["sessionId"];
+            if (eventSessionId !== targetSessionId) {
+                return; // Skip events not for this session
+            }
+            // Apply additional channel filter if provided
+            if (options?.channelFilter && !options.channelFilter(event.channel)) {
+                return;
+            }
+            // Call original handler
+            handler(event);
+        };
+        // Subscribe using filtered handler
+        if (channelName === "*") {
+            return this.subscribeToChannels(ctx, "*", filteredHandler);
+        }
+        else {
+            return this.subscribe(ctx, channelName, filteredHandler);
+        }
+    }
+    /**
+     * Wait for a response on a channel (for bidirectional communication).
+     */
+    async waitForResponse(ctx, channelName, requestId, timeoutMs) {
+        const channel = this.getChannel(ctx, channelName);
+        return channel.waitForResponse(requestId, timeoutMs);
+    }
+    /**
+     * Setup transport handlers.
+     * Forwards events received from transport to local channels.
+     */
+    setupTransport() {
+        if (!this.transport)
+            return;
+        // Forward received events to appropriate channels
+        this.transport.onReceive((event) => {
+            // Extract session ID from event metadata
+            const sessionId = event.metadata?.["sessionId"];
+            if (!sessionId) {
+                console.warn("Received transport event without sessionId in metadata");
+                return;
+            }
+            // Find session and channel
+            const session = this.sessions.get(sessionId);
+            if (!session) {
+                console.warn(`Received transport event for unknown session: ${sessionId}`);
+                return;
+            }
+            // Publish to local channel
+            const channel = session.getChannel(event.channel);
+            channel.publish(event);
+        });
+    }
+    /**
+     * Setup adapter handlers.
+     * Subscribes to channels via adapter and forwards events to local channels.
+     */
+    async setupAdapter() {
+        if (!this.adapter)
+            return;
+        // We'll subscribe to channels on-demand when they're created
+        // This is handled in getChannel() - we check if adapter exists and subscribe
+    }
+    /**
+     * Start cleanup interval for expired sessions.
+     */
+    startCleanupInterval() {
+        if (this.cleanupInterval) {
+            return;
+        }
+        this.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            for (const [sessionId, session] of this.sessions.entries()) {
+                if (now - session.lastActivity > this.sessionTimeout) {
+                    this.destroySession(sessionId);
+                }
+            }
+        }, 60000); // Check every minute
+    }
+    /**
+     * Destroy a session and cleanup resources.
+     */
+    destroySession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            session.destroy();
+            this.sessions.delete(sessionId);
+            // Disconnect transport if available
+            if (this.transport) {
+                this.transport.disconnect().catch((err) => {
+                    console.error(`Failed to disconnect transport for session ${sessionId}:`, err);
+                });
+            }
+        }
+    }
+    /**
+     * Cleanup all sessions and resources.
+     */
+    destroy() {
+        // Clear cleanup interval
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+        // Destroy all sessions
+        for (const sessionId of this.sessions.keys()) {
+            this.destroySession(sessionId);
+        }
+        // Close transport (sends proper close events to clients)
+        if (this.transport) {
+            this.transport.closeAll();
+        }
+        // Close adapter if available
+        if (this.adapter?.close) {
+            this.adapter.close().catch((err) => {
+                console.error("Failed to close adapter during cleanup:", err);
+            });
+        }
+        // Unsubscribe from all adapter subscriptions
+        for (const unsubscribe of this.adapterSubscriptions.values()) {
+            unsubscribe();
+        }
+        this.adapterSubscriptions.clear();
+    }
+}
+export class ChannelRouter {
+    channel;
+    config;
+    handlers = new Map();
+    defaultHandler;
+    errorHandler;
+    /**
+     * Registry of execution contexts.
+     * Key format: `${executionId}:${scopeKey}`
+     * Allows multiple executions to register for same scope, each with own callbacks.
+     */
+    contextRegistry = new Map();
+    constructor(channel, config = {}) {
+        this.channel = channel;
+        this.config = config;
+    }
+    // =========================================================================
+    // Getters for lazy-initialized dependencies
+    // =========================================================================
+    getTransport() {
+        if (this.config.transport) {
+            return typeof this.config.transport === "function"
+                ? this.config.transport()
+                : this.config.transport;
+        }
+        const service = this.getChannelService();
+        const transport = service?.getTransport?.();
+        if (transport) {
+            this.setTransport(transport);
+            return transport;
+        }
+        throw ValidationError.required(`ChannelRouter[${this.channel}].transport`);
+    }
+    getChannelService() {
+        const service = this.config.channelService;
+        if (!service) {
+            throw ValidationError.required(`ChannelRouter[${this.channel}].channelService`);
+        }
+        return typeof service === "function" ? service() : service;
+    }
+    setChannelService(service) {
+        this.config.channelService = service;
+        // If router doesn't have transport configured, get it from the service
+        if (!this.config.transport) {
+            const transport = service?.getTransport?.();
+            if (transport) {
+                this.setTransport(transport);
+            }
+        }
+    }
+    setTransport(transport) {
+        this.config.transport = transport;
+    }
+    setScope(scope) {
+        this.config.scope = scope;
+    }
+    setContextBuilder(contextBuilder) {
+        this.config.contextBuilder = contextBuilder;
+    }
+    // =========================================================================
+    // Handler Registration (Fluent API)
+    // =========================================================================
+    /**
+     * Register a handler for a specific event type.
+     * Handler receives (event, context) where context is built from the request
+     * via contextBuilder or passed directly to handle().
+     */
+    on(eventType, handler) {
+        this.handlers.set(eventType, handler);
+        return this;
+    }
+    /**
+     * Register a default handler for unmatched event types.
+     */
+    default(handler) {
+        this.defaultHandler = handler;
+        return this;
+    }
+    /**
+     * Register an error handler.
+     */
+    onError(handler) {
+        this.errorHandler = handler;
+        return this;
+    }
+    /**
+     * Handle an incoming event.
+     * Called by ChannelService.handleEvent() or directly.
+     * Auto-notifies registered execution contexts after handler returns.
+     *
+     * @param event - The channel event to handle
+     * @param context - Context for the handler (required)
+     * @returns Result from the handler, or undefined if no handler matched
+     */
+    async handle(event, context) {
+        const handler = this.handlers.get(event.type) || this.defaultHandler;
+        if (!handler) {
+            return undefined;
+        }
+        try {
+            const result = await handler(event, context);
+            // Auto-notify all registered execution contexts for this scope
+            this.notifyRegisteredContexts(context, event, result);
+            return result;
+        }
+        catch (error) {
+            if (this.errorHandler) {
+                this.errorHandler(error, event);
+            }
+            else {
+                console.error(`ChannelRouter[${this.channel}] error handling ${event.type}:`, error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Build the context for the handler.
+     */
+    buildContext(data) {
+        return this.config.contextBuilder?.(data) ?? data;
+    }
+    // =========================================================================
+    // Context Registry - Per-execution context registration
+    // =========================================================================
+    /**
+     * Check if value is a ScopeMapping (object with string values, not an array or function)
+     */
+    isScopeMapping(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof value !== "function");
+    }
+    /**
+     * Extract scope keys from channel context based on scope config.
+     * Returns array of fully qualified keys like 'prefix:value'.
+     *
+     * @example
+     * // scope: { user: 'userId' }, ctx: { userId: 'alice' }
+     * // → ['user:alice']
+     *
+     * // scope: [{ user: 'userId' }, { thread: 'threadId' }], ctx: { userId: 'alice', threadId: '123' }
+     * // → ['user:alice', 'thread:123']
+     *
+     * // scope: (ctx) => `user:${ctx.userId}`, ctx: { userId: 'alice' }
+     * // → ['user:alice']
+     */
+    getScopeKeys(channelContext) {
+        const scope = this.config.scope;
+        const ctx = channelContext;
+        if (!scope) {
+            return ["default"];
+        }
+        // Function: (ctx) => 'user:alice' or ['user:alice', 'thread:123']
+        if (typeof scope === "function") {
+            const scopeFn = scope;
+            const result = scopeFn(ctx);
+            return Array.isArray(result) ? result : [result];
+        }
+        // ScopeMapping: { user: 'userId' }
+        if (this.isScopeMapping(scope)) {
+            return this.extractKeysFromMapping(scope, ctx);
+        }
+        // ScopeMapping[]: [{ user: 'userId' }, { thread: 'threadId' }]
+        if (Array.isArray(scope)) {
+            const keys = [];
+            for (const item of scope) {
+                if (this.isScopeMapping(item)) {
+                    keys.push(...this.extractKeysFromMapping(item, ctx));
+                }
+            }
+            return keys.length > 0 ? keys : ["default"];
+        }
+        return ["default"];
+    }
+    /**
+     * Extract scope keys from a single ScopeMapping.
+     */
+    extractKeysFromMapping(mapping, ctx) {
+        const keys = [];
+        for (const [prefix, field] of Object.entries(mapping)) {
+            const value = ctx[field];
+            if (value) {
+                keys.push(`${prefix}:${value}`);
+            }
+        }
+        return keys;
+    }
+    /**
+     * Register an execution's context with this channel.
+     * When channel events are handled, the onEvent callback is automatically invoked
+     * with the event and handler result.
+     *
+     * @param ctx - Engine context (provides executionHandle for auto-cleanup)
+     * @param channelContext - The context to register (used for scope matching)
+     * @param onEvent - Callback invoked after handler returns (receives event + result)
+     * @returns ChannelPublisher for publishing events
+     *
+     * @example
+     * ```typescript
+     * // In component onMount
+     * const publisher = channel.registerContext(ctx, { userId }, (event, result) => {
+     *   if (result?.success) ctx.setState('tasks', result.tasks);
+     * });
+     * publisher.to(userId).broadcast({ type: 'state_changed', payload });
+     *
+     * // In component onUnmount
+     * channel.unregisterContext(ctx);
+     * ```
+     */
+    registerContext(ctx, channelContext, onEvent) {
+        const executionId = ctx.executionHandle?.pid;
+        if (!executionId) {
+            console.warn(`ChannelRouter[${this.channel}]: Cannot register context without execution handle`);
+            return this.createPublisher(); // Return publisher anyway for API consistency
+        }
+        // Get all scope keys for this context (may be multiple with scope mappings)
+        const scopeKeys = this.getScopeKeys(channelContext);
+        // Register for each scope key
+        for (const scopeKey of scopeKeys) {
+            const fullKey = `${executionId}:${scopeKey}`;
+            // Overwrite if already registered (same execution + scope)
+            this.contextRegistry.set(fullKey, {
+                executionId,
+                context: channelContext,
+                onEvent,
+            });
+        }
+        // Auto-cleanup on execution end (fail-safe)
+        const cleanupHandler = () => {
+            this.cleanupExecution(executionId);
+        };
+        // Hook into execution completion/cancellation
+        ctx.executionHandle?.once("completed", cleanupHandler);
+        ctx.executionHandle?.once("abort", cleanupHandler);
+        // Return publisher for this channel
+        return this.createPublisher();
+    }
+    /**
+     * Unregister all contexts for an execution.
+     * Alternative to storing the returned function from registerContext.
+     *
+     * @param ctx - Engine context to unregister
+     */
+    unregisterContext(ctx) {
+        const executionId = ctx.executionHandle?.pid;
+        if (!executionId)
+            return;
+        // Remove all entries for this execution
+        for (const [key] of this.contextRegistry) {
+            if (key.startsWith(`${executionId}:`)) {
+                this.contextRegistry.delete(key);
+            }
+        }
+    }
+    /**
+     * Clean up all contexts for a specific execution ID.
+     * Called as a fail-safe when execution ends.
+     *
+     * @param executionId - The execution ID to clean up
+     */
+    cleanupExecution(executionId) {
+        for (const [key] of this.contextRegistry) {
+            if (key.startsWith(`${executionId}:`)) {
+                this.contextRegistry.delete(key);
+            }
+        }
+    }
+    /**
+     * Extract the scope key from a registry key.
+     * Registry keys are formatted as `${executionId}:${scopeKey}`.
+     * We find the first colon and take everything after it as the scopeKey.
+     */
+    extractScopeKeyFromRegistryKey(registryKey) {
+        const colonIndex = registryKey.indexOf(":");
+        if (colonIndex === -1) {
+            return registryKey;
+        }
+        return registryKey.substring(colonIndex + 1);
+    }
+    /**
+     * Execute a callback for each registered context matching scope(s).
+     * Scope keys are derived from the provided context (or explicit scopeKey).
+     * Deduplicates by executionId - each execution's callback runs at most once.
+     *
+     * @param scopeKeyOrContext - Either explicit scope key or context to derive scope from
+     * @param fn - Callback to execute for each matching context
+     *
+     * @example
+     * ```typescript
+     * // Using context (scope derived automatically, supports multiple scopes)
+     * channel.forEachContext(ctx, (regCtx) => regCtx.onUpdate?.(result.notes));
+     *
+     * // Using explicit scope key (single key)
+     * channel.forEachContext('user:alice', (regCtx) => regCtx.onUpdate?.(result.notes));
+     * ```
+     */
+    forEachContext(scopeKeyOrContext, fn) {
+        const scopeKeys = typeof scopeKeyOrContext === "string"
+            ? [scopeKeyOrContext]
+            : this.getScopeKeys(scopeKeyOrContext);
+        const processedExecutions = new Set();
+        for (const scopeKey of scopeKeys) {
+            for (const [key, { executionId, context }] of this.contextRegistry) {
+                // Extract scope key from registry key and compare exactly
+                // This prevents 'malicious_user:alice' from matching 'user:alice'
+                const registeredScopeKey = this.extractScopeKeyFromRegistryKey(key);
+                if (registeredScopeKey === scopeKey && !processedExecutions.has(executionId)) {
+                    processedExecutions.add(executionId);
+                    try {
+                        fn(context);
+                    }
+                    catch (error) {
+                        console.error(`ChannelRouter[${this.channel}]: Error in forEachContext callback:`, error);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Notify all registered contexts for matching scopes with an event and result.
+     * Called automatically by handle() after handler returns.
+     * Deduplicates by executionId - each execution's callback runs at most once.
+     *
+     * @param context - Context to derive scope from
+     * @param event - The channel event
+     * @param result - The handler's result
+     */
+    notifyRegisteredContexts(context, event, result) {
+        const scopeKeys = this.getScopeKeys(context);
+        const notifiedExecutions = new Set();
+        for (const scopeKey of scopeKeys) {
+            for (const [key, { executionId, onEvent }] of this.contextRegistry) {
+                // Extract scope key from registry key and compare exactly
+                // This prevents 'malicious_user:alice' from matching 'user:alice'
+                const registeredScopeKey = this.extractScopeKeyFromRegistryKey(key);
+                if (registeredScopeKey === scopeKey && !notifiedExecutions.has(executionId) && onEvent) {
+                    notifiedExecutions.add(executionId);
+                    try {
+                        onEvent(event, result);
+                    }
+                    catch (error) {
+                        console.error(`ChannelRouter[${this.channel}]: Error in onEvent callback:`, error);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Get the number of registered contexts (for debugging/monitoring).
+     */
+    getRegisteredContextCount() {
+        return this.contextRegistry.size;
+    }
+    // =========================================================================
+    // Publishing Methods
+    // =========================================================================
+    /**
+     * Resolve a value or getter function.
+     */
+    resolve(valueOrGetter) {
+        return typeof valueOrGetter === "function" ? valueOrGetter() : valueOrGetter;
+    }
+    /**
+     * Get the scope prefix for a given scope key.
+     * If scopeKey is provided, uses that key from the mapping.
+     * Otherwise uses the first key from the mapping.
+     *
+     * Note: Function scopes are not supported for publishing via .scope()/.to() -
+     * use mapping syntax instead: { user: 'userId' }
+     */
+    getScopePrefix(scopeKey) {
+        const scope = this.config.scope;
+        if (!scope)
+            return undefined;
+        // Function scope - can't select by key for publishing
+        // (functions are for context matching, not room prefix selection)
+        if (typeof scope === "function") {
+            return undefined;
+        }
+        // Get the mapping (flatten if array)
+        const mapping = Array.isArray(scope)
+            ? scope.reduce((acc, m) => ({ ...acc, ...m }), {})
+            : scope;
+        // If scopeKey provided, use it; otherwise use first key
+        if (scopeKey) {
+            return scopeKey in mapping ? scopeKey : undefined;
+        }
+        const keys = Object.keys(mapping);
+        return keys.length > 0 ? keys[0] : undefined;
+    }
+    /**
+     * Create a scoped publisher (has scope prefix set, needs .to(id)).
+     */
+    createScopedPublisherForKey(scopePrefix) {
+        return {
+            to: (idGetter) => {
+                return this.createBoundPublisherForPrefix(scopePrefix, idGetter);
+            },
+        };
+    }
+    /**
+     * Create a bound publisher for a specific scope prefix.
+     */
+    createBoundPublisherForPrefix(scopePrefix, idGetter) {
+        return {
+            send: async (event) => {
+                const id = this.resolve(idGetter);
+                await this.sendInternalWithPrefix(scopePrefix, id, event);
+            },
+            broadcast: async (event, options) => {
+                const id = this.resolve(idGetter);
+                await this.sendInternalWithPrefix(scopePrefix, id, event, {
+                    excludeSender: true,
+                    sourceConnectionId: options?.sourceConnectionId,
+                });
+            },
+        };
+    }
+    /**
+     * Internal send with explicit scope prefix and id.
+     */
+    async sendInternalWithPrefix(scopePrefix, id, event, options) {
+        const transport = this.getTransport();
+        const room = `${scopePrefix}:${id}`;
+        const sourceConnectionId = options?.sourceConnectionId ??
+            Context.tryGet()?.metadata?.["sessionId"];
+        await transport.send({
+            channel: this.channel,
+            type: event.type,
+            payload: event.payload,
+            target: {
+                rooms: [room],
+                excludeSender: options?.excludeSender,
+            },
+            metadata: {
+                timestamp: Date.now(),
+                source: `ChannelRouter:${this.channel}`,
+                sourceConnectionId,
+            },
+        });
+    }
+    /**
+     * Create a publisher interface for this channel.
+     */
+    createPublisher() {
+        return {
+            scope: (scopeKey) => {
+                const prefix = this.getScopePrefix(scopeKey);
+                if (!prefix) {
+                    throw new NotFoundError("scope", scopeKey, `ChannelRouter[${this.channel}]: Unknown scope key`);
+                }
+                return this.createScopedPublisherForKey(prefix);
+            },
+            to: (idGetter) => {
+                const prefix = this.getScopePrefix();
+                if (!prefix) {
+                    throw ValidationError.required(`ChannelRouter[${this.channel}].scope`);
+                }
+                return this.createBoundPublisherForPrefix(prefix, idGetter);
+            },
+        };
+    }
+    /**
+     * Get a publisher without subscribing (for services that only publish).
+     */
+    publisher() {
+        return this.createPublisher();
+    }
+}
+/**
+ * Factory function to create a ChannelRouter with common defaults.
+ */
+export function createChannelRouter(channel, config = {}) {
+    return new ChannelRouter(channel, config);
+}
+//# sourceMappingURL=service.js.map