@hogsend/plugin-discord 0.22.0

package/src/env.ts

@@ -0,0 +1,25 @@
+/**
+ * The Discord env contract the CONSUMER validates (the engine's `env.ts` owns
+ * `CONNECTOR_INGRESS_SECRET` + `API_PUBLIC_URL`; Discord-specific vars are the
+ * consumer's). This is documentation-as-types: the plugin never reads
+ * `process.env` itself — the connect helpers receive values explicitly so the
+ * package stays env-source-agnostic. The consumer wires these into its own
+ * `@t3-oss/env-core` schema.
+ *
+ * App secrets ALSO live encrypted in `provider_credentials` (kind="derived",
+ * providerId="discord") after `hogsend connect discord` — `DiscordEnv` is the
+ * deploy-time mirror the gateway worker reads to avoid a DB round-trip at boot.
+ * Rotation must update BOTH (see the plugin README rotation runbook).
+ */
+export interface DiscordEnv {
+  /** Bot token (`Bot <token>` for REST + the Gateway login). */
+  DISCORD_BOT_TOKEN?: string;
+  /** OAuth2 application (client) id — bot-install + member-link links. */
+  DISCORD_APPLICATION_ID?: string;
+  /** OAuth2 client secret — server-side code exchange only, never shipped. */
+  DISCORD_CLIENT_SECRET?: string;
+  /** Ed25519 public key (hex) — interactions signature verification. */
+  DISCORD_PUBLIC_KEY?: string;
+  /** Default guild id the bot is installed into (populated after install). */
+  DISCORD_GUILD_ID?: string;
+}

package/src/events.ts

@@ -0,0 +1,16 @@
+/**
+ * The Discord Gateway dispatch → Hogsend event-name vocabulary. This map is the
+ * semver-visible contract: the VALUES are the event names journeys subscribe to
+ * and `user_events` stores, so renaming one is a breaking change. The KEYS are
+ * Discord's raw dispatch types (the `t` field on a Gateway dispatch frame) the
+ * connector branches on.
+ */
+export const DiscordEvents = {
+  MESSAGE_CREATE: "discord.message_sent",
+  MESSAGE_REACTION_ADD: "discord.reaction_added",
+  GUILD_MEMBER_ADD: "discord.member_joined",
+  PRESENCE_UPDATE: "discord.presence_active",
+} as const;
+
+export type DiscordDispatchType = keyof typeof DiscordEvents;
+export type DiscordEventName = (typeof DiscordEvents)[DiscordDispatchType];

package/src/gateway/index.ts

@@ -0,0 +1,7 @@
+export { type PostToIngressArgs, postToIngress } from "./ingress.js";
+export {
+  createDiscordGatewayWorker,
+  type DiscordGatewayWorker,
+  type DiscordGatewayWorkerConfig,
+  forwardDispatch,
+} from "./worker.js";

package/src/gateway/ingress.ts

@@ -0,0 +1,50 @@
+/**
+ * The dumb relay client: the long-lived gateway worker POSTs each raw Discord
+ * Gateway dispatch to the connector's own ingress
+ * (`POST /v1/connectors/discord/ingress`) behind the shared internal secret,
+ * so ALL transform logic stays in the connector and the socket worker carries
+ * none of it. `fetch`-only; zero `discord.js`.
+ */
+
+import { DISCORD_PROVIDER_ID } from "../constants.js";
+
+export interface PostToIngressArgs {
+  /** Public base URL of the engine API instance. */
+  apiPublicUrl: string;
+  /** Shared internal secret (`CONNECTOR_INGRESS_SECRET`). */
+  ingressSecret: string;
+  /** The raw Discord dispatch type (the `t` on a Gateway frame). */
+  dispatchType: string;
+  /** The raw Discord dispatch `d` payload, forwarded untouched. */
+  data: unknown;
+}
+
+export interface PostToIngressResult {
+  ok: boolean;
+  status: number;
+}
+
+/**
+ * Forward one dispatch to the connector ingress. Wraps the payload as
+ * `{ __t, d }` — the exact shape the connector transform unwraps. The shared
+ * secret rides the `x-hogsend-ingress-secret` header (the ingress route
+ * fails CLOSED when it is unset/mismatched).
+ */
+export async function postToIngress(
+  args: PostToIngressArgs,
+): Promise<PostToIngressResult> {
+  const url =
+    `${args.apiPublicUrl.replace(/\/$/, "")}` +
+    `/v1/connectors/${DISCORD_PROVIDER_ID}/ingress`;
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-hogsend-ingress-secret": args.ingressSecret,
+    },
+    body: JSON.stringify({ __t: args.dispatchType, d: args.data }),
+  });
+
+  return { ok: res.ok, status: res.status };
+}

package/src/gateway/worker.ts

@@ -0,0 +1,180 @@
+import { DISCORD_INTENTS } from "../constants.js";
+import { DiscordEvents } from "../events.js";
+import { type PostToIngressResult, postToIngress } from "./ingress.js";
+
+/**
+ * The long-lived Discord Gateway worker. It is its OWN entrypoint / Railway
+ * service (NOT a Hatchet task): it holds a `discord.js` socket and forwards
+ * every relevant raw dispatch to the connector ingress via {@link postToIngress}
+ * so the transform stays server-side and this worker stays dumb.
+ *
+ * `discord.js` is an OPTIONAL peer, dynamically imported inside `start()` so the
+ * engine API process (which imports the connector but never this file) never
+ * loads a WebSocket client.
+ */
+
+export interface DiscordGatewayWorkerConfig {
+  botToken: string;
+  apiPublicUrl: string;
+  ingressSecret: string;
+  /** Which intents to request. Defaults to the privileged trio + base. */
+  intents?: number;
+  /**
+   * Called with the guild id observed at `GUILD_CREATE` — lets the consumer fold
+   * it into the gateway heartbeat so Studio can confirm "Bot installed".
+   */
+  onGuildObserved?: (guildId: string) => void;
+}
+
+export interface DiscordGatewayWorker {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  /**
+   * The resolved intents bitfield this worker requests at login (the configured
+   * value, else the default privileged trio + base). Lets the consumer fold the
+   * live intents into the gateway heartbeat for Studio's intents chip.
+   */
+  getIntents(): number;
+}
+
+/**
+ * The single dispatch→ingress hop, injected so the mapping can be unit-tested
+ * without a live socket (production passes {@link postToIngress}).
+ */
+type IngressPoster = (args: {
+  apiPublicUrl: string;
+  ingressSecret: string;
+  dispatchType: string;
+  data: unknown;
+}) => Promise<PostToIngressResult>;
+
+/**
+ * Forward one raw Gateway dispatch to the connector ingress. REAL + correct —
+ * the live socket loop in `start()` calls exactly this on every `raw` packet.
+ * Skips dispatch types the connector does not map (cheap pre-filter) and never
+ * throws (a forward failure is logged, not fatal, so the socket stays up).
+ *
+ * Exported for unit tests: the dispatch→ingress mapping (pre-filter + `{ __t, d }`
+ * wrapping + shared-secret forwarding) is exercised by injecting a fake poster,
+ * so no live `discord.js` socket is needed.
+ */
+export async function forwardDispatch(
+  config: DiscordGatewayWorkerConfig,
+  packet: { t?: string | null; d?: unknown },
+  poster: IngressPoster = postToIngress,
+): Promise<void> {
+  if (!packet.t || !(packet.t in DiscordEvents)) return;
+  try {
+    const result = await poster({
+      apiPublicUrl: config.apiPublicUrl,
+      ingressSecret: config.ingressSecret,
+      dispatchType: packet.t,
+      data: packet.d,
+    });
+    if (!result.ok) {
+      console.error(
+        `discord ingress forward non-2xx (${result.status}) for ${packet.t}`,
+      );
+    }
+  } catch (err) {
+    // Log the message only (not the raw error object) — the worker's sole
+    // secret is the bot token; matches the status-only hygiene in connect/oauth.
+    console.error(
+      "discord ingress forward failed:",
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}
+
+export function createDiscordGatewayWorker(
+  config: DiscordGatewayWorkerConfig,
+): DiscordGatewayWorker {
+  const intents =
+    config.intents ??
+    DISCORD_INTENTS.GUILDS |
+      DISCORD_INTENTS.GUILD_MEMBERS |
+      DISCORD_INTENTS.GUILD_MESSAGES |
+      DISCORD_INTENTS.GUILD_MESSAGE_REACTIONS |
+      DISCORD_INTENTS.GUILD_PRESENCES |
+      DISCORD_INTENTS.MESSAGE_CONTENT;
+
+  // Structural holder — keeps zero `discord.js` type coupling at module load
+  // (the runtime module is only pulled by the dynamic import inside start()).
+  let client: { destroy(): Promise<void> } | undefined;
+
+  async function start(): Promise<void> {
+    // `discord.js` is an OPTIONAL peer, dynamically imported here so the engine
+    // API process (connector/destination only) never loads a WebSocket client.
+    const { Client } = await import("discord.js");
+    const c = new Client({ intents });
+    client = c;
+
+    // Forward EVERY raw Gateway dispatch — the connector transform owns event
+    // selection, so the worker subscribes to nothing typed and stays dumb.
+    // `raw` isn't in discord.js's typed `ClientEvents`, but `Client#on` has a
+    // string overload that types args as `unknown[]`, so an explicit packet
+    // annotation compiles with no cast. discord.js emits the full raw Gateway
+    // frame ({ t, s, op, d }) on every Dispatch.
+    c.on("raw", (packet: { t?: string | null; d?: unknown }) => {
+      // Surface the guild id at GUILD_CREATE so the consumer can fold it into
+      // the gateway heartbeat — the strongest "Bot installed" proof for an
+      // env-only deploy (no derived credential carrying a guild id).
+      if (config.onGuildObserved && packet.t === "GUILD_CREATE") {
+        const gid = (packet.d as { id?: string } | undefined)?.id;
+        if (gid) config.onGuildObserved(gid);
+      }
+      // 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);
+    });
+    // discord.js v14 routes SOCKET errors to `shardError` (and signals lifecycle
+    // via `shardDisconnect`/`invalidated`), NOT the generic `error` event. The
+    // generic `error` listener stays purely as the EventEmitter safety net — an
+    // unhandled 'error' emit takes the process down, so we keep one registered
+    // even though it catches almost nothing in normal operation.
+    c.on("error", (err: Error) => {
+      console.error("discord gateway client error:", err.message);
+    });
+    // Per-shard transport error — @discordjs/ws auto-reconnects underneath, so
+    // log (message only) and let it recover. Without this listener the shard
+    // error can escalate to an unhandled EventEmitter 'error' and crash us.
+    c.on("shardError", (err: Error, shardId: number) => {
+      console.error(`discord gateway shard ${shardId} error:`, err.message);
+    });
+    // A shard dropped its socket. discord.js attempts RESUME/reconnect, so this
+    // is usually recoverable — log the close code (no secrets) and ride it out.
+    // closeCode 1000 is a clean close; 4004/4013/4014 (bad token / invalid or
+    // disallowed intents) are unrecoverable and surface via `invalidated`.
+    c.on("shardDisconnect", (closeEvent: { code: number }, shardId: number) => {
+      console.error(
+        `discord gateway shard ${shardId} disconnected (close ${closeEvent.code})`,
+      );
+    });
+    // discord.js gave up reconnecting (session invalidated / unrecoverable) —
+    // the socket is dead and zero events will flow, yet the process would
+    // otherwise sit idle looking healthy. Fail loudly so the orchestrator
+    // (Railway) restarts a fresh worker instead of a silent black hole.
+    c.on("invalidated", () => {
+      console.error(
+        "discord gateway session invalidated — exiting so a fresh worker starts",
+      );
+      process.exit(1);
+    });
+    c.once("ready", () => {
+      console.log("discord gateway worker connected");
+    });
+
+    // Rejects on a bad token or disallowed (un-toggled) privileged intents —
+    // that rejection propagates out of start(), so a misconfigured worker still
+    // fails loudly. discord.js owns heartbeat / RESUME / reconnect / sharding.
+    await c.login(config.botToken);
+  }
+
+  async function stop(): Promise<void> {
+    // Closes the shard(s) and clears timers; await so SIGTERM/SIGINT drains.
+    await client?.destroy();
+    client = undefined;
+  }
+
+  return { start, stop, getIntents: () => intents };
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * `@hogsend/plugin-discord` engine-facing surface — the INBOUND connector + its
+ * connect-time factory, the OUTBOUND destination, and the `fetch`/`node:crypto`
+ * connect helpers. ZERO `discord.js`: everything here runs inside the engine API
+ * process. The long-lived Gateway worker is exported ONLY from the
+ * `"@hogsend/plugin-discord/gateway"` subpath.
+ */
+
+export {
+  ephemeralReply,
+  handleInteraction,
+  InteractionCallbackFlags,
+  type InteractionDeps,
+  type InteractionResponse,
+  InteractionResponseType,
+  InteractionType,
+  isLikelyEmail,
+  LINK_CODE_TTL_SECONDS,
+  type LinkMintResult,
+  type LinkRedeemResult,
+  type ParsedCommand,
+  parseCommand,
+  type VerifyAttemptResult,
+  verifyInteractionSignature,
+} from "./connect/interactions.js";
+export { editInteractionResponse } from "./connect/interactions-followup.js";
+export {
+  type DiscordMemberLink,
+  type MemberLinkContactPatch,
+  memberLinkToContactPatch,
+} from "./connect/member-link.js";
+export {
+  buildBotInstallUrl,
+  buildMemberLinkUrl,
+  type DiscordCurrentUser,
+  type DiscordTokenResponse,
+  exchangeDiscordCode,
+  getCurrentUser,
+} from "./connect/oauth.js";
+export {
+  type PatchApplicationArgs,
+  type PatchApplicationResult,
+  patchApplication,
+} from "./connect/patch-application.js";
+export {
+  type CreateDiscordConnectorConfig,
+  createDiscordConnector,
+  type DiscordConnectorWithHandlers,
+  /**
+   * The bare `discordConnector` is TRANSFORM-ONLY — it has NO `handlers`, so
+   * the generic oauth/interactions routes cannot dispatch into it (a bare
+   * registration warns + 404s). Register {@link createDiscordConnector}(config)
+   * — the connect-ready clone with `handlers` populated — to serve the connect
+   * flow. The bare const is exported only for the gateway worker's transform.
+   */
+  discordConnector,
+} from "./connector.js";
+export {
+  DISCORD_API_BASE,
+  DISCORD_BOT_INSTALL_SCOPES,
+  DISCORD_INTENTS,
+  DISCORD_MEMBER_LINK_SCOPES,
+  DISCORD_PROVIDER_ID,
+} from "./constants.js";
+export { discordDestination } from "./destination.js";
+export type { DiscordEnv } from "./env.js";
+export {
+  type DiscordDispatchType,
+  type DiscordEventName,
+  DiscordEvents,
+} from "./events.js";

package/src/types.ts

@@ -0,0 +1,61 @@
+/**
+ * The narrow subset of Discord Gateway dispatch payloads the connector reads.
+ * Deliberately partial — these are the `d` (data) shapes of the four dispatch
+ * types in {@link DiscordEvents}, typed only for the fields the transform
+ * touches. The full Discord objects carry far more; everything unused is left
+ * off so the transform's data dependency is explicit.
+ *
+ * Field names are Discord's verbatim (snake_case) because the gateway worker
+ * forwards the raw `d` payload untouched (see `gateway/ingress.ts`).
+ */
+
+/** Common Discord user object subset (present across dispatch payloads). */
+export interface DiscordUser {
+  id: string;
+  username?: string;
+  /** Discord's display name (the post-2023 unique-name system). */
+  global_name?: string | null;
+  /** Avatar hash (NOT a URL) — the CDN URL is built consumer-side if needed. */
+  avatar?: string | null;
+  /** Discord's BOT flag — bot/system authors are dropped by the transform. */
+  bot?: boolean;
+  /** Verified-email flag (member-link only; never trusted from a bare event). */
+  verified?: boolean;
+  email?: string | null;
+}
+
+/** `MESSAGE_CREATE` `d` subset. */
+export interface DiscordMessageCreate {
+  id: string;
+  channel_id: string;
+  guild_id?: string | null;
+  content?: string;
+  author: DiscordUser;
+  /** Present when the message was sent by a webhook (dropped by transform). */
+  webhook_id?: string;
+}
+
+/** `MESSAGE_REACTION_ADD` `d` subset. */
+export interface DiscordReactionAdd {
+  user_id: string;
+  channel_id: string;
+  message_id: string;
+  guild_id?: string | null;
+  emoji?: { id?: string | null; name?: string | null };
+}
+
+/** `GUILD_MEMBER_ADD` `d` subset. */
+export interface DiscordGuildMemberAdd {
+  guild_id: string;
+  joined_at?: string | null;
+  /** Role ids granted at join (the GUILD_MEMBER_ADD `d` carries them). */
+  roles?: string[];
+  user?: DiscordUser;
+}
+
+/** `PRESENCE_UPDATE` `d` subset. */
+export interface DiscordPresenceUpdate {
+  guild_id?: string | null;
+  status?: "online" | "idle" | "dnd" | "offline";
+  user?: { id?: string };
+}