@stonyx/sockets 0.1.1-alpha.7 → 0.1.1-alpha.9

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+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;
+    promise: {
+        resolve: () => void;
+        reject: (reason?: unknown) => void;
+    } | null;
+    onDisconnect: (() => 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(): void;
+    close(): void;
+    getReconnectDelay(): number;
+    reconnect(): Promise<void>;
+    reset(): void;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,174 @@
+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 {
+    static instance;
+    handlers = {};
+    reconnectCount = 0;
+    _intentionalClose = false;
+    socket = null;
+    sessionKey = null;
+    globalKey = null;
+    encryptionEnabled = false;
+    _heartBeatTimer = 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;
+        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, (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() {
+        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', () => this.onClose());
+            socket.on('error', () => {
+                log.socket(`Error connecting to socket server`);
+                reject('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;
+                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({ ...handler, client: this }, response);
+        }
+        catch {
+            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() {
+        const { heartBeatInterval } = config.sockets;
+        this._heartBeatTimer = setTimeout(() => this.heartBeat(), 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/dist/encryption.d.ts

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

package/dist/encryption.js

@@ -0,0 +1,27 @@
+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/dist/handler.d.ts

@@ -0,0 +1,5 @@
+export default class Handler {
+    static skipAuth: boolean;
+    server?: (data: unknown, client: unknown) => unknown | Promise<unknown>;
+    client?: (response: unknown) => void;
+}

package/{src → dist}/handler.js

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

package/dist/main.d.ts

@@ -0,0 +1,9 @@
+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;
+}

package/dist/main.js

@@ -0,0 +1,18 @@
+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;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,48 @@
+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) => 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): 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 {};

package/dist/server.js

@@ -0,0 +1,169 @@
+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 {
+    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() {
+        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', (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', () => this.handleDisconnect(client));
+        });
+    }
+    async discoverHandlers() {
+        const { handlerDir } = config.sockets;
+        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;
+                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];
+            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, ws) {
+        const socketSend = ws.send.bind(ws);
+        const server = this;
+        client.send = (payload, keyOverride) => {
+            if (server.encryptionEnabled) {
+                const key = keyOverride || client.__sessionKey;
+                const data = encrypt(JSON.stringify(payload), key);
+                socketSend(data);
+            }
+            else {
+                socketSend(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;
+    }
+}

package/package.json

@@ -4,21 +4,34 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.1.1-alpha.7",
+  "version": "0.1.1-alpha.9",
   "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",
@@ -43,10 +56,15 @@
   },
   "devDependencies": {
     "@stonyx/utils": "0.2.3-beta.7",
+    "@types/node": "^25.5.2",
+    "@types/ws": "^8.18.1",
     "qunit": "^2.24.1",
-    "sinon": "^21.0.0"
+    "sinon": "^21.0.0",
+    "typescript": "^5.8.3"
   },
   "scripts": {
-    "test": "stonyx test"
+    "build": "tsc",
+    "build:test": "tsc -p tsconfig.test.json",
+    "test": "pnpm build && pnpm build:test && stonyx test 'dist-test/test/**/*-test.js'"
   }
 }

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/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;
-  }
-}