@hazeljs/realtime 0.2.0-rc.3

package/dist/providers/openai/openai-realtime.session.test.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const openai_realtime_session_1 = require("./openai-realtime.session");
+const openai_realtime_client_1 = require("./openai-realtime.client");
+const mockClientConnect = jest.fn().mockResolvedValue(undefined);
+const mockClientSend = jest.fn();
+const mockClientDisconnect = jest.fn();
+jest.mock('./openai-realtime.client', () => ({
+    OpenAIRealtimeClient: jest.fn().mockImplementation(() => ({
+        connect: mockClientConnect,
+        send: jest.fn(),
+        appendAudio: jest.fn(),
+        addConversationItem: jest.fn(),
+        createResponse: jest.fn(),
+        onAny: jest.fn((handler) => {
+            mockOnAnyHandler = handler;
+            return () => { };
+        }),
+        disconnect: mockClientDisconnect,
+        connected: true,
+    })),
+}));
+let mockOnAnyHandler = null;
+describe('OpenAIRealtimeSession', () => {
+    const mockHazelClient = {
+        id: 'session-1',
+        send: mockClientSend,
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockOnAnyHandler = null;
+    });
+    describe('connect', () => {
+        it('should connect the underlying client', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            expect(mockClientConnect).toHaveBeenCalled();
+        });
+        it('should forward server events to hazel client via onAny', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            expect(mockOnAnyHandler).toBeDefined();
+            mockOnAnyHandler({ type: 'session.created', session: { id: 's1' } });
+            expect(mockClientSend).toHaveBeenCalledWith('realtime', {
+                type: 'session.created',
+                session: { id: 's1' },
+            });
+        });
+    });
+    describe('handleClientMessage', () => {
+        it('should forward valid OpenAI events to client', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.handleClientMessage({
+                type: 'input_audio_buffer.append',
+                audio: 'base64data',
+            });
+            const clientInstance = openai_realtime_client_1.OpenAIRealtimeClient.mock.results[0]?.value;
+            expect(clientInstance.send).toHaveBeenCalledWith({
+                type: 'input_audio_buffer.append',
+                audio: 'base64data',
+            });
+        });
+        it('should ignore non-object payload', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.handleClientMessage(null);
+            session.handleClientMessage('string');
+            session.handleClientMessage(123);
+            const clientInstance = openai_realtime_client_1.OpenAIRealtimeClient.mock.results[0]?.value;
+            expect(clientInstance.send).not.toHaveBeenCalled();
+        });
+        it('should ignore payload without type', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.handleClientMessage({ data: 'no type' });
+            const clientInstance = openai_realtime_client_1.OpenAIRealtimeClient.mock.results[0]?.value;
+            expect(clientInstance.send).not.toHaveBeenCalled();
+        });
+    });
+    describe('appendAudio', () => {
+        it('should call client appendAudio', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.appendAudio('base64chunk');
+            const clientInstance = openai_realtime_client_1.OpenAIRealtimeClient.mock.results[0]?.value;
+            expect(clientInstance.appendAudio).toHaveBeenCalledWith('base64chunk');
+        });
+    });
+    describe('sendText', () => {
+        it('should add conversation item and create response', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.sendText('Hello world');
+            const clientInstance = openai_realtime_client_1.OpenAIRealtimeClient.mock.results[0]?.value;
+            expect(clientInstance.addConversationItem).toHaveBeenCalledWith('Hello world');
+            expect(clientInstance.createResponse).toHaveBeenCalledWith({
+                outputModalities: ['audio', 'text'],
+            });
+        });
+    });
+    describe('getStats', () => {
+        it('should return session stats', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            const stats = session.getStats();
+            expect(stats).toMatchObject({
+                sessionId: 'session-1',
+                provider: 'openai',
+            });
+            expect(stats.connectedAt).toBeDefined();
+        });
+    });
+    describe('disconnect', () => {
+        it('should disconnect the client', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            session.disconnect();
+            expect(mockClientDisconnect).toHaveBeenCalled();
+        });
+    });
+    describe('isConnected', () => {
+        it('should return client connected state', async () => {
+            const session = new openai_realtime_session_1.OpenAIRealtimeSession(mockHazelClient, {
+                apiKey: 'test-key',
+            });
+            await session.connect();
+            expect(session.isConnected).toBe(true);
+        });
+    });
+});

package/dist/realtime-bootstrap.service.d.ts

@@ -0,0 +1,16 @@
+/**
+ * RealtimeBootstrapService - attaches RealtimeGateway to HTTP server on app bootstrap
+ */
+import type { HazelApp } from '@hazeljs/core';
+import type { RealtimeGateway } from './realtime.gateway';
+/**
+ * Implements OnApplicationBootstrap to auto-attach RealtimeGateway when the server is ready.
+ * Registered by RealtimeModule so users don't need to manually call gateway.attachToServer().
+ */
+export declare class RealtimeBootstrapService {
+    private readonly gateway;
+    private readonly app;
+    constructor(gateway: RealtimeGateway, app: HazelApp);
+    onApplicationBootstrap(): void;
+}
+//# sourceMappingURL=realtime-bootstrap.service.d.ts.map

package/dist/realtime-bootstrap.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-bootstrap.service.d.ts","sourceRoot":"","sources":["../src/realtime-bootstrap.service.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;GAGG;AACH,qBAAa,wBAAwB;IAEjC,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,QAAQ;IAGhC,sBAAsB,IAAI,IAAI;CAM/B"}

package/dist/realtime-bootstrap.service.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * RealtimeBootstrapService - attaches RealtimeGateway to HTTP server on app bootstrap
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeBootstrapService = void 0;
+/**
+ * Implements OnApplicationBootstrap to auto-attach RealtimeGateway when the server is ready.
+ * Registered by RealtimeModule so users don't need to manually call gateway.attachToServer().
+ */
+class RealtimeBootstrapService {
+    constructor(gateway, app) {
+        this.gateway = gateway;
+        this.app = app;
+    }
+    onApplicationBootstrap() {
+        const server = this.app.getServer();
+        if (server && this.gateway) {
+            this.gateway.attachToServer(server);
+        }
+    }
+}
+exports.RealtimeBootstrapService = RealtimeBootstrapService;

package/dist/realtime.gateway.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RealtimeGateway - WebSocket server for real-time voice AI
+ * Uses @Realtime decorator, extends WebSocketGateway, proxies to OpenAI Realtime API
+ */
+import 'reflect-metadata';
+import { Server as HttpServer } from 'http';
+import type { WebSocketServer } from 'ws';
+import { WebSocketGateway } from '@hazeljs/websocket';
+import type { WebSocketClient, WebSocketMessage } from '@hazeljs/websocket';
+import { RealtimeService } from './realtime.service';
+export interface RealtimeGatewayOptions {
+    /** WebSocket path (default: /realtime) */
+    path?: string;
+    /** Max payload size in bytes (default: 1MB) */
+    maxPayload?: number;
+}
+/**
+ * Gateway for real-time voice AI — uses @Realtime decorator for path/config
+ */
+export declare class RealtimeGateway extends WebSocketGateway {
+    private readonly realtimeService;
+    private readonly realtimeOptions;
+    private sessionPromises;
+    constructor(realtimeService: RealtimeService, options?: RealtimeGatewayOptions);
+    /**
+     * Attach Realtime WebSocket server to existing HTTP server
+     */
+    attachToServer(server: HttpServer, options?: {
+        path?: string;
+        maxPayload?: number;
+    }): WebSocketServer;
+    /**
+     * Override: create OpenAI session on connection (async, stored for handleMessage)
+     */
+    protected handleConnection(client: WebSocketClient): void;
+    /**
+     * Override: forward messages to OpenAI session (await session if still connecting)
+     */
+    protected handleMessage(clientId: string, message: WebSocketMessage): void;
+    /**
+     * Override: cleanup session on disconnect
+     */
+    protected handleDisconnection(clientId: string): void;
+}
+//# sourceMappingURL=realtime.gateway.d.ts.map

package/dist/realtime.gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.gateway.d.ts","sourceRoot":"","sources":["../src/realtime.gateway.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAiC,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBACa,eAAgB,SAAQ,gBAAgB;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;IACzD,OAAO,CAAC,eAAe,CAAqD;gBAEhE,eAAe,EAAE,eAAe,EAAE,OAAO,GAAE,sBAA2B;IAUlF;;OAEG;IACM,cAAc,CACrB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,eAAe;IAQlB;;OAEG;cACgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAelE;;OAEG;cACgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAcnF;;OAEG;cACgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAM/D"}

package/dist/realtime.gateway.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * RealtimeGateway - WebSocket server for real-time voice AI
+ * Uses @Realtime decorator, extends WebSocketGateway, proxies to OpenAI Realtime API
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+var RealtimeGateway_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeGateway = void 0;
+require("reflect-metadata");
+const websocket_1 = require("@hazeljs/websocket");
+const core_1 = __importDefault(require("@hazeljs/core"));
+const realtime_service_1 = require("./realtime.service");
+/**
+ * Gateway for real-time voice AI — uses @Realtime decorator for path/config
+ */
+let RealtimeGateway = RealtimeGateway_1 = class RealtimeGateway extends websocket_1.WebSocketGateway {
+    constructor(realtimeService, options = {}) {
+        super();
+        this.sessionPromises = new Map();
+        this.realtimeService = realtimeService;
+        const metadata = (0, websocket_1.getRealtimeMetadata)(RealtimeGateway_1);
+        this.realtimeOptions = {
+            path: options.path ?? metadata?.path ?? '/realtime',
+            maxPayload: options.maxPayload ?? metadata?.maxPayload ?? 1048576,
+        };
+    }
+    /**
+     * Attach Realtime WebSocket server to existing HTTP server
+     */
+    attachToServer(server, options) {
+        return super.attachToServer(server, {
+            path: options?.path ?? this.realtimeOptions.path,
+            maxPayload: options?.maxPayload ?? this.realtimeOptions.maxPayload,
+            perMessageDeflate: false,
+        });
+    }
+    /**
+     * Override: create OpenAI session on connection (async, stored for handleMessage)
+     */
+    handleConnection(client) {
+        const clientId = client.id;
+        const sessionPromise = this.realtimeService.createOpenAISession(client);
+        this.sessionPromises.set(clientId, sessionPromise);
+        sessionPromise
+            .then(() => core_1.default.info(`Realtime session started: ${clientId}`))
+            .catch((err) => {
+            core_1.default.error(`Realtime session failed for ${clientId}:`, err);
+            client.disconnect();
+        });
+        super.handleConnection(client);
+    }
+    /**
+     * Override: forward messages to OpenAI session (await session if still connecting)
+     */
+    handleMessage(clientId, message) {
+        const sessionPromise = this.sessionPromises.get(clientId);
+        if (!sessionPromise)
+            return;
+        sessionPromise
+            .then((session) => {
+            // Realtime client sends raw OpenAI events (e.g. { type, audio })
+            session.handleClientMessage(message);
+        })
+            .catch(() => {
+            // Session failed, ignore message
+        });
+    }
+    /**
+     * Override: cleanup session on disconnect
+     */
+    handleDisconnection(clientId) {
+        this.sessionPromises.delete(clientId);
+        this.realtimeService.removeSession(clientId);
+        core_1.default.info(`Realtime session ended: ${clientId}`);
+        super.handleDisconnection(clientId);
+    }
+};
+exports.RealtimeGateway = RealtimeGateway;
+exports.RealtimeGateway = RealtimeGateway = RealtimeGateway_1 = __decorate([
+    (0, websocket_1.Realtime)({ path: '/realtime', maxPayload: 1048576 }),
+    __metadata("design:paramtypes", [realtime_service_1.RealtimeService, Object])
+], RealtimeGateway);

package/dist/realtime.gateway.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=realtime.gateway.test.d.ts.map

package/dist/realtime.gateway.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.gateway.test.d.ts","sourceRoot":"","sources":["../src/realtime.gateway.test.ts"],"names":[],"mappings":""}

package/dist/realtime.gateway.test.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = require("http");
+const realtime_service_1 = require("./realtime.service");
+jest.mock('./providers/openai', () => {
+    const session = {
+        connect: jest.fn().mockResolvedValue(undefined),
+        disconnect: jest.fn(),
+        handleClientMessage: jest.fn(),
+        getStats: jest.fn().mockReturnValue({ sessionId: 'test', provider: 'openai' }),
+        isConnected: true,
+    };
+    global.__gatewayMockSession = session;
+    return {
+        OpenAIRealtimeSession: jest.fn(() => session),
+    };
+});
+const mockSession = global.__gatewayMockSession;
+jest.mock('@hazeljs/core', () => ({
+    __esModule: true,
+    default: {
+        info: jest.fn(),
+        debug: jest.fn(),
+        error: jest.fn(),
+        warn: jest.fn(),
+    },
+    Service: () => () => { },
+}));
+jest.mock('@hazeljs/websocket', () => {
+    const mockWss = { close: jest.fn((cb) => cb?.()) };
+    class MockWebSocketGateway {
+        constructor() {
+            this.attachToServer = jest.fn().mockReturnValue(mockWss);
+            this.close = jest.fn().mockResolvedValue(undefined);
+        }
+        handleConnection() { }
+        handleMessage() { }
+        handleDisconnection() { }
+    }
+    const Realtime = () => () => { };
+    const getRealtimeMetadata = jest.fn().mockReturnValue({
+        path: '/realtime',
+        maxPayload: 1048576,
+    });
+    return {
+        __esModule: true,
+        WebSocketGateway: MockWebSocketGateway,
+        Realtime,
+        getRealtimeMetadata,
+    };
+});
+const realtime_gateway_1 = require("./realtime.gateway");
+describe('RealtimeGateway', () => {
+    let realtimeService;
+    let gateway;
+    beforeEach(() => {
+        jest.clearAllMocks();
+        mockSession.connect.mockResolvedValue(undefined);
+        process.env.OPENAI_API_KEY = 'test-key';
+        realtimeService = new realtime_service_1.RealtimeService({ openaiApiKey: 'test-key' });
+        gateway = new realtime_gateway_1.RealtimeGateway(realtimeService);
+    });
+    afterEach(() => {
+        delete process.env.OPENAI_API_KEY;
+    });
+    describe('constructor', () => {
+        it('should create gateway with default options', () => {
+            expect(gateway).toBeDefined();
+        });
+        it('should accept custom options', () => {
+            const customGateway = new realtime_gateway_1.RealtimeGateway(realtimeService, {
+                path: '/voice',
+                maxPayload: 2048,
+            });
+            expect(customGateway).toBeDefined();
+        });
+    });
+    describe('attachToServer', () => {
+        it('should attach to HTTP server', () => {
+            const server = (0, http_1.createServer)(() => { });
+            const result = gateway.attachToServer(server);
+            expect(result).toBeDefined();
+            server.close();
+        });
+        it('should use gateway options when attachToServer called without options', () => {
+            const server = (0, http_1.createServer)(() => { });
+            const customGateway = new realtime_gateway_1.RealtimeGateway(realtimeService, { path: '/voice' });
+            const result = customGateway.attachToServer(server);
+            expect(result).toBeDefined();
+            server.close();
+        });
+        it('should use custom path when provided', () => {
+            const server = (0, http_1.createServer)(() => { });
+            const customGateway = new realtime_gateway_1.RealtimeGateway(realtimeService, {
+                path: '/voice',
+            });
+            const result = customGateway.attachToServer(server, { path: '/custom' });
+            expect(result).toBeDefined();
+            server.close();
+        });
+    });
+    describe('handleConnection error', () => {
+        it('should disconnect client when session creation fails', async () => {
+            mockSession.connect.mockRejectedValueOnce(new Error('Connection failed'));
+            const mockClient = {
+                id: 'client-fail',
+                socket: { on: jest.fn(), send: jest.fn(), close: jest.fn() },
+                metadata: new Map(),
+                rooms: new Set(),
+                send: jest.fn(),
+                disconnect: jest.fn(),
+                join: jest.fn(),
+                leave: jest.fn(),
+                inRoom: jest.fn().mockReturnValue(false),
+            };
+            gateway.handleConnection(mockClient);
+            await new Promise((r) => setTimeout(r, 50));
+            expect(mockClient.disconnect).toHaveBeenCalled();
+            mockSession.connect.mockResolvedValue(undefined);
+        });
+    });
+    describe('handleConnection', () => {
+        it('should create OpenAI session on connection', async () => {
+            const mockClient = {
+                id: 'client-123',
+                socket: { on: jest.fn(), send: jest.fn(), close: jest.fn() },
+                metadata: new Map(),
+                rooms: new Set(),
+                send: jest.fn(),
+                disconnect: jest.fn(),
+                join: jest.fn(),
+                leave: jest.fn(),
+                inRoom: jest.fn().mockReturnValue(false),
+            };
+            gateway.handleConnection(mockClient);
+            await new Promise((r) => setTimeout(r, 50));
+            expect(realtimeService.getSession('client-123')).toBeDefined();
+        });
+    });
+    describe('handleMessage', () => {
+        it('should forward message to session when session exists', async () => {
+            const mockClient = {
+                id: 'client-msg',
+                send: jest.fn(),
+            };
+            await realtimeService.createOpenAISession(mockClient);
+            const server = (0, http_1.createServer)(() => { });
+            gateway.attachToServer(server);
+            const mockSocket = {
+                on: jest.fn((ev, fn) => {
+                    if (ev === 'message')
+                        _mockMessageHandler = fn;
+                    return mockSocket;
+                }),
+                send: jest.fn(),
+                close: jest.fn(),
+            };
+            let _mockMessageHandler = () => { };
+            const mockClientForConn = {
+                id: 'client-msg',
+                socket: mockSocket,
+                metadata: new Map(),
+                rooms: new Set(),
+                send: jest.fn(),
+                disconnect: jest.fn(),
+                join: jest.fn(),
+                leave: jest.fn(),
+                inRoom: jest.fn().mockReturnValue(false),
+            };
+            gateway.handleConnection(mockClientForConn);
+            await new Promise((r) => setTimeout(r, 50));
+            const session = realtimeService.getSession('client-msg');
+            expect(session).toBeDefined();
+            gateway.handleMessage('client-msg', { type: 'test.event', data: 'payload' });
+            await new Promise((r) => setTimeout(r, 50));
+            expect(mockSession.handleClientMessage).toHaveBeenCalledWith({
+                type: 'test.event',
+                data: 'payload',
+            });
+            server.close();
+        });
+        it('should do nothing when session does not exist', () => {
+            gateway.handleMessage('non-existent', { type: 'test' });
+            expect(mockSession.handleClientMessage).not.toHaveBeenCalled();
+        });
+        it('should ignore message when session creation failed', async () => {
+            mockSession.connect.mockRejectedValueOnce(new Error('fail'));
+            const mockClient = {
+                id: 'client-msg-fail',
+                socket: { on: jest.fn(), send: jest.fn(), close: jest.fn() },
+                metadata: new Map(),
+                rooms: new Set(),
+                send: jest.fn(),
+                disconnect: jest.fn(),
+                join: jest.fn(),
+                leave: jest.fn(),
+                inRoom: jest.fn().mockReturnValue(false),
+            };
+            gateway.handleConnection(mockClient);
+            gateway.handleMessage('client-msg-fail', { type: 'test.event' });
+            await new Promise((r) => setTimeout(r, 50));
+            expect(mockSession.handleClientMessage).not.toHaveBeenCalled();
+            mockSession.connect.mockResolvedValue(undefined);
+        });
+    });
+    describe('handleDisconnection', () => {
+        it('should remove session on disconnect', async () => {
+            const mockClient = {
+                id: 'client-disc',
+                send: jest.fn(),
+            };
+            await realtimeService.createOpenAISession(mockClient);
+            expect(realtimeService.getSession('client-disc')).toBeDefined();
+            gateway.handleDisconnection('client-disc');
+            expect(realtimeService.getSession('client-disc')).toBeUndefined();
+            expect(mockSession.disconnect).toHaveBeenCalled();
+        });
+    });
+    describe('close', () => {
+        it('should close the gateway', async () => {
+            const server = (0, http_1.createServer)(() => { });
+            gateway.attachToServer(server);
+            await gateway.close();
+            expect(true).toBe(true);
+        });
+        it('should resolve when not attached', async () => {
+            await expect(gateway.close()).resolves.toBeUndefined();
+        });
+    });
+});

package/dist/realtime.module.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RealtimeModule - Real-time voice AI for HazelJS
+ */
+import { RealtimeService } from './realtime.service';
+import { RealtimeGateway } from './realtime.gateway';
+import { RealtimeBootstrapService } from './realtime-bootstrap.service';
+import type { RealtimeModuleOptions } from './realtime.types';
+export declare class RealtimeModule {
+    /**
+     * Configure Realtime module with OpenAI Realtime API
+     */
+    static forRoot(options?: RealtimeModuleOptions): {
+        module: typeof RealtimeModule;
+        providers: Array<{
+            provide: typeof RealtimeService | typeof RealtimeGateway | typeof RealtimeBootstrapService;
+            useClass?: typeof RealtimeBootstrapService;
+            useValue?: RealtimeService | RealtimeGateway;
+        }>;
+        exports: (typeof RealtimeService | typeof RealtimeGateway)[];
+        global: boolean;
+    };
+    /**
+     * Configure Realtime module asynchronously (e.g. from config service)
+     */
+    static forRootAsync(options: {
+        useFactory: (...args: unknown[]) => Promise<RealtimeModuleOptions> | RealtimeModuleOptions;
+        inject?: unknown[];
+    }): {
+        module: typeof RealtimeModule;
+        providers: Array<{
+            provide: string | typeof RealtimeService | typeof RealtimeGateway | typeof RealtimeBootstrapService;
+            useFactory?: unknown;
+            useClass?: typeof RealtimeBootstrapService;
+            inject?: unknown[];
+        }>;
+        exports: (typeof RealtimeService | typeof RealtimeGateway)[];
+        global: boolean;
+    };
+}
+//# sourceMappingURL=realtime.module.d.ts.map

package/dist/realtime.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.module.d.ts","sourceRoot":"","sources":["../src/realtime.module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,qBAIa,cAAc;IACzB;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG;QACnD,MAAM,EAAE,OAAO,cAAc,CAAC;QAC9B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EAAE,OAAO,eAAe,GAAG,OAAO,eAAe,GAAG,OAAO,wBAAwB,CAAC;YAC3F,QAAQ,CAAC,EAAE,OAAO,wBAAwB,CAAC;YAC3C,QAAQ,CAAC,EAAE,eAAe,GAAG,eAAe,CAAC;SAC9C,CAAC,CAAC;QACH,OAAO,EAAE,CAAC,OAAO,eAAe,GAAG,OAAO,eAAe,CAAC,EAAE,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;IA0BD;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE;QAC3B,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,qBAAqB,CAAC,GAAG,qBAAqB,CAAC;QAC3F,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;KACpB,GAAG;QACF,MAAM,EAAE,OAAO,cAAc,CAAC;QAC9B,SAAS,EAAE,KAAK,CAAC;YACf,OAAO,EACH,MAAM,GACN,OAAO,eAAe,GACtB,OAAO,eAAe,GACtB,OAAO,wBAAwB,CAAC;YACpC,UAAU,CAAC,EAAE,OAAO,CAAC;YACrB,QAAQ,CAAC,EAAE,OAAO,wBAAwB,CAAC;YAC3C,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;SACpB,CAAC,CAAC;QACH,OAAO,EAAE,CAAC,OAAO,eAAe,GAAG,OAAO,eAAe,CAAC,EAAE,CAAC;QAC7D,MAAM,EAAE,OAAO,CAAC;KACjB;CAkCF"}