orqo-node-sdk 0.1.0

package/dist/instance.js

@@ -0,0 +1,365 @@
+/**
+ * OrqoInstance — Represents a single provisioned instance.
+ *
+ * Provides typed methods for WhatsApp, Agents, Webhooks,
+ * Guardrails, Handoff, and API Bridge — scoped to a specific
+ * instance + API token.
+ */
+import { OrqoError } from './types.js';
+const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    backoffMs: 1000,
+    multiplier: 2,
+    retryOn: [429, 500, 502, 503, 504],
+};
+export class OrqoInstance {
+    instanceId;
+    host;
+    apiToken;
+    _fetch;
+    retry;
+    constructor(config) {
+        this.host = config.host.replace(/\/+$/, '');
+        this.instanceId = config.instanceId;
+        this.apiToken = config.apiToken;
+        this._fetch = config.fetch ?? globalThis.fetch;
+        this.retry = { ...DEFAULT_RETRY, ...config.retry };
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    async request(path, options = {}) {
+        const url = `${this.host}/api/instances/${this.instanceId}${path}`;
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.retry.maxAttempts; attempt++) {
+            if (attempt > 0) {
+                const delay = this.retry.backoffMs * Math.pow(this.retry.multiplier, attempt - 1);
+                await new Promise(r => setTimeout(r, delay));
+            }
+            const res = await this._fetch(url, {
+                ...options,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiToken}`,
+                    ...options.headers,
+                },
+            });
+            if (!res.ok) {
+                const body = await res.json().catch(() => null);
+                lastError = new OrqoError(body?.error ?? `HTTP ${res.status}`, res.status, body);
+                // Only retry on specific status codes
+                if (this.retry.retryOn.includes(res.status) && attempt < this.retry.maxAttempts) {
+                    continue;
+                }
+                throw lastError;
+            }
+            return res.json();
+        }
+        throw lastError ?? new OrqoError('Max retries exceeded', 0);
+    }
+    // --------------------------------------------------------------------------
+    // Instance Status
+    // --------------------------------------------------------------------------
+    /** Get the current status of this instance. */
+    async getStatus() {
+        return this.request('/status');
+    }
+    // --------------------------------------------------------------------------
+    // WhatsApp
+    // --------------------------------------------------------------------------
+    /** Get WhatsApp connection status and QR code (if available). */
+    async getWhatsAppStatus() {
+        return this.request('/whatsapp/status');
+    }
+    /** Start the WhatsApp socket (begins QR code generation). */
+    async connectWhatsApp() {
+        return this.request('/whatsapp/connect', { method: 'POST' });
+    }
+    /** Disconnect WhatsApp. */
+    async disconnectWhatsApp() {
+        await this.request('/whatsapp/disconnect', { method: 'POST' });
+    }
+    /** Request a pairing code for phone-number-based linking. */
+    async pairByPhone(phoneNumber) {
+        return this.request('/whatsapp/pair-by-phone', {
+            method: 'POST',
+            body: JSON.stringify({ phoneNumber }),
+        });
+    }
+    /**
+     * Poll for WhatsApp connection, resolving when connected.
+     *
+     * @param intervalMs - Polling interval in milliseconds (default: 3000)
+     * @param timeoutMs  - Maximum wait time in milliseconds (default: 120000)
+     * @param onQr       - Optional callback invoked each time a new QR is available
+     * @returns The final WhatsApp status (connected)
+     */
+    async waitForConnection(options) {
+        const interval = options?.intervalMs ?? 3000;
+        const timeout = options?.timeoutMs ?? 120_000;
+        const start = Date.now();
+        let lastQr = '';
+        while (Date.now() - start < timeout) {
+            const status = await this.getWhatsAppStatus();
+            if (status.connected || status.state === 'connected') {
+                return status;
+            }
+            if (status.qr && status.qr !== lastQr && options?.onQr) {
+                lastQr = status.qr;
+                options.onQr(status.qr);
+            }
+            await new Promise(r => setTimeout(r, interval));
+        }
+        throw new OrqoError('Connection timeout — QR was not scanned in time', 408);
+    }
+    // --------------------------------------------------------------------------
+    // Messaging
+    // --------------------------------------------------------------------------
+    /** Send a text message via WhatsApp. */
+    async sendMessage(options) {
+        return this.request('/messages/send', {
+            method: 'POST',
+            body: JSON.stringify(options),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Agent CRUD
+    // --------------------------------------------------------------------------
+    /** Create a new agent for this instance. */
+    async createAgent(config) {
+        return this.request('/agents', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    /** List all agents. */
+    async listAgents() {
+        return this.request('/agents');
+    }
+    /** Update an existing agent. */
+    async updateAgent(agentId, updates) {
+        return this.request(`/agents/${agentId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    /** Delete an agent. */
+    async deleteAgent(agentId) {
+        await this.request(`/agents/${agentId}`, { method: 'DELETE' });
+    }
+    // --------------------------------------------------------------------------
+    // Webhook Management
+    // --------------------------------------------------------------------------
+    /** Register a webhook to receive events. */
+    async addWebhook(config) {
+        return this.request('/webhooks', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    /** List all registered webhooks. */
+    async listWebhooks() {
+        return this.request('/webhooks');
+    }
+    /** Remove a webhook. */
+    async removeWebhook(webhookId) {
+        await this.request(`/webhooks/${webhookId}`, { method: 'DELETE' });
+    }
+    // --------------------------------------------------------------------------
+    // Guardrails
+    // --------------------------------------------------------------------------
+    /** Set guardrail configuration for AI responses. */
+    async setGuardrails(config) {
+        return this.request('/guardrails', {
+            method: 'PUT',
+            body: JSON.stringify(config),
+        });
+    }
+    /** Get current guardrail configuration. */
+    async getGuardrails() {
+        return this.request('/guardrails');
+    }
+    // --------------------------------------------------------------------------
+    // Session / Handoff
+    // --------------------------------------------------------------------------
+    /** Hand off a conversation to a human agent. */
+    async handoffToHuman(options) {
+        return this.request(`/sessions/${options.sessionId}/handoff`, {
+            method: 'POST',
+            body: JSON.stringify({
+                reason: options.reason,
+                target: options.target,
+                metadata: options.metadata,
+            }),
+        });
+    }
+    /** Resume bot control of a conversation after human handoff. */
+    async resumeBot(sessionId) {
+        return this.request(`/sessions/${sessionId}/resume`, {
+            method: 'POST',
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Stats & Messages
+    // --------------------------------------------------------------------------
+    /** Get instance statistics (messages, sessions, uptime). */
+    async getStats() {
+        return this.request('/stats');
+    }
+    /** Get conversation sessions with pagination. */
+    async getSessions(options) {
+        const params = new URLSearchParams();
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        if (options?.offset)
+            params.set('offset', String(options.offset));
+        const qs = params.toString();
+        return this.request(`/messages/sessions${qs ? `?${qs}` : ''}`);
+    }
+    /** Get messages for a session or all messages. */
+    async getMessages(options) {
+        const params = new URLSearchParams();
+        if (options?.sessionKey)
+            params.set('sessionKey', options.sessionKey);
+        if (options?.limit)
+            params.set('limit', String(options.limit));
+        const qs = params.toString();
+        return this.request(`/messages${qs ? `?${qs}` : ''}`);
+    }
+    // --------------------------------------------------------------------------
+    // WhatsApp — Extended
+    // --------------------------------------------------------------------------
+    /** Force reconnect WhatsApp (useful for stale connections). */
+    async reconnectWhatsApp() {
+        return this.request('/whatsapp/reconnect', { method: 'POST' });
+    }
+    // --------------------------------------------------------------------------
+    // Agent — Extended
+    // --------------------------------------------------------------------------
+    /** Get a specific agent by ID. */
+    async getAgent(agentId) {
+        return this.request(`/agents/${agentId}`);
+    }
+    // --------------------------------------------------------------------------
+    // Cron Jobs
+    // --------------------------------------------------------------------------
+    /** List cron jobs for this instance. */
+    async listCronJobs() {
+        return this.request('/cron');
+    }
+    /** Create a new cron job. */
+    async createCronJob(config) {
+        return this.request('/cron', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    /** Delete a cron job. */
+    async deleteCronJob(jobId) {
+        await this.request(`/cron/${jobId}`, { method: 'DELETE' });
+    }
+    /** Manually trigger a cron job. */
+    async runCronJob(jobId) {
+        return this.request(`/cron/${jobId}/run`, { method: 'POST' });
+    }
+    // --------------------------------------------------------------------------
+    // API Bridge (Dynamic Tool Integration)
+    // --------------------------------------------------------------------------
+    /**
+     * Connect an external API via OpenAPI spec.
+     * The agent will automatically gain tools from the spec.
+     *
+     * @example
+     * ```ts
+     * await instance.connectApi({
+     *   name: 'comanda-api',
+     *   specUrl: 'https://api.comanda.app/openapi.json',
+     *   auth: { type: 'bearer', token: 'client-key' },
+     * });
+     * ```
+     */
+    async connectApi(options) {
+        return this.request('/api-bridge', {
+            method: 'POST',
+            body: JSON.stringify(options),
+        });
+    }
+    /** List all connected API Bridges. */
+    async listApiBridges() {
+        return this.request('/api-bridge');
+    }
+    /** Remove an API Bridge by ID. */
+    async removeApiBridge(bridgeId) {
+        return this.request(`/api-bridge/${bridgeId}`, { method: 'DELETE' });
+    }
+    /** Refresh an API Bridge (re-fetch OpenAPI spec and update tools). */
+    async refreshApiBridge(bridgeId) {
+        return this.request(`/api-bridge/${bridgeId}/refresh`, { method: 'POST' });
+    }
+    // --------------------------------------------------------------------------
+    // Webhook — Extended
+    // --------------------------------------------------------------------------
+    /** Update an existing webhook configuration. */
+    async updateWebhook(webhookId, updates) {
+        return this.request(`/webhooks/${webhookId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    /** Send a test event to a webhook endpoint. */
+    async testWebhook(webhookId) {
+        return this.request(`/webhooks/${webhookId}/test`, { method: 'POST' });
+    }
+    // --------------------------------------------------------------------------
+    // Cron Jobs — Extended
+    // --------------------------------------------------------------------------
+    /** Update an existing cron job. */
+    async updateCronJob(jobId, updates) {
+        return this.request(`/cron/${jobId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Monitoring — Extended
+    // --------------------------------------------------------------------------
+    /** Get resource limits and current usage. */
+    async getLimits() {
+        return this.request('/limits');
+    }
+    // --------------------------------------------------------------------------
+    // Backup
+    // --------------------------------------------------------------------------
+    /** Create a backup of this instance. */
+    async backup() {
+        return this.request('/backup', { method: 'POST' });
+    }
+    // --------------------------------------------------------------------------
+    // AI Agent Generation
+    // --------------------------------------------------------------------------
+    /** Generate an agent configuration using AI. */
+    async generateAgent(config) {
+        return this.request('/agents/ai/generate', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Background Jobs
+    // --------------------------------------------------------------------------
+    /** List all background jobs for this instance. */
+    async listBackgroundJobs() {
+        return this.request('/background');
+    }
+    /** Get a specific background job by ID. */
+    async getBackgroundJob(jobId) {
+        return this.request(`/background/${jobId}`);
+    }
+    /** Create a new background job. */
+    async createBackgroundJob(config) {
+        return this.request('/background', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Orqo Gateway SDK — Types
+ *
+ * Zero-dependency type definitions for the Orqo REST API.
+ */
+export interface OrqoClientConfig {
+    /** Base URL of the Orqo Gateway (e.g. "https://orqo.example.com") */
+    host: string;
+    /** Admin token for /api/admin/* endpoints */
+    adminToken: string;
+    /** Optional fetch implementation (defaults to globalThis.fetch) */
+    fetch?: typeof fetch;
+    /** Retry configuration for resilience */
+    retry?: RetryConfig;
+}
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial backoff in ms (default: 1000) */
+    backoffMs?: number;
+    /** Backoff multiplier (default: 2) */
+    multiplier?: number;
+    /** HTTP status codes to retry on (default: [429, 500, 502, 503, 504]) */
+    retryOn?: number[];
+}
+export interface OrqoInstanceConfig {
+    /** Base URL of the Orqo Gateway */
+    host: string;
+    /** Instance ID */
+    instanceId: string;
+    /** Instance API token */
+    apiToken: string;
+    /** Optional fetch implementation */
+    fetch?: typeof fetch;
+    /** Retry configuration */
+    retry?: RetryConfig;
+}
+export interface ProvisionOptions {
+    /** Display name for the instance */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Webhook URL to receive events (connection changes, messages) */
+    webhookUrl?: string;
+    /** HMAC secret for webhook signature verification */
+    webhookSecret?: string;
+    /** Additional instance configuration */
+    config?: Record<string, unknown>;
+}
+export interface ProvisionResult {
+    instanceId: string;
+    apiToken: string;
+    whatsapp: WhatsAppStatus;
+}
+export interface WhatsAppStatus {
+    state: 'initializing' | 'waiting-qr' | 'connected' | 'disconnected';
+    qr: string | null;
+    qrRaw: string | null;
+    connected?: boolean;
+    phoneNumber?: string;
+}
+export interface SendMessageOptions {
+    /** Destination JID (e.g. "5511999887766@s.whatsapp.net") */
+    to: string;
+    /** Text content */
+    text: string;
+}
+export interface SendMessageResult {
+    messageId?: string;
+    status: string;
+}
+export interface InstanceStatus {
+    id: string;
+    name: string;
+    connected: boolean;
+    whatsappState?: string;
+    uptime?: number;
+    channels?: Record<string, unknown>;
+}
+export interface AgentConfig {
+    /** Agent ID (auto-generated if not provided) */
+    id?: string;
+    /** Human-readable agent name */
+    name: string;
+    /** Agent type */
+    type?: 'chat' | 'router' | 'specialist';
+    /** System prompt / instructions for the LLM */
+    systemPrompt?: string;
+    /** List of tool names the agent can use */
+    tools?: string[];
+    /** Agent identity */
+    identity?: {
+        displayName?: string;
+        emoji?: string;
+    };
+    /** Routing rules for multi-agent setups */
+    routingRules?: Record<string, unknown>;
+    /** Additional configuration */
+    [key: string]: unknown;
+}
+export interface Agent extends AgentConfig {
+    id: string;
+    createdAt?: number;
+}
+export interface WebhookConfig {
+    /** Destination URL for webhook delivery */
+    url: string;
+    /** HMAC secret for signature verification */
+    secret?: string;
+    /** Event type to listen for */
+    event: string;
+}
+export interface Webhook extends WebhookConfig {
+    id: string;
+}
+export interface GuardrailConfig {
+    /** Content filtering rules */
+    blockedTopics?: string[];
+    /** Maximum response length */
+    maxResponseLength?: number;
+    /** Whether to filter PII from responses */
+    filterPII?: boolean;
+    /** Custom rules */
+    customRules?: Array<{
+        name: string;
+        pattern: string;
+        action: 'block' | 'warn' | 'redact';
+    }>;
+    /** Additional guardrail settings */
+    [key: string]: unknown;
+}
+export interface HandoffOptions {
+    /** Session/conversation ID */
+    sessionId: string;
+    /** Reason for handoff */
+    reason?: string;
+    /** Target human agent/queue */
+    target?: string;
+    /** Metadata to pass to human agent */
+    metadata?: Record<string, unknown>;
+}
+export interface HandoffResult {
+    success: boolean;
+    sessionId: string;
+    status: string;
+}
+export interface WebhookEvent {
+    event: string;
+    instanceId: string;
+    timestamp: number;
+}
+export interface ConnectionChangedEvent extends WebhookEvent {
+    event: 'connection:changed';
+    state: 'connected' | 'disconnected';
+    phoneNumber: string | null;
+}
+export interface MessageReceivedEvent extends WebhookEvent {
+    event: 'message:received';
+    from: string;
+    text: string;
+    messageId: string;
+    isGroup: boolean;
+    pushName?: string;
+}
+export interface MessageProcessedEvent extends WebhookEvent {
+    event: 'message:processed';
+    messageId: string;
+    agentId?: string;
+    response?: string;
+}
+export interface HandoffEvent extends WebhookEvent {
+    event: 'session:handoff';
+    sessionId: string;
+    reason?: string;
+    from: string;
+}
+/** Union of all known webhook events */
+export type OrqoWebhookEvent = ConnectionChangedEvent | MessageReceivedEvent | MessageProcessedEvent | HandoffEvent | WebhookEvent;
+export interface WebhookHandlerOptions {
+    /** HMAC secret for signature verification */
+    secret?: string;
+    /** Called when WhatsApp connection state changes */
+    onConnectionChanged?: (event: ConnectionChangedEvent) => void | Promise<void>;
+    /** Called when a new message is received */
+    onMessageReceived?: (event: MessageReceivedEvent) => void | Promise<void>;
+    /** Called when a message has been processed by the AI */
+    onMessageProcessed?: (event: MessageProcessedEvent) => void | Promise<void>;
+    /** Called when a session is handed off to a human */
+    onHandoff?: (event: HandoffEvent) => void | Promise<void>;
+    /** Catch-all for any event */
+    onEvent?: (event: OrqoWebhookEvent) => void | Promise<void>;
+    /** Called on signature verification failure */
+    onVerificationFailed?: (error: Error) => void;
+}
+export declare class OrqoError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Orqo Gateway SDK — Types
+ *
+ * Zero-dependency type definitions for the Orqo REST API.
+ */
+// ============================================================================
+// Errors
+// ============================================================================
+export class OrqoError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'OrqoError';
+    }
+}

package/dist/webhook-handler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Webhook Handler — Zero-dependency event dispatcher
+ *
+ * Creates a request handler that verifies HMAC signatures
+ * and dispatches typed events to registered callbacks.
+ *
+ * Works with any HTTP framework (Express, Hono, Fastify, etc.)
+ * via a generic interface.
+ *
+ * @example Express
+ * ```ts
+ * import express from 'express';
+ * import { createWebhookHandler } from '@orqo/sdk';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * app.post('/webhooks/orqo', createWebhookHandler({
+ *   secret: 'my-hmac-secret',
+ *   onConnectionChanged: (e) => console.log(`${e.instanceId} → ${e.state}`),
+ *   onMessageReceived: (e) => console.log(`From ${e.from}: ${e.text}`),
+ *   onMessageProcessed: (e) => console.log(`Processed: ${e.messageId}`),
+ *   onHandoff: (e) => console.log(`Handoff: ${e.sessionId}`),
+ * }));
+ * ```
+ */
+import type { WebhookHandlerOptions } from './types.js';
+/**
+ * Generic HTTP request/response interface.
+ * Compatible with Express, Hono, Node http, etc.
+ */
+interface GenericRequest {
+    body?: unknown;
+    headers?: Record<string, string | string[] | undefined> | {
+        get?: (name: string) => string | null;
+    };
+}
+interface GenericResponse {
+    status?: (code: number) => GenericResponse;
+    json?: (data: unknown) => void;
+    writeHead?: (code: number, headers?: Record<string, string>) => void;
+    end?: (data?: string) => void;
+}
+/**
+ * Creates a webhook handler function compatible with Express/Hono/etc.
+ *
+ * The handler:
+ * 1. Verifies the HMAC signature (if secret is configured)
+ * 2. Parses the event
+ * 3. Dispatches to the appropriate typed callback
+ * 4. Returns 200 OK
+ */
+export declare function createWebhookHandler(options: WebhookHandlerOptions): (req: GenericRequest, res: GenericResponse) => Promise<void>;
+export {};