@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/gmail/gmail-adapter.ts

@@ -0,0 +1,210 @@
+import type { gmail_v1 } from '@googleapis/gmail'
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+
+/**
+ * Gmail credentials format
+ * Stored in credentials table, encrypted
+ */
+interface GmailCredentials {
+  type: 'oauth2' | 'service-account'
+  // OAuth2 credentials
+  clientId?: string
+  clientSecret?: string
+  refreshToken?: string
+  // Service account credentials
+  serviceAccountKey?: Record<string, unknown>
+}
+
+/**
+ * Send email parameters
+ */
+interface SendEmailParams {
+  to: string
+  subject: string
+  body: string
+  cc?: string
+  from?: string
+}
+
+/**
+ * Send email result
+ */
+interface SendEmailResult {
+  messageId: string
+  threadId: string
+}
+
+/**
+ * Gmail adapter for sending emails via Gmail API
+ *
+ * Supported methods:
+ * - sendEmail: Send email message
+ *
+ * @example
+ * const adapter = new GmailAdapter()
+ * const result = await adapter.call('sendEmail', {
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   body: 'This is a test email'
+ * }, {
+ *   type: 'oauth2',
+ *   clientId: '...',
+ *   clientSecret: '...',
+ *   refreshToken: '...'
+ * })
+ */
+export class GmailAdapter implements BaseIntegrationAdapter {
+  readonly name = 'gmail'
+
+  /**
+   * Call Gmail API method
+   * @param method - Method name (e.g., 'sendEmail')
+   * @param params - Method parameters
+   * @param credentials - OAuth2 or service account credentials
+   * @param context - Execution context for logging and tracing
+   */
+  async call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown> {
+    // Validate credentials format
+    if (!this.validateCredentials(credentials)) {
+      throw new ToolingError(
+        'credentials_invalid',
+        'Invalid Gmail credentials',
+        { integration: 'gmail', method }
+      )
+    }
+    const gmailCreds = credentials as unknown as GmailCredentials
+
+    // Create authenticated Gmail client
+    const gmail = await this.createClient(gmailCreds)
+
+    // Route to method handler
+    switch (method) {
+      case 'sendEmail':
+        return this.sendEmail(gmail, params as SendEmailParams, context)
+      default:
+        throw new ToolingError(
+          'method_not_found',
+          `Unknown method: ${method}`,
+          { integration: 'gmail', method }
+        )
+    }
+  }
+
+  /**
+   * Create authenticated Gmail client (lazy loads @googleapis/gmail SDK)
+   */
+  private async createClient(creds: GmailCredentials): Promise<gmail_v1.Gmail> {
+    const { gmail } = await import('@googleapis/gmail')
+    const { OAuth2Client, GoogleAuth } = await import('googleapis-common')
+
+    if (creds.type === 'oauth2') {
+      const auth = new OAuth2Client(
+        creds.clientId,
+        creds.clientSecret
+      )
+      auth.setCredentials({ refresh_token: creds.refreshToken })
+
+      return gmail({ version: 'v1', auth })
+    } else {
+      // Service account (for workspace-wide access)
+      const auth = new GoogleAuth({
+        credentials: creds.serviceAccountKey,
+        scopes: ['https://www.googleapis.com/auth/gmail.send']
+      })
+
+      return gmail({ version: 'v1', auth: await auth.getClient() as any })
+    }
+  }
+
+  /**
+   * Send email via Gmail API
+   */
+  private async sendEmail(
+    gmail: gmail_v1.Gmail,
+    params: SendEmailParams,
+    context?: ExecutionContext
+  ): Promise<SendEmailResult> {
+    // Validate params
+    if (!params.to || !params.subject || !params.body) {
+      throw new ToolingError(
+        'validation_error',
+        'Missing required fields: to, subject, body',
+        { params }
+      )
+    }
+
+    // Build RFC 2822 formatted message
+    const messageParts = [
+      `To: ${params.to}`,
+      `Subject: ${params.subject}`,
+      params.cc ? `Cc: ${params.cc}` : '',
+      'Content-Type: text/html; charset=utf-8',
+      '',
+      params.body
+    ]
+    const message = messageParts.filter(Boolean).join('\n')
+
+    // Base64 encode (URL-safe)
+    const encodedMessage = Buffer.from(message)
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '')
+
+    try {
+      const response = await gmail.users.messages.send({
+        userId: 'me',
+        requestBody: {
+          raw: encodedMessage
+        }
+      })
+
+      if (context?.logger) {
+        console.log('[GmailAdapter] Email sent:', {
+          organizationId: context.organizationId,
+          executionId: context.executionId,
+          to: params.to,
+          subject: params.subject,
+          messageId: response.data.id,
+          threadId: response.data.threadId
+        })
+      }
+
+      return {
+        messageId: response.data.id!,
+        threadId: response.data.threadId!
+      }
+    } catch (error: any) {
+      throw new ToolingError(
+        'api_error',
+        `Gmail API error: ${error.message}`,
+        { statusCode: error.code, details: error }
+      )
+    }
+  }
+
+  /**
+   * Validate credentials structure
+   * Required by BaseIntegrationAdapter interface
+   */
+  validateCredentials(creds: Record<string, unknown>): boolean {
+    if (!creds.type) {
+      return false
+    }
+
+    if (creds.type === 'oauth2') {
+      return !!(creds.clientId && creds.clientSecret && creds.refreshToken)
+    } else if (creds.type === 'service-account') {
+      return !!creds.serviceAccountKey
+    }
+
+    return false
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/gmail/gmail-tools.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod'
+import { createIntegrationTool } from '../../../tool'
+import type { Tool } from '../../../../types'
+
+/**
+ * Create Gmail send email tool
+ *
+ * Creates a tool that sends emails via Gmail API using organization credentials.
+ * Supports both OAuth2 and service account authentication, as well as mock credentials for testing.
+ *
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that sends email via Gmail
+ *
+ * @example
+ * // Create tool for support email account
+ * const sendEmail = createGmailSendEmailTool('support-gmail')
+ *
+ * // In agent definition:
+ * export const emailAgentDefinition: AgentDefinition = {
+ *   config: {
+ *     resourceId: 'email-agent',
+ *     name: 'Email Agent',
+ *     description: 'Sends emails on behalf of users'
+ *   },
+ *   tools: [sendEmail],
+ *   // ...
+ * }
+ *
+ * @example
+ * // Create multiple tools for different accounts
+ * const sendSupportEmail = createGmailSendEmailTool('support-gmail')
+ * const sendSalesEmail = createGmailSendEmailTool('sales-gmail')
+ *
+ * // Use in agent with multiple email accounts
+ * tools: [sendSupportEmail, sendSalesEmail]
+ */
+export function createGmailSendEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'gmail_sendEmail',
+    description: 'Send an email via Gmail API',
+
+    inputSchema: z.object({
+      to: z.string().email().describe('Recipient email address'),
+      subject: z.string().describe('Email subject line'),
+      body: z.string().describe('Email body (HTML supported)'),
+      cc: z.string().email().optional().describe('Optional CC recipient'),
+      from: z.string().optional().describe('Optional sender display name (defaults to "me")')
+    }),
+
+    outputSchema: z.object({
+      messageId: z.string().describe('Gmail message ID'),
+      threadId: z.string().describe('Gmail thread ID')
+    }),
+
+    integration: 'gmail' as const,
+    method: 'sendEmail' as const,
+    credentialName: credentialName
+  })
+}
+
+/**
+ * Create Gmail send email tool with custom name
+ *
+ * Allows creating multiple Gmail tools with different names for the same organization.
+ * Useful when you want to distinguish between different email accounts in tool naming.
+ *
+ * @param toolName - Custom name for the tool (e.g., 'send_support_email')
+ * @param credentialName - Name of credential in credentials table
+ * @returns Tool that sends email via Gmail
+ *
+ * @example
+ * const sendSupportEmail = createGmailSendEmailToolNamed(
+ *   'send_support_email',
+ *   'support-gmail'
+ * )
+ *
+ * const sendSalesEmail = createGmailSendEmailToolNamed(
+ *   'send_sales_email',
+ *   'sales-gmail'
+ * )
+ */
+export function createGmailSendEmailToolNamed(toolName: string, credentialName: string): Tool {
+  return createIntegrationTool({
+    name: toolName,
+    description: `Send an email via Gmail API using ${credentialName} credentials`,
+
+    inputSchema: z.object({
+      to: z.string().email().describe('Recipient email address'),
+      subject: z.string().describe('Email subject line'),
+      body: z.string().describe('Email body (HTML supported)'),
+      cc: z.string().email().optional().describe('Optional CC recipient'),
+      from: z.string().optional().describe('Optional sender display name (defaults to "me")')
+    }),
+
+    outputSchema: z.object({
+      messageId: z.string().describe('Gmail message ID'),
+      threadId: z.string().describe('Gmail thread ID')
+    }),
+
+    integration: 'gmail' as const,
+    method: 'sendEmail' as const,
+    credentialName: credentialName
+  })
+}

package/src/execution/engine/tools/integration/server/adapters/google-sheets/__tests__/google-sheets.integration.test.ts

@@ -0,0 +1,261 @@
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
+import { GoogleSheetsAdapter } from '../google-sheets-adapter'
+import type { ExecutionContext } from '../../../../../../base/types'
+import { createClient } from '@supabase/supabase-js'
+import type { Database } from '../../../../../../../../supabase/database.types'
+import { decryptCredentialValue } from '../../../../../../../../auth/multi-tenancy/credentials/server/service'
+
+/**
+ * Google Sheets Integration Tests
+ *
+ * Consolidated test suite covering:
+ * - Basic CRUD operations (read, write, append, batch update, clear)
+ * - Workflow-friendly methods (getHeaders, getRowByValue, upsertRow, etc.)
+ * - Error handling
+ *
+ * Rate limit: Google Sheets API allows 60 requests/minute/user
+ * Tests are grouped to minimize API calls.
+ */
+
+const SKIP_TESTS = !process.env.SUPABASE_URL || !process.env.SUPABASE_SERVICE_KEY || !process.env.SECRETS_ENCRYPTION_KEY
+
+describe.skipIf(SKIP_TESTS)('Google Sheets Integration Tests', () => {
+  const adapter = new GoogleSheetsAdapter()
+  const organizationId = 'f9aa5a56-8c13-4cd1-9161-8827ae7b452b'
+  const credentialName = 'elevasis-google-sheets'
+  const spreadsheetId = '1cgrLVPE0bpq4GAqo8RvRh3VkP49Ut-osuNKL-hNx44Y'
+
+  const context: ExecutionContext = {
+    organizationId,
+    executionId: 'sheets-integration-test',
+    resourceId: 'sheets-test-agent',
+    resourceType: 'agent',
+    logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn(), child: vi.fn().mockReturnThis() }
+  }
+
+  let credentials: Record<string, unknown>
+  let testSheetName: string
+
+  beforeAll(async () => {
+    console.log('\n=== Google Sheets Integration Tests ===')
+    const supabase = createClient<Database>(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!)
+
+    const { data: credRow, error } = await supabase
+      .from('credentials')
+      .select('encrypted_value')
+      .eq('organization_id', organizationId)
+      .eq('name', credentialName)
+      .single()
+
+    if (error || !credRow) {
+      throw new Error(`Credential not found: ${error?.message}`)
+    }
+
+    credentials = decryptCredentialValue(credRow.encrypted_value)
+    console.log('✓ Credentials loaded\n')
+  }, 15000)
+
+  afterAll(async () => {
+    // Clean up test data
+    const rangesToClean = ['Test!A100:C105', 'Test!A200:C210', 'Test!A300:C302']
+    for (const range of rangesToClean) {
+      try {
+        await adapter.call('clearRange', { spreadsheetId, range }, credentials, context)
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+    console.log('\n=== Tests Complete ===\n')
+  })
+
+  // ============================================
+  // 1. Basic CRUD Operations
+  // ============================================
+
+  describe('Basic CRUD Operations', () => {
+    it('should get spreadsheet metadata', async () => {
+      const result = (await adapter.call('getSpreadsheetMetadata', { spreadsheetId }, credentials, context)) as {
+        title: string
+        sheets: Array<{ sheetId: number; title: string; index: number }>
+      }
+
+      expect(result.title).toBeTruthy()
+      expect(result.sheets.length).toBeGreaterThan(0)
+      testSheetName = result.sheets[0].title
+      console.log(`Using sheet: ${testSheetName}`)
+    }, 15000)
+
+    it('should read, write, and clear data', async () => {
+      const range = 'Test!A100:C101'
+      const testData = [
+        ['TestName', '101', 'Test description'],
+        ['TestName2', '102', 'Another description']
+      ]
+
+      // Write
+      const writeResult = (await adapter.call(
+        'writeSheet',
+        { spreadsheetId, range, values: testData },
+        credentials,
+        context
+      )) as { updatedCells: number }
+      expect(writeResult.updatedCells).toBe(6)
+
+      // Read back
+      const readResult = (await adapter.call('readSheet', { spreadsheetId, range }, credentials, context)) as {
+        values: string[][]
+      }
+      expect(readResult.values[0][0]).toBe('TestName')
+      expect(readResult.values[1][0]).toBe('TestName2')
+
+      // Clear
+      const clearResult = (await adapter.call('clearRange', { spreadsheetId, range }, credentials, context)) as {
+        clearedRange: string
+      }
+      expect(clearResult.clearedRange).toContain('A100')
+
+      // Verify cleared
+      const verifyResult = (await adapter.call('readSheet', { spreadsheetId, range }, credentials, context)) as {
+        values: string[][]
+      }
+      expect(verifyResult.values.length).toBe(0)
+    }, 30000)
+
+    it('should append rows and batch update', async () => {
+      // Append
+      const appendResult = (await adapter.call(
+        'appendRows',
+        {
+          spreadsheetId,
+          range: 'Test!A200:C200',
+          values: [['Appended1', '201', 'Appended row']]
+        },
+        credentials,
+        context
+      )) as { updatedRows: number }
+      expect(appendResult.updatedRows).toBe(1)
+
+      // Batch update
+      const batchResult = (await adapter.call(
+        'batchUpdate',
+        {
+          spreadsheetId,
+          data: [
+            { range: 'Test!A202:C202', values: [['Batch1', '202', 'Batch row 1']] },
+            { range: 'Test!A203:C203', values: [['Batch2', '203', 'Batch row 2']] }
+          ]
+        },
+        credentials,
+        context
+      )) as { totalUpdatedCells: number; totalUpdatedRows: number }
+      expect(batchResult.totalUpdatedRows).toBe(2)
+    }, 20000)
+  })
+
+  // ============================================
+  // 2. Workflow-Friendly Methods
+  // ============================================
+
+  describe('Workflow-Friendly Methods', () => {
+    it('should get headers and find row by value', async () => {
+      // Setup: Write test data with headers
+      await adapter.call(
+        'writeSheet',
+        {
+          spreadsheetId,
+          range: 'Test!A1:C2',
+          values: [
+            ['Name', 'Id', 'Description'],
+            ['FindMe', '999', 'Test row for lookup']
+          ]
+        },
+        credentials,
+        context
+      )
+
+      // Get headers
+      const headersResult = (await adapter.call(
+        'getHeaders',
+        { spreadsheetId, sheetName: 'Test' },
+        credentials,
+        context
+      )) as { headers: string[]; columnMap: Record<string, string> }
+      expect(headersResult.headers).toContain('Name')
+      expect(headersResult.columnMap.Name).toBe('A')
+
+      // Find row by value
+      const findResult = (await adapter.call(
+        'getRowByValue',
+        { spreadsheetId, sheetName: 'Test', searchColumn: 'A', searchValue: 'FindMe' },
+        credentials,
+        context
+      )) as { found: boolean; rowNumber: number | null; rowData: string[] | null }
+      expect(findResult.found).toBe(true)
+      expect(findResult.rowData?.[0]).toBe('FindMe')
+    }, 20000)
+
+    it('should upsert and update rows by value', async () => {
+      const uniqueKey = `UpsertTest_${Date.now()}`
+
+      // Upsert (insert)
+      const insertResult = (await adapter.call(
+        'upsertRow',
+        {
+          spreadsheetId,
+          sheetName: 'Test',
+          keyColumn: 'A',
+          keyValue: uniqueKey,
+          rowData: { Name: uniqueKey, Id: '888', Description: 'Inserted via upsert' }
+        },
+        credentials,
+        context
+      )) as { action: 'inserted' | 'updated' }
+      expect(insertResult.action).toBe('inserted')
+
+      // Upsert (update)
+      const updateResult = (await adapter.call(
+        'upsertRow',
+        {
+          spreadsheetId,
+          sheetName: 'Test',
+          keyColumn: 'A',
+          keyValue: uniqueKey,
+          rowData: { Name: uniqueKey, Id: '888', Description: 'Updated via upsert' }
+        },
+        credentials,
+        context
+      )) as { action: 'inserted' | 'updated' }
+      expect(updateResult.action).toBe('updated')
+
+      // Clean up
+      await adapter.call(
+        'deleteRowByValue',
+        { spreadsheetId, sheetName: 'Test', searchColumn: 'A', searchValue: uniqueKey },
+        credentials,
+        context
+      )
+    }, 25000)
+  })
+
+  // ============================================
+  // 3. Error Handling
+  // ============================================
+
+  describe('Error Handling', () => {
+    it('should handle invalid spreadsheet ID', async () => {
+      await expect(
+        adapter.call('readSheet', { spreadsheetId: 'invalid-id', range: 'Sheet1!A1' }, credentials, context)
+      ).rejects.toThrow()
+    }, 15000)
+
+    it('should validate required fields', async () => {
+      await expect(adapter.call('readSheet', { spreadsheetId: '', range: 'A1' }, credentials, context)).rejects.toThrow(
+        'Missing required field: spreadsheetId'
+      )
+
+      await expect(
+        adapter.call('writeSheet', { spreadsheetId, range: 'A1', values: null }, credentials, context)
+      ).rejects.toThrow('Missing required field: values')
+    }, 15000)
+  })
+})