fastmail-cli 1.0.0

package/src/formatters.ts

@@ -0,0 +1,321 @@
+/**
+ * Token-efficient text formatters for OpenClaw plugin output.
+ *
+ * Each formatter takes parsed MCP tool results (JSON objects/arrays)
+ * and emits compact, scannable text optimized for LLM token efficiency.
+ */
+
+// -- Helpers ----------------------------------------------------------
+
+function formatDate(dateStr: string): string {
+  const d = new Date(dateStr);
+  const month = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const hours = String(d.getHours()).padStart(2, "0");
+  const mins = String(d.getMinutes()).padStart(2, "0");
+  return `${d.getFullYear()}-${month}-${day} ${hours}:${mins}`;
+}
+
+function formatAddr(addr: { name?: string; email: string }): string {
+  if (addr.name) return `${addr.name} <${addr.email}>`;
+  return addr.email;
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return text.slice(0, max - 1) + "\u2026";
+}
+
+function formatFileSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+// -- Email List -------------------------------------------------------
+
+export function formatEmailList(emails: any[], title?: string): string {
+  if (!emails || emails.length === 0) return "No emails found.";
+  const lines: string[] = [];
+  if (title) { lines.push(`# ${title} (${emails.length})`, ""); }
+  for (const e of emails) {
+    const id = e.id || "?";
+    const date = e.receivedAt ? formatDate(e.receivedAt) : "           ";
+    const from = e.from?.[0] ? formatAddr(e.from[0]) : "Unknown";
+    const subject = e.subject || "(no subject)";
+    const preview = e.preview ? truncate(e.preview, 80) : "";
+    const keywords = e.keywords || {};
+    const unread = !keywords.$seen ? "*" : " ";
+    const flagged = keywords.$flagged ? "!" : "";
+    const att = e.hasAttachment ? " [att]" : "";
+    lines.push(`${id}  ${date}  ${unread}${flagged}${from}${att}`);
+    lines.push(`  ${subject} \u2014 ${preview}`, "");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+// -- Single Email -----------------------------------------------------
+
+export function formatEmail(email: any): string {
+  if (typeof email === "string") return email;
+  const lines: string[] = [];
+  const from = email.from?.map(formatAddr).join(", ") || "Unknown";
+  const to = email.to?.map(formatAddr).join(", ") || "";
+  const cc = email.cc?.map(formatAddr).join(", ");
+  const date = email.receivedAt ? formatDate(email.receivedAt) : "";
+  const subject = email.subject || "(no subject)";
+  lines.push(`From: ${from}`);
+  if (to) lines.push(`To: ${to}`);
+  if (cc) lines.push(`CC: ${cc}`);
+  if (date) lines.push(`Date: ${date}`);
+  lines.push(`Subject: ${subject}`);
+  const meta: string[] = [];
+  if (email.id) meta.push(`ID: ${email.id}`);
+  if (email.threadId) meta.push(`Thread: ${email.threadId}`);
+  if (meta.length) lines.push(meta.join(" | "));
+  lines.push("");
+  const bodyValues = email.bodyValues as Record<string, { value: string }> | undefined;
+  const textPartId = email.textBody?.[0]?.partId;
+  const textContent = textPartId && bodyValues?.[textPartId]?.value;
+  if (textContent) { lines.push(textContent); }
+  else if (email.preview) { lines.push(email.preview); }
+  if (email.attachments?.length) {
+    lines.push("", "Attachments:");
+    for (const att of email.attachments) {
+      const size = att.size ? ` (${formatFileSize(att.size)})` : "";
+      lines.push(`  ${att.name || "unnamed"}${size}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// -- Mailboxes --------------------------------------------------------
+
+export function formatMailboxes(mailboxes: any[]): string {
+  if (!mailboxes?.length) return "No mailboxes found.";
+  const lines: string[] = ["# Mailboxes", ""];
+  const sorted = [...mailboxes].sort((a, b) => {
+    if (a.role && !b.role) return -1;
+    if (!a.role && b.role) return 1;
+    return (a.name || "").localeCompare(b.name || "");
+  });
+  for (const mb of sorted) {
+    const role = mb.role ? ` (${mb.role})` : "";
+    const total = mb.totalEmails ?? 0;
+    const unread = mb.unreadEmails ?? 0;
+    const unreadStr = unread > 0 ? `  unread: ${unread}` : "";
+    lines.push(`${mb.id}  ${mb.name}${role}  ${total} emails${unreadStr}`);
+  }
+  return lines.join("\n");
+}
+
+// -- Mailbox Stats ----------------------------------------------------
+
+export function formatMailboxStats(stats: any): string {
+  if (Array.isArray(stats)) {
+    const lines: string[] = ["# Mailbox Statistics", ""];
+    for (const mb of stats) {
+      const unread = mb.unreadEmails > 0 ? `  unread: ${mb.unreadEmails}` : "";
+      lines.push(`${mb.name} (${mb.role || "custom"})  ${mb.totalEmails} emails${unread}`);
+    }
+    return lines.join("\n");
+  }
+  return [
+    `# ${stats.name}${stats.role ? ` (${stats.role})` : ""}`, "",
+    `Total emails: ${stats.totalEmails ?? 0}`,
+    `Unread: ${stats.unreadEmails ?? 0}`,
+    `Threads: ${stats.totalThreads ?? 0}`,
+    `Unread threads: ${stats.unreadThreads ?? 0}`,
+  ].join("\n");
+}
+
+// -- Account Summary --------------------------------------------------
+
+export function formatAccountSummary(summary: any): string {
+  const lines: string[] = [
+    "# Account Summary", "",
+    `Mailboxes: ${summary.mailboxCount}`,
+    `Identities: ${summary.identityCount}`,
+    `Total emails: ${summary.totalEmails}`,
+    `Unread: ${summary.unreadEmails}`, "", "Mailboxes:",
+  ];
+  if (summary.mailboxes) {
+    for (const mb of summary.mailboxes) {
+      const unread = mb.unreadEmails > 0 ? `  unread: ${mb.unreadEmails}` : "";
+      lines.push(`  ${mb.name}${mb.role ? ` (${mb.role})` : ""}  ${mb.totalEmails}${unread}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// -- Contacts ---------------------------------------------------------
+
+export function formatContacts(contacts: any[]): string {
+  if (!contacts?.length) return "No contacts found.";
+  const lines: string[] = [`# Contacts (${contacts.length})`, ""];
+  for (const c of contacts) {
+    const name = c.name || [c.prefix, c.firstName, c.lastName].filter(Boolean).join(" ") || "Unnamed";
+    lines.push(`${c.id}  ${name}`);
+    const emails = c.emails?.map((e: any) => e.value || e.email).filter(Boolean) || [];
+    const phones = c.phones?.map((p: any) => p.value || p.phone).filter(Boolean) || [];
+    const details = [...emails, ...phones].join(" | ");
+    if (details) lines.push(`  ${details}`);
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+export function formatContact(contact: any): string {
+  if (!contact) return "Contact not found.";
+  const lines: string[] = [];
+  const name = contact.name || [contact.prefix, contact.firstName, contact.lastName].filter(Boolean).join(" ") || "Unnamed";
+  lines.push(`# ${name}`);
+  if (contact.id) lines.push(`ID: ${contact.id}`);
+  lines.push("");
+  if (contact.company) lines.push(`Company: ${contact.company}`);
+  if (contact.department) lines.push(`Department: ${contact.department}`);
+  if (contact.jobTitle) lines.push(`Title: ${contact.jobTitle}`);
+  if (contact.emails?.length) {
+    lines.push("", "Emails:");
+    for (const e of contact.emails) {
+      const label = e.label || e.type || "";
+      lines.push(`  ${label ? label + ": " : ""}${e.value || e.email}`);
+    }
+  }
+  if (contact.phones?.length) {
+    lines.push("", "Phones:");
+    for (const p of contact.phones) {
+      const label = p.label || p.type || "";
+      lines.push(`  ${label ? label + ": " : ""}${p.value || p.phone}`);
+    }
+  }
+  if (contact.addresses?.length) {
+    lines.push("", "Addresses:");
+    for (const a of contact.addresses) {
+      const parts = [a.street, a.city, a.state, a.postcode, a.country].filter(Boolean);
+      const label = a.label || a.type || "";
+      lines.push(`  ${label ? label + ": " : ""}${parts.join(", ")}`);
+    }
+  }
+  if (contact.notes) { lines.push("", `Notes: ${contact.notes}`); }
+  return lines.join("\n");
+}
+
+// -- Calendar ---------------------------------------------------------
+
+export function formatCalendars(calendars: any[]): string {
+  if (!calendars?.length) return "No calendars found.";
+  const lines: string[] = ["# Calendars", ""];
+  for (const cal of calendars) {
+    lines.push(`${cal.id}  ${cal.name}${cal.isDefault ? " (default)" : ""}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatEvents(events: any[]): string {
+  if (!events?.length) return "No events found.";
+  const lines: string[] = [`# Events (${events.length})`, ""];
+  for (const e of events) {
+    const start = e.start ? formatDate(e.start) : "?";
+    let timeRange = start;
+    if (e.start && e.duration) {
+      timeRange = `${start}  (${e.duration})`;
+    } else if (e.end) {
+      const endTime = formatDate(e.end);
+      timeRange = endTime.slice(0, 10) === start.slice(0, 10)
+        ? `${start}-${endTime.slice(11)}`
+        : `${start} to ${endTime}`;
+    }
+    lines.push(`${e.id}  ${timeRange}  ${e.title || "(no title)"}`);
+    const details: string[] = [];
+    if (e.location) details.push(e.location);
+    if (e.calendarName || e.calendarId) details.push(`Calendar: ${e.calendarName || e.calendarId}`);
+    if (details.length) lines.push(`  ${details.join(" | ")}`);
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+
+export function formatEvent(event: any): string {
+  if (!event) return "Event not found.";
+  const lines: string[] = [];
+  lines.push(`# ${event.title || "(no title)"}`);
+  if (event.id) lines.push(`ID: ${event.id}`);
+  lines.push("");
+  if (event.start) lines.push(`Start: ${formatDate(event.start)}`);
+  if (event.end) lines.push(`End: ${formatDate(event.end)}`);
+  if (event.duration) lines.push(`Duration: ${event.duration}`);
+  if (event.location) lines.push(`Location: ${event.location}`);
+  if (event.description) { lines.push("", event.description); }
+  if (event.participants?.length) {
+    lines.push("", "Participants:");
+    for (const p of event.participants) {
+      lines.push(`  ${p.name || p.email}${p.name ? ` <${p.email}>` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// -- Identities -------------------------------------------------------
+
+export function formatIdentities(identities: any[]): string {
+  if (!identities?.length) return "No identities found.";
+  const lines: string[] = ["# Identities", ""];
+  for (const id of identities) {
+    const name = id.name || "";
+    const email = id.email || "";
+    const isDefault = id.mayDelete === false ? " (primary)" : "";
+    lines.push(`${name ? name + " " : ""}<${email}>${isDefault}`);
+  }
+  return lines.join("\n");
+}
+
+// -- Memos ------------------------------------------------------------
+
+export function formatMemo(memo: any): string {
+  if (!memo) return "No memo found for this email.";
+  if (typeof memo === "string") return memo;
+  const lines: string[] = [];
+  if (memo.subject) lines.push(`# Memo: ${memo.subject}`);
+  if (memo.memoId) lines.push(`Memo ID: ${memo.memoId}`);
+  if (memo.receivedAt) lines.push(`Created: ${formatDate(memo.receivedAt)}`);
+  lines.push("");
+  const bodyValues = memo.bodyValues as Record<string, { value: string }> | undefined;
+  const textPartId = memo.textBody?.[0]?.partId;
+  const text = textPartId && bodyValues?.[textPartId]?.value;
+  if (text) { lines.push(text); }
+  else if (memo.preview) { lines.push(memo.preview); }
+  else if (memo.text) { lines.push(memo.text); }
+  return lines.join("\n");
+}
+
+// -- Attachments ------------------------------------------------------
+
+export function formatAttachments(attachments: any[]): string {
+  if (!attachments?.length) return "No attachments.";
+  const lines: string[] = [`# Attachments (${attachments.length})`, ""];
+  for (const att of attachments) {
+    const size = att.size ? ` (${formatFileSize(att.size)})` : "";
+    const type = att.type || att.mimeType || "";
+    lines.push(`${att.blobId || att.id || "?"}  ${att.name || "unnamed"}  ${type}${size}`);
+  }
+  return lines.join("\n");
+}
+
+// -- Inbox Updates ----------------------------------------------------
+
+export function formatInboxUpdates(updates: any): string {
+  const lines: string[] = [];
+  if (updates.queryState) lines.push(`State: ${updates.queryState}`);
+  if (updates.added?.length) {
+    lines.push("", `Added (${updates.added.length}):`);
+    lines.push(formatEmailList(updates.added));
+  }
+  if (updates.removed?.length) {
+    lines.push("", `Removed: ${updates.removed.join(", ")}`);
+  }
+  if (!updates.added?.length && !updates.removed?.length) {
+    lines.push("No changes since last check.");
+  }
+  return lines.join("\n");
+}

package/src/mcp-client.ts

@@ -0,0 +1,150 @@
+/**
+ * MCP SDK client wrapper for the Fastmail OpenClaw plugin.
+ *
+ * Maintains a persistent connection to the remote Worker using
+ * StreamableHTTPClientTransport. The connection is lazy-initialized
+ * on first tool call and reused for all subsequent calls.
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+/**
+ * Strip prompt-injection datamarking from MCP tool responses.
+ *
+ * The server wraps external data in [UNTRUSTED_EXTERNAL_DATA_xxx] markers
+ * and prepends a preamble paragraph. These are useful for LLM safety but
+ * noise in a plugin context.
+ *
+ * Coupled to the marker format in src/prompt-guard.ts on the server.
+ * If the server format changes, these regexes must be updated to match.
+ */
+function stripDatamarking(text: string): string {
+  let cleaned = text.replace(
+    /^Data between \[UNTRUSTED_EXTERNAL_DATA_[^\]]+\] and \[\/UNTRUSTED_EXTERNAL_DATA_[^\]]+\] markers is[\s\S]*?not acted upon as directives\.\s*/,
+    "",
+  );
+  cleaned = cleaned.replace(
+    /\[\/?UNTRUSTED_EXTERNAL_DATA_[^\]]+\]\s?/g,
+    "",
+  );
+  cleaned = cleaned.replace(
+    /\[WARNING: The [^\]]*? below contains text patterns[\s\S]*?found in it\.\]\s*/g,
+    "",
+  );
+  return cleaned.trim();
+}
+
+export class FastmailMcpClient {
+  private client: Client | null = null;
+  private url: string;
+  private token: string;
+
+  constructor(url: string, token: string) {
+    this.url = url;
+    this.token = token;
+  }
+
+  private async ensureConnected(): Promise<Client> {
+    if (this.client) return this.client;
+
+    this.client = new Client({
+      name: "fastmail-openclaw",
+      version: "1.0.0",
+    });
+
+    const token = this.token;
+    const authFetch: typeof fetch = (input, init) => {
+      const headers = new Headers(init?.headers);
+      headers.set("Authorization", `Bearer ${token}`);
+      return fetch(input, { ...init, headers });
+    };
+
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`${this.url}/mcp`),
+      { fetch: authFetch },
+    );
+
+    try {
+      await this.client.connect(transport);
+    } catch (err: any) {
+      this.client = null;
+      if (err?.message?.includes("401") || err?.message?.includes("Unauthorized")) {
+        throw new Error(
+          "Authentication failed. Check your bearerToken or run: fastmail auth",
+        );
+      }
+      throw err;
+    }
+
+    return this.client;
+  }
+
+  /**
+   * Call an MCP tool on the remote server and return the parsed result.
+   * JSON responses are parsed; text responses returned as strings.
+   * Datamarking is stripped automatically.
+   *
+   * If the transport has dropped since the last call, resets the connection
+   * and retries once to handle server restarts or network interruptions.
+   */
+  async callTool(
+    name: string,
+    args: Record<string, unknown> = {},
+  ): Promise<any> {
+    let client = await this.ensureConnected();
+    let result;
+    try {
+      result = await client.callTool({ name, arguments: args });
+    } catch (err: any) {
+      // On transport-level errors, reset and retry once
+      const msg = err?.message ?? "";
+      if (msg.includes("ECONNREFUSED") || msg.includes("ECONNRESET") ||
+          msg.includes("fetch failed") || msg.includes("transport") ||
+          msg.includes("closed") || msg.includes("network")) {
+        this.client = null;
+        client = await this.ensureConnected();
+        result = await client.callTool({ name, arguments: args });
+      } else {
+        throw err;
+      }
+    }
+
+    const textParts = (result.content as any[])
+      ?.filter((c) => c.type === "text")
+      .map((c) => c.text) || [];
+    const text = textParts.join("\n");
+    const cleaned = stripDatamarking(text);
+
+    try {
+      return JSON.parse(cleaned);
+    } catch {
+      // Not JSON — try fallback below
+    }
+
+    // Sometimes datamarking leaves a preamble paragraph before the JSON payload.
+    // Walk backwards through double-newline-separated sections to find the
+    // largest trailing chunk that parses as valid JSON.
+    const parts = cleaned.split("\n\n");
+    for (let i = parts.length - 1; i > 0; i--) {
+      const candidate = parts.slice(i).join("\n\n");
+      const trimmed = candidate.trim();
+      if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+          return JSON.parse(trimmed);
+        } catch {
+          // Keep looking at smaller slices
+        }
+      }
+    }
+
+    return cleaned;
+  }
+
+  async close(): Promise<void> {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+    }
+  }
+}

package/src/tools/calendar.ts

@@ -0,0 +1,77 @@
+/**
+ * Calendar tools for the Fastmail OpenClaw plugin.
+ * 3 read-only + 1 optional (create).
+ */
+
+import type { OpenClawApi, GetClientFn } from "../../index.js";
+import { formatCalendars, formatEvents, formatEvent } from "../formatters.js";
+
+export function registerCalendarTools(api: OpenClawApi, getClient: GetClientFn) {
+  api.registerTool({
+    name: "fastmail_list_calendars",
+    description: "List all calendars with IDs and names.",
+    parameters: { type: "object", properties: {} },
+    async execute(_id: string, _params: Record<string, never>) {
+      const client = await getClient();
+      return { content: [{ type: "text", text: formatCalendars(await client.callTool("list_calendars")) }] };
+    },
+  });
+
+  api.registerTool({
+    name: "fastmail_list_events",
+    description: "List calendar events, optionally filtered by calendar.",
+    parameters: {
+      type: "object",
+      properties: {
+        calendarId: { type: "string", description: "Calendar ID (omit for all)" },
+        limit: { type: "integer", default: 50, description: "Max events" },
+      },
+    },
+    async execute(_id: string, params: { calendarId?: string; limit?: number }) {
+      const client = await getClient();
+      const data = await client.callTool("list_calendar_events", { calendarId: params.calendarId, limit: params.limit ?? 50 });
+      return { content: [{ type: "text", text: Array.isArray(data) ? formatEvents(data) : String(data) }] };
+    },
+  });
+
+  api.registerTool({
+    name: "fastmail_get_event",
+    description: "Get full event details by ID.",
+    parameters: {
+      type: "object",
+      properties: { eventId: { type: "string", description: "Event ID" } },
+      required: ["eventId"],
+    },
+    async execute(_id: string, params: { eventId: string }) {
+      const client = await getClient();
+      return { content: [{ type: "text", text: formatEvent(await client.callTool("get_calendar_event", { eventId: params.eventId })) }] };
+    },
+  });
+
+  api.registerTool({
+    name: "fastmail_create_event",
+    description: "Create a new calendar event.",
+    parameters: {
+      type: "object",
+      properties: {
+        calendarId: { type: "string" },
+        title: { type: "string" },
+        start: { type: "string", description: "ISO 8601" },
+        end: { type: "string", description: "ISO 8601" },
+        description: { type: "string" },
+        location: { type: "string" },
+      },
+      required: ["calendarId", "title", "start", "end"],
+    },
+    async execute(_id: string, params: { calendarId: string; title: string; start: string; end: string; description?: string; location?: string }) {
+      const client = await getClient();
+      const data = await client.callTool("create_calendar_event", {
+        calendarId: params.calendarId, title: params.title,
+        start: params.start, end: params.end,
+        ...(params.description && { description: params.description }),
+        ...(params.location && { location: params.location }),
+      });
+      return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data) }] };
+    },
+  }, { optional: true });
+}

package/src/tools/contacts.ts

@@ -0,0 +1,55 @@
+/**
+ * Contact tools for the Fastmail OpenClaw plugin.
+ * 3 read-only tools.
+ */
+
+import type { OpenClawApi, GetClientFn } from "../../index.js";
+import { formatContacts, formatContact } from "../formatters.js";
+
+export function registerContactTools(api: OpenClawApi, getClient: GetClientFn) {
+  api.registerTool({
+    name: "fastmail_list_contacts",
+    description: "List contacts with names, emails, and phone numbers.",
+    parameters: {
+      type: "object",
+      properties: { limit: { type: "integer", default: 50, description: "Max contacts" } },
+    },
+    async execute(_id: string, params: { limit?: number }) {
+      const client = await getClient();
+      const data = await client.callTool("list_contacts", { limit: params.limit ?? 50 });
+      return { content: [{ type: "text", text: Array.isArray(data) ? formatContacts(data) : String(data) }] };
+    },
+  });
+
+  api.registerTool({
+    name: "fastmail_get_contact",
+    description: "Get full contact details by ID.",
+    parameters: {
+      type: "object",
+      properties: { contactId: { type: "string", description: "Contact ID" } },
+      required: ["contactId"],
+    },
+    async execute(_id: string, params: { contactId: string }) {
+      const client = await getClient();
+      return { content: [{ type: "text", text: formatContact(await client.callTool("get_contact", { contactId: params.contactId })) }] };
+    },
+  });
+
+  api.registerTool({
+    name: "fastmail_search_contacts",
+    description: "Search contacts by name or email.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+        limit: { type: "integer", default: 20, description: "Max results" },
+      },
+      required: ["query"],
+    },
+    async execute(_id: string, params: { query: string; limit?: number }) {
+      const client = await getClient();
+      const data = await client.callTool("search_contacts", { query: params.query, limit: params.limit ?? 20 });
+      return { content: [{ type: "text", text: Array.isArray(data) ? formatContacts(data) : String(data) }] };
+    },
+  });
+}