shardwire 1.2.0 → 1.3.0

package/README.md

@@ -30,43 +30,49 @@ Shardwire is built for a common architecture: your Discord bot runs in one proce
 npm install shardwire
 ```
 
+## Documentation
+
+- [Deployment (TLS, nginx, limits, shutdown)](./docs/deployment.md)
+- [Troubleshooting (auth, capabilities, action errors)](./docs/troubleshooting.md)
+- [Patterns (moderation, interactions, multi-secret)](./docs/patterns.md)
+
 ## Quick Start
 
 ### 1) Start the bot bridge process
 
 ```ts
-import { createBotBridge } from "shardwire";
+import { createBotBridge } from 'shardwire';
 
 const bridge = createBotBridge({
-  token: process.env.DISCORD_TOKEN!,
-  intents: ["Guilds", "GuildMessages", "GuildMessageReactions", "MessageContent", "GuildMembers"],
-  server: {
-    port: 3001,
-    secrets: [process.env.SHARDWIRE_SECRET!],
-  },
+	token: process.env.DISCORD_TOKEN!,
+	intents: ['Guilds', 'GuildMessages', 'GuildMessageReactions', 'MessageContent', 'GuildMembers'],
+	server: {
+		port: 3001,
+		secrets: [process.env.SHARDWIRE_SECRET!],
+	},
 });
 
 await bridge.ready();
-console.log("Bot bridge listening on ws://127.0.0.1:3001/shardwire");
+console.log('Bot bridge listening on ws://127.0.0.1:3001/shardwire');
 ```
 
 ### 2) Connect from your app process
 
 ```ts
-import { connectBotBridge } from "shardwire";
+import { connectBotBridge } from 'shardwire';
 
 const app = connectBotBridge({
-  url: "ws://127.0.0.1:3001/shardwire",
-  secret: process.env.SHARDWIRE_SECRET!,
-  appName: "dashboard",
+	url: 'ws://127.0.0.1:3001/shardwire',
+	secret: process.env.SHARDWIRE_SECRET!,
+	appName: 'dashboard',
 });
 
-app.on("ready", ({ user }) => {
-  console.log("Bot ready as", user.username);
+app.on('ready', ({ user }) => {
+	console.log('Bot ready as', user.username);
 });
 
-app.on("messageCreate", ({ message }) => {
-  console.log(message.channelId, message.content);
+app.on('messageCreate', ({ message }) => {
+	console.log(message.channelId, message.content);
 });
 
 await app.ready();
@@ -76,12 +82,12 @@ await app.ready();
 
 ```ts
 const result = await app.actions.sendMessage({
-  channelId: "123456789012345678",
-  content: "Hello from app side",
+	channelId: '123456789012345678',
+	content: 'Hello from app side',
 });
 
 if (!result.ok) {
-  console.error(result.error.code, result.error.message);
+	console.error(result.error.code, result.error.message);
 }
 ```
 
@@ -89,14 +95,20 @@ if (!result.ok) {
 
 ```ts
 app.on(
-  "messageCreate",
-  ({ message }) => {
-    console.log("Only this channel:", message.content);
-  },
-  { channelId: "123456789012345678" },
+	'messageCreate',
+	({ message }) => {
+		console.log('Only this channel:', message.content);
+	},
+	{ channelId: '123456789012345678' },
 );
 ```
 
+## Startup lifecycle
+
+- **`createBotBridge(...)`** starts the WebSocket server immediately; `await bridge.ready()` resolves when the Discord client has finished its initial `ready` handshake (same timing you would expect from a normal bot login).
+- **Register `app.on(...)` handlers before `await app.ready()`** so subscriptions are known when the app authenticates. `ready()` connects, completes auth, negotiates capabilities from intents + secret scope, then throws `BridgeCapabilityError` if any registered handler targets an event the app is not allowed to receive.
+- **Sticky `ready`**: if the bot was already ready before the app connected, the bridge replays the latest `ready` payload to matching subscriptions after auth.
+
 ## Built-In Events
 
 Apps subscribe to events with `app.on(...)`. The bridge forwards only what each app subscribes to.
@@ -162,35 +174,52 @@ All actions return:
 
 ```ts
 type ActionResult<T> =
-  | { ok: true; requestId: string; ts: number; data: T }
-  | { ok: false; requestId: string; ts: number; error: { code: string; message: string; details?: unknown } };
+	| { ok: true; requestId: string; ts: number; data: 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:
+You can provide an `idempotencyKey` in action options so repeated calls return the first result while the server-side entry is still valid (default TTL **120s**).
+
+- **Default scope (`connection`)**: dedupe is per WebSocket connection (a reconnect is a new connection and does not replay prior keys).
+- **Optional scope (`secret`)**: set `server.idempotencyScope: "secret"` on the bot bridge to dedupe by configured secret id across connections (useful when the app reconnects and retries the same logical operation).
 
 ```ts
 await app.actions.sendMessage(
-  { channelId: "123456789012345678", content: "Hello once" },
-  { idempotencyKey: "notify:order:123" },
+	{ channelId: '123456789012345678', content: 'Hello once' },
+	{ idempotencyKey: 'notify:order:123' },
 );
 ```
 
+Tune limits on the bot bridge when needed:
+
+```ts
+server: {
+  port: 3001,
+  secrets: [process.env.SHARDWIRE_SECRET!],
+  maxPayloadBytes: 65536, // per-frame JSON limit (default 65536)
+  idempotencyScope: "secret",
+  idempotencyTtlMs: 120_000,
+},
+```
+
 ### 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);
-    },
-  },
+	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, meta.discordStatus, meta.retryAfterMs);
+		},
+	},
 });
 ```
 
+On Discord **429** responses, failed actions surface `SERVICE_UNAVAILABLE` with `details.retryAfterMs` (when Discord provides `retry_after`) and the metrics hook receives `retryAfterMs` / `discordStatus` for backoff and dashboards.
+
 ## Secret Scopes
 
 Use a plain string secret for full event/action access:
@@ -229,7 +258,7 @@ console.log(capabilities.events, capabilities.actions);
 
 ## Run the Included Examples
 
-In two terminals:
+### Minimal (single shared secret)
 
 ```bash
 # terminal 1
@@ -241,15 +270,42 @@ DISCORD_TOKEN=your-token SHARDWIRE_SECRET=dev-secret npm run example:bot
 SHARDWIRE_SECRET=dev-secret npm run example:app
 ```
 
-Examples:
+- Bot bridge: [`examples/bot-basic.ts`](./examples/bot-basic.ts)
+- App client: [`examples/app-basic.ts`](./examples/app-basic.ts)
 
-- Bot bridge: `examples/bot-basic.ts`
-- App client: `examples/app-basic.ts`
+### Production-style (scoped secrets + moderation + interactions)
+
+Use **two different** secret strings (bridge rejects duplicate values across scoped entries).
+
+```bash
+# terminal 1 — bot with dashboard + moderation scopes
+DISCORD_TOKEN=your-token \
+  SHARDWIRE_SECRET_DASHBOARD=dashboard-secret \
+  SHARDWIRE_SECRET_MODERATION=moderation-secret \
+  npm run example:bot:prod
+```
+
+```bash
+# terminal 2 — delete messages that contain the demo trigger (optional channel filter)
+SHARDWIRE_SECRET_MODERATION=moderation-secret \
+  MOD_ALERT_CHANNEL_ID=123456789012345678 \
+  npm run example:app:moderation
+```
+
+```bash
+# terminal 3 — defer + edit reply for `customId: shardwire.demo.btn` buttons
+SHARDWIRE_SECRET_MODERATION=moderation-secret \
+  npm run example:app:interaction
+```
+
+- [`examples/bot-production.ts`](./examples/bot-production.ts)
+- [`examples/app-moderation.ts`](./examples/app-moderation.ts)
+- [`examples/app-interaction.ts`](./examples/app-interaction.ts)
 
 ## Public API
 
 ```ts
-import { createBotBridge, connectBotBridge } from "shardwire";
+import { createBotBridge, connectBotBridge } from 'shardwire';
 ```
 
 Main exports include:
@@ -266,7 +322,10 @@ 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).
+
+**Reporting vulnerabilities:** email [cored.developments@gmail.com](mailto:cored.developments@gmail.com) with enough detail to reproduce the issue (versions, config shape, and steps). Do not open a public issue for undisclosed security problems.
+
+**Rotating bridge secrets without downtime:** configure **two** entries in `server.secrets` (old + new values), roll the app env to the new secret, then remove the old entry on the next deploy. Scoped secrets should keep **distinct** `id` values so apps can pin `secretId` during rotation.
 
 ## Contributing
 

package/dist/index.d.mts

@@ -92,7 +92,7 @@ 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;
@@ -362,8 +362,8 @@ interface EventSubscription<K extends BotEventName = BotEventName> {
     filter?: EventSubscriptionFilter;
 }
 interface SecretPermissions {
-    events?: "*" | readonly BotEventName[];
-    actions?: "*" | readonly BotActionName[];
+    events?: '*' | readonly BotEventName[];
+    actions?: '*' | readonly BotActionName[];
 }
 interface ScopedSecretConfig {
     id?: string;
@@ -377,6 +377,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 +397,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 +415,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 +437,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 +455,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 = {

package/dist/index.d.ts

@@ -92,7 +92,7 @@ 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;
@@ -362,8 +362,8 @@ interface EventSubscription<K extends BotEventName = BotEventName> {
     filter?: EventSubscriptionFilter;
 }
 interface SecretPermissions {
-    events?: "*" | readonly BotEventName[];
-    actions?: "*" | readonly BotActionName[];
+    events?: '*' | readonly BotEventName[];
+    actions?: '*' | readonly BotActionName[];
 }
 interface ScopedSecretConfig {
     id?: string;
@@ -377,6 +377,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 +397,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 +415,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 +437,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 +455,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 = {

package/dist/index.js

@@ -91,7 +91,9 @@ var EVENT_REQUIRED_INTENTS = {
 };
 function getAvailableEvents(intents) {
   const enabled = new Set(intents);
-  return BOT_EVENT_NAMES.filter((eventName) => EVENT_REQUIRED_INTENTS[eventName].every((intent) => enabled.has(intent)));
+  return BOT_EVENT_NAMES.filter(
+    (eventName) => EVENT_REQUIRED_INTENTS[eventName].every((intent) => enabled.has(intent))
+  );
 }
 
 // src/discord/runtime/adapter.ts
@@ -428,10 +430,19 @@ function mapDiscordErrorToActionExecutionError(error) {
     return new ActionExecutionError("INVALID_REQUEST", message, detailPayload);
   }
   if (details.status === 429) {
+    let retryAfterMs;
+    if (error instanceof import_discord2.DiscordAPIError) {
+      const raw = error.rawError;
+      const retryAfter = raw?.retry_after;
+      if (typeof retryAfter === "number" && Number.isFinite(retryAfter)) {
+        retryAfterMs = Math.max(0, Math.ceil(retryAfter * 1e3));
+      }
+    }
     return new ActionExecutionError("SERVICE_UNAVAILABLE", message, {
       discordStatus: 429,
       retryable: true,
-      ...details.code !== void 0 ? { discordCode: details.code } : {}
+      ...details.code !== void 0 ? { discordCode: details.code } : {},
+      ...retryAfterMs !== void 0 ? { retryAfterMs } : {}
     });
   }
   return null;
@@ -749,7 +760,10 @@ var DiscordJsRuntimeAdapter = class {
         throw mappedError;
       }
       this.logger.error("Discord action execution failed.", { action: name, error: String(error) });
-      throw new ActionExecutionError("INTERNAL_ERROR", error instanceof Error ? error.message : "Discord action failed.");
+      throw new ActionExecutionError(
+        "INTERNAL_ERROR",
+        error instanceof Error ? error.message : "Discord action failed."
+      );
     }
   }
   async fetchSendableChannel(channelId) {
@@ -817,7 +831,10 @@ var DiscordJsRuntimeAdapter = class {
   async replyToInteraction(payload) {
     const interaction = this.getReplyCapableInteraction(payload.interactionId);
     if (interaction.replied || interaction.deferred) {
-      throw new ActionExecutionError("INVALID_REQUEST", `Interaction "${payload.interactionId}" has already been acknowledged.`);
+      throw new ActionExecutionError(
+        "INVALID_REQUEST",
+        `Interaction "${payload.interactionId}" has already been acknowledged.`
+      );
     }
     const reply = await interaction.reply({
       ...toSendOptions(payload),
@@ -829,7 +846,10 @@ var DiscordJsRuntimeAdapter = class {
   async deferInteraction(payload) {
     const interaction = this.getReplyCapableInteraction(payload.interactionId);
     if (interaction.replied) {
-      throw new ActionExecutionError("INVALID_REQUEST", `Interaction "${payload.interactionId}" has already been replied to.`);
+      throw new ActionExecutionError(
+        "INVALID_REQUEST",
+        `Interaction "${payload.interactionId}" has already been replied to.`
+      );
     }
     if (!interaction.deferred) {
       await interaction.deferReply({
@@ -852,7 +872,10 @@ var DiscordJsRuntimeAdapter = class {
   async followUpInteraction(payload) {
     const interaction = this.getReplyCapableInteraction(payload.interactionId);
     if (!interaction.replied && !interaction.deferred) {
-      throw new ActionExecutionError("INVALID_REQUEST", `Interaction "${payload.interactionId}" has not been acknowledged yet.`);
+      throw new ActionExecutionError(
+        "INVALID_REQUEST",
+        `Interaction "${payload.interactionId}" has not been acknowledged yet.`
+      );
     }
     const followUp = await interaction.followUp({
       ...toSendOptions(payload),
@@ -961,7 +984,10 @@ var DiscordJsRuntimeAdapter = class {
       return candidate.emoji.identifier === payload.emoji || candidate.emoji.name === payload.emoji || candidate.emoji.toString() === payload.emoji;
     });
     if (!reaction) {
-      throw new ActionExecutionError("NOT_FOUND", `Reaction "${payload.emoji}" was not found on message "${payload.messageId}".`);
+      throw new ActionExecutionError(
+        "NOT_FOUND",
+        `Reaction "${payload.emoji}" was not found on message "${payload.messageId}".`
+      );
     }
     await reaction.users.remove(ownUserId);
     return {
@@ -1004,7 +1030,9 @@ function normalizeKindList(value) {
     return void 0;
   }
   const rawValues = Array.isArray(value) ? value : [value];
-  const normalized = [...new Set(rawValues.filter((entry) => typeof entry === "string"))].sort();
+  const normalized = [
+    ...new Set(rawValues.filter((entry) => typeof entry === "string"))
+  ].sort();
   return normalized.length > 0 ? normalized : void 0;
 }
 function normalizeEventSubscriptionFilter(filter) {
@@ -1270,6 +1298,8 @@ var BridgeTransportServer = class {
     const maxConcurrent = config.options.server.maxConcurrentActions ?? 32;
     const queueTimeout = config.options.server.actionQueueTimeoutMs ?? 5e3;
     this.actionSemaphore = new AsyncSemaphore(maxConcurrent, queueTimeout);
+    this.idempotencyTtlMs = config.options.server.idempotencyTtlMs ?? 12e4;
+    this.idempotencyScope = config.options.server.idempotencyScope ?? "connection";
     this.wss = new import_ws.WebSocketServer({
       host: config.options.server.host,
       port: config.options.server.port,
@@ -1292,7 +1322,8 @@ var BridgeTransportServer = class {
   stickyEvents = /* @__PURE__ */ new Map();
   actionSemaphore;
   idempotencyCache = /* @__PURE__ */ new Map();
-  idempotencyTtlMs = 12e4;
+  idempotencyTtlMs;
+  idempotencyScope;
   authBuckets = /* @__PURE__ */ new Map();
   connectionCount() {
     let count = 0;
@@ -1522,7 +1553,7 @@ var BridgeTransportServer = class {
         }
         const idempotencyRaw = payload.idempotencyKey;
         const idempotencyKey = typeof idempotencyRaw === "string" && idempotencyRaw.length > 0 && idempotencyRaw.length <= 256 ? idempotencyRaw : void 0;
-        const idempotencyCacheKey = idempotencyKey ? `${state.id}:${idempotencyKey}` : void 0;
+        const idempotencyCacheKey = idempotencyKey ? this.idempotencyScope === "secret" && activeSecret ? `secret:${activeSecret.id}:${idempotencyKey}` : `conn:${state.id}:${idempotencyKey}` : void 0;
         if (idempotencyCacheKey) {
           this.pruneIdempotencyCache(Date.now());
           const cached = this.idempotencyCache.get(idempotencyCacheKey);
@@ -1535,9 +1566,7 @@ var BridgeTransportServer = class {
             });
             this.safeSend(
               state.socket,
-              stringifyEnvelope(
-                makeEnvelope(replay.ok ? "action.result" : "action.error", replay, { requestId })
-              )
+              stringifyEnvelope(makeEnvelope(replay.ok ? "action.result" : "action.error", replay, { requestId }))
             );
             return;
           }
@@ -1728,11 +1757,7 @@ function normalizeSecretEntry(secret, index) {
     value: scoped.value,
     scope: {
       events: normalizeScopeList(scoped.allow?.events, BOT_EVENT_NAMES, `server.secrets[${index}].allow.events`),
-      actions: normalizeScopeList(
-        scoped.allow?.actions,
-        BOT_ACTION_NAMES,
-        `server.secrets[${index}].allow.actions`
-      )
+      actions: normalizeScopeList(scoped.allow?.actions, BOT_ACTION_NAMES, `server.secrets[${index}].allow.actions`)
     }
   };
 }
@@ -1759,6 +1784,14 @@ function assertBotBridgeOptions(options) {
   if (options.server.actionQueueTimeoutMs !== void 0) {
     assertPositiveNumber("server.actionQueueTimeoutMs", options.server.actionQueueTimeoutMs);
   }
+  if (options.server.idempotencyScope !== void 0) {
+    if (options.server.idempotencyScope !== "connection" && options.server.idempotencyScope !== "secret") {
+      throw new Error('server.idempotencyScope must be "connection" or "secret".');
+    }
+  }
+  if (options.server.idempotencyTtlMs !== void 0) {
+    assertPositiveNumber("server.idempotencyTtlMs", options.server.idempotencyTtlMs);
+  }
   if (!Array.isArray(options.server.secrets) || options.server.secrets.length === 0) {
     throw new Error("server.secrets must contain at least one secret.");
   }
@@ -1958,6 +1991,24 @@ var AppRequestError = class extends Error {
   code;
 };
 var DEFAULT_REQUEST_TIMEOUT_MS = 1e4;
+function metricsExtrasFromActionError(error) {
+  const details = error.details;
+  if (!details || typeof details !== "object" || Array.isArray(details)) {
+    return {};
+  }
+  const obj = details;
+  const extras = {};
+  if (typeof obj.retryAfterMs === "number" && Number.isFinite(obj.retryAfterMs)) {
+    extras.retryAfterMs = obj.retryAfterMs;
+  }
+  if (typeof obj.discordStatus === "number" && Number.isFinite(obj.discordStatus)) {
+    extras.discordStatus = obj.discordStatus;
+  }
+  if (typeof obj.discordCode === "number" && Number.isFinite(obj.discordCode)) {
+    extras.discordCode = obj.discordCode;
+  }
+  return extras;
+}
 function connectBotBridge(options) {
   assertAppBridgeOptions(options);
   const logger = withLogger(options.logger);
@@ -2266,7 +2317,7 @@ function connectBotBridge(options) {
         requestId,
         durationMs: Date.now() - started,
         ok: result.ok,
-        ...!result.ok ? { errorCode: result.error.code } : {}
+        ...!result.ok ? { errorCode: result.error.code, ...metricsExtrasFromActionError(result.error) } : {}
       });
       return result;
     } catch (error) {