@fluxerjs/ws 1.0.2

package/dist/index.d.mts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'events';
+import { GatewaySendPayload } from '@fluxerjs/types';
+
+type WebSocketLike = {
+    send(data: string | ArrayBufferLike): void;
+    close(code?: number): void;
+    readyState: number;
+    addEventListener?(type: string, listener: (e: unknown) => void): void;
+    on?(event: string, cb: (data?: unknown) => void): void;
+};
+type WebSocketConstructor$1 = new (url: string) => WebSocketLike;
+interface WebSocketShardOptions {
+    url: string;
+    token: string;
+    intents: number;
+    shardId: number;
+    numShards: number;
+    /** Gateway API version (e.g. "1" for Fluxer). Defaults to "1" when not set. */
+    version?: string;
+    WebSocket?: WebSocketConstructor$1;
+}
+declare class WebSocketShard extends EventEmitter {
+    private ws;
+    private readonly options;
+    private heartbeatInterval;
+    private heartbeatAt;
+    /** True until we send a heartbeat; then false until we get HeartbeatAck. Avoids closing before first heartbeat. */
+    private lastHeartbeatAck;
+    private sessionId;
+    private seq;
+    private destroying;
+    private readonly url;
+    private readonly WS;
+    /** Current reconnect delay in ms; resets on successful connect. */
+    private reconnectDelayMs;
+    private reconnectTimeout;
+    constructor(options: WebSocketShardOptions);
+    get id(): number;
+    get status(): number;
+    connect(): void;
+    private debug;
+    private handlePayload;
+    private handleHello;
+    private startHeartbeat;
+    private stopHeartbeat;
+    send(payload: GatewaySendPayload): void;
+    destroy(): void;
+}
+
+type WebSocketConstructor = WebSocketConstructor$1;
+interface WebSocketManagerOptions {
+    token: string;
+    intents: number;
+    rest: {
+        get: (route: string) => Promise<unknown>;
+    };
+    version?: string;
+    shardIds?: number[];
+    shardCount?: number;
+    WebSocket?: WebSocketConstructor;
+}
+declare class WebSocketManager extends EventEmitter {
+    private readonly options;
+    private shards;
+    private gatewayUrl;
+    private shardCount;
+    constructor(options: WebSocketManagerOptions);
+    connect(): Promise<void>;
+    send(shardId: number, payload: Parameters<WebSocketShard['send']>[0]): void;
+    destroy(): void;
+    getShardCount(): number;
+}
+
+/**
+ * Returns the WebSocket implementation to use.
+ * Uses global WebSocket (browser, Node 22+, Deno, Bun) when available;
+ * otherwise uses the bundled `ws` package (Node 18/20).
+ * Users never need to install ws themselves.
+ */
+type WSConstructor = new (url: string) => {
+    send(data: string | ArrayBufferLike): void;
+    close(code?: number): void;
+    readyState: number;
+    addEventListener?(type: string, listener: (e: unknown) => void): void;
+    on?(event: string, cb: (data?: unknown) => void): void;
+};
+declare function getDefaultWebSocketSync(): WSConstructor;
+/** Async version for ESM where we need dynamic import('ws'). */
+declare function getDefaultWebSocket(): Promise<WSConstructor>;
+
+/** Fluxer gateway close codes (aligned with docs / fluxerapp/fluxer). */
+declare const GatewayCloseCodes: {
+    readonly Normal: 1000;
+    readonly GoingAway: 1001;
+    readonly ProtocolError: 1002;
+    readonly UnsupportedData: 1003;
+    readonly NoStatusReceived: 1005;
+    readonly AbnormalClosure: 1006;
+    readonly UnknownError: 4000;
+    readonly UnknownOpcode: 4001;
+    readonly DecodeError: 4002;
+    readonly NotAuthenticated: 4003;
+    readonly AuthenticationFailed: 4004;
+    readonly AlreadyAuthenticated: 4005;
+    readonly InvalidSeq: 4007;
+    readonly RateLimited: 4008;
+    readonly SessionTimeout: 4009;
+    readonly InvalidShard: 4010;
+    readonly ShardingRequired: 4011;
+    readonly InvalidAPIVersion: 4012;
+};
+
+export { GatewayCloseCodes, type WebSocketConstructor, type WebSocketLike, WebSocketManager, type WebSocketManagerOptions, WebSocketShard, type WebSocketShardOptions, getDefaultWebSocket, getDefaultWebSocketSync };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { EventEmitter } from 'events';
+import { GatewaySendPayload } from '@fluxerjs/types';
+
+type WebSocketLike = {
+    send(data: string | ArrayBufferLike): void;
+    close(code?: number): void;
+    readyState: number;
+    addEventListener?(type: string, listener: (e: unknown) => void): void;
+    on?(event: string, cb: (data?: unknown) => void): void;
+};
+type WebSocketConstructor$1 = new (url: string) => WebSocketLike;
+interface WebSocketShardOptions {
+    url: string;
+    token: string;
+    intents: number;
+    shardId: number;
+    numShards: number;
+    /** Gateway API version (e.g. "1" for Fluxer). Defaults to "1" when not set. */
+    version?: string;
+    WebSocket?: WebSocketConstructor$1;
+}
+declare class WebSocketShard extends EventEmitter {
+    private ws;
+    private readonly options;
+    private heartbeatInterval;
+    private heartbeatAt;
+    /** True until we send a heartbeat; then false until we get HeartbeatAck. Avoids closing before first heartbeat. */
+    private lastHeartbeatAck;
+    private sessionId;
+    private seq;
+    private destroying;
+    private readonly url;
+    private readonly WS;
+    /** Current reconnect delay in ms; resets on successful connect. */
+    private reconnectDelayMs;
+    private reconnectTimeout;
+    constructor(options: WebSocketShardOptions);
+    get id(): number;
+    get status(): number;
+    connect(): void;
+    private debug;
+    private handlePayload;
+    private handleHello;
+    private startHeartbeat;
+    private stopHeartbeat;
+    send(payload: GatewaySendPayload): void;
+    destroy(): void;
+}
+
+type WebSocketConstructor = WebSocketConstructor$1;
+interface WebSocketManagerOptions {
+    token: string;
+    intents: number;
+    rest: {
+        get: (route: string) => Promise<unknown>;
+    };
+    version?: string;
+    shardIds?: number[];
+    shardCount?: number;
+    WebSocket?: WebSocketConstructor;
+}
+declare class WebSocketManager extends EventEmitter {
+    private readonly options;
+    private shards;
+    private gatewayUrl;
+    private shardCount;
+    constructor(options: WebSocketManagerOptions);
+    connect(): Promise<void>;
+    send(shardId: number, payload: Parameters<WebSocketShard['send']>[0]): void;
+    destroy(): void;
+    getShardCount(): number;
+}
+
+/**
+ * Returns the WebSocket implementation to use.
+ * Uses global WebSocket (browser, Node 22+, Deno, Bun) when available;
+ * otherwise uses the bundled `ws` package (Node 18/20).
+ * Users never need to install ws themselves.
+ */
+type WSConstructor = new (url: string) => {
+    send(data: string | ArrayBufferLike): void;
+    close(code?: number): void;
+    readyState: number;
+    addEventListener?(type: string, listener: (e: unknown) => void): void;
+    on?(event: string, cb: (data?: unknown) => void): void;
+};
+declare function getDefaultWebSocketSync(): WSConstructor;
+/** Async version for ESM where we need dynamic import('ws'). */
+declare function getDefaultWebSocket(): Promise<WSConstructor>;
+
+/** Fluxer gateway close codes (aligned with docs / fluxerapp/fluxer). */
+declare const GatewayCloseCodes: {
+    readonly Normal: 1000;
+    readonly GoingAway: 1001;
+    readonly ProtocolError: 1002;
+    readonly UnsupportedData: 1003;
+    readonly NoStatusReceived: 1005;
+    readonly AbnormalClosure: 1006;
+    readonly UnknownError: 4000;
+    readonly UnknownOpcode: 4001;
+    readonly DecodeError: 4002;
+    readonly NotAuthenticated: 4003;
+    readonly AuthenticationFailed: 4004;
+    readonly AlreadyAuthenticated: 4005;
+    readonly InvalidSeq: 4007;
+    readonly RateLimited: 4008;
+    readonly SessionTimeout: 4009;
+    readonly InvalidShard: 4010;
+    readonly ShardingRequired: 4011;
+    readonly InvalidAPIVersion: 4012;
+};
+
+export { GatewayCloseCodes, type WebSocketConstructor, type WebSocketLike, WebSocketManager, type WebSocketManagerOptions, WebSocketShard, type WebSocketShardOptions, getDefaultWebSocket, getDefaultWebSocketSync };

package/dist/index.js

@@ -0,0 +1,414 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  GatewayCloseCodes: () => GatewayCloseCodes,
+  WebSocketManager: () => WebSocketManager,
+  WebSocketShard: () => WebSocketShard,
+  getDefaultWebSocket: () => getDefaultWebSocket,
+  getDefaultWebSocketSync: () => getDefaultWebSocketSync
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/WebSocketManager.ts
+var import_events2 = require("events");
+
+// src/WebSocketShard.ts
+var import_events = require("events");
+var import_types = require("@fluxerjs/types");
+
+// src/utils/getWebSocket.ts
+var cached = null;
+function getDefaultWebSocketSync() {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== "undefined") {
+    cached = globalThis.WebSocket;
+    return cached;
+  }
+  if (typeof require === "function") {
+    try {
+      cached = require("ws");
+      return cached;
+    } catch {
+    }
+  }
+  throw new Error(
+    'No WebSocket implementation. Use Node 22+, or run with CommonJS. The "ws" package is bundled with @fluxerjs/ws.'
+  );
+}
+async function getDefaultWebSocket() {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== "undefined") {
+    cached = globalThis.WebSocket;
+    return cached;
+  }
+  if (typeof require === "function") {
+    try {
+      cached = require("ws");
+      return cached;
+    } catch {
+    }
+  }
+  const mod = await import("ws");
+  cached = mod.default ?? mod;
+  return cached;
+}
+
+// src/WebSocketShard.ts
+var RECONNECT_INITIAL_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var WebSocketShard = class extends import_events.EventEmitter {
+  ws = null;
+  options;
+  heartbeatInterval = null;
+  heartbeatAt = 0;
+  /** True until we send a heartbeat; then false until we get HeartbeatAck. Avoids closing before first heartbeat. */
+  lastHeartbeatAck = true;
+  sessionId = null;
+  seq = null;
+  destroying = false;
+  url;
+  WS;
+  /** Current reconnect delay in ms; resets on successful connect. */
+  reconnectDelayMs = RECONNECT_INITIAL_MS;
+  reconnectTimeout = null;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.WS = options.WebSocket ?? getDefaultWebSocketSync();
+    const version = options.version ?? "1";
+    const params = new URLSearchParams({ v: version, encoding: "json" });
+    this.url = `${options.url}?${params}`;
+  }
+  get id() {
+    return this.options.shardId;
+  }
+  get status() {
+    if (!this.ws) return 0;
+    switch (this.ws.readyState) {
+      case 0:
+        return 1;
+      // Connecting
+      case 1:
+        return 2;
+      // Ready
+      case 2:
+        return 3;
+      // Closing
+      case 3:
+        return 0;
+      default:
+        return 0;
+    }
+  }
+  connect() {
+    if (this.ws?.readyState === 1) return;
+    this.destroying = false;
+    this.debug("Connecting");
+    const ws = new this.WS(this.url);
+    this.ws = ws;
+    const handleMessage = (data) => {
+      try {
+        const str = typeof data === "string" ? data : data.toString();
+        this.handlePayload(JSON.parse(str));
+      } catch (err) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+    const scheduleReconnect = () => {
+      if (this.destroying) return;
+      const delay = Math.min(
+        RECONNECT_MAX_MS,
+        this.reconnectDelayMs * (0.75 + Math.random() * 0.5)
+      );
+      this.reconnectDelayMs = Math.min(RECONNECT_MAX_MS, this.reconnectDelayMs * 1.5);
+      this.debug(`Reconnecting in ${Math.round(delay)}ms\u2026`);
+      this.reconnectTimeout = setTimeout(() => {
+        this.reconnectTimeout = null;
+        this.connect();
+      }, delay);
+    };
+    const handleClose = (code) => {
+      this.ws = null;
+      this.stopHeartbeat();
+      this.emit("close", code);
+      this.debug(`Closed: ${code}`);
+      if (!this.destroying && shouldReconnectOnClose(code)) {
+        scheduleReconnect();
+      }
+    };
+    const handleError = (err) => {
+      const error = err instanceof Error ? err : new Error("WebSocket error");
+      this.emit("error", error);
+      if (!this.destroying && this.ws) {
+        this.ws = null;
+        this.stopHeartbeat();
+        this.debug("Connection error; will retry\u2026");
+        scheduleReconnect();
+      }
+    };
+    const handleOpen = () => {
+      this.debug("Socket open");
+      this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+    };
+    if (typeof ws.addEventListener === "function") {
+      ws.addEventListener("open", handleOpen);
+      ws.addEventListener("message", (e) => handleMessage(e.data));
+      ws.addEventListener("close", (e) => handleClose(e.code));
+      ws.addEventListener("error", () => handleError(new Error("WebSocket error")));
+    } else if (typeof ws.on === "function") {
+      ws.on("open", handleOpen);
+      ws.on("message", (d) => handleMessage(d));
+      ws.on("close", (code) => handleClose(code ?? 1006));
+      ws.on("error", (err) => handleError(err));
+    }
+  }
+  debug(message) {
+    this.emit("debug", `[Shard ${this.id}] ${message}`);
+  }
+  handlePayload(payload) {
+    switch (payload.op) {
+      case import_types.GatewayOpcodes.Hello:
+        this.handleHello(payload.d);
+        break;
+      case import_types.GatewayOpcodes.HeartbeatAck:
+        this.lastHeartbeatAck = true;
+        break;
+      case import_types.GatewayOpcodes.Dispatch:
+        if (payload.t === "READY") {
+          const d = payload.d;
+          this.sessionId = d.session_id;
+          this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+          this.emit("ready", payload.d);
+        } else if (payload.t === "RESUMED") {
+          this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+          this.emit("resumed");
+        }
+        if (payload.s !== void 0) this.seq = payload.s;
+        this.emit("dispatch", payload);
+        break;
+      case import_types.GatewayOpcodes.InvalidSession:
+        this.debug(`Invalid session (d=${payload.d}), reconnecting`);
+        this.sessionId = null;
+        this.seq = null;
+        setTimeout(() => this.connect(), 1e3 + Math.random() * 4e3);
+        break;
+      case import_types.GatewayOpcodes.Reconnect:
+        this.debug("Reconnect requested");
+        this.ws?.close(1e3);
+        setTimeout(() => this.connect(), 100);
+        break;
+      default:
+        break;
+    }
+  }
+  handleHello(data) {
+    const jitter = Math.random() * data.heartbeat_interval;
+    this.heartbeatAt = Date.now() + jitter;
+    this.startHeartbeat(data.heartbeat_interval);
+    if (this.sessionId && this.seq !== null) {
+      this.send({
+        op: import_types.GatewayOpcodes.Resume,
+        d: {
+          token: this.options.token,
+          session_id: this.sessionId,
+          seq: this.seq
+        }
+      });
+    } else {
+      this.send({
+        op: import_types.GatewayOpcodes.Identify,
+        d: {
+          token: this.options.token,
+          intents: this.options.intents,
+          properties: {
+            os: process.platform ?? "unknown",
+            browser: "fluxer-core.js",
+            device: "fluxer-core.js"
+          }
+        }
+      });
+    }
+  }
+  startHeartbeat(interval) {
+    this.stopHeartbeat();
+    this.lastHeartbeatAck = true;
+    this.heartbeatInterval = setInterval(() => {
+      if (!this.lastHeartbeatAck && this.seq !== null) {
+        this.ws?.close(1e3);
+        return;
+      }
+      this.lastHeartbeatAck = false;
+      this.send({ op: import_types.GatewayOpcodes.Heartbeat, d: this.seq ?? null });
+    }, interval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+  send(payload) {
+    if (this.ws?.readyState !== 1) return;
+    this.ws.send(JSON.stringify(payload));
+  }
+  destroy() {
+    this.destroying = true;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.stopHeartbeat();
+    this.ws?.close(1e3);
+    this.ws = null;
+    this.sessionId = null;
+    this.seq = null;
+  }
+};
+function shouldReconnectOnClose(code) {
+  switch (code) {
+    case 1e3:
+    // Normal Closure (server may close with this to ask for reconnect)
+    case 1001:
+    // Going Away
+    case 1011:
+      return true;
+    case 4e3:
+    // Unknown error
+    case 4007:
+    // Invalid seq
+    case 4009:
+    // Session timeout
+    case 4010:
+    // Invalid shard
+    case 4011:
+    // Sharding required
+    case 4012:
+      return true;
+    default:
+      return false;
+  }
+}
+
+// src/WebSocketManager.ts
+var WebSocketManager = class extends import_events2.EventEmitter {
+  options;
+  shards = /* @__PURE__ */ new Map();
+  gatewayUrl = null;
+  shardCount = 1;
+  constructor(options) {
+    super();
+    this.options = options;
+  }
+  async connect() {
+    let WS = this.options.WebSocket;
+    if (!WS) {
+      try {
+        WS = await getDefaultWebSocket();
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        this.emit("error", { shardId: -1, error: e });
+        throw e;
+      }
+    }
+    try {
+      const gateway = await this.options.rest.get("/gateway/bot");
+      this.gatewayUrl = gateway.url;
+      this.shardCount = this.options.shardCount ?? gateway.shards;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", { shardId: -1, error: e });
+      throw e;
+    }
+    const ids = this.options.shardIds ?? [...Array(this.shardCount).keys()];
+    const version = this.options.version ?? "1";
+    for (const id of ids) {
+      const shard = new WebSocketShard({
+        url: this.gatewayUrl,
+        token: this.options.token,
+        intents: this.options.intents,
+        shardId: id,
+        numShards: this.shardCount,
+        version,
+        WebSocket: WS
+      });
+      shard.on("ready", (data) => this.emit("ready", { shardId: id, data }));
+      shard.on("resumed", () => this.emit("resumed", id));
+      shard.on("dispatch", (payload) => this.emit("dispatch", { shardId: id, payload }));
+      shard.on("close", (code) => this.emit("close", { shardId: id, code }));
+      shard.on("error", (err) => this.emit("error", { shardId: id, error: err }));
+      shard.on("debug", (msg) => this.emit("debug", msg));
+      this.shards.set(id, shard);
+      shard.connect();
+    }
+  }
+  send(shardId, payload) {
+    this.shards.get(shardId)?.send(payload);
+  }
+  destroy() {
+    for (const shard of this.shards.values()) shard.destroy();
+    this.shards.clear();
+    this.gatewayUrl = null;
+  }
+  getShardCount() {
+    return this.shardCount;
+  }
+};
+
+// src/utils/constants.ts
+var GatewayCloseCodes = {
+  Normal: 1e3,
+  GoingAway: 1001,
+  ProtocolError: 1002,
+  UnsupportedData: 1003,
+  NoStatusReceived: 1005,
+  AbnormalClosure: 1006,
+  UnknownError: 4e3,
+  UnknownOpcode: 4001,
+  DecodeError: 4002,
+  NotAuthenticated: 4003,
+  AuthenticationFailed: 4004,
+  AlreadyAuthenticated: 4005,
+  InvalidSeq: 4007,
+  RateLimited: 4008,
+  SessionTimeout: 4009,
+  InvalidShard: 4010,
+  ShardingRequired: 4011,
+  InvalidAPIVersion: 4012
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GatewayCloseCodes,
+  WebSocketManager,
+  WebSocketShard,
+  getDefaultWebSocket,
+  getDefaultWebSocketSync
+});

package/dist/index.mjs

@@ -0,0 +1,380 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/WebSocketManager.ts
+import { EventEmitter as EventEmitter2 } from "events";
+
+// src/WebSocketShard.ts
+import { EventEmitter } from "events";
+import { GatewayOpcodes } from "@fluxerjs/types";
+
+// src/utils/getWebSocket.ts
+var cached = null;
+function getDefaultWebSocketSync() {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== "undefined") {
+    cached = globalThis.WebSocket;
+    return cached;
+  }
+  if (typeof __require === "function") {
+    try {
+      cached = __require("ws");
+      return cached;
+    } catch {
+    }
+  }
+  throw new Error(
+    'No WebSocket implementation. Use Node 22+, or run with CommonJS. The "ws" package is bundled with @fluxerjs/ws.'
+  );
+}
+async function getDefaultWebSocket() {
+  if (cached) return cached;
+  if (typeof globalThis.WebSocket !== "undefined") {
+    cached = globalThis.WebSocket;
+    return cached;
+  }
+  if (typeof __require === "function") {
+    try {
+      cached = __require("ws");
+      return cached;
+    } catch {
+    }
+  }
+  const mod = await import("ws");
+  cached = mod.default ?? mod;
+  return cached;
+}
+
+// src/WebSocketShard.ts
+var RECONNECT_INITIAL_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var WebSocketShard = class extends EventEmitter {
+  ws = null;
+  options;
+  heartbeatInterval = null;
+  heartbeatAt = 0;
+  /** True until we send a heartbeat; then false until we get HeartbeatAck. Avoids closing before first heartbeat. */
+  lastHeartbeatAck = true;
+  sessionId = null;
+  seq = null;
+  destroying = false;
+  url;
+  WS;
+  /** Current reconnect delay in ms; resets on successful connect. */
+  reconnectDelayMs = RECONNECT_INITIAL_MS;
+  reconnectTimeout = null;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.WS = options.WebSocket ?? getDefaultWebSocketSync();
+    const version = options.version ?? "1";
+    const params = new URLSearchParams({ v: version, encoding: "json" });
+    this.url = `${options.url}?${params}`;
+  }
+  get id() {
+    return this.options.shardId;
+  }
+  get status() {
+    if (!this.ws) return 0;
+    switch (this.ws.readyState) {
+      case 0:
+        return 1;
+      // Connecting
+      case 1:
+        return 2;
+      // Ready
+      case 2:
+        return 3;
+      // Closing
+      case 3:
+        return 0;
+      default:
+        return 0;
+    }
+  }
+  connect() {
+    if (this.ws?.readyState === 1) return;
+    this.destroying = false;
+    this.debug("Connecting");
+    const ws = new this.WS(this.url);
+    this.ws = ws;
+    const handleMessage = (data) => {
+      try {
+        const str = typeof data === "string" ? data : data.toString();
+        this.handlePayload(JSON.parse(str));
+      } catch (err) {
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+    const scheduleReconnect = () => {
+      if (this.destroying) return;
+      const delay = Math.min(
+        RECONNECT_MAX_MS,
+        this.reconnectDelayMs * (0.75 + Math.random() * 0.5)
+      );
+      this.reconnectDelayMs = Math.min(RECONNECT_MAX_MS, this.reconnectDelayMs * 1.5);
+      this.debug(`Reconnecting in ${Math.round(delay)}ms\u2026`);
+      this.reconnectTimeout = setTimeout(() => {
+        this.reconnectTimeout = null;
+        this.connect();
+      }, delay);
+    };
+    const handleClose = (code) => {
+      this.ws = null;
+      this.stopHeartbeat();
+      this.emit("close", code);
+      this.debug(`Closed: ${code}`);
+      if (!this.destroying && shouldReconnectOnClose(code)) {
+        scheduleReconnect();
+      }
+    };
+    const handleError = (err) => {
+      const error = err instanceof Error ? err : new Error("WebSocket error");
+      this.emit("error", error);
+      if (!this.destroying && this.ws) {
+        this.ws = null;
+        this.stopHeartbeat();
+        this.debug("Connection error; will retry\u2026");
+        scheduleReconnect();
+      }
+    };
+    const handleOpen = () => {
+      this.debug("Socket open");
+      this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+    };
+    if (typeof ws.addEventListener === "function") {
+      ws.addEventListener("open", handleOpen);
+      ws.addEventListener("message", (e) => handleMessage(e.data));
+      ws.addEventListener("close", (e) => handleClose(e.code));
+      ws.addEventListener("error", () => handleError(new Error("WebSocket error")));
+    } else if (typeof ws.on === "function") {
+      ws.on("open", handleOpen);
+      ws.on("message", (d) => handleMessage(d));
+      ws.on("close", (code) => handleClose(code ?? 1006));
+      ws.on("error", (err) => handleError(err));
+    }
+  }
+  debug(message) {
+    this.emit("debug", `[Shard ${this.id}] ${message}`);
+  }
+  handlePayload(payload) {
+    switch (payload.op) {
+      case GatewayOpcodes.Hello:
+        this.handleHello(payload.d);
+        break;
+      case GatewayOpcodes.HeartbeatAck:
+        this.lastHeartbeatAck = true;
+        break;
+      case GatewayOpcodes.Dispatch:
+        if (payload.t === "READY") {
+          const d = payload.d;
+          this.sessionId = d.session_id;
+          this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+          this.emit("ready", payload.d);
+        } else if (payload.t === "RESUMED") {
+          this.reconnectDelayMs = RECONNECT_INITIAL_MS;
+          this.emit("resumed");
+        }
+        if (payload.s !== void 0) this.seq = payload.s;
+        this.emit("dispatch", payload);
+        break;
+      case GatewayOpcodes.InvalidSession:
+        this.debug(`Invalid session (d=${payload.d}), reconnecting`);
+        this.sessionId = null;
+        this.seq = null;
+        setTimeout(() => this.connect(), 1e3 + Math.random() * 4e3);
+        break;
+      case GatewayOpcodes.Reconnect:
+        this.debug("Reconnect requested");
+        this.ws?.close(1e3);
+        setTimeout(() => this.connect(), 100);
+        break;
+      default:
+        break;
+    }
+  }
+  handleHello(data) {
+    const jitter = Math.random() * data.heartbeat_interval;
+    this.heartbeatAt = Date.now() + jitter;
+    this.startHeartbeat(data.heartbeat_interval);
+    if (this.sessionId && this.seq !== null) {
+      this.send({
+        op: GatewayOpcodes.Resume,
+        d: {
+          token: this.options.token,
+          session_id: this.sessionId,
+          seq: this.seq
+        }
+      });
+    } else {
+      this.send({
+        op: GatewayOpcodes.Identify,
+        d: {
+          token: this.options.token,
+          intents: this.options.intents,
+          properties: {
+            os: process.platform ?? "unknown",
+            browser: "fluxer-core.js",
+            device: "fluxer-core.js"
+          }
+        }
+      });
+    }
+  }
+  startHeartbeat(interval) {
+    this.stopHeartbeat();
+    this.lastHeartbeatAck = true;
+    this.heartbeatInterval = setInterval(() => {
+      if (!this.lastHeartbeatAck && this.seq !== null) {
+        this.ws?.close(1e3);
+        return;
+      }
+      this.lastHeartbeatAck = false;
+      this.send({ op: GatewayOpcodes.Heartbeat, d: this.seq ?? null });
+    }, interval);
+  }
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+  send(payload) {
+    if (this.ws?.readyState !== 1) return;
+    this.ws.send(JSON.stringify(payload));
+  }
+  destroy() {
+    this.destroying = true;
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+    this.stopHeartbeat();
+    this.ws?.close(1e3);
+    this.ws = null;
+    this.sessionId = null;
+    this.seq = null;
+  }
+};
+function shouldReconnectOnClose(code) {
+  switch (code) {
+    case 1e3:
+    // Normal Closure (server may close with this to ask for reconnect)
+    case 1001:
+    // Going Away
+    case 1011:
+      return true;
+    case 4e3:
+    // Unknown error
+    case 4007:
+    // Invalid seq
+    case 4009:
+    // Session timeout
+    case 4010:
+    // Invalid shard
+    case 4011:
+    // Sharding required
+    case 4012:
+      return true;
+    default:
+      return false;
+  }
+}
+
+// src/WebSocketManager.ts
+var WebSocketManager = class extends EventEmitter2 {
+  options;
+  shards = /* @__PURE__ */ new Map();
+  gatewayUrl = null;
+  shardCount = 1;
+  constructor(options) {
+    super();
+    this.options = options;
+  }
+  async connect() {
+    let WS = this.options.WebSocket;
+    if (!WS) {
+      try {
+        WS = await getDefaultWebSocket();
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        this.emit("error", { shardId: -1, error: e });
+        throw e;
+      }
+    }
+    try {
+      const gateway = await this.options.rest.get("/gateway/bot");
+      this.gatewayUrl = gateway.url;
+      this.shardCount = this.options.shardCount ?? gateway.shards;
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      this.emit("error", { shardId: -1, error: e });
+      throw e;
+    }
+    const ids = this.options.shardIds ?? [...Array(this.shardCount).keys()];
+    const version = this.options.version ?? "1";
+    for (const id of ids) {
+      const shard = new WebSocketShard({
+        url: this.gatewayUrl,
+        token: this.options.token,
+        intents: this.options.intents,
+        shardId: id,
+        numShards: this.shardCount,
+        version,
+        WebSocket: WS
+      });
+      shard.on("ready", (data) => this.emit("ready", { shardId: id, data }));
+      shard.on("resumed", () => this.emit("resumed", id));
+      shard.on("dispatch", (payload) => this.emit("dispatch", { shardId: id, payload }));
+      shard.on("close", (code) => this.emit("close", { shardId: id, code }));
+      shard.on("error", (err) => this.emit("error", { shardId: id, error: err }));
+      shard.on("debug", (msg) => this.emit("debug", msg));
+      this.shards.set(id, shard);
+      shard.connect();
+    }
+  }
+  send(shardId, payload) {
+    this.shards.get(shardId)?.send(payload);
+  }
+  destroy() {
+    for (const shard of this.shards.values()) shard.destroy();
+    this.shards.clear();
+    this.gatewayUrl = null;
+  }
+  getShardCount() {
+    return this.shardCount;
+  }
+};
+
+// src/utils/constants.ts
+var GatewayCloseCodes = {
+  Normal: 1e3,
+  GoingAway: 1001,
+  ProtocolError: 1002,
+  UnsupportedData: 1003,
+  NoStatusReceived: 1005,
+  AbnormalClosure: 1006,
+  UnknownError: 4e3,
+  UnknownOpcode: 4001,
+  DecodeError: 4002,
+  NotAuthenticated: 4003,
+  AuthenticationFailed: 4004,
+  AlreadyAuthenticated: 4005,
+  InvalidSeq: 4007,
+  RateLimited: 4008,
+  SessionTimeout: 4009,
+  InvalidShard: 4010,
+  ShardingRequired: 4011,
+  InvalidAPIVersion: 4012
+};
+export {
+  GatewayCloseCodes,
+  WebSocketManager,
+  WebSocketShard,
+  getDefaultWebSocket,
+  getDefaultWebSocketSync
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fluxerjs/ws",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.2",
+  "description": "WebSocket manager for the Fluxer Gateway",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@fluxerjs/types": "1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "clean": "rm -rf dist"
+  }
+}