@zero-server/sdk 0.9.7 → 0.9.8

package/lib/webrtc/turn/server.js

@@ -1,36 +1,51 @@
 /**
  * @module webrtc/turn/server
- * @description Zero-dependency embedded TURN server (RFC 5766) backing the
- *              `TurnServer` public API.  Implements the long-term-credential
- *              auth flow paired with `issueTurnCredentials` ephemeral
- *              accounts, UDP allocations, permissions, Send / Data
- *              indications, channel bindings, lifetimes, and per-user
- *              quotas.
+ * @description Zero-dependency embedded TURN server (RFC 5766). Pairs with
+ *   `issueTurnCredentials` for long-term-credential auth and implements
+ *   UDP allocations, permissions, Send/Data indications, channel bindings,
+ *   lifetimes, and per-user quotas. TCP/TLS listeners are reserved and
+ *   currently throw `TURN_TRANSPORT_UNSUPPORTED`.
  *
- *   The hot path is intentionally compact: all framing lives in
- *   `lib/webrtc/turn/codec.js` and the server only owns state +
- *   relay-socket multiplexing.  TCP and TLS listeners are reserved in the
- *   constructor surface and will be implemented in a later PR; calling
- *   `start()` against either currently throws `TURN_TRANSPORT_UNSUPPORTED`.
- *
- * @example
+ * @example | Boot an embedded TURN server alongside Zero Server
  *   const { TurnServer, issueTurnCredentials } = require('@zero-server/webrtc');
  *
  *   const turn = new TurnServer({
- *       secret:   process.env.TURN_SECRET,
- *       realm:    'rtc.example.com',
+ *       secret:    process.env.TURN_SECRET,
+ *       realm:     'rtc.example.com',
+ *       relayHost: process.env.PUBLIC_IP || '0.0.0.0',
  *       listeners: [{ proto: 'udp', port: 3478 }],
- *       quotas:   { maxAllocationsPerUser: 4, maxBytesPerMinute: 50_000_000 },
+ *       quotas:    { maxAllocationsPerUser: 4, maxBytesPerMinute: 50_000_000 },
  *   });
  *   await turn.start();
  *
+ *   turn.on('allocate',   ({ user, relay })   => log.info({ user, relay }, 'turn allocate'));
+ *   turn.on('permission', ({ user, peer })    => log.debug({ user, peer }, 'turn permission'));
+ *   turn.on('relay',      ({ user, bytes })   => metrics.turnBytes.inc(bytes));
+ *
+ *   process.on('SIGTERM', () => turn.close());
+ *
+ * @example | Issue creds + return them with the room join payload
+ *   const { TurnServer, issueTurnCredentials } = require('@zero-server/webrtc');
  *   const creds = issueTurnCredentials({
  *       secret:  process.env.TURN_SECRET,
  *       userId:  req.user.id,
  *       servers: ['turn:rtc.example.com:3478'],
  *       ttl:     '20m',
  *   });
- *   res.json(creds);
+ *   res.json({ token, iceServers: [creds] });
+ *
+ * @example | Multi-listener (UDP + future TCP) with tight per-user quotas
+ *   const turn = new TurnServer({
+ *       secret:    process.env.TURN_SECRET,
+ *       realm:     'rtc.example.com',
+ *       listeners: [{ proto: 'udp', port: 3478, host: '0.0.0.0' }],
+ *       quotas:    {
+ *           maxAllocationsPerUser: 2,
+ *           maxBytesPerMinute:     5_000_000, // 5 MB/min per user
+ *       },
+ *       defaultLifetime: 300,
+ *       maxLifetime:     1800,
+ *   });
  */
 
 'use strict';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zero-server/sdk",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Zero-dependency backend framework for Node.js - routing, ORM, auth, WebSocket, SSE, gRPC, observability, and 20+ middleware. Distributed as a single SDK and as scoped @zero-server/* packages.",
   "main": "index.js",
   "bin": {

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

@@ -97,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 {
@@ -161,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 {

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

package/types/orm.d.ts

@@ -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`).