@radaros/core 0.3.0 → 0.3.1

package/dist/index.js

@@ -3787,14 +3787,14 @@ var MCPToolProvider = class {
     await this.discoverTools();
   }
   async discoverTools() {
-    const { z: z3 } = await import("zod");
+    const { z: z7 } = await import("zod");
     const result = await this.client.listTools();
     const mcpTools = result.tools ?? [];
     this.tools = mcpTools.map((mcpTool) => {
       const toolName = mcpTool.name;
       const description = mcpTool.description ?? "";
       const inputSchema = mcpTool.inputSchema ?? { type: "object", properties: {} };
-      const parameters = this.jsonSchemaToZod(inputSchema, z3);
+      const parameters = this.jsonSchemaToZod(inputSchema, z7);
       const execute = async (args, _ctx) => {
         const callResult = await this.client.callTool({
           name: toolName,
@@ -3822,9 +3822,9 @@ var MCPToolProvider = class {
       };
     });
   }
-  jsonSchemaToZod(schema, z3) {
+  jsonSchemaToZod(schema, z7) {
     if (!schema || !schema.properties) {
-      return z3.object({}).passthrough();
+      return z7.object({}).passthrough();
     }
     const shape = {};
     const required = schema.required ?? [];
@@ -3832,24 +3832,24 @@ var MCPToolProvider = class {
       let field;
       switch (prop.type) {
         case "string":
-          field = z3.string();
-          if (prop.enum) field = z3.enum(prop.enum);
+          field = z7.string();
+          if (prop.enum) field = z7.enum(prop.enum);
           break;
         case "number":
         case "integer":
-          field = z3.number();
+          field = z7.number();
           break;
         case "boolean":
-          field = z3.boolean();
+          field = z7.boolean();
           break;
         case "array":
-          field = z3.array(z3.any());
+          field = z7.array(z7.any());
           break;
         case "object":
-          field = z3.record(z3.any());
+          field = z7.record(z7.any());
           break;
         default:
-          field = z3.any();
+          field = z7.any();
       }
       if (prop.description) {
         field = field.describe(prop.description);
@@ -3859,7 +3859,7 @@ var MCPToolProvider = class {
       }
       shape[key] = field;
     }
-    return z3.object(shape);
+    return z7.object(shape);
   }
   /**
    * Returns tools from this MCP server as RadarOS ToolDef[].
@@ -4108,14 +4108,499 @@ var A2ARemoteAgent = class {
     ).map((p) => p.text).join("\n");
   }
 };
+
+// src/toolkits/base.ts
+var Toolkit = class {
+};
+
+// src/toolkits/websearch.ts
+import { z as z3 } from "zod";
+var WebSearchToolkit = class extends Toolkit {
+  name = "websearch";
+  config;
+  constructor(config) {
+    super();
+    this.config = config;
+  }
+  getApiKey() {
+    if (this.config.apiKey) return this.config.apiKey;
+    const envKey = this.config.provider === "tavily" ? process.env.TAVILY_API_KEY : process.env.SERPAPI_API_KEY;
+    if (!envKey) {
+      const envName = this.config.provider === "tavily" ? "TAVILY_API_KEY" : "SERPAPI_API_KEY";
+      throw new Error(
+        `WebSearchToolkit: No API key provided. Set ${envName} env var or pass apiKey in config.`
+      );
+    }
+    return envKey;
+  }
+  getTools() {
+    const self = this;
+    return [
+      {
+        name: "web_search",
+        description: "Search the web for current information. Returns titles, URLs, and snippets from search results.",
+        parameters: z3.object({
+          query: z3.string().describe("The search query"),
+          maxResults: z3.number().optional().describe("Maximum number of results (default 5)")
+        }),
+        execute: async (args, _ctx) => {
+          const query = args.query;
+          const max = args.maxResults ?? self.config.maxResults ?? 5;
+          if (self.config.provider === "tavily") {
+            return self.searchTavily(query, max);
+          }
+          return self.searchSerpApi(query, max);
+        }
+      }
+    ];
+  }
+  async searchTavily(query, maxResults) {
+    const apiKey = this.getApiKey();
+    const res = await fetch("https://api.tavily.com/search", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_key: apiKey,
+        query,
+        max_results: maxResults,
+        include_answer: true
+      })
+    });
+    if (!res.ok) {
+      throw new Error(`Tavily search failed: ${res.status} ${res.statusText}`);
+    }
+    const data = await res.json();
+    const results = [];
+    if (data.answer) {
+      results.push(`Answer: ${data.answer}
+`);
+    }
+    for (const r of data.results ?? []) {
+      results.push(`Title: ${r.title}
+URL: ${r.url}
+Snippet: ${r.content}
+`);
+    }
+    return results.join("\n---\n") || "No results found.";
+  }
+  async searchSerpApi(query, maxResults) {
+    const apiKey = this.getApiKey();
+    const params = new URLSearchParams({
+      q: query,
+      api_key: apiKey,
+      engine: "google",
+      num: String(maxResults)
+    });
+    const res = await fetch(
+      `https://serpapi.com/search.json?${params.toString()}`
+    );
+    if (!res.ok) {
+      throw new Error(
+        `SerpAPI search failed: ${res.status} ${res.statusText}`
+      );
+    }
+    const data = await res.json();
+    const results = [];
+    if (data.answer_box?.answer) {
+      results.push(`Answer: ${data.answer_box.answer}
+`);
+    }
+    for (const r of (data.organic_results ?? []).slice(0, maxResults)) {
+      results.push(
+        `Title: ${r.title}
+URL: ${r.link}
+Snippet: ${r.snippet ?? ""}
+`
+      );
+    }
+    return results.join("\n---\n") || "No results found.";
+  }
+};
+
+// src/toolkits/gmail.ts
+import { z as z4 } from "zod";
+import { createRequire as createRequire16 } from "module";
+var _require16 = createRequire16(import.meta.url);
+var GmailToolkit = class extends Toolkit {
+  name = "gmail";
+  config;
+  gmail = null;
+  constructor(config = {}) {
+    super();
+    this.config = config;
+  }
+  async getGmailClient() {
+    if (this.gmail) return this.gmail;
+    if (this.config.authClient) {
+      const { google: google3 } = _require16("googleapis");
+      this.gmail = google3.gmail({ version: "v1", auth: this.config.authClient });
+      return this.gmail;
+    }
+    const credPath = this.config.credentialsPath ?? process.env.GMAIL_CREDENTIALS_PATH;
+    const tokenPath = this.config.tokenPath ?? process.env.GMAIL_TOKEN_PATH;
+    if (!credPath || !tokenPath) {
+      throw new Error(
+        "GmailToolkit: Provide credentialsPath + tokenPath, or an authClient. Set GMAIL_CREDENTIALS_PATH and GMAIL_TOKEN_PATH env vars, or pass them in config."
+      );
+    }
+    const { google: google2 } = _require16("googleapis");
+    const fs = await import("fs");
+    const creds = JSON.parse(fs.readFileSync(credPath, "utf-8"));
+    const token = JSON.parse(fs.readFileSync(tokenPath, "utf-8"));
+    const { client_id, client_secret, redirect_uris } = creds.installed || creds.web;
+    const oAuth2 = new google2.auth.OAuth2(
+      client_id,
+      client_secret,
+      redirect_uris?.[0]
+    );
+    oAuth2.setCredentials(token);
+    this.gmail = google2.gmail({ version: "v1", auth: oAuth2 });
+    return this.gmail;
+  }
+  getTools() {
+    const self = this;
+    return [
+      {
+        name: "gmail_send",
+        description: "Send an email via Gmail. Provide recipient, subject, and body.",
+        parameters: z4.object({
+          to: z4.string().describe("Recipient email address"),
+          subject: z4.string().describe("Email subject line"),
+          body: z4.string().describe("Email body (plain text)")
+        }),
+        execute: async (args, _ctx) => {
+          const gmail = await self.getGmailClient();
+          const rawMessage = [
+            `To: ${args.to}`,
+            `Subject: ${args.subject}`,
+            "Content-Type: text/plain; charset=utf-8",
+            "",
+            args.body
+          ].join("\n");
+          const encoded = Buffer.from(rawMessage).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+          const res = await gmail.users.messages.send({
+            userId: "me",
+            requestBody: { raw: encoded }
+          });
+          return `Email sent successfully. Message ID: ${res.data.id}`;
+        }
+      },
+      {
+        name: "gmail_search",
+        description: "Search emails in Gmail. Returns subject, from, date, and snippet for matching messages.",
+        parameters: z4.object({
+          query: z4.string().describe(
+            'Gmail search query (e.g. "from:john subject:meeting is:unread")'
+          ),
+          maxResults: z4.number().optional().describe("Maximum number of results (default 10)")
+        }),
+        execute: async (args, _ctx) => {
+          const gmail = await self.getGmailClient();
+          const max = args.maxResults ?? 10;
+          const list = await gmail.users.messages.list({
+            userId: "me",
+            q: args.query,
+            maxResults: max
+          });
+          const messages = list.data.messages ?? [];
+          if (messages.length === 0) return "No emails found.";
+          const results = [];
+          for (const msg of messages) {
+            const detail = await gmail.users.messages.get({
+              userId: "me",
+              id: msg.id,
+              format: "metadata",
+              metadataHeaders: ["From", "Subject", "Date"]
+            });
+            const headers = detail.data.payload?.headers ?? [];
+            const getHeader = (name) => headers.find(
+              (h) => h.name.toLowerCase() === name.toLowerCase()
+            )?.value ?? "";
+            results.push(
+              `ID: ${msg.id}
+From: ${getHeader("From")}
+Subject: ${getHeader("Subject")}
+Date: ${getHeader("Date")}
+Snippet: ${detail.data.snippet ?? ""}`
+            );
+          }
+          return results.join("\n\n---\n\n");
+        }
+      },
+      {
+        name: "gmail_read",
+        description: "Read the full content of an email by its message ID.",
+        parameters: z4.object({
+          messageId: z4.string().describe("The Gmail message ID to read")
+        }),
+        execute: async (args, _ctx) => {
+          const gmail = await self.getGmailClient();
+          const detail = await gmail.users.messages.get({
+            userId: "me",
+            id: args.messageId,
+            format: "full"
+          });
+          const headers = detail.data.payload?.headers ?? [];
+          const getHeader = (name) => headers.find(
+            (h) => h.name.toLowerCase() === name.toLowerCase()
+          )?.value ?? "";
+          let body = "";
+          const payload = detail.data.payload;
+          if (payload?.body?.data) {
+            body = Buffer.from(payload.body.data, "base64").toString("utf-8");
+          } else if (payload?.parts) {
+            const textPart = payload.parts.find(
+              (p) => p.mimeType === "text/plain"
+            );
+            if (textPart?.body?.data) {
+              body = Buffer.from(textPart.body.data, "base64").toString(
+                "utf-8"
+              );
+            } else {
+              const htmlPart = payload.parts.find(
+                (p) => p.mimeType === "text/html"
+              );
+              if (htmlPart?.body?.data) {
+                body = Buffer.from(htmlPart.body.data, "base64").toString(
+                  "utf-8"
+                );
+              }
+            }
+          }
+          return `From: ${getHeader("From")}
+To: ${getHeader("To")}
+Subject: ${getHeader("Subject")}
+Date: ${getHeader("Date")}
+
+${body || "(no body)"}`;
+        }
+      }
+    ];
+  }
+};
+
+// src/toolkits/whatsapp.ts
+import { z as z5 } from "zod";
+var WhatsAppToolkit = class extends Toolkit {
+  name = "whatsapp";
+  accessToken;
+  phoneNumberId;
+  version;
+  recipientWaid;
+  constructor(config = {}) {
+    super();
+    this.accessToken = config.accessToken ?? process.env.WHATSAPP_ACCESS_TOKEN ?? "";
+    this.phoneNumberId = config.phoneNumberId ?? process.env.WHATSAPP_PHONE_NUMBER_ID ?? "";
+    this.version = config.version ?? process.env.WHATSAPP_VERSION ?? "v22.0";
+    this.recipientWaid = config.recipientWaid ?? process.env.WHATSAPP_RECIPIENT_WAID;
+  }
+  getBaseUrl() {
+    return `https://graph.facebook.com/${this.version}/${this.phoneNumberId}/messages`;
+  }
+  validate() {
+    if (!this.accessToken) {
+      throw new Error(
+        "WhatsAppToolkit: accessToken is required. Set WHATSAPP_ACCESS_TOKEN env var or pass in config."
+      );
+    }
+    if (!this.phoneNumberId) {
+      throw new Error(
+        "WhatsAppToolkit: phoneNumberId is required. Set WHATSAPP_PHONE_NUMBER_ID env var or pass in config."
+      );
+    }
+  }
+  resolveRecipient(recipient) {
+    const r = recipient ?? this.recipientWaid;
+    if (!r) {
+      throw new Error(
+        "WhatsAppToolkit: recipient is required. Provide it in the tool call or set WHATSAPP_RECIPIENT_WAID env var."
+      );
+    }
+    return r.replace(/[^0-9]/g, "");
+  }
+  getTools() {
+    const self = this;
+    return [
+      {
+        name: "whatsapp_send_text",
+        description: "Send a text message to a WhatsApp user via WhatsApp Business Cloud API.",
+        parameters: z5.object({
+          text: z5.string().describe("The text message to send"),
+          recipient: z5.string().optional().describe(
+            "Recipient WhatsApp number with country code (e.g. 919876543210). Uses default if omitted."
+          ),
+          previewUrl: z5.boolean().optional().describe("Enable URL previews in the message (default false)")
+        }),
+        execute: async (args, _ctx) => {
+          self.validate();
+          const recipient = self.resolveRecipient(args.recipient);
+          const res = await fetch(self.getBaseUrl(), {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${self.accessToken}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              messaging_product: "whatsapp",
+              recipient_type: "individual",
+              to: recipient,
+              type: "text",
+              text: {
+                preview_url: args.previewUrl ?? false,
+                body: args.text
+              }
+            })
+          });
+          if (!res.ok) {
+            const err = await res.text();
+            throw new Error(
+              `WhatsApp send failed: ${res.status} ${err}`
+            );
+          }
+          const data = await res.json();
+          const msgId = data.messages?.[0]?.id ?? "unknown";
+          return `Message sent successfully to ${recipient}. Message ID: ${msgId}`;
+        }
+      },
+      {
+        name: "whatsapp_send_template",
+        description: "Send a template message to a WhatsApp user. Required for first-time outreach (24-hour messaging window).",
+        parameters: z5.object({
+          templateName: z5.string().describe(
+            'The pre-approved template name (e.g. "hello_world")'
+          ),
+          recipient: z5.string().optional().describe(
+            "Recipient WhatsApp number with country code. Uses default if omitted."
+          ),
+          languageCode: z5.string().optional().describe('Template language code (default "en_US")'),
+          components: z5.array(z5.record(z5.any())).optional().describe(
+            "Template components for dynamic content (header, body, button parameters)"
+          )
+        }),
+        execute: async (args, _ctx) => {
+          self.validate();
+          const recipient = self.resolveRecipient(args.recipient);
+          const langCode = args.languageCode ?? "en_US";
+          const template = {
+            name: args.templateName,
+            language: { code: langCode }
+          };
+          if (args.components) {
+            template.components = args.components;
+          }
+          const res = await fetch(self.getBaseUrl(), {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${self.accessToken}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+              messaging_product: "whatsapp",
+              recipient_type: "individual",
+              to: recipient,
+              type: "template",
+              template
+            })
+          });
+          if (!res.ok) {
+            const err = await res.text();
+            throw new Error(
+              `WhatsApp template send failed: ${res.status} ${err}`
+            );
+          }
+          const data = await res.json();
+          const msgId = data.messages?.[0]?.id ?? "unknown";
+          return `Template message "${args.templateName}" sent to ${recipient}. Message ID: ${msgId}`;
+        }
+      }
+    ];
+  }
+};
+
+// src/toolkits/hackernews.ts
+import { z as z6 } from "zod";
+var HackerNewsToolkit = class extends Toolkit {
+  name = "hackernews";
+  config;
+  constructor(config = {}) {
+    super();
+    this.config = {
+      enableGetTopStories: config.enableGetTopStories ?? true,
+      enableGetUserDetails: config.enableGetUserDetails ?? true
+    };
+  }
+  getTools() {
+    const tools = [];
+    if (this.config.enableGetTopStories) {
+      tools.push({
+        name: "hackernews_top_stories",
+        description: "Get the top stories from Hacker News. Returns title, URL, score, author, and comment count.",
+        parameters: z6.object({
+          numStories: z6.number().optional().describe("Number of top stories to fetch (default 10, max 30)")
+        }),
+        execute: async (args, _ctx) => {
+          const num = Math.min(args.numStories ?? 10, 30);
+          const idsRes = await fetch(
+            "https://hacker-news.firebaseio.com/v0/topstories.json"
+          );
+          if (!idsRes.ok) throw new Error(`HN API failed: ${idsRes.status}`);
+          const ids = await idsRes.json();
+          const stories = await Promise.all(
+            ids.slice(0, num).map(async (id) => {
+              const res = await fetch(
+                `https://hacker-news.firebaseio.com/v0/item/${id}.json`
+              );
+              return res.json();
+            })
+          );
+          return stories.map(
+            (s, i) => `${i + 1}. ${s.title}
+   URL: ${s.url ?? `https://news.ycombinator.com/item?id=${s.id}`}
+   Score: ${s.score} | By: ${s.by} | Comments: ${s.descendants ?? 0}`
+          ).join("\n\n");
+        }
+      });
+    }
+    if (this.config.enableGetUserDetails) {
+      tools.push({
+        name: "hackernews_user",
+        description: "Get details about a Hacker News user by username. Returns karma, about, and account creation date.",
+        parameters: z6.object({
+          username: z6.string().describe("The HN username to look up")
+        }),
+        execute: async (args, _ctx) => {
+          const username = args.username;
+          const res = await fetch(
+            `https://hacker-news.firebaseio.com/v0/user/${username}.json`
+          );
+          if (!res.ok)
+            throw new Error(`HN user API failed: ${res.status}`);
+          const user = await res.json();
+          if (!user) return `User "${username}" not found.`;
+          const created = new Date(user.created * 1e3).toISOString().split("T")[0];
+          return [
+            `Username: ${user.id}`,
+            `Karma: ${user.karma}`,
+            `Created: ${created}`,
+            user.about ? `About: ${user.about}` : null,
+            `Submitted: ${user.submitted?.length ?? 0} items`
+          ].filter(Boolean).join("\n");
+        }
+      });
+    }
+    return tools;
+  }
+};
 export {
   A2ARemoteAgent,
   Agent,
   AnthropicProvider,
   BaseVectorStore,
   EventBus,
+  GmailToolkit,
   GoogleEmbedding,
   GoogleProvider,
+  HackerNewsToolkit,
   InMemoryStorage,
   InMemoryVectorStore,
   KnowledgeBase,
@@ -4138,7 +4623,10 @@ export {
   Team,
   TeamMode,
   ToolExecutor,
+  Toolkit,
   VertexAIProvider,
+  WebSearchToolkit,
+  WhatsAppToolkit,
   Workflow,
   anthropic,
   defineTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radaros/core",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,7 +34,8 @@
     "ollama": "^0.5.0",
     "openai": "^4.0.0 || ^5.0.0 || ^6.0.0",
     "pg": "^8.0.0",
-    "@modelcontextprotocol/sdk": ">=1.0.0"
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "googleapis": ">=100.0.0"
   },
   "peerDependenciesMeta": {
     "openai": {
@@ -63,6 +64,9 @@
     },
     "@modelcontextprotocol/sdk": {
       "optional": true
+    },
+    "googleapis": {
+      "optional": true
     }
   }
 }

package/src/index.ts

@@ -135,3 +135,14 @@ export type {
   A2ASendParams,
   A2ATaskQueryParams,
 } from "./a2a/types.js";
+
+// Toolkits
+export { Toolkit } from "./toolkits/base.js";
+export { WebSearchToolkit } from "./toolkits/websearch.js";
+export type { WebSearchConfig } from "./toolkits/websearch.js";
+export { GmailToolkit } from "./toolkits/gmail.js";
+export type { GmailConfig } from "./toolkits/gmail.js";
+export { WhatsAppToolkit } from "./toolkits/whatsapp.js";
+export type { WhatsAppConfig } from "./toolkits/whatsapp.js";
+export { HackerNewsToolkit } from "./toolkits/hackernews.js";
+export type { HackerNewsConfig } from "./toolkits/hackernews.js";

package/src/toolkits/base.ts

@@ -0,0 +1,15 @@
+import type { ToolDef } from "../tools/types.js";
+
+/**
+ * Base class for all RadarOS Toolkits.
+ * A Toolkit is a collection of related tools that share configuration.
+ */
+export abstract class Toolkit {
+  abstract readonly name: string;
+
+  /**
+   * Returns all tools provided by this toolkit as ToolDef[].
+   * Spread them into an Agent's `tools` array.
+   */
+  abstract getTools(): ToolDef[];
+}