lunibee 0.1.7 → 0.2.0

package/dist/rest/limiter.d.ts

@@ -0,0 +1,42 @@
+import type { RateLimitStore } from "./store.js";
+/**
+ * Owns Discord's rate-limit state: when a request may go out, and what a
+ * response says about the bucket it landed in.
+ *
+ * The limiter holds no queueing logic of its own — {@link RequestScheduler}
+ * decides ordering — and no HTTP knowledge beyond reading rate-limit headers.
+ */
+export declare class RateLimiter {
+    #private;
+    /**
+     * @param store Rate-limit state store.
+     * @param options `concurrent`: set when several requests per bucket can be
+     *   in flight, so a late response cannot raise `remaining` within its window.
+     */
+    constructor(store: RateLimitStore, options?: {
+        concurrent?: boolean;
+    });
+    /** The backing store, shared across processes when a distributed store is used. */
+    get store(): RateLimitStore;
+    /** Resolves the bucket key a request should be gated on. */
+    resolveBucketKey(route: string, major: string): Promise<string>;
+    /** Whether the backing store can reserve allowance atomically. */
+    get reserves(): boolean;
+    /**
+     * Waits until both the route bucket and the global limit permit sending.
+     *
+     * When the store supports it, allowance is *reserved* rather than merely
+     * observed. Reading `remaining` and deciding to send is a race across
+     * workers: three processes all read `remaining: 1` and all send. A
+     * reservation hands the unit to exactly one of them.
+     */
+    acquire(bucketKey: string, signal: AbortSignal | undefined, path: string): Promise<void>;
+    /** Extends the global limit, never shortening a longer one already recorded. */
+    noteGlobalReset(resetAt: number): Promise<void>;
+    /**
+     * Records a response's rate-limit headers and returns the bucket key the
+     * request actually belongs to: Discord may reveal a server bucket hash that
+     * differs from the route-derived key used before the first response.
+     */
+    applyResponse(response: Response, bucketKey: string, route: string, major: string): Promise<string>;
+}

package/dist/rest/redis.d.ts

@@ -1,4 +1,4 @@
-import type { RateLimitStore, BucketState } from "./store.js";
+import { type RateLimitStore, type BucketState, type Reservation } from "./store.js";
 /**
  * A Redis client interface that matches the subset of ioredis
  * methods needed for the RedisRateLimitStore.
@@ -8,6 +8,12 @@ export interface MinimalRedisClient {
     mget(keys: string[]): Promise<Array<string | null>>;
     set(key: string, value: string | number, mode?: string, duration?: number): Promise<any>;
     del(...keys: string[]): Promise<number>;
+    /**
+     * Optional Lua evaluation (ioredis/node-redis compatible). When present,
+     * {@link RedisRateLimitStore.reserve} becomes available and the limiter
+     * reserves allowance atomically instead of racing on observed state.
+     */
+    eval?(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
 }
 export interface RedisRateLimitStoreOptions {
     /** The Redis client instance (e.g. ioredis). */
@@ -32,6 +38,17 @@ export declare class RedisRateLimitStore implements RateLimitStore {
     setBucketHash(route: string, hash: string): Promise<void>;
     getBucket(key: string): Promise<BucketState | undefined>;
     updateBucket(key: string, state: BucketState): Promise<void>;
+    /** Whether the backing client supports atomic reservations. */
+    get supportsReservation(): boolean;
+    /**
+     * Atomically consumes one unit of a bucket's allowance across the fleet.
+     *
+     * Assigned in the constructor only when the client exposes `eval`, so a
+     * client that cannot reserve atomically does not advertise that it can.
+     * A Redis failure falls back to the local mirror rather than blocking:
+     * refusing every request during an outage would stall the bot.
+     */
+    reserve?: (key: string) => Promise<Reservation>;
     getGlobalReset(): Promise<number>;
     setGlobalReset(resetAt: number): Promise<void>;
 }

package/dist/rest/route.d.ts

@@ -0,0 +1,31 @@
+/** Query-string value accepted by a request. */
+export type RESTQuery = URLSearchParams | Record<string, string | number | boolean | null | undefined> | string;
+/**
+ * Identity of a request as Discord's rate limiter sees it.
+ *
+ * `route` is the shape of the endpoint (ids replaced by `:id`), which is what
+ * Discord returns a bucket hash for. `major` is the resource that gives an
+ * endpoint its own independent limit. Both are needed: the hash alone would
+ * make two channels share one counter.
+ */
+export interface RouteKey {
+    /** Uppercased HTTP method. */ method: string;
+    /** Raw request path, without query string. */ path: string;
+    /** Normalized `METHOD:/path/:id` route used for bucket-hash lookup. */ route: string;
+    /** Major parameter scoping the limit (channel, guild, webhook id[:token]). */ major: string;
+}
+/** Normalizes Discord routes for stable bucket discovery. */
+export declare function normalizeRoutePath(path: string): string;
+/**
+ * Discord's *major parameters* — the resource ids that give an endpoint its own
+ * independent rate limit. Per the API documentation these are `channel_id`,
+ * `guild_id` and `webhook_id`; webhook routes are additionally scoped by
+ * their token. Any other id in a path shares its limit with sibling resources.
+ */
+export declare function majorParameter(path: string): string;
+/** Combines a bucket hash (or route) with a major parameter into a bucket key. */
+export declare function scopeBucket(hashOrRoute: string, major: string): string;
+/** Builds the routing identity for one request. */
+export declare function createRouteKey(method: string, path: string): RouteKey;
+/** Serialises a query into a `?...` suffix (empty string when nothing to add). */
+export declare function serializeQuery(query: RESTQuery | undefined): string;

package/dist/rest/routes.d.ts

@@ -39,6 +39,8 @@ export declare const Routes: {
     /** Returns a thread's members. @param threadId Thread identifier. @returns Thread-member route. */ readonly threadMembers: (threadId: string) => string;
     /** Returns guild scheduled events. @param guildId Guild identifier. @returns Scheduled-event collection route. */ readonly guildScheduledEvents: (guildId: string) => string;
     /** Returns one guild scheduled event. @param guildId Guild identifier. @param eventId Event identifier. @returns Scheduled-event route. */ readonly guildScheduledEvent: (guildId: string, eventId: string) => string;
+    /** Returns users subscribed to a scheduled event. @param guildId Guild identifier. @param eventId Event identifier. @returns Scheduled-event users route. */ readonly guildScheduledEventUsers: (guildId: string, eventId: string) => string;
+    /** Returns a channel permission overwrite. @param channelId Channel identifier. @param overwriteId Role or user identifier. @returns Permission overwrite route. */ readonly channelPermission: (channelId: string, overwriteId: string) => string;
     /** Returns guild automod rules. @param guildId Guild identifier. @returns Automod-rule collection route. */ readonly guildAutoModerationRules: (guildId: string) => string;
     /** Returns one automod rule. @param guildId Guild identifier. @param ruleId Rule identifier. @returns Automod-rule route. */ readonly guildAutoModerationRule: (guildId: string, ruleId: string) => string;
     /** Returns current voice regions. @returns Voice-region route. */ readonly voiceRegions: () => string;
@@ -66,4 +68,24 @@ export declare const Routes: {
     readonly guildEmoji: (guildId: string, emojiId?: string) => string;
     /** Returns application emojis, or a specific emoji. @param applicationId Application identifier. @param emojiId Optional emoji identifier. */
     readonly applicationEmoji: (applicationId: string, emojiId?: string) => string;
+    /** Ends a poll early. @param channelId Channel identifier. @param messageId Poll message identifier. */
+    readonly pollExpire: (channelId: string, messageId: string) => string;
+    /** Returns the users who voted for a poll answer. @param answerId Answer identifier (an integer, not a snowflake). */
+    readonly pollAnswerVoters: (channelId: string, messageId: string, answerId: number) => string;
+    /** Returns guild stickers, or one sticker. */
+    readonly guildSticker: (guildId: string, stickerId?: string) => string;
+    /** Plays a soundboard sound in a voice channel. */
+    readonly sendSoundboardSound: (channelId: string) => string;
+    /** Returns Discord's default soundboard sounds. */
+    readonly soundboardDefaultSounds: () => string;
+    /** Returns guild soundboard sounds, or one sound. */
+    readonly guildSoundboardSound: (guildId: string, soundId?: string) => string;
+    /** Returns an application's SKUs. */
+    readonly applicationSkus: (applicationId: string) => string;
+    /** Returns an application's entitlements, or one entitlement. */
+    readonly applicationEntitlement: (applicationId: string, entitlementId?: string) => string;
+    /** Marks a one-time-purchase entitlement as consumed. */
+    readonly consumeEntitlement: (applicationId: string, entitlementId: string) => string;
+    /** Returns a SKU's subscriptions, or one subscription. */
+    readonly skuSubscription: (skuId: string, subscriptionId?: string) => string;
 };

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

@@ -2,6 +2,19 @@ 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. */
@@ -16,6 +29,15 @@ export interface RateLimitStore {
     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
@@ -30,6 +52,13 @@ export declare class MemoryRateLimitStore implements RateLimitStore {
     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;

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

@@ -15,6 +15,16 @@ export interface ClusterManagerOptions {
     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 {

package/dist/sharding/index.d.ts

@@ -1,6 +1,6 @@
 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. */
@@ -9,10 +9,39 @@ export interface ShardManagerOptions {
     /** 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;
+    /**
+     * Shards that may IDENTIFY at once (Discord's `max_concurrency`). Defaults
+     * to the value from `/gateway/bot` when it was fetched (auto shard count),
+     * else 1.
+     */ maxConcurrency?: number;
+    /**
+     * How long a startup round waits for its shards to send IDENTIFY/RESUME
+     * before the next round's `spawnDelay` starts. Defaults to 15000 ms.
+     */ handshakeTimeout?: 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;
 }
+/** `/gateway/bot` information used to pace shard startup. */
+export interface GatewayBotInfo {
+    /** Recommended shard count. */ shards: number;
+    /** IDENTIFY budget, when Discord reported it. */ sessionStartLimit?: {
+        total: number;
+        remaining: number;
+        /** Milliseconds until `remaining` resets. */ resetAfter: number;
+        maxConcurrency: number;
+    };
+}
+/** Health snapshot for one shard. */
+export interface ShardHealth {
+    id: number;
+    /** Gateway connection state. */ state: Gateway["state"];
+    /** Last heartbeat round-trip in ms, or -1 before the first ACK. */ ping: number;
+}
 /** Runtime state for a managed shard. */
 export interface ShardInfo {
     /** Shard identifier. */ id: number;
@@ -21,12 +50,16 @@ 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. */
     constructor(options: ShardManagerOptions);
     /** Retrieves Discord's recommended shard count. @returns Recommended shard count. @throws {Error} If discovery fails or returns invalid data. */
     fetchRecommendedShardCount(): Promise<number>;
+    /** Retrieves `/gateway/bot`: recommended shards and the IDENTIFY budget. Remembered for pacing the next connect. @throws {Error} If discovery fails or returns invalid data. */
+    fetchGatewayInfo(): Promise<GatewayBotInfo>;
     /** 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. */
@@ -38,5 +71,9 @@ export declare class ShardManager {
     /** Calculates the target shard ID for a Discord guild snowflake. @param guildId Guild snowflake. @returns Shard identifier. */
     getShardIdForGuild(guildId: string): number;
     /** Gets a shard by ID. @param id Shard identifier. @returns Gateway instance or undefined. */ get(id: number): Gateway | undefined;
+    /** Returns each shard's connection state and heartbeat latency. */
+    health(): ShardHealth[];
     /** Returns information for all managed shards. @returns Shard information snapshots. */ values(): ShardInfo[];
 }
+/** Discord.js-familiar alias for {@link ShardManager}. */
+export { ShardManager as ShardingManager };