@radaros/core 0.3.0 → 0.3.2

package/src/toolkits/websearch.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+import type { ToolDef } from "../tools/types.js";
+import type { RunContext } from "../agent/run-context.js";
+import { Toolkit } from "./base.js";
+
+export interface WebSearchConfig {
+  /** Search provider: "tavily" or "serpapi". */
+  provider: "tavily" | "serpapi";
+  /** API key for the search provider. Falls back to TAVILY_API_KEY or SERPAPI_API_KEY env vars. */
+  apiKey?: string;
+  /** Max results to return per search (default 5). */
+  maxResults?: number;
+}
+
+/**
+ * Web Search Toolkit — search the web from your agent.
+ *
+ * Supports Tavily and SerpAPI backends.
+ *
+ * @example
+ * ```ts
+ * const search = new WebSearchToolkit({ provider: "tavily" });
+ * const agent = new Agent({ tools: [...search.getTools()] });
+ * ```
+ */
+export class WebSearchToolkit extends Toolkit {
+  readonly name = "websearch";
+  private config: WebSearchConfig;
+
+  constructor(config: WebSearchConfig) {
+    super();
+    this.config = config;
+  }
+
+  private getApiKey(): string {
+    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(): ToolDef[] {
+    const self = this;
+
+    return [
+      {
+        name: "web_search",
+        description:
+          "Search the web for current information. Returns titles, URLs, and snippets from search results.",
+        parameters: z.object({
+          query: z.string().describe("The search query"),
+          maxResults: z
+            .number()
+            .optional()
+            .describe("Maximum number of results (default 5)"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          const query = args.query as string;
+          const max =
+            (args.maxResults as number) ?? self.config.maxResults ?? 5;
+
+          if (self.config.provider === "tavily") {
+            return self.searchTavily(query, max);
+          }
+          return self.searchSerpApi(query, max);
+        },
+      },
+    ];
+  }
+
+  private async searchTavily(
+    query: string,
+    maxResults: number
+  ): Promise<string> {
+    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()) as any;
+    const results: string[] = [];
+
+    if (data.answer) {
+      results.push(`Answer: ${data.answer}\n`);
+    }
+
+    for (const r of data.results ?? []) {
+      results.push(`Title: ${r.title}\nURL: ${r.url}\nSnippet: ${r.content}\n`);
+    }
+
+    return results.join("\n---\n") || "No results found.";
+  }
+
+  private async searchSerpApi(
+    query: string,
+    maxResults: number
+  ): Promise<string> {
+    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()) as any;
+    const results: string[] = [];
+
+    if (data.answer_box?.answer) {
+      results.push(`Answer: ${data.answer_box.answer}\n`);
+    }
+
+    for (const r of (data.organic_results ?? []).slice(0, maxResults)) {
+      results.push(
+        `Title: ${r.title}\nURL: ${r.link}\nSnippet: ${r.snippet ?? ""}\n`
+      );
+    }
+
+    return results.join("\n---\n") || "No results found.";
+  }
+}

package/src/toolkits/whatsapp.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import type { ToolDef } from "../tools/types.js";
+import type { RunContext } from "../agent/run-context.js";
+import { Toolkit } from "./base.js";
+
+export interface WhatsAppConfig {
+  /** WhatsApp Business API access token. Falls back to WHATSAPP_ACCESS_TOKEN env var. */
+  accessToken?: string;
+  /** WhatsApp Business phone number ID. Falls back to WHATSAPP_PHONE_NUMBER_ID env var. */
+  phoneNumberId?: string;
+  /** API version (default "v22.0"). Falls back to WHATSAPP_VERSION env var. */
+  version?: string;
+  /** Default recipient WhatsApp ID. Falls back to WHATSAPP_RECIPIENT_WAID env var. */
+  recipientWaid?: string;
+}
+
+/**
+ * WhatsApp Toolkit — send messages via WhatsApp Business Cloud API (Meta).
+ *
+ * Uses the WhatsApp Cloud API directly (no Twilio).
+ * Setup: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
+ *
+ * @example
+ * ```ts
+ * const whatsapp = new WhatsAppToolkit({
+ *   accessToken: "...",
+ *   phoneNumberId: "...",
+ * });
+ * const agent = new Agent({ tools: [...whatsapp.getTools()] });
+ * ```
+ */
+export class WhatsAppToolkit extends Toolkit {
+  readonly name = "whatsapp";
+  private accessToken: string;
+  private phoneNumberId: string;
+  private version: string;
+  private recipientWaid: string | undefined;
+
+  constructor(config: WhatsAppConfig = {}) {
+    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;
+  }
+
+  private getBaseUrl(): string {
+    return `https://graph.facebook.com/${this.version}/${this.phoneNumberId}/messages`;
+  }
+
+  private validate(): void {
+    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."
+      );
+    }
+  }
+
+  private resolveRecipient(recipient?: string): string {
+    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(): ToolDef[] {
+    const self = this;
+
+    return [
+      {
+        name: "whatsapp_send_text",
+        description:
+          "Send a text message to a WhatsApp user via WhatsApp Business Cloud API.",
+        parameters: z.object({
+          text: z.string().describe("The text message to send"),
+          recipient: z
+            .string()
+            .optional()
+            .describe(
+              "Recipient WhatsApp number with country code (e.g. 919876543210). Uses default if omitted."
+            ),
+          previewUrl: z
+            .boolean()
+            .optional()
+            .describe("Enable URL previews in the message (default false)"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          self.validate();
+          const recipient = self.resolveRecipient(args.recipient as string);
+
+          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 as boolean) ?? false,
+                body: args.text as string,
+              },
+            }),
+          });
+
+          if (!res.ok) {
+            const err = await res.text();
+            throw new Error(
+              `WhatsApp send failed: ${res.status} ${err}`
+            );
+          }
+
+          const data = (await res.json()) as any;
+          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: z.object({
+          templateName: z
+            .string()
+            .describe(
+              'The pre-approved template name (e.g. "hello_world")'
+            ),
+          recipient: z
+            .string()
+            .optional()
+            .describe(
+              "Recipient WhatsApp number with country code. Uses default if omitted."
+            ),
+          languageCode: z
+            .string()
+            .optional()
+            .describe('Template language code (default "en_US")'),
+          components: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe(
+              "Template components for dynamic content (header, body, button parameters)"
+            ),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          self.validate();
+          const recipient = self.resolveRecipient(args.recipient as string);
+          const langCode = (args.languageCode as string) ?? "en_US";
+
+          const template: Record<string, unknown> = {
+            name: args.templateName as string,
+            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()) as any;
+          const msgId = data.messages?.[0]?.id ?? "unknown";
+          return `Template message "${args.templateName}" sent to ${recipient}. Message ID: ${msgId}`;
+        },
+      },
+    ];
+  }
+}