shardwire 1.4.0 → 1.4.5

package/dist/index.js

@@ -22,7 +22,11 @@ var index_exports = {};
 __export(index_exports, {
   BridgeCapabilityError: () => BridgeCapabilityError,
   connectBotBridge: () => connectBotBridge,
-  createBotBridge: () => createBotBridge
+  createBotBridge: () => createBotBridge,
+  createThreadThenSendMessage: () => createThreadThenSendMessage,
+  deferThenEditInteractionReply: () => deferThenEditInteractionReply,
+  deferUpdateThenEditInteractionReply: () => deferUpdateThenEditInteractionReply,
+  getShardwireCatalog: () => getShardwireCatalog
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -104,6 +108,17 @@ var EVENT_REQUIRED_INTENTS = {
   channelUpdate: ["Guilds"],
   channelDelete: ["Guilds"]
 };
+var SUBSCRIPTION_FILTER_KEYS = [
+  "guildId",
+  "channelId",
+  "userId",
+  "commandName",
+  "customId",
+  "interactionKind",
+  "channelType",
+  "parentChannelId",
+  "threadId"
+];
 function getAvailableEvents(intents) {
   const enabled = new Set(intents);
   return BOT_EVENT_NAMES.filter(
@@ -2311,14 +2326,16 @@ function createBotBridgeWithRuntime(options, runtime) {
 
 // src/discord/types.ts
 var BridgeCapabilityError = class extends Error {
-  constructor(kind, name, message) {
+  constructor(kind, name, message, details) {
     super(message ?? `Capability "${name}" is not available for ${kind}.`);
     this.kind = kind;
     this.name = name;
+    this.details = details;
     this.name = "BridgeCapabilityError";
   }
   kind;
   name;
+  details;
 };
 
 // src/bridge/transport/socket.ts
@@ -2327,6 +2344,172 @@ function createNodeWebSocket(url) {
   return new import_ws2.WebSocket(url);
 }
 
+// src/dx/explain-capability.ts
+var DENIED_REMEDIATION = "Add the required gateway intents on `createBotBridge({ intents })` and/or widen `server.secrets[].allow.events` or `allow.actions` for this secret.";
+function isBotEventName(name) {
+  return BOT_EVENT_NAMES.includes(name);
+}
+function isBotActionName(name) {
+  return BOT_ACTION_NAMES.includes(name);
+}
+function buildBridgeCapabilityErrorDetails(kind, name) {
+  const base = {
+    reasonCode: "not_in_capabilities",
+    kind,
+    name,
+    remediation: DENIED_REMEDIATION
+  };
+  if (kind === "event" && isBotEventName(name)) {
+    return { ...base, requiredIntents: EVENT_REQUIRED_INTENTS[name] };
+  }
+  return base;
+}
+function explainCapability(connected, capabilities, query) {
+  const { kind, name } = query;
+  const known = kind === "event" ? isBotEventName(name) : isBotActionName(name);
+  if (!known) {
+    return {
+      kind,
+      name,
+      known: false,
+      reasonCode: "unknown_name",
+      remediation: "Use a built-in event or action name from `app.catalog()`."
+    };
+  }
+  if (!connected || !capabilities) {
+    const base = {
+      kind,
+      name,
+      known: true,
+      reasonCode: "not_negotiated",
+      remediation: "Call `await app.ready()` (or `await app.preflight()`) after connecting to see negotiated bridge access."
+    };
+    if (kind === "event") {
+      return {
+        ...base,
+        requiredIntents: EVENT_REQUIRED_INTENTS[name]
+      };
+    }
+    return base;
+  }
+  if (kind === "event") {
+    const ev = name;
+    const allowedByBridge2 = capabilities.events.includes(ev);
+    return {
+      kind: "event",
+      name: ev,
+      known: true,
+      requiredIntents: EVENT_REQUIRED_INTENTS[ev],
+      allowedByBridge: allowedByBridge2,
+      reasonCode: allowedByBridge2 ? "allowed" : "denied_by_bridge",
+      ...!allowedByBridge2 ? { remediation: DENIED_REMEDIATION } : {}
+    };
+  }
+  const act = name;
+  const allowedByBridge = capabilities.actions.includes(act);
+  return {
+    kind: "action",
+    name: act,
+    known: true,
+    allowedByBridge,
+    reasonCode: allowedByBridge ? "allowed" : "denied_by_bridge",
+    ...!allowedByBridge ? { remediation: DENIED_REMEDIATION } : {}
+  };
+}
+
+// src/dx/preflight.ts
+function parseAppBridgeUrl(url) {
+  try {
+    return new URL(url);
+  } catch {
+    return null;
+  }
+}
+function buildPreflightReport(input) {
+  const issues = [];
+  const { connected, capabilities, appUrl, desired, subscriptionCapabilityMessage, subscriptionCapabilityRemediation } = input;
+  if (subscriptionCapabilityMessage) {
+    issues.push({
+      severity: "error",
+      code: "subscription_event_not_negotiated",
+      message: subscriptionCapabilityMessage,
+      remediation: subscriptionCapabilityRemediation ?? "Remove `app.on` handlers for disallowed events or widen bot intents / secret scope."
+    });
+  }
+  const parsed = parseAppBridgeUrl(appUrl);
+  if (parsed?.protocol === "ws:") {
+    const host = parsed.hostname;
+    const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1";
+    if (isLoopback) {
+      issues.push({
+        severity: "warning",
+        code: "insecure_transport_local",
+        message: "Using ws:// to a loopback host is fine for development.",
+        remediation: "Use wss:// behind TLS for production deployments."
+      });
+    }
+  }
+  if (!connected || !capabilities) {
+    issues.push({
+      severity: "warning",
+      code: "not_connected",
+      message: "Preflight ran before the app finished authenticating.",
+      remediation: "Ensure the bridge URL and secret are correct; `preflight()` awaits authentication internally."
+    });
+    return {
+      ok: issues.every((i) => i.severity !== "error"),
+      connected,
+      capabilities,
+      issues
+    };
+  }
+  const allowedEvents = new Set(capabilities.events);
+  const allowedActions = new Set(capabilities.actions);
+  if (desired?.events?.length) {
+    for (const ev of desired.events) {
+      if (!allowedEvents.has(ev)) {
+        issues.push({
+          severity: "error",
+          code: "desired_event_not_allowed",
+          message: `Negotiated capabilities do not include event "${ev}".`,
+          remediation: "Add gateway intents on the bot bridge and/or include this event in the scoped secret `allow.events`."
+        });
+      }
+    }
+  }
+  if (desired?.actions?.length) {
+    for (const act of desired.actions) {
+      if (!allowedActions.has(act)) {
+        issues.push({
+          severity: "error",
+          code: "desired_action_not_allowed",
+          message: `Negotiated capabilities do not include action "${act}".`,
+          remediation: "Widen `server.secrets[].allow.actions` or use a full-access secret for this app."
+        });
+      }
+    }
+  }
+  const hasError = issues.some((i) => i.severity === "error");
+  return {
+    ok: !hasError,
+    connected,
+    capabilities: { events: [...capabilities.events], actions: [...capabilities.actions] },
+    issues
+  };
+}
+
+// src/dx/shardwire-catalog.ts
+function getShardwireCatalog() {
+  return {
+    events: BOT_EVENT_NAMES.map((name) => ({
+      name,
+      requiredIntents: EVENT_REQUIRED_INTENTS[name]
+    })),
+    actions: [...BOT_ACTION_NAMES],
+    subscriptionFilters: [...SUBSCRIPTION_FILTER_KEYS]
+  };
+}
+
 // src/utils/backoff.ts
 function getBackoffDelay(attempt, config) {
   const base = Math.min(config.maxDelayMs, config.initialDelayMs * 2 ** attempt);
@@ -2453,7 +2636,12 @@ function connectBotBridge(options) {
     const allowedEvents = new Set(currentCapabilities.events);
     const invalidEvents = [...eventHandlers.keys()].filter((eventName) => !allowedEvents.has(eventName));
     const firstInvalid = invalidEvents[0];
-    capabilityError = firstInvalid !== void 0 ? new BridgeCapabilityError("event", firstInvalid, `Event "${firstInvalid}" is not available for this app.`) : null;
+    capabilityError = firstInvalid !== void 0 ? new BridgeCapabilityError(
+      "event",
+      firstInvalid,
+      `Event "${firstInvalid}" is not available for this app.`,
+      buildBridgeCapabilityErrorDetails("event", firstInvalid)
+    ) : null;
     for (const [eventName, handlers] of eventHandlers.entries()) {
       if (!allowedEvents.has(eventName)) {
         continue;
@@ -2626,7 +2814,12 @@ function connectBotBridge(options) {
         ts: Date.now(),
         error: {
           code: "FORBIDDEN",
-          message: `Action "${name}" is not available for this app.`
+          message: `Action "${name}" is not available for this app.`,
+          details: {
+            reasonCode: "action_not_in_capabilities",
+            action: name,
+            remediation: "Add gateway intents on the bot bridge and/or include this action in the scoped secret `allow.actions`."
+          }
         }
       };
     }
@@ -2773,9 +2966,49 @@ function connectBotBridge(options) {
         actions: [...currentCapabilities.actions]
       };
     },
+    catalog() {
+      return getShardwireCatalog();
+    },
+    explainCapability(query) {
+      const connected = Boolean(socket && socket.readyState === 1 && isAuthed);
+      const caps = connected ? { events: [...currentCapabilities.events], actions: [...currentCapabilities.actions] } : null;
+      return explainCapability(connected, caps, query);
+    },
+    async preflight(desired) {
+      try {
+        await connect();
+      } catch (error) {
+        return {
+          ok: false,
+          connected: false,
+          capabilities: null,
+          issues: [
+            {
+              severity: "error",
+              code: "connection_failed",
+              message: error instanceof Error ? error.message : "Failed to connect or authenticate.",
+              remediation: "Verify `url` and `secret`, and ensure the bot bridge is running and reachable."
+            }
+          ]
+        };
+      }
+      return buildPreflightReport({
+        connected: Boolean(socket && socket.readyState === 1 && isAuthed),
+        capabilities: isAuthed ? { events: [...currentCapabilities.events], actions: [...currentCapabilities.actions] } : null,
+        appUrl: options.url,
+        ...desired !== void 0 ? { desired } : {},
+        subscriptionCapabilityMessage: capabilityError?.message ?? null,
+        subscriptionCapabilityRemediation: capabilityError?.details?.remediation ?? null
+      });
+    },
     on(name, handler, filter) {
       if (currentCapabilities.events.length > 0 && !currentCapabilities.events.includes(name)) {
-        throw new BridgeCapabilityError("event", name, `Event "${name}" is not available for this app.`);
+        throw new BridgeCapabilityError(
+          "event",
+          name,
+          `Event "${name}" is not available for this app.`,
+          buildBridgeCapabilityErrorDetails("event", name)
+        );
       }
       const casted = handler;
       const subscription = filter ? { name, filter } : { name };
@@ -2826,10 +3059,54 @@ function connectBotBridge(options) {
     }
   };
 }
+
+// src/workflows/interaction.ts
+async function deferThenEditInteractionReply(app, args, options) {
+  const { interactionId, defer, edit } = args;
+  const deferResult = await app.actions.deferInteraction({ interactionId, ...defer }, options);
+  if (!deferResult.ok) {
+    return deferResult;
+  }
+  return app.actions.editInteractionReply(edit, options);
+}
+async function deferUpdateThenEditInteractionReply(app, args, options) {
+  const { interactionId, edit } = args;
+  const deferResult = await app.actions.deferUpdateInteraction({ interactionId }, options);
+  if (!deferResult.ok) {
+    return deferResult;
+  }
+  return app.actions.editInteractionReply(edit, options);
+}
+
+// src/workflows/thread.ts
+async function createThreadThenSendMessage(app, args, options) {
+  const threadResult = await app.actions.createThread(args.thread, options);
+  if (!threadResult.ok) {
+    return {
+      threadResult,
+      messageResult: {
+        ok: false,
+        requestId: options?.requestId ?? "unknown",
+        ts: Date.now(),
+        error: {
+          code: "INVALID_REQUEST",
+          message: "Skipped send because createThread failed.",
+          details: { skipped: true }
+        }
+      }
+    };
+  }
+  const messageResult = await app.actions.sendMessage({ ...args.message, channelId: threadResult.data.id }, options);
+  return { threadResult, messageResult };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BridgeCapabilityError,
   connectBotBridge,
-  createBotBridge
+  createBotBridge,
+  createThreadThenSendMessage,
+  deferThenEditInteractionReply,
+  deferUpdateThenEditInteractionReply,
+  getShardwireCatalog
 });
 //# sourceMappingURL=index.js.map