veryfront 0.0.49 → 0.0.51

package/dist/integrations/twilio/connector.json

@@ -0,0 +1,146 @@
+{
+  "name": "twilio",
+  "displayName": "Twilio",
+  "icon": "twilio.svg",
+  "description": "Send SMS, WhatsApp messages, make calls, and manage communications with Twilio",
+  "auth": {
+    "type": "api-key",
+    "keyName": "TWILIO_AUTH_TOKEN",
+    "headerName": "Authorization",
+    "headerPrefix": "Basic",
+    "requiredApis": [
+      {
+        "name": "Twilio API",
+        "enableUrl": "https://console.twilio.com/us1/develop/sms/overview"
+      }
+    ]
+  },
+  "envVars": [
+    {
+      "name": "TWILIO_ACCOUNT_SID",
+      "description": "Twilio Account SID (starts with AC)",
+      "required": true,
+      "sensitive": false,
+      "docsUrl": "https://console.twilio.com/"
+    },
+    {
+      "name": "TWILIO_AUTH_TOKEN",
+      "description": "Twilio Auth Token",
+      "required": true,
+      "sensitive": true,
+      "docsUrl": "https://console.twilio.com/"
+    },
+    {
+      "name": "TWILIO_PHONE_NUMBER",
+      "description": "Your Twilio phone number (E.164 format: +1234567890)",
+      "required": true,
+      "sensitive": false,
+      "docsUrl": "https://console.twilio.com/us1/develop/phone-numbers/manage/incoming"
+    }
+  ],
+  "tools": [
+    {
+      "id": "send-sms",
+      "name": "Send SMS",
+      "description": "Send an SMS text message to a phone number",
+      "requiresWrite": true
+    },
+    {
+      "id": "send-whatsapp",
+      "name": "Send WhatsApp Message",
+      "description": "Send a WhatsApp message to a phone number",
+      "requiresWrite": true
+    },
+    {
+      "id": "list-messages",
+      "name": "List Messages",
+      "description": "List recent SMS and WhatsApp messages",
+      "requiresWrite": false
+    },
+    {
+      "id": "get-message",
+      "name": "Get Message",
+      "description": "Get details about a specific message",
+      "requiresWrite": false
+    },
+    {
+      "id": "list-calls",
+      "name": "List Calls",
+      "description": "List recent phone calls",
+      "requiresWrite": false
+    }
+  ],
+  "prompts": [
+    {
+      "id": "send-notification",
+      "title": "Send SMS notification",
+      "prompt": "Help me send an SMS notification to a customer about their order status.",
+      "category": "communication",
+      "icon": "message"
+    },
+    {
+      "id": "check-messages",
+      "title": "Check recent messages",
+      "prompt": "Show me the most recent SMS and WhatsApp messages from the last 24 hours.",
+      "category": "communication",
+      "icon": "inbox"
+    },
+    {
+      "id": "call-summary",
+      "title": "Call summary",
+      "prompt": "Give me a summary of recent calls including duration and status.",
+      "category": "analytics",
+      "icon": "phone"
+    },
+    {
+      "id": "whatsapp-outreach",
+      "title": "WhatsApp outreach",
+      "prompt": "Help me draft and send a WhatsApp message for customer outreach.",
+      "category": "communication",
+      "icon": "message"
+    }
+  ],
+  "suggestedWith": ["slack", "gmail", "calendar"],
+  "setupGuide": {
+    "title": "Setting up Twilio Integration",
+    "steps": [
+      {
+        "title": "Create a Twilio Account",
+        "description": "Sign up for a free Twilio account at https://www.twilio.com/try-twilio",
+        "url": "https://www.twilio.com/try-twilio"
+      },
+      {
+        "title": "Get Your Account SID and Auth Token",
+        "description": "Navigate to the Twilio Console Dashboard. Your Account SID and Auth Token are displayed on the main dashboard page. Click the eye icon to reveal your Auth Token.",
+        "url": "https://console.twilio.com/"
+      },
+      {
+        "title": "Get a Phone Number",
+        "description": "Go to Phone Numbers > Manage > Buy a number. Select a phone number with SMS and Voice capabilities. Trial accounts come with one free phone number.",
+        "url": "https://console.twilio.com/us1/develop/phone-numbers/manage/search"
+      },
+      {
+        "title": "Set Up WhatsApp (Optional)",
+        "description": "To send WhatsApp messages, join the Twilio Sandbox for WhatsApp. Go to Messaging > Try it out > Send a WhatsApp message. Follow the instructions to connect your WhatsApp to the sandbox.",
+        "url": "https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn"
+      },
+      {
+        "title": "Add Environment Variables",
+        "description": "Add your Twilio credentials to your .env file:\n- TWILIO_ACCOUNT_SID=ACxxxxx\n- TWILIO_AUTH_TOKEN=your_auth_token\n- TWILIO_PHONE_NUMBER=+1234567890",
+        "url": null
+      },
+      {
+        "title": "Test the Integration",
+        "description": "Try sending a test SMS using the send-sms tool. For trial accounts, you can only send messages to verified phone numbers. Add your phone number at Phone Numbers > Manage > Verified Caller IDs.",
+        "url": "https://console.twilio.com/us1/develop/phone-numbers/manage/verified"
+      }
+    ],
+    "notes": [
+      "Trial accounts have limitations: you can only send messages to verified phone numbers",
+      "All trial messages will be prefixed with 'Sent from your Twilio trial account'",
+      "WhatsApp messages require recipients to first opt-in by messaging your sandbox number",
+      "Phone numbers must be in E.164 format: +[country code][number] (e.g., +14155552671)",
+      "Upgrade your account to remove trial restrictions and enable production features"
+    ]
+  }
+}

package/dist/integrations/twilio/files/_env.example

@@ -0,0 +1,14 @@
+# Twilio Integration
+# Get your credentials at https://console.twilio.com/
+# Trial account: Can only send to verified numbers, messages prefixed with trial notice
+# Production account: Remove all restrictions by upgrading at https://console.twilio.com/billing
+
+# Your Twilio Account SID (starts with AC)
+TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Your Twilio Auth Token (keep this secret!)
+TWILIO_AUTH_TOKEN=your_auth_token_here
+
+# Your Twilio phone number in E.164 format (e.g., +14155552671)
+# Get one at: https://console.twilio.com/us1/develop/phone-numbers/manage/search
+TWILIO_PHONE_NUMBER=+1234567890

package/dist/integrations/twilio/files/ai/tools/get-message.ts

@@ -0,0 +1,58 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { getMessage } from "../../lib/twilio-client.ts";
+
+export default tool({
+  id: "get-message",
+  description: "Get detailed information about a specific SMS or WhatsApp message by its SID (Message ID)",
+  inputSchema: z.object({
+    messageSid: z
+      .string()
+      .describe("The unique Twilio Message SID (starts with 'MM' or 'SM', e.g., MM1234567890abcdef)"),
+  }),
+  execute: async ({ messageSid }) => {
+    try {
+      const message = await getMessage(messageSid);
+
+      return {
+        success: true,
+        message: {
+          sid: message.sid,
+          accountSid: message.account_sid,
+          direction: message.direction,
+          from: message.from,
+          to: message.to,
+          body: message.body,
+          status: message.status,
+          dateSent: message.date_sent,
+          dateCreated: message.date_created,
+          dateUpdated: message.date_updated,
+          numSegments: message.num_segments,
+          numMedia: message.num_media,
+          price: message.price ? `${message.price} ${message.price_unit}` : null,
+          errorCode: message.error_code,
+          errorMessage: message.error_message,
+          uri: message.uri,
+          messagingServiceSid: message.messaging_service_sid,
+        },
+        summary: `Message ${message.sid}: ${message.direction} ${message.status} message from ${message.from} to ${message.to}`,
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.message.includes("not configured")) {
+          return {
+            error: "Twilio not configured. Please set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER.",
+            setupUrl: "https://console.twilio.com/",
+          };
+        }
+
+        if (error.message.includes("20404")) {
+          return {
+            error: `Message not found. The SID '${messageSid}' does not exist in your account.`,
+          };
+        }
+      }
+      throw error;
+    }
+  },
+});

package/dist/integrations/twilio/files/ai/tools/list-calls.ts

@@ -0,0 +1,129 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listCalls, formatPhoneNumber } from "../../lib/twilio-client.ts";
+
+export default tool({
+  id: "list-calls",
+  description: "List recent phone calls from your Twilio account. Supports filtering by recipient, sender, status, and date.",
+  inputSchema: z.object({
+    to: z
+      .string()
+      .optional()
+      .describe("Filter by recipient phone number in E.164 format (e.g., +14155552671)"),
+    from: z
+      .string()
+      .optional()
+      .describe("Filter by sender phone number in E.164 format (e.g., +14155552671)"),
+    status: z
+      .enum([
+        "queued",
+        "ringing",
+        "in-progress",
+        "completed",
+        "busy",
+        "failed",
+        "no-answer",
+        "canceled",
+      ])
+      .optional()
+      .describe("Filter by call status"),
+    startTime: z
+      .string()
+      .optional()
+      .describe("Filter by start time in YYYY-MM-DD format (e.g., 2024-01-15)"),
+    limit: z
+      .number()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Maximum number of calls to return (default: 20, max: 100)"),
+  }),
+  execute: async ({ to, from, status, startTime, limit }) => {
+    try {
+      const options: {
+        to?: string;
+        from?: string;
+        status?: "queued" | "ringing" | "in-progress" | "completed" | "busy" | "failed" | "no-answer" | "canceled";
+        startTime?: string;
+        limit?: number;
+      } = {};
+
+      if (to) {
+        options.to = formatPhoneNumber(to);
+      }
+
+      if (from) {
+        options.from = formatPhoneNumber(from);
+      }
+
+      if (status) {
+        options.status = status;
+      }
+
+      if (startTime) {
+        options.startTime = startTime;
+      }
+
+      if (limit) {
+        options.limit = limit;
+      }
+
+      const calls = await listCalls(options);
+
+      if (calls.length === 0) {
+        return {
+          success: true,
+          count: 0,
+          calls: [],
+          message: "No calls found matching the criteria.",
+        };
+      }
+
+      // Format calls for better readability
+      const formattedCalls = calls.map((call) => ({
+        sid: call.sid,
+        direction: call.direction,
+        from: call.from,
+        to: call.to,
+        status: call.status,
+        startTime: call.start_time,
+        endTime: call.end_time,
+        duration: call.duration ? `${call.duration} seconds` : null,
+        dateCreated: call.date_created,
+        dateUpdated: call.date_updated,
+        price: call.price ? `${call.price} ${call.price_unit}` : null,
+        answeredBy: call.answered_by,
+      }));
+
+      // Calculate statistics
+      const totalDuration = calls.reduce((sum, call) => {
+        return sum + (call.duration ? parseInt(call.duration, 10) : 0);
+      }, 0);
+
+      const statusCounts = calls.reduce((acc, call) => {
+        acc[call.status] = (acc[call.status] || 0) + 1;
+        return acc;
+      }, {} as Record<string, number>);
+
+      return {
+        success: true,
+        count: calls.length,
+        calls: formattedCalls,
+        statistics: {
+          totalCalls: calls.length,
+          totalDuration: `${totalDuration} seconds (${Math.round(totalDuration / 60)} minutes)`,
+          statusBreakdown: statusCounts,
+        },
+        message: `Found ${calls.length} call${calls.length === 1 ? "" : "s"}.`,
+      };
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("not configured")) {
+        return {
+          error: "Twilio not configured. Please set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER.",
+          setupUrl: "https://console.twilio.com/",
+        };
+      }
+      throw error;
+    }
+  },
+});

package/dist/integrations/twilio/files/ai/tools/list-messages.ts

@@ -0,0 +1,97 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { listMessages, formatPhoneNumber, formatDate } from "../../lib/twilio-client.ts";
+
+export default tool({
+  id: "list-messages",
+  description: "List recent SMS and WhatsApp messages from your Twilio account. Supports filtering by recipient, sender, and date.",
+  inputSchema: z.object({
+    to: z
+      .string()
+      .optional()
+      .describe("Filter by recipient phone number in E.164 format (e.g., +14155552671)"),
+    from: z
+      .string()
+      .optional()
+      .describe("Filter by sender phone number in E.164 format (e.g., +14155552671)"),
+    dateSent: z
+      .string()
+      .optional()
+      .describe("Filter by date sent in YYYY-MM-DD format (e.g., 2024-01-15)"),
+    limit: z
+      .number()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe("Maximum number of messages to return (default: 20, max: 100)"),
+  }),
+  execute: async ({ to, from, dateSent, limit }) => {
+    try {
+      const options: {
+        to?: string;
+        from?: string;
+        dateSent?: string;
+        limit?: number;
+      } = {};
+
+      if (to) {
+        options.to = formatPhoneNumber(to);
+      }
+
+      if (from) {
+        options.from = formatPhoneNumber(from);
+      }
+
+      if (dateSent) {
+        options.dateSent = dateSent;
+      }
+
+      if (limit) {
+        options.limit = limit;
+      }
+
+      const messages = await listMessages(options);
+
+      if (messages.length === 0) {
+        return {
+          success: true,
+          count: 0,
+          messages: [],
+          message: "No messages found matching the criteria.",
+        };
+      }
+
+      // Format messages for better readability
+      const formattedMessages = messages.map((msg) => ({
+        sid: msg.sid,
+        direction: msg.direction,
+        from: msg.from,
+        to: msg.to,
+        body: msg.body,
+        status: msg.status,
+        dateSent: msg.date_sent,
+        dateCreated: msg.date_created,
+        numSegments: msg.num_segments,
+        numMedia: msg.num_media,
+        price: msg.price ? `${msg.price} ${msg.price_unit}` : null,
+        errorCode: msg.error_code,
+        errorMessage: msg.error_message,
+      }));
+
+      return {
+        success: true,
+        count: messages.length,
+        messages: formattedMessages,
+        message: `Found ${messages.length} message${messages.length === 1 ? "" : "s"}.`,
+      };
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("not configured")) {
+        return {
+          error: "Twilio not configured. Please set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER.",
+          setupUrl: "https://console.twilio.com/",
+        };
+      }
+      throw error;
+    }
+  },
+});

package/dist/integrations/twilio/files/ai/tools/send-sms.ts

@@ -0,0 +1,75 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { sendSMS, formatPhoneNumber } from "../../lib/twilio-client.ts";
+
+export default tool({
+  id: "send-sms",
+  description: "Send an SMS text message to a phone number using Twilio",
+  inputSchema: z.object({
+    to: z
+      .string()
+      .describe("Recipient phone number in E.164 format (e.g., +14155552671) or 10-digit US format"),
+    body: z
+      .string()
+      .min(1)
+      .max(1600)
+      .describe("Message text to send (max 1600 characters)"),
+    mediaUrl: z
+      .array(z.string().url())
+      .optional()
+      .describe("Optional array of media URLs to send as MMS (images, videos, etc.)"),
+  }),
+  execute: async ({ to, body, mediaUrl }) => {
+    try {
+      // Format phone number to E.164 if needed
+      const formattedPhone = formatPhoneNumber(to);
+
+      const message = await sendSMS(formattedPhone, body, {
+        mediaUrl,
+      });
+
+      return {
+        success: true,
+        messageSid: message.sid,
+        status: message.status,
+        to: message.to,
+        from: message.from,
+        body: message.body,
+        numSegments: message.num_segments,
+        price: message.price,
+        priceUnit: message.price_unit,
+        message: `SMS sent successfully to ${message.to}. Status: ${message.status}`,
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        // Check for common errors
+        if (error.message.includes("not configured")) {
+          return {
+            error: "Twilio not configured. Please set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER.",
+            setupUrl: "https://console.twilio.com/",
+          };
+        }
+
+        // Twilio API errors
+        if (error.message.includes("21211")) {
+          return {
+            error: `Invalid phone number: ${to}. Please use E.164 format (e.g., +14155552671).`,
+          };
+        }
+
+        if (error.message.includes("21608")) {
+          return {
+            error: `Unverified number. Trial accounts can only send to verified numbers. Verify at: https://console.twilio.com/us1/develop/phone-numbers/manage/verified`,
+          };
+        }
+
+        if (error.message.includes("21610")) {
+          return {
+            error: `Unverified 'To' number. This number must be verified before you can send messages to it during trial.`,
+          };
+        }
+      }
+      throw error;
+    }
+  },
+});

package/dist/integrations/twilio/files/ai/tools/send-whatsapp.ts

@@ -0,0 +1,81 @@
+import { tool } from "veryfront/ai";
+import { z } from "zod";
+import { sendWhatsApp, formatPhoneNumber } from "../../lib/twilio-client.ts";
+
+export default tool({
+  id: "send-whatsapp",
+  description: "Send a WhatsApp message to a phone number using Twilio. Note: Recipients must have opted in to receive messages.",
+  inputSchema: z.object({
+    to: z
+      .string()
+      .describe("Recipient phone number in E.164 format (e.g., +14155552671). The 'whatsapp:' prefix is optional."),
+    body: z
+      .string()
+      .min(1)
+      .describe("Message text to send"),
+    mediaUrl: z
+      .array(z.string().url())
+      .optional()
+      .describe("Optional array of media URLs to send (images, videos, PDFs, etc.)"),
+  }),
+  execute: async ({ to, body, mediaUrl }) => {
+    try {
+      // Format phone number to E.164 if needed
+      const formattedPhone = formatPhoneNumber(to);
+
+      const message = await sendWhatsApp(formattedPhone, body, {
+        mediaUrl,
+      });
+
+      return {
+        success: true,
+        messageSid: message.sid,
+        status: message.status,
+        to: message.to,
+        from: message.from,
+        body: message.body,
+        numSegments: message.num_segments,
+        price: message.price,
+        priceUnit: message.price_unit,
+        message: `WhatsApp message sent successfully to ${message.to}. Status: ${message.status}`,
+      };
+    } catch (error) {
+      if (error instanceof Error) {
+        // Check for common errors
+        if (error.message.includes("not configured")) {
+          return {
+            error: "Twilio not configured. Please set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER.",
+            setupUrl: "https://console.twilio.com/",
+          };
+        }
+
+        // Twilio WhatsApp-specific errors
+        if (error.message.includes("63007")) {
+          return {
+            error: "Recipient has not opted in to receive WhatsApp messages. They must send a message to your WhatsApp sandbox first.",
+            sandboxUrl: "https://console.twilio.com/us1/develop/sms/try-it-out/whatsapp-learn",
+          };
+        }
+
+        if (error.message.includes("63016")) {
+          return {
+            error: "WhatsApp message failed: Recipient phone number is not a WhatsApp user.",
+          };
+        }
+
+        if (error.message.includes("63030")) {
+          return {
+            error: "Message body is required for WhatsApp messages unless media is included.",
+          };
+        }
+
+        if (error.message.includes("63003")) {
+          return {
+            error: "Message exceeds maximum allowed length for WhatsApp.",
+          };
+        }
+      }
+      throw error;
+    }
+  },
+});