blockintel-gate-sdk 0.3.3 → 0.3.5

package/README.md

@@ -1,6 +1,6 @@
 # BlockIntel Gate SDK
 
-Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintel.ai) Hot Path API.
+Production-grade TypeScript/Node.js SDK for [BlockIntel Gate](https://blockintelai.com) Hot Path API.
 
 ## Installation
 
@@ -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
@@ -102,6 +108,47 @@ const response = await gate.evaluate({
 });
 ```
 
+### Local Development with Gate Local
+
+For local development and testing, use **Gate Local** - a Docker container that emulates the Gate Hot Path:
+
+```bash
+# Start Gate Local
+docker pull blockintelai/gate-local:latest
+docker run -d --name gate-local -p 3000:3000 blockintelai/gate-local:latest
+```
+
+Then configure your client for local mode:
+
+```typescript
+import { GateClient } from '@blockintel/gate-sdk';
+
+// Local development configuration
+const gate = new GateClient({
+  baseUrl: 'http://localhost:3000',  // Gate Local endpoint
+  tenantId: 'local-dev',              // Any tenant ID (ignored in local mode)
+  local: true,                        // Enable local mode (disables auth/heartbeat)
+  auth: {
+    mode: 'apiKey',
+    apiKey: 'local-dev-key'           // Any API key (ignored in local mode)
+  },
+});
+
+// Evaluate transactions locally
+const response = await gate.evaluate({
+  txIntent: {
+    toAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
+    value: '1000000000000000000',  // 1 ETH in wei
+    valueUsd: 2500.0,
+    chainId: 1,
+  },
+});
+
+console.log(`Decision: ${response.decision}`);
+```
+
+**📚 Full Local Development Guide**: See [Gate Local Quick Start Guide](https://docs.blockintelai.com/gate/local-development) for complete setup instructions, trading bot integration examples, and troubleshooting.
+
 ### Step-Up Polling
 
 ```typescript
@@ -159,9 +206,12 @@ When step-up is disabled, the SDK treats `REQUIRE_STEP_UP` as `BLOCK` by default
 
 ```bash
 # Required
-GATE_BASE_URL=https://gate.blockintelai.net
+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
@@ -335,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.
@@ -353,12 +418,12 @@ The heartbeat manager is automatically configured based on your `GateClientConfi
 
 ```typescript
 const gate = new GateClient({
-  baseUrl: 'https://gate.blockintelai.net',  // Hot Path URL
+  baseUrl: 'https://gate.blockintelai.com',  // Hot Path URL
   tenantId: 'your-tenant-id',
   auth: { mode: 'hmac', ... },
   // Heartbeat manager uses baseUrl to infer Control Plane URL
   // Or explicitly set controlPlaneUrl if different
-  controlPlaneUrl: 'https://control-plane.blockintelai.net',  // Optional
+  controlPlaneUrl: 'https://control-plane.blockintelai.com',  // Optional
   signerId: 'my-signer-id',  // Optional: signerId for heartbeat (if known upfront)
   heartbeatRefreshIntervalSeconds: 10,  // Optional: heartbeat refresh interval (default: 10s)
 });
@@ -455,13 +520,22 @@ See [examples](./examples) directory for complete examples:
 
 See [PUBLISHING.md](./PUBLISHING.md) for detailed publishing instructions.
 
+**Quick steps:**
+1. Update version in `package.json`
+2. Create GitHub release tag
+3. GitHub Actions publishes to NPM automatically
+
 ## License
 
 MIT License - see [LICENSE](./LICENSE) file.
 
 ## Support
 
-- **Documentation:** https://docs.blockintel.ai
+- **Documentation:** https://docs.blockintelai.com
 - **Issues:** https://github.com/4KInc/blockintel-ai/issues
-- **Email:** support@blockintel.ai
+- **Email:** support@blockintelai.com
+
+## Keywords
+
+blockintel, gate, sdk, defense, crypto, security, transaction, evaluation