@elevasis/core 0.13.0 → 0.14.0

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

@@ -1,210 +1,204 @@
-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
-  }
-}
+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
+  /**
+   * Idempotency key. When provided, embedded as the RFC 2822 Message-ID header so
+   * duplicate sends from platform_internal retries are deduped on the recipient side.
+   * Pass a stable workflow-derived hash (e.g. `<execId>.<step>@elevasis.io`).
+   */
+  idempotencyKey?: 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. When idempotencyKey is provided, emit a stable
+    // Message-ID header — duplicate sends from platform_internal retries land with the
+    // same Message-ID and are deduped by recipient MTAs / threading clients.
+    const messageIdHeader = params.idempotencyKey ? `Message-ID: <${params.idempotencyKey}@elevasis.io>` : ''
+    const messageParts = [
+      `To: ${params.to}`,
+      `Subject: ${params.subject}`,
+      params.cc ? `Cc: ${params.cc}` : '',
+      messageIdHeader,
+      '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/resend/fetch/send-email/index.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Resend sendEmail — idempotency-key regression tests
+ *
+ * Guards the Idempotency-Key header plumbing added as part of the
+ * cache-as-contract-leak fix. Platform-internal retries (TypeError /
+ * ReferenceError reclassified as platform_internal) must be safe for write
+ * tools — Resend dedupes server-side when the same Idempotency-Key arrives.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { sendEmail } from './index'
+import type { ResendCredentials, SendEmailParams } from '../utils/types'
+
+const credentials: ResendCredentials = { apiKey: 're_test_123' }
+const baseParams: SendEmailParams = {
+  from: 'Test <test@elevasis.io>',
+  to: 'recipient@example.com',
+  subject: 'Hello',
+  html: '<p>Hi</p>'
+}
+
+function mockResendOk(): ReturnType<typeof vi.fn> {
+  const fetchMock = vi.fn(async () =>
+    Promise.resolve(
+      new Response(JSON.stringify({ id: 'email_abc' }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' }
+      })
+    )
+  )
+  ;(globalThis as unknown as { fetch: typeof fetch }).fetch = fetchMock as unknown as typeof fetch
+  return fetchMock
+}
+
+describe('Resend sendEmail — idempotency key', () => {
+  let originalFetch: typeof fetch
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('omits the Idempotency-Key header when idempotencyKey is not provided', async () => {
+    const fetchMock = mockResendOk()
+
+    await sendEmail(credentials, baseParams)
+
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const init = fetchMock.mock.calls[0][1] as RequestInit
+    const headers = init.headers as Record<string, string>
+    expect(headers['Idempotency-Key']).toBeUndefined()
+    // Sanity check: required headers are still present
+    expect(headers.Authorization).toBe('Bearer re_test_123')
+    expect(headers['Content-Type']).toBe('application/json')
+  })
+
+  it('passes idempotencyKey through as the Idempotency-Key header', async () => {
+    const fetchMock = mockResendOk()
+
+    await sendEmail(credentials, { ...baseParams, idempotencyKey: 'wf-exec-001-step-send-approval' })
+
+    const init = fetchMock.mock.calls[0][1] as RequestInit
+    const headers = init.headers as Record<string, string>
+    expect(headers['Idempotency-Key']).toBe('wf-exec-001-step-send-approval')
+  })
+
+  it('sends the same Idempotency-Key on caller-driven retries (regression: platform_internal retries must dedupe)', async () => {
+    const fetchMock = mockResendOk()
+
+    const params: SendEmailParams = { ...baseParams, idempotencyKey: 'stable-key-xyz' }
+
+    // Simulate two calls with identical params (e.g. caller retries after a
+    // platform_internal failure). Both must carry the same Idempotency-Key
+    // so Resend collapses them into a single send.
+    await sendEmail(credentials, params)
+    await sendEmail(credentials, params)
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+
+    const firstHeaders = (fetchMock.mock.calls[0][1] as RequestInit).headers as Record<string, string>
+    const secondHeaders = (fetchMock.mock.calls[1][1] as RequestInit).headers as Record<string, string>
+    expect(firstHeaders['Idempotency-Key']).toBe('stable-key-xyz')
+    expect(secondHeaders['Idempotency-Key']).toBe('stable-key-xyz')
+  })
+})