lunibee 0.2.3 → 0.3.0

package/dist/rest/redis.d.ts

@@ -6,7 +6,7 @@ import { type RateLimitStore, type BucketState, type Reservation } from "./store
 export interface MinimalRedisClient {
     get(key: string): Promise<string | null>;
     mget(keys: string[]): Promise<Array<string | null>>;
-    set(key: string, value: string | number, mode?: string, duration?: number): Promise<any>;
+    set(key: string, value: string | number, mode?: string, duration?: number): Promise<string | null>;
     del(...keys: string[]): Promise<number>;
     /**
      * Optional Lua evaluation (ioredis/node-redis compatible). When present,

package/dist/rest/route.d.ts

@@ -9,10 +9,14 @@ export type RESTQuery = URLSearchParams | Record<string, string | number | boole
  * 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;
+    /** 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;

package/dist/rest/routes.d.ts

@@ -1,57 +1,131 @@
 /** Discord REST API route definitions. */
 export declare const Routes: {
-    /** Returns the current bot user. @returns User route. */ readonly user: () => string;
-    /** Returns one user. @param userId User identifier. @returns User route. */ readonly userById: (userId: string) => string;
-    /** Returns a guild. @param guildId Guild identifier. @returns Guild route. */ readonly guild: (guildId: string) => string;
-    /** Returns a guild preview. @param guildId Guild identifier. */ readonly guildPreview: (guildId: string) => string;
-    /** Returns active threads for a guild. @param guildId Guild identifier. */ readonly guildActiveThreads: (guildId: string) => string;
-    /** Returns webhooks for a guild. @param guildId Guild identifier. */ readonly guildWebhooks: (guildId: string) => string;
-    /** Returns invites for a guild. @param guildId Guild identifier. */ readonly guildInvites: (guildId: string) => string;
-    /** Returns channels in a guild. @param guildId Guild identifier. @returns Channel collection route. */ readonly guildChannels: (guildId: string) => string;
-    /** Returns a guild member. @param guildId Guild identifier. @param userId User identifier. @returns Guild-member route. */ readonly guildMember: (guildId: string, userId: string) => string;
-    /** Returns all guild roles. @param guildId Guild identifier. @returns Guild-role route. */ readonly guildRoles: (guildId: string) => string;
-    /** Returns an individual guild role. */ readonly guildRole: (guildId: string, roleId: string) => string;
-    /** Returns a member role route. */ readonly guildMemberRole: (guildId: string, userId: string, roleId: string) => string;
-    /** Returns guild bans collection. */ readonly guildBans: (guildId: string) => string;
-    /** Returns an individual guild ban. */ readonly guildBan: (guildId: string, userId: string) => string;
-    /** Returns a channel. @param channelId Channel identifier. @returns Channel route. */ readonly channel: (channelId: string) => string;
-    /** Returns messages in a channel. @param channelId Channel identifier. @returns Message collection route. */ readonly channelMessages: (channelId: string) => string;
-    /** Returns a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Message route. */ readonly message: (channelId: string, messageId: string) => string;
-    /** Crossposts a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Crosspost route. */ readonly crosspostMessage: (channelId: string, messageId: string) => string;
-    /** Returns reactions for a message and emoji. @param channelId Channel identifier. @param messageId Message identifier. @param emoji Emoji name or ID. @returns Reaction route. */ readonly messageReactions: (channelId: string, messageId: string, emoji: string) => string;
-    /** Removes all reactions from a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Reaction collection route. */ readonly messageReactionsAll: (channelId: string, messageId: string) => string;
-    /** Returns pinned messages, newest first, in pages of up to 50 (`before`, `limit`). @param channelId Channel identifier. @returns Pins route. */ readonly channelMessagesPins: (channelId: string) => string;
-    /** Pins (PUT) or unpins (DELETE) a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Pin route. */ readonly channelMessagesPin: (channelId: string, messageId: string) => string;
-    /** @deprecated Discord deprecated this endpoint. Use {@link Routes.channelMessagesPins}, which returns `{ items, has_more }`. Removed in 0.3.0. */ readonly channelPins: (channelId: string) => string;
-    /** @deprecated Discord deprecated this endpoint. Use {@link Routes.channelMessagesPin}. Removed in 0.3.0. */ readonly channelPin: (channelId: string, messageId: string) => string;
-    /** Creates a thread from a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Message-thread route. */ readonly messageThread: (channelId: string, messageId: string) => string;
-    /** Bulk deletes messages. @param channelId Channel identifier. @returns Bulk-delete route. */ readonly channelBulkDelete: (channelId: string) => string;
-    /** Returns channel webhooks. @param channelId Channel identifier. @returns Webhook collection route. */ readonly channelWebhooks: (channelId: string) => string;
-    /** Returns channel invites. @param channelId Channel identifier. @returns Invite collection route. */ readonly channelInvites: (channelId: string) => string;
-    /** Returns a webhook. @param webhookId Webhook identifier. @param token Optional webhook token. @returns Webhook route. */ readonly webhook: (webhookId: string, token?: string) => string;
-    /** Returns a webhook message. */ readonly webhookMessage: (webhookId: string, token: string, messageId: string) => string;
-    /** Returns application commands for an application. @param applicationId Application identifier. @returns Global command route. */ readonly applicationCommands: (applicationId: string) => string;
-    /** Returns one application command. @param applicationId Application identifier. @param commandId Command identifier. @returns Command route. */ readonly applicationCommand: (applicationId: string, commandId: string) => string;
-    /** Returns guild application commands. @param applicationId Application identifier. @param guildId Guild identifier. @returns Guild command route. */ readonly guildApplicationCommands: (applicationId: string, guildId: string) => string;
-    /** Returns a single guild application command. @param applicationId Application identifier. @param guildId Guild identifier. @param commandId Command identifier. @returns Guild command route. */ readonly guildApplicationCommand: (applicationId: string, guildId: string, commandId: string) => string;
-    /** Returns an interaction callback endpoint. @param interactionId Interaction identifier. @param token Interaction token. @returns Interaction callback route. */ readonly interactionCallback: (interactionId: string, token: string) => string;
-    /** Returns the original interaction response endpoint. @param applicationId Application identifier. @param token Interaction token. @returns Original-response route. */ readonly interactionOriginalResponse: (applicationId: string, token: string) => string;
-    /** Returns public archived threads for a channel. @param channelId Channel identifier. @returns Public-archive route. */ readonly channelPublicArchivedThreads: (channelId: string) => string;
-    /** Returns private archived threads for a channel. @param channelId Channel identifier. @returns Private-archive route. */ readonly channelPrivateArchivedThreads: (channelId: string) => string;
-    /** 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;
-    /** Returns the generic Gateway endpoint. @returns Gateway route. */ readonly gateway: () => string;
-    /** Returns the Gateway endpoint and recommended shard count for bots. @returns Gateway bot route. */ readonly gatewayBot: () => string;
+    /** Returns the current bot user. @returns User route. */
+    readonly user: () => string;
+    /** Returns one user. @param userId User identifier. @returns User route. */
+    readonly userById: (userId: string) => string;
+    /** Returns a guild. @param guildId Guild identifier. @returns Guild route. */
+    readonly guild: (guildId: string) => string;
+    /** Leaves a guild as the current user (DELETE). @param guildId Guild identifier. @returns Current-user guild route. */
+    readonly currentUserGuild: (guildId: string) => string;
+    /** Returns a sticker. @param stickerId Sticker identifier. @returns Sticker route. */
+    readonly sticker: (stickerId: string) => string;
+    /** Removes one user's reaction (DELETE). @param channelId Channel identifier. @param messageId Message identifier. @param emoji Emoji name or ID. @param userId User identifier. @returns Reaction-user route. */
+    readonly messageReactionUser: (channelId: string, messageId: string, emoji: string, userId: string) => string;
+    /** Returns a guild preview. @param guildId Guild identifier. */
+    readonly guildPreview: (guildId: string) => string;
+    /** Returns active threads for a guild. @param guildId Guild identifier. */
+    readonly guildActiveThreads: (guildId: string) => string;
+    /** Returns webhooks for a guild. @param guildId Guild identifier. */
+    readonly guildWebhooks: (guildId: string) => string;
+    /** Returns invites for a guild. @param guildId Guild identifier. */
+    readonly guildInvites: (guildId: string) => string;
+    /** Returns channels in a guild. @param guildId Guild identifier. @returns Channel collection route. */
+    readonly guildChannels: (guildId: string) => string;
+    /** Returns a guild member. @param guildId Guild identifier. @param userId User identifier. @returns Guild-member route. */
+    readonly guildMember: (guildId: string, userId: string) => string;
+    /** Returns all guild roles. @param guildId Guild identifier. @returns Guild-role route. */
+    readonly guildRoles: (guildId: string) => string;
+    /** Returns an individual guild role. */
+    readonly guildRole: (guildId: string, roleId: string) => string;
+    /** Returns a member role route. */
+    readonly guildMemberRole: (guildId: string, userId: string, roleId: string) => string;
+    /** Returns guild bans collection. */
+    readonly guildBans: (guildId: string) => string;
+    /** Returns an individual guild ban. */
+    readonly guildBan: (guildId: string, userId: string) => string;
+    /** Returns a channel. @param channelId Channel identifier. @returns Channel route. */
+    readonly channel: (channelId: string) => string;
+    /** Returns messages in a channel. @param channelId Channel identifier. @returns Message collection route. */
+    readonly channelMessages: (channelId: string) => string;
+    /** Returns a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Message route. */
+    readonly message: (channelId: string, messageId: string) => string;
+    /** Crossposts a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Crosspost route. */
+    readonly crosspostMessage: (channelId: string, messageId: string) => string;
+    /** Returns reactions for a message and emoji. @param channelId Channel identifier. @param messageId Message identifier. @param emoji Emoji name or ID. @returns Reaction route. */
+    readonly messageReactions: (channelId: string, messageId: string, emoji: string) => string;
+    /** The bot's own reaction: PUT adds it, DELETE removes it. @param channelId Channel identifier. @param messageId Message identifier. @param emoji Emoji name or ID. */
+    readonly messageReactionMe: (channelId: string, messageId: string, emoji: string) => string;
+    /** Removes all reactions from a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Reaction collection route. */
+    readonly messageReactionsAll: (channelId: string, messageId: string) => string;
+    /** Returns pinned messages, newest first, in pages of up to 50 (`before`, `limit`). @param channelId Channel identifier. @returns Pins route. */
+    readonly channelMessagesPins: (channelId: string) => string;
+    /** Pins (PUT) or unpins (DELETE) a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Pin route. */
+    readonly channelMessagesPin: (channelId: string, messageId: string) => string;
+    /** Creates a thread from a message. @param channelId Channel identifier. @param messageId Message identifier. @returns Message-thread route. */
+    readonly messageThread: (channelId: string, messageId: string) => string;
+    /** Bulk deletes messages. @param channelId Channel identifier. @returns Bulk-delete route. */
+    readonly channelBulkDelete: (channelId: string) => string;
+    /** Returns channel webhooks. @param channelId Channel identifier. @returns Webhook collection route. */
+    readonly channelWebhooks: (channelId: string) => string;
+    /** Returns channel invites. @param channelId Channel identifier. @returns Invite collection route. */
+    readonly channelInvites: (channelId: string) => string;
+    /** Returns a webhook. @param webhookId Webhook identifier. @param token Optional webhook token. @returns Webhook route. */
+    readonly webhook: (webhookId: string, token?: string) => string;
+    /** Returns a webhook message. */
+    readonly webhookMessage: (webhookId: string, token: string, messageId: string) => string;
+    /** Returns application commands for an application. @param applicationId Application identifier. @returns Global command route. */
+    readonly applicationCommands: (applicationId: string) => string;
+    /** Returns one application command. @param applicationId Application identifier. @param commandId Command identifier. @returns Command route. */
+    readonly applicationCommand: (applicationId: string, commandId: string) => string;
+    /** Returns guild application commands. @param applicationId Application identifier. @param guildId Guild identifier. @returns Guild command route. */
+    readonly guildApplicationCommands: (applicationId: string, guildId: string) => string;
+    /** Returns a single guild application command. @param applicationId Application identifier. @param guildId Guild identifier. @param commandId Command identifier. @returns Guild command route. */
+    readonly guildApplicationCommand: (applicationId: string, guildId: string, commandId: string) => string;
+    /** Returns an interaction callback endpoint. @param interactionId Interaction identifier. @param token Interaction token. @returns Interaction callback route. */
+    readonly interactionCallback: (interactionId: string, token: string) => string;
+    /** Returns the original interaction response endpoint. @param applicationId Application identifier. @param token Interaction token. @returns Original-response route. */
+    readonly interactionOriginalResponse: (applicationId: string, token: string) => string;
+    /** Returns public archived threads for a channel. @param channelId Channel identifier. @returns Public-archive route. */
+    readonly channelPublicArchivedThreads: (channelId: string) => string;
+    /** Returns private archived threads for a channel. @param channelId Channel identifier. @returns Private-archive route. */
+    readonly channelPrivateArchivedThreads: (channelId: string) => string;
+    /** Returns the private archived threads the current user joined. @param channelId Channel identifier. */
+    readonly channelJoinedPrivateArchivedThreads: (channelId: string) => string;
+    /** Returns one member of a thread; `"@me"` is the current user (PUT joins, DELETE leaves). @param threadId Thread identifier. @param userId User identifier or `"@me"`. */
+    readonly threadMember: (threadId: string, userId: string) => string;
+    /** Starts a typing indicator (POST). @param channelId Channel identifier. */
+    readonly channelTyping: (channelId: string) => string;
+    /** Creates a thread that is not tied to a message, or a forum or media post (POST). @param channelId Channel identifier. */
+    readonly channelThreads: (channelId: string) => string;
+    /** 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;
+    /** Returns the generic Gateway endpoint. @returns Gateway route. */
+    readonly gateway: () => string;
+    /** Returns the Gateway endpoint and recommended shard count for bots. @returns Gateway bot route. */
+    readonly gatewayBot: () => string;
     /** Returns audit log entries for a guild. @param guildId Guild identifier. @returns Audit log route. */
     readonly guildAuditLog: (guildId: string) => string;
     /** Returns members in a guild (paginated). @param guildId Guild identifier. @returns Members collection route. */
     readonly guildMembers: (guildId: string) => string;
+    /** Searches members by nickname or username. @param guildId Guild identifier. */
+    readonly guildMembersSearch: (guildId: string) => string;
+    /** Edits the bot's own member, e.g. its nickname (PATCH). @param guildId Guild identifier. */
+    readonly guildMemberMe: (guildId: string) => string;
+    /** Bans up to 200 users at once (POST). @param guildId Guild identifier. */
+    readonly guildBulkBan: (guildId: string) => string;
+    /** Edits a voice state in a stage channel (PATCH); `"@me"` is the bot. @param guildId Guild identifier. @param userId User identifier or `"@me"`. */
+    readonly guildVoiceState: (guildId: string, userId: string) => string;
+    /** Removes an integration from a guild (DELETE). @param guildId Guild identifier. @param integrationId Integration identifier. */
+    readonly guildIntegration: (guildId: string, integrationId: string) => string;
+    /** Returns the guilds the bot is in (paged with `before`, `after`, `limit`). */
+    readonly userGuilds: () => string;
+    /** Returns the sticker packs Nitro users can use, or one pack. @param packId Optional pack identifier. */
+    readonly stickerPacks: (packId?: string) => string;
     /** Returns the welcome screen for a guild. @param guildId Guild identifier. */
     readonly guildWelcomeScreen: (guildId: string) => string;
     /** Returns the onboarding configuration for a guild. @param guildId Guild identifier. */

package/dist/rest/transport.d.ts

@@ -2,11 +2,16 @@
 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;
+    /** 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 {

package/dist/rest/webhook.d.ts

@@ -1,4 +1,5 @@
-import type { APIEmbed, APIMessage } from "@lunibee/types";
+import { type RESTFileAttachment } from "./index.js";
+import type { APIEmbed, APIMessage, APIMessageComponent } from "@lunibee/types";
 export interface WebhookClientOptions {
     id?: string;
     token?: string;
@@ -12,8 +13,11 @@ export interface WebhookMessageOptions {
     embeds?: (APIEmbed | {
         toJSON(): APIEmbed;
     })[];
-    components?: any[];
-    files?: any[];
+    components?: (APIMessageComponent | {
+        toJSON(): APIMessageComponent;
+    })[];
+    /** Uploaded as multipart form data. */
+    files?: RESTFileAttachment[];
     flags?: number;
     thread_id?: string;
 }
@@ -33,8 +37,8 @@ export declare class WebhookClient {
     /** Edits a previously sent webhook message. */
     editMessage(messageId: string, options: string | {
         content?: string;
-        embeds?: any[];
-    }): Promise<any>;
+        embeds?: APIEmbed[];
+    }): Promise<APIMessage>;
     /** Deletes a previously sent webhook message. */
     deleteMessage(messageId: string): Promise<void>;
 }

package/dist/sharding/bus.d.ts

@@ -1,34 +1,61 @@
+import { type ShardBusTransport } from "./transport.js";
 /** Message envelope exchanged between Lunibee shards. */
 export interface ShardMessage<T = unknown> {
-    /** Sending shard ID. */ source: number;
-    /** Target shard ID, or null for broadcast. */ target: number | null;
-    /** 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;
+    /** Sending shard ID. */
+    source: number;
+    /** Target shard ID, or null for broadcast. */
+    target: number | null;
+    /** 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;
+    /** 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. */
+/** Options for a {@link ShardBus}. */
+export interface ShardBusOptions {
+    /**
+     * How messages travel. Defaults to IPC inside a cluster forked by
+     * `ClusterManager`, and to a `BroadcastChannel` otherwise.
+     */
+    transport?: ShardBusTransport;
+    /** Most requests waiting for a reply at once (default 10,000); more are rejected. */
+    maxPending?: number;
+}
+/** Cross-shard messaging: send, broadcast, and request/reply over a {@link ShardBusTransport}. */
 export declare class ShardBus {
     #private;
-    /** BroadcastChannel name used by this bus. */ readonly channelName: string;
+    /** BroadcastChannel name used by this bus. */
+    readonly channelName: string;
     /** Creates a shard bus. @param shardId Shard ID. @param channelName Application-specific channel name. @throws {RangeError} If shard ID is invalid. @throws {TypeError} If channel name is empty. */
-    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;
+    constructor(shardId: number, channelName: string, options?: ShardBusOptions);
+    /** 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
@@ -49,5 +76,6 @@ export declare class ShardBus {
         timeoutMs?: number;
         expected?: number;
     }): Promise<ShardReply<R>[]>;
-    /** Closes the transport. @returns Nothing. */ close(): void;
+    /** Closes the transport. @returns Nothing. */
+    close(): void;
 }

package/dist/sharding/cluster.d.ts

@@ -1,4 +1,5 @@
 import { type ChildProcess } from "node:child_process";
+import { type SupervisorOptions } from "./supervisor.js";
 /** Configuration for managing multiple shard clusters. */
 export interface ClusterManagerOptions {
     /** Discord bot token. */
@@ -23,6 +24,16 @@ export interface ClusterManagerOptions {
     restartOnExit?: boolean;
     /** Delay in milliseconds before re-forking a crashed cluster. Defaults to 5000. */
     restartDelay?: number;
+    /**
+     * Backoff, jitter and a give-up limit for restarts. `restartDelay` is its
+     * first delay unless it sets its own. The default restarts every crash
+     * after a fixed delay, as before.
+     */
+    supervisor?: Omit<SupervisorOptions, "restartDelay"> & {
+        restartDelay?: number;
+    };
+    /** Called when a cluster crashed more often than `supervisor.maxRestarts` allows and will not be restarted. */
+    onGiveUp?(cluster: ClusterInfo): void;
     /** Called whenever a cluster process exits, before any restart. */
     onClusterExit?(cluster: ClusterInfo, code: number | null, signal: NodeJS.Signals | null): void;
 }

package/dist/sharding/gateway-bot.d.ts

@@ -0,0 +1,18 @@
+/** `/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;
+    };
+}
+/**
+ * Asks Discord for the recommended shard count and the IDENTIFY budget.
+ * @throws {Error} If the request fails or the answer is not usable.
+ */
+export declare function fetchGatewayBot(token: string): Promise<GatewayBotInfo>;

package/dist/sharding/index.d.ts

@@ -1,14 +1,22 @@
+import { type GatewayBotInfo } from "./gateway-bot.js";
 import { Gateway } from "@lunibee/ws";
+export { fetchGatewayBot, type GatewayBotInfo } from "./gateway-bot.js";
 export { ShardBus } from "./bus.js";
-export type { ShardBusErrorHandler, ShardMessage, ShardMessageHandler, ShardReply, } from "./bus.js";
+export { BroadcastChannelTransport, IpcTransport, type IpcEndpoint, type ShardBusTransport, } from "./transport.js";
+export { ShardSupervisor, type SupervisorOptions } from "./supervisor.js";
+export type { ShardBusErrorHandler, ShardBusOptions, 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;
+    /** Bot token. */
+    token: string;
+    /** Gateway intents as an array, e.g. `[GatewayIntentBits.Guilds]`. */
+    intents: ConstructorParameters<typeof Gateway>[0]["intents"];
+    /** 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. Defaults to 5000 to respect
      * Discord's IDENTIFY rate limit (one per 5s per rate-limit key); set 0 to
@@ -23,37 +31,57 @@ export interface ShardManagerOptions {
      * 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;
-    };
+    /** 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;
 }
 /** 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;
+    /** Gateway connection state. */
+    state: Gateway["state"];
+    /** Last heartbeat round-trip in ms, or -1 before the first ACK. */
+    ping: number;
+}
+/** What `ShardManager` emits about its shards. */
+export interface ShardManagerEvents {
+    /** A shard finished its handshake and is receiving events. */
+    shardReady: [shardId: number];
+    /** A shard's connection closed (it may reconnect by itself). */
+    shardDisconnect: [shardId: number, close: {
+        code: number;
+        action: string;
+    }];
+    /** A shard resumed its session after a reconnect. */
+    shardResume: [shardId: number];
+    /** A shard reported an error. */
+    shardError: [shardId: number, error: Error];
+    /** A shard reconnected too often too fast and is backing off (see `Gateway` `unstable`). */
+    shardUnstable: [
+        shardId: number,
+        info: {
+            reconnects: number;
+            delay: number;
+        }
+    ];
 }
 /** Runtime state for a managed shard. */
 export interface ShardInfo {
-    /** Shard identifier. */ id: number;
-    /** Gateway instance. */ gateway: Gateway;
+    /** Shard identifier. */
+    id: number;
+    /** Gateway instance. */
+    gateway: Gateway;
 }
 /** 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;
+    /** 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. */
@@ -68,12 +96,23 @@ export declare class ShardManager {
     reshard(count: number): Promise<void>;
     /** Permanently closes the current shard set and releases Gateway resources. The next connect recreates them. @returns Nothing. */
     destroy(): void;
+    /** Listens for an aggregated shard event. @returns This manager. */
+    on<E extends keyof ShardManagerEvents>(event: E, listener: (...args: ShardManagerEvents[E]) => void): this;
+    /** Stops listening for a shard event. @returns This manager. */
+    off<E extends keyof ShardManagerEvents>(event: E, listener: (...args: ShardManagerEvents[E]) => void): this;
     /** 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;
+    /** Sends a voice state update (op 4) on the shard that owns the guild. @returns Whether it was sent; `false` if that shard is absent or disconnected. */
+    sendVoiceState(guildId: string, channelId: string | null, options?: {
+        selfMute?: boolean;
+        selfDeaf?: boolean;
+    }): boolean;
+    /** 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[];
+    /** Returns information for all managed shards. @returns Shard information snapshots. */
+    values(): ShardInfo[];
 }
 /** Discord.js-familiar alias for {@link ShardManager}. */
 export { ShardManager as ShardingManager };