shardwire 0.2.0 → 1.1.0

package/README.md

@@ -1,339 +1,235 @@
-# shardwire
+# Shardwire
 
-> Lightweight TypeScript library for building a Discord-hosted WebSocket command and event bridge.
+[![npm version](https://img.shields.io/npm/v/shardwire)](https://www.npmjs.com/package/shardwire)
+[![npm downloads](https://img.shields.io/npm/dm/shardwire)](https://www.npmjs.com/package/shardwire)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.18-339933)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-[![npm version](https://img.shields.io/npm/v/shardwire?style=flat-square)](https://www.npmjs.com/package/shardwire)
-[![npm downloads](https://img.shields.io/npm/dm/shardwire?style=flat-square)](https://www.npmjs.com/package/shardwire)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.18-3c873a?style=flat-square)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
+Discord-first bridge for streaming bot events to external apps and executing bot actions over one WebSocket connection.
 
-`shardwire` helps you expose strongly-typed bot capabilities over WebSocket so dashboards, admin tools, and backend services can send commands to your Discord bot host and subscribe to events in real time.
+Shardwire is built for a common architecture: your Discord bot runs in one process, while your web app, backend API, worker, or dashboard runs in another.
 
-[Quick Start](#quick-start) • [Why shardwire](#why-shardwire) • [Host Setup](#host-setup) • [Consumer Setup](#consumer-setup) • [API Overview](#api-overview) • [Configuration](#configuration) • [Security Notes](#security-notes)
+## Why Shardwire
 
-## Table of Contents
+- **Discord-first API**: no generic command bus wiring required.
+- **App-friendly payloads**: receive normalized JSON payloads instead of live `discord.js` objects.
+- **Built-in actions**: send messages, reply to interactions, moderate members, and more from your app process.
+- **Scoped permissions**: restrict each app secret to specific events and actions.
+- **Capability-aware runtime**: apps can inspect what they are allowed to subscribe to and invoke.
 
-- [Why shardwire](#why-shardwire)
-- [Features](#features)
-- [Quick Start](#quick-start)
-- [Host Setup](#host-setup)
-- [Consumer Setup](#consumer-setup)
-- [Token-Only Host (No Existing discord.js Client)](#token-only-host-no-existing-discordjs-client)
-- [Reconnect and Timeout Hardening](#reconnect-and-timeout-hardening)
-- [API Overview](#api-overview)
-- [Configuration](#configuration)
-- [Error Model](#error-model)
-- [Recipes and Troubleshooting](#recipes-and-troubleshooting)
-- [Compatibility](#compatibility)
-- [Security Notes](#security-notes)
-- [Roadmap Constraints (v1)](#roadmap-constraints-v1)
+## Requirements
 
-## Why shardwire
-
-Running bot logic inside your Discord host process while orchestrating it from external services is a common pattern, but wiring this safely and ergonomically takes time. `shardwire` gives you a focused transport layer with a typed contract so you can:
-
-- call bot-hosted commands from apps and services,
-- stream real-time events back to consumers,
-- keep payloads typed end-to-end with TypeScript,
-- start quickly without deploying extra infrastructure.
-
-## Features
-
-- **Typed command RPC** from consumers to host (`send` -> `CommandResult`).
-- **Real-time pub/sub events** from host to all authenticated consumers.
-- **Single factory API** (`createShardwire`) with host and consumer overloads.
-- **Built-in reliability controls** with reconnect backoff, jitter, and timeouts.
-- **Runtime input validation** for config, names, and JSON-serializable payloads.
-- **Optional schema validation** for command and event payloads.
-- **Optional token-only Discord mode** where shardwire can own client lifecycle.
-- **Dual package output** for ESM and CJS consumers.
-
-## Quick Start
+- Node.js `>=18.18`
+- A Discord bot token (`DISCORD_TOKEN`)
+- At least one shared bridge secret (`SHARDWIRE_SECRET`)
+- Discord gateway intents that match the events you want
 
-Install:
+## Install
 
 ```bash
-pnpm add shardwire
+npm install shardwire
 ```
 
-Define shared message contracts:
-
-```ts
-type Commands = {
-  "ban-user": {
-    request: { userId: string };
-    response: { banned: true; userId: string };
-  };
-};
-
-type Events = {
-  "member-joined": { userId: string; guildId: string };
-};
-```
+## Quick Start
 
-## Host Setup
+### 1) Start the bot bridge process
 
 ```ts
-import { createShardwire } from "shardwire";
-
-type Commands = {
-  "ban-user": {
-    request: { userId: string };
-    response: { banned: true; userId: string };
-  };
-};
+import { createBotBridge } from "shardwire";
 
-type Events = {
-  "member-joined": { userId: string; guildId: string };
-};
-
-const wire = createShardwire<Commands, Events>({
-  client: discordClient,
+const bridge = createBotBridge({
+  token: process.env.DISCORD_TOKEN!,
+  intents: ["Guilds", "GuildMessages", "GuildMessageReactions", "MessageContent", "GuildMembers"],
   server: {
     port: 3001,
     secrets: [process.env.SHARDWIRE_SECRET!],
-    primarySecretId: "s0",
   },
-  name: "bot-host",
-});
-
-wire.onCommand("ban-user", async ({ userId }) => {
-  await guild.members.ban(userId);
-  return { banned: true, userId };
 });
 
-wire.emitEvent("member-joined", { userId: "123", guildId: "456" });
+await bridge.ready();
+console.log("Bot bridge listening on ws://127.0.0.1:3001/shardwire");
 ```
 
-## Consumer Setup
+### 2) Connect from your app process
 
 ```ts
-import { createShardwire } from "shardwire";
-
-type Commands = {
-  "ban-user": {
-    request: { userId: string };
-    response: { banned: true; userId: string };
-  };
-};
+import { connectBotBridge } from "shardwire";
 
-type Events = {
-  "member-joined": { userId: string; guildId: string };
-};
-
-const wire = createShardwire<Commands, Events>({
-  url: "ws://localhost:3001/shardwire",
+const app = connectBotBridge({
+  url: "ws://127.0.0.1:3001/shardwire",
   secret: process.env.SHARDWIRE_SECRET!,
-  secretId: "s0",
-  clientName: "dashboard-api",
+  appName: "dashboard",
 });
 
-const result = await wire.send("ban-user", { userId: "123" });
-
-if (result.ok) {
-  console.log("Command succeeded:", result.data);
-} else {
-  console.error("Command failed:", result.error.code, result.error.message);
-}
-
-wire.on("member-joined", (payload, meta) => {
-  console.log("event", payload, meta.ts);
+app.on("ready", ({ user }) => {
+  console.log("Bot ready as", user.username);
 });
 
-wire.onReconnecting(({ attempt, delayMs }) => {
-  console.warn(`reconnecting attempt ${attempt} in ${delayMs}ms`);
+app.on("messageCreate", ({ message }) => {
+  console.log(message.channelId, message.content);
 });
 
-await wire.ready();
+await app.ready();
 ```
 
-## Token-Only Host (No Existing discord.js Client)
-
-If you do not already manage a `discord.js` client, provide a bot token and shardwire can initialize and own the client lifecycle.
+### 3) Call bot actions from your app
 
 ```ts
-const wire = createShardwire<Commands, Events>({
-  token: process.env.DISCORD_BOT_TOKEN!,
-  server: {
-    port: 3001,
-    secrets: [process.env.SHARDWIRE_SECRET!],
-    primarySecretId: "s0",
-  },
+const result = await app.actions.sendMessage({
+  channelId: "123456789012345678",
+  content: "Hello from app side",
 });
-```
 
-> [!IMPORTANT]
-> Keep `DISCORD_BOT_TOKEN` and `SHARDWIRE_SECRET` in environment variables. Never commit them.
-
-## Reconnect and Timeout Hardening
+if (!result.ok) {
+  console.error(result.error.code, result.error.message);
+}
+```
 
-For unstable networks, tune reconnect behavior and request timeout explicitly:
+### 4) Filter subscriptions when needed
 
 ```ts
-const wire = createShardwire({
-  url: "ws://bot-host:3001/shardwire",
-  secret: process.env.SHARDWIRE_SECRET!,
-  secretId: "s0",
-  requestTimeoutMs: 10_000,
-  reconnect: {
-    enabled: true,
-    initialDelayMs: 500,
-    maxDelayMs: 10_000,
-    jitter: true,
+app.on(
+  "messageCreate",
+  ({ message }) => {
+    console.log("Only this channel:", message.content);
   },
-});
+  { channelId: "123456789012345678" },
+);
 ```
 
-## Schema Validation (Zod)
+## Built-In Events
 
-Use runtime schemas to validate command request/response payloads and emitted event payloads.
+Apps subscribe to events with `app.on(...)`. The bridge forwards only what each app subscribes to.
 
-```ts
-import { z } from "zod";
-import { createShardwire, fromZodSchema } from "shardwire";
+- `ready`
+- `interactionCreate`
+- `messageCreate`
+- `messageUpdate`
+- `messageDelete`
+- `messageReactionAdd`
+- `messageReactionRemove`
+- `guildMemberAdd`
+- `guildMemberRemove`
 
-type Commands = {
-  "ban-user": {
-    request: { userId: string };
-    response: { banned: true; userId: string };
-  };
-};
+Supported filters:
 
-const wire = createShardwire<Commands, {}>({
-  server: {
-    port: 3001,
-    secrets: [process.env.SHARDWIRE_SECRET!],
-    primarySecretId: "s0",
-  },
-  validation: {
-    commands: {
-      "ban-user": {
-        request: fromZodSchema(z.object({ userId: z.string().min(3) })),
-        response: fromZodSchema(z.object({ banned: z.literal(true), userId: z.string() })),
-      },
-    },
-  },
-});
-```
-
-## API Overview
-
-### Host API
-
-- `wire.onCommand(name, handler)` register a command handler.
-- `wire.emitEvent(name, payload)` emit an event to all connected consumers.
-- `wire.broadcast(name, payload)` alias of `emitEvent`.
-- `wire.close()` close the server and active sockets.
+- `guildId`
+- `channelId`
+- `userId`
+- `commandName` (for `interactionCreate`)
 
-### Consumer API
+### Intent Notes
 
-- `wire.send(name, payload, options?)` send command and await typed result.
-- `wire.on(name, handler)` subscribe to events.
-- `wire.off(name, handler)` unsubscribe a specific handler.
-- `wire.ready()` wait for authenticated connection.
-- `wire.onConnected(handler)` subscribe to authenticated connection events.
-- `wire.onDisconnected(handler)` subscribe to disconnect events.
-- `wire.onReconnecting(handler)` subscribe to reconnect scheduling events.
-- `wire.connected()` check authenticated connection state.
-- `wire.connectionId()` get current authenticated connection id (or `null`).
-- `wire.close()` close socket and stop reconnect attempts.
+- `ready` and `interactionCreate`: no specific event intent requirement
+- `messageCreate`, `messageUpdate`, `messageDelete`: `GuildMessages`
+- `messageReactionAdd`, `messageReactionRemove`: `GuildMessageReactions`
+- `guildMemberAdd`, `guildMemberRemove`: `GuildMembers`
 
-## Configuration
+## Built-In Actions
 
-### Host options
+`app.actions.*` includes:
 
-- `server.port` required port.
-- `server.secrets` required shared secret list for authentication.
-- `server.primarySecretId` optional preferred secret id (for example `"s0"`).
-- `server.path` optional WebSocket path (default `/shardwire`).
-- `server.host` optional bind host.
-- `server.heartbeatMs` heartbeat interval.
-- `server.commandTimeoutMs` command execution timeout.
-- `server.maxPayloadBytes` WebSocket payload size limit.
-- `server.corsOrigins` CORS allowlist for browser clients.
-- `client` existing `discord.js` client (optional).
-- `token` Discord bot token (optional, enables token-only mode).
+- `sendMessage`
+- `editMessage`
+- `deleteMessage`
+- `replyToInteraction`
+- `deferInteraction`
+- `followUpInteraction`
+- `banMember`
+- `kickMember`
+- `addMemberRole`
+- `removeMemberRole`
+- `addMessageReaction`
+- `removeOwnMessageReaction`
 
-### Consumer options
+All actions return:
 
-- `url` host endpoint (for example `ws://localhost:3001/shardwire`).
-- `secret` shared secret matching host.
-- `secretId` optional secret id (for example `"s0"`) used during handshake.
-- `clientName` optional identity sent during auth handshake for host-side telemetry.
-- `allowInsecureWs` optional escape hatch to allow `ws://` for non-loopback hosts (defaults to `false`).
-- `requestTimeoutMs` default timeout for `send`.
-- `reconnect` reconnect policy (`enabled`, delays, jitter).
-- `webSocketFactory` optional custom client implementation.
+```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 } };
+```
 
-> [!NOTE]
-> Invalid configuration, empty command/event names, or non-serializable payloads throw synchronously with clear errors.
+## Secret Scopes
 
-## Error Model
+Use a plain string secret for full event/action access:
 
-`send()` resolves to:
+```ts
+server: {
+  port: 3001,
+  secrets: ["full-access-secret"],
+}
+```
 
-- success: `{ ok: true, requestId, ts, data }`
-- failure: `{ ok: false, requestId, ts, error }`
+Use a scoped secret to limit what an app can do:
 
-When `error.code === "VALIDATION_ERROR"`, `error.details` includes:
+```ts
+server: {
+  port: 3001,
+  secrets: [
+    {
+      id: "dashboard",
+      value: process.env.SHARDWIRE_SECRET!,
+      allow: {
+        events: ["ready", "messageCreate"],
+        actions: ["sendMessage", "replyToInteraction"],
+      },
+    },
+  ],
+}
+```
 
-- `name`: command/event name
-- `stage`: `"command.request" | "command.response" | "event.emit"`
-- `issues`: optional normalized issue list (`path`, `message`)
+Inspect negotiated capabilities in the app:
 
-Failure codes:
+```ts
+const capabilities = app.capabilities();
+console.log(capabilities.events, capabilities.actions);
+```
 
-- `UNAUTHORIZED`
-- `TIMEOUT`
-- `DISCONNECTED`
-- `COMMAND_NOT_FOUND`
-- `VALIDATION_ERROR`
-- `INTERNAL_ERROR`
+## Run the Included Examples
 
-## Recipes and Troubleshooting
+In two terminals:
 
-Run local examples:
+```bash
+# terminal 1
+DISCORD_TOKEN=your-token SHARDWIRE_SECRET=dev-secret npm run example:bot
+```
 
 ```bash
-pnpm run example:host
-pnpm run example:consumer
-pnpm run example:host:schema
-pnpm run example:consumer:schema
+# terminal 2
+SHARDWIRE_SECRET=dev-secret npm run example:app
 ```
 
-Practical guides:
+Examples:
 
-- [Integration reference](./.agents/skills/shardwire/references.md)
-- [Add command + event flow](./.agents/skills/shardwire/examples/command-event-change.md)
-- [Reconnect hardening](./.agents/skills/shardwire/examples/reconnect-hardening.md)
-- [Token-only host setup](./.agents/skills/shardwire/examples/token-only-host.md)
-- [Troubleshooting flow](./.agents/skills/shardwire/examples/troubleshooting-flow.md)
+- Bot bridge: `examples/bot-basic.ts`
+- App client: `examples/app-basic.ts`
 
-Common symptoms:
+## Public API
 
-- `UNAUTHORIZED`: verify `secret`, `secretId`, and host `server.secrets` ordering.
-- `DISCONNECTED`: host unavailable or connection dropped before response completed.
-- Frequent `TIMEOUT`: increase `requestTimeoutMs` and inspect host command handler duration.
+```ts
+import { createBotBridge, connectBotBridge } from "shardwire";
+```
 
-## Compatibility
+Main exports include:
 
-- Node.js `>=18.18`
-- TypeScript-first API
-- `discord.js` `^14` as optional peer dependency
-- ESM + CJS package exports
+- `createBotBridge(options)`
+- `connectBotBridge(options)`
+- `BridgeCapabilityError`
+- bot/app option types
+- normalized event payload types (for example `BridgeMessage`, `BridgeInteraction`, `BridgeGuildMember`)
+- action payload and result types
+
+## Security and Transport Notes
+
+- 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.
 
-## Security Notes
+## Contributing
 
-- Use strong, rotated secrets via environment variables.
-- Rotate with overlapping `server.secrets` entries and explicit `secretId` cutovers.
-- Use `wss://` for non-localhost deployments. By default, consumer `ws://` is only accepted for loopback hosts.
-- Set payload and timeout limits appropriate for your workload.
-- Configure `server.corsOrigins` when exposing browser consumers.
+Issues and pull requests are welcome: [github.com/unloopedmido/shardwire](https://github.com/unloopedmido/shardwire).
 
-## Roadmap Constraints (v1)
+## License
 
-- Single npm package, no external infrastructure requirement.
-- Host process embeds WebSocket server.
-- Single-host process model (no cross-host sharding in v1).
-- Shared-secret handshake with in-memory dedupe and pending-request tracking.
+MIT - see [`LICENSE`](./LICENSE).