@elevasis/core 0.12.0 → 0.14.0

package/src/execution/engine/tools/integration/server/adapters/resend/fetch/send-email/index.ts

@@ -1,134 +1,141 @@
-import { ToolingError } from '../../../../../../types'
-import type { ExecutionContext } from '../../../../../../../base/types'
-import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
-import type { ResendCredentials, SendEmailParams, SendEmailResult, ResendSendEmailResponse } from '../utils/types'
-
-/**
- * Send an email using Resend API
- *
- * @param credentials - Resend API credentials (apiKey)
- * @param params - Email parameters (from, to, subject, html/text, etc.)
- * @param context - Execution context for logging
- * @returns Email ID and success status
- * @throws ToolingError if email sending fails
- *
- * @example
- * // Send a simple email
- * const result = await sendEmail(
- *   { apiKey: 're_xxx' },
- *   {
- *     from: 'Alex <alexl@elevasis.io>',
- *     to: 'john@example.com',
- *     subject: 'Discovery Call Reminder',
- *     html: '<p>Your call is tomorrow...</p>',
- *     headers: {
- *       'List-Unsubscribe': '<https://elevasis.io/api/unsubscribe?email=...>',
- *       'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
- *     }
- *   },
- *   context
- * )
- */
-export async function sendEmail(
-  credentials: ResendCredentials,
-  params: SendEmailParams,
-  context?: ExecutionContext
-): Promise<SendEmailResult> {
-  const { apiKey } = credentials
-  const { from, to, subject, html, text, replyTo, cc, bcc, headers, tags } = params
-
-  // Validate required parameters
-  if (!apiKey) {
-    throw new ToolingError('credentials_invalid', 'Resend API credentials must include apiKey', {
-      integration: 'resend',
-      method: 'sendEmail'
-    })
-  }
-
-  if (!from || !to || !subject) {
-    throw new ToolingError('validation_error', 'From, to, and subject are required', {
-      integration: 'resend',
-      method: 'sendEmail',
-      params: { from, to, subject }
-    })
-  }
-
-  if (!html && !text) {
-    throw new ToolingError('validation_error', 'Either html or text content is required', {
-      integration: 'resend',
-      method: 'sendEmail'
-    })
-  }
-
-  // Build URL
-  const url = 'https://api.resend.com/emails'
-
-  // Build request body
-  const requestBody: Record<string, unknown> = {
-    from,
-    to: Array.isArray(to) ? to : [to],
-    subject
-  }
-
-  if (html) requestBody.html = html
-  if (text) requestBody.text = text
-  if (replyTo) requestBody.reply_to = replyTo
-  if (cc) requestBody.cc = Array.isArray(cc) ? cc : [cc]
-  if (bcc) requestBody.bcc = Array.isArray(bcc) ? bcc : [bcc]
-  if (headers) requestBody.headers = headers
-  if (tags) requestBody.tags = tags
-
-  try {
-    // Execute with retry logic
-    const response = await withRetry(async () => {
-      const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-          Authorization: `Bearer ${apiKey}`,
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(requestBody)
-      })
-
-      // Handle HTTP errors
-      if (!res.ok) {
-        throw await createHttpError(res, {
-          integration: 'resend',
-          method: 'sendEmail',
-          organizationId: context?.organizationId
-        })
-      }
-
-      return res
-    }, DEFAULT_RETRY_POLICY)
-
-    // Parse response
-    const result = (await response.json()) as ResendSendEmailResponse
-
-    // Log success
-    if (context?.logger) {
-      context.logger.info(
-        `[ResendAdapter] Email sent: organizationId=${context.organizationId} executionId=${context.executionId} emailId=${result.id} to=${Array.isArray(to) ? to.join(',') : to}`
-      )
-    }
-
-    // Return standardized result
-    return {
-      id: result.id,
-      success: true
-    }
-  } catch (error) {
-    // Re-throw ToolingError as-is
-    if (error instanceof ToolingError) {
-      throw error
-    }
-
-    // Wrap unknown errors
-    throw new ToolingError('api_error', `Failed to send email via Resend: ${(error as Error).message}`, {
-      integration: 'resend',
-      method: 'sendEmail',
-      organizationId: context?.organizationId,
-      originalError: error
-    })
-  }
-}
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ResendCredentials, SendEmailParams, SendEmailResult, ResendSendEmailResponse } from '../utils/types'
+
+/**
+ * Send an email using Resend API
+ *
+ * @param credentials - Resend API credentials (apiKey)
+ * @param params - Email parameters (from, to, subject, html/text, etc.)
+ * @param context - Execution context for logging
+ * @returns Email ID and success status
+ * @throws ToolingError if email sending fails
+ *
+ * @example
+ * // Send a simple email
+ * const result = await sendEmail(
+ *   { apiKey: 're_xxx' },
+ *   {
+ *     from: 'Alex <alexl@elevasis.io>',
+ *     to: 'john@example.com',
+ *     subject: 'Discovery Call Reminder',
+ *     html: '<p>Your call is tomorrow...</p>',
+ *     headers: {
+ *       'List-Unsubscribe': '<https://elevasis.io/api/unsubscribe?email=...>',
+ *       'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click'
+ *     }
+ *   },
+ *   context
+ * )
+ */
+export async function sendEmail(
+  credentials: ResendCredentials,
+  params: SendEmailParams,
+  context?: ExecutionContext
+): Promise<SendEmailResult> {
+  const { apiKey } = credentials
+  const { from, to, subject, html, text, replyTo, cc, bcc, headers, tags, idempotencyKey } = params
+
+  // Validate required parameters
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'Resend API credentials must include apiKey', {
+      integration: 'resend',
+      method: 'sendEmail'
+    })
+  }
+
+  if (!from || !to || !subject) {
+    throw new ToolingError('validation_error', 'From, to, and subject are required', {
+      integration: 'resend',
+      method: 'sendEmail',
+      params: { from, to, subject }
+    })
+  }
+
+  if (!html && !text) {
+    throw new ToolingError('validation_error', 'Either html or text content is required', {
+      integration: 'resend',
+      method: 'sendEmail'
+    })
+  }
+
+  // Build URL
+  const url = 'https://api.resend.com/emails'
+
+  // Build request body
+  const requestBody: Record<string, unknown> = {
+    from,
+    to: Array.isArray(to) ? to : [to],
+    subject
+  }
+
+  if (html) requestBody.html = html
+  if (text) requestBody.text = text
+  if (replyTo) requestBody.reply_to = replyTo
+  if (cc) requestBody.cc = Array.isArray(cc) ? cc : [cc]
+  if (bcc) requestBody.bcc = Array.isArray(bcc) ? bcc : [bcc]
+  if (headers) requestBody.headers = headers
+  if (tags) requestBody.tags = tags
+
+  try {
+    // Build request headers; include Idempotency-Key when provided so platform_internal
+    // retries dedupe server-side instead of double-sending.
+    const requestHeaders: Record<string, string> = {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json'
+    }
+    if (idempotencyKey) {
+      requestHeaders['Idempotency-Key'] = idempotencyKey
+    }
+
+    // Execute with retry logic
+    const response = await withRetry(async () => {
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: requestHeaders,
+        body: JSON.stringify(requestBody)
+      })
+
+      // Handle HTTP errors
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'resend',
+          method: 'sendEmail',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    // Parse response
+    const result = (await response.json()) as ResendSendEmailResponse
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[ResendAdapter] Email sent: organizationId=${context.organizationId} executionId=${context.executionId} emailId=${result.id} to=${Array.isArray(to) ? to.join(',') : to}`
+      )
+    }
+
+    // Return standardized result
+    return {
+      id: result.id,
+      success: true
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to send email via Resend: ${(error as Error).message}`, {
+      integration: 'resend',
+      method: 'sendEmail',
+      organizationId: context?.organizationId,
+      originalError: error
+    })
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/resend/fetch/utils/types.ts

@@ -1,75 +1,76 @@
-/**
- * Resend API Types
- *
- * Type definitions for Resend email API operations.
- */
-
-/**
- * Resend credentials format
- * Stored in credentials table, encrypted
- */
-export interface ResendCredentials {
-  apiKey: string // API key (re_xxxxxxxxx)
-}
-
-/**
- * Send email parameters
- */
-export interface SendEmailParams {
-  from: string // "Name <sender@domain.com>"
-  to: string | string[] // Recipients (max 50)
-  subject: string // Email subject
-  html?: string // HTML content
-  text?: string // Plain text (auto-generated from HTML if omitted)
-  replyTo?: string | string[] // Reply-to address
-  cc?: string | string[] // CC recipients
-  bcc?: string | string[] // BCC recipients
-  headers?: Record<string, string> // Custom headers (for unsubscribe)
-  tags?: Array<{ name: string; value: string }> // Key-value metadata
-}
-
-/**
- * Send email result
- */
-export interface SendEmailResult {
-  id: string // Email ID
-  success: boolean
-}
-
-/**
- * Get email parameters
- */
-export interface GetEmailParams {
-  emailId: string // Email ID to retrieve
-}
-
-/**
- * Get email result
- */
-export interface GetEmailResult {
-  id: string
-  to: string[]
-  from: string
-  subject: string
-  lastEvent: string // 'sent', 'delivered', 'bounced', 'complained', 'failed'
-  createdAt: string
-}
-
-/**
- * Resend API response for send email
- */
-export interface ResendSendEmailResponse {
-  id: string
-}
-
-/**
- * Resend API response for get email
- */
-export interface ResendGetEmailResponse {
-  id: string
-  to: string[]
-  from: string
-  subject: string
-  last_event: string
-  created_at: string
-}
+/**
+ * Resend API Types
+ *
+ * Type definitions for Resend email API operations.
+ */
+
+/**
+ * Resend credentials format
+ * Stored in credentials table, encrypted
+ */
+export interface ResendCredentials {
+  apiKey: string // API key (re_xxxxxxxxx)
+}
+
+/**
+ * Send email parameters
+ */
+export interface SendEmailParams {
+  from: string // "Name <sender@domain.com>"
+  to: string | string[] // Recipients (max 50)
+  subject: string // Email subject
+  html?: string // HTML content
+  text?: string // Plain text (auto-generated from HTML if omitted)
+  replyTo?: string | string[] // Reply-to address
+  cc?: string | string[] // CC recipients
+  bcc?: string | string[] // BCC recipients
+  headers?: Record<string, string> // Custom headers (for unsubscribe)
+  tags?: Array<{ name: string; value: string }> // Key-value metadata
+  idempotencyKey?: string // Resend Idempotency-Key header — same key returns the original send instead of duplicating
+}
+
+/**
+ * Send email result
+ */
+export interface SendEmailResult {
+  id: string // Email ID
+  success: boolean
+}
+
+/**
+ * Get email parameters
+ */
+export interface GetEmailParams {
+  emailId: string // Email ID to retrieve
+}
+
+/**
+ * Get email result
+ */
+export interface GetEmailResult {
+  id: string
+  to: string[]
+  from: string
+  subject: string
+  lastEvent: string // 'sent', 'delivered', 'bounced', 'complained', 'failed'
+  createdAt: string
+}
+
+/**
+ * Resend API response for send email
+ */
+export interface ResendSendEmailResponse {
+  id: string
+}
+
+/**
+ * Resend API response for get email
+ */
+export interface ResendGetEmailResponse {
+  id: string
+  to: string[]
+  from: string
+  subject: string
+  last_event: string
+  created_at: string
+}

package/src/execution/engine/tools/integration/service.test.ts

@@ -185,30 +185,55 @@ describe('IntegrationService — credential cache (context.store)', () => {
       })
     })
 
-    it('throws TypeError when context.store is undefined (simulates the pre-fix bug)', async () => {
-      // This documents the exact failure mode that shipped: dispatchIntegrationTool
-      // constructed a context without `store`. The crash was:
+    it('treats context.store as opportunistic — missing store falls through to credential fetch instead of crashing', async () => {
+      // 2026-04-25 regression guard: the original bug crashed with
       //   "Cannot read properties of undefined (reading 'get')"
+      // because context.store.get(cacheKey) had no optional chaining. After the
+      // cache-as-contract-leak fix, the cache is treated as a perf optimization,
+      // not a load-bearing contract. A missing store must therefore fall through
+      // to the credentialsService fetch path and succeed.
       const adapter = makeStubAdapter('stripe')
       const service = new IntegrationService(new Map([['stripe', adapter]]))
       const credentials = { apiKey: 'sk_test_123' }
 
       mockGetCredential.mockResolvedValue(credentials)
 
-      // Deliberately construct a context without `store` (mimics the pre-fix bug)
-      const brokenContext = {
+      const contextWithoutStore = {
         executionId: 'exec-broken',
         organizationId: 'org-test-001',
         organizationName: 'Test Org',
         resourceId: 'resource-broken',
         executionDepth: 0,
         logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} }
-        // store is intentionally absent — this was the bug
+        // store is intentionally absent
       } as unknown as ExecutionContext
 
-      await expect(service.call('stripe', 'listPaymentLinks', {}, 'stripe-cred', brokenContext)).rejects.toThrow(
-        /Cannot read properties of undefined \(reading '(get|set)'\)/
-      )
+      const result = await service.call('stripe', 'listPaymentLinks', {}, 'stripe-cred', contextWithoutStore)
+
+      expect(result).toEqual({ stubResult: true })
+      // Credentials must have been fetched once (no cache hit, no cache write).
+      expect(mockGetCredential).toHaveBeenCalledOnce()
+      expect(mockGetCredential).toHaveBeenCalledWith('org-test-001', 'stripe-cred')
+    })
+
+    it('handles a null context.store the same way as undefined (opportunistic fallthrough)', async () => {
+      const adapter = makeStubAdapter('stripe')
+      const service = new IntegrationService(new Map([['stripe', adapter]]))
+      mockGetCredential.mockResolvedValue({ apiKey: 'sk_test_123' })
+
+      const contextNullStore = {
+        executionId: 'exec-null',
+        organizationId: 'org-test-001',
+        organizationName: 'Test Org',
+        resourceId: 'resource-null',
+        executionDepth: 0,
+        logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+        store: null
+      } as unknown as ExecutionContext
+
+      await expect(service.call('stripe', 'listPaymentLinks', {}, 'stripe-cred', contextNullStore)).resolves.toEqual({
+        stubResult: true
+      })
     })
   })
 })

package/src/execution/engine/tools/integration/service.ts

@@ -89,9 +89,12 @@ export class IntegrationService {
       })
     }
 
-    // 4. Get credentials from registry (per-execution cache keyed by credential name)
+    // 4. Get credentials from registry (per-execution cache keyed by credential name).
+    // The store is an opportunistic perf cache — never a load-bearing contract.
+    // Optional chaining lets a missing/undefined store fall through to the fetch path
+    // instead of crashing with "Cannot read properties of undefined (reading 'get')".
     const cacheKey = `__cred_cache__:${credentialName}`
-    let credentials = context.store.get(cacheKey) as Record<string, unknown> | undefined
+    let credentials = context.store?.get(cacheKey) as Record<string, unknown> | undefined
 
     if (!credentials) {
       const { credentialsService } = getToolServices()
@@ -112,7 +115,7 @@ export class IntegrationService {
         })
       }
 
-      context.store.set(cacheKey, fetched)
+      context.store?.set(cacheKey, fetched)
       credentials = fetched
     }