@stonyx/sockets 0.1.1-alpha.3 → 0.1.1-alpha.31

package/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/abofs/stonyx-sockets/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-sockets/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/sockets.svg)](https://www.npmjs.com/package/@stonyx/sockets)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # @stonyx/sockets
 
 WebSocket server and client module for the [Stonyx framework](https://github.com/abofs/stonyx), providing plug-and-play handler discovery, built-in authentication enforcement, AES-256-GCM encryption, and automatic heartbeat keep-alive.
@@ -201,11 +205,28 @@ Configuration is read from `stonyx/config` under `sockets`:
 | Option | Env Var | Default | Description |
 |--------|---------|---------|-------------|
 | `port` | `SOCKET_PORT` | `2667` | WebSocket server port |
-| `address` | `SOCKET_ADDRESS` | `ws://localhost:2667` | Client connection address |
+| `address` | `SOCKET_ADDRESS` | `ws://localhost:{port}` | Client connection address |
 | `authKey` | `SOCKET_AUTH_KEY` | `'AUTH_KEY'` | Shared authentication key |
 | `heartBeatInterval` | `SOCKET_HEARTBEAT_INTERVAL` | `30000` | Heartbeat interval in ms |
 | `handlerDir` | `SOCKET_HANDLER_DIR` | `'./socket-handlers'` | Handler directory path |
+| `log` | `SOCKET_LOG` | `false` | Enable verbose logging |
 | `encryption` | `SOCKET_ENCRYPTION` | `'true'` | Enable AES-256-GCM encryption |
+| `reconnectBaseDelay` | `SOCKET_RECONNECT_BASE_DELAY` | `1000` | Base delay in ms for reconnect backoff |
+| `reconnectMaxDelay` | `SOCKET_RECONNECT_MAX_DELAY` | `60000` | Ceiling in ms for reconnect backoff |
+| `maxReconnectAttempts` | `SOCKET_MAX_RECONNECT_ATTEMPTS` | `Infinity` | Reconnect attempts before giving up |
+
+That is every variable `config/environment.js` reads -- all ten. `authData`
+(`{}`), `logColor` (`'white'`) and `logMethod` (`'socket'`) are also part of the
+resolved config but are not settable from the environment. No environment value
+is coerced: each resolves as the string the shell supplied.
+
+> **If your app consumes this package and runs its own test suite:** pin all ten
+> of these in your own `test/config/environment.js`, and keep `port` and
+> `address` coupled -- `address` is computed from `port` at module-eval time, so
+> pinning `port` alone does not move it. This package reads these variables
+> unconditionally, so a `NODE_ENV=test` run in a shell that exports
+> `SOCKET_ADDRESS` will dial whatever it names and send `authKey` to it. See
+> [docs/configuration.md](docs/configuration.md#why-all-ten-keys-are-pinned).
 
 ## API Reference
 
@@ -228,7 +249,7 @@ Configuration is read from `stonyx/config` under `sockets`:
 | `new SocketClient()` | Singleton constructor |
 | `async init()` | Discover handlers, connect, authenticate |
 | `send(payload)` | Send a message to the server |
-| `close()` | Close the connection |
+| `close()` | Forcefully tear down the socket (remove listeners, terminate, null) |
 | `reconnect()` | Reconnect (max 5 retries) |
 | `reset()` | Close + clear all state (for testing) |
 

package/config/environment.js

@@ -13,7 +13,7 @@ const {
 
 const port = SOCKET_PORT ?? 2667;
 
-export default {
+const config = {
   port,
   address: SOCKET_ADDRESS ?? `ws://localhost:${port}`,
   authKey: SOCKET_AUTH_KEY ?? 'AUTH_KEY',
@@ -28,3 +28,5 @@ export default {
   reconnectMaxDelay: SOCKET_RECONNECT_MAX_DELAY ?? 60000,
   maxReconnectAttempts: SOCKET_MAX_RECONNECT_ATTEMPTS ?? Infinity,
 };
+
+export default config;

package/dist/client.d.ts

@@ -0,0 +1,47 @@
+import { WebSocket } from 'ws';
+interface SocketMessage {
+    request: string;
+    data?: unknown;
+    response?: unknown;
+    sessionKey?: string;
+}
+interface HandlerInstance {
+    _clientRef?: SocketClient;
+    client: (response: unknown) => void;
+    [key: string]: unknown;
+}
+export default class SocketClient {
+    static instance: SocketClient | null;
+    handlers: Record<string, HandlerInstance>;
+    reconnectCount: number;
+    _intentionalClose: boolean;
+    socket: WebSocket | null;
+    sessionKey: Buffer | null;
+    globalKey: Buffer | null;
+    encryptionEnabled: boolean;
+    _heartBeatTimer: ReturnType<typeof setTimeout> | null;
+    _heartBeatResponseTimer: ReturnType<typeof setTimeout> | null;
+    promise: {
+        resolve: () => void;
+        reject: (reason?: unknown) => void;
+    } | null;
+    onDisconnect: ((code: number, reason: string) => void) | null;
+    onReconnecting: ((attempt: number, delay: number) => void) | null;
+    onReconnected: (() => void) | null;
+    onReconnectFailed: (() => void) | null;
+    constructor();
+    init(): Promise<void>;
+    discoverHandlers(): Promise<void>;
+    connect(): Promise<void>;
+    onMessage(payload: Buffer | string): void;
+    send(payload: SocketMessage, useGlobalKey?: boolean): void;
+    heartBeat(): void;
+    nextHeartBeat(): void;
+    onClose(code?: number, reason?: string): void;
+    close(): void;
+    getReconnectDelay(): number;
+    reconnect(): Promise<void>;
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAQ/B,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,eAAe;IACvB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,CAAC,OAAO,OAAO,YAAY;IAC/B,MAAM,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAErC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAM;IAC/C,cAAc,SAAK;IACnB,iBAAiB,UAAS;IAC1B,MAAM,EAAE,SAAS,GAAG,IAAI,CAAQ;IAChC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IACjC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAChC,iBAAiB,UAAS;IAC1B,eAAe,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAQ;IAC7D,uBAAuB,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,IAAI,CAAQ;IACrE,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,GAAG,IAAI,CAAQ;IAEnF,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACrE,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;IACzE,aAAa,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC1C,iBAAiB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAQ;;IAOxC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAwBrB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgC9B,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA2CzC,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,YAAY,UAAQ,GAAG,IAAI;IAYxD,SAAS,IAAI,IAAI;IAIjB,aAAa,IAAI,IAAI;IAcrB,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa7C,KAAK,IAAI,IAAI;IAab,iBAAiB,IAAI,MAAM;IAYrB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBhC,KAAK,IAAI,IAAI;CAYd"}

package/dist/client.js

@@ -0,0 +1,225 @@
+import { WebSocket } from 'ws';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { sleep } from '@stonyx/utils/promise';
+import { encrypt, decrypt, deriveKey } from './encryption.js';
+export default class SocketClient {
+    static instance;
+    handlers = {};
+    reconnectCount = 0;
+    _intentionalClose = false;
+    socket = null;
+    sessionKey = null;
+    globalKey = null;
+    encryptionEnabled = false;
+    _heartBeatTimer = null;
+    _heartBeatResponseTimer = null;
+    promise = null;
+    onDisconnect = null;
+    onReconnecting = null;
+    onReconnected = null;
+    onReconnectFailed = null;
+    constructor() {
+        if (SocketClient.instance)
+            return SocketClient.instance;
+        SocketClient.instance = this;
+    }
+    async init() {
+        await this.discoverHandlers();
+        const { encryption, authKey } = config.sockets;
+        if (encryption === undefined) {
+            throw new Error('SocketClient: config.sockets.encryption is undefined — the @stonyx/sockets module ' +
+                'config was not merged. Refusing to connect (would send cleartext). Ensure Stonyx has ' +
+                'finished loading modules before constructing a SocketClient.');
+        }
+        this.encryptionEnabled = encryption === 'true' || encryption === true;
+        if (this.encryptionEnabled) {
+            this.globalKey = deriveKey(authKey);
+        }
+        if (process.env.NODE_ENV === 'test')
+            return;
+        return this.connect();
+    }
+    async discoverHandlers() {
+        const { handlerDir } = config.sockets;
+        if (handlerDir === undefined) {
+            throw new Error('SocketClient: config.sockets.handlerDir is undefined — the @stonyx/sockets module ' +
+                'config was not merged. Ensure Stonyx has finished loading modules before constructing a SocketClient.');
+        }
+        await forEachFileImport(handlerDir, (HandlerClassUntyped, { name }) => {
+            const HandlerClass = HandlerClassUntyped;
+            const instance = new HandlerClass();
+            if (typeof instance.client === 'function') {
+                instance._clientRef = this;
+                this.handlers[name] = instance;
+            }
+        }, { ignoreAccessFailure: true });
+    }
+    async connect() {
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.on('error', () => { });
+            this.socket.terminate();
+            this.socket = null;
+        }
+        if (this.sessionKey)
+            log.socket('Clearing stale sessionKey');
+        this.sessionKey = null;
+        return new Promise((resolve, reject) => {
+            const { address, authKey, authData } = config.sockets;
+            this.promise = { resolve, reject };
+            log.socket(`Connecting to remote server: ${address}`);
+            const socket = new WebSocket(address);
+            this.socket = socket;
+            socket.on('message', (data) => this.onMessage(data));
+            socket.on('close', (code, reason) => this.onClose(code, reason.toString()));
+            socket.on('error', () => {
+                log.socket(`Error connecting to socket server`);
+                reject(new Error('Error connecting to socket server'));
+            });
+            socket.on('open', () => {
+                this._intentionalClose = false;
+                this.reconnectCount = 0;
+                this.send({ request: 'auth', data: { authKey, ...authData } }, true);
+            });
+        });
+    }
+    onMessage(payload) {
+        try {
+            let parsed;
+            if (this.encryptionEnabled) {
+                const key = this.sessionKey || this.globalKey;
+                if (!key)
+                    throw new Error('Encryption enabled but no key available');
+                const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+                parsed = JSON.parse(decrypt(raw, key));
+            }
+            else {
+                const raw = Buffer.isBuffer(payload) ? payload.toString() : payload;
+                parsed = JSON.parse(raw);
+            }
+            const { request, response, sessionKey } = parsed;
+            if (request === 'auth') {
+                if (sessionKey && this.encryptionEnabled) {
+                    this.sessionKey = Buffer.from(sessionKey, 'base64');
+                }
+                this.nextHeartBeat();
+                this.promise?.resolve();
+                this.promise = null;
+            }
+            if (request === 'heartBeat') {
+                this.nextHeartBeat();
+                return;
+            }
+            const handler = this.handlers[request] ?? this.handlers[kebabCaseToCamelCase(request)];
+            if (!handler) {
+                log.socket(`Call to invalid handler: ${request}`);
+                return;
+            }
+            handler.client.call({ ...handler, client: this }, response);
+        }
+        catch {
+            log.socket(`Invalid payload received from remote server`);
+        }
+    }
+    send(payload, useGlobalKey = false) {
+        if (!this.socket)
+            throw new Error('Socket is not connected');
+        if (this.encryptionEnabled) {
+            const key = useGlobalKey ? this.globalKey : this.sessionKey;
+            if (!key)
+                throw new Error('Encryption enabled but no key available');
+            const data = encrypt(JSON.stringify(payload), key);
+            this.socket.send(data);
+        }
+        else {
+            this.socket.send(JSON.stringify(payload));
+        }
+    }
+    heartBeat() {
+        this.send({ request: 'heartBeat' });
+    }
+    nextHeartBeat() {
+        if (this._heartBeatResponseTimer)
+            clearTimeout(this._heartBeatResponseTimer);
+        this._heartBeatResponseTimer = null;
+        const { heartBeatInterval } = config.sockets;
+        this._heartBeatTimer = setTimeout(() => {
+            this.heartBeat();
+            this._heartBeatResponseTimer = setTimeout(() => {
+                log.socket('Heartbeat response timeout — closing stale connection');
+                if (this.socket)
+                    this.socket.close();
+            }, heartBeatInterval);
+        }, heartBeatInterval);
+    }
+    // ws always provides code and reason; params are optional for direct calls and testing
+    onClose(code, reason) {
+        log.socket(`Disconnected from remote server (code: ${code ?? 'unknown'}, reason: ${reason || 'none'})`);
+        if (this._heartBeatTimer)
+            clearTimeout(this._heartBeatTimer);
+        if (this._heartBeatResponseTimer)
+            clearTimeout(this._heartBeatResponseTimer);
+        this._heartBeatResponseTimer = null;
+        this.onDisconnect?.(code ?? 1006, reason ?? '');
+        if (!this._intentionalClose) {
+            this.reconnect();
+        }
+    }
+    close() {
+        this._intentionalClose = true;
+        if (this._heartBeatTimer)
+            clearTimeout(this._heartBeatTimer);
+        if (this._heartBeatResponseTimer)
+            clearTimeout(this._heartBeatResponseTimer);
+        this._heartBeatResponseTimer = null;
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.on('error', () => { });
+            this.socket.terminate();
+            this.socket = null;
+        }
+    }
+    getReconnectDelay() {
+        const { reconnectBaseDelay = 1000, reconnectMaxDelay = 60000, } = config.sockets;
+        const exponential = reconnectBaseDelay * Math.pow(2, this.reconnectCount - 1);
+        const capped = Math.min(exponential, reconnectMaxDelay);
+        const jitter = Math.floor(Math.random() * 1000);
+        return capped + jitter;
+    }
+    async reconnect() {
+        const { maxReconnectAttempts = Infinity } = config.sockets;
+        this.reconnectCount++;
+        if (this.reconnectCount > maxReconnectAttempts) {
+            log.socket('Max reconnect attempts exceeded');
+            this.onReconnectFailed?.();
+            return;
+        }
+        const delay = this.getReconnectDelay();
+        this.onReconnecting?.(this.reconnectCount, delay);
+        log.socket(`Reconnecting (attempt ${this.reconnectCount}, delay ${delay}ms)`);
+        await sleep(delay / 1000);
+        try {
+            await this.connect();
+            this.onReconnected?.();
+        }
+        catch {
+            // onClose will fire and trigger the next reconnect attempt
+        }
+    }
+    reset() {
+        this.close();
+        this.handlers = {};
+        this.sessionKey = null;
+        this.reconnectCount = 0;
+        this._intentionalClose = false;
+        this.onDisconnect = null;
+        this.onReconnecting = null;
+        this.onReconnected = null;
+        this.onReconnectFailed = null;
+        SocketClient.instance = null;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/encryption.d.ts

@@ -0,0 +1,5 @@
+export declare function encrypt(data: string, key: Buffer): Buffer;
+export declare function decrypt(buffer: Buffer | string, key: Buffer): string;
+export declare function generateSessionKey(): Buffer;
+export declare function deriveKey(authKey: string): Buffer;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAMA,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQpE;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD"}

package/dist/encryption.js

@@ -0,0 +1,28 @@
+import crypto from 'node:crypto';
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+export function encrypt(data, key) {
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+    const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([iv, tag, encrypted]);
+}
+export function decrypt(buffer, key) {
+    if (typeof buffer === 'string')
+        buffer = Buffer.from(buffer, 'base64');
+    const iv = buffer.subarray(0, IV_LENGTH);
+    const tag = buffer.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+    const encrypted = buffer.subarray(IV_LENGTH + TAG_LENGTH);
+    const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+}
+export function generateSessionKey() {
+    return crypto.randomBytes(32);
+}
+export function deriveKey(authKey) {
+    return crypto.scryptSync(authKey, 'stonyx-sockets', 32);
+}
+//# sourceMappingURL=encryption.js.map

package/dist/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../src/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AAEjC,MAAM,SAAS,GAAG,aAAa,CAAC;AAChC,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,GAAW;IAC/C,MAAM,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC/E,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IAChC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,MAAuB,EAAE,GAAW;IAC1D,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,GAAG,UAAU,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,CAAC,CAAC;AAC1D,CAAC"}

package/dist/handler.d.ts

@@ -0,0 +1,6 @@
+export default class Handler {
+    static skipAuth: boolean;
+    server?: (data: unknown, client: unknown) => unknown | Promise<unknown>;
+    client?: (response: unknown) => void;
+}
+//# sourceMappingURL=handler.d.ts.map

package/dist/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,QAAQ,UAAS;IAEhB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9C"}

package/dist/handler.js

@@ -0,0 +1,4 @@
+export default class Handler {
+    static skipAuth = false;
+}
+//# sourceMappingURL=handler.js.map

package/dist/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../src/handler.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,QAAQ,GAAG,KAAK,CAAC"}

package/dist/main.d.ts

@@ -0,0 +1,10 @@
+export { default as SocketServer } from './server.js';
+export { default as SocketClient } from './client.js';
+export { default as Handler } from './handler.js';
+export default class Sockets {
+    static instance: Sockets | null;
+    constructor();
+    init(): Promise<void>;
+    reset(): void;
+}
+//# sourceMappingURL=main.d.ts.map

package/dist/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;;IAO1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,KAAK,IAAI,IAAI;CAGd"}

package/dist/main.js

@@ -0,0 +1,19 @@
+export { default as SocketServer } from './server.js';
+export { default as SocketClient } from './client.js';
+export { default as Handler } from './handler.js';
+export default class Sockets {
+    static instance;
+    constructor() {
+        if (Sockets.instance)
+            return Sockets.instance;
+        Sockets.instance = this;
+    }
+    async init() {
+        // Handler discovery is deferred to SocketServer.init() / SocketClient.init()
+        // This entry point satisfies Stonyx module auto-initialization
+    }
+    reset() {
+        Sockets.instance = null;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,OAAO,OAAO,OAAO;IAC1B,MAAM,CAAC,QAAQ,CAAiB;IAEhC;QACE,IAAI,OAAO,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC,QAAQ,CAAC;QAC9C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI;QACR,6EAA6E;QAC7E,+DAA+D;IACjE,CAAC;IAED,KAAK;QACH,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC;CACF"}

package/dist/server.d.ts

@@ -0,0 +1,49 @@
+import { WebSocket, WebSocketServer } from 'ws';
+interface SocketMessage {
+    request: string;
+    data?: unknown;
+    response?: unknown;
+    sessionKey?: string;
+}
+interface ConnectedClient {
+    id: number;
+    ip: string;
+    __authenticated: boolean;
+    __sessionKey?: Buffer;
+    meta?: Record<string, unknown>;
+    send(payload: SocketMessage, keyOverride?: Buffer): void;
+    close(): void;
+    terminate(): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+}
+interface HandlerInstance {
+    _serverRef?: SocketServer;
+    server: (data: unknown, client: ConnectedClient) => unknown | Promise<unknown>;
+    constructor: {
+        skipAuth: boolean;
+    };
+    [key: string]: unknown;
+}
+export default class SocketServer {
+    static instance: SocketServer | null;
+    clientMap: Map<number, ConnectedClient>;
+    handlers: Record<string, HandlerInstance>;
+    wss: WebSocketServer | null;
+    encryptionEnabled: boolean;
+    globalKey: Buffer | null;
+    onClientDisconnect: ((client: ConnectedClient, code: number, reason: string) => void) | null;
+    constructor();
+    init(): Promise<void>;
+    discoverHandlers(): Promise<void>;
+    validateAuthHandler(): void;
+    onMessage(payload: Buffer | string, client: ConnectedClient): Promise<void>;
+    prepareSend(client: ConnectedClient, ws: WebSocket): void;
+    handleDisconnect(client: ConnectedClient, code?: number, reason?: string): void;
+    sendTo(clientId: number, request: string, response: unknown): void;
+    sendToByMeta(key: string, value: unknown, request: string, response: unknown): boolean;
+    broadcast(request: string, response: unknown): void;
+    close(): void;
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAOhD,UAAU,aAAa;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,KAAK,IAAI,IAAI,CAAC;IACd,SAAS,IAAI,IAAI,CAAC;IAClB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAChE;AAED,UAAU,eAAe;IACvB,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,WAAW,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID,MAAM,CAAC,OAAO,OAAO,YAAY;IAC/B,MAAM,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAErC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAa;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAM;IAC/C,GAAG,EAAE,eAAe,GAAG,IAAI,CAAQ;IACnC,iBAAiB,UAAS;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEhC,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAQ;;IAO9F,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6CrB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBvC,mBAAmB,IAAI,IAAI;IAMrB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA2DjF,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI;IAiBzD,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAO/E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAMlE,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO;IAUtF,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAQnD,KAAK,IAAI,IAAI;IAUb,KAAK,IAAI,IAAI;CAOd"}

package/dist/server.js

@@ -0,0 +1,191 @@
+import { WebSocketServer } from 'ws';
+import config from 'stonyx/config';
+import log from 'stonyx/log';
+import { forEachFileImport } from '@stonyx/utils/file';
+import { kebabCaseToCamelCase } from '@stonyx/utils/string';
+import { encrypt, decrypt, deriveKey, generateSessionKey } from './encryption.js';
+let clientId = 0;
+export default class SocketServer {
+    static instance;
+    clientMap = new Map();
+    handlers = {};
+    wss = null;
+    encryptionEnabled = false;
+    globalKey = null;
+    onClientDisconnect = null;
+    constructor() {
+        if (SocketServer.instance)
+            return SocketServer.instance;
+        SocketServer.instance = this;
+    }
+    async init() {
+        // Self-register so log.socket works even when @stonyx/sockets is in the
+        // consumer's `dependencies` (stonyx loader only merges devDependencies).
+        const { logColor = 'white', logMethod = 'socket' } = config.sockets;
+        log.defineType(logMethod, logColor);
+        await this.discoverHandlers();
+        this.validateAuthHandler();
+        const { port, encryption, authKey } = config.sockets;
+        if (encryption === undefined) {
+            throw new Error('SocketServer: config.sockets.encryption is undefined — the @stonyx/sockets module ' +
+                'config was not merged. Refusing to start (would accept cleartext). Ensure Stonyx has ' +
+                'finished loading modules before constructing a SocketServer.');
+        }
+        this.encryptionEnabled = encryption === 'true' || encryption === true;
+        if (this.encryptionEnabled) {
+            this.globalKey = deriveKey(authKey);
+        }
+        const wss = new WebSocketServer({ port });
+        this.wss = wss;
+        log.socket(`WebSocket server is listening on port ${port}`);
+        wss.on('connection', (ws, request) => {
+            const { remoteAddress } = request.socket;
+            log.socket(`[${remoteAddress}] Client connected`);
+            const client = ws;
+            client.id = ++clientId;
+            client.ip = remoteAddress || '';
+            client.__authenticated = false;
+            this.prepareSend(client, ws);
+            ws.on('message', (payload) => this.onMessage(payload, client));
+            ws.on('close', (code, reason) => this.handleDisconnect(client, code, reason.toString()));
+        });
+    }
+    async discoverHandlers() {
+        const { handlerDir } = config.sockets;
+        if (handlerDir === undefined) {
+            throw new Error('SocketServer: config.sockets.handlerDir is undefined — the @stonyx/sockets module ' +
+                'config was not merged. Ensure Stonyx has finished loading modules before constructing a SocketServer.');
+        }
+        await forEachFileImport(handlerDir, (HandlerClassUntyped, { name }) => {
+            const HandlerClass = HandlerClassUntyped;
+            const instance = new HandlerClass();
+            if (typeof instance.server === 'function') {
+                instance._serverRef = this;
+                this.handlers[name] = instance;
+            }
+        }, { ignoreAccessFailure: true });
+    }
+    validateAuthHandler() {
+        if (!this.handlers.auth) {
+            throw new Error('SocketServer requires an "auth" handler with a server() method');
+        }
+    }
+    async onMessage(payload, client) {
+        try {
+            let parsed;
+            if (this.encryptionEnabled) {
+                const key = client.__authenticated ? client.__sessionKey : this.globalKey;
+                if (!key)
+                    throw new Error('Encryption enabled but no key available');
+                const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
+                parsed = JSON.parse(decrypt(raw, key));
+            }
+            else {
+                parsed = JSON.parse(typeof payload === 'string' ? payload : payload.toString());
+            }
+            const { request, data } = parsed;
+            // Built-in heartbeat - no handler needed
+            if (request === 'heartBeat') {
+                if (client.__authenticated)
+                    client.send({ request: 'heartBeat', response: true });
+                return;
+            }
+            const handler = this.handlers[request] ?? this.handlers[kebabCaseToCamelCase(request)];
+            if (!handler) {
+                log.socket(`Invalid request received: ${request}`);
+                return;
+            }
+            if (request !== 'auth' && !handler.constructor.skipAuth && !client.__authenticated) {
+                log.socket(`Rejected unauthenticated request: ${request}`);
+                client.close();
+                return;
+            }
+            const response = await handler.server(data, client);
+            if (response === undefined || response === null)
+                return;
+            if (request === 'auth' && response) {
+                client.__authenticated = true;
+                if (this.encryptionEnabled) {
+                    const sessionKey = generateSessionKey();
+                    client.__sessionKey = sessionKey;
+                    if (!this.globalKey)
+                        throw new Error('Encryption enabled but globalKey not initialized');
+                    client.send({ request, response, sessionKey: sessionKey.toString('base64') }, this.globalKey);
+                }
+                else {
+                    client.send({ request, response });
+                }
+                return;
+            }
+            client.send({ request, response });
+        }
+        catch (error) {
+            log.socket(`Invalid payload from client`);
+            if (config.debug)
+                console.error(error);
+            client.close();
+        }
+    }
+    prepareSend(client, ws) {
+        const socketSend = ws.send.bind(ws);
+        const server = this;
+        client.send = (payload, keyOverride) => {
+            if (server.encryptionEnabled) {
+                const key = keyOverride || client.__sessionKey;
+                if (!key)
+                    throw new Error('Encryption enabled but no key available');
+                const data = encrypt(JSON.stringify(payload), key);
+                socketSend(data);
+            }
+            else {
+                socketSend(JSON.stringify(payload));
+            }
+        };
+    }
+    // ws always provides code and reason; params are optional for direct calls and testing
+    handleDisconnect(client, code, reason) {
+        const { ip } = client;
+        log.socket(`[${ip}] Client disconnected (code: ${code ?? 'unknown'}, reason: ${reason || 'none'})`);
+        this.clientMap.delete(client.id);
+        this.onClientDisconnect?.(client, code ?? 1006, reason ?? '');
+    }
+    sendTo(clientId, request, response) {
+        const client = this.clientMap.get(clientId);
+        if (!client)
+            return;
+        client.send({ request, response });
+    }
+    sendToByMeta(key, value, request, response) {
+        for (const [, client] of this.clientMap) {
+            if (client.meta?.[key] === value && client.__authenticated) {
+                client.send({ request, response });
+                return true;
+            }
+        }
+        return false;
+    }
+    broadcast(request, response) {
+        for (const [, client] of this.clientMap) {
+            if (client.__authenticated) {
+                client.send({ request, response });
+            }
+        }
+    }
+    close() {
+        if (this.wss) {
+            for (const client of this.wss.clients) {
+                client.terminate();
+            }
+            this.wss.close();
+            this.wss = null;
+        }
+    }
+    reset() {
+        this.close();
+        this.clientMap.clear();
+        this.handlers = {};
+        clientId = 0;
+        SocketServer.instance = null;
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -4,21 +4,34 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.3",
+  "version": "0.1.1-alpha.31",
   "description": "WebSocket server and client module for the Stonyx framework",
-  "main": "src/main.js",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "type": "module",
   "files": [
-    "src",
+    "dist",
     "config",
     "LICENSE.md",
     "README.md"
   ],
   "exports": {
-    ".": "./src/main.js",
-    "./server": "./src/server.js",
-    "./client": "./src/client.js",
-    "./handler": "./src/handler.js"
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./handler": {
+      "types": "./dist/handler.d.ts",
+      "default": "./dist/handler.js"
+    }
   },
   "publishConfig": {
     "access": "public",
@@ -38,15 +51,21 @@
   },
   "homepage": "https://github.com/abofs/stonyx-sockets#readme",
   "dependencies": {
-    "stonyx": "0.2.3-beta.12",
+    "stonyx": "0.2.3-beta.62",
     "ws": "^8.18.1"
   },
   "devDependencies": {
-    "@stonyx/utils": "0.2.3-beta.7",
+    "@stonyx/utils": "0.2.3-beta.23",
+    "@types/node": "^25.5.2",
+    "@types/ws": "^8.18.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm build:test && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
   }
 }

package/src/client.js

@@ -1,197 +0,0 @@
-import { WebSocket } from 'ws';
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { forEachFileImport } from '@stonyx/utils/file';
-import { sleep } from '@stonyx/utils/promise';
-import { encrypt, decrypt, deriveKey } from './encryption.js';
-
-export default class SocketClient {
-  handlers = {};
-  reconnectCount = 0;
-  _intentionalClose = false;
-
-  onDisconnect = null;
-  onReconnecting = null;
-  onReconnected = null;
-  onReconnectFailed = null;
-
-  constructor() {
-    if (SocketClient.instance) return SocketClient.instance;
-    SocketClient.instance = this;
-  }
-
-  async init() {
-    await this.discoverHandlers();
-
-    const { encryption, authKey } = config.sockets;
-    this.encryptionEnabled = encryption === 'true' || encryption === true;
-
-    if (this.encryptionEnabled) {
-      this.globalKey = deriveKey(authKey);
-    }
-
-    return this.connect();
-  }
-
-  async discoverHandlers() {
-    const { handlerDir } = config.sockets;
-
-    await forEachFileImport(handlerDir, (HandlerClass, { name }) => {
-      const instance = new HandlerClass();
-
-      if (typeof instance.client === 'function') {
-        instance._clientRef = this;
-        this.handlers[name] = instance;
-      }
-    }, { ignoreAccessFailure: true });
-  }
-
-  async connect() {
-    return new Promise((resolve, reject) => {
-      const { address, authKey, authData } = config.sockets;
-      this.promise = { resolve, reject };
-
-      log.socket(`Connecting to remote server: ${address}`);
-      const socket = new WebSocket(address);
-      this.socket = socket;
-
-      socket.onmessage = this.onMessage.bind(this);
-      socket.onclose = this.onClose.bind(this);
-      socket.onerror = event => {
-        log.socket(`Error connecting to socket server`);
-        reject('Error connecting to socket server');
-      };
-
-      socket.onopen = () => {
-        this._intentionalClose = false;
-        this.reconnectCount = 0;
-        this.send({ request: 'auth', data: { authKey, ...authData } }, true);
-      };
-    });
-  }
-
-  onMessage({ data: payload }) {
-    try {
-      let parsed;
-
-      if (this.encryptionEnabled) {
-        const key = this.sessionKey || this.globalKey;
-        const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
-        parsed = JSON.parse(decrypt(raw, key));
-      } else {
-        const raw = Buffer.isBuffer(payload) ? payload.toString() : payload;
-        parsed = JSON.parse(raw);
-      }
-
-      const { request, response, sessionKey } = parsed;
-
-      if (request === 'auth') {
-        if (sessionKey && this.encryptionEnabled) {
-          this.sessionKey = Buffer.from(sessionKey, 'base64');
-        }
-        this.nextHeartBeat();
-      }
-
-      if (request === 'heartBeat') {
-        this.nextHeartBeat();
-        return;
-      }
-
-      const handler = this.handlers[request];
-
-      if (!handler) {
-        log.socket(`Call to invalid handler: ${request}`);
-        return;
-      }
-
-      handler.client.call({ client: this, ...handler }, response);
-    } catch (error) {
-      log.socket(`Invalid payload received from remote server`);
-    }
-  }
-
-  send(payload, useGlobalKey = false) {
-    if (this.encryptionEnabled) {
-      const key = useGlobalKey ? this.globalKey : this.sessionKey;
-      const data = encrypt(JSON.stringify(payload), key);
-      this.socket.send(data);
-    } else {
-      this.socket.send(JSON.stringify(payload));
-    }
-  }
-
-  heartBeat() {
-    this.send({ request: 'heartBeat' });
-  }
-
-  nextHeartBeat() {
-    this._heartBeatTimer = setTimeout(() => this.heartBeat(), config.sockets.heartBeatInterval);
-  }
-
-  onClose() {
-    log.socket('Disconnected from remote server');
-    if (this._heartBeatTimer) clearTimeout(this._heartBeatTimer);
-
-    this.onDisconnect?.();
-
-    if (!this._intentionalClose) {
-      this.reconnect();
-    }
-  }
-
-  close() {
-    this._intentionalClose = true;
-    if (this._heartBeatTimer) clearTimeout(this._heartBeatTimer);
-    if (this.socket) this.socket.close();
-  }
-
-  getReconnectDelay() {
-    const {
-      reconnectBaseDelay = 1000,
-      reconnectMaxDelay = 60000,
-    } = config.sockets;
-
-    const exponential = reconnectBaseDelay * Math.pow(2, this.reconnectCount - 1);
-    const capped = Math.min(exponential, reconnectMaxDelay);
-    const jitter = Math.floor(Math.random() * 1000);
-    return capped + jitter;
-  }
-
-  async reconnect() {
-    const { maxReconnectAttempts = Infinity } = config.sockets;
-
-    this.reconnectCount++;
-
-    if (this.reconnectCount > maxReconnectAttempts) {
-      log.socket('Max reconnect attempts exceeded');
-      this.onReconnectFailed?.();
-      return;
-    }
-
-    const delay = this.getReconnectDelay();
-    this.onReconnecting?.(this.reconnectCount, delay);
-    log.socket(`Reconnecting (attempt ${this.reconnectCount}, delay ${delay}ms)`);
-
-    await sleep(delay / 1000);
-
-    try {
-      await this.connect();
-      this.onReconnected?.();
-    } catch {
-      // onClose will fire and trigger the next reconnect attempt
-    }
-  }
-
-  reset() {
-    this.close();
-    this.handlers = {};
-    this.sessionKey = null;
-    this.reconnectCount = 0;
-    this._intentionalClose = false;
-    this.onDisconnect = null;
-    this.onReconnecting = null;
-    this.onReconnected = null;
-    this.onReconnectFailed = null;
-    SocketClient.instance = null;
-  }
-}

package/src/encryption.js

@@ -1,31 +0,0 @@
-import crypto from 'node:crypto';
-
-const ALGORITHM = 'aes-256-gcm';
-const IV_LENGTH = 12;
-const TAG_LENGTH = 16;
-
-export function encrypt(data, key) {
-  const iv = crypto.randomBytes(IV_LENGTH);
-  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
-  const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
-  const tag = cipher.getAuthTag();
-  return Buffer.concat([iv, tag, encrypted]);
-}
-
-export function decrypt(buffer, key) {
-  if (typeof buffer === 'string') buffer = Buffer.from(buffer, 'base64');
-  const iv = buffer.subarray(0, IV_LENGTH);
-  const tag = buffer.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
-  const encrypted = buffer.subarray(IV_LENGTH + TAG_LENGTH);
-  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
-  decipher.setAuthTag(tag);
-  return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
-}
-
-export function generateSessionKey() {
-  return crypto.randomBytes(32);
-}
-
-export function deriveKey(authKey) {
-  return crypto.scryptSync(authKey, 'stonyx-sockets', 32);
-}

package/src/handler.js

@@ -1,3 +0,0 @@
-export default class Handler {
-  static skipAuth = false;
-}

package/src/main.js

@@ -1,19 +0,0 @@
-export { default as SocketServer } from './server.js';
-export { default as SocketClient } from './client.js';
-export { default as Handler } from './handler.js';
-
-export default class Sockets {
-  constructor() {
-    if (Sockets.instance) return Sockets.instance;
-    Sockets.instance = this;
-  }
-
-  async init() {
-    // Handler discovery is deferred to SocketServer.init() / SocketClient.init()
-    // This entry point satisfies Stonyx module auto-initialization
-  }
-
-  reset() {
-    Sockets.instance = null;
-  }
-}

package/src/server.js

@@ -1,186 +0,0 @@
-import { WebSocketServer } from 'ws';
-import config from 'stonyx/config';
-import log from 'stonyx/log';
-import { forEachFileImport } from '@stonyx/utils/file';
-import { encrypt, decrypt, deriveKey, generateSessionKey } from './encryption.js';
-
-let clientId = 0;
-
-export default class SocketServer {
-  clientMap = new Map();
-  handlers = {};
-
-  constructor() {
-    if (SocketServer.instance) return SocketServer.instance;
-    SocketServer.instance = this;
-  }
-
-  async init() {
-    await this.discoverHandlers();
-    this.validateAuthHandler();
-
-    const { port, encryption, authKey } = config.sockets;
-    this.encryptionEnabled = encryption === 'true' || encryption === true;
-
-    if (this.encryptionEnabled) {
-      this.globalKey = deriveKey(authKey);
-    }
-
-    const wss = new WebSocketServer({ port });
-    this.wss = wss;
-
-    log.socket(`WebSocket server is listening on port ${port}`);
-
-    wss.on('connection', (client, request) => {
-      const { remoteAddress } = request.socket;
-      log.socket(`[${remoteAddress}] Client connected`);
-      client.id = ++clientId;
-      client.ip = remoteAddress;
-      client.__authenticated = false;
-      this.prepareSend(client);
-
-      client.on('message', payload => this.onMessage(payload, client));
-      client.on('close', () => this.handleDisconnect(client));
-    });
-  }
-
-  async discoverHandlers() {
-    const { handlerDir } = config.sockets;
-
-    await forEachFileImport(handlerDir, (HandlerClass, { name }) => {
-      const instance = new HandlerClass();
-
-      if (typeof instance.server === 'function') {
-        instance._serverRef = this;
-        this.handlers[name] = instance;
-      }
-    }, { ignoreAccessFailure: true });
-  }
-
-  validateAuthHandler() {
-    if (!this.handlers.auth) {
-      throw new Error('SocketServer requires an "auth" handler with a server() method');
-    }
-  }
-
-  async onMessage(payload, client) {
-    try {
-      let parsed;
-
-      if (this.encryptionEnabled) {
-        const key = client.__authenticated ? client.__sessionKey : this.globalKey;
-        const raw = Buffer.isBuffer(payload) ? payload : Buffer.from(payload);
-        parsed = JSON.parse(decrypt(raw, key));
-      } else {
-        parsed = JSON.parse(payload);
-      }
-
-      const { request, data } = parsed;
-
-      // Built-in heartbeat — no handler needed
-      if (request === 'heartBeat') {
-        if (client.__authenticated) client.send({ request: 'heartBeat', response: true });
-        return;
-      }
-
-      const handler = this.handlers[request];
-
-      if (!handler) {
-        log.socket(`Invalid request received: ${request}`);
-        return;
-      }
-
-      if (request !== 'auth' && !handler.constructor.skipAuth && !client.__authenticated) {
-        log.socket(`Rejected unauthenticated request: ${request}`);
-        client.close();
-        return;
-      }
-
-      const response = await handler.server(data, client);
-      if (response === undefined || response === null) return;
-
-      if (request === 'auth' && response) {
-        client.__authenticated = true;
-
-        if (this.encryptionEnabled) {
-          const sessionKey = generateSessionKey();
-          client.__sessionKey = sessionKey;
-          client.send({ request, response, sessionKey: sessionKey.toString('base64') }, this.globalKey);
-        } else {
-          client.send({ request, response });
-        }
-        return;
-      }
-
-      client.send({ request, response });
-    } catch (error) {
-      log.socket(`Invalid payload from client`);
-      if (config.debug) console.error(error);
-      client.close();
-    }
-  }
-
-  prepareSend(client) {
-    const { send: socketSend } = client;
-    const server = this;
-
-    client.send = (payload, keyOverride) => {
-      if (server.encryptionEnabled) {
-        const key = keyOverride || client.__sessionKey;
-        const data = encrypt(JSON.stringify(payload), key);
-        socketSend.bind(client)(data);
-      } else {
-        socketSend.bind(client)(JSON.stringify(payload));
-      }
-    };
-  }
-
-  handleDisconnect(client) {
-    const { ip } = client;
-    log.socket(`[${ip}] Client disconnected`);
-    this.clientMap.delete(client.id);
-    this.onClientDisconnect?.(client);
-  }
-
-  sendTo(clientId, request, response) {
-    const client = this.clientMap.get(clientId);
-    if (!client) return;
-    client.send({ request, response });
-  }
-
-  sendToByMeta(key, value, request, response) {
-    for (const [, client] of this.clientMap) {
-      if (client.meta?.[key] === value && client.__authenticated) {
-        client.send({ request, response });
-        return true;
-      }
-    }
-    return false;
-  }
-
-  broadcast(request, response) {
-    for (const [, client] of this.clientMap) {
-      if (client.__authenticated) {
-        client.send({ request, response });
-      }
-    }
-  }
-
-  close() {
-    if (this.wss) {
-      for (const client of this.wss.clients) {
-        client.terminate();
-      }
-      this.wss.close();
-      this.wss = null;
-    }
-  }
-
-  reset() {
-    this.close();
-    this.clientMap.clear();
-    this.handlers = {};
-    clientId = 0;
-    SocketServer.instance = null;
-  }
-}