orqo-node-sdk 0.1.0

package/README.md

@@ -0,0 +1,547 @@
+<p align="center">
+  <img src="https://img.shields.io/badge/%40orqo%2Fsdk-v0.1.0-7c3aed?style=for-the-badge&logo=typescript&logoColor=white" alt="version" />
+  <img src="https://img.shields.io/badge/zero--deps-✓-10b981?style=for-the-badge" alt="zero deps" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="typescript strict" />
+  <img src="https://img.shields.io/badge/license-MIT-f59e0b?style=for-the-badge" alt="license" />
+</p>
+
+<h1 align="center">🎯 Orqo SDK</h1>
+
+<p align="center">
+  <strong>The official TypeScript SDK for the Orqo AI Agent Gateway.</strong><br/>
+  Provision instances, connect WhatsApp, manage agents, and orchestrate<br/>
+  conversations — all from a single, type-safe package with <b>zero runtime dependencies</b>.
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-api-reference">API Reference</a> •
+  <a href="#-webhook-handler">Webhook Handler</a> •
+  <a href="#-api-bridge">API Bridge</a> •
+  <a href="#%EF%B8%8F-resilience">Resilience</a> •
+  <a href="#-architecture">Architecture</a>
+</p>
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🚀 **Plug-and-Play** | Provision → Connect → Send in 5 lines of code |
+| 🔒 **Type-Safe** | Full TypeScript coverage with strict mode — every method, every event |
+| 📦 **Zero Dependencies** | Only `globalThis.fetch` — works in Node.js 18+, Bun, Deno, and Edge |
+| 🔁 **Retry & Resilience** | Exponential backoff with configurable retry on 429/5xx |
+| 🪝 **Webhook Handler** | HMAC-verified, typed event dispatch for Express/Hono/Fastify/Node |
+| 🤖 **Agent Management** | Full CRUD for AI agents with system prompts and tool bindings |
+| 🔌 **API Bridge** | Connect any OpenAPI spec and the agent gains tools automatically |
+| ⏰ **Cron Jobs** | Schedule recurring actions per instance |
+| 🤝 **Handoff** | Bot ↔ Human session transfer with metadata |
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @orqo/sdk
+```
+
+> **Requirements:** Node.js 18+ (or any runtime with `globalThis.fetch`)
+
+---
+
+## 🚀 Quick Start
+
+### 1. Provision an Instance
+
+```typescript
+import { OrqoClient } from '@orqo/sdk';
+
+const orqo = new OrqoClient({
+  host: 'https://gateway.orqo.ai',
+  adminToken: process.env.ORQO_ADMIN_TOKEN!,
+});
+
+const { instance, result } = await orqo.provision({
+  name: 'My Support Bot',
+  webhookUrl: 'https://my-app.com/webhooks/orqo',
+  webhookSecret: process.env.WEBHOOK_SECRET,
+});
+
+console.log(`✅ Instance ${result.instanceId} created`);
+```
+
+### 2. Connect WhatsApp
+
+```typescript
+// Wait for QR scan with live feedback
+await instance.waitForConnection({
+  onQr: (qr) => console.log('📱 Scan this QR:', qr),
+  timeoutMs: 120_000,
+});
+
+console.log('🟢 WhatsApp connected!');
+```
+
+### 3. Send a Message
+
+```typescript
+await instance.sendMessage({
+  to: '5511999887766@s.whatsapp.net',
+  text: 'Hello from Orqo! 🚀',
+});
+```
+
+### 4. Receive Events
+
+```typescript
+import { createWebhookHandler } from '@orqo/sdk';
+
+app.post('/webhooks/orqo', createWebhookHandler({
+  secret: process.env.WEBHOOK_SECRET,
+  onMessageReceived: async (event) => {
+    console.log(`💬 ${event.from}: ${event.text}`);
+  },
+  onConnectionChanged: (event) => {
+    console.log(`📡 ${event.state}`);
+  },
+}));
+```
+
+---
+
+## 📖 API Reference
+
+### `OrqoClient` — Admin Operations
+
+> Requires `adminToken`. Used for instance lifecycle management.
+
+```typescript
+const orqo = new OrqoClient({ host, adminToken });
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `provision(options)` | `{ instance, result }` | Create instance + boot WhatsApp |
+| `listInstances()` | `InstanceStatus[]` | List all instances |
+| `getInstance(id, token)` | `OrqoInstance` | Get handle for existing instance |
+| `deleteInstance(id)` | `void` | Delete an instance |
+
+---
+
+### `OrqoInstance` — Instance Operations
+
+> Scoped to a single instance. All methods auto-retry on 429/5xx.
+
+#### WhatsApp
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getWhatsAppStatus()` | `WhatsAppStatus` | Connection state + QR code |
+| `connectWhatsApp()` | `InstanceStatus` | Start WhatsApp socket |
+| `disconnectWhatsApp()` | `void` | Disconnect WhatsApp |
+| `reconnectWhatsApp()` | `InstanceStatus` | Force reconnect (stale connections) |
+| `pairByPhone(phone)` | `{ code }` | Phone-number pairing code |
+| `waitForConnection(opts?)` | `WhatsAppStatus` | Poll until connected (with QR callback) |
+
+#### Messaging
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sendMessage({ to, text })` | `SendMessageResult` | Send a text message |
+| `getMessages(opts?)` | `Record[]` | Retrieve messages (with sessionKey filter) |
+| `getSessions(opts?)` | `Record[]` | List conversation sessions |
+
+#### Agents
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createAgent(config)` | `Agent` | Create an AI agent |
+| `listAgents()` | `Agent[]` | List all agents |
+| `getAgent(id)` | `Agent` | Get agent by ID |
+| `updateAgent(id, updates)` | `Agent` | Patch agent config |
+| `deleteAgent(id)` | `void` | Remove an agent |
+
+#### Webhooks
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `addWebhook({ url, event, secret? })` | `Webhook` | Register a webhook |
+| `listWebhooks()` | `Webhook[]` | List registered webhooks |
+| `removeWebhook(id)` | `void` | Unregister a webhook |
+
+#### Guardrails
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `setGuardrails(config)` | `GuardrailConfig` | Set AI response rules |
+| `getGuardrails()` | `GuardrailConfig` | Get current guardrail config |
+
+#### Session Handoff
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `handoffToHuman(options)` | `HandoffResult` | Transfer session to human agent |
+| `resumeBot(sessionId)` | `HandoffResult` | Return session to bot control |
+
+#### Cron Jobs
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `listCronJobs()` | `Record[]` | List scheduled jobs |
+| `createCronJob(config)` | `Record` | Schedule a recurring job |
+| `deleteCronJob(id)` | `void` | Remove a scheduled job |
+| `runCronJob(id)` | `Record` | Trigger a job manually |
+
+#### API Bridge
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connectApi(options)` | `{ bridge, tools }` | Connect an OpenAPI spec |
+| `listApiBridges()` | `Array` | List connected bridges |
+| `removeApiBridge(id)` | `{ success }` | Disconnect a bridge |
+| `refreshApiBridge(id)` | `{ bridge, tools }` | Re-fetch spec & update tools |
+
+#### Monitoring
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getStatus()` | `InstanceStatus` | Instance health & metadata |
+| `getStats()` | `Record` | Messages, sessions, uptime |
+
+---
+
+## 🪝 Webhook Handler
+
+The `createWebhookHandler()` function provides a framework-agnostic webhook receiver with **HMAC signature verification** and **typed event dispatch**.
+
+### Express
+
+```typescript
+import express from 'express';
+import { createWebhookHandler } from '@orqo/sdk';
+
+const app = express();
+app.use(express.json());
+
+app.post('/webhooks/orqo', createWebhookHandler({
+  secret: process.env.WEBHOOK_SECRET,
+  onConnectionChanged: (e) => {
+    console.log(`${e.instanceId}: ${e.state}`);
+  },
+  onMessageReceived: async (e) => {
+    console.log(`From ${e.from}: ${e.text}`);
+    // Process message...
+  },
+  onMessageProcessed: (e) => {
+    console.log(`AI processed: ${e.messageId}`);
+  },
+  onHandoff: (e) => {
+    console.log(`Handoff: session ${e.sessionId}`);
+  },
+  onEvent: (e) => {
+    // Catch-all for any event type
+  },
+  onVerificationFailed: (err) => {
+    console.error('⚠️ Invalid signature:', err.message);
+  },
+}));
+```
+
+### Hono
+
+```typescript
+import { Hono } from 'hono';
+import { createWebhookHandler } from '@orqo/sdk';
+
+const app = new Hono();
+
+app.post('/webhooks/orqo', async (c) => {
+  const handler = createWebhookHandler({
+    secret: c.env.WEBHOOK_SECRET,
+    onMessageReceived: async (e) => {
+      console.log(`${e.from}: ${e.text}`);
+    },
+  });
+  await handler(
+    { body: await c.req.json(), headers: c.req.raw.headers },
+    { status: (s) => ({ json: (b) => c.json(b, s) }) },
+  );
+  return c.body(null, 200);
+});
+```
+
+### Event Types
+
+| Event | Interface | Trigger |
+|-------|-----------|---------|
+| `connection:changed` | `ConnectionChangedEvent` | WhatsApp connects/disconnects |
+| `message:received` | `MessageReceivedEvent` | New incoming message |
+| `message:processed` | `MessageProcessedEvent` | AI finishes processing |
+| `session:handoff` | `HandoffEvent` | Session transferred to human |
+
+### Security
+
+- **HMAC-SHA256** signature verification (`X-Webhook-Signature` header)
+- **Dual runtime**: Web Crypto API (browser/edge) + Node.js `crypto` fallback
+- **Timing-safe** string comparison to prevent timing attacks
+
+---
+
+## 🔌 API Bridge
+
+Connect any external REST API via its OpenAPI spec. The AI agent automatically gains typed tools from the spec endpoints.
+
+```typescript
+// Connect your CRM API — agent instantly gets tools like
+// "crm_getContact", "crm_createLead", "crm_updateDeal"
+await instance.connectApi({
+  name: 'salesforce',
+  specUrl: 'https://api.salesforce.com/openapi.json',
+  auth: { type: 'bearer', token: process.env.SF_TOKEN },
+  description: 'CRM for sales pipeline management',
+});
+
+// Connect a payments API
+await instance.connectApi({
+  name: 'stripe',
+  specUrl: 'https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json',
+  auth: { type: 'bearer', token: process.env.STRIPE_KEY },
+});
+
+// List what's connected
+const bridges = await instance.listApiBridges();
+console.log(bridges.map(b => `${b.name}: ${b.tools.length} tools`));
+```
+
+### Auth Types
+
+| Type | Fields | Example |
+|------|--------|---------|
+| `bearer` | `token` | `{ type: 'bearer', token: 'sk-...' }` |
+| `apiKey` | `token`, `headerName` | `{ type: 'apiKey', token: 'key', headerName: 'X-API-Key' }` |
+| `basic` | `username`, `password` | `{ type: 'basic', username: 'u', password: 'p' }` |
+| `custom` | `headers` | `{ type: 'custom', headers: { 'X-Custom': 'val' } }` |
+
+### Security
+
+The API Bridge includes built-in **SSRF prevention**:
+- Blocks private/loopback/metadata IP addresses
+- Validates URL protocols (http/https only)
+- Limits spec size (2MB), operations (100), bridges per instance (10)
+- Blocks redirect-based attacks
+
+---
+
+## 🛡️ Resilience
+
+All HTTP methods include automatic retry with exponential backoff:
+
+```typescript
+const orqo = new OrqoClient({
+  host: 'https://gateway.orqo.ai',
+  adminToken: 'token',
+  retry: {
+    maxAttempts: 5,        // default: 3
+    backoffMs: 500,        // default: 1000
+    multiplier: 2,         // default: 2
+    retryOn: [429, 503],   // default: [429, 500, 502, 503, 504]
+  },
+});
+```
+
+The retry config cascades from `OrqoClient` → `OrqoInstance`, so all instance methods inherit the same resilience settings.
+
+### Backoff Timeline (defaults)
+
+```
+Attempt 1 → immediate
+Attempt 2 → wait 1000ms
+Attempt 3 → wait 2000ms
+Attempt 4 → wait 4000ms  (if maxAttempts > 3)
+```
+
+---
+
+## 🤝 Complete Workflow Example
+
+```typescript
+import { OrqoClient, createWebhookHandler } from '@orqo/sdk';
+import express from 'express';
+
+// ── 1. Setup ─────────────────────────────────────────────
+const orqo = new OrqoClient({
+  host: process.env.ORQO_HOST!,
+  adminToken: process.env.ORQO_ADMIN_TOKEN!,
+});
+
+// ── 2. Provision ─────────────────────────────────────────
+const { instance } = await orqo.provision({
+  name: 'Customer Support',
+  webhookUrl: 'https://my-app.com/webhooks/orqo',
+  webhookSecret: process.env.WEBHOOK_SECRET,
+});
+
+// ── 3. Configure Agent ───────────────────────────────────
+await instance.createAgent({
+  name: 'Support Agent',
+  type: 'chat',
+  systemPrompt: `You are a helpful customer support agent.
+    Be concise and professional. If you cannot resolve
+    the issue, hand off to a human agent.`,
+  tools: ['knowledge-base', 'ticket-system'],
+});
+
+// ── 4. Set Guardrails ────────────────────────────────────
+await instance.setGuardrails({
+  blockedTopics: ['competitor-pricing', 'internal-processes'],
+  maxResponseLength: 500,
+  filterPII: true,
+});
+
+// ── 5. Connect External APIs ─────────────────────────────
+await instance.connectApi({
+  name: 'zendesk',
+  specUrl: 'https://api.zendesk.com/openapi.json',
+  auth: { type: 'bearer', token: process.env.ZENDESK_TOKEN },
+});
+
+// ── 6. Connect WhatsApp ──────────────────────────────────
+await instance.waitForConnection({
+  onQr: (qr) => sendQrToAdmin(qr),
+});
+
+// ── 7. Receive Events ────────────────────────────────────
+const app = express();
+app.use(express.json());
+
+app.post('/webhooks/orqo', createWebhookHandler({
+  secret: process.env.WEBHOOK_SECRET,
+  onMessageReceived: async (e) => {
+    console.log(`💬 ${e.pushName}: ${e.text}`);
+  },
+  onHandoff: async (e) => {
+    await notifyHumanAgent(e.sessionId, e.reason);
+  },
+}));
+
+// ── 8. Schedule Reminders ────────────────────────────────
+await instance.createCronJob({
+  schedule: '0 9 * * 1',  // Every Monday at 9am
+  action: 'send-weekly-summary',
+  payload: { channel: 'admin' },
+});
+
+app.listen(3000, () => console.log('🚀 Running on :3000'));
+```
+
+---
+
+## 🏗 Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                        @orqo/sdk                             │
+├──────────────┬─────────────────┬─────────────────────────────┤
+│  OrqoClient  │  OrqoInstance   │  createWebhookHandler()     │
+│  (Admin)     │  (Per-instance) │  (Event receiver)           │
+│              │                 │                             │
+│  provision() │  30 methods     │  HMAC verification          │
+│  listInst()  │  WhatsApp       │  Typed event dispatch       │
+│  deleteInst()│  Agents         │  Express/Hono/Fastify       │
+│  getInst()   │  Webhooks       │  Web Crypto + Node.js       │
+│              │  Guardrails     │                             │
+│              │  Handoff        │                             │
+│              │  API Bridge     │                             │
+│              │  Cron Jobs      │                             │
+│              │  Stats/Messages │                             │
+├──────────────┴─────────────────┴─────────────────────────────┤
+│                   Retry / Resilience Layer                    │
+│          Exponential backoff • Configurable • Cascading      │
+├──────────────────────────────────────────────────────────────┤
+│                   globalThis.fetch (zero deps)               │
+│          Node.js 18+ • Bun • Deno • Cloudflare Workers       │
+└──────────────────────────────────────────────────────────────┘
+         │                    │
+         ▼                    ▼
+  ┌──────────────┐   ┌──────────────────┐
+  │ Orqo Gateway │   │ Your HTTP Server │
+  │  REST API    │   │  Webhook Events  │
+  └──────────────┘   └──────────────────┘
+```
+
+---
+
+## 📋 Type Exports
+
+All types are exported from the main entry point:
+
+```typescript
+import type {
+  // Config
+  OrqoClientConfig,
+  OrqoInstanceConfig,
+  RetryConfig,
+
+  // Provisioning
+  ProvisionOptions,
+  ProvisionResult,
+
+  // WhatsApp
+  WhatsAppStatus,
+  SendMessageOptions,
+  SendMessageResult,
+
+  // Instance
+  InstanceStatus,
+
+  // Agents
+  AgentConfig,
+  Agent,
+
+  // Webhooks
+  WebhookConfig,
+  Webhook,
+
+  // Guardrails
+  GuardrailConfig,
+
+  // Handoff
+  HandoffOptions,
+  HandoffResult,
+
+  // Events
+  WebhookEvent,
+  ConnectionChangedEvent,
+  MessageReceivedEvent,
+  MessageProcessedEvent,
+  HandoffEvent,
+  OrqoWebhookEvent,
+  WebhookHandlerOptions,
+} from '@orqo/sdk';
+```
+
+---
+
+## 🔧 Runtime Compatibility
+
+| Runtime | Version | Status |
+|---------|---------|--------|
+| Node.js | 18+ | ✅ Full support |
+| Bun | 1.0+ | ✅ Full support |
+| Deno | 1.28+ | ✅ Full support |
+| Cloudflare Workers | — | ✅ Full support |
+| Vercel Edge | — | ✅ Full support |
+| Browser | — | ⚠️ CORS-dependent |
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) — Use it however you want.
+
+---
+
+<p align="center">
+  <sub>Built with 💜 by the Orqo team. Zero dependencies. Maximum developer happiness.</sub>
+</p>

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * OrqoClient — Admin-level client for the Orqo Gateway.
+ *
+ * Provides methods for managing instances (create, list, provision)
+ * using the Admin Token. Individual instances are represented by
+ * the OrqoInstance class.
+ */
+import type { OrqoClientConfig, ProvisionOptions, ProvisionResult, InstanceStatus } from './types.js';
+import { OrqoInstance } from './instance.js';
+export declare class OrqoClient {
+    private readonly host;
+    private readonly adminToken;
+    private readonly _fetch;
+    private readonly retry;
+    constructor(config: OrqoClientConfig);
+    private request;
+    /** List all instances. */
+    listInstances(): Promise<InstanceStatus[]>;
+    /**
+     * Quick-Provision: Create an instance, boot WhatsApp, and return QR code
+     * in a single call. Returns an OrqoInstance ready for interaction.
+     */
+    provision(options: ProvisionOptions): Promise<{
+        instance: OrqoInstance;
+        result: ProvisionResult;
+    }>;
+    /**
+     * Get an OrqoInstance handle for an existing instance.
+     * Does NOT validate the instance exists — use listInstances() first.
+     */
+    getInstance(instanceId: string, apiToken: string): OrqoInstance;
+    /**
+     * Delete an instance.
+     */
+    deleteInstance(instanceId: string): Promise<void>;
+    /** Search instances by query string. */
+    searchInstances(query: string): Promise<InstanceStatus[]>;
+    /** Get a single instance by ID (admin detail view). */
+    getInstanceById(instanceId: string): Promise<InstanceStatus>;
+    /** Update instance metadata (name, etc). */
+    updateInstance(instanceId: string, updates: Record<string, unknown>): Promise<InstanceStatus>;
+    /** Get full instance settings. */
+    getInstanceSettings(instanceId: string): Promise<Record<string, unknown>>;
+    /** Update instance settings. */
+    updateInstanceSettings(instanceId: string, settings: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Rotate API token for an instance. Returns the new token. */
+    rotateToken(instanceId: string): Promise<{
+        apiToken: string;
+    }>;
+    /** Delete a contact's data (LGPD/GDPR DSR). */
+    deleteContact(instanceId: string, contactId: string): Promise<void>;
+    /** Generate a full instance configuration using AI. */
+    generateInstanceConfig(config: {
+        instanceName: string;
+        description?: string;
+        context: string;
+        language?: string;
+    }): Promise<Record<string, unknown>>;
+    /** Rotate (re-generate) a secret by key. Returns the new secret value. */
+    rotateSecret(secretKey: string): Promise<{
+        key: string;
+        rotatedAt: string;
+    }>;
+}