shardwire 1.1.0 → 1.2.0

package/README.md

@@ -108,8 +108,14 @@ Apps subscribe to events with `app.on(...)`. The bridge forwards only what each
 - `messageDelete`
 - `messageReactionAdd`
 - `messageReactionRemove`
+- `guildCreate`
+- `guildDelete`
 - `guildMemberAdd`
 - `guildMemberRemove`
+- `guildMemberUpdate`
+- `threadCreate`
+- `threadUpdate`
+- `threadDelete`
 
 Supported filters:
 
@@ -117,13 +123,16 @@ Supported filters:
 - `channelId`
 - `userId`
 - `commandName` (for `interactionCreate`)
+- `customId` (for `interactionCreate`)
+- `interactionKind` (for `interactionCreate`)
 
 ### Intent Notes
 
 - `ready` and `interactionCreate`: no specific event intent requirement
 - `messageCreate`, `messageUpdate`, `messageDelete`: `GuildMessages`
 - `messageReactionAdd`, `messageReactionRemove`: `GuildMessageReactions`
-- `guildMemberAdd`, `guildMemberRemove`: `GuildMembers`
+- `guildCreate`, `guildDelete`, `threadCreate`, `threadUpdate`, `threadDelete`: `Guilds`
+- `guildMemberAdd`, `guildMemberRemove`, `guildMemberUpdate`: `GuildMembers`
 
 ## Built-In Actions
 
@@ -134,7 +143,14 @@ Supported filters:
 - `deleteMessage`
 - `replyToInteraction`
 - `deferInteraction`
+- `deferUpdateInteraction`
 - `followUpInteraction`
+- `editInteractionReply`
+- `deleteInteractionReply`
+- `updateInteraction`
+- `showModal`
+- `fetchMessage`
+- `fetchMember`
 - `banMember`
 - `kickMember`
 - `addMemberRole`
@@ -150,6 +166,31 @@ type ActionResult<T> =
   | { ok: false; requestId: string; ts: number; error: { code: string; message: string; details?: unknown } };
 ```
 
+### Idempotency for safe retries
+
+You can provide an `idempotencyKey` in action options to dedupe repeated requests on the same connection:
+
+```ts
+await app.actions.sendMessage(
+  { channelId: "123456789012345678", content: "Hello once" },
+  { idempotencyKey: "notify:order:123" },
+);
+```
+
+### App-side action metrics
+
+```ts
+const app = connectBotBridge({
+  url: "ws://127.0.0.1:3001/shardwire",
+  secret: process.env.SHARDWIRE_SECRET!,
+  metrics: {
+    onActionComplete(meta) {
+      console.log(meta.name, meta.durationMs, meta.ok, meta.errorCode);
+    },
+  },
+});
+```
+
 ## Secret Scopes
 
 Use a plain string secret for full event/action access:
@@ -225,6 +266,7 @@ Main exports include:
 - Use `wss://` for non-loopback deployments.
 - `ws://` is only accepted for loopback hosts (`127.0.0.1`, `localhost`, `::1`).
 - Event availability depends on enabled intents and secret scope.
+- For vulnerability reporting and security policy, see [`SECURITY.md`](./SECURITY.md).
 
 ## Contributing
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Snowflake, APIEmbed, APIAllowedMentions } from 'discord-api-types/v10';
+import { Snowflake, APIEmbed, APIAllowedMentions, APIActionRowComponent, APIComponentInMessageActionRow, APITextInputComponent } from 'discord-api-types/v10';
 import { GatewayIntentBits } from 'discord.js';
 
 type Unsubscribe = () => void;
@@ -42,6 +42,23 @@ interface BridgeGuildMember {
     pending?: boolean;
     communicationDisabledUntil?: string | null;
 }
+/** Normalized guild snapshot for `guildCreate` / `guildDelete` events. */
+interface BridgeGuild {
+    id: Snowflake;
+    name: string;
+    icon?: string | null;
+    ownerId?: Snowflake;
+}
+/** Normalized thread channel snapshot for thread lifecycle events. */
+interface BridgeThread {
+    id: Snowflake;
+    guildId: Snowflake;
+    parentId: Snowflake | null;
+    name: string;
+    type: number;
+    archived?: boolean;
+    locked?: boolean;
+}
 interface BridgeMessage {
     id: Snowflake;
     channelId: Snowflake;
@@ -53,6 +70,8 @@ interface BridgeMessage {
     editedAt?: string | null;
     attachments: BridgeAttachment[];
     embeds: APIEmbed[];
+    /** Message component rows (JSON-serializable API shape). */
+    components?: APIActionRowComponent<APIComponentInMessageActionRow>[];
     reference?: BridgeMessageReference;
 }
 interface BridgeDeletedMessage {
@@ -91,6 +110,7 @@ interface BridgeInteraction {
 }
 interface EventEnvelopeBase {
     receivedAt: number;
+    /** Populated when the bot runs under `ShardingManager` (multi-shard). */
     shardId?: number;
 }
 interface ReadyEventPayload extends EventEnvelopeBase {
@@ -115,6 +135,26 @@ interface GuildMemberAddEventPayload extends EventEnvelopeBase {
 interface GuildMemberRemoveEventPayload extends EventEnvelopeBase {
     member: BridgeGuildMember;
 }
+interface GuildMemberUpdateEventPayload extends EventEnvelopeBase {
+    oldMember?: BridgeGuildMember;
+    member: BridgeGuildMember;
+}
+interface GuildCreateEventPayload extends EventEnvelopeBase {
+    guild: BridgeGuild;
+}
+interface GuildDeleteEventPayload extends EventEnvelopeBase {
+    guild: BridgeGuild;
+}
+interface ThreadCreateEventPayload extends EventEnvelopeBase {
+    thread: BridgeThread;
+}
+interface ThreadUpdateEventPayload extends EventEnvelopeBase {
+    oldThread?: BridgeThread;
+    thread: BridgeThread;
+}
+interface ThreadDeleteEventPayload extends EventEnvelopeBase {
+    thread: BridgeThread;
+}
 interface MessageReactionAddEventPayload extends EventEnvelopeBase {
     reaction: BridgeMessageReaction;
 }
@@ -129,14 +169,24 @@ interface BotEventPayloadMap {
     messageDelete: MessageDeleteEventPayload;
     messageReactionAdd: MessageReactionAddEventPayload;
     messageReactionRemove: MessageReactionRemoveEventPayload;
+    guildCreate: GuildCreateEventPayload;
+    guildDelete: GuildDeleteEventPayload;
     guildMemberAdd: GuildMemberAddEventPayload;
     guildMemberRemove: GuildMemberRemoveEventPayload;
+    guildMemberUpdate: GuildMemberUpdateEventPayload;
+    threadCreate: ThreadCreateEventPayload;
+    threadUpdate: ThreadUpdateEventPayload;
+    threadDelete: ThreadDeleteEventPayload;
 }
 type BotEventName = keyof BotEventPayloadMap;
 interface BridgeMessageInput {
     content?: string;
     embeds?: APIEmbed[];
     allowedMentions?: APIAllowedMentions;
+    components?: APIActionRowComponent<APIComponentInMessageActionRow>[];
+    /** Bitfield compatible with `MessageFlags` from discord.js / Discord API. */
+    flags?: number;
+    stickerIds?: Snowflake[];
 }
 interface SendMessageActionPayload extends BridgeMessageInput {
     channelId: Snowflake;
@@ -161,6 +211,32 @@ interface FollowUpInteractionActionPayload extends BridgeMessageInput {
     interactionId: Snowflake;
     ephemeral?: boolean;
 }
+interface DeferUpdateInteractionActionPayload {
+    interactionId: Snowflake;
+}
+interface EditInteractionReplyActionPayload extends BridgeMessageInput {
+    interactionId: Snowflake;
+}
+interface DeleteInteractionReplyActionPayload {
+    interactionId: Snowflake;
+}
+interface UpdateInteractionActionPayload extends BridgeMessageInput {
+    interactionId: Snowflake;
+}
+interface ShowModalActionPayload {
+    interactionId: Snowflake;
+    title: string;
+    customId: string;
+    components: APIActionRowComponent<APITextInputComponent>[];
+}
+interface FetchMessageActionPayload {
+    channelId: Snowflake;
+    messageId: Snowflake;
+}
+interface FetchMemberActionPayload {
+    guildId: Snowflake;
+    userId: Snowflake;
+}
 interface BanMemberActionPayload {
     guildId: Snowflake;
     userId: Snowflake;
@@ -200,7 +276,14 @@ interface BotActionPayloadMap {
     deleteMessage: DeleteMessageActionPayload;
     replyToInteraction: ReplyToInteractionActionPayload;
     deferInteraction: DeferInteractionActionPayload;
+    deferUpdateInteraction: DeferUpdateInteractionActionPayload;
     followUpInteraction: FollowUpInteractionActionPayload;
+    editInteractionReply: EditInteractionReplyActionPayload;
+    deleteInteractionReply: DeleteInteractionReplyActionPayload;
+    updateInteraction: UpdateInteractionActionPayload;
+    showModal: ShowModalActionPayload;
+    fetchMessage: FetchMessageActionPayload;
+    fetchMember: FetchMemberActionPayload;
     banMember: BanMemberActionPayload;
     kickMember: KickMemberActionPayload;
     addMemberRole: AddMemberRoleActionPayload;
@@ -217,6 +300,18 @@ interface DeferInteractionActionResult {
     deferred: true;
     interactionId: Snowflake;
 }
+interface DeferUpdateInteractionActionResult {
+    deferred: true;
+    interactionId: Snowflake;
+}
+interface DeleteInteractionReplyActionResult {
+    deleted: true;
+    interactionId: Snowflake;
+}
+interface ShowModalActionResult {
+    shown: true;
+    interactionId: Snowflake;
+}
 interface MemberModerationActionResult {
     guildId: Snowflake;
     userId: Snowflake;
@@ -232,7 +327,14 @@ interface BotActionResultDataMap {
     deleteMessage: DeleteMessageActionResult;
     replyToInteraction: BridgeMessage;
     deferInteraction: DeferInteractionActionResult;
+    deferUpdateInteraction: DeferUpdateInteractionActionResult;
     followUpInteraction: BridgeMessage;
+    editInteractionReply: BridgeMessage;
+    deleteInteractionReply: DeleteInteractionReplyActionResult;
+    updateInteraction: BridgeMessage;
+    showModal: ShowModalActionResult;
+    fetchMessage: BridgeMessage;
+    fetchMember: BridgeGuildMember;
     banMember: MemberModerationActionResult;
     kickMember: MemberModerationActionResult;
     addMemberRole: BridgeGuildMember;
@@ -250,6 +352,10 @@ interface EventSubscriptionFilter {
     channelId?: Snowflake | readonly Snowflake[];
     userId?: Snowflake | readonly Snowflake[];
     commandName?: string | readonly string[];
+    /** Matches `BridgeInteraction.customId` when present (components, modals). */
+    customId?: string | readonly string[];
+    /** Matches `BridgeInteraction.kind`. */
+    interactionKind?: BridgeInteractionKind | readonly BridgeInteractionKind[];
 }
 interface EventSubscription<K extends BotEventName = BotEventName> {
     name: K;
@@ -265,6 +371,14 @@ interface ScopedSecretConfig {
     allow?: SecretPermissions;
 }
 type BotBridgeSecret = string | ScopedSecretConfig;
+/** Structured Discord / transport context for failed actions (machine-readable). */
+interface ActionErrorDetails {
+    discordStatus?: number;
+    discordCode?: number;
+    /** When true, callers may retry with backoff (e.g. rate limits). */
+    retryable?: boolean;
+    [key: string]: unknown;
+}
 interface BotBridgeOptions {
     token: string;
     intents: readonly BotIntentName[];
@@ -275,9 +389,24 @@ interface BotBridgeOptions {
         heartbeatMs?: number;
         maxPayloadBytes?: number;
         secrets: readonly BotBridgeSecret[];
+        /** Reject new TCP connections when authenticated client count reaches this cap (default: unlimited). */
+        maxConnections?: number;
+        /** Max concurrent action executions per bot process (default: 32). */
+        maxConcurrentActions?: number;
+        /** When the queue is full, fail fast with `SERVICE_UNAVAILABLE` (default: 5000). */
+        actionQueueTimeoutMs?: number;
     };
     logger?: ShardwireLogger;
 }
+interface AppBridgeMetricsHooks {
+    onActionComplete?: (meta: {
+        name: BotActionName;
+        requestId: string;
+        durationMs: number;
+        ok: boolean;
+        errorCode?: string;
+    }) => void;
+}
 interface AppBridgeOptions {
     url: string;
     secret: string;
@@ -291,11 +420,12 @@ interface AppBridgeOptions {
     };
     requestTimeoutMs?: number;
     logger?: ShardwireLogger;
+    metrics?: AppBridgeMetricsHooks;
 }
 interface ActionError {
-    code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_REQUEST" | "INTERNAL_ERROR";
+    code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_REQUEST" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE";
     message: string;
-    details?: unknown;
+    details?: ActionErrorDetails | unknown;
 }
 interface ActionSuccess<T> {
     ok: true;
@@ -316,11 +446,14 @@ declare class BridgeCapabilityError extends Error {
     constructor(kind: "event" | "action", name: string, message?: string);
 }
 type EventHandler<K extends BotEventName> = (payload: BotEventPayloadMap[K]) => void;
+type AppBridgeActionInvokeOptions = {
+    timeoutMs?: number;
+    requestId?: string;
+    /** When set, duplicate keys within TTL return the first result (best-effort idempotency). */
+    idempotencyKey?: string;
+};
 type AppBridgeActions = {
-    [K in BotActionName]: (payload: BotActionPayloadMap[K], options?: {
-        timeoutMs?: number;
-        requestId?: string;
-    }) => Promise<ActionResult<BotActionResultDataMap[K]>>;
+    [K in BotActionName]: (payload: BotActionPayloadMap[K], options?: AppBridgeActionInvokeOptions) => Promise<ActionResult<BotActionResultDataMap[K]>>;
 };
 interface BotBridge {
     ready(): Promise<void>;
@@ -345,4 +478,4 @@ declare function createBotBridge(options: BotBridgeOptions): BotBridge;
 
 declare function connectBotBridge(options: AppBridgeOptions): AppBridge;
 
-export { type ActionError, type ActionFailure, type ActionResult, type ActionSuccess, type AddMemberRoleActionPayload, type AddMessageReactionActionPayload, type AppBridge, type AppBridgeActions, 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 BridgeGuildMember, type BridgeInteraction, type BridgeInteractionKind, type BridgeMessage, type BridgeMessageInput, type BridgeMessageReaction, type BridgeMessageReference, type BridgeReactionEmoji, type BridgeUser, type DeferInteractionActionPayload, type DeleteMessageActionPayload, type EditMessageActionPayload, type EventEnvelopeBase, type EventHandler, type EventSubscription, type EventSubscriptionFilter, type FollowUpInteractionActionPayload, type GuildMemberAddEventPayload, type GuildMemberRemoveEventPayload, type InteractionCreateEventPayload, type KickMemberActionPayload, 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 Unsubscribe, 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 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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Snowflake, APIEmbed, APIAllowedMentions } from 'discord-api-types/v10';
+import { Snowflake, APIEmbed, APIAllowedMentions, APIActionRowComponent, APIComponentInMessageActionRow, APITextInputComponent } from 'discord-api-types/v10';
 import { GatewayIntentBits } from 'discord.js';
 
 type Unsubscribe = () => void;
@@ -42,6 +42,23 @@ interface BridgeGuildMember {
     pending?: boolean;
     communicationDisabledUntil?: string | null;
 }
+/** Normalized guild snapshot for `guildCreate` / `guildDelete` events. */
+interface BridgeGuild {
+    id: Snowflake;
+    name: string;
+    icon?: string | null;
+    ownerId?: Snowflake;
+}
+/** Normalized thread channel snapshot for thread lifecycle events. */
+interface BridgeThread {
+    id: Snowflake;
+    guildId: Snowflake;
+    parentId: Snowflake | null;
+    name: string;
+    type: number;
+    archived?: boolean;
+    locked?: boolean;
+}
 interface BridgeMessage {
     id: Snowflake;
     channelId: Snowflake;
@@ -53,6 +70,8 @@ interface BridgeMessage {
     editedAt?: string | null;
     attachments: BridgeAttachment[];
     embeds: APIEmbed[];
+    /** Message component rows (JSON-serializable API shape). */
+    components?: APIActionRowComponent<APIComponentInMessageActionRow>[];
     reference?: BridgeMessageReference;
 }
 interface BridgeDeletedMessage {
@@ -91,6 +110,7 @@ interface BridgeInteraction {
 }
 interface EventEnvelopeBase {
     receivedAt: number;
+    /** Populated when the bot runs under `ShardingManager` (multi-shard). */
     shardId?: number;
 }
 interface ReadyEventPayload extends EventEnvelopeBase {
@@ -115,6 +135,26 @@ interface GuildMemberAddEventPayload extends EventEnvelopeBase {
 interface GuildMemberRemoveEventPayload extends EventEnvelopeBase {
     member: BridgeGuildMember;
 }
+interface GuildMemberUpdateEventPayload extends EventEnvelopeBase {
+    oldMember?: BridgeGuildMember;
+    member: BridgeGuildMember;
+}
+interface GuildCreateEventPayload extends EventEnvelopeBase {
+    guild: BridgeGuild;
+}
+interface GuildDeleteEventPayload extends EventEnvelopeBase {
+    guild: BridgeGuild;
+}
+interface ThreadCreateEventPayload extends EventEnvelopeBase {
+    thread: BridgeThread;
+}
+interface ThreadUpdateEventPayload extends EventEnvelopeBase {
+    oldThread?: BridgeThread;
+    thread: BridgeThread;
+}
+interface ThreadDeleteEventPayload extends EventEnvelopeBase {
+    thread: BridgeThread;
+}
 interface MessageReactionAddEventPayload extends EventEnvelopeBase {
     reaction: BridgeMessageReaction;
 }
@@ -129,14 +169,24 @@ interface BotEventPayloadMap {
     messageDelete: MessageDeleteEventPayload;
     messageReactionAdd: MessageReactionAddEventPayload;
     messageReactionRemove: MessageReactionRemoveEventPayload;
+    guildCreate: GuildCreateEventPayload;
+    guildDelete: GuildDeleteEventPayload;
     guildMemberAdd: GuildMemberAddEventPayload;
     guildMemberRemove: GuildMemberRemoveEventPayload;
+    guildMemberUpdate: GuildMemberUpdateEventPayload;
+    threadCreate: ThreadCreateEventPayload;
+    threadUpdate: ThreadUpdateEventPayload;
+    threadDelete: ThreadDeleteEventPayload;
 }
 type BotEventName = keyof BotEventPayloadMap;
 interface BridgeMessageInput {
     content?: string;
     embeds?: APIEmbed[];
     allowedMentions?: APIAllowedMentions;
+    components?: APIActionRowComponent<APIComponentInMessageActionRow>[];
+    /** Bitfield compatible with `MessageFlags` from discord.js / Discord API. */
+    flags?: number;
+    stickerIds?: Snowflake[];
 }
 interface SendMessageActionPayload extends BridgeMessageInput {
     channelId: Snowflake;
@@ -161,6 +211,32 @@ interface FollowUpInteractionActionPayload extends BridgeMessageInput {
     interactionId: Snowflake;
     ephemeral?: boolean;
 }
+interface DeferUpdateInteractionActionPayload {
+    interactionId: Snowflake;
+}
+interface EditInteractionReplyActionPayload extends BridgeMessageInput {
+    interactionId: Snowflake;
+}
+interface DeleteInteractionReplyActionPayload {
+    interactionId: Snowflake;
+}
+interface UpdateInteractionActionPayload extends BridgeMessageInput {
+    interactionId: Snowflake;
+}
+interface ShowModalActionPayload {
+    interactionId: Snowflake;
+    title: string;
+    customId: string;
+    components: APIActionRowComponent<APITextInputComponent>[];
+}
+interface FetchMessageActionPayload {
+    channelId: Snowflake;
+    messageId: Snowflake;
+}
+interface FetchMemberActionPayload {
+    guildId: Snowflake;
+    userId: Snowflake;
+}
 interface BanMemberActionPayload {
     guildId: Snowflake;
     userId: Snowflake;
@@ -200,7 +276,14 @@ interface BotActionPayloadMap {
     deleteMessage: DeleteMessageActionPayload;
     replyToInteraction: ReplyToInteractionActionPayload;
     deferInteraction: DeferInteractionActionPayload;
+    deferUpdateInteraction: DeferUpdateInteractionActionPayload;
     followUpInteraction: FollowUpInteractionActionPayload;
+    editInteractionReply: EditInteractionReplyActionPayload;
+    deleteInteractionReply: DeleteInteractionReplyActionPayload;
+    updateInteraction: UpdateInteractionActionPayload;
+    showModal: ShowModalActionPayload;
+    fetchMessage: FetchMessageActionPayload;
+    fetchMember: FetchMemberActionPayload;
     banMember: BanMemberActionPayload;
     kickMember: KickMemberActionPayload;
     addMemberRole: AddMemberRoleActionPayload;
@@ -217,6 +300,18 @@ interface DeferInteractionActionResult {
     deferred: true;
     interactionId: Snowflake;
 }
+interface DeferUpdateInteractionActionResult {
+    deferred: true;
+    interactionId: Snowflake;
+}
+interface DeleteInteractionReplyActionResult {
+    deleted: true;
+    interactionId: Snowflake;
+}
+interface ShowModalActionResult {
+    shown: true;
+    interactionId: Snowflake;
+}
 interface MemberModerationActionResult {
     guildId: Snowflake;
     userId: Snowflake;
@@ -232,7 +327,14 @@ interface BotActionResultDataMap {
     deleteMessage: DeleteMessageActionResult;
     replyToInteraction: BridgeMessage;
     deferInteraction: DeferInteractionActionResult;
+    deferUpdateInteraction: DeferUpdateInteractionActionResult;
     followUpInteraction: BridgeMessage;
+    editInteractionReply: BridgeMessage;
+    deleteInteractionReply: DeleteInteractionReplyActionResult;
+    updateInteraction: BridgeMessage;
+    showModal: ShowModalActionResult;
+    fetchMessage: BridgeMessage;
+    fetchMember: BridgeGuildMember;
     banMember: MemberModerationActionResult;
     kickMember: MemberModerationActionResult;
     addMemberRole: BridgeGuildMember;
@@ -250,6 +352,10 @@ interface EventSubscriptionFilter {
     channelId?: Snowflake | readonly Snowflake[];
     userId?: Snowflake | readonly Snowflake[];
     commandName?: string | readonly string[];
+    /** Matches `BridgeInteraction.customId` when present (components, modals). */
+    customId?: string | readonly string[];
+    /** Matches `BridgeInteraction.kind`. */
+    interactionKind?: BridgeInteractionKind | readonly BridgeInteractionKind[];
 }
 interface EventSubscription<K extends BotEventName = BotEventName> {
     name: K;
@@ -265,6 +371,14 @@ interface ScopedSecretConfig {
     allow?: SecretPermissions;
 }
 type BotBridgeSecret = string | ScopedSecretConfig;
+/** Structured Discord / transport context for failed actions (machine-readable). */
+interface ActionErrorDetails {
+    discordStatus?: number;
+    discordCode?: number;
+    /** When true, callers may retry with backoff (e.g. rate limits). */
+    retryable?: boolean;
+    [key: string]: unknown;
+}
 interface BotBridgeOptions {
     token: string;
     intents: readonly BotIntentName[];
@@ -275,9 +389,24 @@ interface BotBridgeOptions {
         heartbeatMs?: number;
         maxPayloadBytes?: number;
         secrets: readonly BotBridgeSecret[];
+        /** Reject new TCP connections when authenticated client count reaches this cap (default: unlimited). */
+        maxConnections?: number;
+        /** Max concurrent action executions per bot process (default: 32). */
+        maxConcurrentActions?: number;
+        /** When the queue is full, fail fast with `SERVICE_UNAVAILABLE` (default: 5000). */
+        actionQueueTimeoutMs?: number;
     };
     logger?: ShardwireLogger;
 }
+interface AppBridgeMetricsHooks {
+    onActionComplete?: (meta: {
+        name: BotActionName;
+        requestId: string;
+        durationMs: number;
+        ok: boolean;
+        errorCode?: string;
+    }) => void;
+}
 interface AppBridgeOptions {
     url: string;
     secret: string;
@@ -291,11 +420,12 @@ interface AppBridgeOptions {
     };
     requestTimeoutMs?: number;
     logger?: ShardwireLogger;
+    metrics?: AppBridgeMetricsHooks;
 }
 interface ActionError {
-    code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_REQUEST" | "INTERNAL_ERROR";
+    code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "FORBIDDEN" | "NOT_FOUND" | "INVALID_REQUEST" | "INTERNAL_ERROR" | "SERVICE_UNAVAILABLE";
     message: string;
-    details?: unknown;
+    details?: ActionErrorDetails | unknown;
 }
 interface ActionSuccess<T> {
     ok: true;
@@ -316,11 +446,14 @@ declare class BridgeCapabilityError extends Error {
     constructor(kind: "event" | "action", name: string, message?: string);
 }
 type EventHandler<K extends BotEventName> = (payload: BotEventPayloadMap[K]) => void;
+type AppBridgeActionInvokeOptions = {
+    timeoutMs?: number;
+    requestId?: string;
+    /** When set, duplicate keys within TTL return the first result (best-effort idempotency). */
+    idempotencyKey?: string;
+};
 type AppBridgeActions = {
-    [K in BotActionName]: (payload: BotActionPayloadMap[K], options?: {
-        timeoutMs?: number;
-        requestId?: string;
-    }) => Promise<ActionResult<BotActionResultDataMap[K]>>;
+    [K in BotActionName]: (payload: BotActionPayloadMap[K], options?: AppBridgeActionInvokeOptions) => Promise<ActionResult<BotActionResultDataMap[K]>>;
 };
 interface BotBridge {
     ready(): Promise<void>;
@@ -345,4 +478,4 @@ declare function createBotBridge(options: BotBridgeOptions): BotBridge;
 
 declare function connectBotBridge(options: AppBridgeOptions): AppBridge;
 
-export { type ActionError, type ActionFailure, type ActionResult, type ActionSuccess, type AddMemberRoleActionPayload, type AddMessageReactionActionPayload, type AppBridge, type AppBridgeActions, 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 BridgeGuildMember, type BridgeInteraction, type BridgeInteractionKind, type BridgeMessage, type BridgeMessageInput, type BridgeMessageReaction, type BridgeMessageReference, type BridgeReactionEmoji, type BridgeUser, type DeferInteractionActionPayload, type DeleteMessageActionPayload, type EditMessageActionPayload, type EventEnvelopeBase, type EventHandler, type EventSubscription, type EventSubscriptionFilter, type FollowUpInteractionActionPayload, type GuildMemberAddEventPayload, type GuildMemberRemoveEventPayload, type InteractionCreateEventPayload, type KickMemberActionPayload, 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 Unsubscribe, 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 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 };