blockintel-gate-sdk 0.3.6 → 0.3.8

package/README.md

@@ -13,6 +13,12 @@ npm install @blockintel/gate-sdk
 - Node.js >= 18.0.0 (uses global `fetch` API)
 - TypeScript >= 5.0.0 (optional, for type definitions)
 
+### Hot Path compatibility
+
+- **Mode**: Default is `SHADOW` (Hot Path returns ALLOW with reason codes for would-block decisions). Set `mode: 'ENFORCE'` or `GATE_MODE=ENFORCE` for real BLOCK responses.
+- **signingContext**: Hot Path requires `actorPrincipal` and `signerId`. The SDK defaults them when missing (`gate-sdk-client` or from `signingContext.signerId`).
+- **ESM**: HMAC and SHA-256 use `node:crypto` (no `require('crypto')`), so the SDK works in ESM (`"type": "module"`) and in bundled canary apps.
+
 ## Quick Start
 
 ### HMAC Authentication
@@ -203,6 +209,9 @@ When step-up is disabled, the SDK treats `REQUIRE_STEP_UP` as `BLOCK` by default
 GATE_BASE_URL=https://gate.blockintelai.com
 GATE_TENANT_ID=your-tenant-id
 
+# Heartbeat (required when not using local mode; parity with Python GATE_HEARTBEAT_KEY)
+GATE_HEARTBEAT_KEY=your-heartbeat-key
+
 # HMAC Authentication
 GATE_KEY_ID=your-key-id
 GATE_HMAC_SECRET=your-secret
@@ -376,6 +385,21 @@ The SDK automatically retries failed requests:
 - Same `requestId` is used across all retries
 - Ensures idempotency on Gate server
 
+## Degraded Mode / X-BlockIntel-Degraded
+
+When the SDK is in a degraded situation, it logs `X-BlockIntel-Degraded: true` with a `reason` for **logs and telemetry only**. This is **never sent as an HTTP request header** to the Gate server.
+
+**Reasons:** `retry`, `429`, `fail_open`, `fail_safe_allow`.
+
+**Example (one line):**  
+`[GATE SDK] X-BlockIntel-Degraded: true (reason=retry) attempt=1/3 status=503 err=RATE_LIMITED`
+
+**How to observe:**
+- **Logs:** `[GATE SDK] X-BlockIntel-Degraded: true (reason: <reason>)` via `console.warn`. Pipe stderr to your log aggregator.
+- **Metrics:** Use `onMetrics`; metrics include `timeouts`, `errors`, `failOpen`, etc. Correlate with log lines if you ship both.
+
+**Manual check (retry):** Point the SDK at an endpoint that returns 5xx; confirm one degraded log per retry attempt including `attempt`, `max`, and `status`/`err`.
+
 ## Heartbeat System
 
 The SDK includes a **Heartbeat Manager** that automatically acquires and refreshes heartbeat tokens from the Gate Control Plane. Heartbeat tokens are required for all signing operations and ensure that Gate is alive and enforcing policy.