@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/resend/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Resend Integration - Barrel Export
+ *
+ * Exports Resend adapter and tool factory functions.
+ */
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export * from './types'
+
+// ============================================================================
+// RESEND ADAPTER
+// ============================================================================
+
+export { ResendAdapter } from './resend-adapter'
+
+// ============================================================================
+// RESEND TOOLS
+// ============================================================================
+
+export {
+  createResendSendEmailTool,
+  createResendGetEmailTool,
+  createResendSendEmailToolNamed
+} from './resend-tools'

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

@@ -0,0 +1,108 @@
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+import { sendEmail } from './fetch/send-email/index'
+import { getEmail } from './fetch/get-email/index'
+
+/**
+ * Resend credentials format
+ * Stored in credentials table, encrypted
+ *
+ * Uses API key authentication only
+ */
+interface ResendCredentials {
+  apiKey: string // API key (re_xxxxxxxxx)
+}
+
+/**
+ * Send email parameters
+ */
+interface SendEmailParams {
+  from: string
+  to: string | string[]
+  subject: string
+  html?: string
+  text?: string
+  replyTo?: string | string[]
+  cc?: string | string[]
+  bcc?: string | string[]
+  headers?: Record<string, string>
+  tags?: Array<{ name: string; value: string }>
+}
+
+/**
+ * Get email parameters
+ */
+interface GetEmailParams {
+  emailId: string
+}
+
+/**
+ * Resend integration adapter
+ *
+ * Provides access to Resend transactional email API for sending emails
+ * with unsubscribe headers (RFC 8058 compliant).
+ *
+ * @example
+ * ```typescript
+ * const adapter = new ResendAdapter()
+ * const result = await adapter.call(
+ *   'sendEmail',
+ *   {
+ *     from: 'Alex <alexl@elevasis.io>',
+ *     to: 'john@example.com',
+ *     subject: 'Reminder',
+ *     html: '<p>Hello</p>'
+ *   },
+ *   { apiKey: 're_xxx' },
+ *   context
+ * )
+ * ```
+ */
+export class ResendAdapter implements BaseIntegrationAdapter {
+  readonly name = 'resend'
+
+  /**
+   * Call Resend API method
+   */
+  async call(
+    method: string,
+    params: unknown,
+    credentials: Record<string, unknown>,
+    context?: ExecutionContext
+  ): Promise<unknown> {
+    // Validate credentials first
+    if (!this.validateCredentials(credentials)) {
+      throw new ToolingError('credentials_invalid', 'Invalid Resend credentials', {
+        integration: this.name,
+        organizationId: context?.organizationId
+      })
+    }
+
+    // Safe to cast after validation confirms apiKey exists and is valid
+    const creds = credentials as unknown as ResendCredentials
+
+    // Route to method handler - delegate to fetch functions
+    switch (method) {
+      case 'sendEmail':
+        return sendEmail(creds, params as SendEmailParams, context)
+      case 'getEmail':
+        return getEmail(creds, params as GetEmailParams, context)
+      default:
+        throw new ToolingError('method_not_found', `Unknown Resend method: ${method}`, {
+          integration: this.name,
+          method,
+          organizationId: context?.organizationId
+        })
+    }
+  }
+
+  /**
+   * Validate Resend credentials
+   */
+  validateCredentials(credentials: Record<string, unknown>): boolean {
+    const creds = credentials as unknown as ResendCredentials
+    // Require API key (should start with 're_')
+    return !!creds.apiKey && typeof creds.apiKey === 'string' && creds.apiKey.length > 0
+  }
+}

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

@@ -0,0 +1,132 @@
+import { z } from 'zod'
+import type { Tool } from '../../../../types'
+import { createIntegrationTool } from '../../../tool'
+
+/**
+ * Create a tool that sends transactional emails via Resend
+ *
+ * @param credentialName - Name of the Resend credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createResendSendEmailTool('elevasis-resend')
+ * const result = await tool.execute({
+ *   from: 'Alex <alexl@elevasis.io>',
+ *   to: 'john@example.com',
+ *   subject: 'Discovery Call Reminder',
+ *   html: '<p>Your call is tomorrow...</p>'
+ * }, context)
+ * ```
+ */
+export function createResendSendEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'resend_send_email',
+    description: `Send a transactional email via Resend.
+
+Use this tool to send emails for:
+- Discovery call reminders (-24h, -1h before meeting)
+- Proposal follow-ups (Day 3, 7, 14)
+- Onboarding emails (welcome, kickoff scheduling)
+
+Examples:
+- Send reminder: from="Alex <alexl@elevasis.io>", to, subject, html with meeting details
+- With unsubscribe: Include headers with List-Unsubscribe and List-Unsubscribe-Post
+
+Supports RFC 8058 one-click unsubscribe via headers parameter.`,
+    inputSchema: z.object({
+      from: z.string().describe('Sender in format "Name <email@domain.com>"'),
+      to: z.union([z.string(), z.array(z.string())]).describe('Recipient email(s) - max 50'),
+      subject: z.string().describe('Email subject line'),
+      html: z.string().optional().describe('HTML email content'),
+      text: z.string().optional().describe('Plain text content (auto-generated from HTML if omitted)'),
+      replyTo: z.union([z.string(), z.array(z.string())]).optional().describe('Reply-to address(es)'),
+      cc: z.union([z.string(), z.array(z.string())]).optional().describe('CC recipient(s)'),
+      bcc: z.union([z.string(), z.array(z.string())]).optional().describe('BCC recipient(s)'),
+      headers: z.record(z.string(), z.string()).optional().describe('Custom headers (e.g., List-Unsubscribe)'),
+      tags: z.array(z.object({
+        name: z.string(),
+        value: z.string()
+      })).optional().describe('Key-value metadata tags')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Resend email ID'),
+      success: z.boolean().describe('Whether the email was sent successfully')
+    }),
+    integration: 'resend' as const,
+    method: 'sendEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that retrieves email status from Resend
+ *
+ * @param credentialName - Name of the Resend credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createResendGetEmailTool('elevasis-resend')
+ * const result = await tool.execute({
+ *   emailId: '49a3999c-0ce1-4ea6-ab68-afcd6dc2e794'
+ * }, context)
+ * // result.lastEvent: 'sent', 'delivered', 'bounced', 'complained', 'failed'
+ * ```
+ */
+export function createResendGetEmailTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'resend_get_email',
+    description: `Get email delivery status from Resend.
+
+Use this tool to check if an email was delivered successfully.
+
+Status values:
+- sent: Email was sent
+- delivered: Email was delivered to recipient
+- bounced: Email bounced (hard bounce)
+- complained: Recipient marked as spam
+- failed: Email failed to send
+
+Not required for MVP, but useful for debugging delivery issues.`,
+    inputSchema: z.object({
+      emailId: z.string().describe('Resend email ID to retrieve')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Email ID'),
+      to: z.array(z.string()).describe('Recipient email addresses'),
+      from: z.string().describe('Sender email address'),
+      subject: z.string().describe('Email subject'),
+      lastEvent: z.string().describe('Last delivery event (sent, delivered, bounced, complained, failed)'),
+      createdAt: z.string().describe('ISO timestamp when email was created')
+    }),
+    integration: 'resend' as const,
+    method: 'getEmail' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a named version of Resend send email tool (for multi-account support)
+ *
+ * @param toolName - Unique tool name
+ * @param credentialName - Name of the Resend credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * // Support multiple Resend accounts or domains
+ * const salesTool = createResendSendEmailToolNamed('resend_sales_send', 'resend-sales')
+ * const supportTool = createResendSendEmailToolNamed('resend_support_send', 'resend-support')
+ * ```
+ */
+export function createResendSendEmailToolNamed(
+  toolName: string,
+  credentialName: string
+): Tool {
+  const tool = createResendSendEmailTool(credentialName)
+  return {
+    ...tool,
+    name: toolName
+  }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Resend Types
+ *
+ * Type definitions for Resend email configuration and API operations.
+ */
+
+// ============================================================================
+// SENDER CONFIGURATION
+// ============================================================================
+
+/**
+ * Email sender configuration for Resend
+ *
+ * Used by workflows to configure email sending with consistent
+ * from address, reply-to, and signature across all emails.
+ *
+ * @example
+ * ```typescript
+ * const EMAIL: ResendEmailConfig = {
+ *   senderName: 'Alex from Elevasis',
+ *   senderEmail: 'hello@mail.elevasis.io',
+ *   replyTo: 'alexl@elevasis.io',
+ *   senderSignature: 'Best,\nAlex'
+ * }
+ * ```
+ */
+export interface ResendEmailConfig {
+  /** Display name for sender (e.g., "Alex from Elevasis") */
+  senderName: string
+  /** Email address only (e.g., "hello@mail.elevasis.io") */
+  senderEmail: string
+  /** Reply-To address for responses (e.g., real inbox) */
+  replyTo: string
+  /** Email signature for body content */
+  senderSignature: string
+  /** BCC address for archiving sent emails */
+  bcc?: string
+}
+
+// ============================================================================
+// API TYPES (re-exported)
+// ============================================================================
+
+export * from './fetch/utils/types'

package/src/execution/engine/tools/integration/server/adapters/signature-api/fetch/create-envelope/index.ts

@@ -0,0 +1,274 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { SignatureApiCredentials, CreateEnvelopeParams, CreateEnvelopeResult } from '../utils/types'
+
+const DEFAULT_API_URL = 'https://api.signatureapi.com/v1'
+
+/**
+ * Create a signature envelope via SignatureAPI
+ *
+ * @param credentials - SignatureAPI credentials (apiKey, optional apiUrl)
+ * @param params - Envelope parameters (title, documents, recipients)
+ * @param context - Execution context for logging
+ * @returns Envelope ID and status
+ * @throws ToolingError if creation fails
+ */
+export async function createEnvelope(
+  credentials: SignatureApiCredentials,
+  params: CreateEnvelopeParams,
+  context?: ExecutionContext
+): Promise<CreateEnvelopeResult> {
+  const { apiKey, apiUrl = DEFAULT_API_URL } = credentials
+  const { title, message, documents, recipients, metadata, webhookUrl, routing } = params
+
+  // Validate credentials
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'SignatureAPI credentials must include apiKey', {
+      integration: 'signature-api',
+      method: 'createEnvelope'
+    })
+  }
+
+  // Validate required params
+  if (!title || !documents?.length || !recipients?.length) {
+    throw new ToolingError('validation_error', 'Title, documents, and recipients are required', {
+      integration: 'signature-api',
+      method: 'createEnvelope'
+    })
+  }
+
+  // Map field types from our convenience types to SignatureAPI types
+  // SignatureAPI does NOT support 'date' - must use 'recipient_completed_date'
+  const mapFieldType = (type: string): string => {
+    if (type === 'date') return 'recipient_completed_date'
+    return type
+  }
+
+  // Standard page height for Letter size (792 points)
+  // SignatureAPI uses 'top' (from top of page) instead of 'y' (from bottom)
+  const PAGE_HEIGHT = 792
+
+  // Convert y (from bottom) to top (from top)
+  const yToTop = (y: number): number => PAGE_HEIGHT - y
+
+  // Build request body
+  // SignatureAPI requires separate arrays:
+  // - fixed_positions: coordinates with place_key
+  // - places: field definitions with key that matches place_key
+  let placeCounter = 0
+  const requestBody: Record<string, unknown> = {
+    title,
+    documents: documents.map((doc) => {
+      // Build fixed_positions and places arrays from our places data
+      const fixedPositions: Array<{
+        place_key: string
+        page: number
+        top: number
+        left: number
+      }> = []
+
+      const places: Array<{
+        key: string
+        type: string
+        recipient_key: string
+        font_color?: string
+      }> = []
+
+      doc.places?.forEach((place) => {
+        const placeKey = `place_${placeCounter++}`
+
+        // Fixed position (coordinates)
+        fixedPositions.push({
+          place_key: placeKey,
+          page: place.page,
+          top: yToTop(place.y), // Convert y (from bottom) to top (from top)
+          left: place.x
+        })
+
+        // Place definition (field type, recipient, and optional styling)
+        const placeObj: {
+          key: string
+          type: string
+          recipient_key: string
+          font_color?: string
+        } = {
+          key: placeKey,
+          type: mapFieldType(place.type),
+          recipient_key: place.recipientKey
+        }
+
+        // Add font color if specified
+        if (place.fontColor) {
+          placeObj.font_color = place.fontColor
+        }
+
+        places.push(placeObj)
+      })
+
+      return {
+        url: doc.url,
+        name: doc.name,
+        fixed_positions: fixedPositions,
+        places
+      }
+    }),
+    recipients: recipients.map((r) => ({
+      key: r.key,
+      type: r.type,
+      name: r.name,
+      email: r.email,
+      language: r.language,
+      // Use manual ceremony creation so we get the signing URL back
+      // and can send the email via our own system (Resend)
+      ceremony_creation: 'manual'
+    }))
+  }
+
+  if (message) requestBody.message = message
+  if (metadata) requestBody.metadata = metadata
+  if (webhookUrl) requestBody.webhook_url = webhookUrl
+  if (routing) requestBody.routing = routing
+
+  try {
+    // Debug: Log the request structure
+    const debugBody = {
+      ...requestBody,
+      documents: (
+        requestBody.documents as Array<{
+          name: string
+          url: string
+          fixed_positions: unknown[]
+          places: unknown[]
+        }>
+      ).map((d) => ({
+        name: d.name,
+        url: d.url,
+        fixed_positions: d.fixed_positions,
+        places: d.places
+      }))
+    }
+    context?.logger?.info(`[SignatureAPI] Request structure: ${JSON.stringify(debugBody, null, 2)}`)
+
+    const response = await withRetry(async () => {
+      const res = await fetch(`${apiUrl}/envelopes`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': apiKey
+        },
+        body: JSON.stringify(requestBody)
+      })
+
+      if (!res.ok) {
+        // Read body once and log it, then create error manually
+        const errorBody = await res.text()
+        context?.logger?.error(`[SignatureAPI] Error response: ${res.status} ${errorBody}`)
+
+        // Parse error message from response
+        let message = `signature-api API error: ${res.status}`
+        try {
+          const json = JSON.parse(errorBody)
+          if (json.message) message = json.message
+          else if (json.error?.message) message = json.error.message
+          else if (json.errors?.[0]?.message) message = json.errors[0].message
+          else if (errorBody.length < 1000) message = `signature-api ${res.status}: ${errorBody}`
+        } catch {
+          if (errorBody && errorBody.length < 1000) message = `signature-api ${res.status}: ${errorBody}`
+        }
+
+        throw new ToolingError('validation_error', message, {
+          integration: 'signature-api',
+          method: 'createEnvelope',
+          statusCode: res.status,
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    const result = await response.json()
+
+    // Log full response for debugging
+    context?.logger?.info(`[SignatureApiAdapter] Full API response: ${JSON.stringify(result, null, 2)}`)
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[SignatureApiAdapter] Envelope created: organizationId=${context.organizationId} executionId=${context.executionId} envelopeId=${result.id}`
+      )
+    }
+
+    // With ceremony_creation: 'manual', we need to create the ceremony separately
+    // to get the signing URL. The ceremony is NOT created automatically.
+    let signingUrl = ''
+    const recipientId = result.recipients?.[0]?.id
+
+    if (recipientId) {
+      context?.logger?.info(`[SignatureApiAdapter] Creating ceremony for recipient: ${recipientId}`)
+
+      try {
+        // Ceremony creation requires authentication configuration
+        // Using 'custom' auth means we handle verification ourselves (via our proposal workflow)
+        // The recipient clicks the URL and goes directly to signing - no code needed
+        // This works even in SignatureAPI test mode since no emails are sent by SignatureAPI
+        const recipientEmail = recipients[0]?.email || 'unknown'
+        const ceremonyBody = {
+          authentication: [
+            {
+              type: 'custom',
+              provider: 'Elevasis',
+              data: {
+                verified_via: 'proposal_workflow',
+                email: recipientEmail,
+                timestamp: new Date().toISOString()
+              }
+            }
+          ]
+        }
+
+        const ceremonyResponse = await fetch(`${apiUrl}/recipients/${recipientId}/ceremonies`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'X-API-Key': apiKey
+          },
+          body: JSON.stringify(ceremonyBody)
+        })
+
+        if (ceremonyResponse.ok) {
+          const ceremony = await ceremonyResponse.json()
+          signingUrl = ceremony.url || ''
+          context?.logger?.info(`[SignatureApiAdapter] Ceremony created, signing URL available: ${!!signingUrl}`)
+        } else {
+          const ceremonyError = await ceremonyResponse.text()
+          context?.logger?.error(
+            `[SignatureApiAdapter] Failed to create ceremony: ${ceremonyResponse.status} ${ceremonyError}`
+          )
+        }
+      } catch (ceremonyError) {
+        context?.logger?.error(`[SignatureApiAdapter] Error creating ceremony: ${ceremonyError}`)
+      }
+    } else {
+      context?.logger?.warn('[SignatureApiAdapter] No recipient ID in response - cannot create ceremony')
+    }
+
+    return {
+      id: result.id,
+      status: result.status,
+      signingUrl
+    }
+  } catch (error) {
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    throw new ToolingError('api_error', `Failed to create envelope: ${(error as Error).message}`, {
+      integration: 'signature-api',
+      method: 'createEnvelope',
+      organizationId: context?.organizationId,
+      originalError: error
+    })
+  }
+}