@ego-z/client

Official EgoZ Client SDK for Node.js - LLM orchestration made easy.

Installation

npm install @ego-z/client

Quick Start

import { EgoZ } from '@ego-z/client';

const egoz = new EgoZ({
  apiKey: process.env.EGOZ_API_KEY,    // egoz_live_xxx or egoz_test_xxx
  tenantId: process.env.EGOZ_TENANT_ID,
});

const response = await egoz.ask({
  message: 'What is the refund policy?',
});

console.log(response.answer);
console.log(`Tokens used: ${response.usage.totalTokens}`);

Features

• Simple API - One method to interact with your AI assistant
• Streaming - Token-by-token SSE via callback (askStream) or for-await (askStreamIter)
• Trusted-header passthrough - Per-request headers field flows into EgoZ's per-tool forwardHeaders allowlist
• TypeScript First - Full type definitions included
• Automatic Retries - Built-in retry logic with exponential backoff
• Webhook Verification - Secure your tool endpoints with signature validation
• Express Middleware - Drop-in middleware for webhook verification

Configuration

const egoz = new EgoZ({
  apiKey: 'egoz_live_xxx',      // Required - Your EgoZ API key
  tenantId: 'your-tenant-id',   // Required - Your tenant/project ID
  timeout: 30000,               // Optional - Request timeout (ms)
  retries: 2,                   // Optional - Number of retry attempts
});

Sending Messages

Basic Message

const response = await egoz.ask({
  message: 'Hello, how can you help me?',
});

With Conversation Threading

// Start a new conversation
const first = await egoz.ask({
  message: 'What is your return policy?',
  externalUserId: 'user-123', // Your user's ID
});

// Continue the conversation
const second = await egoz.ask({
  message: 'What about electronics?',
  threadId: first.threadId, // Continue same thread
  externalUserId: 'user-123',
});

Bring Your Own Conversation ID (externalThreadId)

If your app already has its own notion of a conversation (e.g. conv:abc123, thread:user42:session99), send it as externalThreadId and EgoZ will resolve every subsequent call with the same id to the same thread — no need to round-trip the EgoZ UUID.

// First call — YOUR conversation id, no need to track EgoZ's UUID.
const r1 = await egoz.ask({
  message: 'Hello',
  externalThreadId: 'conv:abc123', // YOUR id
  externalUserId: 'user:42',
});

// Later — same externalThreadId resolves to the same EgoZ thread.
const r2 = await egoz.ask({
  message: 'Continue please',
  externalThreadId: 'conv:abc123',
});

// r1.threadId === r2.threadId         (the EgoZ UUID is stable across the conversation)
// r1.externalThreadId === 'conv:abc123' (echoed back so you can verify)

Failure modes (Phase 6 — explicit on both fields):

| You send | Behaviour | |---|---| | externalThreadId: 'conv:abc123' (first time) | New thread is created with this id attached. | | externalThreadId: 'conv:abc123' (subsequent) | Same thread is resolved every time. | | threadId: '<unknown EgoZ UUID>' | 404 NotFound — no silent new thread. | | threadId: '<not a UUID>' | 400 InvalidInput — use externalThreadId for your own ids. | | Both threadId and externalThreadId | threadId wins for back-compat; debug warning logged. |

externalThreadId shape rules: any string up to 255 characters, opaque to EgoZ (never parsed). Uniqueness is enforced per-tenant.

With Auth Token Forwarding

// Forward your user's auth token to your tools
const response = await egoz.ask({
  message: 'Check my order status',
  authToken: 'user-jwt-token', // Forwarded to your tool endpoints
});

With Custom Metadata

const response = await egoz.ask({
  message: 'Process refund for my order',
  metadata: {
    orderId: 'order-456',
    customerId: 'cust-789',
    internalTenantId: 'tenant-abc', // For multi-tenant setups
  },
});

With Per-Request Headers (forwardHeaders passthrough)

Pass extra HTTP headers on a single /ask call. EgoZ captures every inbound header and forwards any name listed in the target tool's forwardHeaders allowlist verbatim to that tool's endpoint. Use this for trusted, server-set context — locale, app version, the authenticated user/tenant id when proxying through a gateway, A/B bucket, etc.

// Server-side (e.g. inside a GraphQL resolver) — caller already authenticated
const response = await egoz.ask({
  message: 'Show my recent orders',
  externalUserId: ctx.user.id,
  headers: {
    'x-user-id':   ctx.user.id,        // trusted: injected from session
    'x-tenant-id': ctx.user.tenantId,  // (your app's tenant, not EgoZ's)
    'x-locale':    ctx.user.locale,
    'x-app-version': req.get('x-app-version') ?? 'unknown',
  },
});

For these to actually reach the upstream tool, configure the tool's forwardHeaders allowlist in the EgoZ console (or via MCP) to include the names you're sending.

SDK-reserved names are silently stripped: Authorization, Content-Type, Accept, X-API-Key, X-Tenant-Id, X-Request-Id, plus HTTP framing headers (Host, Content-Length, Transfer-Encoding, Connection). Use authToken instead of Authorization. The exhaustive list is exported as SDK_RESERVED_HEADERS if you want to validate ahead of time.

Forwarding per-call secrets to tools (toolHeaders)

The HTTP headers channel above is the right fit for trusted, server-set context the SDK can pass through verbatim. It's the wrong channel when the value:

1. is per-end-user (so it can't be baked into the tool's static headers config in the console), AND
2. shares a name with a header EgoZ itself uses to authenticate the caller — most commonly Authorization and X-API-Key.

A literal Authorization: Bearer <user-token> sent on the HTTP request would clash with the SDK's own auth (and is stripped from the inbound forward path defensively, regardless). The body field toolHeaders is the explicit opt-in for that case:

const response = await egoz.ask({
  message: 'Show my recent invoices',
  externalUserId: ctx.user.id,
  toolHeaders: {
    // Per-end-user secret destined for the tool, NOT for EgoZ.
    Authorization: `Bearer ${ctx.user.tenantApiToken}`,
    // Tenant's own service-to-service key — also reserved by EgoZ
    // on the HTTP path, so it goes here instead.
    'X-API-Key': ctx.user.tenantServiceKey,
  },
});

How it flows:

• The SDK puts toolHeaders on the /ask request body, not the HTTP headers, so it can't collide with EgoZ-platform credentials.
• EgoZ validates the map (RFC 7230 names, value byte budget, MAX_FORWARD_HEADERS count, no CR/LF/NUL, no EgoZ-internal namespaces) and rejects malformed input with 400 INVALID_INPUT.
• For each tool the LLM ends up calling, EgoZ picks names that appear on both toolHeaders and that tool's forwardHeaders allowlist. Body values win over inbound-HTTP forwards on name conflicts.
• Static tool config (tool.headers) and authType: 'FORWARD' still override on top of forwarded values — tool owners stay in control of the final outbound request.

When debug mode is on (console only), the tool.debug SSE frame includes forwardedHeaderSources: { name: 'body' | 'inbound' } so you can see which channel actually delivered each header without the backend re-emitting the value.

Streaming

EgoZ streams events as it thinks, retrieves knowledge, calls tools, and generates text. Two consumption styles, pick whichever fits the call site.

Callback style (askStream)

await egoz.askStream(
  {
    message: 'Walk me through resetting my password.',
    headers: { 'x-locale': 'en-US' },
  },
  {
    onEvent: (event) => {
      if (event.type === 'delta') process.stdout.write(event.content);
      if (event.type === 'tool.calling') console.log('\n→', event.name);
      if (event.type === 'done') console.log('\n[done]', event.usage);
    },
  },
);

Async-iterator style (askStreamIter)

Designed for GraphQL Subscription resolvers and any place where for await is more natural than registering a callback. Breaking out of the loop aborts the underlying SSE connection.

for await (const ev of egoz.askStreamIter({
  message: 'Walk me through resetting my password.',
  headers: { 'x-locale': 'en-US' },
})) {
  switch (ev.type) {
    case 'delta':       yield { token: ev.content };           break;
    case 'tool.calling': yield { toolStart: ev.name };          break;
    case 'done':        yield { final: ev };                    return;
    case 'error':       throw new Error(ev.message);
  }
}

Pass an AbortSignal for external cancellation (e.g. WebSocket close, HTTP request aborted by the client):

const ctrl = new AbortController();
req.on('close', () => ctrl.abort());

for await (const ev of egoz.askStreamIter(req.body, { signal: ctrl.signal })) {
  // ...
}

Response Object

interface AskResponse {
  threadId: string;              // Conversation thread ID
  answer: string;                // AI's response text
  intent: 'vanilla' | 'rag' | 'tools' | 'rag_tools';
  toolUsed: string | null;       // Tool name if one was called
  ragChunksUsed: number;         // Number of knowledge chunks used
  usage: {
    promptTokens: number;
    completionTokens: number;
    totalTokens: number;
  };
  model: string;                 // Model used (e.g., 'gpt-4.1')
}

Webhook Signature Verification

When EgoZ calls your tool endpoints, it signs the request. Verify these signatures to ensure requests are authentic.

Using Express Middleware

import express from 'express';
import { createEgoZMiddleware } from '@ego-z/client/express';

const app = express();
app.use(express.json());

// Create middleware with your webhook secret
const verifyEgoZ = createEgoZMiddleware({
  secret: process.env.EGOZ_WEBHOOK_SECRET,
  tolerance: 300, // Optional: max age in seconds (default: 5 min)
});

// Apply to your tool routes
app.post('/api/tools/check-order', verifyEgoZ, (req, res) => {
  // Request is verified - access metadata
  console.log(req.egoz?.requestId);  // EgoZ request ID
  console.log(req.egoz?.tenantId);   // Tenant ID
  
  // Your tool logic...
  res.json({ status: 'Order shipped' });
});

Manual Verification

import { verifySignature, validateSignature } from '@ego-z/client';

// Option 1: Throws on invalid signature
try {
  verifySignature({
    signature: req.headers['x-egoz-signature'],
    timestamp: req.headers['x-egoz-timestamp'],
    body: JSON.stringify(req.body),
    secret: process.env.EGOZ_WEBHOOK_SECRET,
  });
  // Signature is valid
} catch (error) {
  // Signature is invalid
  return res.status(401).json({ error: 'Invalid signature' });
}

// Option 2: Returns boolean
const isValid = validateSignature({
  signature: req.headers['x-egoz-signature'],
  timestamp: req.headers['x-egoz-timestamp'],
  body: JSON.stringify(req.body),
  secret: process.env.EGOZ_WEBHOOK_SECRET,
});

Error Handling

import {
  EgoZError,
  AuthenticationError,
  ValidationError,
  NetworkError,
  TimeoutError,
  RateLimitError,
} from '@ego-z/client';

try {
  const response = await egoz.ask({ message: 'Hello' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (error instanceof ValidationError) {
    console.log('Invalid request:', error.message);
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.message);
  } else if (error instanceof EgoZError) {
    console.log(`API error: ${error.code} - ${error.message}`);
  }
}

Health Check

const isHealthy = await egoz.ping();
if (!isHealthy) {
  console.log('EgoZ API is not reachable');
}

Headers Sent by EgoZ

When EgoZ calls your tool endpoints, it includes these headers:

| Header | Description | |--------|-------------| | X-EgoZ-Signature | HMAC-SHA256 signature (sha256=...) | | X-EgoZ-Timestamp | Unix timestamp of the request | | X-EgoZ-Request-Id | Unique request ID for debugging | | X-EgoZ-Tenant-Id | Your tenant/project ID |

TypeScript

Full TypeScript support with exported types:

import type {
  EgoZConfig,
  AskRequest,
  AskResponse,
  AskStreamRequest,
  AskStreamEvent,
  SignatureParams,
  ExpressMiddlewareOptions,
} from '@ego-z/client';

Wire-level types (AskRequest, AskResponse, AskStreamEvent, …) are sourced from @ego-z/contracts — the same package the EgoZ backend imports — so your decoded responses are guaranteed to match what the server actually sends. No more silent answer === undefined from a field-name drift between SDK and backend.

End-to-End Smoke Tests

The SDK ships an opt-in smoke suite that hits a real EgoZ backend over HTTP. Set the three env vars below and run npm run test:smoke to verify your /ask and /ask/stream paths end-to-end against your own project:

EGOZ_SMOKE_BASE_URL=http://localhost:3000 \
EGOZ_SMOKE_API_KEY=egoz_test_xxxxxxxxxxxxxxxx \
EGOZ_SMOKE_TENANT_ID=00000000-0000-0000-0000-000000000000 \
npm run test:smoke

When the env isn't set the suite skips cleanly — npm test never tries to talk to a live service.

License

Apache-2.0 — see LICENSE and NOTICE.