@runflow-ai/sdk 1.0.39 → 1.0.41

package/README.md

@@ -740,113 +740,203 @@ The `execute` function receives:
 
 ### Connectors
 
-**Connectors** are pre-configured integrations with external services (HubSpot, Twilio, Email, Slack).
+**Connectors** are dynamic integrations with external services defined in the Runflow backend. Connector tools automatically load schemas from the backend, support mock execution, and handle path parameters seamlessly.
+
+#### Key Features
+
+- 🔄 **Dynamic Schema Loading** - Schemas are fetched from the backend automatically
+- 🎭 **Transparent Mocking** - Enable mock mode for development and testing
+- 🛣️ **Path Parameter Resolution** - Automatic extraction and URL building
+- ⚡ **Lazy Initialization** - Schemas loaded only when needed, cached globally
+- 🔐 **Flexible Authentication** - Supports API Key, Bearer Token, Basic Auth, OAuth2
+- ✅ **Type-Safe** - Automatic JSON Schema → Zod → LLM Parameters conversion
 
 #### Create Connector Tool
 
 ```typescript
-import { createConnectorTool } from '@runflow-ai/sdk';
+import { createConnectorTool, Agent, openai } from '@runflow-ai/sdk';
 
-// HubSpot - Create contact
-const createContact = createConnectorTool(
-  'hubspot',
-  'contacts',
-  'create',
-  {
-    email: 'email',
-    firstName: 'string?',
-    lastName: 'string?',
-    phone: 'string?',
-    company: 'string?',
-  }
-);
+// Basic connector tool (schema loaded from backend)
+const getClienteTool = createConnectorTool({
+  connector: 'api-contabil',
+  resource: 'clientes',
+  action: 'get',
+  description: 'Get customer by ID from accounting API',
+  enableMock: true, // Optional: enables mock mode
+});
 
-// Twilio - Send WhatsApp
-const sendWhatsApp = createConnectorTool(
-  'twilio',
-  'messages',
-  'send-whatsapp',
-  {
-    to: 'string',
-    message: 'string',
-    mediaUrl: 'url?',
-  }
-);
+// Use with Agent
+const agent = new Agent({
+  name: 'Accounting Agent',
+  instructions: 'You help manage customers in the accounting system.',
+  model: openai('gpt-4o'),
+  tools: {
+    getCliente: getClienteTool,
+    listClientes: createConnectorTool({
+      connector: 'api-contabil',
+      resource: 'clientes',
+      action: 'list',
+    }),
+  },
+});
 
-// Email - Send email
-const sendEmail = createConnectorTool(
-  'email',
-  'messages',
-  'send',
-  {
-    to: 'email',
-    subject: 'string',
-    body: 'string',
-    html: 'boolean?',
-  }
-);
+// First execution automatically loads schemas from backend
+const result = await agent.process({
+  message: 'Get customer with ID 123',
+  sessionId: 'session-123',
+  companyId: 'company-456',
+});
+```
 
-// Slack - Send message
-const sendSlack = createConnectorTool(
-  'slack',
-  'messages',
-  'send',
-  {
-    channel: 'string',
-    message: 'string',
-    username: 'string?',
-    iconEmoji: 'string?',
-  }
-);
+#### Connector Tool Configuration
+
+```typescript
+createConnectorTool({
+  connector: string,      // Connector instance name (e.g., 'hubspot', 'api-contabil')
+  resource: string,        // Resource name (e.g., 'contacts', 'clientes', 'tickets')
+  action: string,          // Action name (e.g., 'get', 'list', 'create', 'update')
+  description?: string,    // Optional: Custom description (defaults to auto-generated)
+  enableMock?: boolean,    // Optional: Enable mock mode (adds useMock parameter)
+})
 ```
 
-#### Use Built-in Shortcuts
+#### Multiple Connector Tools
 
 ```typescript
-import { hubspot, twilio, email, slack } from '@runflow-ai/sdk';
+// Create multiple tools for the same connector
+const tools = {
+  listClientes: createConnectorTool({
+    connector: 'api-contabil',
+    resource: 'clientes',
+    action: 'list',
+    enableMock: true,
+  }),
+  
+  getCliente: createConnectorTool({
+    connector: 'api-contabil',
+    resource: 'clientes',
+    action: 'get',
+    enableMock: true,
+  }),
+  
+  createCliente: createConnectorTool({
+    connector: 'api-contabil',
+    resource: 'clientes',
+    action: 'create',
+    enableMock: true,
+  }),
+};
 
 const agent = new Agent({
-  name: 'Support Agent',
-  instructions: 'You help customers.',
+  name: 'Customer Management Agent',
+  instructions: 'You help manage customers.',
+  model: openai('gpt-4o'),
+  tools,
+});
+
+// All schemas are loaded in parallel on first execution
+const result = await agent.process({
+  message: 'Create a new customer named ACME Corp',
+  sessionId: 'session-123',
+  companyId: 'company-456',
+});
+```
+
+#### Using loadConnector Helper
+
+For connectors with many resources, use the `loadConnector` helper:
+
+```typescript
+import { loadConnector } from '@runflow-ai/sdk';
+
+const contabil = loadConnector('api-contabil');
+
+const agent = new Agent({
+  name: 'Accounting Agent',
+  instructions: 'You manage accounting data.',
   model: openai('gpt-4o'),
   tools: {
-    // Built-in connector shortcuts
-    createContact: hubspot.createContact(),
-    getContact: hubspot.getContact(),
-    createTicket: hubspot.createTicket(),
-    sendWhatsApp: twilio.sendWhatsApp(),
-    sendSMS: twilio.sendSMS(),
-    sendEmail: email.send(),
-    sendSlack: slack.sendMessage(),
+    listClientes: contabil.tool('clientes', 'list'),
+    getCliente: contabil.tool('clientes', 'get'),
+    createCliente: contabil.tool('clientes', 'create'),
+    updateCliente: contabil.tool('clientes', 'update'),
   },
 });
 ```
 
-#### Parameter Types
+#### Path Parameters
+
+Connectors automatically resolve path parameters from the resource URL:
 
 ```typescript
-const tool = createConnectorTool('service', 'resource', 'action', {
-  // Basic types
-  name: 'string',
-  age: 'number',
-  active: 'boolean',
-  createdAt: 'date',
+// Resource defined in backend: /clientes/{id}/pedidos/{pedidoId}
+const getClientePedidoTool = createConnectorTool({
+  connector: 'api-contabil',
+  resource: 'clientes.pedidos',
+  action: 'get',
+  description: 'Get specific order from a customer',
+});
 
-  // Optional (append ?)
-  nickname: 'string?',
-  score: 'number?',
+// Agent automatically extracts path params from context
+const result = await agent.process({
+  message: 'Get order 456 from customer 123',
+  sessionId: 'session-123',
+  companyId: 'company-456',
+});
+
+// Backend automatically resolves: /clientes/123/pedidos/456
+```
 
-  // Special validations
-  email: 'email',
-  website: 'url',
+#### Mock Execution
 
-  // Enum
-  priority: { enum: ['low', 'medium', 'high'] },
+Enable mock mode for development and testing:
 
-  // Arrays
-  tags: { array: 'string' },
-  scores: { array: 'number' },
+```typescript
+const tool = createConnectorTool({
+  connector: 'api-contabil',
+  resource: 'clientes',
+  action: 'list',
+  enableMock: true, // Adds useMock parameter
+});
+
+// Use mock mode in development
+const result = await agent.process({
+  message: 'List customers (use mock data)',
+  sessionId: 'dev-session',
+  companyId: 'dev-company',
+  // Tool will automatically include useMock=true if mock data is configured
+});
+```
+
+#### How It Works
+
+1. **Tool Creation**: `createConnectorTool` creates a tool with a temporary schema
+2. **Lazy Loading**: On first agent execution, schemas are fetched from the backend in parallel
+3. **Schema Conversion**: JSON Schema → Zod → LLM Parameters (automatic)
+4. **Caching**: Schemas are cached globally to avoid repeated API calls
+5. **Execution**: Tool executes with proper authentication, path resolution, and error handling
+
+#### Automatic Setup
+
+The Agent automatically initializes connector tools on first execution:
+
+```typescript
+const agent = new Agent({
+  name: 'My Agent',
+  model: openai('gpt-4o'),
+  tools: {
+    // Connector tools are automatically identified and initialized
+    tool1: createConnectorTool({ ... }),
+    tool2: createTool({ ... }), // Regular tool
+    tool3: createConnectorTool({ ... }),
+  },
 });
+
+// First process() call:
+// 1. Identifies connector tools (marked with _isConnectorTool)
+// 2. Loads schemas in parallel from backend
+// 3. Updates tool parameters
+// 4. Proceeds with normal execution
 ```
 
 ---

package/dist/connectors/connector-creator.d.ts

@@ -1,5 +1,15 @@
 import { z } from 'zod';
-export declare function createConnectorTool(connector: string, resource: string, action: string, parameters: ConnectorParameters, options?: ConnectorToolOptions): import("..").RunflowTool;
+import { RunflowTool } from '../types';
+export declare function createConnectorTool(config: {
+    connector: string;
+    resource: string;
+    action: string;
+    description?: string;
+    enableMock?: boolean;
+}): RunflowTool;
+export declare function loadConnector(name: string): {
+    tool(resource: string, action: string): RunflowTool;
+};
 export type ConnectorParameters = Record<string, ConnectorParameter>;
 export type ConnectorParameter = 'string' | 'string?' | 'number' | 'number?' | 'boolean' | 'boolean?' | 'email' | 'email?' | 'url' | 'url?' | 'date' | 'date?' | {
     enum: string[];
@@ -12,18 +22,18 @@ export interface ConnectorToolOptions {
     outputSchema?: z.ZodSchema;
 }
 export declare const hubspot: {
-    createContact: () => import("..").RunflowTool;
-    getContact: () => import("..").RunflowTool;
-    createTicket: () => import("..").RunflowTool;
+    createContact: () => RunflowTool;
+    getContact: () => RunflowTool;
+    createTicket: () => RunflowTool;
 };
 export declare const twilio: {
-    sendWhatsApp: () => import("..").RunflowTool;
-    sendSMS: () => import("..").RunflowTool;
+    sendWhatsApp: () => RunflowTool;
+    sendSMS: () => RunflowTool;
 };
 export declare const email: {
-    send: () => import("..").RunflowTool;
+    send: () => RunflowTool;
 };
 export declare const slack: {
-    sendMessage: () => import("..").RunflowTool;
+    sendMessage: () => RunflowTool;
 };
 //# sourceMappingURL=connector-creator.d.ts.map

package/dist/connectors/connector-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connector-creator.d.ts","sourceRoot":"","sources":["../../src/connectors/connector-creator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,mBAAmB,EAC/B,OAAO,CAAC,EAAE,oBAAoB,4BAkB/B;AAMD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,UAAU,GACV,OAAO,GACP,QAAQ,GACR,KAAK,GACL,MAAM,GACN,MAAM,GACN,OAAO,GACP;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAClB;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;CAC5B;AAkED,eAAO,MAAM,OAAO;;;;CAmBnB,CAAC;AAEF,eAAO,MAAM,MAAM;;;CAWlB,CAAC;AAEF,eAAO,MAAM,KAAK;;CASjB,CAAC;AAEF,eAAO,MAAM,KAAK;;CAOjB,CAAC"}
+{"version":3,"file":"connector-creator.d.ts","sourceRoot":"","sources":["../../src/connectors/connector-creator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAiBvC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,WAAW,CA+Fd;AAiMD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM;mBAGvB,MAAM,UAAU,MAAM;EASxC;AAMD,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,UAAU,GACV,OAAO,GACP,QAAQ,GACR,KAAK,GACL,MAAM,GACN,MAAM,GACN,OAAO,GACP;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAClB;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,oBAAoB;IACnC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC;CAC5B;AAGD,eAAO,MAAM,OAAO;;;;CAqBnB,CAAC;AAEF,eAAO,MAAM,MAAM;;;CAclB,CAAC;AAEF,eAAO,MAAM,KAAK;;CAOjB,CAAC;AAEF,eAAO,MAAM,KAAK;;CAOjB,CAAC"}