shardwire 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -59,6 +59,14 @@ interface BridgeThread {
     archived?: boolean;
     locked?: boolean;
 }
+/** Normalized non-thread channel snapshot for channel lifecycle events. */
+interface BridgeChannel {
+    id: Snowflake;
+    type: number;
+    name?: string | null;
+    guildId?: Snowflake;
+    parentId?: Snowflake | null;
+}
 interface BridgeMessage {
     id: Snowflake;
     channelId: Snowflake;
@@ -73,12 +81,18 @@ interface BridgeMessage {
     /** Message component rows (JSON-serializable API shape). */
     components?: APIActionRowComponent<APIComponentInMessageActionRow>[];
     reference?: BridgeMessageReference;
+    /** Discord `ChannelType` when the runtime could resolve `message.channel`. */
+    channelType?: number;
+    /** Parent category (guild text channels) or parent text/forum (threads), when known. */
+    parentChannelId?: Snowflake;
 }
 interface BridgeDeletedMessage {
     id: Snowflake;
     channelId: Snowflake;
     guildId?: Snowflake;
     deletedAt: string;
+    channelType?: number;
+    parentChannelId?: Snowflake;
 }
 interface BridgeReactionEmoji {
     id?: Snowflake;
@@ -92,13 +106,17 @@ interface BridgeMessageReaction {
     user?: BridgeUser;
     emoji: BridgeReactionEmoji;
 }
-type BridgeInteractionKind = "chatInput" | "contextMenu" | "button" | "stringSelect" | "userSelect" | "roleSelect" | "mentionableSelect" | "channelSelect" | "modalSubmit" | "unknown";
+type BridgeInteractionKind = 'chatInput' | 'contextMenu' | 'button' | 'stringSelect' | 'userSelect' | 'roleSelect' | 'mentionableSelect' | 'channelSelect' | 'modalSubmit' | 'unknown';
 interface BridgeInteraction {
     id: Snowflake;
     applicationId: Snowflake;
     kind: BridgeInteractionKind;
     guildId?: Snowflake;
     channelId?: Snowflake;
+    /** Discord `ChannelType` for `channelId` when the runtime resolved the channel. */
+    channelType?: number;
+    /** Parent category or parent text/forum for thread channels, when known. */
+    parentChannelId?: Snowflake;
     user: BridgeUser;
     member?: BridgeGuildMember;
     commandName?: string;
@@ -161,12 +179,32 @@ interface MessageReactionAddEventPayload extends EventEnvelopeBase {
 interface MessageReactionRemoveEventPayload extends EventEnvelopeBase {
     reaction: BridgeMessageReaction;
 }
+interface ChannelCreateEventPayload extends EventEnvelopeBase {
+    channel: BridgeChannel;
+}
+interface ChannelUpdateEventPayload extends EventEnvelopeBase {
+    oldChannel?: BridgeChannel;
+    channel: BridgeChannel;
+}
+interface ChannelDeleteEventPayload extends EventEnvelopeBase {
+    channel: BridgeChannel;
+}
+interface MessageBulkDeleteEventPayload extends EventEnvelopeBase {
+    channelId: Snowflake;
+    guildId: Snowflake;
+    messageIds: Snowflake[];
+    /** Discord `ChannelType` for `channelId` when known. */
+    channelType?: number;
+    /** Parent category or forum/text parent when the channel reports one. */
+    parentChannelId?: Snowflake;
+}
 interface BotEventPayloadMap {
     ready: ReadyEventPayload;
     interactionCreate: InteractionCreateEventPayload;
     messageCreate: MessageCreateEventPayload;
     messageUpdate: MessageUpdateEventPayload;
     messageDelete: MessageDeleteEventPayload;
+    messageBulkDelete: MessageBulkDeleteEventPayload;
     messageReactionAdd: MessageReactionAddEventPayload;
     messageReactionRemove: MessageReactionRemoveEventPayload;
     guildCreate: GuildCreateEventPayload;
@@ -177,6 +215,9 @@ interface BotEventPayloadMap {
     threadCreate: ThreadCreateEventPayload;
     threadUpdate: ThreadUpdateEventPayload;
     threadDelete: ThreadDeleteEventPayload;
+    channelCreate: ChannelCreateEventPayload;
+    channelUpdate: ChannelUpdateEventPayload;
+    channelDelete: ChannelDeleteEventPayload;
 }
 type BotEventName = keyof BotEventPayloadMap;
 interface BridgeMessageInput {
@@ -270,6 +311,53 @@ interface RemoveOwnMessageReactionActionPayload {
     messageId: Snowflake;
     emoji: string;
 }
+interface TimeoutMemberActionPayload {
+    guildId: Snowflake;
+    userId: Snowflake;
+    /** Duration in milliseconds (Discord allows up to 28 days). */
+    durationMs: number;
+    reason?: string;
+}
+interface RemoveMemberTimeoutActionPayload {
+    guildId: Snowflake;
+    userId: Snowflake;
+    reason?: string;
+}
+interface CreateChannelActionPayload {
+    guildId: Snowflake;
+    name: string;
+    /** Discord `ChannelType` (default: `0` guild text). */
+    type?: number;
+    parentId?: Snowflake;
+    topic?: string;
+    reason?: string;
+}
+interface EditChannelActionPayload {
+    channelId: Snowflake;
+    name?: string | null;
+    parentId?: Snowflake | null;
+    topic?: string | null;
+    reason?: string;
+}
+interface DeleteChannelActionPayload {
+    channelId: Snowflake;
+    reason?: string;
+}
+/** `autoArchiveDuration` is in minutes (Discord-supported values). */
+interface CreateThreadActionPayload {
+    parentChannelId: Snowflake;
+    name: string;
+    /** When set, starts a thread on this message (requires a text-based parent). */
+    messageId?: Snowflake;
+    type?: 'public' | 'private';
+    autoArchiveDuration?: 60 | 1440 | 4320 | 10080;
+    reason?: string;
+}
+interface ArchiveThreadActionPayload {
+    threadId: Snowflake;
+    archived?: boolean;
+    reason?: string;
+}
 interface BotActionPayloadMap {
     sendMessage: SendMessageActionPayload;
     editMessage: EditMessageActionPayload;
@@ -290,6 +378,13 @@ interface BotActionPayloadMap {
     removeMemberRole: RemoveMemberRoleActionPayload;
     addMessageReaction: AddMessageReactionActionPayload;
     removeOwnMessageReaction: RemoveOwnMessageReactionActionPayload;
+    timeoutMember: TimeoutMemberActionPayload;
+    removeMemberTimeout: RemoveMemberTimeoutActionPayload;
+    createChannel: CreateChannelActionPayload;
+    editChannel: EditChannelActionPayload;
+    deleteChannel: DeleteChannelActionPayload;
+    createThread: CreateThreadActionPayload;
+    archiveThread: ArchiveThreadActionPayload;
 }
 interface DeleteMessageActionResult {
     deleted: true;
@@ -321,6 +416,10 @@ interface MessageReactionActionResult {
     channelId: Snowflake;
     emoji: string;
 }
+interface DeleteChannelActionResult {
+    deleted: true;
+    channelId: Snowflake;
+}
 interface BotActionResultDataMap {
     sendMessage: BridgeMessage;
     editMessage: BridgeMessage;
@@ -341,6 +440,13 @@ interface BotActionResultDataMap {
     removeMemberRole: BridgeGuildMember;
     addMessageReaction: MessageReactionActionResult;
     removeOwnMessageReaction: MessageReactionActionResult;
+    timeoutMember: MemberModerationActionResult;
+    removeMemberTimeout: BridgeGuildMember;
+    createChannel: BridgeChannel;
+    editChannel: BridgeChannel;
+    deleteChannel: DeleteChannelActionResult;
+    createThread: BridgeThread;
+    archiveThread: BridgeThread;
 }
 type BotActionName = keyof BotActionPayloadMap;
 interface BridgeCapabilities {
@@ -356,14 +462,20 @@ interface EventSubscriptionFilter {
     customId?: string | readonly string[];
     /** Matches `BridgeInteraction.kind`. */
     interactionKind?: BridgeInteractionKind | readonly BridgeInteractionKind[];
+    /** Matches Discord `ChannelType` when present on the payload (messages, interactions, bulk delete). */
+    channelType?: number | readonly number[];
+    /** Matches `BridgeMessage.parentChannelId` / thread parent / channel parent when present. */
+    parentChannelId?: Snowflake | readonly Snowflake[];
+    /** Matches guild thread channels only: same as message `channelId` when `channelType` is a guild thread. */
+    threadId?: Snowflake | readonly Snowflake[];
 }
 interface EventSubscription<K extends BotEventName = BotEventName> {
     name: K;
     filter?: EventSubscriptionFilter;
 }
 interface SecretPermissions {
-    events?: "*" | readonly BotEventName[];
-    actions?: "*" | readonly BotActionName[];
+    events?: '*' | readonly BotEventName[];
+    actions?: '*' | readonly BotActionName[];
 }
 interface ScopedSecretConfig {
     id?: string;
@@ -377,6 +489,8 @@ interface ActionErrorDetails {
     discordCode?: number;
     /** When true, callers may retry with backoff (e.g. rate limits). */
     retryable?: boolean;
+    /** Suggested wait derived from Discord `retry_after` (milliseconds), when available. */
+    retryAfterMs?: number;
     [key: string]: unknown;
 }
 interface BotBridgeOptions {
@@ -395,6 +509,14 @@ interface BotBridgeOptions {
         maxConcurrentActions?: number;
         /** When the queue is full, fail fast with `SERVICE_UNAVAILABLE` (default: 5000). */
         actionQueueTimeoutMs?: number;
+        /**
+         * Where `idempotencyKey` deduplication is scoped (default: `connection`).
+         * - `connection`: same WebSocket connection only (reconnect uses a new scope).
+         * - `secret`: same configured secret id across connections (useful for retries after reconnect).
+         */
+        idempotencyScope?: 'connection' | 'secret';
+        /** TTL for idempotency cache entries in ms (default: 120000). */
+        idempotencyTtlMs?: number;
     };
     logger?: ShardwireLogger;
 }
@@ -405,6 +527,10 @@ interface AppBridgeMetricsHooks {
         durationMs: number;
         ok: boolean;
         errorCode?: string;
+        /** Present when Discord returned HTTP 429 or similar retryable signals. */
+        retryAfterMs?: number;
+        discordStatus?: number;
+        discordCode?: number;
     }) => void;
 }
 interface AppBridgeOptions {
@@ -423,7 +549,7 @@ interface AppBridgeOptions {
     metrics?: AppBridgeMetricsHooks;
 }
 interface ActionError {
-    code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_REQUEST" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE";
+    code: 'UNAUTHORIZED' | 'TIMEOUT' | 'DISCONNECTED' | 'FORBIDDEN' | 'NOT_FOUND' | 'INVALID_REQUEST' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE';
     message: string;
     details?: ActionErrorDetails | unknown;
 }
@@ -441,9 +567,9 @@ interface ActionFailure {
 }
 type ActionResult<T> = ActionSuccess<T> | ActionFailure;
 declare class BridgeCapabilityError extends Error {
-    readonly kind: "event" | "action";
+    readonly kind: 'event' | 'action';
     readonly name: string;
-    constructor(kind: "event" | "action", name: string, message?: string);
+    constructor(kind: 'event' | 'action', name: string, message?: string);
 }
 type EventHandler<K extends BotEventName> = (payload: BotEventPayloadMap[K]) => void;
 type AppBridgeActionInvokeOptions = {
@@ -478,4 +604,4 @@ declare function createBotBridge(options: BotBridgeOptions): BotBridge;
 
 declare function connectBotBridge(options: AppBridgeOptions): AppBridge;
 
-export { type ActionError, type ActionErrorDetails, type ActionFailure, type ActionResult, type ActionSuccess, type AddMemberRoleActionPayload, type AddMessageReactionActionPayload, type AppBridge, type AppBridgeActionInvokeOptions, type AppBridgeActions, type AppBridgeMetricsHooks, type AppBridgeOptions, type BanMemberActionPayload, type BotActionName, type BotActionPayloadMap, type BotActionResultDataMap, type BotBridge, type BotBridgeOptions, type BotBridgeSecret, type BotEventName, type BotEventPayloadMap, type BotIntentName, type BridgeAttachment, type BridgeCapabilities, BridgeCapabilityError, type BridgeDeletedMessage, type BridgeGuild, type BridgeGuildMember, type BridgeInteraction, type BridgeInteractionKind, type BridgeMessage, type BridgeMessageInput, type BridgeMessageReaction, type BridgeMessageReference, type BridgeReactionEmoji, type BridgeThread, type BridgeUser, type DeferInteractionActionPayload, type DeferInteractionActionResult, type DeferUpdateInteractionActionPayload, type DeferUpdateInteractionActionResult, type DeleteInteractionReplyActionPayload, type DeleteInteractionReplyActionResult, type DeleteMessageActionPayload, type DeleteMessageActionResult, type EditInteractionReplyActionPayload, type EditMessageActionPayload, type EventEnvelopeBase, type EventHandler, type EventSubscription, type EventSubscriptionFilter, type FetchMemberActionPayload, type FetchMessageActionPayload, type FollowUpInteractionActionPayload, type GuildCreateEventPayload, type GuildDeleteEventPayload, type GuildMemberAddEventPayload, type GuildMemberRemoveEventPayload, type GuildMemberUpdateEventPayload, type InteractionCreateEventPayload, type KickMemberActionPayload, type MemberModerationActionResult, type MessageCreateEventPayload, type MessageDeleteEventPayload, type MessageReactionActionResult, type MessageReactionAddEventPayload, type MessageReactionRemoveEventPayload, type MessageUpdateEventPayload, type ReadyEventPayload, type RemoveMemberRoleActionPayload, type RemoveOwnMessageReactionActionPayload, type ReplyToInteractionActionPayload, type ScopedSecretConfig, type SecretPermissions, type SendMessageActionPayload, type ShardwireLogger, type ShowModalActionPayload, type ShowModalActionResult, type ThreadCreateEventPayload, type ThreadDeleteEventPayload, type ThreadUpdateEventPayload, type Unsubscribe, type UpdateInteractionActionPayload, connectBotBridge, createBotBridge };
+export { type ActionError, type ActionErrorDetails, type ActionFailure, type ActionResult, type ActionSuccess, type AddMemberRoleActionPayload, type AddMessageReactionActionPayload, type AppBridge, type AppBridgeActionInvokeOptions, type AppBridgeActions, type AppBridgeMetricsHooks, type AppBridgeOptions, type ArchiveThreadActionPayload, type BanMemberActionPayload, type BotActionName, type BotActionPayloadMap, type BotActionResultDataMap, type BotBridge, type BotBridgeOptions, type BotBridgeSecret, type BotEventName, type BotEventPayloadMap, type BotIntentName, type BridgeAttachment, type BridgeCapabilities, BridgeCapabilityError, type BridgeChannel, type BridgeDeletedMessage, type BridgeGuild, type BridgeGuildMember, type BridgeInteraction, type BridgeInteractionKind, type BridgeMessage, type BridgeMessageInput, type BridgeMessageReaction, type BridgeMessageReference, type BridgeReactionEmoji, type BridgeThread, type BridgeUser, type ChannelCreateEventPayload, type ChannelDeleteEventPayload, type ChannelUpdateEventPayload, type CreateChannelActionPayload, type CreateThreadActionPayload, type DeferInteractionActionPayload, type DeferInteractionActionResult, type DeferUpdateInteractionActionPayload, type DeferUpdateInteractionActionResult, type DeleteChannelActionPayload, type DeleteChannelActionResult, type DeleteInteractionReplyActionPayload, type DeleteInteractionReplyActionResult, type DeleteMessageActionPayload, type DeleteMessageActionResult, type EditChannelActionPayload, type EditInteractionReplyActionPayload, type EditMessageActionPayload, type EventEnvelopeBase, type EventHandler, type EventSubscription, type EventSubscriptionFilter, type FetchMemberActionPayload, type FetchMessageActionPayload, type FollowUpInteractionActionPayload, type GuildCreateEventPayload, type GuildDeleteEventPayload, type GuildMemberAddEventPayload, type GuildMemberRemoveEventPayload, type GuildMemberUpdateEventPayload, type InteractionCreateEventPayload, type KickMemberActionPayload, type MemberModerationActionResult, type MessageBulkDeleteEventPayload, type MessageCreateEventPayload, type MessageDeleteEventPayload, type MessageReactionActionResult, type MessageReactionAddEventPayload, type MessageReactionRemoveEventPayload, type MessageUpdateEventPayload, type ReadyEventPayload, type RemoveMemberRoleActionPayload, type RemoveMemberTimeoutActionPayload, type RemoveOwnMessageReactionActionPayload, type ReplyToInteractionActionPayload, type ScopedSecretConfig, type SecretPermissions, type SendMessageActionPayload, type ShardwireLogger, type ShowModalActionPayload, type ShowModalActionResult, type ThreadCreateEventPayload, type ThreadDeleteEventPayload, type ThreadUpdateEventPayload, type TimeoutMemberActionPayload, type Unsubscribe, type UpdateInteractionActionPayload, connectBotBridge, createBotBridge };