lunibee 0.3.1 → 0.3.3

package/dist/rest/webhook.d.ts

@@ -1,10 +1,12 @@
 import { type RESTFileAttachment } from "./index.js";
-import type { APIEmbed, APIMessage, APIMessageComponent } from "@lunibee/types";
+import type { AllowedMentions, APIEmbed, APIMessage, APIMessageComponent } from "@lunibee/types";
+/** Where a `WebhookClient` sends: a Discord webhook `url`, or its `id` and `token`. */
 export interface WebhookClientOptions {
     id?: string;
     token?: string;
     url?: string;
 }
+/** A webhook message for `send()` and `editMessage()`; camelCase aliases (`avatarURL`, `threadId`, `allowedMentions`) are accepted beside the wire names. */
 export interface WebhookMessageOptions {
     content?: string;
     username?: string;
@@ -20,6 +22,13 @@ export interface WebhookMessageOptions {
     files?: RESTFileAttachment[];
     flags?: number;
     thread_id?: string;
+    /** Discord.js-familiar alias of `avatar_url`. */
+    avatarURL?: string;
+    /** Discord.js-familiar alias of `thread_id`. */
+    threadId?: string;
+    /** Discord.js-familiar alias of `allowed_mentions`. */
+    allowedMentions?: AllowedMentions;
+    allowed_mentions?: AllowedMentions;
 }
 /** Standalone client for sending Discord webhooks. */
 export declare class WebhookClient {
@@ -34,11 +43,14 @@ export declare class WebhookClient {
     });
     /** Sends a message to the webhook. */
     send(options: string | WebhookMessageOptions): Promise<APIMessage>;
-    /** Edits a previously sent webhook message. */
-    editMessage(messageId: string, options: string | {
-        content?: string;
-        embeds?: APIEmbed[];
+    /** Fetches a message this webhook sent (`threadId` for a message inside a thread). */
+    fetchMessage(messageId: string, options?: {
+        threadId?: string;
     }): Promise<APIMessage>;
+    /** Edits a previously sent webhook message. Takes the same options as {@link WebhookClient.send}, files included. */
+    editMessage(messageId: string, options: string | WebhookMessageOptions): Promise<APIMessage>;
     /** Deletes a previously sent webhook message. */
-    deleteMessage(messageId: string): Promise<void>;
+    deleteMessage(messageId: string, options?: {
+        threadId?: string;
+    }): Promise<void>;
 }

package/dist/sharding/bus.d.ts

@@ -55,7 +55,7 @@ export declare class ShardBus {
     /** 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;
+    off<T>(type: string, handler: ShardMessageHandler<T> | ((data: T, message: ShardMessage<T>) => unknown)): 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. */
@@ -78,7 +78,9 @@ export declare class ShardBus {
     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).
+     * `expected` have arrived or `timeoutMs` elapses. A timeout or a shard
+     * going away does not reject; a closed bus, a blank type or too many
+     * pending requests does.
      */
     broadcastRequest<R = unknown, T = unknown>(type: string, data: T, options?: {
         timeoutMs?: number;

package/dist/sharding/cluster.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess } from "node:child_process";
 import { type ShardReply } from "./bus.js";
 import type { ClusterManagerHealth, ClusterState, WorkerReport } from "./health.js";
+import type { LeaderLock } from "./leader.js";
 import { type HostStatus, type RemoteOptions } from "./remote.js";
 import { type SupervisorOptions } from "./supervisor.js";
 /** Configuration for managing multiple shard clusters. */
@@ -82,6 +83,22 @@ export interface ClusterManagerOptions {
      * workers like local ones. See {@link RemoteOptions}.
      */
     remote?: RemoteOptions;
+    /**
+     * Run several coordinators of one deployment, one active at a time, so a
+     * standby takes over when the active one dies (`RedisLeaderLock`, or your
+     * own {@link LeaderLock}). `spawn()` waits until this coordinator holds
+     * the lock. The leader renews it every quarter of `ttl`; if it cannot for
+     * half of `ttl` (or another holds it) it kills every cluster at once,
+     * closes the host listener, and waits to lead again. A new leader waits
+     * two `remote.lease`s before it starts clusters, so the previous leader's
+     * hosts have fenced themselves. Point hosts at every coordinator
+     * (`ClusterHost` `url` as a list).
+     */
+    leader?: {
+        lock: LeaderLock;
+        /** Lock lifetime in ms. Default 10,000; at least 100. */
+        ttl?: number;
+    };
     /** Starts a worker process. Defaults to `child_process.fork()`; replace it for tests or custom launchers. */
     fork?: (script: string, env: Record<string, string | undefined>) => ChildProcess;
     /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. */
@@ -179,6 +196,15 @@ export interface ClusterManagerEvents {
     hostJoin: [hostId: string];
     /** A host left or was lost. Its clusters are treated as crashed. */
     hostLeave: [hostId: string, reason: string];
+    /** A lost host's cluster is restarting on another host (`remote.moveClusters`). */
+    clusterMoved: [cluster: ClusterInfo, info: {
+        from: string;
+        to: string;
+    }];
+    /** This coordinator took the `leader` lock and will start the clusters. */
+    leaderAcquired: [];
+    /** This coordinator lost the `leader` lock and killed its clusters; it waits to lead again. */
+    leaderLost: [reason: string];
     /** An IDENTIFY is waiting for the session-start budget to reset. */
     identifyWait: [info: {
         shardId: number;
@@ -238,6 +264,8 @@ export declare class ClusterManager {
      * @throws {Error} If called from a cluster worker (a worker must not start the fleet again).
      */
     spawn(): Promise<void>;
+    /** Whether this coordinator holds the `leader` lock; always true without `leader`. */
+    get isLeader(): boolean;
     /** The port hosts connect to, once the listener is open (useful with `remote.port: 0`). */
     get remotePort(): number | undefined;
     /** The hosts of this deployment: connected or not, and the clusters on each. Empty without `remote`. */
@@ -287,6 +315,6 @@ export declare class ClusterManager {
      * @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. */
+    /** Immediately sends SIGTERM to every cluster process (no grace period, no SIGKILL escalation) and clears the cluster map. Prefer {@link shutdownAll} for a graceful stop. */
     killAll(): void;
 }

package/dist/sharding/health.d.ts

@@ -78,7 +78,7 @@ export interface ClusterHealth {
     lastReadyAt?: number;
     /** Per-shard health from the worker's last report. Empty until it reports. */
     shards: ShardHealth[];
-    /** Present when requested with `health({ metrics: true })` and the worker answered. */
+    /** Present when requested with `refreshHealth({ metrics: true })` and the worker answered. */
     metrics?: WorkerMetrics;
     /** When `shards` and `metrics` were reported (epoch ms). */
     reportedAt?: number;

package/dist/sharding/host.d.ts

@@ -1,8 +1,13 @@
 import type { ChildProcess } from "node:child_process";
 /** Options for a {@link ClusterHost}. */
 export interface ClusterHostOptions {
-    /** The coordinator's address: `wss://host:port`. `ws://` is accepted for this machine, or anywhere with `allowInsecure`. */
-    url: string;
+    /**
+     * The coordinator's address: `wss://host:port`. `ws://` is accepted for
+     * this machine, or anywhere with `allowInsecure`. A list names every
+     * coordinator of a deployment with a `leader` lock: the host tries them in
+     * turn, and moves to the next whenever one cannot be reached or drops it.
+     */
+    url: string | string[];
     /** Connect with `ws://` to a coordinator on another machine, over a network you fully trust. Default false. */
     allowInsecure?: boolean;
     /** The coordinator's shared secret. */
@@ -20,6 +25,12 @@ export interface ClusterHostOptions {
     reconnectDelay?: number;
     /** Longest delay between reconnect attempts, in ms. Default 30,000. */
     maxReconnectDelay?: number;
+    /**
+     * Attempts `connect()` makes while the coordinator is busy (it answers
+     * "too many connections" or the hello timed out) before it gives up.
+     * Default 10. A refusal (bad secret, unknown or duplicate id) is final.
+     */
+    connectAttempts?: number;
 }
 /** What a {@link ClusterHost} emits. */
 export interface ClusterHostEvents {

package/dist/sharding/identify.d.ts

@@ -6,6 +6,8 @@ export interface IdentifyBudget {
     remaining: number;
     /** Milliseconds until `remaining` resets, counted from construction. */
     resetAfter: number;
+    /** Milliseconds between resets after that one. Discord resets the budget every 24 hours (the default). */
+    period?: number;
 }
 /** Options for an {@link IdentifyCoordinator}. */
 export interface IdentifyCoordinatorOptions {

package/dist/sharding/index.d.ts

@@ -12,8 +12,10 @@ export { ClusterManager } from "./cluster.js";
 export type { ClusterManagerOptions, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, } from "./cluster.js";
 export { allocateShards, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
 export { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { threadEndpoint, threadFork, type ThreadEndpoint, type ThreadForkOptions, } from "./thread.js";
 export { ClusterHost, type ClusterHostEvents, type ClusterHostOptions, } from "./host.js";
 export type { HostStatus, RemoteOptions } from "./remote.js";
+export { RedisLeaderLock, type LeaderLock, type LeaderRedisClient, type RedisLeaderLockOptions, } from "./leader.js";
 export { RemoteClose, REMOTE_PROTOCOL_VERSION } from "./remote-protocol.js";
 export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, } from "./identify.js";
 export { RequestTracker } from "./requests.js";
@@ -91,6 +93,12 @@ export interface ShardManagerEvents {
     shardError: [shardId: number, error: Error];
     /** Every shard this manager owns is ready. Emitted again after a shard drops and recovers. */
     ready: [];
+    /**
+     * A shard's `Gateway` was created and has not connected yet: attach dispatch
+     * listeners here so none of its events are missed. Fires again for the new
+     * Gateways after `destroy()` + `connect()` or `reshard()`.
+     */
+    shardCreate: [shardId: number, gateway: Gateway];
     /** A shard reconnected too often too fast and is backing off (see `Gateway` `unstable`). */
     shardUnstable: [
         shardId: number,