shardwire 0.0.3 → 0.2.0

package/README.md

@@ -24,6 +24,7 @@
 - [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)
@@ -44,6 +45,7 @@ Running bot logic inside your Discord host process while orchestrating it from e
 - **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.
 
@@ -59,7 +61,10 @@ Define shared message contracts:
 
 ```ts
 type Commands = {
-  "ban-user": { userId: string };
+  "ban-user": {
+    request: { userId: string };
+    response: { banned: true; userId: string };
+  };
 };
 
 type Events = {
@@ -73,7 +78,10 @@ type Events = {
 import { createShardwire } from "shardwire";
 
 type Commands = {
-  "ban-user": { userId: string };
+  "ban-user": {
+    request: { userId: string };
+    response: { banned: true; userId: string };
+  };
 };
 
 type Events = {
@@ -104,7 +112,10 @@ wire.emitEvent("member-joined", { userId: "123", guildId: "456" });
 import { createShardwire } from "shardwire";
 
 type Commands = {
-  "ban-user": { userId: string };
+  "ban-user": {
+    request: { userId: string };
+    response: { banned: true; userId: string };
+  };
 };
 
 type Events = {
@@ -115,6 +126,7 @@ const wire = createShardwire<Commands, Events>({
   url: "ws://localhost:3001/shardwire",
   secret: process.env.SHARDWIRE_SECRET!,
   secretId: "s0",
+  clientName: "dashboard-api",
 });
 
 const result = await wire.send("ban-user", { userId: "123" });
@@ -128,6 +140,12 @@ if (result.ok) {
 wire.on("member-joined", (payload, meta) => {
   console.log("event", payload, meta.ts);
 });
+
+wire.onReconnecting(({ attempt, delayMs }) => {
+  console.warn(`reconnecting attempt ${attempt} in ${delayMs}ms`);
+});
+
+await wire.ready();
 ```
 
 ## Token-Only Host (No Existing discord.js Client)
@@ -167,6 +185,38 @@ const wire = createShardwire({
 });
 ```
 
+## Schema Validation (Zod)
+
+Use runtime schemas to validate command request/response payloads and emitted event payloads.
+
+```ts
+import { z } from "zod";
+import { createShardwire, fromZodSchema } from "shardwire";
+
+type Commands = {
+  "ban-user": {
+    request: { userId: string };
+    response: { banned: true; userId: string };
+  };
+};
+
+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
@@ -181,7 +231,12 @@ const wire = createShardwire({
 - `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.
 
 ## Configuration
@@ -205,6 +260,8 @@ const wire = createShardwire({
 - `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.
@@ -219,14 +276,46 @@ const wire = createShardwire({
 - success: `{ ok: true, requestId, ts, data }`
 - failure: `{ ok: false, requestId, ts, error }`
 
+When `error.code === "VALIDATION_ERROR"`, `error.details` includes:
+
+- `name`: command/event name
+- `stage`: `"command.request" | "command.response" | "event.emit"`
+- `issues`: optional normalized issue list (`path`, `message`)
+
 Failure codes:
 
 - `UNAUTHORIZED`
 - `TIMEOUT`
+- `DISCONNECTED`
 - `COMMAND_NOT_FOUND`
 - `VALIDATION_ERROR`
 - `INTERNAL_ERROR`
 
+## Recipes and Troubleshooting
+
+Run local examples:
+
+```bash
+pnpm run example:host
+pnpm run example:consumer
+pnpm run example:host:schema
+pnpm run example:consumer:schema
+```
+
+Practical guides:
+
+- [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)
+
+Common symptoms:
+
+- `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.
+
 ## Compatibility
 
 - Node.js `>=18.18`
@@ -238,6 +327,7 @@ Failure codes:
 
 - 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.
 

package/dist/index.d.mts

@@ -1,5 +1,20 @@
-type CommandMap = Record<string, unknown>;
+import { ZodType } from 'zod';
+
+interface CommandSchema<Request = unknown, Response = unknown> {
+    request: Request;
+    response: Response;
+}
+type CommandMap = Record<string, unknown | CommandSchema>;
 type EventMap = Record<string, unknown>;
+interface SchemaValidationIssue {
+    path: string;
+    message: string;
+}
+interface RuntimeSchema<T = unknown> {
+    parse: (value: unknown) => T;
+}
+type CommandRequestOf<T> = T extends CommandSchema<infer Request, unknown> ? Request : T;
+type CommandResponseOf<T> = T extends CommandSchema<unknown, infer Response> ? Response : unknown;
 type Unsubscribe = () => void;
 interface ShardwireLogger {
     debug?: (message: string, meta?: Record<string, unknown>) => void;
@@ -35,7 +50,7 @@ interface CommandFailure {
     requestId: string;
     ts: number;
     error: {
-        code: "UNAUTHORIZED" | "TIMEOUT" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
         message: string;
         details?: unknown;
     };
@@ -55,18 +70,36 @@ interface HostOptions<C extends CommandMap, E extends EventMap> {
         maxPayloadBytes?: number;
         corsOrigins?: string[];
     };
+    validation?: {
+        commands?: Partial<{
+            [K in keyof C & string]: {
+                request?: RuntimeSchema<CommandRequestOf<C[K]>>;
+                response?: RuntimeSchema<CommandResponseOf<C[K]>>;
+            };
+        }>;
+        events?: Partial<{
+            [K in keyof E & string]: RuntimeSchema<E[K]>;
+        }>;
+    };
     name?: string;
     logger?: ShardwireLogger;
 }
-interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
+interface ConsumerOptions {
     url: string;
     secret: string;
     secretId?: string;
+    clientName?: string;
+    /**
+     * Allows plain `ws://` connections to non-loopback hosts.
+     *
+     * Keep this `false` unless you explicitly terminate TLS upstream and trust the network path.
+     */
+    allowInsecureWs?: boolean;
     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;
+        on(event: "open" | "message" | "close" | "error", listener: (...args: unknown[]) => void): void;
         once(event: "close", listener: () => void): void;
     };
     reconnect?: {
@@ -80,24 +113,63 @@ interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
 }
 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;
+    onCommand<K extends keyof C & string>(name: K, handler: (payload: CommandRequestOf<C[K]>, ctx: CommandContext) => Promise<CommandResponseOf<C[K]>> | CommandResponseOf<C[K]>): 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?: {
+    send<K extends keyof C & string>(name: K, payload: CommandRequestOf<C[K]>, options?: {
         timeoutMs?: number;
         requestId?: string;
-    }): Promise<CommandResult>;
+    }): Promise<CommandResult<CommandResponseOf<C[K]>>>;
     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;
+    onConnected(handler: (info: {
+        connectionId: string;
+        connectedAt: number;
+    }) => void): Unsubscribe;
+    onDisconnected(handler: (info: {
+        reason: string;
+        at: number;
+        willReconnect: boolean;
+    }) => void): Unsubscribe;
+    onReconnecting(handler: (info: {
+        attempt: number;
+        delayMs: number;
+        at: number;
+    }) => void): Unsubscribe;
+    ready(): Promise<void>;
     connected(): boolean;
+    connectionId(): string | null;
     close(): Promise<void>;
 }
+interface CreateShardwire {
+    <C extends CommandMap = {}, E extends EventMap = {}>(options: HostOptions<C, E>): HostShardwire<C, E>;
+    <C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions): ConsumerShardwire<C, E>;
+}
+
+interface SafeParseResultSuccess<T> {
+    success: true;
+    data: T;
+}
+interface SafeParseResultFailure {
+    success: false;
+    error: {
+        message: string;
+        issues?: SchemaValidationIssue[];
+    };
+}
+type SafeParseResult<T> = SafeParseResultSuccess<T> | SafeParseResultFailure;
+interface SafeParseSchema<T> {
+    safeParse: (value: unknown) => SafeParseResult<T>;
+}
+declare function fromSafeParseSchema<T>(schema: SafeParseSchema<T>): RuntimeSchema<T>;
+
+declare function fromZodSchema<T>(schema: ZodType<T>): RuntimeSchema<T>;
 
 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>;
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions): 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 };
+export { type CommandContext, type CommandFailure, type CommandMap, type CommandRequestOf, type CommandResponseOf, type CommandResult, type CommandSchema, type CommandSuccess, type ConsumerOptions, type ConsumerShardwire, type CreateShardwire, type DiscordClientLike, type EventMap, type EventMeta, type HostOptions, type HostShardwire, type RuntimeSchema, type SchemaValidationIssue, type ShardwireLogger, type Unsubscribe, createShardwire, fromSafeParseSchema, fromZodSchema };

package/dist/index.d.ts

@@ -1,5 +1,20 @@
-type CommandMap = Record<string, unknown>;
+import { ZodType } from 'zod';
+
+interface CommandSchema<Request = unknown, Response = unknown> {
+    request: Request;
+    response: Response;
+}
+type CommandMap = Record<string, unknown | CommandSchema>;
 type EventMap = Record<string, unknown>;
+interface SchemaValidationIssue {
+    path: string;
+    message: string;
+}
+interface RuntimeSchema<T = unknown> {
+    parse: (value: unknown) => T;
+}
+type CommandRequestOf<T> = T extends CommandSchema<infer Request, unknown> ? Request : T;
+type CommandResponseOf<T> = T extends CommandSchema<unknown, infer Response> ? Response : unknown;
 type Unsubscribe = () => void;
 interface ShardwireLogger {
     debug?: (message: string, meta?: Record<string, unknown>) => void;
@@ -35,7 +50,7 @@ interface CommandFailure {
     requestId: string;
     ts: number;
     error: {
-        code: "UNAUTHORIZED" | "TIMEOUT" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
+        code: "UNAUTHORIZED" | "TIMEOUT" | "DISCONNECTED" | "COMMAND_NOT_FOUND" | "VALIDATION_ERROR" | "INTERNAL_ERROR";
         message: string;
         details?: unknown;
     };
@@ -55,18 +70,36 @@ interface HostOptions<C extends CommandMap, E extends EventMap> {
         maxPayloadBytes?: number;
         corsOrigins?: string[];
     };
+    validation?: {
+        commands?: Partial<{
+            [K in keyof C & string]: {
+                request?: RuntimeSchema<CommandRequestOf<C[K]>>;
+                response?: RuntimeSchema<CommandResponseOf<C[K]>>;
+            };
+        }>;
+        events?: Partial<{
+            [K in keyof E & string]: RuntimeSchema<E[K]>;
+        }>;
+    };
     name?: string;
     logger?: ShardwireLogger;
 }
-interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
+interface ConsumerOptions {
     url: string;
     secret: string;
     secretId?: string;
+    clientName?: string;
+    /**
+     * Allows plain `ws://` connections to non-loopback hosts.
+     *
+     * Keep this `false` unless you explicitly terminate TLS upstream and trust the network path.
+     */
+    allowInsecureWs?: boolean;
     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;
+        on(event: "open" | "message" | "close" | "error", listener: (...args: unknown[]) => void): void;
         once(event: "close", listener: () => void): void;
     };
     reconnect?: {
@@ -80,24 +113,63 @@ interface ConsumerOptions<C extends CommandMap, E extends EventMap> {
 }
 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;
+    onCommand<K extends keyof C & string>(name: K, handler: (payload: CommandRequestOf<C[K]>, ctx: CommandContext) => Promise<CommandResponseOf<C[K]>> | CommandResponseOf<C[K]>): 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?: {
+    send<K extends keyof C & string>(name: K, payload: CommandRequestOf<C[K]>, options?: {
         timeoutMs?: number;
         requestId?: string;
-    }): Promise<CommandResult>;
+    }): Promise<CommandResult<CommandResponseOf<C[K]>>>;
     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;
+    onConnected(handler: (info: {
+        connectionId: string;
+        connectedAt: number;
+    }) => void): Unsubscribe;
+    onDisconnected(handler: (info: {
+        reason: string;
+        at: number;
+        willReconnect: boolean;
+    }) => void): Unsubscribe;
+    onReconnecting(handler: (info: {
+        attempt: number;
+        delayMs: number;
+        at: number;
+    }) => void): Unsubscribe;
+    ready(): Promise<void>;
     connected(): boolean;
+    connectionId(): string | null;
     close(): Promise<void>;
 }
+interface CreateShardwire {
+    <C extends CommandMap = {}, E extends EventMap = {}>(options: HostOptions<C, E>): HostShardwire<C, E>;
+    <C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions): ConsumerShardwire<C, E>;
+}
+
+interface SafeParseResultSuccess<T> {
+    success: true;
+    data: T;
+}
+interface SafeParseResultFailure {
+    success: false;
+    error: {
+        message: string;
+        issues?: SchemaValidationIssue[];
+    };
+}
+type SafeParseResult<T> = SafeParseResultSuccess<T> | SafeParseResultFailure;
+interface SafeParseSchema<T> {
+    safeParse: (value: unknown) => SafeParseResult<T>;
+}
+declare function fromSafeParseSchema<T>(schema: SafeParseSchema<T>): RuntimeSchema<T>;
+
+declare function fromZodSchema<T>(schema: ZodType<T>): RuntimeSchema<T>;
 
 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>;
+declare function createShardwire<C extends CommandMap = {}, E extends EventMap = {}>(options: ConsumerOptions): 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 };
+export { type CommandContext, type CommandFailure, type CommandMap, type CommandRequestOf, type CommandResponseOf, type CommandResult, type CommandSchema, type CommandSuccess, type ConsumerOptions, type ConsumerShardwire, type CreateShardwire, type DiscordClientLike, type EventMap, type EventMeta, type HostOptions, type HostShardwire, type RuntimeSchema, type SchemaValidationIssue, type ShardwireLogger, type Unsubscribe, createShardwire, fromSafeParseSchema, fromZodSchema };