@hogsend/plugin-discord 0.22.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025 Doug Silkstone and Hogsend contributors
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,235 @@
+# @hogsend/plugin-discord
+
+Discord integration for Hogsend — both faces of one platform:
+
+- **Inbound** — a `transport: "gateway"` connector (`discordConnector`) that
+  turns raw Discord Gateway dispatches (messages, reactions, joins, presence)
+  into `IngestEvent`s. The socket itself lives in a separate long-lived worker
+  (`@hogsend/plugin-discord/gateway`) that POSTs each dispatch to the connector
+  ingress (`POST /v1/connectors/discord/ingress`) so all transform logic stays
+  server-side.
+- **Outbound** — a `defineDestination` (`discordDestination`) that posts a
+  message per lifecycle event to a Discord channel (incoming webhook preferred,
+  bot-REST as the alt).
+
+Same `meta.id = "discord"` on both so they read as one integration.
+
+Full setup and the four event mappings live in the
+[Discord integration docs](https://hogsend.com/docs/integrations/discord).
+
+## Inbound events
+
+The server-side connector transform emits these into `ingestEvent()` (stored in
+`user_events` + upserts a contact). Bot/webhook/system messages and
+offline/absent presence are dropped; each event carries a deterministic
+`idempotencyKey` so redelivery dedupes.
+
+| Discord dispatch       | Hogsend event              |
+| ---------------------- | -------------------------- |
+| `MESSAGE_CREATE`       | `discord.message_sent`     |
+| `MESSAGE_REACTION_ADD` | `discord.reaction_added`   |
+| `GUILD_MEMBER_ADD`     | `discord.member_joined`    |
+| `PRESENCE_UPDATE`      | `discord.presence_active`  |
+
+## Identity
+
+`contacts.discord_id` is a 4th contact identity Kind
+(`external | email | anonymous | discord`) — the raw snowflake is the indexed
+merge key (partial unique index). The connector also writes
+`contacts.properties.discord` (deep-merged one level, non-clobbering): `id` and
+`last_seen` always, plus conditional `username`, `global_name`, `avatar`,
+`joined_at`, and `roles`. `null` is never written.
+
+`last_seen` is DERIVED first-party (the max of observed event timestamps —
+Discord has no last-seen field). Presence is collapsed to "active" (offline and
+absent are dropped), so presence is not a last-seen feed.
+
+## The `/link` identity loop
+
+`/link` (no options) opens an email modal. A valid address mails a 6-digit code
+via a transactional template; an "Enter code" button then opens a code modal
+that redeems it and resolves the contact (the button is the mandatory bridge —
+Discord forbids returning a modal from a modal submit). Every step is ephemeral;
+no message body echoes the email or code. `/verify <code>` is the typed
+fallback.
+
+Codes are single-use (atomic claim), have a 15-min TTL, are bound to the
+invoking Discord user (constant-time compare), and are hashed at rest. Throttles:
+5 mints/user + 3 mints/email per 15-min window (engine); an optional consumer
+Redis throttle of 10 `/verify` attempts/user/15 min (fail-open). Every
+interaction is ed25519-verified (native `node:crypto`, fail-closed) with a ±300s
+timestamp replay window.
+
+## Routes
+
+The engine mounts these under `/v1/connectors/discord`:
+
+| Route                                       | Purpose                                          | Auth                                                          |
+| ------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| `POST /v1/connectors/discord/ingress`       | Gateway worker posts raw dispatches              | `x-hogsend-ingress-secret` header (= `CONNECTOR_INGRESS_SECRET`, ≥32 chars, fail-closed) |
+| `POST /v1/connectors/discord/interactions`  | Discord HTTP interactions (slash/modal/button)   | ed25519 signature + ±300s replay window                      |
+| `GET\|POST /v1/connectors/discord/oauth/callback` | OAuth install + member-link (not wired in apps/api) | signed CSRF `state`, engine-verified                         |
+
+`/v1/connectors/*` is per-IP rate-limited (60/min) EXCEPT `/ingress` and
+`/interactions` (exempt — gated by the ingress secret and ed25519+replay).
+
+## Install
+
+```bash
+pnpm add @hogsend/plugin-discord
+# the Gateway worker needs discord.js (an optional peer):
+pnpm add discord.js
+```
+
+`discord.js` is an **optional peer** — only the `/gateway` subpath imports it.
+The engine API process imports `discordConnector` / `discordDestination` /
+connect helpers from the main entry and never loads a WebSocket client.
+
+## Wiring (consumer)
+
+All callbacks below are required (only `recordVerifyAttempt` is optional). The
+consumer injects the engine helpers so the plugin never reaches into the engine
+itself — see `apps/api/src/discord.ts` for the full reference wiring.
+
+```ts
+import {
+  createLinkCode,
+  getDerivedCredential,
+  getEmailService,
+  redeemLinkCode,
+  resolveOrCreateContact,
+  saveDerivedCredential,
+} from "@hogsend/engine";
+import {
+  createDiscordConnector,
+  discordDestination,
+} from "@hogsend/plugin-discord";
+
+const base = env.API_PUBLIC_URL.replace(/\/$/, "");
+
+const discord = createDiscordConnector({
+  applicationId: env.DISCORD_APPLICATION_ID,
+  clientSecret: env.DISCORD_CLIENT_SECRET,
+  publicKeyHex: env.DISCORD_PUBLIC_KEY,
+  redirectUri: `${base}/v1/connectors/discord/oauth/callback`,
+  // Studio's SPA is mounted at /studio, so its integrations page lives at
+  // /studio/integrations (NOT /integrations, which 404s at the API root).
+  studioIntegrationsUrl: `${base}/studio/integrations`,
+  // Read-merge-write — the derived store is a full-payload OVERWRITE.
+  saveDerived: async (patch) => {
+    const current = (await getDerivedCredential(db, "discord")) ?? {};
+    await saveDerivedCredential(db, "discord", { ...current, ...patch });
+  },
+  // Route the snowflake through the `discord` identity Kind; `email` is the
+  // engine-verified address the link was issued for (never the OAuth email).
+  resolveContact: async (patch) => {
+    await resolveOrCreateContact({
+      db,
+      discordId: patch.discordId,
+      email: patch.email,
+      contactProperties: patch.contactProperties,
+    });
+  },
+  // Mint a single-use code — the anti-email-bomb throttle runs FIRST inside
+  // createLinkCode; over-cap returns { ok: false } with no mint.
+  mintCode: async ({ discordUserId, email }) => {
+    const r = await createLinkCode({
+      db,
+      connectorId: "discord",
+      platformUserId: discordUserId,
+      email,
+    });
+    return r.ok ? { ok: true, code: r.code } : { ok: false, reason: "throttled" };
+  },
+  // TRANSACTIONAL send — skipPreferenceCheck so a code is NEVER dropped by an
+  // unsubscribe or frequency cap.
+  sendLinkCode: async ({ email, code }) => {
+    await getEmailService().send({
+      template: "transactional/discord-link-code",
+      props: { code },
+      to: email,
+      userId: email,
+      userEmail: email,
+      subject: "Your Discord verification code",
+      category: "transactional",
+      skipPreferenceCheck: true,
+    });
+  },
+  // Redeem — single-use (atomic claim), TTL-enforced, identity-bound.
+  redeemCode: ({ discordUserId, code }) =>
+    redeemLinkCode({
+      db,
+      connectorId: "discord",
+      platformUserId: discordUserId,
+      code,
+    }),
+});
+
+const client = createHogsendClient({
+  connectors: [discord],
+  destinations: [discordDestination],
+});
+```
+
+## Gateway worker
+
+A separate Railway service (mirrors `railway.worker.toml`):
+
+```ts
+import { createDiscordGatewayWorker } from "@hogsend/plugin-discord/gateway";
+
+const worker = createDiscordGatewayWorker({
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  apiPublicUrl: process.env.API_PUBLIC_URL!,
+  ingressSecret: process.env.CONNECTOR_INGRESS_SECRET!,
+});
+process.on("SIGTERM", () => void worker.stop());
+process.on("SIGINT", () => void worker.stop());
+await worker.start();
+```
+
+`start()` dynamically imports `discord.js`, logs in with the bot token, and
+forwards every raw Gateway dispatch to the ingress via `forwardDispatch`
+(`{ __t, d }` wrapping over `postToIngress`). It fails loudly: `login()` rejects
+(and the rejection propagates out of `start()`) on a bad token or a requested
+privileged intent that is not toggled in the portal, so a misconfigured worker
+is never silently dead. discord.js owns heartbeat / RESUME / reconnect /
+sharding.
+
+## Secrets & rotation
+
+Discord app secrets are held in **two places**:
+
+1. Encrypted in `provider_credentials` (kind `derived`, providerId `discord`)
+   for the API-side connect helpers — written by `hogsend connect discord`.
+2. Plain env on the deployed Gateway worker (`DISCORD_BOT_TOKEN`) so it can log
+   in without a DB round-trip at boot.
+
+**Rotation runbook** — rotate the bot token in the Discord Developer Portal,
+then:
+
+1. Re-run `hogsend connect discord` (re-paste the new token) to update the
+   encrypted derived store, **and**
+2. Update `DISCORD_BOT_TOKEN` on the Gateway worker service and redeploy it.
+
+Both copies point at the same token; updating only one leaves them drifted.
+
+## Required intents
+
+Toggle ON in the Developer Portal (Bot → Privileged Gateway Intents):
+`SERVER MEMBERS`, `PRESENCE`, and `MESSAGE CONTENT`. Without them the Gateway
+connection is rejected and message text is empty (`hasContent` reports it).
+Under 10k users / 100 guilds these three are a self-serve portal toggle (no
+Discord review). Each self-hosted deploy runs its own Discord app (single
+tenant).
+
+## Caveats
+
+- The bot must be a guild member to receive a channel's events.
+- Presence is not last-seen (offline/absent dropped; `last_seen` is derived).
+- The one-click install + OAuth member-link (`hogsend connect discord`) is NOT
+  wired in `apps/api` yet — the consumer-mounted `secrets`/`wire` admin routes
+  are unmounted, so that CLI 404s today. Use the env-only inbound path
+  (Gateway → ingress) and the modal `/link` for identity.
+- First npm publish of this package is MANUAL — CI cannot create a brand-new
+  `@hogsend/*` package.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hogsend/plugin-discord",
+  "version": "0.22.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/plugin-discord"
+  },
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./gateway": "./src/gateway/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hogsend/engine": "^0.22.0"
+  },
+  "peerDependencies": {
+    "discord.js": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "discord.js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "discord.js": "^14.26.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.7",
+    "@repo/typescript-config": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest watch"
+  }
+}

package/src/__tests__/connector-transform.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it, vi } from "vitest";
+import { discordConnector } from "../connector.js";
+import { DiscordEvents } from "../events.js";
+
+/**
+ * The connector transform is pure (no db/network touched), so the ctx is a
+ * stub: a no-op logger + a cast db. `transport: "gateway"` matches the ingress.
+ */
+const logger = {
+  debug: vi.fn(),
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+};
+const ctx = {
+  db: {} as never,
+  logger: logger as never,
+  transport: "gateway" as const,
+};
+
+function wrap(t: keyof typeof DiscordEvents, d: unknown) {
+  return { __t: t, d };
+}
+
+describe("discordConnector.transform", () => {
+  it("maps MESSAGE_CREATE → discord.message_sent with derived lastSeen", async () => {
+    const event = await discordConnector.transform(
+      wrap("MESSAGE_CREATE", {
+        // snowflake encoding a known epoch-ish timestamp
+        id: "175928847299117063",
+        channel_id: "c1",
+        guild_id: "g1",
+        content: "hi there",
+        author: { id: "u1", username: "alice" },
+      }),
+      ctx,
+    );
+    expect(event).not.toBeNull();
+    expect(event?.event).toBe(DiscordEvents.MESSAGE_CREATE);
+    expect(event?.userId).toBe("discord:u1");
+    // discordId is the snowflake (forward-compat IngestEvent field)
+    expect((event as { discordId?: string })?.discordId).toBe("u1");
+    expect(event?.eventProperties.hasContent).toBe(true);
+    expect(event?.eventProperties.guildId).toBe("g1");
+    // Nested NON-KEY metadata under contactProperties.discord (deep-merged
+    // engine-side); discord_id stays the sole identity key.
+    const meta = event?.contactProperties?.discord as Record<string, unknown>;
+    expect(meta.id).toBe("u1");
+    expect(meta.username).toBe("alice");
+    expect(meta.last_seen).toBeTypeOf("string");
+    expect(event?.idempotencyKey).toBe("discord:msg:175928847299117063");
+    // occurredAt derived from the snowflake (not "now")
+    expect(event?.occurredAt).toBeInstanceOf(Date);
+  });
+
+  it("hasContent=false when MESSAGE_CONTENT intent yields empty text", async () => {
+    const event = await discordConnector.transform(
+      wrap("MESSAGE_CREATE", {
+        id: "175928847299117064",
+        channel_id: "c1",
+        content: "",
+        author: { id: "u2" },
+      }),
+      ctx,
+    );
+    expect(event?.eventProperties.hasContent).toBe(false);
+  });
+
+  it("drops bot and webhook messages (returns null)", async () => {
+    const bot = await discordConnector.transform(
+      wrap("MESSAGE_CREATE", {
+        id: "1",
+        channel_id: "c1",
+        author: { id: "b1", bot: true },
+      }),
+      ctx,
+    );
+    const hook = await discordConnector.transform(
+      wrap("MESSAGE_CREATE", {
+        id: "2",
+        channel_id: "c1",
+        webhook_id: "w1",
+        author: { id: "x1" },
+      }),
+      ctx,
+    );
+    expect(bot).toBeNull();
+    expect(hook).toBeNull();
+  });
+
+  it("maps MESSAGE_REACTION_ADD with deterministic idempotency key", async () => {
+    const event = await discordConnector.transform(
+      wrap("MESSAGE_REACTION_ADD", {
+        user_id: "u9",
+        channel_id: "c2",
+        message_id: "m5",
+        guild_id: "g2",
+        emoji: { name: "🔥" },
+      }),
+      ctx,
+    );
+    expect(event?.event).toBe(DiscordEvents.MESSAGE_REACTION_ADD);
+    expect(event?.userId).toBe("discord:u9");
+    expect(event?.eventProperties.emoji).toBe("🔥");
+    expect(event?.idempotencyKey).toBe("discord:react:m5:u9:🔥");
+  });
+
+  it("maps GUILD_MEMBER_ADD → discord.member_joined", async () => {
+    const event = await discordConnector.transform(
+      wrap("GUILD_MEMBER_ADD", {
+        guild_id: "g3",
+        joined_at: "2026-06-13T00:00:00.000Z",
+        roles: ["r1", "r2"],
+        user: {
+          id: "u10",
+          username: "bob",
+          global_name: "Bob",
+          avatar: "abc123",
+        },
+      }),
+      ctx,
+    );
+    expect(event?.event).toBe(DiscordEvents.GUILD_MEMBER_ADD);
+    expect(event?.userId).toBe("discord:u10");
+    const meta = event?.contactProperties?.discord as Record<string, unknown>;
+    expect(meta.id).toBe("u10");
+    expect(meta.username).toBe("bob");
+    expect(meta.global_name).toBe("Bob");
+    expect(meta.avatar).toBe("abc123");
+    expect(meta.joined_at).toBe("2026-06-13T00:00:00.000Z");
+    expect(meta.roles).toEqual(["r1", "r2"]);
+    expect(event?.idempotencyKey).toBe("discord:join:g3:u10");
+  });
+
+  it("drops a bot GUILD_MEMBER_ADD", async () => {
+    const event = await discordConnector.transform(
+      wrap("GUILD_MEMBER_ADD", {
+        guild_id: "g3",
+        user: { id: "bot1", bot: true },
+      }),
+      ctx,
+    );
+    expect(event).toBeNull();
+  });
+
+  it("collapses non-offline presence to discord.presence_active", async () => {
+    const online = await discordConnector.transform(
+      wrap("PRESENCE_UPDATE", { user: { id: "u11" }, status: "online" }),
+      ctx,
+    );
+    expect(online?.event).toBe(DiscordEvents.PRESENCE_UPDATE);
+    expect(online?.eventProperties.status).toBe("online");
+
+    const offline = await discordConnector.transform(
+      wrap("PRESENCE_UPDATE", { user: { id: "u11" }, status: "offline" }),
+      ctx,
+    );
+    expect(offline).toBeNull();
+  });
+
+  it("logs + drops an unmapped dispatch", async () => {
+    const event = await discordConnector.transform(
+      { __t: "TYPING_START", d: {} },
+      ctx,
+    );
+    expect(event).toBeNull();
+    expect(logger.debug).toHaveBeenCalled();
+  });
+
+  it("declares gateway transport with a derived credential, no inboundVerify", () => {
+    expect(discordConnector.meta.transport).toBe("gateway");
+    expect(discordConnector.inboundVerify).toBeUndefined();
+    expect(discordConnector.credential).toEqual({
+      providerId: "discord",
+      kind: "derived",
+    });
+  });
+});

package/src/__tests__/gateway-forward.test.ts

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DiscordEvents } from "../events.js";
+import {
+  type DiscordGatewayWorkerConfig,
+  forwardDispatch,
+} from "../gateway/worker.js";
+
+/**
+ * Unit-tests the dispatch→ingress mapping WITHOUT a live `discord.js` socket:
+ * a fake poster is injected (the same seam `start()` calls on every raw packet),
+ * so we assert the pre-filter, the args handed to ingress, and the never-throws
+ * contract independently of the WebSocket loop.
+ */
+const config: DiscordGatewayWorkerConfig = {
+  botToken: "Bot fake-token",
+  apiPublicUrl: "https://tunnel.example.com",
+  ingressSecret: "x".repeat(32),
+};
+
+let errorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  errorSpy.mockRestore();
+  vi.restoreAllMocks();
+});
+
+describe("forwardDispatch", () => {
+  it("forwards a mapped dispatch with the exact ingress args", async () => {
+    const poster = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    const d = { id: "1", author: { id: "u1" } };
+
+    await forwardDispatch(config, { t: "MESSAGE_CREATE", d }, poster);
+
+    expect(poster).toHaveBeenCalledTimes(1);
+    expect(poster).toHaveBeenCalledWith({
+      apiPublicUrl: config.apiPublicUrl,
+      ingressSecret: config.ingressSecret,
+      dispatchType: "MESSAGE_CREATE",
+      data: d,
+    });
+  });
+
+  it("forwards every mapped Discord dispatch type", async () => {
+    const poster = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    for (const t of Object.keys(DiscordEvents)) {
+      await forwardDispatch(config, { t, d: { probe: t } }, poster);
+    }
+    expect(poster).toHaveBeenCalledTimes(Object.keys(DiscordEvents).length);
+    for (const t of Object.keys(DiscordEvents)) {
+      expect(poster).toHaveBeenCalledWith(
+        expect.objectContaining({ dispatchType: t }),
+      );
+    }
+  });
+
+  it("skips an unmapped dispatch type (cheap pre-filter, no POST)", async () => {
+    const poster = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    await forwardDispatch(config, { t: "TYPING_START", d: {} }, poster);
+    expect(poster).not.toHaveBeenCalled();
+  });
+
+  it("skips a frame with no dispatch type (op-only / heartbeat ack)", async () => {
+    const poster = vi.fn().mockResolvedValue({ ok: true, status: 200 });
+    await forwardDispatch(config, { t: null, d: undefined }, poster);
+    await forwardDispatch(config, {}, poster);
+    expect(poster).not.toHaveBeenCalled();
+  });
+
+  it("logs a non-2xx ingress response but does not throw", async () => {
+    const poster = vi.fn().mockResolvedValue({ ok: false, status: 401 });
+    await expect(
+      forwardDispatch(config, { t: "MESSAGE_CREATE", d: {} }, poster),
+    ).resolves.toBeUndefined();
+    expect(errorSpy).toHaveBeenCalledWith(
+      expect.stringContaining("non-2xx (401)"),
+    );
+  });
+
+  it("swallows a thrown poster error (socket stays up)", async () => {
+    const poster = vi.fn().mockRejectedValue(new Error("network down"));
+    await expect(
+      forwardDispatch(config, { t: "GUILD_MEMBER_ADD", d: {} }, poster),
+    ).resolves.toBeUndefined();
+    // message-only log (secret hygiene): the raw Error object is never logged.
+    expect(errorSpy).toHaveBeenCalledWith(
+      "discord ingress forward failed:",
+      "network down",
+    );
+  });
+});