@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/mcp/adapters/whereby.adapter.ts

@@ -0,0 +1,240 @@
+/**
+ * MCP Skill Adapter — Whereby
+ *
+ * Maps Whereby REST API v1 endpoints to MCP tool handlers.
+ * Supports creating, retrieving, listing, and deleting video meeting rooms.
+ *
+ * Whereby API docs: https://whereby.dev/http-api
+ */
+
+import type { SkillAdapter, ToolHandler, ToolResult, ToolExecutionContext } from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+function wherebyError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const detail = data.message || data.error || err.message;
+      return { content: `Whereby API error: ${detail}`, isError: true };
+    }
+    return { content: `Whereby API error: ${err.message}`, isError: true };
+  }
+  return { content: `Whereby API error: ${String(err)}`, isError: true };
+}
+
+// ─── Tool: whereby_create_meeting ───────────────────────
+
+const createMeeting: ToolHandler = {
+  description:
+    'Create a new Whereby video meeting room. Specify an end date and optional room settings.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      endDate: {
+        type: 'string',
+        description: 'When the meeting room expires in ISO 8601 format (e.g. "2024-12-01T23:59:59Z")',
+      },
+      roomNamePrefix: {
+        type: 'string',
+        description: 'Custom prefix for the room name (optional)',
+      },
+      roomMode: {
+        type: 'string',
+        enum: ['normal', 'group'],
+        description: 'Room mode: "normal" (up to 4) or "group" (up to 200) participants (default: "normal")',
+      },
+      isLocked: {
+        type: 'boolean',
+        description: 'Whether the room requires a knock to enter (default: false)',
+      },
+      fields: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Additional fields to include in the response (e.g. ["hostRoomUrl"])',
+      },
+    },
+    required: ['endDate'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const body: Record<string, any> = {
+        endDate: params.endDate,
+      };
+      if (params.roomNamePrefix) body.roomNamePrefix = params.roomNamePrefix;
+      if (params.roomMode) body.roomMode = params.roomMode;
+      if (params.isLocked !== undefined) body.isLocked = params.isLocked;
+      if (params.fields?.length) body.fields = params.fields;
+
+      const result = await ctx.apiExecutor.post('/meetings', body);
+
+      const locked = result.isLocked ? ' (locked)' : '';
+      return {
+        content: [
+          `Meeting room created${locked}`,
+          `Meeting ID: ${result.meetingId}`,
+          `Room URL: ${result.roomUrl || 'N/A'}`,
+          `Host URL: ${result.hostRoomUrl || 'N/A'}`,
+          `Mode: ${result.roomMode || 'normal'}`,
+          `Expires: ${result.endDate}`,
+        ].join('\n'),
+        metadata: {
+          meetingId: result.meetingId,
+          roomUrl: result.roomUrl,
+          hostRoomUrl: result.hostRoomUrl,
+          endDate: result.endDate,
+        },
+      };
+    } catch (err) {
+      return wherebyError(err);
+    }
+  },
+};
+
+// ─── Tool: whereby_get_meeting ──────────────────────────
+
+const getMeeting: ToolHandler = {
+  description:
+    'Get details of a specific Whereby meeting room by its meeting ID.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      meeting_id: {
+        type: 'string',
+        description: 'The unique meeting ID to retrieve',
+      },
+    },
+    required: ['meeting_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const result = await ctx.apiExecutor.get(`/meetings/${params.meeting_id}`);
+
+      return {
+        content: [
+          `Meeting ID: ${result.meetingId}`,
+          `Room URL: ${result.roomUrl || 'N/A'}`,
+          `Host URL: ${result.hostRoomUrl || 'N/A'}`,
+          `Mode: ${result.roomMode || 'normal'}`,
+          `Locked: ${result.isLocked ? 'Yes' : 'No'}`,
+          `Start: ${result.startDate || 'N/A'}`,
+          `End: ${result.endDate || 'N/A'}`,
+          `Created: ${result.createdAt || 'N/A'}`,
+        ].join('\n'),
+        metadata: {
+          meetingId: result.meetingId,
+          roomUrl: result.roomUrl,
+          roomMode: result.roomMode,
+          endDate: result.endDate,
+        },
+      };
+    } catch (err) {
+      return wherebyError(err);
+    }
+  },
+};
+
+// ─── Tool: whereby_delete_meeting ───────────────────────
+
+const deleteMeeting: ToolHandler = {
+  description:
+    'Delete a Whereby meeting room by its meeting ID. The room URL will no longer be accessible.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      meeting_id: {
+        type: 'string',
+        description: 'The unique meeting ID to delete',
+      },
+    },
+    required: ['meeting_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      await ctx.apiExecutor.delete(`/meetings/${params.meeting_id}`);
+
+      return {
+        content: `Meeting ${params.meeting_id} has been deleted. The room URL is no longer accessible.`,
+        metadata: { meetingId: params.meeting_id, deleted: true },
+      };
+    } catch (err) {
+      return wherebyError(err);
+    }
+  },
+};
+
+// ─── Tool: whereby_list_meetings ────────────────────────
+
+const listMeetings: ToolHandler = {
+  description:
+    'List all active Whereby meeting rooms. Returns room URLs, modes, and expiration dates.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      limit: {
+        type: 'number',
+        description: 'Maximum number of meetings to return (default 20)',
+      },
+      cursor: {
+        type: 'string',
+        description: 'Pagination cursor for the next page of results (optional)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const query: Record<string, string> = {
+        limit: String(params.limit ?? 20),
+      };
+      if (params.cursor) query.cursor = params.cursor;
+
+      const result = await ctx.apiExecutor.get('/meetings', query);
+
+      const meetings: any[] = result.results || result.data || [];
+      if (meetings.length === 0) {
+        return { content: 'No active meeting rooms found.' };
+      }
+
+      const lines = meetings.map((m: any) => {
+        const mode = m.roomMode || 'normal';
+        const locked = m.isLocked ? ' (locked)' : '';
+        const endDate = m.endDate ? m.endDate.slice(0, 16) : 'N/A';
+        return `${m.roomUrl || 'N/A'}${locked} — ${mode} mode — Expires: ${endDate} — ID: ${m.meetingId}`;
+      });
+
+      const nextCursor = result.nextCursor || result.pagination?.cursor;
+      const paginationNote = nextCursor ? `\n(Next cursor: ${nextCursor})` : '';
+
+      return {
+        content: `Found ${meetings.length} meeting rooms:\n${lines.join('\n')}${paginationNote}`,
+        metadata: { count: meetings.length, nextCursor },
+      };
+    } catch (err) {
+      return wherebyError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const wherebyAdapter: SkillAdapter = {
+  skillId: 'whereby',
+  name: 'Whereby',
+  baseUrl: 'https://api.whereby.dev/v1',
+  auth: {
+    type: 'api_key',
+    headerName: 'Authorization',
+    headerPrefix: 'Bearer',
+  },
+  tools: {
+    whereby_create_meeting: createMeeting,
+    whereby_get_meeting: getMeeting,
+    whereby_delete_meeting: deleteMeeting,
+    whereby_list_meetings: listMeetings,
+  },
+  rateLimits: { requestsPerSecond: 5, burstLimit: 10 },
+};

package/src/mcp/adapters/woocommerce.adapter.ts

@@ -0,0 +1,454 @@
+/**
+ * MCP Skill Adapter — WooCommerce
+ *
+ * Maps WooCommerce REST API endpoints to MCP tool handlers.
+ * WooCommerce uses a dynamic site URL: https://{site}/wp-json/wc/v3
+ *
+ * Authentication uses consumer key and consumer secret passed as query params
+ * or via Basic auth depending on the site configuration.
+ *
+ * WooCommerce API docs: https://woocommerce.github.io/woocommerce-rest-api-docs/
+ *
+ * Tools:
+ *   - woo_list_products      List products in the store
+ *   - woo_create_product     Create a new product
+ *   - woo_list_orders        List orders with optional filters
+ *   - woo_update_order       Update an existing order
+ *   - woo_list_customers     List customers
+ */
+
+import type {
+  SkillAdapter,
+  ToolHandler,
+  ToolResult,
+  ToolExecutionContext,
+} from '../framework/types.js';
+
+// ─── Helpers ────────────────────────────────────────────
+
+/** Resolve the WooCommerce base URL from skill config */
+function wooUrl(ctx: ToolExecutionContext): string {
+  const siteUrl = ctx.skillConfig.siteUrl;
+  if (!siteUrl) {
+    throw new Error('WooCommerce site URL is required in skillConfig (e.g. { siteUrl: "https://mysite.com" })');
+  }
+  return `${siteUrl.replace(/\/$/, '')}/wp-json/wc/v3`;
+}
+
+/** Build auth query params from credentials */
+function wooAuthQuery(ctx: ToolExecutionContext): Record<string, string> {
+  const consumerKey = ctx.credentials.fields?.consumerKey ?? '';
+  const consumerSecret = ctx.credentials.fields?.consumerSecret ?? '';
+  return {
+    consumer_key: consumerKey,
+    consumer_secret: consumerSecret,
+  };
+}
+
+function wooError(err: unknown): ToolResult {
+  if (err instanceof Error) {
+    const data = (err as any).data;
+    if (data && typeof data === 'object') {
+      const code = data.code || '';
+      const message = data.message || err.message;
+      return { content: `WooCommerce API error [${code}]: ${message}`, isError: true };
+    }
+    return { content: `WooCommerce API error: ${err.message}`, isError: true };
+  }
+  return { content: `WooCommerce API error: ${String(err)}`, isError: true };
+}
+
+/** Format a WooCommerce product for display */
+function formatProduct(product: any): string {
+  const name = product.name || '(untitled)';
+  const status = product.status || 'unknown';
+  const price = product.price || 'N/A';
+  const sku = product.sku || 'no sku';
+  const stock = product.stock_status || 'unknown';
+  return `${name} (ID: ${product.id}) -- ${status} -- $${price} -- SKU: ${sku} -- stock: ${stock}`;
+}
+
+/** Format a WooCommerce order for display */
+function formatOrder(order: any): string {
+  const number = order.number || order.id;
+  const status = order.status || 'unknown';
+  const total = order.total ? `${order.total} ${order.currency}` : 'N/A';
+  const billing = order.billing?.first_name
+    ? `${order.billing.first_name} ${order.billing.last_name || ''}`
+    : order.billing?.email || 'unknown';
+  const created = order.date_created ? order.date_created.slice(0, 10) : '';
+  return `#${number} -- ${status} -- ${total} -- ${billing} -- ${created}`;
+}
+
+/** Format a WooCommerce customer for display */
+function formatCustomer(customer: any): string {
+  const name = `${customer.first_name || ''} ${customer.last_name || ''}`.trim() || '(no name)';
+  const email = customer.email || '(no email)';
+  const orders = customer.orders_count ?? 0;
+  const spent = customer.total_spent || '0';
+  return `${name} <${email}> (ID: ${customer.id}) -- ${orders} orders -- spent: $${spent}`;
+}
+
+// ─── Tool: woo_list_products ────────────────────────────
+
+const listProducts: ToolHandler = {
+  description:
+    'List products in the WooCommerce store. Returns product names, prices, stock status, and SKUs.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      per_page: {
+        type: 'number',
+        description: 'Results per page (default 25, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      status: {
+        type: 'string',
+        enum: ['any', 'draft', 'pending', 'private', 'publish'],
+        description: 'Filter by product status',
+      },
+      search: {
+        type: 'string',
+        description: 'Search term to filter products',
+      },
+      category: {
+        type: 'string',
+        description: 'Filter by category ID',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wooUrl(ctx);
+      const authQuery = wooAuthQuery(ctx);
+      const query: Record<string, string> = {
+        ...authQuery,
+        per_page: String(params.per_page ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params.status) query.status = params.status;
+      if (params.search) query.search = params.search;
+      if (params.category) query.category = params.category;
+
+      const products = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/products`,
+        query,
+      });
+
+      const items: any[] = Array.isArray(products) ? products : [];
+      if (items.length === 0) {
+        return { content: 'No products found.', metadata: { productCount: 0 } };
+      }
+
+      const lines = items.map((p: any) => formatProduct(p));
+      return {
+        content: `${items.length} product(s):\n${lines.join('\n')}`,
+        metadata: { productCount: items.length },
+      };
+    } catch (err) {
+      return wooError(err);
+    }
+  },
+};
+
+// ─── Tool: woo_create_product ───────────────────────────
+
+const createProduct: ToolHandler = {
+  description:
+    'Create a new product in the WooCommerce store. Provide a name and optional price, description, SKU, and status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Product name',
+      },
+      regular_price: {
+        type: 'string',
+        description: 'Regular price as a string (e.g. "29.99")',
+      },
+      description: {
+        type: 'string',
+        description: 'Full product description (HTML supported)',
+      },
+      short_description: {
+        type: 'string',
+        description: 'Short product description (HTML supported)',
+      },
+      sku: {
+        type: 'string',
+        description: 'Stock keeping unit',
+      },
+      status: {
+        type: 'string',
+        enum: ['draft', 'pending', 'private', 'publish'],
+        description: 'Product status (default: "draft")',
+      },
+      type: {
+        type: 'string',
+        enum: ['simple', 'grouped', 'external', 'variable'],
+        description: 'Product type (default: "simple")',
+      },
+    },
+    required: ['name'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wooUrl(ctx);
+      const authQuery = wooAuthQuery(ctx);
+      const body: Record<string, any> = {
+        name: params.name,
+        status: params.status || 'draft',
+        type: params.type || 'simple',
+      };
+      if (params.regular_price) body.regular_price = params.regular_price;
+      if (params.description) body.description = params.description;
+      if (params.short_description) body.short_description = params.short_description;
+      if (params.sku) body.sku = params.sku;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'POST',
+        url: `${baseUrl}/products`,
+        query: authQuery,
+        body,
+      });
+
+      return {
+        content: `Product created: "${result.name}" (ID: ${result.id}) -- status: ${result.status} -- price: $${result.regular_price || 'N/A'}`,
+        metadata: {
+          productId: result.id,
+          name: result.name,
+          status: result.status,
+        },
+      };
+    } catch (err) {
+      return wooError(err);
+    }
+  },
+};
+
+// ─── Tool: woo_list_orders ──────────────────────────────
+
+const listOrders: ToolHandler = {
+  description:
+    'List orders from the WooCommerce store. Optionally filter by status or date range.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      per_page: {
+        type: 'number',
+        description: 'Results per page (default 25, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      status: {
+        type: 'string',
+        enum: ['any', 'pending', 'processing', 'on-hold', 'completed', 'cancelled', 'refunded', 'failed'],
+        description: 'Filter by order status',
+      },
+      after: {
+        type: 'string',
+        description: 'Limit to orders after this date (ISO 8601 format)',
+      },
+      before: {
+        type: 'string',
+        description: 'Limit to orders before this date (ISO 8601 format)',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wooUrl(ctx);
+      const authQuery = wooAuthQuery(ctx);
+      const query: Record<string, string> = {
+        ...authQuery,
+        per_page: String(params.per_page ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params.status) query.status = params.status;
+      if (params.after) query.after = params.after;
+      if (params.before) query.before = params.before;
+
+      const orders = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/orders`,
+        query,
+      });
+
+      const items: any[] = Array.isArray(orders) ? orders : [];
+      if (items.length === 0) {
+        return { content: 'No orders found.', metadata: { orderCount: 0 } };
+      }
+
+      const lines = items.map((o: any) => formatOrder(o));
+      return {
+        content: `${items.length} order(s):\n${lines.join('\n')}`,
+        metadata: { orderCount: items.length },
+      };
+    } catch (err) {
+      return wooError(err);
+    }
+  },
+};
+
+// ─── Tool: woo_update_order ─────────────────────────────
+
+const updateOrder: ToolHandler = {
+  description:
+    'Update an existing WooCommerce order. Can change status, add a note, or update billing/shipping details.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      order_id: {
+        type: 'number',
+        description: 'The order ID to update',
+      },
+      status: {
+        type: 'string',
+        enum: ['pending', 'processing', 'on-hold', 'completed', 'cancelled', 'refunded', 'failed'],
+        description: 'New order status',
+      },
+      customer_note: {
+        type: 'string',
+        description: 'Customer-facing note to add to the order',
+      },
+      transaction_id: {
+        type: 'string',
+        description: 'Transaction ID for payment tracking',
+      },
+    },
+    required: ['order_id'],
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wooUrl(ctx);
+      const authQuery = wooAuthQuery(ctx);
+      const body: Record<string, any> = {};
+      if (params.status) body.status = params.status;
+      if (params.customer_note) body.customer_note = params.customer_note;
+      if (params.transaction_id) body.transaction_id = params.transaction_id;
+
+      const result = await ctx.apiExecutor.request({
+        method: 'PUT',
+        url: `${baseUrl}/orders/${params.order_id}`,
+        query: authQuery,
+        body,
+      });
+
+      return {
+        content: `Order #${result.number || result.id} updated -- status: ${result.status}`,
+        metadata: {
+          orderId: result.id,
+          orderNumber: result.number,
+          status: result.status,
+        },
+      };
+    } catch (err) {
+      return wooError(err);
+    }
+  },
+};
+
+// ─── Tool: woo_list_customers ───────────────────────────
+
+const listCustomers: ToolHandler = {
+  description:
+    'List customers in the WooCommerce store. Optionally search by name or email.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      per_page: {
+        type: 'number',
+        description: 'Results per page (default 25, max 100)',
+      },
+      page: {
+        type: 'number',
+        description: 'Page number (default 1)',
+      },
+      search: {
+        type: 'string',
+        description: 'Search term (searches name and email)',
+      },
+      role: {
+        type: 'string',
+        enum: ['all', 'customer', 'subscriber'],
+        description: 'Filter by role (default: "all")',
+      },
+    },
+  },
+
+  async execute(params: Record<string, any>, ctx: ToolExecutionContext): Promise<ToolResult> {
+    try {
+      const baseUrl = wooUrl(ctx);
+      const authQuery = wooAuthQuery(ctx);
+      const query: Record<string, string> = {
+        ...authQuery,
+        per_page: String(params.per_page ?? 25),
+        page: String(params.page ?? 1),
+      };
+      if (params.search) query.search = params.search;
+      if (params.role) query.role = params.role;
+
+      const customers = await ctx.apiExecutor.request({
+        method: 'GET',
+        url: `${baseUrl}/customers`,
+        query,
+      });
+
+      const items: any[] = Array.isArray(customers) ? customers : [];
+      if (items.length === 0) {
+        return { content: 'No customers found.', metadata: { customerCount: 0 } };
+      }
+
+      const lines = items.map((c: any) => formatCustomer(c));
+      return {
+        content: `${items.length} customer(s):\n${lines.join('\n')}`,
+        metadata: { customerCount: items.length },
+      };
+    } catch (err) {
+      return wooError(err);
+    }
+  },
+};
+
+// ─── Adapter Export ─────────────────────────────────────
+
+export const woocommerceAdapter: SkillAdapter = {
+  skillId: 'woocommerce',
+  name: 'WooCommerce',
+  // Base URL is dynamic based on site URL; tools use ctx.apiExecutor.request() with full URLs
+  baseUrl: 'https://SITE/wp-json/wc/v3',
+  auth: {
+    type: 'credentials',
+    fields: ['consumerKey', 'consumerSecret'],
+  },
+  tools: {
+    woo_list_products: listProducts,
+    woo_create_product: createProduct,
+    woo_list_orders: listOrders,
+    woo_update_order: updateOrder,
+    woo_list_customers: listCustomers,
+  },
+  configSchema: {
+    siteUrl: {
+      type: 'string' as const,
+      label: 'Site URL',
+      description: 'Your WooCommerce site URL (e.g. "https://mysite.com")',
+      required: true,
+    },
+  },
+  rateLimits: {
+    requestsPerSecond: 5,
+    burstLimit: 15,
+  },
+};