@zero-server/orm 0.9.5 → 0.9.7

package/README.md

@@ -10,7 +10,7 @@ Full-featured ORM with seven adapters (memory, JSON file, SQLite, MySQL, Postgre
 npm install @zero-server/orm
 ```
 
-Or grab everything via the optional aggregate:
+Or install the full SDK to get everything at once:
 
 ```bash
 npm install @zero-server/sdk

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/orm';

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/orm");
 

package/lib/debug.js

@@ -16,7 +16,7 @@
  *   log.error('failed to connect', err);
  *   log('shorthand for debug level');
  *
- *   // Set minimum level — anything below is silenced
+ *   // Set minimum level - anything below is silenced
  *   debug.level('warn');   // only warn, error, fatal
  *   debug.level('silent'); // suppress all output
  *   debug.level('trace');  // show everything
@@ -81,7 +81,7 @@ _enabledPatterns = _parsePatterns();
  */
 function _isEnabled(ns)
 {
-    if (!_enabledPatterns) return true; // No DEBUG set — enable all
+    if (!_enabledPatterns) return true; // No DEBUG set - enable all
     let enabled = false;
     for (const { neg, re } of _enabledPatterns)
     {
@@ -116,7 +116,7 @@ function _ts()
 }
 
 /**
- * Format arguments (like console.log — supports %s, %d, %j, %o).
+ * Format arguments (like console.log - supports %s, %d, %j, %o).
  * @private
  */
 function _format(args)
@@ -278,13 +278,13 @@ function debug(namespace)
  * Messages below this level are silenced.
  *
  * @param {string|number} level - Level name or number.
- *   `'trace'` (0) — all output
- *   `'debug'` (1) — debug and above
- *   `'info'` (2) — info and above
- *   `'warn'` (3) — warn and above
- *   `'error'` (4) — error and fatal only
- *   `'fatal'` (5) — fatal only
- *   `'silent'` (6) — nothing
+ *   `'trace'` (0) - all output
+ *   `'debug'` (1) - debug and above
+ *   `'info'` (2) - info and above
+ *   `'warn'` (3) - warn and above
+ *   `'error'` (4) - error and fatal only
+ *   `'fatal'` (5) - fatal only
+ *   `'silent'` (6) - nothing
  */
 debug.level = function(level)
 {

package/lib/orm/adapters/json.js

@@ -1,7 +1,7 @@
 /**
  * @module orm/adapters/json
  * @description JSON file-backed database adapter.
- *              Persists data to JSON files on disk — one file per table.
+ *              Persists data to JSON files on disk - one file per table.
  *              Zero-dependency, suitable for prototyping, small apps, and
  *              embedded scenarios. Uses atomic writes for safety.
  *

package/lib/orm/adapters/memory.js

@@ -413,7 +413,7 @@ class MemoryAdapter
         for (let i = 0; i < where.length; i++)
         {
             const clause = where[i];
-            // Skip raw SQL clauses — not supported in memory adapter
+            // Skip raw SQL clauses - not supported in memory adapter
             if (clause.raw) continue;
             const matches = this._matchClause(row, clause);
 
@@ -695,7 +695,7 @@ class MemoryAdapter
 
     /**
      * Drop an index.
-     * @param {string} _table - Table name (unused — searches all tables).
+     * @param {string} _table - Table name (unused - searches all tables).
      * @param {string} name   - Index name.
      * @returns {Promise<void>}
      */

package/lib/orm/adapters/mongo.js

@@ -369,7 +369,7 @@ class MongoAdapter
 
         let results = await cursor.toArray();
 
-        // Distinct — in-memory since MongoDB distinct() only returns values for a single field
+        // Distinct - in-memory since MongoDB distinct() only returns values for a single field
         if (distinct && fields && fields.length > 0)
         {
             const seen = new Set();
@@ -420,7 +420,7 @@ class MongoAdapter
         for (let i = 0; i < where.length; i++)
         {
             const w = where[i];
-            // Skip raw SQL clauses — not applicable to MongoDB
+            // Skip raw SQL clauses - not applicable to MongoDB
             if (w.raw) continue;
             const { field, op, value, logic } = w;
             const clause = this._opToMongo(field, op, value);

package/lib/orm/adapters/mysql.js

@@ -685,7 +685,7 @@ class MysqlAdapter extends BaseSqlAdapter
     }
 
     /**
-     * Get full database overview — all tables with size and row counts.
+     * Get full database overview - all tables with size and row counts.
      * Returns a structured database summary.
      * @returns {Promise<{ tables: Array, totalSize: string, totalRows: number }>}
      */
@@ -724,7 +724,7 @@ class MysqlAdapter extends BaseSqlAdapter
     }
 
     /**
-     * Get processlist — active connections/queries.
+     * Get processlist - active connections/queries.
      * @returns {Promise<Array<{ id: number, user: string, host: string, db: string, command: string, time: number, state: string, info: string }>>}
      */
     async processlist()

package/lib/orm/adapters/postgres.js

@@ -129,7 +129,7 @@ class PostgresAdapter extends BaseSqlAdapter
         {
             const w = where[i];
 
-            // Handle raw WHERE clauses (from whereRaw) — convert ? to $N
+            // Handle raw WHERE clauses (from whereRaw) - convert ? to $N
             if (w.raw)
             {
                 let rawExpr = w.raw;
@@ -847,7 +847,7 @@ class PostgresAdapter extends BaseSqlAdapter
     }
 
     /**
-     * Get full database overview — all tables with size and row counts.
+     * Get full database overview - all tables with size and row counts.
      * @returns {Promise<{ tables: Array, totalSize: string, totalRows: number }>}
      */
     async overview()

package/lib/orm/adapters/sqlite.js

@@ -84,7 +84,7 @@ class SqliteAdapter extends BaseSqlAdapter
         this._db = new Database(filename, dbOpts);
         this._filename = filename;
 
-        /** @private Prepared statement cache — avoids recompilation overhead */
+        /** @private Prepared statement cache - avoids recompilation overhead */
         this._stmtCache = new Map();
         /** @private Maximum cached statements before LRU eviction */
         this._stmtCacheMax = options.stmtCacheSize || 256;
@@ -685,7 +685,7 @@ class SqliteAdapter extends BaseSqlAdapter
     }
 
     /**
-     * Get counts for all tables — structured database overview.
+     * Get counts for all tables - structured database overview.
      * @returns {{ tables: Array<{ name: string, rows: number }>, totalRows: number, fileSize: string }}
      */
     overview()
@@ -807,7 +807,7 @@ class SqliteAdapter extends BaseSqlAdapter
 
     /**
      * Drop an index.
-     * @param {string} _table - Table name (unused — SQLite indexes are schema-scoped).
+     * @param {string} _table - Table name (unused - SQLite indexes are schema-scoped).
      * @param {string} name   - Index name.
      */
     dropIndex(_table, name)

package/lib/orm/audit.js

@@ -134,7 +134,7 @@ class AuditLog
         }
         else
         {
-            // Memory/JSON adapter — ensure table structure
+            // Memory/JSON adapter - ensure table structure
             if (typeof adapter.createTable === 'function')
             {
                 const schema = {

package/lib/orm/index.js

@@ -5,12 +5,12 @@
  *              `TYPES` enum, and schema helpers.
  *
  * Supported adapters (all optional "bring your own driver"):
- *   - `memory`  — in-process (no driver needed)
- *   - `json`    — JSON file persistence (no driver needed)
- *   - `sqlite`  — requires `better-sqlite3`
- *   - `mysql`   — requires `mysql2`
- *   - `postgres` — requires `pg`
- *   - `mongo`   — requires `mongodb`
+ *   - `memory`  - in-process (no driver needed)
+ *   - `json`    - JSON file persistence (no driver needed)
+ *   - `sqlite`  - requires `better-sqlite3`
+ *   - `mysql`   - requires `mysql2`
+ *   - `postgres` - requires `pg`
+ *   - `mongo`   - requires `mongodb`
  *
  * @example
  *   const { Database, Model, TYPES } = require('@zero-server/sdk');
@@ -231,7 +231,7 @@ class Database
     }
 
     /**
-     * Synchronise all registered models — create tables if they don't exist.
+     * Synchronise all registered models - create tables if they don't exist.
      * Tables are ordered so referenced tables are created first (topological sort).
      * @returns {Promise<void>}
      */

package/lib/orm/migrate.js

@@ -322,7 +322,7 @@ class Migrator
 
     /**
      * Fresh start: drop ALL tables (not just migrated ones) then re-migrate.
-     * ⚠️  DESTRUCTIVE — use with caution.
+     * ⚠️  DESTRUCTIVE - use with caution.
      *
      * @returns {Promise<{ migrated: string[], batch: number }>}
      */

package/lib/orm/model.js

@@ -38,13 +38,13 @@ const { EventEmitter } = require('events');
 class Model
 {
     /**
-     * Table name — override in subclass.
+     * Table name - override in subclass.
      * @type {string}
      */
     static table = '';
 
     /**
-     * Column schema — override in subclass.
+     * Column schema - override in subclass.
      * @type {Object<string, object>}
      */
     static schema = {};
@@ -74,7 +74,7 @@ class Model
     static hidden = [];
 
     /**
-     * Named query scopes — reusable query conditions.
+     * Named query scopes - reusable query conditions.
      * Each scope is a function that receives a Query and returns it.
      * @type {Object<string, Function>}
      *
@@ -103,7 +103,7 @@ class Model
     // -- Computed & Virtual Columns ---------------------
 
     /**
-     * Computed column definitions — virtual columns derived from other fields.
+     * Computed column definitions - virtual columns derived from other fields.
      * Not stored in the database; calculated on the fly.
      * Each entry maps a column name to a getter function `(instance) => value`.
      * @type {Object<string, Function>}
@@ -122,17 +122,17 @@ class Model
     static computed = {};
 
     /**
-     * Attribute casts — automatic type transformations on get/set.
+     * Attribute casts - automatic type transformations on get/set.
      * Maps column names to cast types or custom cast objects.
      *
      * Built-in cast types:
-     * - `'json'`     — JSON.parse on get, JSON.stringify on set
-     * - `'boolean'`  — Cast to true/false
-     * - `'integer'`  — parseInt
-     * - `'float'`    — parseFloat
-     * - `'date'`     — Cast to Date object
-     * - `'string'`   — Cast to String
-     * - `'array'`    — JSON parse/stringify for array data
+     * - `'json'`     - JSON.parse on get, JSON.stringify on set
+     * - `'boolean'`  - Cast to true/false
+     * - `'integer'`  - parseInt
+     * - `'float'`    - parseFloat
+     * - `'date'`     - Cast to Date object
+     * - `'string'`   - Cast to String
+     * - `'array'`    - JSON parse/stringify for array data
      *
      * Custom casts:
      * - `{ get: (v) => transformed, set: (v) => transformed }`
@@ -211,7 +211,7 @@ class Model
     static _relations = {};
 
     /**
-     * Database adapter reference — set by Database.register().
+     * Database adapter reference - set by Database.register().
      * @type {object|null}
      * @private
      */
@@ -222,7 +222,7 @@ class Model
     /**
      * @constructor
      * Create a model instance from a data row.
-     * Generally you won't call this directly — use static methods.
+     * Generally you won't call this directly - use static methods.
      *
      * @param {object} data - Row data.
      */
@@ -825,7 +825,7 @@ class Model
 
     /**
      * Get all records, optionally filtered.
-     * Alias for find() — for LINQ-familiarity.
+     * Alias for find() - for LINQ-familiarity.
      *
      * @param {object} [conditions={}] - WHERE conditions.
      * @returns {Promise<Model[]>} All matching records.

package/lib/orm/procedures.js

@@ -56,7 +56,7 @@ class StoredProcedure
             throw new Error('StoredProcedure requires a "body" string');
         }
 
-        // Sanitize name — only allow identifiers
+        // Sanitize name - only allow identifiers
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name))
         {
             throw new Error(`Invalid procedure name: "${name}"`);

package/lib/orm/profiler.js

@@ -117,7 +117,7 @@ class QueryProfiler
 
         if (!counter || (now - counter.firstTs) >= this._n1Window)
         {
-            // Window expired or first query — start a new window
+            // Window expired or first query - start a new window
             counter = { count: 1, firstTs: now };
             this._selectCounters.set(table, counter);
             return;

package/lib/orm/query.js

@@ -388,7 +388,7 @@ class Query
     }
 
     /**
-     * Alias for with() — mirrors Entity Framework include syntax.
+     * Alias for with() - mirrors Entity Framework include syntax.
      * @param {...string|object} relations - Relation names or config objects to eager-load.
      * @returns {Query} This query for chaining.
      */
@@ -998,7 +998,7 @@ class Query
     }
 
     /**
-     * Make Query thenable — allows `await query`.
+     * Make Query thenable - allows `await query`.
      * @param {Function} resolve - Fulfillment handler.
      * @param {Function} reject  - Rejection handler.
      * @returns {Promise} Result of exec().
@@ -1043,7 +1043,7 @@ class Query
     }
 
     /**
-     * Alias for exec — explicitly convert to array.
+     * Alias for exec - explicitly convert to array.
      * @returns {Promise<Array>} Matching rows as an array.
      */
     toArray()
@@ -1072,7 +1072,7 @@ class Query
     }
 
     /**
-     * Alias for first() — C# FirstOrDefault returns null on empty.
+     * Alias for first() - C# FirstOrDefault returns null on empty.
      * @returns {Promise<object|null>} Matching row or null.
      */
     firstOrDefault()
@@ -1081,7 +1081,7 @@ class Query
     }
 
     /**
-     * Alias for avg() — C# naming.
+     * Alias for avg() - C# naming.
      * @param {string} field - Column name.
      * @returns {Promise<number>} Average of the column values.
      */
@@ -1091,7 +1091,7 @@ class Query
     }
 
     /**
-     * Alias for reduce() — C# Aggregate naming.
+     * Alias for reduce() - C# Aggregate naming.
      * @param {Function} fn - Callback function.
      * @param {*} seed - Initial accumulator value.
      * @returns {Promise<*>} Accumulated value.
@@ -1126,7 +1126,7 @@ class Query
     }
 
     /**
-     * Alias for last() — C# naming.
+     * Alias for last() - C# naming.
      * @returns {Promise<object|null>} Matching row or null.
      */
     lastOrDefault()
@@ -1346,7 +1346,7 @@ class Query
     // -- Projection --
 
     /**
-     * FlatMap — project each element to an array and flatten.
+     * FlatMap - project each element to an array and flatten.
      * @param {Function} fn - (item, index) => Array
      * @returns {Promise<Array>} Flattened projected results.
      */
@@ -1599,7 +1599,7 @@ class Query
     }
 
     /**
-     * Inverse of when — apply query logic when condition is falsy.
+     * Inverse of when - apply query logic when condition is falsy.
      *
      * @param {*}        condition - Condition to evaluate.
      * @param {Function} fn - Callback function.

package/lib/orm/schema.js

@@ -180,7 +180,7 @@ function validateValue(value, colDef, colName)
                 try { return JSON.parse(value); }
                 catch (e) { throw new Error(`"${colName}" must be valid JSON`); }
             }
-            // Already an object/array — return as-is for storage
+            // Already an object/array - return as-is for storage
             return value;
         }
         case 'uuid':

package/lib/orm/seed/data/person.js

@@ -6,7 +6,7 @@
  *              job titles, prefixes/suffixes, gender, bio phrases, zodiac signs.
  */
 
-/** Title prefixes — separate lists per target sex for contextual use. */
+/** Title prefixes - separate lists per target sex for contextual use. */
 const NAME_PREFIXES = {
     male:    ['Mr.', 'Dr.', 'Prof.'],
     female:  ['Ms.', 'Mrs.', 'Dr.', 'Prof.', 'Miss'],

package/lib/orm/seed/fake.js

@@ -5,13 +5,13 @@
  * @description Extensible fake data generator.
  *
  *  Key capabilities:
- *    • Seeded / reproducible output  — Fake.seed(42)
- *    • Guaranteed-unique values      — Fake.unique(() => Fake.email())
- *    • Multi-locale names            — Fake.firstName({ locale: 'ja', sex: 'female' })
- *    • Rich phone formats            — Fake.phone({ countryCode: 'DE', format: 'international' })
- *    • Configurable emails           — Fake.email({ provider: 'company.io' })
- *    • Flexible usernames            — Fake.username({ style: 'underscore' })
- *    • Fixed-length numeric strings  — Fake.numericString(8)
+ *    • Seeded / reproducible output  - Fake.seed(42)
+ *    • Guaranteed-unique values      - Fake.unique(() => Fake.email())
+ *    • Multi-locale names            - Fake.firstName({ locale: 'ja', sex: 'female' })
+ *    • Rich phone formats            - Fake.phone({ countryCode: 'DE', format: 'international' })
+ *    • Configurable emails           - Fake.email({ provider: 'company.io' })
+ *    • Flexible usernames            - Fake.username({ style: 'underscore' })
+ *    • Fixed-length numeric strings  - Fake.numericString(8)
  *    • Person: job titles, bio, zodiac, gender, prefix/suffix
  *    • Location: city, country, state, address, lat/lng, timezone
  *    • Commerce: product, company, category, price, industry
@@ -928,7 +928,7 @@ class Fake
     // -- Internet & Network -------------------------------------------------
 
     /**
-     * Random email address (backward-compatible shorthand — same as email()).
+     * Random email address (backward-compatible shorthand - same as email()).
      * Accepts no arguments for historical use.
      */
 
@@ -1051,7 +1051,7 @@ class Fake
     static userAgent() { return _pick(USER_AGENTS); }
 
     /**
-     * Random password-like string. NOT suitable for real passwords — uses a
+     * Random password-like string. NOT suitable for real passwords - uses a
      * PRNG seeded from Math.random, not a CSPRNG.
      *
      * @param {object}  [options] - Configuration options.
@@ -1180,7 +1180,7 @@ class Fake
     }
 }
 
-// Static uniqueness tracker — shared across all calls in the process lifetime
+// Static uniqueness tracker - shared across all calls in the process lifetime
 Fake._tracker = new UniqueTracker();
 
 module.exports = { Fake };

package/lib/orm/seed/index.js

@@ -5,10 +5,10 @@
  * @description Public API for the seed subsystem.
  *
  * Re-exports:
- *   - `Fake`         — static fake-data generator
- *   - `Factory`      — model factory for defining / creating test fixtures
- *   - `Seeder`       — base class for database seeders
- *   - `SeederRunner` — orchestrates running multiple seeders
+ *   - `Fake`         - static fake-data generator
+ *   - `Factory`      - model factory for defining / creating test fixtures
+ *   - `Seeder`       - base class for database seeders
+ *   - `SeederRunner` - orchestrates running multiple seeders
  */
 
 const { Fake }                   = require('./fake');

package/lib/orm/seed/rng.js

@@ -14,7 +14,7 @@
  */
 
 /**
- * mulberry32 — minimal, high-quality 32-bit PRNG.
+ * mulberry32 - minimal, high-quality 32-bit PRNG.
  * @param {number} s - Unsigned 32-bit integer seed.
  * @returns {() => number} Float in [0, 1).
  */

package/lib/orm/snapshot.js

@@ -234,7 +234,7 @@ function generateMigrationCode(migrationName, changes, currentSnap)
     for (const table of changes.tables.dropped)
     {
         upLines.push(`        await db.adapter.dropTable('${table}');`);
-        // down recreates — but we need the previous snapshot's schema for that
+        // down recreates - but we need the previous snapshot's schema for that
         // This is handled via the `prev` reference embedded in the dropped table
     }
 
@@ -268,7 +268,7 @@ function generateMigrationCode(migrationName, changes, currentSnap)
     return `'use strict';
 
 /**
- * Auto-generated migration — ${migrationName}
+ * Auto-generated migration - ${migrationName}
  * Generated by: npx zh make:migration
  */
 module.exports = {

package/lib/orm/tenancy.js

@@ -43,8 +43,8 @@ class TenantContext
 /**
  * Multi-tenancy manager.
  * Supports two strategies:
- *   - `'row'`    — adds a tenant column to every query (row-level isolation)
- *   - `'schema'` — uses separate database schemas per tenant (PostgreSQL)
+ *   - `'row'`    - adds a tenant column to every query (row-level isolation)
+ *   - `'schema'` - uses separate database schemas per tenant (PostgreSQL)
  */
 class TenantManager
 {
@@ -242,7 +242,7 @@ class TenantManager
         const origCount      = ModelClass.count.bind(ModelClass);
         const origExists     = ModelClass.exists.bind(ModelClass);
 
-        // Patch query() — all query builder paths
+        // Patch query() - all query builder paths
         ModelClass.query = function ()
         {
             const q = origQuery();
@@ -251,7 +251,7 @@ class TenantManager
             return q;
         };
 
-        // Patch create() — inject tenant column
+        // Patch create() - inject tenant column
         ModelClass.create = async function (data)
         {
             const tid = manager.getCurrentTenant();
@@ -283,7 +283,7 @@ class TenantManager
             return origFindOne(conditions);
         };
 
-        // Patch findById() — still applies tenant scope
+        // Patch findById() - still applies tenant scope
         ModelClass.findById = async function (id)
         {
             const tid = manager.getCurrentTenant();
@@ -344,7 +344,7 @@ class TenantManager
                 throw new Error('Schema-based tenancy requires a SQL adapter');
             }
 
-            // Sanitize schema name — only allow alphanumerics and underscores
+            // Sanitize schema name - only allow alphanumerics and underscores
             if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(schema))
             {
                 throw new Error(`Invalid schema name: "${schema}"`);

package/lib/orm/views.js

@@ -293,7 +293,7 @@ class DatabaseView
         const descriptor = this._query.build();
         const table = descriptor.table;
 
-        // Validate field names and table — identifier-safe only
+        // Validate field names and table - identifier-safe only
         const idRe = /^[a-zA-Z_][a-zA-Z0-9_.*]*$/;
         const fields = descriptor.fields
             ? descriptor.fields.filter(f => idRe.test(f)).join(', ') || '*'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/orm",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Database, Model, Query, migrations, seeds, search, geo, tenancy, audit.",
   "keywords": [
     "zero-server",
@@ -45,10 +45,10 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@zero-server/errors": "0.9.5"
+    "@zero-server/errors": "0.9.7"
   },
   "peerDependencies": {
-    "@zero-server/sdk": ">=0.9.5"
+    "@zero-server/sdk": ">=0.9.7"
   },
   "peerDependenciesMeta": {
     "@zero-server/sdk": {

package/types/body.d.ts

@@ -1,4 +1,4 @@
-// Re-exports for @zero-server/body — body parser types
+// Re-exports for @zero-server/body - body parser types
 export {
     BodyParserOptions,
     JsonParserOptions,

package/types/cli.d.ts

@@ -1,2 +1,2 @@
-// Re-exports for @zero-server/cli — CLI runner types
+// Re-exports for @zero-server/cli - CLI runner types
 export { CLI, runCLI } from './orm';

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 {
@@ -294,10 +306,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 +318,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

@@ -136,7 +136,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

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 {}