@vox-ai-app/integrations 1.0.0

package/src/mail/def.js

@@ -0,0 +1,317 @@
+export const MAIL_TOOL_DEFINITIONS = [
+  {
+    name: 'read_emails',
+    description:
+      "Read emails from the user's Mail.app on macOS. By default 20 emails per account are returned; use offset for pagination. Returns a list of messages with id, sender, subject, date, read/unread status, flagged status, and account name, ordered newest first. Each message includes a unique id that can be used with other email tools (get_email_body, reply_to_email, forward_email, mark_email_read, delete_email, move_email, save_attachment). Requires Full Disk Access in System Settings → Privacy & Security.",
+    parameters: {
+      type: 'object',
+      properties: {
+        folder: {
+          type: 'string',
+          description:
+            'Mailbox folder name to read from. Default is "INBOX". Other examples: "Sent", "Drafts", "Archive".'
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of emails to return. Default 20, max 200.'
+        },
+        offset: {
+          type: 'number',
+          description:
+            'Number of matching messages to skip before returning results. Use for pagination. Default 0.'
+        },
+        unread_only: {
+          type: 'boolean',
+          description: 'If true, only return unread emails. Default false.'
+        },
+        search: {
+          type: 'string',
+          description:
+            'Optional keyword to filter results by sender or subject. Case-insensitive. Filtering happens in the mail client for speed.'
+        },
+        account: {
+          type: 'string',
+          description:
+            'Optional account name to read from (partial match, case-insensitive). If omitted, reads from all accounts. The account name is returned in read_emails results.'
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'search_contacts',
+    description:
+      "Search the user's Contacts.app on macOS by name. Returns matching contacts with their name, email address, and where available: phone number, company, and job title. Call this before send_email whenever the user refers to a person by name rather than a full email address.",
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description:
+            'Name (or partial name) to search for. Case-insensitive. Examples: "Sara", "John Smith".'
+        }
+      },
+      required: ['query']
+    }
+  },
+  {
+    name: 'send_email',
+    description:
+      "Send an email from a specific or the default mail account via Mail.app on macOS. Always call search_contacts first if you only know the recipient's name, not their full email address.",
+    parameters: {
+      type: 'object',
+      properties: {
+        to: {
+          type: 'string',
+          description:
+            'Recipient email address or comma-separated list of addresses. Must be fully resolved email addresses (e.g. sara@example.com), not names. Use search_contacts first if needed.'
+        },
+        subject: {
+          type: 'string',
+          description: 'Email subject line.'
+        },
+        body: {
+          type: 'string',
+          description: 'Plain text email body.'
+        },
+        cc: {
+          type: 'string',
+          description: 'Optional CC email address or comma-separated list.'
+        },
+        bcc: {
+          type: 'string',
+          description: 'Optional BCC email address or comma-separated list.'
+        },
+        attachments: {
+          type: 'string',
+          description:
+            'Optional comma-separated list of absolute local file paths to attach. Supports ~/ shortcuts.'
+        },
+        account: {
+          type: 'string',
+          description:
+            'Optional account name to send from (partial match, case-insensitive). If omitted, sends from the default account.'
+        }
+      },
+      required: ['to', 'subject', 'body']
+    }
+  },
+  {
+    name: 'get_email_body',
+    description:
+      "Retrieve the full body/content of a specific email from the user's local mail client. Also returns a list of attachment names if the email has any. Prefer using message_id (from read_emails) for fast, unambiguous lookup. Falls back to sender/subject search if no id provided.",
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description:
+            'The unique message id returned by read_emails. Fastest and most reliable way to identify a specific email.'
+        },
+        sender: {
+          type: 'string',
+          description:
+            'Sender name or email address to match (partial match, case-insensitive). Used only if message_id is not provided.'
+        },
+        subject: {
+          type: 'string',
+          description:
+            'Subject text to match (partial match, case-insensitive). Used only if message_id is not provided.'
+        }
+      },
+      required: []
+    }
+  },
+  {
+    name: 'reply_to_email',
+    description:
+      'Reply to a specific email. Sends the reply immediately via the local mail client. Use the message id from read_emails or get_email_body to identify the email.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email to reply to (from read_emails).'
+        },
+        body: {
+          type: 'string',
+          description: 'The reply body text.'
+        },
+        reply_all: {
+          type: 'boolean',
+          description: 'If true, reply to all recipients. Default false.'
+        },
+        account: {
+          type: 'string',
+          description:
+            'Optional account name to send the reply from (partial match). If omitted, replies from the account that received the email.'
+        }
+      },
+      required: ['message_id', 'body']
+    }
+  },
+  {
+    name: 'forward_email',
+    description:
+      'Forward a specific email to one or more recipients. Sends immediately via the local mail client.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email to forward (from read_emails).'
+        },
+        to: {
+          type: 'string',
+          description:
+            'Recipient email address or comma-separated list to forward to. Must be resolved email addresses.'
+        },
+        body: {
+          type: 'string',
+          description: 'Optional message to prepend above the forwarded content.'
+        },
+        account: {
+          type: 'string',
+          description:
+            'Optional account name to forward from (partial match). If omitted, forwards from the account that received the email.'
+        }
+      },
+      required: ['message_id', 'to']
+    }
+  },
+  {
+    name: 'mark_email_read',
+    description: 'Mark a specific email as read or unread.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email (from read_emails).'
+        },
+        read: {
+          type: 'boolean',
+          description: 'True to mark as read, false to mark as unread. Default true.'
+        }
+      },
+      required: ['message_id']
+    }
+  },
+  {
+    name: 'flag_email',
+    description: 'Flag or unflag a specific email.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email (from read_emails).'
+        },
+        flagged: {
+          type: 'boolean',
+          description: 'True to flag, false to unflag. Default true.'
+        }
+      },
+      required: ['message_id']
+    }
+  },
+  {
+    name: 'delete_email',
+    description:
+      'Delete a specific email (moves it to Trash). This action can usually be undone by the user in their mail client.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email to delete (from read_emails).'
+        }
+      },
+      required: ['message_id']
+    }
+  },
+  {
+    name: 'move_email',
+    description:
+      'Move a specific email to a different mailbox folder (e.g. Archive, Work, Finance).',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email to move (from read_emails).'
+        },
+        target_folder: {
+          type: 'string',
+          description:
+            'Name of the destination mailbox folder. Partial match is supported (e.g. "Archive", "Work").'
+        }
+      },
+      required: ['message_id', 'target_folder']
+    }
+  },
+  {
+    name: 'create_draft',
+    description:
+      "Create an email draft without sending it. The draft opens in the user's mail client for review. Use this when the user wants to review before sending, or says 'draft' instead of 'send'.",
+    parameters: {
+      type: 'object',
+      properties: {
+        to: {
+          type: 'string',
+          description: 'Recipient email address or comma-separated list.'
+        },
+        subject: {
+          type: 'string',
+          description: 'Email subject line.'
+        },
+        body: {
+          type: 'string',
+          description: 'Email body text.'
+        },
+        cc: {
+          type: 'string',
+          description: 'Optional CC email address or comma-separated list.'
+        },
+        bcc: {
+          type: 'string',
+          description: 'Optional BCC email address or comma-separated list.'
+        },
+        attachments: {
+          type: 'string',
+          description: 'Optional comma-separated list of absolute local file paths to attach.'
+        },
+        account: {
+          type: 'string',
+          description:
+            'Optional account name to create the draft in (partial match). If omitted, uses the default account.'
+        }
+      },
+      required: ['to', 'subject', 'body']
+    }
+  },
+  {
+    name: 'save_attachment',
+    description:
+      'Save/download an email attachment to a local folder. Use get_email_body first to see the list of attachment names, then call this with the attachment name to save it.',
+    parameters: {
+      type: 'object',
+      properties: {
+        message_id: {
+          type: 'string',
+          description: 'The unique message id of the email containing the attachment.'
+        },
+        attachment_name: {
+          type: 'string',
+          description: 'Name of the attachment to save (from get_email_body attachment list).'
+        },
+        save_path: {
+          type: 'string',
+          description:
+            'Local directory path to save the attachment to. Defaults to ~/Downloads. Supports ~/ shortcuts.'
+        }
+      },
+      required: ['message_id', 'attachment_name']
+    }
+  }
+]

package/src/mail/index.js

@@ -0,0 +1,165 @@
+import { sendEmailMac, searchContactsMac } from './send/index.js'
+import { readEmailsMac, getEmailBodyMac } from './read/index.js'
+import {
+  replyToEmailMac,
+  forwardEmailMac,
+  markEmailReadMac,
+  flagEmailMac,
+  deleteEmailMac,
+  moveEmailMac,
+  createDraftMac,
+  saveAttachmentMac
+} from './manage/index.js'
+const normalizeList = (v) => {
+  if (!v) return []
+  if (Array.isArray(v)) return v.map((s) => String(s).trim()).filter(Boolean)
+  return String(v)
+    .split(/[,;]/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+export const sendEmail = async (payload) => {
+  const to = normalizeList(payload?.to)
+  if (!to.length) throw new Error('"to" is required.')
+  const args = {
+    to,
+    cc: normalizeList(payload?.cc),
+    bcc: normalizeList(payload?.bcc),
+    subject: String(payload?.subject || '').trim(),
+    body: String(payload?.body ?? payload?.text ?? payload?.content ?? '').trim(),
+    attachments: normalizeList(payload?.attachments ?? payload?.attachment),
+    account: String(payload?.account ?? '').trim() || undefined
+  }
+  return sendEmailMac(args)
+}
+export const readEmails = async (payload) => {
+  const folder = String(payload?.folder ?? 'INBOX').trim()
+  const limit = Math.min(Math.max(1, Number(payload?.limit ?? 20)), 200)
+  const offset = Math.max(0, Number(payload?.offset ?? 0))
+  const unreadOnly = Boolean(payload?.unread_only ?? payload?.unreadOnly ?? false)
+  const search = String(payload?.search ?? '').trim()
+  const account = String(payload?.account ?? '').trim() || undefined
+  const args = {
+    folder,
+    limit,
+    offset,
+    unreadOnly,
+    search,
+    account
+  }
+  const messages = await readEmailsMac(args)
+  return {
+    folder,
+    count: messages.length,
+    messages
+  }
+}
+export const searchContacts = async (payload) => {
+  const query = String(payload?.query ?? payload?.name ?? payload?.q ?? '').trim()
+  if (!query) throw new Error('"query" is required.')
+  const contacts = await searchContactsMac(query)
+  return {
+    query,
+    count: contacts.length,
+    contacts
+  }
+}
+export const getEmailBody = async (payload) => {
+  const sender = String(payload?.sender ?? payload?.from ?? '').trim()
+  const subject = String(payload?.subject ?? '').trim()
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  const args = {
+    sender,
+    subject,
+    messageId
+  }
+  return getEmailBodyMac(args)
+}
+export const replyToEmail = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const body = String(payload?.body ?? '').trim()
+  if (!body) throw new Error('"body" is required.')
+  const replyAll = Boolean(payload?.reply_all ?? payload?.replyAll ?? false)
+  const account = String(payload?.account ?? '').trim() || undefined
+  return replyToEmailMac({
+    messageId,
+    body,
+    replyAll,
+    account
+  })
+}
+export const forwardEmail = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const to = normalizeList(payload?.to)
+  if (!to.length) throw new Error('"to" is required.')
+  const body = String(payload?.body ?? '').trim()
+  const account = String(payload?.account ?? '').trim() || undefined
+  return forwardEmailMac({
+    messageId,
+    to,
+    body,
+    account
+  })
+}
+export const markEmailRead = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const read = payload?.read !== undefined ? Boolean(payload.read) : true
+  return markEmailReadMac({
+    messageId,
+    read
+  })
+}
+export const flagEmail = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const flagged = payload?.flagged !== undefined ? Boolean(payload.flagged) : true
+  return flagEmailMac({
+    messageId,
+    flagged
+  })
+}
+export const deleteEmail = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  return deleteEmailMac({
+    messageId
+  })
+}
+export const moveEmail = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const targetFolder = String(payload?.target_folder ?? payload?.targetFolder ?? '').trim()
+  if (!targetFolder) throw new Error('"target_folder" is required.')
+  return moveEmailMac({
+    messageId,
+    targetFolder
+  })
+}
+export const createDraft = async (payload) => {
+  const to = normalizeList(payload?.to)
+  if (!to.length) throw new Error('"to" is required.')
+  return createDraftMac({
+    to,
+    subject: String(payload?.subject || '').trim(),
+    body: String(payload?.body ?? payload?.text ?? payload?.content ?? '').trim(),
+    cc: normalizeList(payload?.cc),
+    bcc: normalizeList(payload?.bcc),
+    attachments: normalizeList(payload?.attachments ?? payload?.attachment),
+    account: String(payload?.account ?? '').trim() || undefined
+  })
+}
+export const saveAttachment = async (payload) => {
+  const messageId = String(payload?.message_id ?? payload?.messageId ?? '').trim()
+  if (!messageId) throw new Error('"message_id" is required.')
+  const attachmentName = String(payload?.attachment_name ?? payload?.attachmentName ?? '').trim()
+  if (!attachmentName) throw new Error('"attachment_name" is required.')
+  const savePath = String(payload?.save_path ?? payload?.savePath ?? '').trim() || undefined
+  return saveAttachmentMac({
+    messageId,
+    attachmentName,
+    savePath
+  })
+}

package/src/mail/manage/index.js

@@ -0,0 +1,10 @@
+export {
+  replyToEmailMac,
+  forwardEmailMac,
+  markEmailReadMac,
+  flagEmailMac,
+  deleteEmailMac,
+  moveEmailMac,
+  createDraftMac,
+  saveAttachmentMac
+} from './mac/index.js'