o2g-node-sdk 2.5.7 → 2.5.9

package/README.md

@@ -54,6 +54,55 @@ await O2G.telephony.makeCall("1234", "5678");
 await O2G.shutdown();
 ```
 
+## What's New in 2.5.9
+
+### TLS certificate validation — `TlsOptions`
+
+The SDK now provides fine-grained control over how the O2G server's TLS
+certificate is validated, via a new `TlsOptions` class passed as the optional
+fourth argument to `O2G.initialize()`.
+
+| Mode | How to configure | When to use |
+|---|---|---|
+| Corporate CA (recommended) | `NODE_EXTRA_CA_CERTS=/path/ca.pem` env var | Standard production deployment — CA as a file on disk |
+| Corporate CA (programmatic) | `TlsOptions.Builder.ca(pem).build()` | CA comes from a database, secret manager, or env var containing PEM content |
+| Self-signed (dev only) | `TlsOptions.Builder.allowSelfSigned().build()` | Development and test environments only |
+| Strict mode | `.rejectInsecureEnvironment()` | Refuse to start if `NODE_TLS_REJECT_UNAUTHORIZED=0` is set |
+
+> **Note:** Node.js does not read the Windows or system certificate store.
+> Internal CA certificates must always be provided explicitly via
+> `NODE_EXTRA_CA_CERTS` or `TlsOptions.ca`.
+
+`allowSelfSigned` is scoped to the SDK only — unlike the global
+`NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable it does not disable TLS
+validation for the entire Node.js process.
+
+See the [TLS Configuration](#tls-configuration) section for full examples.
+
+---
+
+## What's New in 2.5.8
+
+### Service instance caching — fixes listeners silenced after recovery
+
+Service getters (`O2G.eventSummary`, `O2G.telephony`, …) now return the **same
+instance** for the lifetime of a session. Previously every call created a new
+object, and because each constructor silently overwrites the shared `EventSink`
+registration, any listener attached to an earlier instance would stop receiving
+events — a particularly subtle failure after session recovery.
+
+The instances are automatically invalidated on `O2G_SESSION_LOST` and
+`O2G_RECONNECTED`, so the first access after recovery always binds to the new
+session. Re-attach your listeners once in the `O2G_RECONNECTED` handler and they
+will keep working across any number of recovery cycles.
+
+```typescript
+O2G.on(O2G.O2G_RECONNECTED, () => {
+    // Re-attach — O2G.eventSummary now returns a fresh instance
+    O2G.eventSummary.on(EventSummary.ON_EVENT_SUMMARY_UPDATED, onEventSummary);
+});
+```
+
 ## What's New in 2.5.7
 
 - Add new field `emailAddress` in object `User`
@@ -192,6 +241,103 @@ new Host("10.0.0.1", "93.12.1.1")
 
 The SDK tries the private address first, then falls back to the public address.
 
+## TLS Configuration
+
+O2G servers in enterprise environments typically use certificates signed by an
+internal CA. Node.js **does not read the Windows or system certificate store** —
+it ships with its own Mozilla-derived CA bundle. You therefore need to explicitly
+tell Node.js about your internal CA using one of the approaches below.
+
+### `NODE_EXTRA_CA_CERTS` — recommended for most deployments
+
+The standard Node.js mechanism: point to a PEM file on disk before the process
+starts. Node.js adds those certificates to its built-in bundle without replacing
+the existing public CAs.
+
+```bash
+NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corporate-ca.pem node app.js
+```
+
+With this variable set, `O2G.initialize()` requires no `TlsOptions` at all —
+Node.js already trusts the O2G server's certificate:
+
+```typescript
+O2G.initialize("MyApp", O2GServers.Builder
+    .primaryHost(new Host("10.0.0.1"))
+    .build());
+```
+
+This is the recommended approach for production deployments where the CA
+certificate is a stable file on the server (systemd unit, Docker, PM2
+ecosystem file, etc.).
+
+### `TlsOptions.ca` — programmatic alternative
+
+Use this when the CA certificate is not available as a file on disk — for
+example, when it is stored in a database, a secret manager, or an environment
+variable containing the PEM content:
+
+```typescript
+import fs from 'node:fs';
+import { O2G, O2GServers, Host, TlsOptions } from 'o2g-node-sdk';
+
+O2G.initialize("MyApp",
+    O2GServers.Builder.primaryHost(new Host("10.0.0.1")).build(),
+    "1.0",
+    TlsOptions.Builder
+        .ca(fs.readFileSync('/etc/ssl/certs/o2g-ca.pem'))
+        .build()
+);
+```
+
+Unlike `NODE_EXTRA_CA_CERTS`, this is scoped to the SDK only and does not
+affect other HTTPS connections in the same Node.js process.
+
+### Self-signed certificate (development only)
+
+If the O2G server uses a self-signed certificate, disable certificate validation
+for the SDK:
+
+```typescript
+import { O2G, O2GServers, Host, TlsOptions } from 'o2g-node-sdk';
+
+O2G.initialize("MyApp",
+    O2GServers.Builder.primaryHost(new Host("10.0.0.1")).build(),
+    "1.0",
+    TlsOptions.Builder
+        .allowSelfSigned()
+        .build()
+);
+```
+
+> **Warning:** `allowSelfSigned` disables certificate validation entirely.
+> Only use this in development or test environments, never in production.
+
+Unlike the global `NODE_TLS_REJECT_UNAUTHORIZED=0` environment variable,
+`allowSelfSigned` is scoped to the SDK only and does not affect other HTTPS
+connections in the process.
+
+### Strict mode (production hardening)
+
+To ensure that `NODE_TLS_REJECT_UNAUTHORIZED=0` cannot silently bypass TLS
+validation in production, add `.rejectInsecureEnvironment()`:
+
+```typescript
+O2G.initialize("MyApp",
+    O2GServers.Builder.primaryHost(new Host("10.0.0.1")).build(),
+    "1.0",
+    TlsOptions.Builder
+        .rejectInsecureEnvironment()
+        .build()
+);
+```
+
+If `NODE_TLS_REJECT_UNAUTHORIZED=0` is present in the environment when
+`initialize()` is called, the SDK throws an error and refuses to start.
+This can be combined with `NODE_EXTRA_CA_CERTS` or `TlsOptions.ca`.
+
+---
+
 ## Session Monitoring and Recovery
 
 The SDK automatically handles session failures and recovery. When the O2G server
@@ -248,6 +394,10 @@ O2G.on(O2G.O2G_SESSION_LOST, ({ reason }) => {
 
 O2G.on(O2G.O2G_RECONNECTED, () => {
     console.log("Session recovered — resuming activity.");
+    // Re-attach service listeners here: each service getter returns a fresh
+    // instance after recovery, so listeners registered before the outage must
+    // be re-registered (see "Service instance caching" in What's New 2.5.8).
+    O2G.eventSummary.on(EventSummary.ON_EVENT_SUMMARY_UPDATED, onEventSummary);
 });
 
 O2G.on(O2G.O2G_SERVER_SWITCHED, ({ from, to }) => {