orqo-node-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,174 @@
+/**
+ * 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 { OrqoError } from './types.js';
+import { OrqoInstance } from './instance.js';
+export class OrqoClient {
+    host;
+    adminToken;
+    _fetch;
+    retry;
+    constructor(config) {
+        this.host = config.host.replace(/\/+$/, '');
+        this.adminToken = config.adminToken;
+        this._fetch = config.fetch ?? globalThis.fetch;
+        this.retry = {
+            maxAttempts: 3,
+            backoffMs: 1000,
+            multiplier: 2,
+            retryOn: [429, 500, 502, 503, 504],
+            ...config.retry,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    async request(path, options = {}) {
+        const url = `${this.host}${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.adminToken}`,
+                    ...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 Management
+    // --------------------------------------------------------------------------
+    /** List all instances. */
+    async listInstances() {
+        return this.request('/api/admin/instances');
+    }
+    /**
+     * Quick-Provision: Create an instance, boot WhatsApp, and return QR code
+     * in a single call. Returns an OrqoInstance ready for interaction.
+     */
+    async provision(options) {
+        const result = await this.request('/api/admin/quick-provision', {
+            method: 'POST',
+            body: JSON.stringify(options),
+        });
+        const instance = new OrqoInstance({
+            host: this.host,
+            instanceId: result.instanceId,
+            apiToken: result.apiToken,
+            fetch: this._fetch,
+            retry: this.retry,
+        });
+        return { instance, result };
+    }
+    /**
+     * Get an OrqoInstance handle for an existing instance.
+     * Does NOT validate the instance exists — use listInstances() first.
+     */
+    getInstance(instanceId, apiToken) {
+        return new OrqoInstance({
+            host: this.host,
+            instanceId,
+            apiToken,
+            fetch: this._fetch,
+            retry: this.retry,
+        });
+    }
+    /**
+     * Delete an instance.
+     */
+    async deleteInstance(instanceId) {
+        await this.request(`/api/admin/instances/${instanceId}`, {
+            method: 'DELETE',
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Instance Discovery
+    // --------------------------------------------------------------------------
+    /** Search instances by query string. */
+    async searchInstances(query) {
+        return this.request(`/api/admin/instances/search?q=${encodeURIComponent(query)}`);
+    }
+    /** Get a single instance by ID (admin detail view). */
+    async getInstanceById(instanceId) {
+        return this.request(`/api/admin/instances/${instanceId}`);
+    }
+    /** Update instance metadata (name, etc). */
+    async updateInstance(instanceId, updates) {
+        return this.request(`/api/admin/instances/${instanceId}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Instance Settings
+    // --------------------------------------------------------------------------
+    /** Get full instance settings. */
+    async getInstanceSettings(instanceId) {
+        return this.request(`/api/admin/instances/${instanceId}/settings`);
+    }
+    /** Update instance settings. */
+    async updateInstanceSettings(instanceId, settings) {
+        return this.request(`/api/admin/instances/${instanceId}/settings`, {
+            method: 'PUT',
+            body: JSON.stringify(settings),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Security
+    // --------------------------------------------------------------------------
+    /** Rotate API token for an instance. Returns the new token. */
+    async rotateToken(instanceId) {
+        return this.request(`/api/admin/instances/${instanceId}/rotate-token`, {
+            method: 'POST',
+        });
+    }
+    // --------------------------------------------------------------------------
+    // LGPD / Data Subject Requests
+    // --------------------------------------------------------------------------
+    /** Delete a contact's data (LGPD/GDPR DSR). */
+    async deleteContact(instanceId, contactId) {
+        await this.request(`/api/admin/instances/${instanceId}/dsr/contact/${contactId}`, {
+            method: 'DELETE',
+        });
+    }
+    // --------------------------------------------------------------------------
+    // AI Instance Config Generation
+    // --------------------------------------------------------------------------
+    /** Generate a full instance configuration using AI. */
+    async generateInstanceConfig(config) {
+        return this.request('/api/admin/ai/instance-config', {
+            method: 'POST',
+            body: JSON.stringify(config),
+        });
+    }
+    // --------------------------------------------------------------------------
+    // Secrets Management
+    // --------------------------------------------------------------------------
+    /** Rotate (re-generate) a secret by key. Returns the new secret value. */
+    async rotateSecret(secretKey) {
+        return this.request(`/api/admin/super/secrets/${encodeURIComponent(secretKey)}/rotate`, {
+            method: 'POST',
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @orqo/sdk — Plug-and-Play WhatsApp Integration
+ *
+ * Zero-dependency TypeScript SDK for the Orqo Gateway.
+ *
+ * @example
+ * ```typescript
+ * import { OrqoClient } from '@orqo/sdk';
+ *
+ * const orqo = new OrqoClient({
+ *   host: 'https://orqo.example.com',
+ *   adminToken: 'your-admin-token',
+ * });
+ *
+ * // Provision a new instance with WhatsApp
+ * const { instance, result } = await orqo.provision({
+ *   name: 'My Bot',
+ *   webhookUrl: 'https://your-app.com/webhooks',
+ * });
+ *
+ * // Wait for QR scan (with live QR callback)
+ * await instance.waitForConnection({
+ *   onQr: (qr) => console.log('Scan this QR:', qr),
+ * });
+ *
+ * // Send a message
+ * await instance.sendMessage({
+ *   to: '5511999887766@s.whatsapp.net',
+ *   text: 'Hello from Orqo! 🚀',
+ * });
+ * ```
+ */
+export { OrqoClient } from './client.js';
+export { OrqoInstance } from './instance.js';
+export { createWebhookHandler } from './webhook-handler.js';
+export { OrqoError, type OrqoClientConfig, type OrqoInstanceConfig, type RetryConfig, type ProvisionOptions, type ProvisionResult, type WhatsAppStatus, type SendMessageOptions, type SendMessageResult, type InstanceStatus, type AgentConfig, type Agent, type WebhookConfig, type Webhook, type GuardrailConfig, type HandoffOptions, type HandoffResult, type WebhookEvent, type ConnectionChangedEvent, type MessageReceivedEvent, type MessageProcessedEvent, type HandoffEvent, type OrqoWebhookEvent, type WebhookHandlerOptions, } from './types.js';

package/dist/index.js

@@ -0,0 +1,36 @@
+/**
+ * @orqo/sdk — Plug-and-Play WhatsApp Integration
+ *
+ * Zero-dependency TypeScript SDK for the Orqo Gateway.
+ *
+ * @example
+ * ```typescript
+ * import { OrqoClient } from '@orqo/sdk';
+ *
+ * const orqo = new OrqoClient({
+ *   host: 'https://orqo.example.com',
+ *   adminToken: 'your-admin-token',
+ * });
+ *
+ * // Provision a new instance with WhatsApp
+ * const { instance, result } = await orqo.provision({
+ *   name: 'My Bot',
+ *   webhookUrl: 'https://your-app.com/webhooks',
+ * });
+ *
+ * // Wait for QR scan (with live QR callback)
+ * await instance.waitForConnection({
+ *   onQr: (qr) => console.log('Scan this QR:', qr),
+ * });
+ *
+ * // Send a message
+ * await instance.sendMessage({
+ *   to: '5511999887766@s.whatsapp.net',
+ *   text: 'Hello from Orqo! 🚀',
+ * });
+ * ```
+ */
+export { OrqoClient } from './client.js';
+export { OrqoInstance } from './instance.js';
+export { createWebhookHandler } from './webhook-handler.js';
+export { OrqoError, } from './types.js';

package/dist/instance.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 type { OrqoInstanceConfig, WhatsAppStatus, SendMessageOptions, SendMessageResult, InstanceStatus, AgentConfig, Agent, WebhookConfig, Webhook, GuardrailConfig, HandoffOptions, HandoffResult } from './types.js';
+export declare class OrqoInstance {
+    readonly instanceId: string;
+    private readonly host;
+    private readonly apiToken;
+    private readonly _fetch;
+    private readonly retry;
+    constructor(config: OrqoInstanceConfig);
+    private request;
+    /** Get the current status of this instance. */
+    getStatus(): Promise<InstanceStatus>;
+    /** Get WhatsApp connection status and QR code (if available). */
+    getWhatsAppStatus(): Promise<WhatsAppStatus>;
+    /** Start the WhatsApp socket (begins QR code generation). */
+    connectWhatsApp(): Promise<InstanceStatus>;
+    /** Disconnect WhatsApp. */
+    disconnectWhatsApp(): Promise<void>;
+    /** Request a pairing code for phone-number-based linking. */
+    pairByPhone(phoneNumber: string): Promise<{
+        code: string;
+    }>;
+    /**
+     * 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)
+     */
+    waitForConnection(options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onQr?: (qr: string) => void;
+    }): Promise<WhatsAppStatus>;
+    /** Send a text message via WhatsApp. */
+    sendMessage(options: SendMessageOptions): Promise<SendMessageResult>;
+    /** Create a new agent for this instance. */
+    createAgent(config: AgentConfig): Promise<Agent>;
+    /** List all agents. */
+    listAgents(): Promise<Agent[]>;
+    /** Update an existing agent. */
+    updateAgent(agentId: string, updates: Partial<AgentConfig>): Promise<Agent>;
+    /** Delete an agent. */
+    deleteAgent(agentId: string): Promise<void>;
+    /** Register a webhook to receive events. */
+    addWebhook(config: WebhookConfig): Promise<Webhook>;
+    /** List all registered webhooks. */
+    listWebhooks(): Promise<Webhook[]>;
+    /** Remove a webhook. */
+    removeWebhook(webhookId: string): Promise<void>;
+    /** Set guardrail configuration for AI responses. */
+    setGuardrails(config: GuardrailConfig): Promise<GuardrailConfig>;
+    /** Get current guardrail configuration. */
+    getGuardrails(): Promise<GuardrailConfig>;
+    /** Hand off a conversation to a human agent. */
+    handoffToHuman(options: HandoffOptions): Promise<HandoffResult>;
+    /** Resume bot control of a conversation after human handoff. */
+    resumeBot(sessionId: string): Promise<HandoffResult>;
+    /** Get instance statistics (messages, sessions, uptime). */
+    getStats(): Promise<Record<string, unknown>>;
+    /** Get conversation sessions with pagination. */
+    getSessions(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Array<Record<string, unknown>>>;
+    /** Get messages for a session or all messages. */
+    getMessages(options?: {
+        sessionKey?: string;
+        limit?: number;
+    }): Promise<Array<Record<string, unknown>>>;
+    /** Force reconnect WhatsApp (useful for stale connections). */
+    reconnectWhatsApp(): Promise<InstanceStatus>;
+    /** Get a specific agent by ID. */
+    getAgent(agentId: string): Promise<Agent>;
+    /** List cron jobs for this instance. */
+    listCronJobs(): Promise<Array<Record<string, unknown>>>;
+    /** Create a new cron job. */
+    createCronJob(config: {
+        schedule: string;
+        action: string;
+        payload?: Record<string, unknown>;
+    }): Promise<Record<string, unknown>>;
+    /** Delete a cron job. */
+    deleteCronJob(jobId: string): Promise<void>;
+    /** Manually trigger a cron job. */
+    runCronJob(jobId: string): Promise<Record<string, unknown>>;
+    /**
+     * 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' },
+     * });
+     * ```
+     */
+    connectApi(options: {
+        name: string;
+        specUrl?: string;
+        specInline?: Record<string, unknown>;
+        auth?: {
+            type: 'bearer' | 'apiKey' | 'basic' | 'custom';
+            token?: string;
+            headerName?: string;
+            username?: string;
+            password?: string;
+            headers?: Record<string, string>;
+        };
+        baseUrl?: string;
+        timeoutMs?: number;
+        refreshIntervalMs?: number;
+        description?: string;
+    }): Promise<{
+        bridge: Record<string, unknown>;
+        tools: string[];
+    }>;
+    /** List all connected API Bridges. */
+    listApiBridges(): Promise<Array<Record<string, unknown> & {
+        tools: string[];
+    }>>;
+    /** Remove an API Bridge by ID. */
+    removeApiBridge(bridgeId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Refresh an API Bridge (re-fetch OpenAPI spec and update tools). */
+    refreshApiBridge(bridgeId: string): Promise<{
+        bridge: Record<string, unknown>;
+        tools: string[];
+    }>;
+    /** Update an existing webhook configuration. */
+    updateWebhook(webhookId: string, updates: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Send a test event to a webhook endpoint. */
+    testWebhook(webhookId: string): Promise<Record<string, unknown>>;
+    /** Update an existing cron job. */
+    updateCronJob(jobId: string, updates: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Get resource limits and current usage. */
+    getLimits(): Promise<Record<string, unknown>>;
+    /** Create a backup of this instance. */
+    backup(): Promise<Record<string, unknown>>;
+    /** Generate an agent configuration using AI. */
+    generateAgent(config: {
+        name: string;
+        description: string;
+        context: string;
+        language?: string;
+    }): Promise<Agent>;
+    /** List all background jobs for this instance. */
+    listBackgroundJobs(): Promise<Record<string, unknown>[]>;
+    /** Get a specific background job by ID. */
+    getBackgroundJob(jobId: string): Promise<Record<string, unknown>>;
+    /** Create a new background job. */
+    createBackgroundJob(config: {
+        agentId: string;
+        input: string;
+    }): Promise<Record<string, unknown>>;
+}