lunibee 0.1.7 → 0.2.0

package/dist/ws/protocol.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Discord Gateway protocol: what a payload *means*.
+ *
+ * Pure translation from a received frame to an action, plus construction of
+ * the payloads Lunibee sends. It performs nothing: no socket, no timers, no
+ * session mutation, no event emission, no sending. The caller decides what to
+ * do with an action, which is what lets the whole protocol be tested without a
+ * connection.
+ */
+import type { GatewayPayload, GatewayPresence } from "@lunibee/types";
+import type { ResumeInfo } from "./session.js";
+/** Why a frame could not be understood. */
+export type ProtocolViolation = 
+/** The frame was not valid JSON. */
+"invalid-json"
+/** The frame decoded to something other than a payload object. */
+ | "invalid-payload"
+/** `HELLO` carried no usable heartbeat interval. */
+ | "invalid-hello";
+/** What a received frame means. */
+export type GatewayAction = 
+/** `op 10`: begin heartbeating and hand shake. */
+{
+    type: "hello";
+    heartbeatInterval: number;
+}
+/** `op 0`: an event. `event` is null only if Discord omitted `t`. */
+ | {
+    type: "dispatch";
+    event: string | null;
+    data: unknown;
+}
+/** `op 1`: Discord asks for a heartbeat now. */
+ | {
+    type: "heartbeat";
+}
+/** `op 11`: the last heartbeat was acknowledged. */
+ | {
+    type: "heartbeat-ack";
+    data: unknown;
+}
+/** `op 7`: Discord asks the client to reconnect. */
+ | {
+    type: "reconnect";
+}
+/** `op 9`: the session is gone. `resumable` decides RESUME vs IDENTIFY. */
+ | {
+    type: "invalid-session";
+    resumable: boolean;
+}
+/**
+ * An opcode this version does not handle.
+ *
+ * Ignored rather than treated as an error: Discord adds opcodes, and a
+ * client that fails on an unfamiliar one breaks itself on every addition.
+ */
+ | {
+    type: "unknown";
+    opcode: number;
+}
+/** The frame was malformed. Never silently swallowed. */
+ | {
+    type: "invalid";
+    violation: ProtocolViolation;
+    message: string;
+    cause?: unknown;
+};
+/** A classified frame: its sequence, if any, and what it means. */
+export interface ProtocolResult {
+    /**
+     * Sequence carried by the frame, or null when it carried none.
+     *
+     * Reported for every payload type, not just dispatches: recording it is
+     * the caller's decision, and the caller records before acting so a RESUME
+     * cannot be built from a sequence that was never seen.
+     */
+    sequence: number | null;
+    /** What the frame means. */
+    action: GatewayAction;
+}
+/**
+ * Classifies one received frame.
+ *
+ * @param raw The frame text, already decompressed by the transport.
+ */
+export declare function classifyFrame(raw: string): ProtocolResult;
+/** Classifies an already-parsed payload. */
+export declare function classifyPayload(payload: unknown): ProtocolResult;
+/** Identification properties sent with IDENTIFY. */
+export interface IdentifyProperties {
+    os?: string;
+    browser?: string;
+    device?: string;
+    [key: string]: unknown;
+}
+/** Everything IDENTIFY needs. */
+export interface IdentifyOptions {
+    token: string;
+    intents: number;
+    shardId: number;
+    shardCount: number;
+    properties?: IdentifyProperties;
+    presence?: GatewayPresence;
+}
+/** Builds an IDENTIFY payload. */
+export declare function identifyPayload(options: IdentifyOptions): GatewayPayload;
+/** Builds a RESUME payload from the session's resume material. */
+export declare function resumePayload(token: string, resume: ResumeInfo): GatewayPayload;
+/** Builds a heartbeat payload carrying the last sequence seen. */
+export declare function heartbeatPayload(sequence: number | null): GatewayPayload;

package/dist/ws/reconnect.d.ts

@@ -0,0 +1,108 @@
+/** What a closed connection should do next. */
+export type CloseAction = 
+/** Reconnect and RESUME the existing session. */
+"resume"
+/** Reconnect, but IDENTIFY afresh: the session cannot be resumed. */
+ | "identify"
+/** Do not reconnect; the condition will not fix itself. */
+ | "stop";
+/**
+ * Close codes that no reconnect can recover from: bad token, bad shard
+ * configuration, bad API version, or intents the application is not approved
+ * for. Retrying these hammers Discord with a request that cannot succeed.
+ */
+export declare const FATAL_CLOSE_CODES: readonly number[];
+/**
+ * Close codes that keep the connection recoverable but destroy the session, so
+ * the next connection must IDENTIFY rather than RESUME.
+ */
+export declare const IDENTIFY_CLOSE_CODES: readonly number[];
+/**
+ * Classifies a close code.
+ *
+ * Any code outside the two tables above is **reconnectable**: transport-level
+ * closes (`1006`), server restarts (`1001`), Discord's own `4000`, and the
+ * `1000` the Gateway itself sends after a non-resumable `op 9` all belong here.
+ * Whether that reconnect resumes or identifies is not a property of the code —
+ * it is whether a session survives, which is why `canResume` is a parameter
+ * rather than something this module works out for itself.
+ *
+ * @param code WebSocket close code.
+ * @param canResume Whether the session can still be resumed.
+ */
+export declare function classifyCloseCode(code: number, canResume: boolean): CloseAction;
+/** Why a reconnect was not scheduled. */
+export type ScheduleRefusal = 
+/** Automatic reconnect is disabled for this Gateway. */
+"disabled"
+/** A reconnect is already armed; a second would open a second socket. */
+ | "pending"
+/** The attempt budget is spent. */
+ | "exhausted";
+/** Outcome of asking for a reconnect. */
+export type ScheduleResult = {
+    scheduled: true;
+    delayMs: number;
+    attempt: number;
+} | {
+    scheduled: false;
+    reason: ScheduleRefusal;
+};
+/** Configuration for {@link GatewayReconnect}. */
+export interface ReconnectOptions {
+    /** Whether automatic reconnect is permitted at all. */
+    enabled: boolean;
+    /** Maximum consecutive attempts before giving up. */
+    maxAttempts: number;
+    /** Delay for the first attempt, doubled per attempt. */
+    baseDelay: number;
+    /** Ceiling for the backoff. */
+    maxDelay: number;
+    /** Randomness source for jitter; injected in tests. */
+    random?: () => number;
+}
+/** Reconnect scheduling, backoff and attempt coordination. */
+export declare class GatewayReconnect {
+    #private;
+    constructor(options: ReconnectOptions);
+    /** Whether automatic reconnect is permitted. */
+    get enabled(): boolean;
+    /** Consecutive attempts made since the last {@link reset}. */
+    get attempts(): number;
+    /** Whether a reconnect timer is currently armed. */
+    get pending(): boolean;
+    /** Whether the attempt budget is spent. */
+    get exhausted(): boolean;
+    /** Whether a connection attempt is currently in flight. */
+    get connecting(): boolean;
+    /** The in-flight attempt, or undefined when none is active. */
+    get attemptPromise(): Promise<void> | undefined;
+    /** Classifies a close code against this Gateway's policy. */
+    classifyClose(code: number, canResume: boolean): CloseAction;
+    /** Whether another reconnect is currently allowed. */
+    canReconnect(): boolean;
+    /**
+     * Arms a reconnect, unless one is already armed or no attempt is allowed.
+     *
+     * Refusing while `pending` is what keeps repeated closes from stacking
+     * timers: several closes in a row produce one reconnect, not several
+     * competing sockets.
+     */
+    schedule(run: () => void): ScheduleResult;
+    /** Cancels an armed reconnect. Safe to call when none is armed. */
+    cancel(): void;
+    /** Clears the attempt counter after a connection succeeds. */
+    reset(): void;
+    /**
+     * Coordinates one logical connection attempt.
+     *
+     * Callers that ask while an attempt is in flight join it instead of
+     * starting a second: three `connect()` calls produce one socket attempt and
+     * one shared promise.
+     *
+     * @param start Invoked exactly once, when this call begins a new attempt.
+     */
+    attempt(start: () => void): Promise<void>;
+    /** Settles the in-flight attempt, resolving it or rejecting with `error`. */
+    settle(error?: Error): void;
+}

package/dist/ws/send-budget.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Sliding-window budget for outgoing Gateway payloads.
+ *
+ * Discord allows 120 sends per 60 seconds. Application traffic is capped at
+ * 115 so the remaining headroom is reserved for privileged sends (heartbeats),
+ * which are still recorded so the true total stays under Discord's limit.
+ */
+export declare class SendBudget {
+    #private;
+    constructor(limit?: number, windowMs?: number);
+    /** Sends recorded within the current window. */
+    get used(): number;
+    /** Whether a send may go out now. Privileged sends always may. */
+    allows(privileged: boolean, now?: number): boolean;
+    /** Records a send that went out. */
+    record(now?: number): void;
+}

package/dist/ws/session.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Identity of a Discord Gateway session, and the decision of how to open the
+ * next connection with it.
+ *
+ * Deliberately owns nothing else: no socket, no timers, no opcode dispatch, no
+ * compression, no event emission. Those belong to the transport, heartbeat,
+ * reconnect and protocol seams. Keeping this object small is the point —
+ * session confusion is what produced both WS-001 and WS-005.
+ */
+/** Everything needed to send a RESUME, or nothing when one is impossible. */
+export interface ResumeInfo {
+    /** Discord's session identifier from READY. */ sessionId: string;
+    /** Last sequence number observed on this session. */ sequence: number;
+    /** Host READY nominated for resuming this session. */ resumeURL: string;
+}
+/**
+ * What the next connection must do.
+ *
+ * A discriminated union rather than a boolean plus three nullable fields: the
+ * caller cannot reach for a session id on the identify branch, so "resume with
+ * an undefined session" is not a state this codebase can express.
+ */
+export type HandshakeIntent = ({
+    type: "resume";
+} & ResumeInfo) | {
+    type: "identify";
+};
+/** Why a session was discarded. */
+export type InvalidationReason = 
+/** Discord sent `op 9` with `d: false`. */
+"invalid-session"
+/** The connection closed with a code that forbids resuming. */
+ | "session-timeout"
+/** Discarded by the owner without a protocol cause. */
+ | "explicit";
+/**
+ * Session state for one Gateway shard.
+ *
+ * **Generations.** Every connection attempt takes a token from
+ * {@link GatewaySession.beginConnection}, and every mutation must present it.
+ * A socket that has been superseded still holds the old token, so a late
+ * dispatch arriving on it cannot advance the new connection's sequence or
+ * overwrite its session id. Ownership is therefore structural rather than a
+ * chain of `if (this.#ws === ws)` checks at each call site.
+ */
+export declare class GatewaySession {
+    #private;
+    /** Why the last session was discarded, for diagnostics and reconnect policy. */
+    get lastInvalidation(): InvalidationReason | undefined;
+    /** Token of the current connection attempt; mutations must match it. */
+    get generation(): number;
+    /** Discord's session id, or undefined when no session is established. */
+    get sessionId(): string | undefined;
+    /** Host to reconnect to for a RESUME, or undefined when none is known. */
+    get resumeURL(): string | undefined;
+    /**
+     * Last sequence number seen, or null when none has been observed.
+     *
+     * Null, never zero, marks "nothing seen": sequence `0` is a legitimate
+     * value that must survive into a RESUME.
+     */
+    get sequence(): number | null;
+    /** Whether a RESUME is possible: a session, a resume host, and a sequence. */
+    get canResume(): boolean;
+    /**
+     * Opens a new connection generation and returns its token.
+     *
+     * The session itself is untouched: reconnecting to resume must keep the
+     * session id and sequence. Only ownership moves.
+     */
+    beginConnection(): number;
+    /** Whether `token` still owns this session. */
+    owns(token: number): boolean;
+    /**
+     * Records a sequence number from a payload.
+     * @returns Whether the token owned the session and the value was stored.
+     */
+    recordSequence(sequence: number, token: number): boolean;
+    /**
+     * Establishes the session from a READY payload.
+     * @returns Whether the token owned the session and READY was well-formed.
+     */
+    activate(payload: unknown, token: number): boolean;
+    /**
+     * Discards the session so the next connection must IDENTIFY.
+     *
+     * Resumable invalidation (`op 9` with `d: true`) is *not* an invalidation:
+     * the session survives and the caller simply reconnects, so this is only
+     * called for the non-resumable cases.
+     *
+     * @returns Whether the token owned the session and state was discarded.
+     */
+    invalidate(token: number, reason?: InvalidationReason): boolean;
+    /** Resume material, or undefined when a RESUME is not possible. */
+    resumeInfo(): ResumeInfo | undefined;
+    /** What the next connection must send: RESUME with material, or IDENTIFY. */
+    handshake(): HandshakeIntent;
+    /** Host the next connection should dial: the resume host, else `fallback`. */
+    connectURL(fallback: string): string;
+}

package/dist/ws/state.d.ts

@@ -0,0 +1,27 @@
+/** Gateway connection lifecycle states. */
+export declare enum GatewayState {
+    /** Initial connection state. */ Connect = "CONNECT",
+    /** Gateway HELLO received state. */ Hello = "HELLO",
+    /** IDENTIFY operation in progress. */ Identify = "IDENTIFY",
+    /** RESUME operation in progress. */ Resume = "RESUME",
+    /** Gateway READY state. */ Ready = "READY",
+    /** Gateway dispatch processing state. */ Dispatch = "DISPATCH",
+    /** Heartbeat processing state. */ Heartbeat = "HEARTBEAT",
+    /** Reconnect in progress. */ Reconnect = "RECONNECT",
+    /** Gateway is permanently closed. */ Closed = "CLOSED"
+}
+/**
+ * Discord.js-familiar alias for {@link GatewayState}.
+ *
+ * Discord.js exposes connection status via a `Status` enum. Lunibee's canonical
+ * name is {@link GatewayState}; this is an additive alias so `discord.js` users
+ * find the expected name. Note the *values* remain Lunibee's string states
+ * (e.g. `"READY"`), not Discord.js's numeric `Status` members — an intentional
+ * divergence documented in the compatibility matrix.
+ */
+export { GatewayState as Status };
+/** Gateway protocol error. */
+export declare class GatewayError extends Error {
+    /** Gateway close/error code. */ readonly code?: number;
+    /** Creates a Gateway error. @param message Error message. @param code Optional Gateway code. @param options Optional error metadata. */ constructor(message: string, code?: number, options?: ErrorOptions);
+}

package/dist/ws/transport.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The WebSocket a Gateway connection runs on.
+ *
+ * Owns socket construction, listener wiring, sending, closing, and replacement.
+ * It is infrastructure, not Discord semantics: it never inspects an opcode, a
+ * session, or a heartbeat. Frames go out as text and come back as text.
+ */
+import { type GatewayDecoder } from "./decoder.js";
+/** Creates the underlying socket. Injected to support alternative runtimes. */
+export type SocketFactory = (url: string) => WebSocket;
+/** Callbacks a transport reports to its owner. */
+export interface TransportHandlers {
+    /** The socket opened and is ready to send. */
+    onOpen: () => void;
+    /** A complete frame arrived, already decompressed. */
+    onFrame: (raw: string) => void;
+    /** The socket closed. */
+    onClose: (code: number, reason: string) => void;
+    /** A socket or decoding failure. Not a close on its own. */
+    onError: (error: Error) => void;
+}
+/** Outcome of opening a connection. */
+export type ConnectResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: Error;
+};
+/** Configuration for {@link WebSocketTransport}. */
+export interface TransportOptions {
+    /** Handlers for this transport's lifetime. */
+    handlers: TransportHandlers;
+    /** Frame decoder. Defaults to plain text, or zlib-stream when compressing. */
+    decoder?: GatewayDecoder;
+    /** Whether the connection negotiates `zlib-stream` compression. */
+    compress?: boolean;
+    /** Socket constructor. Defaults to the ambient `WebSocket`. */
+    createSocket?: SocketFactory;
+}
+/**
+ * A replaceable WebSocket connection.
+ *
+ * **Generations.** Each {@link connect} takes a generation, and every event is
+ * checked against the current one. A socket that has been replaced still holds
+ * its listeners and can still fire — especially a frame that finishes
+ * decompressing after the swap — and every such event is dropped. The owner
+ * therefore never has to ask "is this still my socket?".
+ */
+export declare class WebSocketTransport {
+    #private;
+    constructor(options: TransportOptions);
+    /** Whether a socket is open and able to send. */
+    get connected(): boolean;
+    /** Whether a socket is connecting or open, and therefore still in play. */
+    get live(): boolean;
+    /** Current connection generation; increments on every {@link connect}. */
+    get generation(): number;
+    /**
+     * Opens a connection, replacing any existing one.
+     *
+     * A construction failure is returned rather than reported through
+     * `onError`: the caller is mid-`connect` and must decide what the failure
+     * means for the attempt it is running.
+     */
+    connect(url: string): ConnectResult;
+    /**
+     * Writes a frame.
+     * @returns Whether it reached the socket.
+     */
+    send(data: string): boolean;
+    /** Closes the current socket, if any. Its `close` event still fires. */
+    close(code?: number, reason?: string): void;
+    /**
+     * Abandons the current socket without reporting its close.
+     *
+     * Used for a deliberate shutdown, where the owner has already decided the
+     * connection is over and must not be woken by the resulting close event.
+     */
+    destroy(code?: number, reason?: string): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lunibee",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "A lightweight, Bun-first Discord API library.",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,37 +88,38 @@
   "scripts": {
     "build": "bun scripts/build.ts",
     "build:dts": "bun scripts/build-dts.ts",
-    "format": "npx prettier --write packages/*/src/**/*.ts tests/**/*.ts",
+    "format": "prettier --write \"packages/*/src/**/*.ts\" \"tests/**/*.ts\"",
+    "format:check": "prettier --check \"packages/*/src/**/*.ts\" \"tests/**/*.ts\"",
     "check:deps": "bun scripts/check-dependency-graph.ts",
+    "audit:api": "bun scripts/api-audit.ts",
     "typecheck": "bunx tsc --noEmit --project tsconfig.json",
     "ci:install": "bun install --frozen-lockfile",
     "ci:deps": "bun run check:deps",
     "ci:typecheck": "bun run typecheck",
-    "ci:test": "bun test --coverage",
-    "ci": "bun run ci:deps && bun run ci:typecheck && bun run ci:test",
-    "bench": "bun benchmarks/full.ts",
-    "bench:compare": "bun benchmarks/compare.ts",
-    "bench:stress": "bun benchmarks/stress.ts",
+    "ci:test": "bun test --coverage && bun test ./packages/testing/src",
+    "ci": "bun run ci:deps && bun run audit:api && bun run format:check && bun run ci:typecheck && bun run ci:test",
+    "bench": "bun benchmarks/parity.ts",
     "build:all": "bun run build && bun run build:dts",
     "publish:all": "bun run scripts/publish.ts"
   },
   "dependencies": {
-    "@lunibee/builders": "^0.1.7",
-    "@lunibee/collection": "^0.1.7",
-    "@lunibee/core": "^0.1.7",
-    "@lunibee/formatters": "^0.1.7",
-    "@lunibee/handlers": "^0.1.7",
-    "@lunibee/managers": "^0.1.7",
-    "@lunibee/rest": "^0.1.7",
-    "@lunibee/sharding": "^0.1.7",
-    "@lunibee/structures": "^0.1.7",
-    "@lunibee/types": "^0.1.7",
-    "@lunibee/utils": "^0.1.7",
-    "@lunibee/voice": "^0.1.7",
-    "@lunibee/ws": "^0.1.7"
+    "@lunibee/builders": "^0.2.0",
+    "@lunibee/collection": "^0.2.0",
+    "@lunibee/core": "^0.2.0",
+    "@lunibee/formatters": "^0.2.0",
+    "@lunibee/handlers": "^0.2.0",
+    "@lunibee/managers": "^0.2.0",
+    "@lunibee/rest": "^0.2.0",
+    "@lunibee/sharding": "^0.2.0",
+    "@lunibee/structures": "^0.2.0",
+    "@lunibee/types": "^0.2.0",
+    "@lunibee/utils": "^0.2.0",
+    "@lunibee/voice": "^0.2.0",
+    "@lunibee/ws": "^0.2.0"
   },
   "devDependencies": {
     "@types/bun": "^1.4.1",
+    "prettier": "^3.9.9",
     "typescript": "^7.0.2"
   },
   "engines": {