@hmawla/co-assistant 1.0.0

package/plugins/gmail/tools.ts

@@ -0,0 +1,336 @@
+/**
+ * @module gmail/tools
+ * @description Gmail AI tool definitions for searching, reading, and sending emails.
+ *
+ * Each tool calls the Gmail REST API directly using `fetch` and the access
+ * token obtained via {@link GmailAuth}. Tool handlers never throw — they
+ * return user-friendly error messages so the AI model can report failures
+ * gracefully.
+ */
+
+import { z } from "zod";
+import type { Logger } from "pino";
+import type { ToolDefinition } from "../../src/plugins/types.js";
+import type { GmailAuth } from "./auth.js";
+
+/** Base URL for the Gmail v1 REST API. */
+const GMAIL_API = "https://gmail.googleapis.com/gmail/v1/users/me";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an `Authorization` header using a fresh access token.
+ */
+async function authHeaders(auth: GmailAuth): Promise<Record<string, string>> {
+  const token = await auth.getAccessToken();
+  return { Authorization: `Bearer ${token}` };
+}
+
+/**
+ * Decode a base64url-encoded string (as returned by the Gmail API) to UTF-8.
+ *
+ * Gmail encodes message bodies using the URL-safe base64 variant defined in
+ * RFC 4648 §5 — i.e. `+` → `-` and `/` → `_`, with no padding.
+ */
+function decodeBase64Url(encoded: string): string {
+  const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  return Buffer.from(base64, "base64").toString("utf-8");
+}
+
+/**
+ * Encode a UTF-8 string to base64url (for sending raw RFC 2822 messages).
+ */
+function encodeBase64Url(text: string): string {
+  return Buffer.from(text, "utf-8")
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/**
+ * Extract a header value from a Gmail message resource.
+ */
+function getHeader(
+  headers: Array<{ name: string; value: string }>,
+  name: string,
+): string {
+  return headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+}
+
+/**
+ * Extract the plain-text body from a Gmail message payload.
+ *
+ * Gmail messages may be simple (body on the payload itself) or multipart.
+ * This function walks the MIME tree looking for `text/plain`, falling back
+ * to `text/html` when no plain-text part exists.
+ */
+function extractBody(payload: Record<string, unknown>): string {
+  // Simple (non-multipart) message — body is directly on the payload.
+  const body = payload.body as { data?: string; size?: number } | undefined;
+  if (body?.data) {
+    return decodeBase64Url(body.data);
+  }
+
+  // Multipart — walk parts looking for text/plain, then text/html.
+  const parts = (payload.parts ?? []) as Array<Record<string, unknown>>;
+  let htmlFallback = "";
+
+  for (const part of parts) {
+    const mimeType = part.mimeType as string | undefined;
+    const partBody = part.body as { data?: string } | undefined;
+
+    if (mimeType === "text/plain" && partBody?.data) {
+      return decodeBase64Url(partBody.data);
+    }
+    if (mimeType === "text/html" && partBody?.data) {
+      htmlFallback = decodeBase64Url(partBody.data);
+    }
+
+    // Recurse into nested multipart parts.
+    if (part.parts) {
+      const nested = extractBody(part as Record<string, unknown>);
+      if (nested) return nested;
+    }
+  }
+
+  return htmlFallback || "(no body)";
+}
+
+// ---------------------------------------------------------------------------
+// Tool Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the Gmail tool definitions.
+ *
+ * @param auth   - A configured {@link GmailAuth} instance for token management.
+ * @param logger - Plugin-scoped logger.
+ * @returns An array of {@link ToolDefinition} objects for the plugin manager.
+ */
+export function createGmailTools(auth: GmailAuth, logger: Logger): ToolDefinition[] {
+  // -----------------------------------------------------------------------
+  // search_emails
+  // -----------------------------------------------------------------------
+  const searchEmails: ToolDefinition = {
+    name: "search_emails",
+    description:
+      "Search for emails in Gmail using a query string (same syntax as the Gmail search bar)",
+    parameters: z.object({
+      /** Gmail search query (e.g. "from:alice subject:meeting"). */
+      query: z.string().describe("Gmail search query"),
+      /** Maximum number of results to return (default 10, max 50). */
+      maxResults: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .default(10)
+        .describe("Maximum number of results to return"),
+    }),
+
+    handler: async (args) => {
+      try {
+        const query = args.query as string;
+        const maxResults = (args.maxResults as number | undefined) ?? 10;
+        logger.debug({ query, maxResults }, "search_emails called");
+
+        // Step 1 — List message IDs matching the query.
+        const params = new URLSearchParams({
+          q: query,
+          maxResults: String(maxResults),
+        });
+        const listRes = await fetch(`${GMAIL_API}/messages?${params}`, {
+          headers: await authHeaders(auth),
+        });
+
+        if (!listRes.ok) {
+          const errText = await listRes.text();
+          logger.error({ status: listRes.status, errText }, "Gmail search failed");
+          return `Error searching emails (${listRes.status}): ${errText}`;
+        }
+
+        const listData = (await listRes.json()) as {
+          messages?: Array<{ id: string; threadId: string }>;
+          resultSizeEstimate?: number;
+        };
+
+        if (!listData.messages?.length) {
+          return "No emails found matching that query.";
+        }
+
+        // Step 2 — Fetch each message's metadata (Subject, From, Date, snippet).
+        const headers = await authHeaders(auth);
+        const results = await Promise.all(
+          listData.messages.map(async (msg) => {
+            const msgRes = await fetch(
+              `${GMAIL_API}/messages/${msg.id}?format=metadata&metadataHeaders=Subject&metadataHeaders=From&metadataHeaders=Date`,
+              { headers },
+            );
+
+            if (!msgRes.ok) {
+              return { id: msg.id, error: `Failed to fetch (${msgRes.status})` };
+            }
+
+            const msgData = (await msgRes.json()) as {
+              id: string;
+              snippet: string;
+              payload: { headers: Array<{ name: string; value: string }> };
+            };
+
+            return {
+              id: msgData.id,
+              subject: getHeader(msgData.payload.headers, "Subject"),
+              from: getHeader(msgData.payload.headers, "From"),
+              date: getHeader(msgData.payload.headers, "Date"),
+              snippet: msgData.snippet,
+            };
+          }),
+        );
+
+        return {
+          resultCount: results.length,
+          estimatedTotal: listData.resultSizeEstimate ?? results.length,
+          messages: results,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message }, "search_emails error");
+        return `Error searching emails: ${message}`;
+      }
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // read_email
+  // -----------------------------------------------------------------------
+  const readEmail: ToolDefinition = {
+    name: "read_email",
+    description: "Read the full content of a specific email by its message ID",
+    parameters: z.object({
+      /** The Gmail message ID (returned by search_emails). */
+      messageId: z.string().describe("Gmail message ID"),
+    }),
+
+    handler: async (args) => {
+      try {
+        const messageId = args.messageId as string;
+        logger.debug({ messageId }, "read_email called");
+
+        // Fetch the full message in "full" format to get decoded body parts.
+        const res = await fetch(`${GMAIL_API}/messages/${messageId}?format=full`, {
+          headers: await authHeaders(auth),
+        });
+
+        if (!res.ok) {
+          const errText = await res.text();
+          logger.error({ status: res.status, errText }, "Gmail read failed");
+          return `Error reading email (${res.status}): ${errText}`;
+        }
+
+        const data = (await res.json()) as {
+          id: string;
+          threadId: string;
+          labelIds: string[];
+          snippet: string;
+          payload: {
+            headers: Array<{ name: string; value: string }>;
+            body?: { data?: string };
+            parts?: Array<Record<string, unknown>>;
+            mimeType?: string;
+          };
+        };
+
+        const hdrs = data.payload.headers;
+        const body = extractBody(data.payload as Record<string, unknown>);
+
+        return {
+          id: data.id,
+          threadId: data.threadId,
+          labels: data.labelIds,
+          subject: getHeader(hdrs, "Subject"),
+          from: getHeader(hdrs, "From"),
+          to: getHeader(hdrs, "To"),
+          date: getHeader(hdrs, "Date"),
+          body,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message }, "read_email error");
+        return `Error reading email: ${message}`;
+      }
+    },
+  };
+
+  // -----------------------------------------------------------------------
+  // send_email
+  // -----------------------------------------------------------------------
+  const sendEmail: ToolDefinition = {
+    name: "send_email",
+    description: "Send an email via Gmail",
+    parameters: z.object({
+      /** Recipient email address. */
+      to: z.string().email().describe("Recipient email address"),
+      /** Email subject line. */
+      subject: z.string().describe("Email subject"),
+      /** Plain-text email body. */
+      body: z.string().describe("Email body (plain text)"),
+    }),
+
+    handler: async (args) => {
+      try {
+        const to = args.to as string;
+        const subject = args.subject as string;
+        const body = args.body as string;
+        logger.debug({ to, subject }, "send_email called");
+
+        // Build an RFC 2822 message and encode it as base64url.
+        const rfc2822 = [
+          `To: ${to}`,
+          `Subject: ${subject}`,
+          "Content-Type: text/plain; charset=UTF-8",
+          "MIME-Version: 1.0",
+          "",
+          body,
+        ].join("\r\n");
+
+        const raw = encodeBase64Url(rfc2822);
+
+        // POST the raw message to the Gmail send endpoint.
+        const res = await fetch(`${GMAIL_API}/messages/send`, {
+          method: "POST",
+          headers: {
+            ...(await authHeaders(auth)),
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ raw }),
+        });
+
+        if (!res.ok) {
+          const errText = await res.text();
+          logger.error({ status: res.status, errText }, "Gmail send failed");
+          return `Error sending email (${res.status}): ${errText}`;
+        }
+
+        const data = (await res.json()) as { id: string; threadId: string };
+        logger.info({ id: data.id, to }, "Email sent successfully");
+
+        return {
+          success: true,
+          messageId: data.id,
+          threadId: data.threadId,
+          message: `Email sent successfully to ${to}`,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error({ error: message }, "send_email error");
+        return `Error sending email: ${message}`;
+      }
+    },
+  };
+
+  return [searchEmails, readEmail, sendEmail];
+}

package/plugins/google-calendar/README.md

@@ -0,0 +1,51 @@
+# Google Calendar Plugin
+
+View, create, update, and delete Google Calendar events from your Co-Assistant bot.
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `list_events` | List upcoming events with optional date-range filtering |
+| `create_event` | Create a new calendar event with attendees and location |
+| `update_event` | Update an existing event by ID |
+| `delete_event` | Delete an event by ID |
+
+## Setup
+
+### 1. Create Google Cloud credentials
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project (or select an existing one).
+3. Configure the **OAuth consent screen** (APIs & Services → OAuth consent screen).
+   - Set to "External" for personal use, add your email as a test user.
+4. Navigate to **APIs & Services → Library** and enable the **Google Calendar API**.
+5. Go to **APIs & Services → Credentials** and create an **OAuth 2.0 Client ID**.
+   - Application type: **Desktop app** (recommended — allows automatic localhost redirect).
+6. Download the **client secret JSON file**.
+
+### 2. Run the setup wizard
+
+```bash
+npx tsx src/cli/index.ts setup --plugin google-calendar
+```
+
+The setup will:
+- Ask for your downloaded JSON file path (extracts credentials, does not store the file)
+- Open your browser to authorize Google Calendar access
+- Capture the refresh token automatically via a local callback server
+
+| Key | Description |
+|-----|-------------|
+| `GCAL_CLIENT_ID` | Google OAuth2 Client ID |
+| `GCAL_CLIENT_SECRET` | Google OAuth2 Client Secret |
+| `GCAL_REFRESH_TOKEN` | Google OAuth2 Refresh Token |
+
+## Usage Examples
+
+Once configured, the AI assistant can use natural language to manage your calendar:
+
+- *"What's on my calendar today?"*
+- *"Schedule a meeting with alice@example.com tomorrow at 2 PM for one hour."*
+- *"Update event abc123 to start at 3 PM instead."*
+- *"Delete the event with ID xyz789."*

package/plugins/google-calendar/auth.ts

@@ -0,0 +1,92 @@
+/**
+ * @module google-calendar/auth
+ * @description Google Calendar OAuth2 authentication handler.
+ *
+ * Manages access-token refresh via the Google OAuth2 token endpoint.
+ * Tokens are cached in memory and automatically refreshed when they
+ * expire (with a 60-second safety margin).
+ */
+
+/** Google OAuth2 token endpoint. */
+const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+
+/** Safety margin (ms) subtracted from `expires_in` to avoid edge-case expiry. */
+const EXPIRY_MARGIN_MS = 60_000;
+
+/**
+ * Lightweight Google OAuth2 helper that handles the refresh-token flow.
+ *
+ * @example
+ * ```ts
+ * const auth = new CalendarAuth(clientId, clientSecret, refreshToken);
+ * const token = await auth.getAccessToken();
+ * ```
+ */
+export class CalendarAuth {
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  private readonly refreshToken: string;
+
+  private accessToken: string | null = null;
+  private expiresAt = 0;
+
+  constructor(clientId: string, clientSecret: string, refreshToken: string) {
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.refreshToken = refreshToken;
+  }
+
+  /**
+   * Check whether all required credentials have been provided.
+   */
+  isConfigured(): boolean {
+    return Boolean(this.clientId && this.clientSecret && this.refreshToken);
+  }
+
+  /**
+   * Return a valid access token, refreshing it first if necessary.
+   *
+   * @throws {Error} If credentials are missing or the token exchange fails.
+   */
+  async getAccessToken(): Promise<string> {
+    if (!this.isConfigured()) {
+      throw new Error(
+        "CalendarAuth is not configured — client ID, client secret, and refresh token are all required.",
+      );
+    }
+
+    if (this.accessToken && Date.now() < this.expiresAt) {
+      return this.accessToken;
+    }
+
+    const body = new URLSearchParams({
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      refresh_token: this.refreshToken,
+      grant_type: "refresh_token",
+    });
+
+    const response = await fetch(TOKEN_ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(
+        `Failed to refresh Google access token (${response.status}): ${text}`,
+      );
+    }
+
+    const data = (await response.json()) as {
+      access_token: string;
+      expires_in: number;
+    };
+
+    this.accessToken = data.access_token;
+    this.expiresAt = Date.now() + data.expires_in * 1000 - EXPIRY_MARGIN_MS;
+
+    return this.accessToken;
+  }
+}

package/plugins/google-calendar/index.ts

@@ -0,0 +1,82 @@
+/**
+ * @module google-calendar
+ * @description Google Calendar plugin — view, create, update, and delete
+ * calendar events via the Google Calendar v3 API.
+ *
+ * This is a reference implementation showing how to build a fully-featured
+ * Co-Assistant plugin with OAuth2 authentication and multiple tool definitions.
+ */
+
+import type {
+  CoAssistantPlugin,
+  PluginContext,
+  PluginFactory,
+  ToolDefinition,
+} from "../../src/plugins/types.js";
+import { CalendarAuth } from "./auth.js";
+import { createCalendarTools } from "./tools.js";
+
+/**
+ * Factory function that creates a new Google Calendar plugin instance.
+ *
+ * This is the default export expected by the plugin loader (see
+ * {@link PluginFactory}).
+ */
+const createPlugin: PluginFactory = (): CoAssistantPlugin => {
+  let auth: CalendarAuth;
+  let tools: ToolDefinition[] = [];
+  let logger: PluginContext["logger"];
+
+  return {
+    id: "google-calendar",
+    name: "Google Calendar Plugin",
+    version: "1.0.0",
+    description: "View, create, and manage Google Calendar events",
+    requiredCredentials: [
+      "GCAL_CLIENT_ID",
+      "GCAL_CLIENT_SECRET",
+      "GCAL_REFRESH_TOKEN",
+    ],
+
+    async initialize(context: PluginContext): Promise<void> {
+      logger = context.logger;
+      logger.info("Initialising Google Calendar plugin…");
+
+      auth = new CalendarAuth(
+        context.credentials.GCAL_CLIENT_ID,
+        context.credentials.GCAL_CLIENT_SECRET,
+        context.credentials.GCAL_REFRESH_TOKEN,
+      );
+
+      if (!auth.isConfigured()) {
+        throw new Error(
+          "Google Calendar plugin is missing one or more required credentials.",
+        );
+      }
+
+      tools = createCalendarTools(auth);
+      logger.info(`Registered ${tools.length} calendar tools`);
+    },
+
+    getTools(): ToolDefinition[] {
+      return tools;
+    },
+
+    async destroy(): Promise<void> {
+      tools = [];
+      logger?.info("Google Calendar plugin destroyed");
+    },
+
+    async healthCheck(): Promise<boolean> {
+      try {
+        // A lightweight token refresh confirms the credentials are still valid.
+        await auth.getAccessToken();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+};
+
+export default createPlugin;

package/plugins/google-calendar/plugin.json

@@ -0,0 +1,13 @@
+{
+  "id": "google-calendar",
+  "name": "Google Calendar Plugin",
+  "version": "1.0.0",
+  "description": "View, create, and manage Google Calendar events",
+  "author": "co-assistant",
+  "requiredCredentials": [
+    { "key": "GCAL_CLIENT_ID", "description": "Google OAuth2 Client ID", "type": "oauth" },
+    { "key": "GCAL_CLIENT_SECRET", "description": "Google OAuth2 Client Secret", "type": "oauth" },
+    { "key": "GCAL_REFRESH_TOKEN", "description": "Google OAuth2 Refresh Token", "type": "oauth" }
+  ],
+  "dependencies": []
+}