lunibee 0.1.6 → 0.1.8

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.6",
+  "version": "0.1.8",
   "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",
-    "prepare": "bun run build && bun run build:dts",
+    "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.6",
-    "@lunibee/collection": "^0.1.6",
-    "@lunibee/core": "^0.1.6",
-    "@lunibee/formatters": "^0.1.6",
-    "@lunibee/handlers": "^0.1.6",
-    "@lunibee/managers": "^0.1.6",
-    "@lunibee/rest": "^0.1.6",
-    "@lunibee/sharding": "^0.1.6",
-    "@lunibee/structures": "^0.1.6",
-    "@lunibee/types": "^0.1.6",
-    "@lunibee/utils": "^0.1.6",
-    "@lunibee/voice": "^0.1.6",
-    "@lunibee/ws": "^0.1.6"
+    "@lunibee/builders": "^0.1.8",
+    "@lunibee/collection": "^0.1.8",
+    "@lunibee/core": "^0.1.8",
+    "@lunibee/formatters": "^0.1.8",
+    "@lunibee/handlers": "^0.1.8",
+    "@lunibee/managers": "^0.1.8",
+    "@lunibee/rest": "^0.1.8",
+    "@lunibee/sharding": "^0.1.8",
+    "@lunibee/structures": "^0.1.8",
+    "@lunibee/types": "^0.1.8",
+    "@lunibee/utils": "^0.1.8",
+    "@lunibee/voice": "^0.1.8",
+    "@lunibee/ws": "^0.1.8"
   },
   "devDependencies": {
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.1",
+    "prettier": "^3.9.9",
     "typescript": "^7.0.2"
   },
   "engines": {

package/dist/structures/permissions.d.ts

@@ -1,73 +0,0 @@
-/** Permission bit values exposed by Discord. */
-export declare const Permissions: {
-    /** Create instant invite permission. */ readonly CreateInstantInvite: bigint;
-    /** Kick members permission. */ readonly KickMembers: bigint;
-    /** Ban members permission. */ readonly BanMembers: bigint;
-    /** Administrator permission. */ readonly Administrator: bigint;
-    /** Manage channels permission. */ readonly ManageChannels: bigint;
-    /** Manage guild permission. */ readonly ManageGuild: bigint;
-    /** Add reactions permission. */ readonly AddReactions: bigint;
-    /** View audit log permission. */ readonly ViewAuditLog: bigint;
-    /** Priority speaker permission. */ readonly PrioritySpeaker: bigint;
-    /** Stream permission. */ readonly Stream: bigint;
-    /** View channel permission. */ readonly ViewChannel: bigint;
-    /** Send messages permission. */ readonly SendMessages: bigint;
-    /** Send TTS messages permission. */ readonly SendTTSMessages: bigint;
-    /** Manage messages permission. */ readonly ManageMessages: bigint;
-    /** Embed links permission. */ readonly EmbedLinks: bigint;
-    /** Attach files permission. */ readonly AttachFiles: bigint;
-    /** Read message history permission. */ readonly ReadMessageHistory: bigint;
-    /** Mention everyone permission. */ readonly MentionEveryone: bigint;
-    /** Use external emojis permission. */ readonly UseExternalEmojis: bigint;
-    /** View guild insights permission. */ readonly ViewGuildInsights: bigint;
-    /** Connect permission. */ readonly Connect: bigint;
-    /** Speak permission. */ readonly Speak: bigint;
-    /** Mute members permission. */ readonly MuteMembers: bigint;
-    /** Deafen members permission. */ readonly DeafenMembers: bigint;
-    /** Move members permission. */ readonly MoveMembers: bigint;
-    /** Use voice activity detection permission. */ readonly UseVAD: bigint;
-    /** Change nickname permission. */ readonly ChangeNickname: bigint;
-    /** Manage nicknames permission. */ readonly ManageNicknames: bigint;
-    /** Manage roles permission. */ readonly ManageRoles: bigint;
-    /** Manage webhooks permission. */ readonly ManageWebhooks: bigint;
-    /** Manage guild expressions permission. */ readonly ManageGuildExpressions: bigint;
-    /** Use application commands permission. */ readonly UseApplicationCommands: bigint;
-    /** Request to speak permission. */ readonly RequestToSpeak: bigint;
-    /** Manage events permission. */ readonly ManageEvents: bigint;
-    /** Manage threads permission. */ readonly ManageThreads: bigint;
-    /** Create public threads permission. */ readonly CreatePublicThreads: bigint;
-    /** Create private threads permission. */ readonly CreatePrivateThreads: bigint;
-    /** Use external stickers permission. */ readonly UseExternalStickers: bigint;
-    /** Send messages in threads permission. */ readonly SendMessagesInThreads: bigint;
-    /** Use embedded activities permission. */ readonly UseEmbeddedActivities: bigint;
-    /** Moderate members permission. */ readonly ModerateMembers: bigint;
-    /** View creator monetization analytics permission. */ readonly ViewCreatorMonetizationAnalytics: bigint;
-    /** Use soundboard permission. */ readonly UseSoundboard: bigint;
-    /** Create guild expressions permission. */ readonly CreateGuildExpressions: bigint;
-    /** Create events permission. */ readonly CreateEvents: bigint;
-    /** Use external sounds permission. */ readonly UseExternalSounds: bigint;
-    /** Send voice messages permission. */ readonly SendVoiceMessages: bigint;
-    /** Send polls permission. */ readonly SendPolls: bigint;
-    /** Use external apps permission. */ readonly UseExternalApps: bigint;
-};
-/** Public permission resolvable. */
-export type PermissionResolvable = bigint | number | string | PermissionName | PermissionSet | PermissionResolvable[];
-/** Immutable Discord permission bitfield. */
-export declare class PermissionSet {
-    #private;
-    /** Permission bitfield. */ readonly bitfield: bigint;
-    /** Creates a permission set. @param value Initial permission bitfield. @throws {RangeError} If the value is negative. @throws {TypeError} If the value is not a valid integer. */
-    constructor(value?: PermissionResolvable);
-    /** Checks whether all supplied permissions are present. @param permissions Permission names or raw bits. @returns True when every requested permission is present. */ has(...permissions: PermissionResolvable[]): boolean;
-    /** Checks whether any supplied permission is present. @param permissions Permission names or raw bits. @returns True when at least one requested permission is present. */ any(...permissions: PermissionResolvable[]): boolean;
-    /** Returns a new set with permissions added. @param permissions Permission names or raw bits. @returns A new permission set. */ add(...permissions: PermissionResolvable[]): PermissionSet;
-    /** Returns a new set with permissions removed. @param permissions Permission names or raw bits. @returns A new permission set. */ remove(...permissions: PermissionResolvable[]): PermissionSet;
-    /** Checks equality with another permission set or raw bitfield. @param other Permission set or raw bitfield. @returns True when both values are equal. */ equals(other: PermissionSet | bigint | number | string): boolean;
-    /** Returns the decimal permission representation. @returns Decimal permission bitfield. */ toString(): string;
-    /** Returns known permission names contained in this set. @returns Names of all enabled known permissions. */ toArray(): PermissionName[];
-}
-/** Discord.js-compatible permission bitfield. */
-export declare class PermissionsBitField extends PermissionSet {
-    /** Creates a permissions bitfield. @param value Initial permission bitfield. */
-    constructor(value?: PermissionResolvable);
-}