@2en/clawly-plugins 1.3.1 → 1.4.1

package/calendar.ts

@@ -0,0 +1,257 @@
+/**
+ * Calendar integration via Clawly backend.
+ *
+ * Gateway methods (external RPC):
+ * - calendar.listCalendars — list available calendars
+ * - calendar.listEvents    — list events in a time range
+ * - calendar.createEvent   — create a new calendar event
+ *
+ * Agent tools (LLM-callable):
+ * - calendar_list_calendars — list available calendars
+ * - calendar_list_events    — list events in a time range
+ * - calendar_create_event   — create a new calendar event
+ */
+
+import type {PluginApi} from './index'
+import type {GatewayCfg, HandlerResult} from './gateway-fetch'
+import {gatewayFetch, toToolResult} from './gateway-fetch'
+
+// ── Handlers ──
+
+async function handleListCalendars(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const qs = typeof params.provider === 'string' ? `?provider=${params.provider}` : ''
+  const res = await gatewayFetch(cfg, `/calendar/calendars${qs}`)
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleListEvents(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const calendarId = typeof params.calendarId === 'string' ? params.calendarId : ''
+  const start =
+    typeof params.start === 'number'
+      ? params.start
+      : typeof params.start === 'string'
+        ? Number(params.start)
+        : 0
+  const end =
+    typeof params.end === 'number'
+      ? params.end
+      : typeof params.end === 'string'
+        ? Number(params.end)
+        : 0
+
+  if (!calendarId || !start || !end)
+    return {
+      ok: false,
+      error: {code: 'invalid_params', message: 'calendarId, start, and end are required'},
+    }
+
+  const qs = new URLSearchParams({calendar_id: calendarId, start: String(start), end: String(end)})
+  if (typeof params.provider === 'string') qs.set('provider', params.provider)
+
+  const res = await gatewayFetch(cfg, `/calendar/events?${qs.toString()}`)
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleCreateEvent(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const calendarId = typeof params.calendarId === 'string' ? params.calendarId : ''
+  const title = typeof params.title === 'string' ? params.title : ''
+  const startTime = typeof params.startTime === 'number' ? params.startTime : 0
+  const endTime = typeof params.endTime === 'number' ? params.endTime : 0
+
+  if (!calendarId || !title || !startTime || !endTime)
+    return {
+      ok: false,
+      error: {
+        code: 'invalid_params',
+        message: 'calendarId, title, startTime, and endTime are required',
+      },
+    }
+
+  const res = await gatewayFetch(cfg, '/calendar/events', {
+    method: 'POST',
+    body: JSON.stringify({
+      calendarId,
+      title,
+      startTime,
+      endTime,
+      description: typeof params.description === 'string' ? params.description : undefined,
+      location: typeof params.location === 'string' ? params.location : undefined,
+      participants: Array.isArray(params.participants) ? params.participants : undefined,
+      provider: typeof params.provider === 'string' ? params.provider : undefined,
+    }),
+  })
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+// ── Registration ──
+
+export function registerCalendar(api: PluginApi, cfg: GatewayCfg) {
+  // Gateway methods (external RPC)
+
+  api.registerGatewayMethod('calendar.listCalendars', async ({params, respond}) => {
+    try {
+      const r = await handleListCalendars(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('calendar.listEvents', async ({params, respond}) => {
+    try {
+      const r = await handleListEvents(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('calendar.createEvent', async ({params, respond}) => {
+    try {
+      const r = await handleCreateEvent(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  // Agent tools (LLM-callable)
+
+  api.registerTool({
+    name: 'calendar_list_calendars',
+    description:
+      'List available calendars for the connected account. ' +
+      'If no calendar account is connected, the result will contain a CONNECTION_REQUIRED error.',
+    parameters: {
+      type: 'object',
+      properties: {
+        provider: {type: 'string', description: 'Calendar provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleListCalendars(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'calendar_list_events',
+    description: 'List calendar events in a time range.',
+    parameters: {
+      type: 'object',
+      required: ['calendarId', 'start', 'end'],
+      properties: {
+        calendarId: {type: 'string', description: 'Calendar ID (from calendar_list_calendars)'},
+        start: {type: 'number', description: 'Start time as Unix timestamp (seconds)'},
+        end: {type: 'number', description: 'End time as Unix timestamp (seconds)'},
+        provider: {type: 'string', description: 'Calendar provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleListEvents(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'calendar_create_event',
+    description: 'Create a new calendar event.',
+    parameters: {
+      type: 'object',
+      required: ['calendarId', 'title', 'startTime', 'endTime'],
+      properties: {
+        calendarId: {type: 'string', description: 'Calendar ID (from calendar_list_calendars)'},
+        title: {type: 'string', description: 'Event title'},
+        startTime: {type: 'number', description: 'Start time as Unix timestamp (seconds)'},
+        endTime: {type: 'number', description: 'End time as Unix timestamp (seconds)'},
+        description: {type: 'string', description: 'Event description'},
+        location: {type: 'string', description: 'Event location'},
+        participants: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {name: {type: 'string'}, email: {type: 'string'}},
+            required: ['email'],
+          },
+          description: 'Event participants',
+        },
+        provider: {type: 'string', description: 'Calendar provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleCreateEvent(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.logger.info(
+    'calendar: registered gateway methods (calendar.listCalendars, calendar.listEvents, calendar.createEvent) ' +
+      'and agent tools (calendar_list_calendars, calendar_list_events, calendar_create_event)',
+  )
+}

package/email.ts

@@ -0,0 +1,313 @@
+/**
+ * Email integration via Clawly backend.
+ *
+ * Gateway methods (external RPC):
+ * - email.search       — search/list email messages
+ * - email.read         — read a single email message
+ * - email.send         — send an email
+ * - email.getConnectUrl — get OAuth URL to connect an email account
+ *
+ * Agent tools (LLM-callable):
+ * - email_search       — search/list email messages
+ * - email_read         — read a single email message by ID
+ * - email_send         — send an email
+ * - email_connect      — get OAuth URL to connect an email account
+ */
+
+import type {PluginApi} from './index'
+import type {GatewayCfg, HandlerResult} from './gateway-fetch'
+import {gatewayFetch, toToolResult} from './gateway-fetch'
+
+// ── Handlers ──
+
+async function handleSearch(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const qs = new URLSearchParams()
+  if (typeof params.query === 'string') qs.set('query', params.query)
+  if (typeof params.from === 'string') qs.set('from', params.from)
+  if (typeof params.to === 'string') qs.set('to', params.to)
+  if (typeof params.folder === 'string') qs.set('in', params.folder)
+  if (typeof params.limit === 'number') qs.set('limit', String(params.limit))
+  if (typeof params.provider === 'string') qs.set('provider', params.provider)
+
+  const res = await gatewayFetch(cfg, `/email/messages?${qs.toString()}`)
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleRead(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const id = typeof params.id === 'string' ? params.id : ''
+  if (!id) return {ok: false, error: {code: 'invalid_params', message: 'id is required'}}
+
+  const qs = typeof params.provider === 'string' ? `?provider=${params.provider}` : ''
+  const res = await gatewayFetch(cfg, `/email/messages/${encodeURIComponent(id)}${qs}`)
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleSend(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const to = Array.isArray(params.to)
+    ? params.to
+    : typeof params.to === 'string'
+      ? [{email: params.to}]
+      : []
+  const subject = typeof params.subject === 'string' ? params.subject : ''
+  const body = typeof params.body === 'string' ? params.body : ''
+
+  if (!to.length || !subject || !body)
+    return {
+      ok: false,
+      error: {code: 'invalid_params', message: 'to, subject, and body are required'},
+    }
+
+  const res = await gatewayFetch(cfg, '/email/messages/send', {
+    method: 'POST',
+    body: JSON.stringify({
+      to,
+      subject,
+      body,
+      replyToMessageId:
+        typeof params.replyToMessageId === 'string' ? params.replyToMessageId : undefined,
+      provider: typeof params.provider === 'string' ? params.provider : undefined,
+    }),
+  })
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+async function handleGetConnectUrl(
+  cfg: GatewayCfg,
+  params: Record<string, unknown>,
+): Promise<HandlerResult> {
+  const provider = typeof params.provider === 'string' ? params.provider : undefined
+  const res = await gatewayFetch(cfg, '/connections/start', {
+    method: 'POST',
+    body: JSON.stringify({provider}),
+  })
+  const data = await res.json()
+  if (!res.ok)
+    return {
+      ok: false,
+      error: {code: data.error ?? 'error', message: data.message ?? res.statusText},
+    }
+  return {ok: true, data}
+}
+
+// ── Registration ──
+
+export function registerEmail(api: PluginApi, cfg: GatewayCfg) {
+  // Gateway methods (external RPC)
+
+  api.registerGatewayMethod('email.search', async ({params, respond}) => {
+    try {
+      const r = await handleSearch(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('email.read', async ({params, respond}) => {
+    try {
+      const r = await handleRead(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('email.send', async ({params, respond}) => {
+    try {
+      const r = await handleSend(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  api.registerGatewayMethod('email.getConnectUrl', async ({params, respond}) => {
+    try {
+      const r = await handleGetConnectUrl(cfg, params)
+      r.ok ? respond(true, r.data) : respond(false, undefined, r.error)
+    } catch (err) {
+      respond(false, undefined, {
+        code: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      })
+    }
+  })
+
+  // Agent tools (LLM-callable)
+
+  api.registerTool({
+    name: 'email_search',
+    description:
+      'Search or list email messages. Returns a list of email messages matching the query. ' +
+      'If no email account is connected, the result will contain a CONNECTION_REQUIRED error ' +
+      'with available providers — use email_connect to get an OAuth URL.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {type: 'string', description: 'Search query (e.g. "from:alice subject:meeting")'},
+        from: {type: 'string', description: 'Filter by sender email'},
+        to: {type: 'string', description: 'Filter by recipient email'},
+        folder: {type: 'string', description: 'Folder name (e.g. INBOX, SENT)'},
+        limit: {type: 'number', description: 'Max results (default 10)'},
+        provider: {type: 'string', description: 'Email provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleSearch(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'email_read',
+    description: 'Read a single email message by ID. Returns full message content including body.',
+    parameters: {
+      type: 'object',
+      required: ['id'],
+      properties: {
+        id: {type: 'string', description: 'Message ID'},
+        provider: {type: 'string', description: 'Email provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleRead(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'email_send',
+    description: 'Send an email. Requires a connected email account.',
+    parameters: {
+      type: 'object',
+      required: ['to', 'subject', 'body'],
+      properties: {
+        to: {
+          oneOf: [
+            {type: 'string', description: 'Recipient email address'},
+            {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {name: {type: 'string'}, email: {type: 'string'}},
+                required: ['email'],
+              },
+            },
+          ],
+          description: 'Recipient(s) — single email string or array of {name?, email}',
+        },
+        subject: {type: 'string', description: 'Email subject'},
+        body: {type: 'string', description: 'Email body (plain text or HTML)'},
+        replyToMessageId: {type: 'string', description: 'Message ID to reply to'},
+        provider: {type: 'string', description: 'Email provider: google or microsoft'},
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleSend(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.registerTool({
+    name: 'email_connect',
+    description:
+      'Get an OAuth URL to connect an email account (Gmail or Outlook). ' +
+      'Returns an authorizeUrl that the user should open in a browser to authorize access. ' +
+      'Use this when email operations return CONNECTION_REQUIRED.',
+    parameters: {
+      type: 'object',
+      properties: {
+        provider: {
+          type: 'string',
+          enum: ['google', 'microsoft'],
+          description: 'Email provider to connect (google for Gmail, microsoft for Outlook)',
+        },
+      },
+    },
+    async execute(_toolCallId, params) {
+      try {
+        return toToolResult(await handleGetConnectUrl(cfg, params))
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({error: err instanceof Error ? err.message : String(err)}),
+            },
+          ],
+        }
+      }
+    },
+  })
+
+  api.logger.info(
+    'email: registered gateway methods (email.search, email.read, email.send, email.getConnectUrl) ' +
+      'and agent tools (email_search, email_read, email_send, email_connect)',
+  )
+}

package/gateway-fetch.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared helpers for plugins that proxy to the Clawly model-gateway backend.
+ */
+
+import type {PluginApi} from './index'
+
+export type GatewayCfg = {baseUrl: string; token: string}
+
+export type HandlerResult = {ok: boolean; data?: unknown; error?: {code: string; message: string}}
+
+export function getGatewayConfig(api: PluginApi): GatewayCfg {
+  const cfg = api.pluginConfig && typeof api.pluginConfig === 'object' ? api.pluginConfig : {}
+  const baseUrl =
+    typeof (cfg as Record<string, unknown>).gatewayBaseUrl === 'string'
+      ? ((cfg as Record<string, unknown>).gatewayBaseUrl as string).replace(/\/$/, '')
+      : ''
+  const token =
+    typeof (cfg as Record<string, unknown>).gatewayToken === 'string'
+      ? ((cfg as Record<string, unknown>).gatewayToken as string)
+      : ''
+  return {baseUrl, token}
+}
+
+export async function gatewayFetch(
+  cfg: GatewayCfg,
+  path: string,
+  init?: RequestInit,
+): Promise<Response> {
+  return fetch(`${cfg.baseUrl}${path}`, {
+    ...init,
+    headers: {
+      ...(init?.headers ?? {}),
+      Authorization: `Bearer ${cfg.token}`,
+      'Content-Type': 'application/json',
+    },
+  })
+}
+
+export function toToolResult(result: HandlerResult) {
+  return {content: [{type: 'text', text: JSON.stringify(result.ok ? result.data : result.error)}]}
+}

package/index.ts

@@ -22,10 +22,13 @@
  */
 
 import {registerAgentSend} from './agent-send'
+import {registerCalendar} from './calendar'
 import {registerIsUserOnlineTool, registerSendAppPushTool} from './tools'
 import {registerClawlyCronChannel} from './channel'
 import {registerCronHook} from './cron-hook'
 import {registerEchoCommand} from './echo'
+import {registerEmail} from './email'
+import {getGatewayConfig} from './gateway-fetch'
 import {registerNotification} from './notification'
 import {registerOutboundHook, registerOutboundMethods} from './outbound'
 import {registerPresence} from './presence'
@@ -91,6 +94,14 @@ export default {
     registerSendAppPushTool(api)
     registerClawlyCronChannel(api)
     registerCronHook(api)
+
+    // Email & calendar (optional — requires gatewayBaseUrl + gatewayToken in config)
+    const gw = getGatewayConfig(api)
+    if (gw.baseUrl && gw.token) {
+      registerEmail(api, gw)
+      registerCalendar(api, gw)
+    }
+
     api.logger.info(`Loaded ${api.id} plugin.`)
   },
 }

package/openclaw.plugin.json

@@ -6,7 +6,10 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {},
+    "properties": {
+      "gatewayBaseUrl": { "type": "string" },
+      "gatewayToken": { "type": "string" }
+    },
     "required": []
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2en/clawly-plugins",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "module": "index.ts",
   "type": "module",
   "repository": {
@@ -14,8 +14,11 @@
   "files": [
     "tools",
     "index.ts",
+    "calendar.ts",
     "channel.ts",
     "cron-hook.ts",
+    "email.ts",
+    "gateway-fetch.ts",
     "outbound.ts",
     "echo.ts",
     "presence.ts",