lunibee 0.1.6 → 0.1.8

package/dist/rest/scheduler.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Serialises work per rate-limit bucket.
+ *
+ * One request per bucket key is in flight at a time, so each request sees the
+ * limit state its predecessor's response wrote. The queue slot is released on
+ * every exit path — including an abort raised while still waiting — because a
+ * slot that is never released wedges its bucket for the process lifetime.
+ */
+export declare class RequestScheduler {
+    #private;
+    /** Maximum times a request may be moved to a different bucket queue. */
+    static readonly MAX_REMAPS = 2;
+    /** Number of bucket keys currently holding a queue slot. */
+    get size(): number;
+    /**
+     * Runs `task` under the bucket key that `resolveKey` reports *at the moment
+     * the slot is acquired*, not at enqueue time.
+     *
+     * Discord can map several routes onto one bucket hash, and a route only
+     * learns its hash from a response. A request that queued under its
+     * route-derived key while another request discovered the shared hash would
+     * otherwise run concurrently with that bucket's other traffic. Re-resolving
+     * after the wait moves it onto the right queue instead.
+     *
+     * @param resolveKey Returns the current bucket key for this request.
+     * @param signal Cancellation signal honoured while queued.
+     * @param path Request path, used for cancellation error context.
+     * @param task Work to run while holding the slot, given the final key and
+     *   a callback that frees the slot early.
+     */
+    runResolved<T>(resolveKey: () => Promise<string>, signal: AbortSignal | undefined, path: string, task: (key: string, release: () => void) => Promise<T>): Promise<T>;
+    /**
+     * Runs `task` once every earlier task for `key` has settled, or has freed
+     * its slot early through the `release` callback it was given.
+     * @param key Bucket key to serialise on.
+     * @param signal Cancellation signal honoured while queued.
+     * @param path Request path, used for cancellation error context.
+     * @param task Work to run while holding the slot, given an idempotent
+     *   callback that frees the slot before the task settles.
+     */
+    run<T>(key: string, signal: AbortSignal | undefined, path: string, task: (release: () => void) => Promise<T>): Promise<T>;
+}

package/dist/rest/store.d.ts

@@ -0,0 +1,67 @@
+export interface BucketState {
+    remaining: number;
+    resetAt: number;
+}
+/**
+ * Outcome of an atomic reservation.
+ *
+ * `granted` means one unit of the bucket's allowance now belongs to the caller
+ * and to nobody else — the distinction that a read-then-write cannot make when
+ * several workers share a store.
+ */
+export type Reservation = {
+    granted: true;
+} | {
+    granted: false;
+    retryAfterMs: number;
+};
+/** Interface for distributed or local rate limit synchronization. */
+export interface RateLimitStore {
+    /** Gets the server bucket hash for a normalized route. */
+    getBucketHash(route: string): Promise<string | undefined> | string | undefined;
+    /** Associates a route with a server bucket hash. */
+    setBucketHash(route: string, hash: string): Promise<void> | void;
+    /** Gets the current state for a bucket key. */
+    getBucket(key: string): Promise<BucketState | undefined> | BucketState | undefined;
+    /** Updates the state for a bucket key. */
+    updateBucket(key: string, state: BucketState): Promise<void> | void;
+    /** Gets the global reset timestamp. */
+    getGlobalReset(): Promise<number> | number;
+    /** Sets the global reset timestamp. */
+    setGlobalReset(resetAt: number): Promise<void> | void;
+    /**
+     * Atomically consumes one unit of a bucket's allowance.
+     *
+     * Optional: a store that cannot do this atomically must omit it, and the
+     * limiter falls back to waiting on observed state. Implementations must
+     * grant when the bucket is unknown or its window has elapsed — an unknown
+     * bucket is discovered by sending, and refusing would deadlock the route.
+     */
+    reserve?(key: string): Promise<Reservation> | Reservation;
+    /**
+     * Evicts expired bucket entries. Optional: stores with native key
+     * expiry (e.g. Redis) can omit it. `maxAge` (ms) additionally drops
+     * buckets whose reset is older than that window; defaults to 0 (only
+     * already-reset buckets are removed).
+     */
+    prune?(maxAge?: number): Promise<void> | void;
+}
+/** Local memory implementation of RateLimitStore. */
+export declare class MemoryRateLimitStore implements RateLimitStore {
+    #private;
+    getBucketHash(route: string): string | undefined;
+    setBucketHash(route: string, hash: string): void;
+    getBucket(key: string): BucketState | undefined;
+    /**
+     * Consumes one unit of the bucket's allowance.
+     *
+     * Single-process reservation is trivially atomic: JavaScript will not
+     * interleave this method with another caller's copy of it.
+     */
+    reserve(key: string): Reservation;
+    updateBucket(key: string, state: BucketState): void;
+    /** Removes buckets whose reset is in the past (or older than `maxAge` ms). */
+    prune(maxAge?: number): void;
+    getGlobalReset(): number;
+    setGlobalReset(resetAt: number): void;
+}

package/dist/rest/transport.d.ts

@@ -0,0 +1,40 @@
+/** Minimal fetch shape the transport depends on, so a stub needs no extras. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** One HTTP attempt, fully resolved: no routing, retry or rate-limit concerns. */
+export interface TransportRequest {
+    /** Uppercased HTTP method. */ method: string;
+    /** Path with query string, relative to the transport's base URL. */ path: string;
+    /** Request headers, already including authorization. */ headers: Record<string, string>;
+    /** Encoded body, or undefined for a bodyless request. */ body?: BodyInit;
+    /** Caller cancellation signal. */ signal?: AbortSignal;
+}
+/** Thrown by {@link HttpTransport} when the attempt never produced a response. */
+export declare class TransportError extends Error {
+    /** Whether the attempt was cut short by the transport timeout or an abort. */
+    readonly timedOut: boolean;
+    constructor(message: string, timedOut: boolean, cause?: unknown);
+}
+/**
+ * Sends one HTTP attempt and returns the raw {@link Response}.
+ *
+ * Everything above it — routing, rate limiting, retries, decoding — is somebody
+ * else's job, which is what makes the layer substitutable in tests.
+ */
+export declare class HttpTransport {
+    #private;
+    constructor(options?: {
+        baseURL?: string;
+        timeout?: number;
+        fetch?: FetchLike;
+    });
+    /** Base URL every request path is resolved against. */
+    get baseURL(): string;
+    /** Per-attempt timeout in milliseconds. */
+    get timeout(): number;
+    /**
+     * Performs the attempt.
+     * @throws {RESTError} If the caller's signal was already aborted.
+     * @throws {TransportError} If the attempt times out or the transport fails.
+     */
+    send(request: TransportRequest): Promise<Response>;
+}

package/dist/rest/webhook.d.ts

@@ -1,4 +1,4 @@
-import type { APIEmbed } from "@lunibee/types";
+import type { APIEmbed, APIMessage } from "@lunibee/types";
 export interface WebhookClientOptions {
     id?: string;
     token?: string;
@@ -29,7 +29,7 @@ export declare class WebhookClient {
         retries?: number;
     });
     /** Sends a message to the webhook. */
-    send(options: string | WebhookMessageOptions): Promise<any>;
+    send(options: string | WebhookMessageOptions): Promise<APIMessage>;
     /** Edits a previously sent webhook message. */
     editMessage(messageId: string, options: string | {
         content?: string;

package/dist/sharding/bus.d.ts

@@ -5,9 +5,18 @@ export interface ShardMessage<T = unknown> {
     /** Application message type. */ type: string;
     /** Message payload. */ data: T;
     /** Unique message ID. */ id: string;
+    /** Set on requests that expect a reply (see {@link ShardBus.request}). */ expectsReply?: boolean;
+}
+/** A reply collected by {@link ShardBus.broadcastRequest}. */
+export interface ShardReply<R = unknown> {
+    /** Replying shard ID. */ shardId: number;
+    /** Handler result, when it succeeded. */ result?: R;
+    /** Handler error message, when it failed. */ error?: string;
 }
 /** Handler invoked for shard messages. @typeParam T Message payload type. */
 export type ShardMessageHandler<T = unknown> = (message: ShardMessage<T>) => unknown;
+/** Listener for errors thrown or rejected by shard message handlers. */
+export type ShardBusErrorHandler = (error: unknown, message: ShardMessage) => void;
 /** Bun/Node-compatible cross-shard transport using BroadcastChannel. */
 export declare class ShardBus {
     #private;
@@ -16,7 +25,29 @@ export declare class ShardBus {
     constructor(shardId: number, channelName: string);
     /** Registers a message handler. @param type Message type. @param handler Handler callback. @returns This bus. @throws {TypeError} If type or handler is invalid. */ on<T>(type: string, handler: ShardMessageHandler<T>): this;
     /** Removes a message handler. @param type Message type. @param handler Handler callback. @returns This bus. */ off<T>(type: string, handler: ShardMessageHandler<T>): this;
+    /** Registers a listener for errors thrown or rejected by message handlers. Without one, handler errors are isolated and dropped. @param handler Error listener. @returns This bus. @throws {TypeError} If handler is invalid. */ onError(handler: ShardBusErrorHandler): this;
+    /** Removes a handler error listener. @param handler Error listener. @returns This bus. */ offError(handler: ShardBusErrorHandler): this;
     /** Sends a targeted shard message. @param target Target shard ID. @param type Message type. @param data Payload. @returns Unique message ID. */ send<T>(target: number, type: string, data: T): string;
     /** Broadcasts to all other shards. @param type Message type. @param data Payload. @returns Unique message ID. */ broadcast<T>(type: string, data: T): string;
+    /**
+     * Registers a handler that answers requests of `type`. Its return value (or
+     * thrown error) is sent back to the requesting shard. Discord.js-familiar
+     * replacement for `broadcastEval` that never evaluates received code.
+     * @returns This bus.
+     */
+    respond<T, R>(type: string, handler: (data: T, message: ShardMessage<T>) => R | Promise<R>): this;
+    /**
+     * Sends a request to one shard and resolves with its handler's result.
+     * @throws {Error} If the handler failed or no reply arrives in time.
+     */
+    request<R = unknown, T = unknown>(target: number, type: string, data: T, timeoutMs?: number): Promise<R>;
+    /**
+     * Sends a request to every other shard and collects replies until
+     * `expected` have arrived or `timeoutMs` elapses (never rejects).
+     */
+    broadcastRequest<R = unknown, T = unknown>(type: string, data: T, options?: {
+        timeoutMs?: number;
+        expected?: number;
+    }): Promise<ShardReply<R>[]>;
     /** Closes the transport. @returns Nothing. */ close(): void;
 }

package/dist/sharding/cluster.d.ts

@@ -0,0 +1,71 @@
+import { type ChildProcess } from "node:child_process";
+/** Configuration for managing multiple shard clusters. */
+export interface ClusterManagerOptions {
+    /** Discord bot token. */
+    token: string;
+    /** Path to the worker script to execute for each cluster. */
+    script: string;
+    /** Number of shards. Use "auto" to request Discord's recommended count. */
+    shardCount?: number | "auto";
+    /** Number of clusters to spawn. Defaults to the number of logical CPUs. */
+    clusterCount?: number;
+    /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. */
+    autoScaleInterval?: number;
+    /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */
+    onAutoScaleError?: (error: Error) => void;
+    /** Grace period in milliseconds to await a cluster's clean exit after SIGTERM before force-killing. Defaults to 5000. */
+    shutdownTimeout?: number;
+    /**
+     * Whether a cluster that exits unexpectedly is re-forked with the same
+     * shard assignment. Defaults to true: without it a crashed child leaves
+     * its shards permanently offline and nothing reports it.
+     */
+    restartOnExit?: boolean;
+    /** Delay in milliseconds before re-forking a crashed cluster. Defaults to 5000. */
+    restartDelay?: number;
+    /** Called whenever a cluster process exits, before any restart. */
+    onClusterExit?(cluster: ClusterInfo, code: number | null, signal: NodeJS.Signals | null): void;
+}
+/** Information about a running cluster. */
+export interface ClusterInfo {
+    /** Cluster identifier. */
+    id: number;
+    /** The child process running the cluster. */
+    process: ChildProcess;
+    /** The shard IDs managed by this cluster. */
+    shards: number[];
+}
+/**
+ * Manages multiple clusters of shards, distributing shards across child processes.
+ *
+ * **Runtime requirement:** clustering relies on Node.js `child_process.fork()`
+ * and IPC. `fork()` is not fully supported under Bun, so run the cluster
+ * manager under the Node.js runtime; `spawn()` will fail on a runtime whose
+ * `fork()` is unavailable.
+ */
+export declare class ClusterManager {
+    #private;
+    /** Active clusters indexed by cluster ID. */
+    readonly clusters: Map<number, ClusterInfo>;
+    /** Total number of shards across all clusters. */
+    shardCount: number;
+    /** Creates a cluster manager. @param options Clustering configuration. @throws {TypeError} If token or script is missing. */
+    constructor(options: ClusterManagerOptions);
+    /** Retrieves Discord's recommended shard count. @returns Recommended shard count. @throws {Error} If discovery fails or returns invalid data. */
+    fetchRecommendedShardCount(): Promise<number>;
+    /** Spawns all clusters. @returns A promise fulfilled after clusters have launched. */
+    spawn(): Promise<void>;
+    /** Checks if the recommended shard count has changed and respawns if so. */
+    checkAutoScale(): Promise<void>;
+    /** Gracefully shuts the existing clusters down and respawns them with the new shard count. @param newShardCount The new total shard count. */
+    respawn(newShardCount: number): Promise<void>;
+    /**
+     * Gracefully stops all active clusters: sends SIGTERM, awaits each child's
+     * clean exit, and force-kills (SIGKILL) only children that outlast the
+     * shutdown timeout. Clears the auto-scale timer and cluster map.
+     * @param timeoutMs Grace period per child before force-kill. Defaults to the configured `shutdownTimeout` (5000 ms).
+     */
+    shutdownAll(timeoutMs?: number): Promise<void>;
+    /** Immediately force-kills all active cluster processes and clears the cluster map. Prefer {@link shutdownAll} for a graceful stop. */
+    killAll(): void;
+}

package/dist/sharding/index.d.ts

@@ -1,13 +1,21 @@
 import { Gateway } from "@lunibee/ws";
 export { ShardBus } from "./bus.js";
-export type { ShardMessage, ShardMessageHandler } from "./bus.js";
+export type { ShardBusErrorHandler, ShardMessage, ShardMessageHandler, ShardReply, } from "./bus.js";
+export { ClusterManager } from "./cluster.js";
+export type { ClusterManagerOptions, ClusterInfo } from "./cluster.js";
 /** Configuration for a sharded Gateway client. */
 export interface ShardManagerOptions {
     /** Bot token. */ token: string;
     /** Gateway intents. */ intents: number;
     /** Number of shards. Use `"auto"` to request Discord's recommended count. */ shardCount?: number | "auto";
     /** Gateway reconnect behavior. */ reconnect?: boolean;
-    /** Delay between shard starts in milliseconds. */ spawnDelay?: number;
+    /**
+     * Delay between shard starts in milliseconds. Defaults to 5000 to respect
+     * Discord's IDENTIFY rate limit (one per 5s per rate-limit key); set 0 to
+     * opt out when an external scheduler already paces the handshakes.
+     */ spawnDelay?: number;
+    /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. Must be an integer >= 1000. */ autoScaleInterval?: number;
+    /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */ onAutoScaleError?: (error: unknown) => void;
 }
 /** Runtime state for a managed shard. */
 export interface ShardInfo {
@@ -17,6 +25,8 @@ export interface ShardInfo {
 /** Manages independent Discord Gateway shards with explicit destruction and reinitialization semantics. */
 export declare class ShardManager {
     #private;
+    /** Discord's minimum interval between IDENTIFY payloads, in milliseconds. */
+    static readonly IDENTIFY_INTERVAL = 5000;
     /** Active Gateway shards indexed by shard identifier. */ readonly shards: Map<number, Gateway>;
     /** Number of shards managed by this instance after initialization. */ get shardCount(): number;
     /** Creates a shard manager. @param options Sharding configuration. @throws {TypeError} If token or intents are invalid. @throws {RangeError} If shard count is invalid. */
@@ -25,6 +35,10 @@ export declare class ShardManager {
     fetchRecommendedShardCount(): Promise<number>;
     /** Connects all shards sequentially. A destroyed manager is reinitialized before connecting. @returns A promise fulfilled after all shards connect. @throws {Error} If a shard fails to connect. */
     connect(): Promise<void>;
+    /** Checks if the recommended shard count has changed and reconnects if so. */
+    checkAutoScale(): Promise<void>;
+    /** Forces a reshard to a new shard count, replacing all active shards. @param count New shard count. */
+    reshard(count: number): Promise<void>;
     /** Permanently closes the current shard set and releases Gateway resources. The next connect recreates them. @returns Nothing. */
     destroy(): void;
     /** Calculates the target shard ID for a Discord guild snowflake. @param guildId Guild snowflake. @returns Shard identifier. */
@@ -32,3 +46,5 @@ export declare class ShardManager {
     /** Gets a shard by ID. @param id Shard identifier. @returns Gateway instance or undefined. */ get(id: number): Gateway | undefined;
     /** Returns information for all managed shards. @returns Shard information snapshots. */ values(): ShardInfo[];
 }
+/** Discord.js-familiar alias for {@link ShardManager}. */
+export { ShardManager as ShardingManager };