shardwire 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# shardwire
+
+Lightweight TypeScript library that turns a Discord bot host into a WebSocket command/event bridge.
+
+## Install
+
+```bash
+pnpm add shardwire
+```
+
+## Host mode
+
+```ts
+import { createShardwire } from "shardwire";
+
+type Commands = {
+  "ban-user": { userId: string };
+};
+
+type Events = {
+  "member-joined": { userId: string; guildId: string };
+};
+
+const wire = createShardwire<Commands, Events>({
+  client: discordClient,
+  server: {
+    port: 3001,
+    secret: process.env.SHARDWIRE_SECRET!,
+  },
+});
+
+wire.onCommand("ban-user", async ({ userId }) => {
+  await guild.members.ban(userId);
+  return { banned: true };
+});
+
+wire.emitEvent("member-joined", { userId: "123", guildId: "456" });
+```
+
+## Consumer mode
+
+```ts
+import { createShardwire } from "shardwire";
+
+type Commands = {
+  "ban-user": { userId: string };
+};
+
+type Events = {
+  "member-joined": { userId: string; guildId: string };
+};
+
+const wire = createShardwire<Commands, Events>({
+  url: "ws://localhost:3001/shardwire",
+  secret: process.env.SHARDWIRE_SECRET!,
+});
+
+const result = await wire.send("ban-user", { userId: "123" });
+
+wire.on("member-joined", (payload) => {
+  console.log(payload.guildId);
+});
+```
+
+## Local examples
+
+Run a local host and consumer in two terminals:
+
+1. Start host:
+   - `pnpm example:host`
+2. Start consumer:
+   - `pnpm example:consumer`
+
+Environment overrides:
+
+- `SHARDWIRE_SECRET` (default: `local-dev-secret`)
+- `SHARDWIRE_PORT` for host (default: `3001`)
+- `SHARDWIRE_URL` for consumer (default: `ws://localhost:3001/shardwire`)
+
+## API quick reference
+
+### Host
+
+- `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()` stop websocket server and close connections.
+
+### Consumer
+
+- `wire.send(name, payload, options?)` send command request and await typed result.
+- `wire.on(name, handler)` subscribe to events.
+- `wire.off(name, handler)` remove specific event handler.
+- `wire.connected()` check authenticated connection state.
+- `wire.close()` close socket and stop reconnect attempts.
+
+### Command result shape
+
+`send()` resolves to:
+
+- success: `{ ok: true, requestId, ts, data }`
+- failure: `{ ok: false, requestId, ts, error: { code, message, details? } }`
+
+Error codes: `AUTH_ERROR`, `TIMEOUT`, `COMMAND_NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`.
+
+## Runtime validation behavior
+
+- Host config requires a valid `server` block (`port`, `secret`, and positive numeric limits).
+- Consumer config requires non-empty `url` and `secret`.
+- Command/event names must be non-empty strings.
+- Command/event payloads must be JSON-serializable.
+
+Invalid input throws synchronously with a descriptive `Error`.
+
+## Compatibility matrix
+
+- Node.js: `>=18.18`
+- TypeScript: `>=5.x` (consumer project)
+- discord.js: `^14` (optional peer dependency)
+- Module support: ESM + CJS exports
+
+## Security and operations notes
+
+- Keep `secret` in environment variables, never commit it.
+- v1 uses static shared secret (restart host to rotate).
+- Use `server.corsOrigins` when browser clients connect.
+- Set `server.maxPayloadBytes` and `requestTimeoutMs` for your workload profile.
+
+## CI and release workflow
+
+- CI runs `pnpm verify` (`test`, `typecheck`, `build`) on pushes and pull requests.
+- Local verification: `pnpm verify`
+- Release guide: see `RELEASING.md`
+- Change history: see `CHANGELOG.md`
+
+## v1 constraints
+
+- Single package, no external services required.
+- Single host process only (no cross-host sharding in v1).
+- Shared-secret auth for host/consumer handshake.
+- In-memory command dedupe and pending request tracking.

package/dist/index.d.mts

@@ -0,0 +1,101 @@
+type CommandMap = Record<string, unknown>;
+type EventMap = Record<string, unknown>;
+type Unsubscribe = () => void;
+interface ShardwireLogger {
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    error?: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface DiscordClientLike {
+    login(token: string): Promise<string>;
+    destroy(): void;
+    once(event: "ready", listener: () => void): void;
+    on(event: "ready", listener: () => void): void;
+    off(event: "ready", listener: () => void): void;
+}
+interface CommandContext {
+    requestId: string;
+    receivedAt: number;
+    connectionId: string;
+    source?: string;
+}
+interface EventMeta {
+    ts: number;
+    source?: string;
+}
+interface CommandSuccess<T = unknown> {
+    ok: true;
+    requestId: string;
+    ts: number;
+    data: T;
+}
+interface CommandFailure {
+    ok: false;
+    requestId: string;
+    ts: number;
+    error: {
+        code: "AUTH_ERROR" | "TIMEOUT" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        details?: unknown;
+    };
+}
+type CommandResult<T = unknown> = CommandSuccess<T> | CommandFailure;
+interface HostOptions<C extends CommandMap, E extends EventMap> {
+    client?: DiscordClientLike;
+    token?: string;
+    server: {
+        port: number;
+        host?: string;
+        secret: string;
+        path?: string;
+        heartbeatMs?: number;
+        commandTimeoutMs?: number;
+        maxPayloadBytes?: number;
+        corsOrigins?: string[];
+    };
+    name?: string;
+    logger?: ShardwireLogger;
+}
+interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
+    url: string;
+    secret: string;
+    webSocketFactory?: (url: string) => {
+        readyState: number;
+        send(data: string): void;
+        close(code?: number, reason?: string): void;
+        on(event: "open" | "message" | "close" | "error", listener: (...args: any[]) => void): void;
+        once(event: "close", listener: () => void): void;
+    };
+    reconnect?: {
+        enabled?: boolean;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: boolean;
+    };
+    requestTimeoutMs?: number;
+    logger?: ShardwireLogger;
+}
+interface HostShardwire<C extends CommandMap, E extends EventMap> {
+    mode: "host";
+    onCommand<K extends keyof C & string>(name: K, handler: (payload: C[K], ctx: CommandContext) => Promise<unknown> | unknown): Unsubscribe;
+    emitEvent<K extends keyof E & string>(name: K, payload: E[K]): void;
+    broadcast<K extends keyof E & string>(name: K, payload: E[K]): void;
+    close(): Promise<void>;
+}
+interface ConsumerShardwire<C extends CommandMap, E extends EventMap> {
+    mode: "consumer";
+    send<K extends keyof C & string>(name: K, payload: C[K], options?: {
+        timeoutMs?: number;
+        requestId?: string;
+    }): Promise<CommandResult>;
+    on<K extends keyof E & string>(name: K, handler: (payload: E[K], meta: EventMeta) => void): Unsubscribe;
+    off<K extends keyof E & string>(name: K, handler: (payload: E[K], meta: EventMeta) => void): void;
+    connected(): boolean;
+    close(): Promise<void>;
+}
+
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: HostOptions<C, E>): HostShardwire<C, E>;
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions<C, E>): ConsumerShardwire<C, E>;
+
+export { type CommandContext, type CommandFailure, type CommandMap, type CommandResult, type CommandSuccess, type ConsumerOptions, type ConsumerShardwire, type DiscordClientLike, type EventMap, type EventMeta, type HostOptions, type HostShardwire, type ShardwireLogger, type Unsubscribe, createShardwire };

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+type CommandMap = Record<string, unknown>;
+type EventMap = Record<string, unknown>;
+type Unsubscribe = () => void;
+interface ShardwireLogger {
+    debug?: (message: string, meta?: Record<string, unknown>) => void;
+    info?: (message: string, meta?: Record<string, unknown>) => void;
+    warn?: (message: string, meta?: Record<string, unknown>) => void;
+    error?: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface DiscordClientLike {
+    login(token: string): Promise<string>;
+    destroy(): void;
+    once(event: "ready", listener: () => void): void;
+    on(event: "ready", listener: () => void): void;
+    off(event: "ready", listener: () => void): void;
+}
+interface CommandContext {
+    requestId: string;
+    receivedAt: number;
+    connectionId: string;
+    source?: string;
+}
+interface EventMeta {
+    ts: number;
+    source?: string;
+}
+interface CommandSuccess<T = unknown> {
+    ok: true;
+    requestId: string;
+    ts: number;
+    data: T;
+}
+interface CommandFailure {
+    ok: false;
+    requestId: string;
+    ts: number;
+    error: {
+        code: "AUTH_ERROR" | "TIMEOUT" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        message: string;
+        details?: unknown;
+    };
+}
+type CommandResult<T = unknown> = CommandSuccess<T> | CommandFailure;
+interface HostOptions<C extends CommandMap, E extends EventMap> {
+    client?: DiscordClientLike;
+    token?: string;
+    server: {
+        port: number;
+        host?: string;
+        secret: string;
+        path?: string;
+        heartbeatMs?: number;
+        commandTimeoutMs?: number;
+        maxPayloadBytes?: number;
+        corsOrigins?: string[];
+    };
+    name?: string;
+    logger?: ShardwireLogger;
+}
+interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
+    url: string;
+    secret: string;
+    webSocketFactory?: (url: string) => {
+        readyState: number;
+        send(data: string): void;
+        close(code?: number, reason?: string): void;
+        on(event: "open" | "message" | "close" | "error", listener: (...args: any[]) => void): void;
+        once(event: "close", listener: () => void): void;
+    };
+    reconnect?: {
+        enabled?: boolean;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: boolean;
+    };
+    requestTimeoutMs?: number;
+    logger?: ShardwireLogger;
+}
+interface HostShardwire<C extends CommandMap, E extends EventMap> {
+    mode: "host";
+    onCommand<K extends keyof C & string>(name: K, handler: (payload: C[K], ctx: CommandContext) => Promise<unknown> | unknown): Unsubscribe;
+    emitEvent<K extends keyof E & string>(name: K, payload: E[K]): void;
+    broadcast<K extends keyof E & string>(name: K, payload: E[K]): void;
+    close(): Promise<void>;
+}
+interface ConsumerShardwire<C extends CommandMap, E extends EventMap> {
+    mode: "consumer";
+    send<K extends keyof C & string>(name: K, payload: C[K], options?: {
+        timeoutMs?: number;
+        requestId?: string;
+    }): Promise<CommandResult>;
+    on<K extends keyof E & string>(name: K, handler: (payload: E[K], meta: EventMeta) => void): Unsubscribe;
+    off<K extends keyof E & string>(name: K, handler: (payload: E[K], meta: EventMeta) => void): void;
+    connected(): boolean;
+    close(): Promise<void>;
+}
+
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: HostOptions<C, E>): HostShardwire<C, E>;
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions<C, E>): ConsumerShardwire<C, E>;
+
+export { type CommandContext, type CommandFailure, type CommandMap, type CommandResult, type CommandSuccess, type ConsumerOptions, type ConsumerShardwire, type DiscordClientLike, type EventMap, type EventMeta, type HostOptions, type HostShardwire, type ShardwireLogger, type Unsubscribe, createShardwire };