@radaros/core 0.3.0 → 0.3.1

package/src/toolkits/gmail.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { createRequire } from "node:module";
+import type { ToolDef } from "../tools/types.js";
+import type { RunContext } from "../agent/run-context.js";
+import { Toolkit } from "./base.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface GmailConfig {
+  /** Path to OAuth2 credentials JSON file. Falls back to GMAIL_CREDENTIALS_PATH env var. */
+  credentialsPath?: string;
+  /** Path to saved token JSON file. Falls back to GMAIL_TOKEN_PATH env var. */
+  tokenPath?: string;
+  /** Pre-authenticated OAuth2 client (if you handle auth yourself). */
+  authClient?: any;
+}
+
+/**
+ * Gmail Toolkit — send, search, and read emails from your agent.
+ *
+ * Requires: npm install googleapis
+ *
+ * @example
+ * ```ts
+ * const gmail = new GmailToolkit({ credentialsPath: "./credentials.json", tokenPath: "./token.json" });
+ * const agent = new Agent({ tools: [...gmail.getTools()] });
+ * ```
+ */
+export class GmailToolkit extends Toolkit {
+  readonly name = "gmail";
+  private config: GmailConfig;
+  private gmail: any = null;
+
+  constructor(config: GmailConfig = {}) {
+    super();
+    this.config = config;
+  }
+
+  private async getGmailClient(): Promise<any> {
+    if (this.gmail) return this.gmail;
+
+    if (this.config.authClient) {
+      const { google } = _require("googleapis");
+      this.gmail = google.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 } = _require("googleapis");
+    const fs = await import("node: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 google.auth.OAuth2(
+      client_id,
+      client_secret,
+      redirect_uris?.[0]
+    );
+    oAuth2.setCredentials(token);
+
+    this.gmail = google.gmail({ version: "v1", auth: oAuth2 });
+    return this.gmail;
+  }
+
+  getTools(): ToolDef[] {
+    const self = this;
+
+    return [
+      {
+        name: "gmail_send",
+        description:
+          "Send an email via Gmail. Provide recipient, subject, and body.",
+        parameters: z.object({
+          to: z.string().describe("Recipient email address"),
+          subject: z.string().describe("Email subject line"),
+          body: z.string().describe("Email body (plain text)"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          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: z.object({
+          query: z
+            .string()
+            .describe(
+              'Gmail search query (e.g. "from:john subject:meeting is:unread")'
+            ),
+          maxResults: z
+            .number()
+            .optional()
+            .describe("Maximum number of results (default 10)"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          const gmail = await self.getGmailClient();
+          const max = (args.maxResults as number) ?? 10;
+
+          const list = await gmail.users.messages.list({
+            userId: "me",
+            q: args.query as string,
+            maxResults: max,
+          });
+
+          const messages = list.data.messages ?? [];
+          if (messages.length === 0) return "No emails found.";
+
+          const results: string[] = [];
+          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: string) =>
+              headers.find(
+                (h: any) => h.name.toLowerCase() === name.toLowerCase()
+              )?.value ?? "";
+
+            results.push(
+              `ID: ${msg.id}\nFrom: ${getHeader("From")}\nSubject: ${getHeader("Subject")}\nDate: ${getHeader("Date")}\nSnippet: ${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: z.object({
+          messageId: z.string().describe("The Gmail message ID to read"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          const gmail = await self.getGmailClient();
+
+          const detail = await gmail.users.messages.get({
+            userId: "me",
+            id: args.messageId as string,
+            format: "full",
+          });
+
+          const headers = detail.data.payload?.headers ?? [];
+          const getHeader = (name: string) =>
+            headers.find(
+              (h: any) => 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: any) => 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: any) => p.mimeType === "text/html"
+              );
+              if (htmlPart?.body?.data) {
+                body = Buffer.from(htmlPart.body.data, "base64").toString(
+                  "utf-8"
+                );
+              }
+            }
+          }
+
+          return `From: ${getHeader("From")}\nTo: ${getHeader("To")}\nSubject: ${getHeader("Subject")}\nDate: ${getHeader("Date")}\n\n${body || "(no body)"}`;
+        },
+      },
+    ];
+  }
+}

package/src/toolkits/hackernews.ts

@@ -0,0 +1,121 @@
+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 HackerNewsConfig {
+  /** Enable fetching top stories (default true). */
+  enableGetTopStories?: boolean;
+  /** Enable fetching user details (default true). */
+  enableGetUserDetails?: boolean;
+}
+
+/**
+ * Hacker News Toolkit — search top stories and user details from HN.
+ *
+ * No API key required — uses the public Hacker News API.
+ *
+ * @example
+ * ```ts
+ * const hn = new HackerNewsToolkit();
+ * const agent = new Agent({ tools: [...hn.getTools()] });
+ * ```
+ */
+export class HackerNewsToolkit extends Toolkit {
+  readonly name = "hackernews";
+  private config: HackerNewsConfig;
+
+  constructor(config: HackerNewsConfig = {}) {
+    super();
+    this.config = {
+      enableGetTopStories: config.enableGetTopStories ?? true,
+      enableGetUserDetails: config.enableGetUserDetails ?? true,
+    };
+  }
+
+  getTools(): ToolDef[] {
+    const tools: ToolDef[] = [];
+
+    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: z.object({
+          numStories: z
+            .number()
+            .optional()
+            .describe("Number of top stories to fetch (default 10, max 30)"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          const num = Math.min((args.numStories as number) ?? 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()) as number[];
+
+          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() as Promise<any>;
+            })
+          );
+
+          return stories
+            .map(
+              (s, i) =>
+                `${i + 1}. ${s.title}\n   URL: ${s.url ?? `https://news.ycombinator.com/item?id=${s.id}`}\n   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: z.object({
+          username: z.string().describe("The HN username to look up"),
+        }),
+        execute: async (
+          args: Record<string, unknown>,
+          _ctx: RunContext
+        ): Promise<string> => {
+          const username = args.username as string;
+          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()) as any;
+          if (!user) return `User "${username}" not found.`;
+
+          const created = new Date(user.created * 1000).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;
+  }
+}

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.";
+  }
+}