@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/network/index.md

@@ -1,626 +1,168 @@
-# Network
-
-Multi-protocol network communication helpers for HTTP requests, TCP/TLS sockets, and UDP datagrams with scoped logging, auto-reconnect, and client authentication support.
-
-## Quick Reference
-
-| Class | Extends | Protocol | Type |
-|-------|---------|----------|------|
-| `AxiosNetworkRequest` | `BaseNetworkRequest<'axios'>` | HTTP/HTTPS | Client |
-| `NodeFetchNetworkRequest` | `BaseNetworkRequest<'node-fetch'>` | HTTP/HTTPS | Client |
-| `NetworkTcpClient` | `BaseNetworkTcpClient` | TCP | Client |
-| `NetworkTcpServer` | `BaseNetworkTcpServer` | TCP | Server |
-| `NetworkTlsTcpClient` | `BaseNetworkTcpClient` | TLS/SSL | Client |
-| `NetworkTlsTcpServer` | `BaseNetworkTcpServer` | TLS/SSL | Server |
-| `NetworkUdpClient` | `BaseHelper` | UDP | Client |
-
-#### Import Paths
-
-```typescript
-// Main package -- TCP, UDP, and Node Fetch
-import {
-  NodeFetchNetworkRequest,
-  BaseNetworkRequest,
-  NetworkTcpClient,
-  NetworkTcpServer,
-  NetworkTlsTcpClient,
-  NetworkTlsTcpServer,
-  BaseNetworkTcpClient,
-  BaseNetworkTcpServer,
-  NetworkUdpClient,
-} from '@venizia/ignis-helpers';
-
-// Axios (separate export -- optional peer dependency)
-import {
-  AxiosNetworkRequest,
-  AxiosFetcher,
-  type IAxiosNetworkRequestOptions,
-  type IAxiosRequestOptions,
-} from '@venizia/ignis-helpers/axios';
-
-// Types
-import type {
-  INodeFetchNetworkRequestOptions,
-  INodeFetchRequestOptions,
-  INetworkTcpClientProps,
-  ITcpSocketServerOptions,
-  ITcpSocketClient,
-  IRequestOptions,
-  IFetchable,
-  TFetcherVariant,
-} from '@venizia/ignis-helpers';
-```
+---
+title: Network
+description: HTTP request clients, TCP/TLS socket clients and servers, and a UDP client, all built on scoped logging with automatic secret redaction
+difficulty: intermediate
+---
 
-## Creating an Instance
+# Network
 
-### HTTP Request
+Network helpers give you HTTP request clients (fetch or Axios), symmetric TCP/TLS socket client-server pairs, and a UDP client, all sharing the same options-object construction and scoped logging as the rest of the framework.
 
-HTTP helpers follow a two-layer design: a `BaseNetworkRequest` that holds the base URL and delegates to an underlying `IFetchable` fetcher (either Axios or native `fetch`). You typically extend one of the concrete classes to create a typed API client.
+## In one example
 
-#### Axios
+Extend `NodeFetchNetworkRequest` to build a typed HTTP client backed by native `fetch` - no extra dependency required.
 
 ```typescript
-import { AxiosNetworkRequest } from '@venizia/ignis-helpers/axios';
+import { NodeFetchNetworkRequest } from '@venizia/ignis-helpers';
 
-class PaymentGateway extends AxiosNetworkRequest {
+class GitHubApi extends NodeFetchNetworkRequest {
   constructor() {
     super({
-      name: 'PaymentGateway',
-      networkOptions: {
-        baseUrl: 'https://api.payments.com',
-        timeout: 30000,
-        headers: {
-          'X-API-Key': process.env.PAYMENT_API_KEY,
-        },
-      },
+      name: 'GitHubApi',
+      networkOptions: { baseUrl: 'https://api.github.com' },
     });
   }
-}
-```
-
-#### `IAxiosNetworkRequestOptions`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | -- | Helper name, used for scoped logging |
-| `networkOptions.baseUrl` | `string` | `undefined` | Base URL prepended to all request paths |
-| `networkOptions.timeout` | `number` | `60000` | Request timeout in milliseconds |
-| `networkOptions.headers` | `object` | `{ 'content-type': 'application/json; charset=utf-8' }` | Default headers; your values override the default content-type |
-| `networkOptions.*` | `AxiosRequestConfig` | -- | All other Axios config options are accepted |
 
-> [!TIP]
-> `AxiosNetworkRequest` sets sensible defaults: `Content-Type: application/json`, `withCredentials: true`, `validateStatus: status < 500`, and `timeout: 60000` (1 minute). Your options override these defaults.
-
-#### Node.js Fetch
-
-```typescript
-import { NodeFetchNetworkRequest } from '@venizia/ignis-helpers';
-
-class MyApiClient extends NodeFetchNetworkRequest {
-  constructor() {
-    super({
-      name: 'MyApiClient',
-      networkOptions: {
-        baseUrl: 'https://api.example.com',
-        headers: {
-          'Authorization': 'Bearer my-token',
-        },
-        credentials: 'include',
-        mode: 'cors',
-      },
-    });
+  async getUser(username: string) {
+    const url = this.getRequestUrl({ paths: ['users', username] });
+    const response = await this.getNetworkService().get({ url });
+    return response.json();
   }
 }
 ```
 
-#### `INodeFetchNetworkRequestOptions`
+`getRequestUrl()` joins the constructor's `baseUrl` with the path segments; `getNetworkService()` returns the underlying fetcher, which exposes `send()` plus `get`/`post`/`put`/`patch`/`delete`/`query` shortcuts.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `name` | `string` | -- | Helper name, used for scoped logging |
-| `networkOptions.baseUrl` | `string` | `undefined` | Base URL prepended to all request paths |
-| `networkOptions.headers` | `HeadersInit` | `{ 'content-type': 'application/json; charset=utf-8' }` | Default headers; supports `Headers` object or plain object |
-| `networkOptions.*` | `RequestInit` | -- | All other `fetch` options are accepted |
+## How it works
 
-### TCP Client / Server
+- **HTTP is two layers.** `BaseNetworkRequest` holds a base URL and delegates every call to an `IFetchable` fetcher. `NodeFetchNetworkRequest` (root barrel, wraps native `fetch`) and `AxiosNetworkRequest` (`@venizia/ignis-helpers/axios` sub-path, wraps Axios) are the two concrete clients - you typically extend one to build a typed API client, as in the example above.
+- **`axios` is optional.** It's an optional peer dependency, so `AxiosNetworkRequest`'s fetcher is never exported from the root barrel - only from the `/axios` sub-path.
+- **TCP and TLS share one hierarchy.** `BaseNetworkTcpServer`/`BaseNetworkTcpClient` are abstract classes that take a `createServerFn`/`createClientFn` (`net.*` for plain TCP, `tls.*` for TLS). `NetworkTcpServer`/`NetworkTcpClient` and `NetworkTlsTcpServer`/`NetworkTlsTcpClient` pre-wire those functions - constructor options and every method are otherwise identical between the plain and encrypted variants.
+- **Servers track per-client authentication state.** `unauthorized` → `authenticating` → `authenticated`.
+- **Clients auto-reconnect on a fixed delay.** 5 seconds between attempts, up to `maxRetry` attempts, when `reconnect: true`. See the [Full reference](/extensions/helpers/network/api) for the `maxRetry: -1` edge case.
+- **UDP has no client/server split.** `NetworkUdpClient` is a single class wrapping `node:dgram` (UDP4), with optional multicast group joining via `onBind`.
+- **Every class extends `BaseHelper`.** `this.logger.for('methodName')` scoped logging is available throughout.
 
-#### TCP Client
+**HTTP method case**
 
-```typescript
-import { NetworkTcpClient } from '@venizia/ignis-helpers';
+| Layer | Case | Why |
+|-------|------|-----|
+| `HTTP.Methods.GET`/`.POST`/`.QUERY`/... tokens | always lowercase | Required by `@hono/zod-openapi` route definitions |
+| Wire dispatch | uppercased right before send | Node's undici only auto-normalizes `DELETE`/`GET`/`HEAD`/`OPTIONS`/`POST`/`PUT` - a lowercase `patch` or `query` would go out unchanged |
 
-const tcpClient = new NetworkTcpClient({
-  identifier: 'sensor-reader',
-  options: {
-    host: 'localhost',
-    port: 8080,
-  },
-  reconnect: true,
-  maxRetry: 10,
-  encoding: 'utf8',
-  onConnected: ({ client }) => { console.log('Connected'); },
-  onData: ({ identifier, message }) => { console.log('Data:', message.toString()); },
-  onClosed: ({ client }) => { console.log('Closed'); },
-  onError: (error) => { console.error('Error:', error); },
-});
-```
+## Common tasks
 
-#### TCP Client Options (`INetworkTcpClientProps`)
+### Use Axios instead of fetch
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `identifier` | `string` | -- | Unique client identifier for logging |
-| `scope` | `string` | `identifier` | Logger scope name |
-| `options` | `TcpSocketConnectOpts` | -- | Node.js `net.connect` options (`host`, `port`, etc.) |
-| `reconnect` | `boolean` | `false` | Enable automatic reconnection on error |
-| `maxRetry` | `number` | `5` | Maximum reconnection attempts |
-| `encoding` | `BufferEncoding` | `undefined` | Socket encoding (e.g., `'utf8'`) |
-| `onConnected` | `(opts: { client }) => void` | Internal logger | Called when connection is established |
-| `onData` | `(opts: { identifier, message }) => void` | No-op | Called when data is received |
-| `onClosed` | `(opts: { client }) => void` | Internal logger | Called when connection closes |
-| `onError` | `(error: any) => void` | Internal handler with auto-reconnect | Called on connection errors |
-
-#### TCP Server
+Import from the `/axios` sub-path - never from the root barrel, since `axios` is an optional peer dependency.
 
 ```typescript
-import { NetworkTcpServer } from '@venizia/ignis-helpers';
-
-const tcpServer = new NetworkTcpServer({
-  identifier: 'my-tcp-server',
-  serverOptions: {},
-  listenOptions: { port: 8080, host: '0.0.0.0' },
-  authenticateOptions: { required: true, duration: 5000 },
-  onServerReady: ({ server }) => { console.log('Listening'); },
-  onClientConnected: ({ id, socket }) => { console.log(`Client ${id} connected`); },
-  onClientData: ({ id, socket, data }) => { console.log(`Data from ${id}:`, data.toString()); },
-  onClientClose: ({ id, socket }) => { console.log(`Client ${id} disconnected`); },
-  onClientError: ({ id, socket, error }) => { console.error(`Error from ${id}:`, error); },
-});
-```
-
-> [!IMPORTANT]
-> When `authenticateOptions.required` is `true`, you **must** provide a positive `duration` value. Clients that do not authenticate within this duration are automatically disconnected with an "Unauthorized Client" message. Use `doAuthenticate()` in your `onClientData` handler to transition the client's state.
-
-#### TCP Server Options (`ITcpSocketServerOptions`)
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `identifier` | `string` | -- | Server identifier for logging |
-| `scope` | `string` | `identifier` | Logger scope name |
-| `serverOptions` | `Partial<ServerOpts>` | -- | Node.js `net.Server` options |
-| `listenOptions` | `Partial<ListenOptions>` | -- | Listen options (`port`, `host`, `backlog`, etc.) |
-| `authenticateOptions.required` | `boolean` | -- | Whether clients must authenticate |
-| `authenticateOptions.duration` | `number` | `undefined` | Auth timeout in ms (required when `required: true`) |
-| `extraEvents` | `Record<string, (opts) => void>` | `{}` | Additional socket events to register per client |
-| `onServerReady` | `(opts: { server }) => void` | `undefined` | Called when server starts listening |
-| `onClientConnected` | `(opts: { id, socket }) => void` | `undefined` | Called on new client connection |
-| `onClientData` | `(opts: { id, socket, data }) => void` | `undefined` | Called when data is received from a client |
-| `onClientClose` | `(opts: { id, socket }) => void` | `undefined` | Called when a client disconnects |
-| `onClientError` | `(opts: { id, socket, error }) => void` | `undefined` | Called on client socket error |
-
-### TLS Client / Server
-
-TLS variants are identical to their TCP counterparts but use `node:tls` under the hood for encrypted connections. The constructor options accept TLS-specific fields (`cert`, `key`, `ca`, `rejectUnauthorized`, etc.) in addition to all the same handler options.
-
-#### TLS Client
-
-```typescript
-import { NetworkTlsTcpClient } from '@venizia/ignis-helpers';
-import fs from 'node:fs';
-
-const tlsClient = new NetworkTlsTcpClient({
-  identifier: 'secure-client',
-  options: {
-    host: 'secure.example.com',
-    port: 8443,
-    rejectUnauthorized: true,
-    ca: fs.readFileSync('ca.crt'),
-    cert: fs.readFileSync('client.crt'),
-    key: fs.readFileSync('client.key'),
-  },
-  reconnect: true,
-  maxRetry: 3,
-  onData: ({ message }) => { console.log('Secure data:', message); },
-});
-
-tlsClient.connect({ resetReconnectCounter: true });
-```
-
-> [!NOTE]
-> `NetworkTlsTcpClient` accepts `ConnectionOptions` from `node:tls` in the `options` field. All other options (`reconnect`, `maxRetry`, callbacks) are identical to `NetworkTcpClient`.
-
-#### TLS Server
-
-```typescript
-import { NetworkTlsTcpServer } from '@venizia/ignis-helpers';
-import fs from 'node:fs';
-
-const tlsServer = new NetworkTlsTcpServer({
-  identifier: 'secure-tcp-server',
-  serverOptions: {
-    cert: fs.readFileSync('server.crt'),
-    key: fs.readFileSync('server.key'),
-    ca: [fs.readFileSync('ca.crt')],
-    requestCert: true,
-  },
-  listenOptions: { port: 8443, host: '0.0.0.0' },
-  authenticateOptions: { required: false },
-  onClientData: ({ id, data }) => { console.log(`Secure data from ${id}:`, data.toString()); },
-});
-```
-
-> [!NOTE]
-> `NetworkTlsTcpServer` accepts `TlsOptions` from `node:tls` in `serverOptions`. All handlers and methods are identical to `NetworkTcpServer`.
-
-### UDP Client
-
-```typescript
-import { NetworkUdpClient } from '@venizia/ignis-helpers';
-
-const udpClient = NetworkUdpClient.newInstance({
-  identifier: 'my-udp-client',
-  port: 8081,
-  host: '0.0.0.0',
-  reuseAddr: true,
-  multicastAddress: {
-    groups: ['239.1.2.3'],
-    interface: '0.0.0.0',
-  },
-  onData: ({ message, remoteInfo }) => {
-    console.log(`From ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
-  },
-  onBind: async ({ socket, multicastAddress }) => {
-    if (multicastAddress?.groups) {
-      for (const group of multicastAddress.groups) {
-        socket.addMembership(group, multicastAddress.interface);
-      }
-    }
-  },
-});
-```
-
-#### UDP Client Options (`INetworkUdpClientProps`)
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `identifier` | `string` | -- | Unique client identifier for logging |
-| `host` | `string` | `undefined` | Bind address |
-| `port` | `number` | -- | Bind port |
-| `reuseAddr` | `boolean` | `undefined` | Allow address reuse (`SO_REUSEADDR`) |
-| `multicastAddress.groups` | `string[]` | `undefined` | Multicast group addresses to join |
-| `multicastAddress.interface` | `string` | `undefined` | Network interface for multicast |
-| `onConnected` | `(opts: { identifier, host?, port }) => void` | Internal logger | Called when socket starts listening |
-| `onData` | `(opts: { identifier, message, remoteInfo }) => void` | Internal logger | Called when data is received |
-| `onClosed` | `(opts: { identifier, host?, port }) => void` | Internal logger | Called when socket is closed |
-| `onError` | `(opts: { identifier, host?, port, error }) => void` | Internal logger | Called on socket error |
-| `onBind` | `(opts: { identifier, socket, host?, port, reuseAddr?, multicastAddress? }) => void` | `undefined` | Called after socket is bound; use to join multicast groups |
-
-## Usage
-
-### HTTP Requests
-
-Access the underlying fetcher via `getNetworkService()`, then use `send()` or the convenience methods (`get`, `post`, `put`, `patch`, `delete`):
+import { AxiosNetworkRequest } from '@venizia/ignis-helpers/axios';
 
-```typescript
 class PaymentGateway extends AxiosNetworkRequest {
   constructor() {
     super({
       name: 'PaymentGateway',
       networkOptions: {
-        baseUrl: process.env.PAYMENT_API_URL,
+        baseUrl: 'https://api.payments.com',
         timeout: 30000,
         headers: { 'X-API-Key': process.env.PAYMENT_API_KEY },
       },
     });
   }
-
-  async charge(amount: number, currency: string) {
-    const url = this.getRequestUrl({ paths: ['v1', 'charges'] });
-    const response = await this.getNetworkService().send({
-      url,
-      method: 'post',
-      body: { amount, currency },
-    });
-    this.logger.for('charge').info('Payment processed: %s', response.data.id);
-    return response.data;
-  }
-
-  async getTransaction(id: string) {
-    const url = this.getRequestUrl({ paths: ['v1', 'transactions', id] });
-    return this.getNetworkService().get({ url });
-  }
 }
 ```
 
-#### Request Logging & Redaction
-
-Both `NodeFetcher` and `AxiosFetcher` log every outbound request at `info` level (`URL: %s | Props: %s | ...`), including the request config -- headers, body, and any other options passed to `send()`. Before that log line is written, the request config is run through `redactSecrets()`, so values under secret-looking keys never reach the log.
-
-Redaction matches by key name, case-insensitively, at any depth -- both options-object spellings (`apiKey`, `token`, `password`, `authorization`, ...) and HTTP header spellings (`x-api-key`, `x-csrf-token`, `cookie`, `set-cookie`, `proxy-authorization`, `www-authenticate`, ...). A header like `'X-API-Key': process.env.PAYMENT_API_KEY` or `'Authorization': 'Bearer my-token'` (as in the examples above) is logged as `'[REDACTED]'`, not the real value. This redaction happens automatically -- there is nothing to configure.
-
-#### Convenience Methods
-
-```typescript
-const fetcher = this.getNetworkService();
-
-// These are equivalent:
-await fetcher.send({ url: '/users', method: 'get' });
-await fetcher.get({ url: '/users' });
-
-// POST with body
-await fetcher.post({ url: '/users', body: { name: 'Alice' } });
-
-// All methods: get(), post(), put(), patch(), delete()
-```
+`AxiosNetworkRequest` applies defaults you can override: `Content-Type: application/json`, `withCredentials: true`, `validateStatus: status < 500`, `timeout: 60000`.
 
-#### HTTPS with Axios
+### Log a request with secrets redacted
 
-For HTTPS requests, the `AxiosFetcher` automatically creates an `https.Agent`. By default, `rejectUnauthorized` is `false`. Override it per request:
+Pass a logger (typically `this.logger` from a `BaseHelper` subclass) as the second argument to `send()` or any shortcut method - the fetcher logs the URL and config at `info` level with the config run through `redactSecrets()` first, so values like `Authorization` or `X-API-Key` reach the log as `'[REDACTED]'`. Without a logger argument, nothing is logged.
 
 ```typescript
-await fetcher.send({
-  url: 'https://strict-api.example.com/data',
-  method: 'get',
-  rejectUnauthorized: true,
-});
-```
-
-#### Timeout with Node Fetch
-
-The `NodeFetcher` implements timeout via `AbortController`. Pass `timeout` in each `send()` call:
-
-```typescript
-await fetcher.send({
-  url: '/slow-endpoint',
-  method: 'get',
-  timeout: 5000, // Aborts after 5 seconds
-});
+async charge(amount: number, currency: string) {
+  const url = this.getRequestUrl({ paths: ['v1', 'charges'] });
+  const response = await this.getNetworkService().post(
+    { url, body: { amount, currency } },
+    this.logger,
+  );
+  return response.data;
+}
 ```
 
-### TCP Communication
+### Open a TCP connection
 
 ```typescript
 import { NetworkTcpClient, NetworkTcpServer } from '@venizia/ignis-helpers';
 
-// --- Server ---
 const server = new NetworkTcpServer({
   identifier: 'echo-server',
   serverOptions: {},
   listenOptions: { port: 9000, host: '0.0.0.0' },
   authenticateOptions: { required: false },
-  onClientData: ({ id, data }) => {
-    // Echo back to the sender
-    server.emit({ clientId: id, payload: data });
-  },
+  onClientData: ({ id, data }) => server.emit({ clientId: id, payload: data }),
 });
 
-// --- Client ---
 const client = new NetworkTcpClient({
   identifier: 'echo-client',
   options: { host: 'localhost', port: 9000 },
   reconnect: true,
   maxRetry: 5,
-  encoding: 'utf8',
-  onData: ({ message }) => { console.log('Echo:', message); },
+  onData: ({ message }) => console.log('Echo:', message),
 });
 
 client.connect({ resetReconnectCounter: true });
 client.emit({ payload: 'Hello, Server!' });
 ```
 
-#### Server with Authentication Flow
+`NetworkTlsTcpServer`/`NetworkTlsTcpClient` use the identical API - pass certificates in `serverOptions`/`options` (types `TlsOptions`/`ConnectionOptions` from `node:tls`).
+
+### Require TCP client authentication
+
+Set `authenticateOptions.required: true` with a positive `duration` (milliseconds); the constructor throws if `duration` is missing or negative. Clients that never call `doAuthenticate()` within that window are disconnected automatically.
 
 ```typescript
 const server = new NetworkTcpServer({
-  identifier: 'auth-tcp-server',
+  identifier: 'auth-server',
   serverOptions: {},
   listenOptions: { port: 9000, host: '0.0.0.0' },
   authenticateOptions: { required: true, duration: 5000 },
-
   onClientData: ({ id, data }) => {
-    const message = data.toString();
-    const client = server.getClient({ id });
-
-    if (client?.state === 'unauthorized') {
-      if (message === 'secret-token') {
-        server.doAuthenticate({ id, state: 'authenticated' });
-        server.emit({ clientId: id, payload: 'Authenticated!' });
-      } else {
-        server.emit({ clientId: id, payload: 'Invalid credentials' });
-      }
-      return;
+    if (data.toString() === 'secret-token') {
+      server.doAuthenticate({ id, state: 'authenticated' });
     }
-
-    // Handle authenticated client messages
-    console.log(`[${id}] ${message}`);
   },
 });
 ```
 
-#### Client State Tracking
-
-Each connected client is tracked as an `ITcpSocketClient`:
-
-```typescript
-interface ITcpSocketClient<SocketClientType> {
-  id: string;
-  socket: SocketClientType;
-  state: 'unauthorized' | 'authenticating' | 'authenticated';
-  subscriptions: Set<string>;
-  storage: {
-    connectedAt: dayjs.Dayjs;
-    authenticatedAt: dayjs.Dayjs | null;
-    [additionField: symbol | string]: any; // Extensible storage
-  };
-}
-```
-
-### TLS Encrypted Communication
-
-TLS classes share the same API as their TCP counterparts. Provide TLS certificates in the `options` or `serverOptions` field:
-
-```typescript
-import { NetworkTlsTcpServer, NetworkTlsTcpClient } from '@venizia/ignis-helpers';
-import fs from 'node:fs';
-
-// --- TLS Server ---
-const tlsServer = new NetworkTlsTcpServer({
-  identifier: 'secure-server',
-  serverOptions: {
-    cert: fs.readFileSync('server.crt'),
-    key: fs.readFileSync('server.key'),
-    ca: [fs.readFileSync('ca.crt')],
-    requestCert: true,
-  },
-  listenOptions: { port: 8443, host: '0.0.0.0' },
-  authenticateOptions: { required: false },
-  onClientData: ({ id, data }) => {
-    console.log(`Secure data from ${id}:`, data.toString());
-  },
-});
-
-// --- TLS Client ---
-const tlsClient = new NetworkTlsTcpClient({
-  identifier: 'secure-client',
-  options: {
-    host: 'localhost',
-    port: 8443,
-    rejectUnauthorized: true,
-    ca: fs.readFileSync('ca.crt'),
-    cert: fs.readFileSync('client.crt'),
-    key: fs.readFileSync('client.key'),
-  },
-  onData: ({ message }) => { console.log('Secure:', message); },
-});
-
-tlsClient.connect({ resetReconnectCounter: true });
-tlsClient.emit({ payload: 'Hello over TLS!' });
-```
-
-### UDP Communication
+### Send a UDP datagram
 
 ```typescript
 import { NetworkUdpClient } from '@venizia/ignis-helpers';
 
 const udpClient = NetworkUdpClient.newInstance({
-  identifier: 'multicast-listener',
-  port: 5000,
+  identifier: 'my-udp-client',
+  port: 8081,
   host: '0.0.0.0',
-  reuseAddr: true,
-  multicastAddress: {
-    groups: ['239.1.2.3'],
-    interface: '0.0.0.0',
-  },
   onData: ({ message, remoteInfo }) => {
     console.log(`From ${remoteInfo.address}:${remoteInfo.port}:`, message.toString());
   },
-  onBind: async ({ socket, multicastAddress }) => {
-    // Join multicast groups after socket is bound
-    if (multicastAddress?.groups) {
-      for (const group of multicastAddress.groups) {
-        socket.addMembership(group, multicastAddress.interface);
-      }
-    }
-  },
 });
 
-// Start listening
 udpClient.connect();
-
-// Access the underlying dgram.Socket
-const socket = udpClient.getClient();
-
-// Check if bound
-if (udpClient.isConnected()) {
-  // Send a datagram via the raw socket
-  socket.send('Hello', 5001, '239.1.2.3');
-}
-
-// Stop listening
-udpClient.disconnect();
-```
-
-## Troubleshooting
-
-### HTTP: "[getRequestUrl] Invalid configuration for third party request base url!"
-
-**Cause:** `getRequestUrl()` was called but no `baseUrl` was provided at construction time or in the call's `opts.baseUrl` parameter.
-
-**Fix:** Provide a `baseUrl` either in the constructor's `networkOptions` or pass it in the `opts` parameter of `getRequestUrl()`:
-
-```typescript
-// At construction
-const client = new AxiosNetworkRequest({
-  name: 'MyClient',
-  networkOptions: { baseUrl: 'https://api.example.com' },
-});
-
-// Or per call
-const url = client.getRequestUrl({
-  baseUrl: 'https://api.example.com',
-  paths: ['v1', 'users'],
-});
-```
-
-### HTTP: Timeout not working with NodeFetchNetworkRequest
-
-**Cause:** The `timeout` option on the constructor's `networkOptions` is not automatically applied to individual requests. Timeout must be set per-request.
-
-**Fix:** Pass `timeout` in each `send()` call:
-
-```typescript
-await this.getNetworkService().send({
-  url: '/slow-endpoint',
-  method: 'get',
-  timeout: 5000,
-});
-```
-
-The `NodeFetcher` internally creates an `AbortController` and aborts the request after the specified timeout.
-
-### TCP Server: "Invalid authenticate duration"
-
-**Cause:** `authenticateOptions.required` is `true` but `duration` is missing, zero, or negative.
-
-**Fix:** Provide a positive `duration` value when authentication is required:
-
-```typescript
-// Correct
-authenticateOptions: { required: true, duration: 5000 }
-
-// Wrong -- throws at construction time
-authenticateOptions: { required: true }
-authenticateOptions: { required: true, duration: -1 }
+udpClient.getClient()?.send('Hello', 5001, '239.1.2.3');
 ```
 
-### TCP Client: Reconnect loop never stops
+## See also
 
-**Cause:** `maxRetry` is set to `-1` (infinite retries) and the target server is unreachable. The reconnect delay is fixed at 5 seconds between attempts.
-
-**Fix:** Use a finite `maxRetry` value, or set `reconnect: false` if you handle reconnection externally:
-
-```typescript
-const client = new NetworkTcpClient({
-  identifier: 'my-client',
-  options: { host: 'localhost', port: 8080 },
-  reconnect: true,
-  maxRetry: 5, // Stop after 5 attempts
-});
-```
-
-### TCP Server: Client emit does nothing
-
-**Cause:** The target client socket is not writable (already closed or half-closed), or the payload is empty. The server logs a warning but does not throw.
-
-**Fix:** Check the client state before emitting:
-
-```typescript
-const client = server.getClient({ id: clientId });
-if (client && client.socket.writable) {
-  server.emit({ clientId, payload: 'Hello' });
-}
-```
+- [Full reference](/extensions/helpers/network/api) - every class, method signature, and type in the module
+- [Redis helper](/extensions/helpers/redis/) - another `BaseHelper`-based connection helper with the same scoped-logging conventions
 
-## See Also
+**Files:**
 
-- [API Reference](./api) -- Full method signatures and types
+- [`packages/helpers/src/modules/network/http-request/base-network-request.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/http-request/base-network-request.helper.ts) - `BaseNetworkRequest`
+- [`packages/helpers/src/modules/network/http-request/fetcher/node-fetcher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/http-request/fetcher/node-fetcher.ts) - `NodeFetcher`, `NodeFetchNetworkRequest`
+- [`packages/helpers/src/modules/network/http-request/fetcher/axios-fetcher.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/http-request/fetcher/axios-fetcher.ts) - `AxiosFetcher`, `AxiosNetworkRequest` (sub-path export)
+- [`packages/helpers/src/modules/network/tcp-socket/base-tcp-server.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/tcp-socket/base-tcp-server.helper.ts) - `BaseNetworkTcpServer`
+- [`packages/helpers/src/modules/network/tcp-socket/base-tcp-client.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/tcp-socket/base-tcp-client.helper.ts) - `BaseNetworkTcpClient`
+- [`packages/helpers/src/modules/network/udp-socket/network-udp-client.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/network/udp-socket/network-udp-client.helper.ts) - `NetworkUdpClient`