orqo-node-sdk 0.1.0 → 0.2.0

package/README.md

@@ -43,7 +43,7 @@
 ## 📦 Installation
 
 ```bash
-npm install @orqo/sdk
+npm install orqo-node-sdk
 ```
 
 > **Requirements:** Node.js 18+ (or any runtime with `globalThis.fetch`)
@@ -55,7 +55,7 @@ npm install @orqo/sdk
 ### 1. Provision an Instance
 
 ```typescript
-import { OrqoClient } from '@orqo/sdk';
+import { OrqoClient } from 'orqo-node-sdk';
 
 const orqo = new OrqoClient({
   host: 'https://gateway.orqo.ai',
@@ -95,7 +95,7 @@ await instance.sendMessage({
 ### 4. Receive Events
 
 ```typescript
-import { createWebhookHandler } from '@orqo/sdk';
+import { createWebhookHandler } from 'orqo-node-sdk';
 
 app.post('/webhooks/orqo', createWebhookHandler({
   secret: process.env.WEBHOOK_SECRET,
@@ -219,7 +219,7 @@ The `createWebhookHandler()` function provides a framework-agnostic webhook rece
 
 ```typescript
 import express from 'express';
-import { createWebhookHandler } from '@orqo/sdk';
+import { createWebhookHandler } from 'orqo-node-sdk';
 
 const app = express();
 app.use(express.json());
@@ -252,7 +252,7 @@ app.post('/webhooks/orqo', createWebhookHandler({
 
 ```typescript
 import { Hono } from 'hono';
-import { createWebhookHandler } from '@orqo/sdk';
+import { createWebhookHandler } from 'orqo-node-sdk';
 
 const app = new Hono();
 
@@ -366,7 +366,7 @@ Attempt 4 → wait 4000ms  (if maxAttempts > 3)
 ## 🤝 Complete Workflow Example
 
 ```typescript
-import { OrqoClient, createWebhookHandler } from '@orqo/sdk';
+import { OrqoClient, createWebhookHandler } from 'orqo-node-sdk';
 import express from 'express';
 
 // ── 1. Setup ─────────────────────────────────────────────
@@ -441,7 +441,7 @@ app.listen(3000, () => console.log('🚀 Running on :3000'));
 
 ```
 ┌──────────────────────────────────────────────────────────────┐
-│                        @orqo/sdk                             │
+│                      orqo-node-sdk                           │
 ├──────────────┬─────────────────┬─────────────────────────────┤
 │  OrqoClient  │  OrqoInstance   │  createWebhookHandler()     │
 │  (Admin)     │  (Per-instance) │  (Event receiver)           │
@@ -518,7 +518,7 @@ import type {
   HandoffEvent,
   OrqoWebhookEvent,
   WebhookHandlerOptions,
-} from '@orqo/sdk';
+} from 'orqo-node-sdk';
 ```
 
 ---

package/dist/builders.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Orqo SDK — Fluent Builders
+ *
+ * Builder pattern classes that provide a chainable, ergonomic API
+ * for complex configuration objects. These are convenience wrappers —
+ * the underlying raw config objects remain fully supported.
+ *
+ * @example
+ * ```typescript
+ * // Fluent Agent creation
+ * const agent = await instance
+ *     .agent('Atendente')
+ *     .prompt('Você é um atendente educado.')
+ *     .tools('search', 'calendar')
+ *     .identity('Ana', '👩‍💼')
+ *     .create();
+ *
+ * // Fluent Provisioning
+ * const instance = await orqo
+ *     .provision('Pizzaria do Zé')
+ *     .withLLM('openai', 'gpt-4o-mini', process.env.OPENAI_KEY!)
+ *     .withWebhook('https://api.example.com/events')
+ *     .withTelegram(process.env.TG_BOT_TOKEN!)
+ *     .execute();
+ * ```
+ */
+import type { AgentConfig, Agent, ProvisionOptions, ProvisionResult, WebhookConfig } from './types.js';
+import type { OrqoInstance } from './instance.js';
+import type { AgentTypeValue, LLMProviderType } from './constants.js';
+export declare class AgentBuilder {
+    private config;
+    private readonly _instance;
+    constructor(instance: OrqoInstance, name: string);
+    /** Set the agent type (default: 'chat'). */
+    type(type: AgentTypeValue): this;
+    /** Set the system prompt / instructions. */
+    prompt(systemPrompt: string): this;
+    /** Set the agent's custom ID. */
+    id(id: string): this;
+    /** Add tools the agent can use. */
+    tools(...toolNames: string[]): this;
+    /** Set the agent identity (display name + emoji). */
+    identity(displayName: string, emoji?: string): this;
+    /** Set routing rules (for router agents). */
+    routing(rules: Record<string, unknown>): this;
+    /** Set the fallback agent ID (for router agents). */
+    fallback(agentId: string): this;
+    /** Set any additional configuration property. */
+    set(key: string, value: unknown): this;
+    /** Build the raw config object without creating the agent. */
+    build(): AgentConfig;
+    /** Create the agent on the server. */
+    create(): Promise<Agent>;
+}
+export declare class ProvisionBuilder {
+    private options;
+    private readonly _client;
+    private _agents;
+    private _webhooks;
+    constructor(client: {
+        _doProvision(options: ProvisionOptions): Promise<{
+            instance: OrqoInstance;
+            result: ProvisionResult;
+        }>;
+    }, name: string);
+    /** Set instance description. */
+    description(desc: string): this;
+    /** Configure the LLM provider for this instance. */
+    withLLM(provider: LLMProviderType, model: string, apiKey: string): this;
+    /** Add a Telegram bot channel. */
+    withTelegram(botToken: string, webhookSecret?: string): this;
+    /** Queue an agent to be created after provisioning. */
+    withAgent(name: string, systemPrompt?: string): this;
+    /** Queue a webhook to be registered after provisioning. */
+    withWebhook(urlOrConfig: string | WebhookConfig): this;
+    /** Set the webhook URL for instance-level connection events. */
+    onEvents(webhookUrl: string, secret?: string): this;
+    /** Add arbitrary config. */
+    withConfig(config: Record<string, unknown>): this;
+    /** Build the raw options object without provisioning. */
+    build(): ProvisionOptions;
+    /**
+     * Execute provisioning and all queued setup steps.
+     * Returns the ready-to-use OrqoInstance.
+     */
+    execute(): Promise<{
+        instance: OrqoInstance;
+        result: ProvisionResult;
+        agents: Agent[];
+        webhooks: unknown[];
+    }>;
+}

package/dist/builders.js

@@ -0,0 +1,161 @@
+/**
+ * Orqo SDK — Fluent Builders
+ *
+ * Builder pattern classes that provide a chainable, ergonomic API
+ * for complex configuration objects. These are convenience wrappers —
+ * the underlying raw config objects remain fully supported.
+ *
+ * @example
+ * ```typescript
+ * // Fluent Agent creation
+ * const agent = await instance
+ *     .agent('Atendente')
+ *     .prompt('Você é um atendente educado.')
+ *     .tools('search', 'calendar')
+ *     .identity('Ana', '👩‍💼')
+ *     .create();
+ *
+ * // Fluent Provisioning
+ * const instance = await orqo
+ *     .provision('Pizzaria do Zé')
+ *     .withLLM('openai', 'gpt-4o-mini', process.env.OPENAI_KEY!)
+ *     .withWebhook('https://api.example.com/events')
+ *     .withTelegram(process.env.TG_BOT_TOKEN!)
+ *     .execute();
+ * ```
+ */
+// ============================================================================
+// Agent Builder
+// ============================================================================
+export class AgentBuilder {
+    config;
+    _instance;
+    constructor(instance, name) {
+        this._instance = instance;
+        this.config = { name };
+    }
+    /** Set the agent type (default: 'chat'). */
+    type(type) {
+        this.config.type = type;
+        return this;
+    }
+    /** Set the system prompt / instructions. */
+    prompt(systemPrompt) {
+        this.config.systemPrompt = systemPrompt;
+        return this;
+    }
+    /** Set the agent's custom ID. */
+    id(id) {
+        this.config.id = id;
+        return this;
+    }
+    /** Add tools the agent can use. */
+    tools(...toolNames) {
+        this.config.tools = [...(this.config.tools || []), ...toolNames];
+        return this;
+    }
+    /** Set the agent identity (display name + emoji). */
+    identity(displayName, emoji) {
+        this.config.identity = { displayName, emoji };
+        return this;
+    }
+    /** Set routing rules (for router agents). */
+    routing(rules) {
+        this.config.routingRules = rules;
+        return this;
+    }
+    /** Set the fallback agent ID (for router agents). */
+    fallback(agentId) {
+        this.config.defaultAgentId = agentId;
+        return this;
+    }
+    /** Set any additional configuration property. */
+    set(key, value) {
+        this.config[key] = value;
+        return this;
+    }
+    /** Build the raw config object without creating the agent. */
+    build() {
+        return { ...this.config };
+    }
+    /** Create the agent on the server. */
+    async create() {
+        return this._instance.createAgent(this.config);
+    }
+}
+// ============================================================================
+// Provision Builder
+// ============================================================================
+export class ProvisionBuilder {
+    options;
+    _client;
+    _agents = [];
+    _webhooks = [];
+    constructor(client, name) {
+        this._client = client;
+        this.options = { name };
+    }
+    /** Set instance description. */
+    description(desc) {
+        this.options.description = desc;
+        return this;
+    }
+    /** Configure the LLM provider for this instance. */
+    withLLM(provider, model, apiKey) {
+        this.options.llm = { provider, model, apiKey };
+        return this;
+    }
+    /** Add a Telegram bot channel. */
+    withTelegram(botToken, webhookSecret) {
+        this.options.telegram = { botToken, webhookSecret };
+        return this;
+    }
+    /** Queue an agent to be created after provisioning. */
+    withAgent(name, systemPrompt) {
+        const config = { name };
+        if (systemPrompt)
+            config.systemPrompt = systemPrompt;
+        this._agents.push(config);
+        return this;
+    }
+    /** Queue a webhook to be registered after provisioning. */
+    withWebhook(urlOrConfig) {
+        this._webhooks.push(urlOrConfig);
+        return this;
+    }
+    /** Set the webhook URL for instance-level connection events. */
+    onEvents(webhookUrl, secret) {
+        this.options.webhookUrl = webhookUrl;
+        if (secret)
+            this.options.webhookSecret = secret;
+        return this;
+    }
+    /** Add arbitrary config. */
+    withConfig(config) {
+        this.options.config = { ...this.options.config, ...config };
+        return this;
+    }
+    /** Build the raw options object without provisioning. */
+    build() {
+        return { ...this.options };
+    }
+    /**
+     * Execute provisioning and all queued setup steps.
+     * Returns the ready-to-use OrqoInstance.
+     */
+    async execute() {
+        // Step 1: Provision
+        const { instance, result } = await this._client._doProvision(this.options);
+        // Step 2: Create queued agents
+        const agents = [];
+        for (const agentConfig of this._agents) {
+            agents.push(await instance.createAgent(agentConfig));
+        }
+        // Step 3: Register queued webhooks
+        const webhooks = [];
+        for (const wh of this._webhooks) {
+            webhooks.push(await instance.addWebhook(wh));
+        }
+        return { instance, result, agents, webhooks };
+    }
+}

package/dist/client.d.ts

@@ -7,23 +7,65 @@
  */
 import type { OrqoClientConfig, ProvisionOptions, ProvisionResult, InstanceStatus } from './types.js';
 import { OrqoInstance } from './instance.js';
+import { ProvisionBuilder } from './builders.js';
 export declare class OrqoClient {
     private readonly host;
     private readonly adminToken;
     private readonly _fetch;
     private readonly retry;
     constructor(config: OrqoClientConfig);
+    /**
+     * Create an OrqoClient from environment variables.
+     *
+     * Reads `ORQO_HOST` and `ORQO_ADMIN_TOKEN` from `process.env`.
+     * Throws a clear error if required variables are missing.
+     *
+     * @param overrides - Partial config to override env values
+     *
+     * @example
+     * ```typescript
+     * // Reads from .env automatically
+     * const orqo = OrqoClient.fromEnv();
+     *
+     * // Override host for local development
+     * const orqo = OrqoClient.fromEnv({ host: 'http://localhost:3001' });
+     * ```
+     */
+    static fromEnv(overrides?: Partial<OrqoClientConfig>): OrqoClient;
     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.
+     *
+     * Accepts a name string (returns a ProvisionBuilder for fluent chaining)
+     * or a full ProvisionOptions object (returns directly).
+     *
+     * @example
+     * ```typescript
+     * // Fluent builder
+     * const { instance } = await orqo
+     *     .provision('Pizzaria do Zé')
+     *     .withLLM('openai', 'gpt-4o-mini', process.env.OPENAI_KEY!)
+     *     .withAgent('Atendente', 'Você atende pedidos.')
+     *     .withWebhook('https://api.example.com/events')
+     *     .execute();
+     *
+     * // Direct (classic)
+     * const { instance } = await orqo.provision({ name: 'My Bot' });
+     * ```
      */
+    provision(name: string): ProvisionBuilder;
     provision(options: ProvisionOptions): Promise<{
         instance: OrqoInstance;
         result: ProvisionResult;
     }>;
+    /** @internal Performs the actual provisioning request. */
+    _doProvision(options: ProvisionOptions): Promise<{
+        instance: OrqoInstance;
+        result: ProvisionResult;
+    }>;
     /**
      * Get an OrqoInstance handle for an existing instance.
      * Does NOT validate the instance exists — use listInstances() first.

package/dist/client.js

@@ -7,6 +7,7 @@
  */
 import { OrqoError } from './types.js';
 import { OrqoInstance } from './instance.js';
+import { ProvisionBuilder } from './builders.js';
 export class OrqoClient {
     host;
     adminToken;
@@ -25,6 +26,41 @@ export class OrqoClient {
         };
     }
     // --------------------------------------------------------------------------
+    // Static Factory
+    // --------------------------------------------------------------------------
+    /**
+     * Create an OrqoClient from environment variables.
+     *
+     * Reads `ORQO_HOST` and `ORQO_ADMIN_TOKEN` from `process.env`.
+     * Throws a clear error if required variables are missing.
+     *
+     * @param overrides - Partial config to override env values
+     *
+     * @example
+     * ```typescript
+     * // Reads from .env automatically
+     * const orqo = OrqoClient.fromEnv();
+     *
+     * // Override host for local development
+     * const orqo = OrqoClient.fromEnv({ host: 'http://localhost:3001' });
+     * ```
+     */
+    static fromEnv(overrides) {
+        const host = overrides?.host || process.env.ORQO_HOST;
+        const adminToken = overrides?.adminToken || process.env.ORQO_ADMIN_TOKEN;
+        if (!host) {
+            throw new OrqoError('ORQO_HOST environment variable is required. Set it or pass { host } to fromEnv().', 0);
+        }
+        if (!adminToken) {
+            throw new OrqoError('ORQO_ADMIN_TOKEN environment variable is required. Set it or pass { adminToken } to fromEnv().', 0);
+        }
+        return new OrqoClient({
+            host,
+            adminToken,
+            ...overrides,
+        });
+    }
+    // --------------------------------------------------------------------------
     // Private helpers
     // --------------------------------------------------------------------------
     async request(path, options = {}) {
@@ -63,11 +99,14 @@ export class OrqoClient {
     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) {
+    provision(nameOrOptions) {
+        if (typeof nameOrOptions === 'string') {
+            return new ProvisionBuilder(this, nameOrOptions);
+        }
+        return this._doProvision(nameOrOptions);
+    }
+    /** @internal Performs the actual provisioning request. */
+    async _doProvision(options) {
         const result = await this.request('/api/admin/quick-provision', {
             method: 'POST',
             body: JSON.stringify(options),

package/dist/constants.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Orqo SDK — Constants
+ *
+ * Typed enum-like constants for common configuration values.
+ * These provide IDE autocomplete and documentation while still
+ * accepting any string value for extensibility.
+ *
+ * @example
+ * ```typescript
+ * import { Events, LLMProvider } from 'orqo-node-sdk';
+ *
+ * // Use constants for autocomplete
+ * await instance.addWebhook({
+ *     url: 'https://my-api.com/hook',
+ *     events: [Events.MESSAGE_RECEIVED],
+ * });
+ *
+ * // Or use free-form strings
+ * await instance.addWebhook({
+ *     url: 'https://my-api.com/hook',
+ *     events: ['my.custom.event'],
+ * });
+ * ```
+ */
+/** Well-known webhook event types. Custom event strings are also accepted. */
+export declare const Events: {
+    /** A new message was received from a contact */
+    readonly MESSAGE_RECEIVED: "message.received";
+    /** A message was sent to a contact */
+    readonly MESSAGE_SENT: "message.sent";
+    /** A message was processed by the AI agent */
+    readonly MESSAGE_PROCESSED: "message.processed";
+    /** A session was handed off to a human operator */
+    readonly SESSION_HANDOFF: "session.handoff";
+    /** WhatsApp connection state changed */
+    readonly CONNECTION_CHANGED: "connection.changed";
+    /** A new contact was created */
+    readonly CONTACT_CREATED: "contact.created";
+    /** A contact was updated */
+    readonly CONTACT_UPDATED: "contact.updated";
+};
+/** Type for event values — accepts constants or custom string */
+export type EventType = typeof Events[keyof typeof Events] | (string & {});
+/** Default events used when none are specified */
+export declare const DEFAULT_WEBHOOK_EVENTS: EventType[];
+/** Well-known LLM provider identifiers. Custom provider strings are also accepted. */
+export declare const LLMProvider: {
+    readonly OPENAI: "openai";
+    readonly GEMINI: "gemini";
+    readonly ANTHROPIC: "anthropic";
+    readonly GROQ: "groq";
+    readonly DEEPSEEK: "deepseek";
+    readonly OLLAMA: "ollama";
+};
+/** Type for provider values — accepts constants or custom string */
+export type LLMProviderType = typeof LLMProvider[keyof typeof LLMProvider] | (string & {});
+/** Well-known agent types. */
+export declare const AgentType: {
+    /** Standard conversational agent */
+    readonly CHAT: "chat";
+    /** Routes messages to specialized agents */
+    readonly ROUTER: "router";
+    /** Domain-specific specialist agent */
+    readonly SPECIALIST: "specialist";
+};
+/** Type for agent type values — accepts constants or custom string */
+export type AgentTypeValue = typeof AgentType[keyof typeof AgentType] | (string & {});
+/** Well-known WhatsApp connection states. */
+export declare const WhatsAppState: {
+    readonly INITIALIZING: "initializing";
+    readonly WAITING_QR: "waiting-qr";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+};
+/** Actions for custom guardrail rules. */
+export declare const GuardrailAction: {
+    readonly BLOCK: "block";
+    readonly WARN: "warn";
+    readonly REDACT: "redact";
+};

package/dist/constants.js

@@ -0,0 +1,94 @@
+/**
+ * Orqo SDK — Constants
+ *
+ * Typed enum-like constants for common configuration values.
+ * These provide IDE autocomplete and documentation while still
+ * accepting any string value for extensibility.
+ *
+ * @example
+ * ```typescript
+ * import { Events, LLMProvider } from 'orqo-node-sdk';
+ *
+ * // Use constants for autocomplete
+ * await instance.addWebhook({
+ *     url: 'https://my-api.com/hook',
+ *     events: [Events.MESSAGE_RECEIVED],
+ * });
+ *
+ * // Or use free-form strings
+ * await instance.addWebhook({
+ *     url: 'https://my-api.com/hook',
+ *     events: ['my.custom.event'],
+ * });
+ * ```
+ */
+// ============================================================================
+// Webhook Events
+// ============================================================================
+/** Well-known webhook event types. Custom event strings are also accepted. */
+export const Events = {
+    /** A new message was received from a contact */
+    MESSAGE_RECEIVED: 'message.received',
+    /** A message was sent to a contact */
+    MESSAGE_SENT: 'message.sent',
+    /** A message was processed by the AI agent */
+    MESSAGE_PROCESSED: 'message.processed',
+    /** A session was handed off to a human operator */
+    SESSION_HANDOFF: 'session.handoff',
+    /** WhatsApp connection state changed */
+    CONNECTION_CHANGED: 'connection.changed',
+    /** A new contact was created */
+    CONTACT_CREATED: 'contact.created',
+    /** A contact was updated */
+    CONTACT_UPDATED: 'contact.updated',
+};
+/** Default events used when none are specified */
+export const DEFAULT_WEBHOOK_EVENTS = [
+    Events.MESSAGE_RECEIVED,
+    Events.MESSAGE_SENT,
+    Events.MESSAGE_PROCESSED,
+    Events.SESSION_HANDOFF,
+];
+// ============================================================================
+// LLM Providers
+// ============================================================================
+/** Well-known LLM provider identifiers. Custom provider strings are also accepted. */
+export const LLMProvider = {
+    OPENAI: 'openai',
+    GEMINI: 'gemini',
+    ANTHROPIC: 'anthropic',
+    GROQ: 'groq',
+    DEEPSEEK: 'deepseek',
+    OLLAMA: 'ollama',
+};
+// ============================================================================
+// Agent Types
+// ============================================================================
+/** Well-known agent types. */
+export const AgentType = {
+    /** Standard conversational agent */
+    CHAT: 'chat',
+    /** Routes messages to specialized agents */
+    ROUTER: 'router',
+    /** Domain-specific specialist agent */
+    SPECIALIST: 'specialist',
+};
+// ============================================================================
+// WhatsApp States
+// ============================================================================
+/** Well-known WhatsApp connection states. */
+export const WhatsAppState = {
+    INITIALIZING: 'initializing',
+    WAITING_QR: 'waiting-qr',
+    CONNECTED: 'connected',
+    DISCONNECTED: 'disconnected',
+};
+// ============================================================================
+// Guardrail Actions
+// ============================================================================
+/** Actions for custom guardrail rules. */
+export const GuardrailAction = {
+    BLOCK: 'block',
+    WARN: 'warn',
+    REDACT: 'redact',
+};

package/dist/index.d.ts

@@ -1,36 +1,38 @@
 /**
- * @orqo/sdk — Plug-and-Play WhatsApp Integration
+ * orqo-node-sdk — Plug-and-Play WhatsApp + AI Agent Integration
  *
  * Zero-dependency TypeScript SDK for the Orqo Gateway.
  *
  * @example
  * ```typescript
- * import { OrqoClient } from '@orqo/sdk';
+ * import { OrqoClient, Events, LLMProvider } from 'orqo-node-sdk';
  *
- * const orqo = new OrqoClient({
- *   host: 'https://orqo.example.com',
- *   adminToken: 'your-admin-token',
- * });
+ * // Quick start from environment variables
+ * const orqo = OrqoClient.fromEnv();
  *
- * // Provision a new instance with WhatsApp
- * const { instance, result } = await orqo.provision({
- *   name: 'My Bot',
- *   webhookUrl: 'https://your-app.com/webhooks',
- * });
+ * // Fluent provisioning with builder pattern
+ * const { instance } = await orqo
+ *     .provision('My Restaurant')
+ *     .withLLM(LLMProvider.OPENAI, 'gpt-4o-mini', process.env.OPENAI_KEY!)
+ *     .withAgent('Atendente', 'Você é um atendente educado.')
+ *     .withWebhook('https://my-api.com/events')
+ *     .execute();
  *
- * // Wait for QR scan (with live QR callback)
- * await instance.waitForConnection({
- *   onQr: (qr) => console.log('Scan this QR:', qr),
- * });
+ * // Send a message (auto-formats phone to JID)
+ * await instance.send('5511999887766', 'Hello from Orqo! 🚀');
  *
- * // Send a message
- * await instance.sendMessage({
- *   to: '5511999887766@s.whatsapp.net',
- *   text: 'Hello from Orqo! 🚀',
- * });
+ * // Build agents fluently
+ * await instance
+ *     .agent('Specialist')
+ *     .prompt('You handle refunds.')
+ *     .tools('refund_tool', 'lookup_order')
+ *     .identity('Carlos', '🧑‍💻')
+ *     .create();
  * ```
  */
 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';
+export { AgentBuilder, ProvisionBuilder } from './builders.js';
+export { Events, LLMProvider, AgentType, WhatsAppState, GuardrailAction, DEFAULT_WEBHOOK_EVENTS, type EventType, type LLMProviderType, type AgentTypeValue, } from './constants.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, type InstanceStats, type CronJob, type BackgroundJob, type InstanceLimits, type SessionInfo, type MessageRecord, } from './types.js';

package/dist/index.js

@@ -1,36 +1,42 @@
 /**
- * @orqo/sdk — Plug-and-Play WhatsApp Integration
+ * orqo-node-sdk — Plug-and-Play WhatsApp + AI Agent Integration
  *
  * Zero-dependency TypeScript SDK for the Orqo Gateway.
  *
  * @example
  * ```typescript
- * import { OrqoClient } from '@orqo/sdk';
+ * import { OrqoClient, Events, LLMProvider } from 'orqo-node-sdk';
  *
- * const orqo = new OrqoClient({
- *   host: 'https://orqo.example.com',
- *   adminToken: 'your-admin-token',
- * });
+ * // Quick start from environment variables
+ * const orqo = OrqoClient.fromEnv();
  *
- * // Provision a new instance with WhatsApp
- * const { instance, result } = await orqo.provision({
- *   name: 'My Bot',
- *   webhookUrl: 'https://your-app.com/webhooks',
- * });
+ * // Fluent provisioning with builder pattern
+ * const { instance } = await orqo
+ *     .provision('My Restaurant')
+ *     .withLLM(LLMProvider.OPENAI, 'gpt-4o-mini', process.env.OPENAI_KEY!)
+ *     .withAgent('Atendente', 'Você é um atendente educado.')
+ *     .withWebhook('https://my-api.com/events')
+ *     .execute();
  *
- * // Wait for QR scan (with live QR callback)
- * await instance.waitForConnection({
- *   onQr: (qr) => console.log('Scan this QR:', qr),
- * });
+ * // Send a message (auto-formats phone to JID)
+ * await instance.send('5511999887766', 'Hello from Orqo! 🚀');
  *
- * // Send a message
- * await instance.sendMessage({
- *   to: '5511999887766@s.whatsapp.net',
- *   text: 'Hello from Orqo! 🚀',
- * });
+ * // Build agents fluently
+ * await instance
+ *     .agent('Specialist')
+ *     .prompt('You handle refunds.')
+ *     .tools('refund_tool', 'lookup_order')
+ *     .identity('Carlos', '🧑‍💻')
+ *     .create();
  * ```
  */
+// Core classes
 export { OrqoClient } from './client.js';
 export { OrqoInstance } from './instance.js';
 export { createWebhookHandler } from './webhook-handler.js';
+// Fluent builders
+export { AgentBuilder, ProvisionBuilder } from './builders.js';
+// Constants (enum-like, with string escape hatches)
+export { Events, LLMProvider, AgentType, WhatsAppState, GuardrailAction, DEFAULT_WEBHOOK_EVENTS, } from './constants.js';
+// Type exports
 export { OrqoError, } from './types.js';

package/dist/instance.d.ts

@@ -5,7 +5,8 @@
  * 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';
+import type { OrqoInstanceConfig, WhatsAppStatus, SendMessageOptions, SendMessageResult, InstanceStatus, AgentConfig, Agent, WebhookConfig, Webhook, GuardrailConfig, HandoffOptions, HandoffResult, InstanceStats, CronJob, BackgroundJob, InstanceLimits, SessionInfo, MessageRecord } from './types.js';
+import { AgentBuilder } from './builders.js';
 export declare class OrqoInstance {
     readonly instanceId: string;
     private readonly host;
@@ -39,18 +40,66 @@ export declare class OrqoInstance {
         timeoutMs?: number;
         onQr?: (qr: string) => void;
     }): Promise<WhatsAppStatus>;
-    /** Send a text message via WhatsApp. */
+    /** Send a text message via WhatsApp (full options). */
     sendMessage(options: SendMessageOptions): Promise<SendMessageResult>;
+    /**
+     * Send a message with automatic JID formatting.
+     *
+     * @param phone - Phone number (e.g. "5511999887766") or full JID
+     * @param text  - Text content to send
+     * @param opts  - Optional extra parameters
+     *
+     * @example
+     * ```typescript
+     * // Simple — phone number auto-formatted to JID
+     * await instance.send('5511999887766', 'Seu pedido saiu!');
+     *
+     * // With options
+     * await instance.send('5511999887766', 'Confira!', { quotedMessageId: 'msg123' });
+     * ```
+     */
+    send(phone: string, text: string, opts?: Record<string, unknown>): Promise<SendMessageResult>;
     /** Create a new agent for this instance. */
     createAgent(config: AgentConfig): Promise<Agent>;
+    /**
+     * Start building an agent with a fluent API.
+     *
+     * @example
+     * ```typescript
+     * const agent = await instance
+     *     .agent('Atendente')
+     *     .prompt('Você é um atendente educado.')
+     *     .tools('search', 'calendar')
+     *     .identity('Ana', '👩‍💼')
+     *     .create();
+     * ```
+     */
+    agent(name: string): AgentBuilder;
     /** 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>;
+    /**
+     * Register a webhook to receive events.
+     *
+     * Accepts a URL string (with all defaults applied) or a full config object.
+     *
+     * @example
+     * ```typescript
+     * // Shorthand — just a URL, all defaults applied
+     * await instance.addWebhook('https://my-api.com/hook');
+     *
+     * // Full config
+     * await instance.addWebhook({
+     *     url: 'https://my-api.com/hook',
+     *     events: [Events.MESSAGE_RECEIVED],
+     *     name: 'My Hook',
+     * });
+     * ```
+     */
+    addWebhook(urlOrConfig: string | WebhookConfig): Promise<Webhook>;
     /** List all registered webhooks. */
     listWebhooks(): Promise<Webhook[]>;
     /** Remove a webhook. */
@@ -64,33 +113,33 @@ export declare class OrqoInstance {
     /** 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>>;
+    getStats(): Promise<InstanceStats>;
     /** Get conversation sessions with pagination. */
     getSessions(options?: {
         limit?: number;
         offset?: number;
-    }): Promise<Array<Record<string, unknown>>>;
+    }): Promise<SessionInfo[]>;
     /** Get messages for a session or all messages. */
     getMessages(options?: {
         sessionKey?: string;
         limit?: number;
-    }): Promise<Array<Record<string, unknown>>>;
+    }): Promise<MessageRecord[]>;
     /** 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>>>;
+    listCronJobs(): Promise<CronJob[]>;
     /** Create a new cron job. */
     createCronJob(config: {
         schedule: string;
         action: string;
         payload?: Record<string, unknown>;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<CronJob>;
     /** Delete a cron job. */
     deleteCronJob(jobId: string): Promise<void>;
     /** Manually trigger a cron job. */
-    runCronJob(jobId: string): Promise<Record<string, unknown>>;
+    runCronJob(jobId: string): Promise<CronJob>;
     /**
      * Connect an external API via OpenAPI spec.
      * The agent will automatically gain tools from the spec.
@@ -138,15 +187,24 @@ export declare class OrqoInstance {
         tools: string[];
     }>;
     /** Update an existing webhook configuration. */
-    updateWebhook(webhookId: string, updates: Record<string, unknown>): Promise<Record<string, unknown>>;
+    updateWebhook(webhookId: string, updates: Partial<WebhookConfig>): Promise<Webhook>;
     /** Send a test event to a webhook endpoint. */
-    testWebhook(webhookId: string): Promise<Record<string, unknown>>;
+    testWebhook(webhookId: string): Promise<{
+        success: boolean;
+        statusCode: number;
+        [key: string]: unknown;
+    }>;
     /** Update an existing cron job. */
-    updateCronJob(jobId: string, updates: Record<string, unknown>): Promise<Record<string, unknown>>;
+    updateCronJob(jobId: string, updates: Partial<CronJob>): Promise<CronJob>;
     /** Get resource limits and current usage. */
-    getLimits(): Promise<Record<string, unknown>>;
+    getLimits(): Promise<InstanceLimits>;
     /** Create a backup of this instance. */
-    backup(): Promise<Record<string, unknown>>;
+    backup(): Promise<{
+        url: string;
+        size: number;
+        createdAt: string;
+        [key: string]: unknown;
+    }>;
     /** Generate an agent configuration using AI. */
     generateAgent(config: {
         name: string;
@@ -155,12 +213,12 @@ export declare class OrqoInstance {
         language?: string;
     }): Promise<Agent>;
     /** List all background jobs for this instance. */
-    listBackgroundJobs(): Promise<Record<string, unknown>[]>;
+    listBackgroundJobs(): Promise<BackgroundJob[]>;
     /** Get a specific background job by ID. */
-    getBackgroundJob(jobId: string): Promise<Record<string, unknown>>;
+    getBackgroundJob(jobId: string): Promise<BackgroundJob>;
     /** Create a new background job. */
     createBackgroundJob(config: {
         agentId: string;
         input: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<BackgroundJob>;
 }

package/dist/instance.js

@@ -6,12 +6,21 @@
  * instance + API token.
  */
 import { OrqoError } from './types.js';
+import { AgentBuilder } from './builders.js';
+import { DEFAULT_WEBHOOK_EVENTS } from './constants.js';
 const DEFAULT_RETRY = {
     maxAttempts: 3,
     backoffMs: 1000,
     multiplier: 2,
     retryOn: [429, 500, 502, 503, 504],
 };
+/** Format a phone number to WhatsApp JID */
+function toJid(phone) {
+    if (phone.includes('@'))
+        return phone; // Already a JID
+    const cleaned = phone.replace(/[\s\-\(\)\+]/g, '');
+    return `${cleaned}@s.whatsapp.net`;
+}
 export class OrqoInstance {
     instanceId;
     host;
@@ -115,23 +124,62 @@ export class OrqoInstance {
     // --------------------------------------------------------------------------
     // Messaging
     // --------------------------------------------------------------------------
-    /** Send a text message via WhatsApp. */
+    /** Send a text message via WhatsApp (full options). */
     async sendMessage(options) {
         return this.request('/messages/send', {
             method: 'POST',
             body: JSON.stringify(options),
         });
     }
+    /**
+     * Send a message with automatic JID formatting.
+     *
+     * @param phone - Phone number (e.g. "5511999887766") or full JID
+     * @param text  - Text content to send
+     * @param opts  - Optional extra parameters
+     *
+     * @example
+     * ```typescript
+     * // Simple — phone number auto-formatted to JID
+     * await instance.send('5511999887766', 'Seu pedido saiu!');
+     *
+     * // With options
+     * await instance.send('5511999887766', 'Confira!', { quotedMessageId: 'msg123' });
+     * ```
+     */
+    async send(phone, text, opts) {
+        return this.sendMessage({ to: toJid(phone), text, ...opts });
+    }
     // --------------------------------------------------------------------------
     // Agent CRUD
     // --------------------------------------------------------------------------
     /** Create a new agent for this instance. */
     async createAgent(config) {
+        const payload = {
+            type: 'chat', // Default to chat agent
+            ...config
+        };
         return this.request('/agents', {
             method: 'POST',
-            body: JSON.stringify(config),
+            body: JSON.stringify(payload),
         });
     }
+    /**
+     * Start building an agent with a fluent API.
+     *
+     * @example
+     * ```typescript
+     * const agent = await instance
+     *     .agent('Atendente')
+     *     .prompt('Você é um atendente educado.')
+     *     .tools('search', 'calendar')
+     *     .identity('Ana', '👩‍💼')
+     *     .create();
+     * ```
+     */
+    agent(name) {
+        return new AgentBuilder(this, name);
+    }
     /** List all agents. */
     async listAgents() {
         return this.request('/agents');
@@ -150,11 +198,37 @@ export class OrqoInstance {
     // --------------------------------------------------------------------------
     // Webhook Management
     // --------------------------------------------------------------------------
-    /** Register a webhook to receive events. */
-    async addWebhook(config) {
+    /**
+     * Register a webhook to receive events.
+     *
+     * Accepts a URL string (with all defaults applied) or a full config object.
+     *
+     * @example
+     * ```typescript
+     * // Shorthand — just a URL, all defaults applied
+     * await instance.addWebhook('https://my-api.com/hook');
+     *
+     * // Full config
+     * await instance.addWebhook({
+     *     url: 'https://my-api.com/hook',
+     *     events: [Events.MESSAGE_RECEIVED],
+     *     name: 'My Hook',
+     * });
+     * ```
+     */
+    async addWebhook(urlOrConfig) {
+        const config = typeof urlOrConfig === 'string'
+            ? { url: urlOrConfig }
+            : urlOrConfig;
+        const payload = {
+            name: config.name || `Webhook ${Date.now()}`,
+            events: config.events || [...DEFAULT_WEBHOOK_EVENTS],
+            enabled: config.enabled ?? true,
+            ...config
+        };
         return this.request('/webhooks', {
             method: 'POST',
-            body: JSON.stringify(config),
+            body: JSON.stringify(payload),
         });
     }
     /** List all registered webhooks. */
@@ -200,7 +274,7 @@ export class OrqoInstance {
         });
     }
     // --------------------------------------------------------------------------
-    // Stats & Messages
+    // Stats & Messages (Strong Types)
     // --------------------------------------------------------------------------
     /** Get instance statistics (messages, sessions, uptime). */
     async getStats() {
@@ -241,7 +315,7 @@ export class OrqoInstance {
         return this.request(`/agents/${agentId}`);
     }
     // --------------------------------------------------------------------------
-    // Cron Jobs
+    // Cron Jobs (Strong Types)
     // --------------------------------------------------------------------------
     /** List cron jobs for this instance. */
     async listCronJobs() {
@@ -345,7 +419,7 @@ export class OrqoInstance {
         });
     }
     // --------------------------------------------------------------------------
-    // Background Jobs
+    // Background Jobs (Strong Types)
     // --------------------------------------------------------------------------
     /** List all background jobs for this instance. */
     async listBackgroundJobs() {

package/dist/types.d.ts

@@ -44,6 +44,19 @@ export interface ProvisionOptions {
     webhookUrl?: string;
     /** HMAC secret for webhook signature verification */
     webhookSecret?: string;
+    /** Initial LLM Model Configuration */
+    llm?: {
+        provider: 'openai' | 'gemini' | 'anthropic' | 'groq' | string;
+        model: string;
+        apiKey: string;
+        [key: string]: unknown;
+    };
+    /** Initial Telegram Channel Configuration */
+    telegram?: {
+        enabled?: boolean;
+        botToken: string;
+        webhookSecret?: string;
+    };
     /** Additional instance configuration */
     config?: Record<string, unknown>;
 }
@@ -82,7 +95,7 @@ export interface AgentConfig {
     id?: string;
     /** Human-readable agent name */
     name: string;
-    /** Agent type */
+    /** Agent type (Defaults to 'chat') */
     type?: 'chat' | 'router' | 'specialist';
     /** System prompt / instructions for the LLM */
     systemPrompt?: string;
@@ -95,6 +108,10 @@ export interface AgentConfig {
     };
     /** Routing rules for multi-agent setups */
     routingRules?: Record<string, unknown>;
+    /** Fallback Agent ID if this is a Router */
+    defaultAgentId?: string | null;
+    /** Message sent if no route matches (Router type) */
+    noRouteMessage?: string | null;
     /** Additional configuration */
     [key: string]: unknown;
 }
@@ -103,12 +120,16 @@ export interface Agent extends AgentConfig {
     createdAt?: number;
 }
 export interface WebhookConfig {
+    /** Human-readable name for the webhook */
+    name?: string;
     /** Destination URL for webhook delivery */
     url: string;
     /** HMAC secret for signature verification */
     secret?: string;
-    /** Event type to listen for */
-    event: string;
+    /** Events to listen for (Defaults to all message and session events) */
+    events?: string[];
+    /** Whether the webhook is enabled right away (Defaults to true) */
+    enabled?: boolean;
 }
 export interface Webhook extends WebhookConfig {
     id: string;
@@ -192,6 +213,66 @@ export interface WebhookHandlerOptions {
     /** Called on signature verification failure */
     onVerificationFailed?: (error: Error) => void;
 }
+export interface InstanceStats {
+    totalMessages: number;
+    activeSessions: number;
+    uptime: number;
+    connectedChannels: string[];
+    /** Additional stats from the server */
+    [key: string]: unknown;
+}
+export interface CronJob {
+    id: string;
+    schedule: string;
+    action: string;
+    payload?: Record<string, unknown>;
+    enabled: boolean;
+    lastRun?: number;
+    nextRun?: number;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+export interface BackgroundJob {
+    id: string;
+    agentId: string;
+    input: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | string;
+    result?: string;
+    error?: string;
+    createdAt: number;
+    completedAt?: number;
+    /** Additional fields */
+    [key: string]: unknown;
+}
+export interface InstanceLimits {
+    maxAgents: number;
+    maxWebhooks: number;
+    maxCronJobs: number;
+    currentAgents: number;
+    currentWebhooks: number;
+    currentCronJobs: number;
+    /** Additional limits */
+    [key: string]: unknown;
+}
+export interface SessionInfo {
+    sessionKey: string;
+    contactJid: string;
+    lastMessageAt: number;
+    messageCount: number;
+    agentId?: string;
+    /** Additional session data */
+    [key: string]: unknown;
+}
+export interface MessageRecord {
+    id: string;
+    sessionKey: string;
+    role: 'user' | 'assistant' | 'system' | string;
+    content: string;
+    timestamp: number;
+    agentId?: string;
+    /** Additional message data */
+    [key: string]: unknown;
+}
 export declare class OrqoError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "orqo-node-sdk",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Orqo Gateway — TypeScript SDK for plug-and-play WhatsApp integration",
     "type": "module",
     "main": "dist/index.js",