@hogsend/plugin-discord 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/plugin-discord",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@hogsend/engine": "^0.24.0"
+    "@hogsend/engine": "^0.25.0"
   },
   "peerDependencies": {
     "discord.js": ">=14.0.0"

package/src/actions/broadcast.ts

@@ -0,0 +1,40 @@
+import {
+  type DefinedConnectorAction,
+  defineConnectorAction,
+} from "@hogsend/engine";
+import { DISCORD_PROVIDER_ID } from "../constants.js";
+import { botFetch, type SendMessageResult } from "./rest.js";
+
+export interface BroadcastToChannelArgs {
+  /** Target channel snowflake. */
+  channelId: string;
+  /** Message content (Discord markdown). */
+  content: string;
+  /**
+   * Whether `@everyone` / `@here` in the content actually ping. Default `true`
+   * (a broadcast is announcement-shaped); set `false` to ping roles only.
+   */
+  pingEveryone?: boolean;
+}
+
+/** Broadcast to a channel, ALLOWING @everyone/@here + role pings to fire. */
+export const broadcastToChannel: DefinedConnectorAction<
+  BroadcastToChannelArgs,
+  SendMessageResult
+> = defineConnectorAction({
+  connectorId: DISCORD_PROVIDER_ID,
+  name: "broadcastToChannel",
+  description:
+    "Broadcast a message to a Discord channel, allowing @everyone/@role pings.",
+  async run(args) {
+    const allowed =
+      args.pingEveryone === false
+        ? { parse: ["roles"] }
+        : { parse: ["everyone", "roles"] };
+    const res = (await botFetch(`/channels/${args.channelId}/messages`, {
+      method: "POST",
+      body: { content: args.content, allowed_mentions: allowed },
+    })) as { id?: string } | null;
+    return { messageId: res?.id ?? null };
+  },
+});

package/src/actions/dm.ts

@@ -0,0 +1,60 @@
+import {
+  type DefinedConnectorAction,
+  defineConnectorAction,
+} from "@hogsend/engine";
+import { DISCORD_PROVIDER_ID } from "../constants.js";
+import { botFetch, resolveDiscordId } from "./rest.js";
+
+export interface DmMemberArgs {
+  /** Recipient: email, external id, or raw discord snowflake. */
+  member: string;
+  /** Message content (Discord markdown). */
+  content: string;
+}
+
+export interface DmResult {
+  messageId: string | null;
+  /** False when unresolved OR the user's DMs are closed (a soft, non-throwing failure). */
+  delivered: boolean;
+}
+
+/**
+ * Direct-message a member (resolved contact → discord_id). A closed-DM / no
+ * shared-guild rejection is a SOFT failure (`delivered: false`, logged) rather
+ * than a throw — a single un-DMable recipient must not fail a journey.
+ */
+export const dmMember: DefinedConnectorAction<DmMemberArgs, DmResult> =
+  defineConnectorAction({
+    connectorId: DISCORD_PROVIDER_ID,
+    name: "dmMember",
+    description:
+      "Send a direct message to a member (resolved contact → discord_id).",
+    async run(args, ctx) {
+      const id = await resolveDiscordId(ctx, args.member);
+      if (!id) {
+        ctx.logger.warn("discord dmMember: recipient unresolved", {
+          member: args.member,
+        });
+        return { messageId: null, delivered: false };
+      }
+      try {
+        // Open (or fetch) the 1:1 DM channel, then post into it.
+        const dm = (await botFetch("/users/@me/channels", {
+          method: "POST",
+          body: { recipient_id: id },
+        })) as { id?: string } | null;
+        if (!dm?.id) return { messageId: null, delivered: false };
+        const res = (await botFetch(`/channels/${dm.id}/messages`, {
+          method: "POST",
+          body: { content: args.content },
+        })) as { id?: string } | null;
+        return { messageId: res?.id ?? null, delivered: Boolean(res?.id) };
+      } catch (err) {
+        // Closed DMs / no shared guild → Discord 403. Soft-fail.
+        ctx.logger.warn("discord dmMember: delivery failed", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return { messageId: null, delivered: false };
+      }
+    },
+  });

package/src/actions/index.ts

@@ -0,0 +1,38 @@
+import type { DefinedConnectorAction } from "@hogsend/engine";
+import { broadcastToChannel } from "./broadcast.js";
+import { dmMember } from "./dm.js";
+import { mentionMembers, mentionRole } from "./mention.js";
+import { sendChannelMessage } from "./send-channel-message.js";
+
+/**
+ * Every Discord OUTBOUND action — pass to
+ * `createHogsendClient({ connectorActions: discordActions })`, then invoke from a
+ * journey via the standalone `sendConnectorAction({ connectorId: "discord", … })`.
+ * All are bot-REST (token only), socket-free, and independent of the inbound
+ * gateway runtime.
+ */
+export const discordActions: DefinedConnectorAction[] = [
+  sendChannelMessage,
+  broadcastToChannel,
+  mentionMembers,
+  mentionRole,
+  dmMember,
+];
+
+export {
+  type BroadcastToChannelArgs,
+  broadcastToChannel,
+} from "./broadcast.js";
+export { type DmMemberArgs, type DmResult, dmMember } from "./dm.js";
+export {
+  type MentionMembersArgs,
+  type MentionMembersResult,
+  type MentionRoleArgs,
+  mentionMembers,
+  mentionRole,
+} from "./mention.js";
+export type { SendMessageResult } from "./rest.js";
+export {
+  type SendChannelMessageArgs,
+  sendChannelMessage,
+} from "./send-channel-message.js";

package/src/actions/mention.ts

@@ -0,0 +1,85 @@
+import {
+  type DefinedConnectorAction,
+  defineConnectorAction,
+} from "@hogsend/engine";
+import { DISCORD_PROVIDER_ID } from "../constants.js";
+import { botFetch, resolveDiscordId, type SendMessageResult } from "./rest.js";
+
+export interface MentionMembersArgs {
+  /** Target channel snowflake. */
+  channelId: string;
+  /** Recipients: emails, external ids, or raw discord snowflakes. */
+  members: string[];
+  /** Optional message appended after the mentions. */
+  content?: string;
+}
+
+export interface MentionMembersResult extends SendMessageResult {
+  /** The discord ids that resolved + were mentioned. */
+  mentioned: string[];
+  /** Refs that could not be resolved to a discord id (skipped). */
+  unresolved: string[];
+}
+
+/** Post a message @-mentioning specific members (resolved contact → discord_id). */
+export const mentionMembers: DefinedConnectorAction<
+  MentionMembersArgs,
+  MentionMembersResult
+> = defineConnectorAction({
+  connectorId: DISCORD_PROVIDER_ID,
+  name: "mentionMembers",
+  description:
+    "Post a message @-mentioning specific members (resolved contact → discord_id).",
+  async run(args, ctx) {
+    const mentioned: string[] = [];
+    const unresolved: string[] = [];
+    for (const ref of args.members) {
+      const id = await resolveDiscordId(ctx, ref);
+      if (id) mentioned.push(id);
+      else unresolved.push(ref);
+    }
+    if (mentioned.length === 0) {
+      ctx.logger.warn("discord mentionMembers: no members resolved", {
+        unresolved,
+      });
+      return { messageId: null, mentioned, unresolved };
+    }
+    const mentions = mentioned.map((id) => `<@${id}>`).join(" ");
+    const content = args.content ? `${mentions} ${args.content}` : mentions;
+    const res = (await botFetch(`/channels/${args.channelId}/messages`, {
+      method: "POST",
+      // Only the explicitly-resolved users may ping — never widen to everyone.
+      body: { content, allowed_mentions: { users: mentioned } },
+    })) as { id?: string } | null;
+    return { messageId: res?.id ?? null, mentioned, unresolved };
+  },
+});
+
+export interface MentionRoleArgs {
+  /** Target channel snowflake. */
+  channelId: string;
+  /** Role snowflake to mention (a group of members). */
+  roleId: string;
+  /** Optional message appended after the mention. */
+  content?: string;
+}
+
+/** Post a message @-mentioning a role (a group of members). */
+export const mentionRole: DefinedConnectorAction<
+  MentionRoleArgs,
+  SendMessageResult
+> = defineConnectorAction({
+  connectorId: DISCORD_PROVIDER_ID,
+  name: "mentionRole",
+  description: "Post a message @-mentioning a role (group of members).",
+  async run(args) {
+    const content = args.content
+      ? `<@&${args.roleId}> ${args.content}`
+      : `<@&${args.roleId}>`;
+    const res = (await botFetch(`/channels/${args.channelId}/messages`, {
+      method: "POST",
+      body: { content, allowed_mentions: { roles: [args.roleId] } },
+    })) as { id?: string } | null;
+    return { messageId: res?.id ?? null };
+  },
+});

package/src/actions/rest.ts

@@ -0,0 +1,66 @@
+import type { ConnectorActionCtx } from "@hogsend/engine";
+import { DISCORD_API_BASE } from "../constants.js";
+
+/**
+ * Shared bot-REST plumbing for the Discord OUTBOUND actions. Every action is a
+ * pure HTTPS call to discord.com needing only the bot token — NO `discord.js`,
+ * NO gateway socket — so actions run on any replica regardless of the inbound
+ * runtime's state.
+ */
+
+/** The bot token, read from the platform's own env. Throws when unset. */
+export function getBotToken(): string {
+  const token = process.env.DISCORD_BOT_TOKEN;
+  if (!token) {
+    throw new Error(
+      "DISCORD_BOT_TOKEN is required for Discord outbound actions",
+    );
+  }
+  return token;
+}
+
+/**
+ * One bot-REST call. Throws on a non-2xx (STATUS ONLY in the message — never the
+ * response body, which can echo the request carrying the `Bot` token). Returns
+ * the parsed JSON, or null for 204 / empty bodies.
+ */
+export async function botFetch(
+  path: string,
+  init: { method: string; body?: unknown },
+): Promise<unknown> {
+  const res = await fetch(`${DISCORD_API_BASE}${path}`, {
+    method: init.method,
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bot ${getBotToken()}`,
+    },
+    ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+  });
+  if (!res.ok) {
+    throw new Error(
+      `discord bot-REST ${init.method} ${path} failed (${res.status})`,
+    );
+  }
+  if (res.status === 204) return null;
+  return res.json().catch(() => null);
+}
+
+/**
+ * Resolve a recipient ref to a Discord snowflake: the contact store first
+ * (email / external id / discord id), then an all-digit ref treated as a raw
+ * snowflake. Null when unresolvable.
+ */
+export async function resolveDiscordId(
+  ctx: ConnectorActionCtx,
+  ref: string,
+): Promise<string | null> {
+  const contact = await ctx.resolveContact(ref);
+  if (contact?.discordId) return contact.discordId;
+  if (/^\d{5,}$/.test(ref)) return ref;
+  return null;
+}
+
+/** The shared result shape for a channel post. */
+export interface SendMessageResult {
+  messageId: string | null;
+}

package/src/actions/send-channel-message.ts

@@ -0,0 +1,39 @@
+import {
+  type DefinedConnectorAction,
+  defineConnectorAction,
+} from "@hogsend/engine";
+import { DISCORD_PROVIDER_ID } from "../constants.js";
+import { botFetch, type SendMessageResult } from "./rest.js";
+
+export interface SendChannelMessageArgs {
+  /** Target channel snowflake. */
+  channelId: string;
+  /** Message content (Discord markdown). */
+  content: string;
+  /**
+   * Discord `allowed_mentions` object. Defaults to `{ parse: [] }` — a message
+   * that merely CONTAINS `<@id>` text should not ping by surprise; opt in
+   * explicitly (or use `mentionMembers` / `broadcastToChannel`).
+   */
+  allowedMentions?: unknown;
+}
+
+/** Post a plain message to a Discord channel (no pings by default). */
+export const sendChannelMessage: DefinedConnectorAction<
+  SendChannelMessageArgs,
+  SendMessageResult
+> = defineConnectorAction({
+  connectorId: DISCORD_PROVIDER_ID,
+  name: "sendChannelMessage",
+  description: "Post a message to a Discord channel (bot-REST).",
+  async run(args) {
+    const res = (await botFetch(`/channels/${args.channelId}/messages`, {
+      method: "POST",
+      body: {
+        content: args.content,
+        allowed_mentions: args.allowedMentions ?? { parse: [] },
+      },
+    })) as { id?: string } | null;
+    return { messageId: res?.id ?? null };
+  },
+});

package/src/gateway/index.ts

@@ -1,4 +1,5 @@
 export { type PostToIngressArgs, postToIngress } from "./ingress.js";
+export { createDiscordRuntime } from "./runtime.js";
 export {
   createDiscordGatewayWorker,
   type DiscordGatewayWorker,

package/src/gateway/runtime.ts

@@ -0,0 +1,46 @@
+import type { ConnectorRuntime, ConnectorRuntimeDeps } from "@hogsend/engine";
+import { createDiscordGatewayWorker } from "./worker.js";
+
+/**
+ * The Discord {@link ConnectorRuntime} factory — the plugin's contribution to
+ * the engine's connector-runtime seam. The consumer passes it to
+ * `createWorker({ connectorRuntimes: { discord: createDiscordRuntime } })`; the
+ * engine elects a single leader replica and calls this with an in-process
+ * `ingest` sink, so the gateway socket forwards dispatches straight into
+ * `transform`→`ingestEvent` — no HTTP ingress hop, no `CONNECTOR_INGRESS_SECRET`.
+ *
+ * Returns `null` when `DISCORD_BOT_TOKEN` is unset — the engine then skips
+ * Discord cleanly (no lease held, dashboard stays truthfully Offline). The bot
+ * token is the platform's OWN env, read here (not in the engine) so the engine
+ * stays platform-neutral; `discord.js` is still imported only inside the worker's
+ * `start()` (dynamic import), so enabling the runtime without the optional peer
+ * fails loudly at start rather than at module load.
+ */
+export function createDiscordRuntime(
+  deps: ConnectorRuntimeDeps,
+): ConnectorRuntime | null {
+  const botToken = process.env.DISCORD_BOT_TOKEN;
+  if (!botToken) {
+    deps.logger.info(
+      "Discord runtime: DISCORD_BOT_TOKEN not set; gateway will not start",
+    );
+    return null;
+  }
+
+  const worker = createDiscordGatewayWorker({
+    botToken,
+    // Unused in inline mode — the poster below replaces the HTTP ingress hop.
+    apiPublicUrl: "",
+    ingressSecret: "",
+    poster: async ({ dispatchType, data }) => deps.ingest(dispatchType, data),
+    // Fold the guild id (seen at GUILD_CREATE) into the engine heartbeat so
+    // Studio confirms "Bot installed".
+    onGuildObserved: (guildId) => deps.onMetadata({ guildId }),
+  });
+
+  return {
+    start: () => worker.start(),
+    stop: () => worker.stop(),
+    getMetadata: () => ({ intents: worker.getIntents() }),
+  };
+}

package/src/gateway/worker.ts

@@ -24,6 +24,13 @@ export interface DiscordGatewayWorkerConfig {
    * it into the gateway heartbeat so Studio can confirm "Bot installed".
    */
   onGuildObserved?: (guildId: string) => void;
+  /**
+   * In-process dispatch sink. When supplied, each raw dispatch is handed to this
+   * poster INSTEAD of the default HTTP ingress POST — so an engine-hosted inline
+   * runtime feeds `transform`→`ingest` directly, with no network hop and no
+   * shared ingress secret. Omit for the standalone (HTTP) path.
+   */
+  poster?: IngressPoster;
 }
 
 export interface DiscordGatewayWorker {
@@ -125,7 +132,9 @@ export function createDiscordGatewayWorker(
       }
       // Fire-and-forget: forwardDispatch never throws (it try/catches and logs),
       // so a slow/failed ingress POST never blocks the socket or crashes us.
-      void forwardDispatch(config, packet);
+      // `config.poster` (engine inline runtime) overrides the default HTTP poster;
+      // undefined ⇒ the standalone HTTP ingress path.
+      void forwardDispatch(config, packet, config.poster);
     });
     // discord.js v14 routes SOCKET errors to `shardError` (and signals lifecycle
     // via `shardDisconnect`/`invalidated`), NOT the generic `error` event. The

package/src/index.ts

@@ -6,6 +6,22 @@
  * `"@hogsend/plugin-discord/gateway"` subpath.
  */
 
+export {
+  type BroadcastToChannelArgs,
+  broadcastToChannel,
+  type DmMemberArgs,
+  type DmResult,
+  discordActions,
+  dmMember,
+  type MentionMembersArgs,
+  type MentionMembersResult,
+  type MentionRoleArgs,
+  mentionMembers,
+  mentionRole,
+  type SendChannelMessageArgs,
+  type SendMessageResult,
+  sendChannelMessage,
+} from "./actions/index.js";
 export {
   ephemeralReply,
   handleInteraction,