@zero-server/cli 0.9.6 → 0.9.8

package/README.md

@@ -1,8 +1,8 @@
 # @zero-server/cli
 
-> Programmatic access to the `zh` / `zs` CLI.
+> Programmatic access to the `zs` CLI.
 
-Programmatic entry points for the bundled CLI (`zh` / `zs`): scaffolding, migrations, seeding, rollback, status. Useful when embedding the CLI inside your own tooling.
+Programmatic entry points for the bundled CLI (`zs`): scaffolding, migrations, seeding, rollback, status. Useful when embedding the CLI inside your own tooling.
 
 ## Install
 

package/index.d.ts

@@ -1,2 +1,2 @@
-// AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
+// AUTO-GENERATED by .tools/generate-package-stubs.js - edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 export * from './types/cli';

package/index.js

@@ -1,4 +1,4 @@
-// AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
+// AUTO-GENERATED by .tools/generate-package-stubs.js - edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
 const lib = require("./lib/cli");
 

package/lib/cli.js

@@ -9,7 +9,7 @@
  *              that exports your database adapter and connection settings.
  *
  * @example
- *   // zero.config.js — required by all CLI commands except make:* and help
+ *   // zero.config.js - required by all CLI commands except make:* and help
  *   module.exports = {
  *       adapter: 'sqlite',
  *       connection: { filename: './app.db' },
@@ -18,13 +18,13 @@
  *   };
  *
  *   // Run via npx (no global install needed):
- *   // npx zh migrate
- *   // npx zh migrate:rollback
- *   // npx zh migrate:status
- *   // npx zh seed
- *   // npx zh make:model User
- *   // npx zh make:migration create_posts
- *   // npx zh make:seeder Users
+ *   // npx zs migrate
+ *   // npx zs migrate:rollback
+ *   // npx zs migrate:status
+ *   // npx zs seed
+ *   // npx zs make:model User
+ *   // npx zs make:migration create_posts
+ *   // npx zs make:seeder Users
  *
  *   // Or programmatically:
  *   const { runCLI } = require('@zero-server/sdk');
@@ -150,6 +150,15 @@ class CLI
      */
     async run()
     {
+        // WebRTC subcommands - delegate the whole `webrtc:*` namespace to the
+        // webrtc CLI module so the top-level dispatcher stays small.
+        if (typeof this.command === 'string' && this.command.startsWith('webrtc:'))
+        {
+            const { runWebRTCCommand } = require('@zero-server/webrtc');
+            await runWebRTCCommand(this.command.slice('webrtc:'.length), this.flags);
+            return;
+        }
+
         const commands = {
             'migrate':           () => this._migrate(),
             'migrate:rollback':  () => this._rollback(),
@@ -206,7 +215,7 @@ class CLI
             throw new Error(
                 'No configuration file found.\n' +
                 'Create a zero.config.js with database and migration settings.\n' +
-                'See "zh help" for examples.'
+                'See "zs help" for examples.'
             );
         }
 
@@ -421,8 +430,8 @@ class CLI
         const status = await migrator.status();
         if (status.executed.includes(lastMigration.name))
         {
-            console.error(red(`Cannot remove "${lastMigration.name}" — it has already been applied.`));
-            console.error(dim('Run "zh migrate:rollback" first, then try again.'));
+            console.error(red(`Cannot remove "${lastMigration.name}" - it has already been applied.`));
+            console.error(dim('Run "zs migrate:rollback" first, then try again.'));
             process.exitCode = 1;
             await db.close();
             return;
@@ -510,7 +519,7 @@ class CLI
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:model <Name>'));
+            console.error(red('Usage: zs make:model <Name>'));
             process.exitCode = 1;
             return;
         }
@@ -566,7 +575,7 @@ module.exports = ${className};
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:migration <name>'));
+            console.error(red('Usage: zs make:migration <name>'));
             process.exitCode = 1;
             return;
         }
@@ -645,7 +654,7 @@ module.exports = {
 
         if (hasNoChanges(changes))
         {
-            console.log(dim('No schema changes detected — nothing to migrate.'));
+            console.log(dim('No schema changes detected - nothing to migrate.'));
             return;
         }
 
@@ -692,7 +701,7 @@ module.exports = {
         const name = this.args.find(a => !a.startsWith('-'));
         if (!name)
         {
-            console.error(red('Usage: zh make:seeder <name>'));
+            console.error(red('Usage: zs make:seeder <name>'));
             process.exitCode = 1;
             return;
         }
@@ -742,9 +751,9 @@ module.exports = ${className};
     _help()
     {
         console.log(`
-${bold('zh CLI')} — zero-server ORM tooling
+${bold('zs CLI')} - zero-server ORM tooling
 
-${bold('Usage:')}  npx zh <command> [options]
+${bold('Usage:')}  npx zs <command> [options]
 
 ${bold('Commands:')}
 
@@ -761,6 +770,12 @@ ${bold('Commands:')}
   ${cyan('make:migration')} <n>   Auto-generate migration from model changes
   ${cyan('make:seeder')} <name>   Scaffold a new seeder file
 
+  ${cyan('webrtc:stun')}          Run a STUN binding probe, print public addr
+  ${cyan('webrtc:turn-creds')}    Issue ephemeral TURN credentials
+  ${cyan('webrtc:join-token')}    Sign a signaling join token
+  ${cyan('webrtc:verify-token')}  Verify and decode a join token
+  ${cyan('webrtc:help')}          Show webrtc subcommand help
+
   ${cyan('help')}                 Show this help message
   ${cyan('version')}              Show version
 
@@ -788,19 +803,19 @@ ${bold('Config file:')} ${dim('zero.config.js (or .zero-server.js / legacy .zero
 
 ${bold('Auto-generated migrations:')}
 
-  ${dim('$')} npx zh make:migration create_users  ${dim('# detects new User model → generates CREATE TABLE')}
-  ${dim('$')} npx zh make:migration add_email     ${dim('# detects new email column → generates ADD COLUMN')}
-  ${dim('$')} npx zh make:migration --empty init   ${dim('# blank migration (manual mode)')}
-  ${dim('$')} npx zh migrate                      ${dim('# apply pending migrations')}
-  ${dim('$')} npx zh migrate:remove               ${dim('# undo last make:migration')}
+  ${dim('$')} npx zs make:migration create_users  ${dim('# detects new User model → generates CREATE TABLE')}
+  ${dim('$')} npx zs make:migration add_email     ${dim('# detects new email column → generates ADD COLUMN')}
+  ${dim('$')} npx zs make:migration --empty init   ${dim('# blank migration (manual mode)')}
+  ${dim('$')} npx zs migrate                      ${dim('# apply pending migrations')}
+  ${dim('$')} npx zs migrate:remove               ${dim('# undo last make:migration')}
 
 ${bold('Examples:')}
 
-  ${dim('$')} npx zh make:model User             ${dim('# creates models/User.js')}
-  ${dim('$')} npx zh make:migration create_users  ${dim('# auto-generates from models')}
-  ${dim('$')} npx zh migrate                     ${dim('# runs all pending migrations')}
-  ${dim('$')} npx zh migrate --config=db.config.js
-  ${dim('$')} npx zh seed                        ${dim('# runs all seeders')}
+  ${dim('$')} npx zs make:model User             ${dim('# creates models/User.js')}
+  ${dim('$')} npx zs make:migration create_users  ${dim('# auto-generates from models')}
+  ${dim('$')} npx zs migrate                     ${dim('# runs all pending migrations')}
+  ${dim('$')} npx zs migrate --config=db.config.js
+  ${dim('$')} npx zs seed                        ${dim('# runs all seeders')}
 `);
     }
 
@@ -810,7 +825,7 @@ ${bold('Examples:')}
     _version()
     {
         const pkg = require('../package.json');
-        console.log(`zh v${pkg.version} (zero-server)`);
+        console.log(`zs v${pkg.version} (zero-server)`);
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zero-server/cli",
-  "version": "0.9.6",
-  "description": "Programmatic access to the `zh` / `zs` CLI.",
+  "version": "0.9.8",
+  "description": "Programmatic access to the `zs` CLI.",
   "keywords": [
     "zero-server",
     "zero-server",
@@ -45,10 +45,11 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/orm": "0.9.6"
+    "@zero-server/orm": "0.9.8",
+    "@zero-server/webrtc": "0.9.8"
   },
   "peerDependencies": {
-    "@zero-server/sdk": ">=0.9.6"
+    "@zero-server/sdk": ">=0.9.8"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {

package/types/body.d.ts

@@ -1,14 +1,82 @@
-// Re-exports for @zero-server/body — body parser types
-export {
-    BodyParserOptions,
-    JsonParserOptions,
-    UrlencodedParserOptions,
-    TextParserOptions,
-    MultipartOptions,
-    MultipartFile,
-    json,
-    urlencoded,
-    text,
-    raw,
-    multipart,
-} from './middleware';
+// TypeScript declarations for the bundled body parsers
+// (`json`, `urlencoded`, `text`, `raw`, `multipart`).
+//
+// These live in `lib/body/*` at runtime and are surfaced both via the
+// top-level SDK and the standalone `@zero-server/body` scope.  They are
+// declared here (not in `./middleware`) so the body-parser package has
+// a self-contained declaration file.
+
+import { MiddlewareFunction } from './middleware';
+import { Request } from './request';
+import { Response } from './response';
+
+export interface BodyParserOptions {
+    /** Max body size (e.g. '10kb', '1mb'). Default: '1mb'. */
+    limit?: string | number;
+    /** Content-Type(s) to match. Accepts a string, an array of strings, or a predicate function. */
+    type?: string | string[] | ((ct: string) => boolean);
+    /** Reject non-HTTPS requests with 403. */
+    requireSecure?: boolean;
+    /**
+     * Verification callback invoked with the raw buffer before parsing.
+     * Throw an error to reject the request with 403.
+     * Useful for webhook signature verification (e.g. Stripe, GitHub).
+     */
+    verify?: (req: Request, res: Response, buf: Buffer, encoding: string) => void;
+    /** Decompress gzip/deflate/br request bodies. Default: true. When false, compressed bodies return 415. */
+    inflate?: boolean;
+}
+
+export interface JsonParserOptions extends BodyParserOptions {
+    /** JSON.parse reviver function. */
+    reviver?: (key: string, value: any) => any;
+    /** Reject non-object/array roots. Default: true. */
+    strict?: boolean;
+}
+
+export interface UrlencodedParserOptions extends BodyParserOptions {
+    /** Enable nested bracket parsing. Default: false. */
+    extended?: boolean;
+    /** Max number of parameters. Default: 1000. Prevents parameter flooding DoS. */
+    parameterLimit?: number;
+    /** Max nesting depth for bracket syntax. Default: 32. Prevents deep-nesting DoS. */
+    depth?: number;
+}
+
+export interface TextParserOptions extends BodyParserOptions {
+    /** Fallback character encoding when Content-Type has no charset. Default: 'utf8'. */
+    encoding?: BufferEncoding;
+}
+
+export interface MultipartOptions {
+    /** Upload directory (default: OS temp). */
+    dir?: string;
+    /** Maximum size per file in bytes. */
+    maxFileSize?: number;
+    /** Reject non-HTTPS requests with 403. */
+    requireSecure?: boolean;
+    /** Maximum number of non-file fields. Default: 1000. */
+    maxFields?: number;
+    /** Maximum number of uploaded files. Default: 10. */
+    maxFiles?: number;
+    /** Maximum size of a single field value in bytes. Default: 1 MB. */
+    maxFieldSize?: number;
+    /** Whitelist of allowed MIME types for uploaded files (e.g. ['image/png', 'image/jpeg']). */
+    allowedMimeTypes?: string[];
+    /** Maximum combined size of all uploaded files in bytes. */
+    maxTotalSize?: number;
+}
+
+export interface MultipartFile {
+    originalFilename: string;
+    storedName: string;
+    path: string;
+    contentType: string;
+    size: number;
+}
+
+export function json(options?: JsonParserOptions): MiddlewareFunction;
+export function urlencoded(options?: UrlencodedParserOptions): MiddlewareFunction;
+export function text(options?: TextParserOptions): MiddlewareFunction;
+export function raw(options?: BodyParserOptions): MiddlewareFunction;
+export function multipart(options?: MultipartOptions): MiddlewareFunction;

package/types/cli.d.ts

@@ -1,2 +1,40 @@
-// Re-exports for @zero-server/cli — CLI runner types
-export { CLI, runCLI } from './orm';
+// TypeScript declarations for the bundled CLI runner (`zs` / `zh`).
+//
+// The CLI lives in `lib/cli.js` and is published both as the `zs` /
+// `zh` bin scripts and as a programmatic API on the SDK.  It dispatches
+// ORM subcommands (`migrate`, `seed`, `make:*`) to `@zero-server/orm`
+// and `webrtc:*` subcommands to `@zero-server/webrtc`, but the runner
+// itself is scope-neutral - hence its own declaration file.
+
+/**
+ * CLI runner for the bundled `zs` command.
+ *
+ * Parses `process.argv`-style input, resolves a config file
+ * (`zero.config.js` / `.zero-server.js` / `.zero-http.js`), and
+ * dispatches to the matching subcommand handler.
+ */
+export class CLI {
+    constructor(argv?: string[]);
+
+    /** The first positional argument (subcommand name). Defaults to `"help"`. */
+    readonly command: string;
+
+    /** Remaining positional arguments after the subcommand. */
+    readonly args: string[];
+
+    /** Parsed `--flag=value` and `-f value` pairs. */
+    readonly flags: Map<string, string>;
+
+    /** Execute the parsed command.  Sets `process.exitCode` on failure. */
+    run(): Promise<void>;
+}
+
+/**
+ * One-shot helper: `new CLI(argv).run()`.
+ *
+ * @example
+ *   const { runCLI } = require('@zero-server/sdk');
+ *   await runCLI(['migrate']);
+ *   await runCLI(['make:model', 'User', '--dir=src/models']);
+ */
+export function runCLI(argv?: string[]): Promise<void>;

package/types/index.d.ts

@@ -11,6 +11,18 @@ export { RouterInstance, RouteChain, RouteEntry, RouteInfo, RouteOptions, RouteH
 export { Request, RangeResult } from './request';
 export { Response, SendFileOptions, CookieOptions, PushOptions } from './response';
 export { SSEOptions, SSEStream } from './sse';
+export {
+    createWebRTC, SignalingHub, Room as WebRTCRoom, Peer as WebRTCPeer,
+    parseSdp, stringifySdp, parseCandidate, stringifyCandidate,
+    stunBinding, encodeBindingRequest, decodeMessage,
+    encodeXorMappedAddress, decodeXorMappedAddress,
+    STUN_MAGIC_COOKIE, STUN_METHOD, STUN_CLASS, STUN_ATTR,
+    issueTurnCredentials, TurnServer, SfuAdapter,
+    signJoinToken, verifyJoinToken,
+    WebRTCOptions, RoomOptions as WebRTCRoomOptions, PeerInfo, SignalingMessage,
+    IceServerConfig, TurnCredentials, IssueTurnCredentialsOptions, ClusterAdapter as WebRTCClusterAdapter,
+    WebRTCError, SignalingError, IceError, TurnError, SdpError,
+} from './webrtc';
 export { LifecycleManager, LifecycleState, LIFECYCLE_STATE } from './lifecycle';
 export { ClusterManager, ClusterOptions, cluster } from './cluster';
 export {
@@ -85,8 +97,8 @@ export {
     StoredProcedure, StoredProcedureOptions, ProcedureParam,
     StoredFunction, StoredFunctionOptions,
     TriggerManager, TriggerDefinition,
-    CLI, runCLI,
 } from './orm';
+export { CLI, runCLI } from './cli';
 // Re-export validate from orm as schemaValidate to avoid collision with middleware validate
 export { validate as schemaValidate } from './orm';
 export {
@@ -149,7 +161,8 @@ import { Database, Model, Query } from './orm';
 import { TYPES, validateFKAction, validateCheck } from './orm';
 import { Migrator, QueryCache, Seeder, SeederRunner, Factory, Fake, defineMigration } from './orm';
 import { QueryProfiler, ReplicaManager } from './orm';
-import { TenantManager, AuditLog, PluginManager, StoredProcedure, StoredFunction, TriggerManager, CLI, runCLI } from './orm';
+import { TenantManager, AuditLog, PluginManager, StoredProcedure, StoredFunction, TriggerManager } from './orm';
+import { CLI, runCLI } from './cli';
 import { LifecycleManager, LIFECYCLE_STATE } from './lifecycle';
 import { ClusterManager, cluster as clusterize } from './cluster';
 import {
@@ -294,10 +307,10 @@ declare const zeroServer: {
     LIFECYCLE_STATE: typeof LIFECYCLE_STATE;
     ClusterManager: typeof ClusterManager;
     cluster: typeof clusterize;
-    // Observability — Structured Logging
+    // Observability - Structured Logging
     Logger: typeof Logger;
     structuredLogger: typeof structuredLogger;
-    // Observability — Metrics
+    // Observability - Metrics
     Counter: typeof Counter;
     Gauge: typeof Gauge;
     Histogram: typeof Histogram;
@@ -306,14 +319,14 @@ declare const zeroServer: {
     createDefaultMetrics: typeof createDefaultMetrics;
     metricsMiddleware: typeof metricsMiddleware;
     metricsEndpoint: typeof metricsEndpointHandler;
-    // Observability — Tracing
+    // Observability - Tracing
     Span: typeof Span;
     Tracer: typeof Tracer;
     parseTraceparent: typeof parseTraceparent;
     formatTraceparent: typeof formatTraceparent;
     tracingMiddleware: typeof tracingMiddleware;
     instrumentFetch: typeof instrumentFetch;
-    // Observability — Health Checks
+    // Observability - Health Checks
     healthCheck: typeof healthCheck;
     createHealthHandlers: typeof createHealthHandlers;
     memoryCheck: typeof memoryCheck;

package/types/middleware.d.ts

@@ -21,77 +21,23 @@ export interface CorsOptions {
 export function cors(options?: CorsOptions): MiddlewareFunction;
 
 // --- Body Parsers ------------------------------------------------
-
-export interface BodyParserOptions {
-    /** Max body size (e.g. '10kb', '1mb'). Default: '1mb'. */
-    limit?: string | number;
-    /** Content-Type(s) to match. Accepts a string, an array of strings, or a predicate function. */
-    type?: string | string[] | ((ct: string) => boolean);
-    /** Reject non-HTTPS requests with 403. */
-    requireSecure?: boolean;
-    /**
-     * Verification callback invoked with the raw buffer before parsing.
-     * Throw an error to reject the request with 403.
-     * Useful for webhook signature verification (e.g. Stripe, GitHub).
-     */
-    verify?: (req: import('./request').Request, res: import('./response').Response, buf: Buffer, encoding: string) => void;
-    /** Decompress gzip/deflate/br request bodies. Default: true. When false, compressed bodies return 415. */
-    inflate?: boolean;
-}
-
-export interface JsonParserOptions extends BodyParserOptions {
-    /** JSON.parse reviver function. */
-    reviver?: (key: string, value: any) => any;
-    /** Reject non-object/array roots. Default: true. */
-    strict?: boolean;
-}
-
-export interface UrlencodedParserOptions extends BodyParserOptions {
-    /** Enable nested bracket parsing. Default: false. */
-    extended?: boolean;
-    /** Max number of parameters. Default: 1000. Prevents parameter flooding DoS. */
-    parameterLimit?: number;
-    /** Max nesting depth for bracket syntax. Default: 32. Prevents deep-nesting DoS. */
-    depth?: number;
-}
-
-export interface TextParserOptions extends BodyParserOptions {
-    /** Fallback character encoding when Content-Type has no charset. Default: 'utf8'. */
-    encoding?: BufferEncoding;
-}
-
-export interface MultipartOptions {
-    /** Upload directory (default: OS temp). */
-    dir?: string;
-    /** Maximum size per file in bytes. */
-    maxFileSize?: number;
-    /** Reject non-HTTPS requests with 403. */
-    requireSecure?: boolean;
-    /** Maximum number of non-file fields. Default: 1000. */
-    maxFields?: number;
-    /** Maximum number of uploaded files. Default: 10. */
-    maxFiles?: number;
-    /** Maximum size of a single field value in bytes. Default: 1 MB. */
-    maxFieldSize?: number;
-    /** Whitelist of allowed MIME types for uploaded files (e.g. ['image/png', 'image/jpeg']). */
-    allowedMimeTypes?: string[];
-    /** Maximum combined size of all uploaded files in bytes. */
-    maxTotalSize?: number;
-}
-
-export interface MultipartFile {
-    originalFilename: string;
-    storedName: string;
-    path: string;
-    contentType: string;
-    size: number;
-}
-
-export function json(options?: JsonParserOptions): MiddlewareFunction;
-export function urlencoded(options?: UrlencodedParserOptions): MiddlewareFunction;
-export function text(options?: TextParserOptions): MiddlewareFunction;
-export function raw(options?: BodyParserOptions): MiddlewareFunction;
-export function multipart(options?: MultipartOptions): MiddlewareFunction;
+// Declarations live in `./body` so the standalone `@zero-server/body`
+// package has its own self-contained type file.  Re-exported here so
+// callers using the aggregate middleware surface continue to work.
+
+export {
+    BodyParserOptions,
+    JsonParserOptions,
+    UrlencodedParserOptions,
+    TextParserOptions,
+    MultipartOptions,
+    MultipartFile,
+    json,
+    urlencoded,
+    text,
+    raw,
+    multipart,
+} from './body';
 
 // --- Rate Limiting -----------------------------------------------
 
@@ -136,7 +82,7 @@ export interface CompressOptions {
     level?: number;
     /** Force specific encoding(s). */
     encoding?: string | string[];
-    /** Filter function — return false to skip compression. */
+    /** Filter function - return false to skip compression. */
     filter?: (req: Request, res: Response) => boolean;
 }
 

package/types/orm.d.ts

@@ -29,7 +29,7 @@ export interface SchemaColumnDef {
     enum?: string[];
     /** Allowed values (set type). */
     values?: string[];
-    /** Mass-assignment protection — exclude from bulk writes. */
+    /** Mass-assignment protection - exclude from bulk writes. */
     guarded?: boolean;
     /** Precision for decimal types. */
     precision?: number;
@@ -229,7 +229,7 @@ export class Query {
     take(n: number): Query;
     /** Alias for offset (LINQ naming). */
     skip(n: number): Query;
-    /** Alias for exec — explicitly convert to array. */
+    /** Alias for exec - explicitly convert to array. */
     toArray(): Promise<Model[]>;
     /** Shorthand for orderBy(field, 'desc'). */
     orderByDesc(field: string): Query;
@@ -260,7 +260,7 @@ export class Query {
     /** Inject a raw WHERE clause for SQL adapters (ignored by memory/mongo). */
     whereRaw(sql: string, ...params: any[]): Query;
 
-    /** Thenable support — `await query`. */
+    /** Thenable support - `await query`. */
     then<TResult1 = Model[], TResult2 = never>(
         onfulfilled?: ((value: Model[]) => TResult1 | PromiseLike<TResult1>) | null,
         onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
@@ -1875,13 +1875,4 @@ export class TriggerManager {
     get(name: string): TriggerDefinition | undefined;
 }
 
-// --- CLI (Phase 4) --------------------------------------------------
-
-export class CLI {
-    constructor(argv?: string[]);
-    /** Run the CLI command. */
-    run(): Promise<void>;
-}
-
-/** Create and run the CLI. */
-export function runCLI(argv?: string[]): Promise<void>;
+// CLI declarations live in `./cli` (re-exported from `./index`).

package/types/request.d.ts

@@ -31,7 +31,7 @@ export interface Request {
     readonly ips: string[];
     /** `true` when the connection is over TLS (trust-proxy-aware). */
     readonly secure: boolean;
-    /** Protocol string — `'https'` or `'http'` (trust-proxy-aware). */
+    /** Protocol string - `'https'` or `'http'` (trust-proxy-aware). */
     readonly protocol: 'http' | 'https';
     /** HTTP version string (e.g. '1.1', '2.0'). */
     httpVersion: string;
@@ -49,7 +49,7 @@ export interface Request {
     id?: string;
     /** Whether the request timed out (populated by timeout middleware). */
     timedOut?: boolean;
-    /** The original URL as received — never rewritten by middleware. */
+    /** The original URL as received - never rewritten by middleware. */
     originalUrl: string;
     /** The URL path on which the current router was mounted. */
     baseUrl: string;
@@ -83,7 +83,7 @@ export interface Request {
     subdomains(offset?: number): string[];
 
     /**
-     * Content negotiation — check which types the client accepts.
+     * Content negotiation - check which types the client accepts.
      */
     accepts(...types: string[]): string | false;
 

package/types/webrtc.d.ts

@@ -0,0 +1,501 @@
+/**
+ * TypeScript surface for @zero-server/webrtc.
+ *
+ * Mirrors the runtime surface exported from `lib/webrtc/index.js` and
+ * re-exported from the top-level SDK in `index.js`.  Every entry listed
+ * in `.tools/scope-manifest.js` under the `webrtc` scope MUST have a
+ * matching declaration here - this is enforced by
+ * `test/packages/webrtc-types.test.js`.
+ */
+
+import type { EventEmitter } from 'node:events';
+import type { KeyObject } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+//  Shared option / config types
+// ---------------------------------------------------------------------------
+
+export interface IceServerConfig {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+
+export interface TurnCredentials {
+    urls: string[];
+    username: string;
+    credential: string;
+    ttl: number;
+}
+
+export interface IssueTurnCredentialsOptions {
+    secret: string;
+    userId: string;
+    ttl?: string | number;
+    servers: string[];
+    realm?: string;
+}
+
+export interface SignalingHubOptions {
+    maxSdpSize?: number;
+    maxCandidatesPerOffer?: number;
+    peerMessageRate?: number;
+    maxProtocolErrors?: number;
+    ipAttachRate?: number;
+    originAllowlist?: string[];
+    joinTokenSecret?: string | Buffer;
+    autoCreateRooms?: boolean;
+}
+
+export interface WebRTCOptions extends SignalingHubOptions {
+    path?: string;
+    iceServers?: IceServerConfig[] | 'auto';
+}
+
+export interface PeerAttachInfo {
+    user?: unknown;
+    ip?: string;
+    origin?: string;
+    [extra: string]: unknown;
+}
+
+export interface PeerTransport {
+    send(data: string): void;
+    on(event: 'message' | 'close', cb: (...args: unknown[]) => void): void;
+    close(code?: number, reason?: string): void;
+}
+
+// ---------------------------------------------------------------------------
+//  SDP / ICE helpers
+// ---------------------------------------------------------------------------
+
+export interface ParsedSdpMedia {
+    type: string;
+    port: number;
+    proto: string;
+    formats: string[];
+    iceUfrag?: string;
+    icePwd?: string;
+    fingerprint?: { algorithm: string; hash: string };
+    candidates?: ParsedIceCandidate[];
+    [key: string]: unknown;
+}
+
+export interface ParsedSdp {
+    version: number;
+    origin: Record<string, unknown>;
+    sessionName: string;
+    media: ParsedSdpMedia[];
+    [key: string]: unknown;
+}
+
+export interface ParsedIceCandidate {
+    foundation: string;
+    component: number;
+    transport: string;
+    priority: number;
+    address: string;
+    port: number;
+    type: string;
+    relatedAddress?: string;
+    relatedPort?: number;
+    tcpType?: string;
+    [key: string]: unknown;
+}
+
+export declare function parseSdp(sdp: string, opts?: { maxBytes?: number }): ParsedSdp;
+export declare function stringifySdp(parsed: ParsedSdp): string;
+
+export declare function parseCandidate(line: string): ParsedIceCandidate;
+export declare function stringifyCandidate(parsed: ParsedIceCandidate): string;
+export declare function filterCandidates(
+    candidates: ParsedIceCandidate[],
+    opts?: { allowPrivate?: boolean; allowLoopback?: boolean; allowLinkLocal?: boolean; allowMdns?: boolean }
+): ParsedIceCandidate[];
+
+export declare function isPrivateIp(addr: string): boolean;
+export declare function isLoopbackIp(addr: string): boolean;
+export declare function isLinkLocalIp(addr: string): boolean;
+export declare function isMdnsHostname(addr: string): boolean;
+
+export declare const CANDIDATE_TYPES: Readonly<{ HOST: string; SRFLX: string; PRFLX: string; RELAY: string }>;
+export declare const TCP_TYPES: Readonly<{ ACTIVE: string; PASSIVE: string; SO: string }>;
+
+// ---------------------------------------------------------------------------
+//  STUN / TURN
+// ---------------------------------------------------------------------------
+
+export declare function stunBinding(opts: {
+    host: string;
+    port?: number;
+    timeoutMs?: number;
+    retries?: number;
+    socketType?: 'udp4' | 'udp6';
+}): Promise<{ family: 4 | 6; address: string; port: number }>;
+
+export declare function encodeBindingRequest(transactionId?: Buffer): { buffer: Buffer; transactionId: Buffer };
+export declare function decodeMessage(buf: Buffer): {
+    method: number;
+    class: number;
+    transactionId: Buffer;
+    attributes: Array<{ type: number; value: Buffer }>;
+};
+export declare function encodeXorMappedAddress(address: string, port: number, transactionId: Buffer): Buffer;
+export declare function decodeXorMappedAddress(value: Buffer, transactionId: Buffer): { family: 4 | 6; address: string; port: number };
+
+export declare const STUN_MAGIC_COOKIE: number;
+export declare const STUN_METHOD: Readonly<{ BINDING: number }>;
+export declare const STUN_CLASS: Readonly<{ REQUEST: number; INDICATION: number; SUCCESS: number; ERROR: number }>;
+export declare const STUN_ATTR: Readonly<{ MAPPED_ADDRESS: number; XOR_MAPPED_ADDRESS: number; ERROR_CODE: number; SOFTWARE: number }>;
+
+export declare function issueTurnCredentials(opts: IssueTurnCredentialsOptions): TurnCredentials;
+
+export declare class TurnServer {
+    constructor(opts: {
+        secret: string;
+        realm?: string;
+        listeners: Array<{ proto: 'udp' | 'tcp' | 'tls'; port: number; host?: string; tls?: { cert: Buffer; key: Buffer } }>;
+        quotas?: { maxAllocationsPerUser?: number; maxBytesPerMinute?: number };
+        defaultLifetime?: number;
+        maxLifetime?: number;
+        relayHost?: string;
+    });
+    readonly realm: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    address(): { address: string; port: number } | null;
+    on(event: 'allocation', listener: (ev: { userId: string; relay: { address: string; port: number }; client: { address: string; port: number } }) => void): this;
+    on(event: 'deallocation', listener: (ev: { userId: string; client: { address: string; port: number }; reason?: string }) => void): this;
+    on(event: 'error', listener: (err: Error) => void): this;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+}
+
+// ---------------------------------------------------------------------------
+//  Signaling core
+// ---------------------------------------------------------------------------
+
+export type PeerState = 'stable' | 'have-local-offer' | 'have-remote-offer';
+
+export declare const PEER_STATE: Readonly<{
+    STABLE: 'stable';
+    HAVE_LOCAL_OFFER: 'have-local-offer';
+    HAVE_REMOTE_OFFER: 'have-remote-offer';
+}>;
+
+export declare class Peer {
+    readonly id: string;
+    readonly user: unknown;
+    readonly ip: string | null;
+    readonly transport: PeerTransport;
+    state: PeerState;
+    room: Room | null;
+    errors: number;
+    readonly connectedAt: number;
+    closed: boolean;
+    e2ee?: E2eeChannel;
+    constructor(transport: PeerTransport, info?: PeerAttachInfo);
+    send(type: string, payload?: object): void;
+    sendError(code: string, message: string): void;
+    close(code?: number, reason?: string): void;
+}
+
+export declare class Room {
+    readonly name: string;
+    readonly hub: SignalingHub | null;
+    isOpen: boolean;
+    constructor(name: string, opts?: { hub?: SignalingHub });
+    open(): this;
+    require(fn: (peer: Peer) => boolean | Promise<boolean>): this;
+    canPublish(fn: (peer: Peer) => boolean): this;
+    canSubscribe(fn: (peer: Peer) => boolean): this;
+    readonly size: number;
+    peers(): Peer[];
+    canJoin(peer: Peer): boolean | Promise<boolean>;
+    broadcast(type: string, payload?: object, exceptPeerId?: string): void;
+    close(reason?: string): void;
+}
+
+export interface SignalingHubEvents {
+    join:            (ev: { peer: Peer; room: Room }) => void;
+    leave:           (ev: { peer: Peer; room: Room }) => void;
+    offer:           (ev: { peer: Peer; target: Peer | null; room: Room; sdp: string }) => void;
+    answer:          (ev: { peer: Peer; target: Peer | null; room: Room; sdp: string }) => void;
+    signal:          (ev: { peer: Peer; type: string }) => void;
+    joinFailed:      (ev: { peer: Peer; reason: string; room?: string }) => void;
+    publishFailed:   (ev: { peer: Peer; reason: string; room: string }) => void;
+    subscribeFailed: (ev: { peer: Peer; reason: string; room: string }) => void;
+    wireError:       (ev: { peer: Peer; code: string }) => void;
+    e2eeKey:         (ev: { peer: Peer; room: Room; epoch: number; key: string }) => void;
+    clusterError:    (err: Error) => void;
+}
+
+export declare class SignalingHub extends EventEmitter {
+    constructor(opts?: SignalingHubOptions);
+    readonly size: number;
+    room(name: string): Room;
+    rooms(): Room[];
+    attach(transport: PeerTransport, info?: PeerAttachInfo): Peer;
+    close(): void;
+    on<E extends keyof SignalingHubEvents>(event: E, listener: SignalingHubEvents[E]): this;
+    on(event: string, listener: (...args: unknown[]) => void): this;
+    off<E extends keyof SignalingHubEvents>(event: E, listener: SignalingHubEvents[E]): this;
+    off(event: string, listener: (...args: unknown[]) => void): this;
+    emit<E extends keyof SignalingHubEvents>(event: E, ...args: Parameters<SignalingHubEvents[E]>): boolean;
+    emit(event: string, ...args: unknown[]): boolean;
+}
+
+export declare function createWebRTC(app: unknown, opts?: WebRTCOptions): SignalingHub;
+
+// ---------------------------------------------------------------------------
+//  Join tokens
+// ---------------------------------------------------------------------------
+
+export interface SignJoinTokenOptions {
+    secret: string | Buffer;
+    user: string | { id?: string; userId?: string; sub?: string; [k: string]: unknown };
+    room: string;
+    ttl?: number;
+    claims?: Record<string, unknown>;
+    algorithm?: string;
+    audience?: string;
+}
+
+export interface VerifyJoinTokenOptions {
+    secret: string | Buffer;
+    room?: string;
+    audience?: string | string[];
+    algorithms?: string | string[];
+    clockTolerance?: number;
+}
+
+export declare function signJoinToken(opts: SignJoinTokenOptions): string;
+
+export declare function verifyJoinToken(
+    token: string,
+    opts: VerifyJoinTokenOptions
+): { room: string; user: unknown; sub?: string; aud?: string; [k: string]: unknown };
+
+// ---------------------------------------------------------------------------
+//  Observability
+// ---------------------------------------------------------------------------
+
+export interface ObservabilityBindOptions {
+    metrics?: unknown;
+    tracer?: unknown;
+    prefix?: string;
+}
+
+export declare function bindObservability(
+    hub: SignalingHub,
+    opts?: ObservabilityBindOptions
+): () => void;
+
+// ---------------------------------------------------------------------------
+//  E2EE key relay
+// ---------------------------------------------------------------------------
+
+export interface E2eeKeyEvent {
+    from: string;
+    epoch: number;
+    key: Buffer;
+}
+
+export declare class E2eeChannel {
+    readonly peer: Peer;
+    readonly hub: SignalingHub;
+    epoch: number;
+    constructor(peer: Peer, hub: SignalingHub);
+    publish(epoch: number | null, key: Buffer | Uint8Array | string): number;
+    subscribe(fn: (ev: E2eeKeyEvent) => void): () => void;
+}
+
+export declare function attachE2ee(peer: Peer, hub: SignalingHub): E2eeChannel;
+export declare function generateE2eeKeyPair(): { publicKey: KeyObject; privateKey: KeyObject };
+export declare function sealKey(plaintext: Buffer | Uint8Array, recipientPubKey: KeyObject | Buffer): Buffer;
+export declare function openSealedKey(sealed: Buffer | Uint8Array, recipientPrivKey: KeyObject | Buffer): Buffer;
+
+// ---------------------------------------------------------------------------
+//  Cluster adapter
+// ---------------------------------------------------------------------------
+
+export interface ClusterAdapter {
+    publish(channel: string, message: unknown): void | Promise<void>;
+    subscribe(channel: string, handler: (message: unknown) => void): (() => void) | void;
+}
+
+export interface UseClusterOptions {
+    nodeId?: string;
+}
+
+export declare class ClusterCoordinator {
+    readonly hub: SignalingHub;
+    readonly adapter: ClusterAdapter;
+    readonly nodeId: string;
+    constructor(hub: SignalingHub, adapter: ClusterAdapter, opts?: UseClusterOptions);
+    locate(peerId: string): { nodeId: string; room: string } | null;
+    routeDirect(toPeerId: string, type: string, payload: object): boolean;
+    fanoutRoom(roomName: string, type: string, payload: object, excludeId?: string): void;
+    close(): void;
+}
+
+export declare function useCluster(
+    hub: SignalingHub,
+    adapter: ClusterAdapter,
+    opts?: UseClusterOptions
+): ClusterCoordinator;
+
+export declare class MemoryClusterAdapter implements ClusterAdapter {
+    publish(channel: string, message: unknown): void;
+    subscribe(channel: string, handler: (message: unknown) => void): () => void;
+}
+
+// ---------------------------------------------------------------------------
+//  CLI
+// ---------------------------------------------------------------------------
+
+export interface WebRTCCommandDeps {
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+    setExit?: (code: number) => void;
+    stunBinding?: typeof stunBinding;
+}
+
+export declare function runWebRTCCommand(
+    subcmd: 'stun' | 'turn-creds' | 'join-token' | 'verify-token' | 'help' | string,
+    flags?: Map<string, string>,
+    deps?: WebRTCCommandDeps
+): Promise<number>;
+
+// ---------------------------------------------------------------------------
+//  SFU adapter (interface only - real implementations land in later PRs)
+// ---------------------------------------------------------------------------
+
+export interface SfuPeerInfo {
+    id: string;
+    user?: unknown;
+    room: string;
+    joinedAt: number;
+}
+
+export interface SfuRouter { id: string; routerId: string; }
+export interface SfuTransport {
+    id: string;
+    transportId: string;
+    routerId: string;
+    peer: SfuPeerInfo | null;
+    iceParameters: unknown;
+    dtlsParameters: unknown;
+}
+export interface SfuProducer {
+    id: string;
+    producerId: string;
+    transportId: string;
+    kind: 'audio' | 'video';
+    rtpParams: unknown;
+    paused: boolean;
+}
+export interface SfuConsumer {
+    id: string;
+    consumerId: string;
+    transportId: string;
+    producerId: string;
+    kind: 'audio' | 'video';
+    rtpParams: unknown;
+    rtpCaps: unknown;
+}
+export interface SfuStats {
+    kind: 'global' | 'router' | 'transport';
+    [key: string]: unknown;
+}
+
+export type SfuEventHandler = (event: string, payload: unknown) => void;
+
+export declare class SfuAdapter {
+    constructor();
+    createRouter(opts?: unknown): Promise<SfuRouter>;
+    createTransport(router: SfuRouter, peer: SfuPeerInfo): Promise<SfuTransport>;
+    produce(transport: SfuTransport, kind: 'audio' | 'video', rtpParams: unknown): Promise<SfuProducer>;
+    consume(transport: SfuTransport, producerId: string, rtpCaps: unknown): Promise<SfuConsumer>;
+    pauseProducer(producerId: string): Promise<void>;
+    resumeProducer(producerId: string): Promise<void>;
+    closeRouter(routerId: string): Promise<void>;
+    stats(scope?: string): Promise<SfuStats>;
+    onEvent(handler: SfuEventHandler): () => void;
+}
+
+export declare class MemorySfuAdapter extends SfuAdapter {
+    constructor(opts?: Record<string, unknown>);
+}
+
+export interface MediasoupAdapterOptions {
+    mediasoup?: unknown;
+    worker?: unknown;
+    workerSettings?: Record<string, unknown>;
+    mediaCodecs?: Array<Record<string, unknown>>;
+    webRtcTransportOptions?: Record<string, unknown>;
+}
+
+export declare class MediasoupSfuAdapter extends SfuAdapter {
+    constructor(opts?: MediasoupAdapterOptions);
+    close(): Promise<void>;
+}
+
+export interface LiveKitAdapterOptions {
+    url: string;
+    apiKey: string;
+    apiSecret: string;
+    livekit?: unknown;
+    client?: unknown;
+    defaultRoomOpts?: Record<string, unknown>;
+    defaultGrants?: Record<string, unknown>;
+    tokenTtl?: string | number;
+}
+
+export declare class LiveKitSfuAdapter extends SfuAdapter {
+    constructor(opts: LiveKitAdapterOptions);
+}
+
+export declare function loadSfuAdapter(
+    spec: SfuAdapter | 'memory' | 'mediasoup' | 'livekit' | string,
+    opts?: Record<string, unknown>,
+): SfuAdapter;
+
+// ---------------------------------------------------------------------------
+//  Server-side bot peer (wrtc)
+// ---------------------------------------------------------------------------
+
+export interface BotPeerOptions {
+    hub:            SignalingHub;
+    room:           string;
+    user?:          unknown;
+    ip?:            string;
+    joinToken?:     string;
+    iceServers?:    Array<Record<string, unknown>>;
+    rtcConfig?:     Record<string, unknown>;
+    wrtc?:          unknown;
+    onTrack?:       (track: unknown, streams: unknown[], fromPeerId: string) => void;
+    onDataChannel?: (channel: unknown, fromPeerId: string) => void;
+    onPeerJoin?:    (remotePeerId: string) => void;
+    onPeerLeave?:   (remotePeerId: string) => void;
+    onError?:       (err: Error) => void;
+}
+
+export interface BotPeerHandle {
+    peer:               Peer;
+    peerConnections:    Map<string, unknown>;
+    getPeerConnection:  (remotePeerId: string) => unknown | undefined;
+    ready:              Promise<{ peerId: string }>;
+    close:              () => void;
+}
+
+export declare function spawnBotPeer(opts: BotPeerOptions): BotPeerHandle;
+
+// ---------------------------------------------------------------------------
+//  Errors
+// ---------------------------------------------------------------------------
+
+export declare class WebRTCError extends Error { readonly code: string; }
+export declare class SignalingError extends WebRTCError {}
+export declare class IceError extends WebRTCError {}
+export declare class TurnError extends WebRTCError {}
+export declare class SdpError extends WebRTCError {}