@zero-server/sdk 0.9.6 → 0.9.8

package/lib/env/index.js

@@ -61,7 +61,7 @@ function parse(src)
         const key = line.slice(0, eqIdx).trim();
         let value = line.slice(eqIdx + 1).trim();
 
-        // Validate key name — only word chars + dots
+        // Validate key name - only word chars + dots
         if (!/^[\w.]+$/.test(key)) continue;
 
         // Quoted values
@@ -72,7 +72,7 @@ function parse(src)
         }
         else if (q === '"' || q === "'" || q === '`')
         {
-            // Multiline — read until closing quote
+            // Multiline - read until closing quote
             let multiline = value.slice(1);
             while (i < lines.length)
             {
@@ -89,7 +89,7 @@ function parse(src)
         }
         else
         {
-            // Unquoted — strip inline comment
+            // Unquoted - strip inline comment
             const hashIdx = value.indexOf(' #');
             if (hashIdx !== -1) value = value.slice(0, hashIdx).trim();
         }
@@ -215,10 +215,10 @@ let _loaded = false;
  * Load environment variables from `.env` files and validate against a typed schema.
  *
  * Files are loaded in precedence order (later overrides earlier):
- * 1. `.env` — shared defaults
- * 2. `.env.local` — local overrides (gitignored)
- * 3. `.env.{NODE_ENV}` — environment-specific  (e.g. `.env.production`)
- * 4. `.env.{NODE_ENV}.local` — env-specific local overrides
+ * 1. `.env` - shared defaults
+ * 2. `.env.local` - local overrides (gitignored)
+ * 3. `.env.{NODE_ENV}` - environment-specific  (e.g. `.env.production`)
+ * 4. `.env.{NODE_ENV}.local` - env-specific local overrides
  *
  * Process environment variables (`process.env`) always take precedence.
  *
@@ -284,7 +284,7 @@ function load(schema, options = {})
     }
     else
     {
-        // No schema — load everything
+        // No schema - load everything
         Object.assign(merged, raw);
         for (const key of Object.keys(raw))
         {
@@ -340,7 +340,7 @@ function load(schema, options = {})
     }
     else
     {
-        // No schema — store raw strings
+        // No schema - store raw strings
         Object.assign(_store, merged);
     }
 
@@ -427,11 +427,11 @@ function reset()
 }
 
 // ===========================================================
-//  Proxy-based accessor — env.PORT, env('PORT'), env.get('PORT')
+//  Proxy-based accessor - env.PORT, env('PORT'), env.get('PORT')
 // ===========================================================
 
 /**
- * The env function — callable as `env(key)` or `env.key`.
+ * The env function - callable as `env(key)` or `env.key`.
  *
  * @param {string} key - Environment variable name.
  * @returns {*} Result value.

package/lib/errors.js

@@ -21,7 +21,7 @@
  *       age:   'must be >= 18',
  *   });
  *
- *   // Factory — create by status code
+ *   // Factory - create by status code
  *   throw createError(503, 'Try again later');
  */
 
@@ -288,7 +288,7 @@ class ServiceUnavailableError extends HttpError
 // --- Framework Error Classes -------------------------------------
 
 /**
- * Database / ORM error — wraps adapter-level failures.
+ * Database / ORM error - wraps adapter-level failures.
  */
 class DatabaseError extends HttpError
 {
@@ -308,7 +308,7 @@ class DatabaseError extends HttpError
 }
 
 /**
- * Configuration error — thrown when app/adapter configuration is invalid.
+ * Configuration error - thrown when app/adapter configuration is invalid.
  */
 class ConfigurationError extends HttpError
 {
@@ -326,7 +326,7 @@ class ConfigurationError extends HttpError
 }
 
 /**
- * Middleware error — a middleware function failed unexpectedly.
+ * Middleware error - a middleware function failed unexpectedly.
  */
 class MiddlewareError extends HttpError
 {
@@ -344,7 +344,7 @@ class MiddlewareError extends HttpError
 }
 
 /**
- * Routing error — thrown when route resolution fails.
+ * Routing error - thrown when route resolution fails.
  */
 class RoutingError extends HttpError
 {
@@ -364,7 +364,7 @@ class RoutingError extends HttpError
 }
 
 /**
- * Timeout error — operation exceeded allowed time.
+ * Timeout error - operation exceeded allowed time.
  */
 class TimeoutError extends HttpError
 {
@@ -384,7 +384,7 @@ class TimeoutError extends HttpError
 // --- ORM-Specific Error Classes ----------------------------------
 
 /**
- * Connection error — database connection failures with retry context.
+ * Connection error - database connection failures with retry context.
  */
 class ConnectionError extends DatabaseError
 {
@@ -409,7 +409,7 @@ class ConnectionError extends DatabaseError
 }
 
 /**
- * Migration error — migration execution failures.
+ * Migration error - migration execution failures.
  */
 class MigrationError extends DatabaseError
 {
@@ -431,7 +431,7 @@ class MigrationError extends DatabaseError
 }
 
 /**
- * Transaction error — transaction commit/rollback failures.
+ * Transaction error - transaction commit/rollback failures.
  */
 class TransactionError extends DatabaseError
 {
@@ -449,7 +449,7 @@ class TransactionError extends DatabaseError
 }
 
 /**
- * Query error — query execution failures with SQL context.
+ * Query error - query execution failures with SQL context.
  */
 class QueryError extends DatabaseError
 {
@@ -471,7 +471,7 @@ class QueryError extends DatabaseError
 }
 
 /**
- * Adapter error — adapter-level issues (driver not found, unsupported operation).
+ * Adapter error - adapter-level issues (driver not found, unsupported operation).
  */
 class AdapterError extends DatabaseError
 {
@@ -490,7 +490,7 @@ class AdapterError extends DatabaseError
 }
 
 /**
- * Cache error — caching layer failures.
+ * Cache error - caching layer failures.
  */
 class CacheError extends HttpError
 {
@@ -512,7 +512,7 @@ class CacheError extends HttpError
 // --- Phase 4 Error Classes ---------------------------------------
 
 /**
- * Tenancy error — multi-tenancy operation failures.
+ * Tenancy error - multi-tenancy operation failures.
  */
 class TenancyError extends DatabaseError
 {
@@ -532,7 +532,7 @@ class TenancyError extends DatabaseError
 }
 
 /**
- * Audit error — audit logging failures.
+ * Audit error - audit logging failures.
  */
 class AuditError extends DatabaseError
 {
@@ -552,7 +552,7 @@ class AuditError extends DatabaseError
 }
 
 /**
- * Plugin error — plugin registration or lifecycle failures.
+ * Plugin error - plugin registration or lifecycle failures.
  */
 class PluginError extends HttpError
 {
@@ -571,8 +571,117 @@ class PluginError extends HttpError
     }
 }
 
+// --- WebRTC Error Classes ----------------------------------------
+
+/**
+ * Base WebRTC error.  All `@zero-server/webrtc` errors extend this so
+ * they round-trip through `errorHandler` like every other framework error.
+ *
+ * @section WebRTC Error Classes
+ */
+class WebRTCError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts]    - Additional error options.
+     * @param {number} [opts.statusCode=500] - HTTP status override.
+     * @param {string} [opts.code='WEBRTC_ERROR'] - Machine-readable code.
+     * @param {*}      [opts.details] - Extra context.
+     */
+    constructor(message, opts = {})
+    {
+        super(opts.statusCode || 500, message || 'WebRTC Error', { code: 'WEBRTC_ERROR', ...opts });
+    }
+}
+
+/**
+ * Signaling error - malformed or rejected signaling message
+ * (offer / answer / ice / mute / e2ee-key / bye).
+ *
+ * @section WebRTC Error Classes
+ */
+class SignalingError extends WebRTCError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts]    - Additional options.
+     * @param {string} [opts.type] - Signaling message type that failed.
+     * @param {string} [opts.peer] - Peer id involved (if known).
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Signaling Error', { statusCode: 400, code: 'SIGNALING_ERROR', ...opts });
+        if (opts.type) this.type = opts.type;
+        if (opts.peer) this.peer = opts.peer;
+    }
+}
+
+/**
+ * ICE error - candidate parsing, filtering, or selection failure.
+ *
+ * @section WebRTC Error Classes
+ */
+class IceError extends WebRTCError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts]    - Additional options.
+     * @param {string} [opts.candidate] - Raw candidate line (if available).
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'ICE Error', { statusCode: 400, code: 'ICE_ERROR', ...opts });
+        if (opts.candidate) this.candidate = opts.candidate;
+    }
+}
+
+/**
+ * TURN error - upstream TURN server / credential issuance failure.
+ *
+ * @section WebRTC Error Classes
+ */
+class TurnError extends WebRTCError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts]    - Additional options.
+     * @param {string} [opts.realm]    - TURN realm (if applicable).
+     * @param {string} [opts.username] - Username that failed (if applicable).
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'TURN Error', { statusCode: 502, code: 'TURN_ERROR', ...opts });
+        if (opts.realm) this.realm = opts.realm;
+        if (opts.username) this.username = opts.username;
+    }
+}
+
+/**
+ * SDP error - malformed or policy-rejected Session Description Protocol payload.
+ *
+ * @section WebRTC Error Classes
+ */
+class SdpError extends WebRTCError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts]    - Additional options.
+     * @param {number} [opts.line] - Line number where parsing failed.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'SDP Error', { statusCode: 400, code: 'SDP_ERROR', ...opts });
+        if (opts.line !== undefined) this.line = opts.line;
+    }
+}
+
 /**
- * Procedure error — stored procedure/function failures.
+ * Procedure error - stored procedure/function failures.
  */
 class ProcedureError extends DatabaseError
 {
@@ -678,6 +787,12 @@ module.exports = {
     AuditError,
     PluginError,
     ProcedureError,
+    // WebRTC errors
+    WebRTCError,
+    SignalingError,
+    IceError,
+    TurnError,
+    SdpError,
     createError,
     isHttpError,
 };

package/lib/fetch/index.js

@@ -23,7 +23,7 @@ const STATUS_CODES = http.STATUS_CODES;
  * @param {import('http').Agent} [opts.agent]      - Custom HTTP agent.
  * @param {Function} [opts.onDownloadProgress]     - `({ loaded, total }) => void` download progress callback.
  * @param {Function} [opts.onUploadProgress]       - `({ loaded, total }) => void` upload progress callback.
- * @param {boolean}  [opts.rejectUnauthorized]     - Reject connections with unverified certs (default: Node default `true`). TLS option — passed to `https.request()`.
+ * @param {boolean}  [opts.rejectUnauthorized]     - Reject connections with unverified certs (default: Node default `true`). TLS option - passed to `https.request()`.
  * @param {string|Buffer|Array} [opts.ca]          - Override default CA certificates.
  * @param {string|Buffer}       [opts.cert]        - Client certificate (PEM) for mutual TLS.
  * @param {string|Buffer}       [opts.key]         - Private key (PEM) for mutual TLS.

package/lib/grpc/call.js

@@ -4,10 +4,10 @@
  *              Wraps HTTP/2 streams with protobuf encode/decode, metadata,
  *              framing, deadline enforcement, and cancellation support.
  *
- *              - `UnaryCall` — single request, single response
- *              - `ServerStreamCall` — single request, stream of responses
- *              - `ClientStreamCall` — stream of requests, single response
- *              - `BidiStreamCall` — bidirectional streaming
+ *              - `UnaryCall` - single request, single response
+ *              - `ServerStreamCall` - single request, stream of responses
+ *              - `ClientStreamCall` - stream of requests, single response
+ *              - `BidiStreamCall` - bidirectional streaming
  *
  * @example | Unary handler
  *   async function GetUser(call) {
@@ -181,7 +181,7 @@ class BaseCall extends EventEmitter
 
         if (!this._headersSent)
         {
-            // Trailers-Only response — include status in initial HEADERS frame
+            // Trailers-Only response - include status in initial HEADERS frame
             this._headersSent = true;
             try
             {
@@ -199,7 +199,7 @@ class BaseCall extends EventEmitter
         }
         else
         {
-            // Headers already sent — send trailing HEADERS after final DATA
+            // Headers already sent - send trailing HEADERS after final DATA
             this.stream.on('wantTrailers', () =>
             {
                 try { this.stream.sendTrailers(trailHeaders); }
@@ -359,7 +359,7 @@ class BaseCall extends EventEmitter
 // -- Unary Call --------------------------------------------
 
 /**
- * A unary gRPC call — single request message, single response message.
+ * A unary gRPC call - single request message, single response message.
  *
  * @class
  * @extends BaseCall
@@ -391,7 +391,7 @@ class UnaryCall extends BaseCall
     }
 
     /**
-     * Initialize the call — collect the full request body and decode it.
+     * Initialize the call - collect the full request body and decode it.
      * @private
      * @returns {Promise<void>}
      */
@@ -422,7 +422,7 @@ class UnaryCall extends BaseCall
 // -- Server Streaming Call ---------------------------------
 
 /**
- * A server-streaming gRPC call — single request, multiple responses.
+ * A server-streaming gRPC call - single request, multiple responses.
  * The handler calls `call.write(msg)` for each response and `call.end()` to finish.
  *
  * @class
@@ -481,7 +481,7 @@ class ServerStreamCall extends BaseCall
 // -- Client Streaming Call ---------------------------------
 
 /**
- * A client-streaming gRPC call — multiple requests, single response.
+ * A client-streaming gRPC call - multiple requests, single response.
  * The handler iterates `for await (const msg of call)` to consume messages,
  * then returns the response object.
  *
@@ -512,7 +512,7 @@ class ClientStreamCall extends BaseCall
     }
 
     /**
-     * Initialize — set up the frame parser to enqueue decoded messages.
+     * Initialize - set up the frame parser to enqueue decoded messages.
      * @private
      */
     _init()
@@ -560,7 +560,7 @@ class ClientStreamCall extends BaseCall
     }
 
     /**
-     * Async iterator — enables `for await (const msg of call)`.
+     * Async iterator - enables `for await (const msg of call)`.
      *
      * @returns {AsyncIterator<object>}
      */
@@ -589,7 +589,7 @@ class ClientStreamCall extends BaseCall
 // -- Bidirectional Streaming Call ---------------------------
 
 /**
- * A bidirectional streaming gRPC call — multiple requests AND multiple responses.
+ * A bidirectional streaming gRPC call - multiple requests AND multiple responses.
  * The handler can `for await` incoming messages while simultaneously
  * calling `call.write()` to send responses.
  *
@@ -673,7 +673,7 @@ class BidiStreamCall extends BaseCall
     }
 
     /**
-     * Async iterator — enables `for await (const msg of call)`.
+     * Async iterator - enables `for await (const msg of call)`.
      *
      * @returns {AsyncIterator<object>}
      */

package/lib/grpc/client.js

@@ -266,7 +266,7 @@ class GrpcClient extends EventEmitter
     // -- Unary Call -----------------------------------------
 
     /**
-     * Make a unary gRPC call — send one message, receive one response.
+     * Make a unary gRPC call - send one message, receive one response.
      *
      * @param {string} methodName - RPC method name as defined in the proto service.
      * @param {object} request - Request message object.
@@ -394,7 +394,7 @@ class GrpcClient extends EventEmitter
     // -- Server Streaming ----------------------------------
 
     /**
-     * Make a server-streaming gRPC call — send one request, receive a stream of responses.
+     * Make a server-streaming gRPC call - send one request, receive a stream of responses.
      * Returns an async-iterable that yields decoded response messages.
      *
      * @param {string} methodName - RPC method name.
@@ -509,7 +509,7 @@ class GrpcClient extends EventEmitter
     // -- Client Streaming ----------------------------------
 
     /**
-     * Make a client-streaming gRPC call — send a stream of requests, receive one response.
+     * Make a client-streaming gRPC call - send a stream of requests, receive one response.
      * Returns a writable object with `write()`, `end()`, and a `response` Promise.
      *
      * @param {string} methodName - RPC method name.
@@ -608,7 +608,7 @@ class GrpcClient extends EventEmitter
     // -- Bidirectional Streaming ----------------------------
 
     /**
-     * Make a bidirectional streaming gRPC call — send and receive streams simultaneously.
+     * Make a bidirectional streaming gRPC call - send and receive streams simultaneously.
      * Returns an object that is both writable (`write`/`end`) and async-iterable.
      *
      * @param {string} methodName - RPC method name.

package/lib/grpc/codec.js

@@ -76,7 +76,7 @@ const TYPE_INFO = {
 // -- Writer ------------------------------------------------
 
 /**
- * Protobuf binary writer — encodes JavaScript objects into wire-format bytes.
+ * Protobuf binary writer - encodes JavaScript objects into wire-format bytes.
  *
  * @class
  *
@@ -397,7 +397,7 @@ class Writer
 // -- Reader ------------------------------------------------
 
 /**
- * Protobuf binary reader — decodes wire-format bytes into JavaScript values.
+ * Protobuf binary reader - decodes wire-format bytes into JavaScript values.
  *
  * @class
  *
@@ -762,7 +762,7 @@ class Reader
 function encode(obj, messageDesc, allMessages, depth = 0)
 {
     if (depth > MAX_RECURSION_DEPTH)
-        throw new Error(`Maximum encoding depth (${MAX_RECURSION_DEPTH}) exceeded — possible circular reference`);
+        throw new Error(`Maximum encoding depth (${MAX_RECURSION_DEPTH}) exceeded - possible circular reference`);
 
     if (!obj || typeof obj !== 'object')
         return Buffer.alloc(0);
@@ -809,7 +809,7 @@ function encode(obj, messageDesc, allMessages, depth = 0)
 function decode(buffer, messageDesc, allMessages, depth = 0)
 {
     if (depth > MAX_RECURSION_DEPTH)
-        throw new Error(`Maximum decoding depth (${MAX_RECURSION_DEPTH}) exceeded — possible circular reference`);
+        throw new Error(`Maximum decoding depth (${MAX_RECURSION_DEPTH}) exceeded - possible circular reference`);
 
     if (!Buffer.isBuffer(buffer) || buffer.length === 0)
         return _defaultObject(messageDesc);
@@ -830,7 +830,7 @@ function decode(buffer, messageDesc, allMessages, depth = 0)
 
         if (!field)
         {
-            // Unknown field — skip it (forward compatibility)
+            // Unknown field - skip it (forward compatibility)
             reader.skipField(wireType);
             continue;
         }
@@ -868,7 +868,7 @@ function _encodeField(writer, field, value, allMessages, depth)
 
     if (typeInfo)
     {
-        // Scalar type — skip default values in proto3
+        // Scalar type - skip default values in proto3
         if (_isDefaultValue(field.type, value)) return;
 
         writer.writeTag(field.number, typeInfo.wire);
@@ -913,7 +913,7 @@ function _encodeRepeated(writer, field, values, allMessages, depth)
     }
     else
     {
-        // Non-packable (strings, bytes, messages) — one tag per element
+        // Non-packable (strings, bytes, messages) - one tag per element
         for (const v of values) _encodeField(writer, field, v, allMessages, depth);
     }
 }

package/lib/grpc/credentials.js

@@ -5,7 +5,7 @@
  *              and metadata-based credentials. Supports certificate rotation
  *              and credential composition.
  *
- *              Uses only Node.js built-in `tls` and `fs` — no external packages.
+ *              Uses only Node.js built-in `tls` and `fs` - no external packages.
  *
  * @example | Insecure (plaintext)
  *   const { ChannelCredentials, GrpcClient } = require('@zero-server/sdk');
@@ -71,7 +71,7 @@ class ChannelCredentials
 
     /**
      * Create insecure (plaintext) credentials.
-     * No TLS — suitable for development or service-mesh environments
+     * No TLS - suitable for development or service-mesh environments
      * where transport security is handled by the infrastructure.
      *
      * @returns {ChannelCredentials}

package/lib/grpc/frame.js

@@ -23,7 +23,7 @@ const log = require('../debug')('zero:grpc');
 const FRAME_HEADER_SIZE = 5;
 
 /**
- * Maximum frame size (16 MB — matches the default gRPC max).
+ * Maximum frame size (16 MB - matches the default gRPC max).
  * @type {number}
  */
 const MAX_FRAME_SIZE = 16 * 1024 * 1024;
@@ -92,7 +92,7 @@ function _buildFrame(payload, flag)
 // -- Frame Decoder -----------------------------------------
 
 /**
- * Stateful gRPC frame parser — buffers incoming data and emits complete
+ * Stateful gRPC frame parser - buffers incoming data and emits complete
  * decompressed messages.  Designed to be fed chunks from an HTTP/2 stream.
  *
  * @class

package/lib/grpc/health.js

@@ -193,7 +193,7 @@ class HealthService
     }
 
     /**
-     * Handle a Check RPC — unary request for current health of a service.
+     * Handle a Check RPC - unary request for current health of a service.
      * @param {import('./call').UnaryCall} call
      */
     Check(call)
@@ -205,7 +205,7 @@ class HealthService
     }
 
     /**
-     * Handle a Watch RPC — server-stream that pushes status changes.
+     * Handle a Watch RPC - server-stream that pushes status changes.
      * Sends the current status immediately, then pushes on every change.
      * @param {import('./call').ServerStreamCall} call
      */
@@ -232,7 +232,7 @@ class HealthService
 
     /**
      * Get the schema object needed for server registration.
-     * Avoids requiring proto parsing — returns descriptors directly.
+     * Avoids requiring proto parsing - returns descriptors directly.
      * @returns {object} Schema compatible with GrpcServiceRegistry.addService
      */
     getSchema()

package/lib/grpc/index.js

@@ -1,6 +1,6 @@
 /**
  * @module grpc
- * @description Full gRPC support for zero-server — zero external dependencies.
+ * @description Full gRPC support for zero-server - zero external dependencies.
  *              Provides a proto3 parser, protobuf codec, gRPC framing, call objects,
  *              a service server, and a client for all four RPC patterns.
  *
@@ -14,7 +14,7 @@
  *              - Graceful shutdown with call draining
  *              - Message size limits and deadline enforcement
  *
- * @example | Quick Start — Server
+ * @example | Quick Start - Server
  *   const { createApp, parseProto } = require('@zero-server/sdk');
  *   const app = createApp();
  *   const schema = parseProto(`
@@ -35,7 +35,7 @@
  *
  *   app.listen(50051, { http2: true });
  *
- * @example | Quick Start — Client
+ * @example | Quick Start - Client
  *   const { GrpcClient, parseProto } = require('@zero-server/sdk');
  *   const schema = parseProto(fs.readFileSync('hello.proto', 'utf8'));
  *   const client = new GrpcClient('http://localhost:50051', schema, 'Greeter');

package/lib/grpc/metadata.js

@@ -1,6 +1,6 @@
 /**
  * @module grpc/metadata
- * @description gRPC metadata container — typed key-value pairs transmitted as
+ * @description gRPC metadata container - typed key-value pairs transmitted as
  *              HTTP/2 headers (initial metadata) and trailers (trailing metadata).
  *              Keys ending in `-bin` carry binary values (base64-encoded on the wire).
  *              All other keys carry ASCII string values.
@@ -44,7 +44,7 @@ const GRPC_INTERNAL = new Set([
 const MAX_KEY_LENGTH = 256;
 
 /**
- * Maximum total metadata size in bytes (soft limit — 8 KB default, configurable).
+ * Maximum total metadata size in bytes (soft limit - 8 KB default, configurable).
  * @type {number}
  */
 const DEFAULT_MAX_METADATA_SIZE = 8192;
@@ -52,7 +52,7 @@ const DEFAULT_MAX_METADATA_SIZE = 8192;
 // -- Metadata Class ----------------------------------------
 
 /**
- * gRPC metadata container — type-safe key-value pairs for headers and trailers.
+ * gRPC metadata container - type-safe key-value pairs for headers and trailers.
  *
  * @class
  *