@elevasis/core 0.1.0

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

@@ -0,0 +1,230 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import type {
+  SignatureApiCredentials,
+  DownloadDocumentParams,
+  DownloadDocumentResult,
+  Deliverable,
+  ListDeliverablesResponse
+} from '../utils/types'
+
+const DEFAULT_API_URL = 'https://api.signatureapi.com/v1'
+
+/**
+ * Retry configuration for waiting on deliverable generation
+ */
+const DELIVERABLE_RETRY_CONFIG = {
+  maxAttempts: 8,
+  initialDelayMs: 500,
+  maxDelayMs: 8000,
+  backoffMultiplier: 2
+}
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Download signed document from a completed envelope using the deliverable system
+ *
+ * SignatureAPI uses a deliverable system for signed documents:
+ * 1. List deliverables for the envelope
+ * 2. If none exist or none are generated, create one
+ * 3. Poll until status is 'generated'
+ * 4. Download via the pre-signed URL
+ *
+ * @param credentials - SignatureAPI credentials (apiKey, optional apiUrl)
+ * @param params - Download parameters (envelopeId, documentType)
+ * @param context - Execution context for logging
+ * @returns Buffer containing PDF content, content type, and filename
+ * @throws ToolingError if download fails
+ */
+export async function downloadDocument(
+  credentials: SignatureApiCredentials,
+  params: DownloadDocumentParams,
+  context?: ExecutionContext
+): Promise<DownloadDocumentResult> {
+  const { apiKey, apiUrl = DEFAULT_API_URL } = credentials
+  const { envelopeId } = params
+  // Map documentType to deliverable type: 'combined'/'audit' -> 'standard', 'original' -> 'simple'
+  const deliverableType = params.documentType === 'original' ? 'simple' : 'standard'
+
+  // Validate credentials
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'SignatureAPI credentials must include apiKey', {
+      integration: 'signature-api',
+      method: 'downloadDocument'
+    })
+  }
+
+  // Validate required parameters
+  if (!envelopeId) {
+    throw new ToolingError('validation_error', 'Envelope ID is required', {
+      integration: 'signature-api',
+      method: 'downloadDocument'
+    })
+  }
+
+  const log = (message: string, data?: Record<string, unknown>) => {
+    if (context?.logger) {
+      const dataStr = data
+        ? ` ${Object.entries(data)
+            .map(([k, v]) => `${k}=${v}`)
+            .join(' ')}`
+        : ''
+      context.logger.info(
+        `[SignatureAPI:downloadDocument] ${message} organizationId=${context.organizationId} executionId=${context.executionId} envelopeId=${envelopeId}${dataStr}`
+      )
+    }
+  }
+
+  try {
+    // Step 1: List existing deliverables
+    log('Listing deliverables')
+    const listRes = await fetch(`${apiUrl}/envelopes/${envelopeId}/deliverables`, {
+      headers: { 'X-API-Key': apiKey }
+    })
+
+    if (!listRes.ok) {
+      const errorText = await listRes.text()
+      throw new ToolingError('api_error', `Failed to list deliverables: ${listRes.status} ${errorText}`, {
+        integration: 'signature-api',
+        method: 'downloadDocument',
+        envelopeId
+      })
+    }
+
+    const listData: ListDeliverablesResponse = await listRes.json()
+    log('Found deliverables', { count: listData.data.length })
+
+    // Step 2: Find existing generated deliverable or create one
+    let deliverable: Deliverable | undefined = listData.data.find(
+      (d) => d.type === deliverableType && d.status === 'generated'
+    )
+
+    if (!deliverable) {
+      // Check for pending/processing deliverable of matching type
+      deliverable = listData.data.find(
+        (d) => d.type === deliverableType && (d.status === 'pending' || d.status === 'processing')
+      )
+
+      if (!deliverable) {
+        // Create new deliverable
+        log('Creating new deliverable', { type: deliverableType })
+        const createRes = await fetch(`${apiUrl}/envelopes/${envelopeId}/deliverables`, {
+          method: 'POST',
+          headers: {
+            'X-API-Key': apiKey,
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({ type: deliverableType })
+        })
+
+        if (!createRes.ok) {
+          const errorText = await createRes.text()
+          throw new ToolingError('api_error', `Failed to create deliverable: ${createRes.status} ${errorText}`, {
+            integration: 'signature-api',
+            method: 'downloadDocument',
+            envelopeId
+          })
+        }
+
+        deliverable = await createRes.json()
+        log('Created deliverable', { id: deliverable!.id, status: deliverable!.status })
+      }
+    }
+
+    // Step 3: Poll until generated (exponential backoff)
+    let attempts = 0
+    let delay = DELIVERABLE_RETRY_CONFIG.initialDelayMs
+
+    while (deliverable!.status !== 'generated' && attempts < DELIVERABLE_RETRY_CONFIG.maxAttempts) {
+      if (deliverable!.status === 'failed') {
+        throw new ToolingError('api_error', 'Deliverable generation failed', {
+          integration: 'signature-api',
+          method: 'downloadDocument',
+          envelopeId,
+          deliverableId: deliverable!.id
+        })
+      }
+
+      log('Deliverable not ready, waiting', { status: deliverable!.status, attempt: attempts + 1, delayMs: delay })
+      await sleep(delay)
+
+      // Fetch updated status
+      const getRes = await fetch(`${apiUrl}/deliverables/${deliverable!.id}`, {
+        headers: { 'X-API-Key': apiKey }
+      })
+
+      if (!getRes.ok) {
+        const errorText = await getRes.text()
+        throw new ToolingError('api_error', `Failed to get deliverable: ${getRes.status} ${errorText}`, {
+          integration: 'signature-api',
+          method: 'downloadDocument',
+          deliverableId: deliverable!.id
+        })
+      }
+
+      deliverable = await getRes.json()
+      log('Deliverable status', { id: deliverable!.id, status: deliverable!.status })
+
+      attempts++
+      delay = Math.min(delay * DELIVERABLE_RETRY_CONFIG.backoffMultiplier, DELIVERABLE_RETRY_CONFIG.maxDelayMs)
+    }
+
+    if (deliverable!.status !== 'generated') {
+      throw new ToolingError(
+        'timeout_error',
+        `Deliverable not ready after ${DELIVERABLE_RETRY_CONFIG.maxAttempts} attempts (status: ${deliverable!.status})`,
+        { integration: 'signature-api', method: 'downloadDocument', envelopeId, deliverableId: deliverable!.id }
+      )
+    }
+
+    // Step 4: Download PDF from pre-signed URL
+    if (!deliverable!.url) {
+      throw new ToolingError('api_error', 'Deliverable generated but URL is null', {
+        integration: 'signature-api',
+        method: 'downloadDocument',
+        deliverableId: deliverable!.id
+      })
+    }
+
+    log('Downloading PDF from pre-signed URL', { deliverableId: deliverable!.id })
+    const downloadRes = await fetch(deliverable!.url)
+
+    if (!downloadRes.ok) {
+      throw new ToolingError('api_error', `Failed to download PDF: ${downloadRes.status}`, {
+        integration: 'signature-api',
+        method: 'downloadDocument',
+        deliverableId: deliverable!.id
+      })
+    }
+
+    const buffer = Buffer.from(await downloadRes.arrayBuffer())
+    const filename = `${envelopeId}-signed.pdf`
+
+    log('Download complete', { size: buffer.length, filename })
+
+    return {
+      content: buffer,
+      contentType: 'application/pdf',
+      filename
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to download document: ${(error as Error).message}`, {
+      integration: 'signature-api',
+      method: 'downloadDocument',
+      organizationId: context?.organizationId,
+      originalError: error
+    })
+  }
+}

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

@@ -0,0 +1,133 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { SignatureApiCredentials, GetEnvelopeParams, GetEnvelopeResult } from '../utils/types'
+
+const DEFAULT_API_URL = 'https://api.signatureapi.com/v1'
+
+/**
+ * SignatureAPI raw response format (snake_case)
+ */
+interface SignatureApiGetEnvelopeResponse {
+  id: string
+  title: string
+  status: 'processing' | 'pending' | 'completed' | 'declined' | 'voided'
+  created_at: string
+  completed_at?: string
+  metadata: Record<string, string>
+  recipients: Array<{
+    key: string
+    name: string
+    email: string
+    status: 'pending' | 'signed' | 'declined'
+    signed_at?: string
+  }>
+}
+
+/**
+ * Get envelope details from SignatureAPI
+ *
+ * @param credentials - SignatureAPI credentials (apiKey, optional apiUrl)
+ * @param params - Envelope ID to retrieve
+ * @param context - Execution context for logging
+ * @returns Envelope details including status and recipients
+ * @throws ToolingError if retrieval fails
+ *
+ * @example
+ * const result = await getEnvelope(
+ *   { apiKey: 'key_test_xxx' },
+ *   { envelopeId: 'env_xxx' },
+ *   context
+ * )
+ * // result.status: 'processing', 'pending', 'completed', 'declined', 'voided'
+ */
+export async function getEnvelope(
+  credentials: SignatureApiCredentials,
+  params: GetEnvelopeParams,
+  context?: ExecutionContext
+): Promise<GetEnvelopeResult> {
+  const { apiKey, apiUrl = DEFAULT_API_URL } = credentials
+  const { envelopeId } = params
+
+  // Validate required parameters
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'SignatureAPI credentials must include apiKey', {
+      integration: 'signature-api',
+      method: 'getEnvelope'
+    })
+  }
+
+  if (!envelopeId) {
+    throw new ToolingError('validation_error', 'Envelope ID is required', {
+      integration: 'signature-api',
+      method: 'getEnvelope'
+    })
+  }
+
+  // Build URL
+  const url = `${apiUrl}/envelopes/${encodeURIComponent(envelopeId)}`
+
+  try {
+    // Execute with retry logic
+    const response = await withRetry(async () => {
+      const res = await fetch(url, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': apiKey
+        }
+      })
+
+      // Handle HTTP errors
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'signature-api',
+          method: 'getEnvelope',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    // Parse response
+    const result = (await response.json()) as SignatureApiGetEnvelopeResponse
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[SignatureApiAdapter] Envelope retrieved: organizationId=${context.organizationId} executionId=${context.executionId} envelopeId=${result.id} status=${result.status}`
+      )
+    }
+
+    // Return standardized result (snake_case -> camelCase)
+    return {
+      id: result.id,
+      title: result.title,
+      status: result.status,
+      createdAt: result.created_at,
+      completedAt: result.completed_at,
+      metadata: result.metadata || {},
+      recipients: result.recipients.map((recipient) => ({
+        key: recipient.key,
+        name: recipient.name,
+        email: recipient.email,
+        status: recipient.status,
+        signedAt: recipient.signed_at
+      }))
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to get envelope from SignatureAPI: ${(error as Error).message}`, {
+      integration: 'signature-api',
+      method: 'getEnvelope',
+      organizationId: context?.organizationId,
+      envelopeId,
+      originalError: error
+    })
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/signature-api/fetch/utils/types.ts

@@ -0,0 +1,246 @@
+/**
+ * SignatureAPI Types
+ *
+ * Type definitions for SignatureAPI eSignature operations.
+ * SignatureAPI uses raw fetch (no official SDK).
+ */
+
+/**
+ * SignatureAPI credentials format
+ * Stored in credentials table, encrypted
+ */
+export interface SignatureApiCredentials {
+  apiKey: string // key_live_xxx or key_test_xxx
+  apiUrl?: string // Optional override, defaults to https://api.signatureapi.com/v1
+}
+
+/**
+ * Signature field configuration
+ *
+ * Note: The 'date' type is supported here for convenience but gets mapped
+ * to 'recipient_completed_date' when sent to the SignatureAPI.
+ */
+export interface SignatureField {
+  type: 'signature' | 'date' | 'text' | 'initials' // 'date' maps to 'recipient_completed_date'
+  page: number // 1-indexed, or -1 for last page
+  x: number // X position in points
+  y: number // Y position in points
+  width?: number // Field width
+  height?: number // Field height
+}
+
+/**
+ * Valid SignatureAPI field types
+ *
+ * Note: SignatureAPI does NOT support 'date' - use 'recipient_completed_date' instead.
+ * Our workflow utility maps 'date' -> 'recipient_completed_date' for convenience.
+ */
+export type SignatureApiFieldType =
+  | 'signature'
+  | 'initials'
+  | 'recipient_completed_date'
+  | 'envelope_completed_date'
+  | 'recipient_name'
+  | 'recipient_email'
+  | 'text'
+  | 'text_input'
+  | 'boxed_text_input'
+  | 'multi_line_text_input'
+  | 'checkbox'
+  | 'dropdown'
+
+/**
+ * Signing place configuration
+ */
+export interface SigningPlace {
+  recipientKey: string // Links to recipient
+  type: SignatureApiFieldType
+  page: number
+  x: number
+  y: number
+  width?: number
+  height?: number
+  fontColor?: string // Hex color (e.g., '#FFFFFF' for white)
+}
+
+/**
+ * Document for signing
+ *
+ * Note: SignatureAPI requires documents to be provided via URL (not base64).
+ * Use a publicly accessible URL (e.g., Supabase signed URL).
+ */
+export interface EnvelopeDocument {
+  name: string // Display name (e.g., 'proposal.pdf')
+  url: string // Publicly accessible URL to PDF (NOT base64)
+  places?: SigningPlace[] // Where to place signature fields
+}
+
+/**
+ * Recipient/signer configuration
+ */
+export interface Recipient {
+  key: string // Unique identifier (e.g., 'signer1')
+  type: 'signer' | 'viewer' | 'approver'
+  name: string
+  email: string
+  language?: string // 'en', 'es', 'fr', etc.
+}
+
+/**
+ * Create envelope parameters
+ */
+export interface CreateEnvelopeParams {
+  title: string // Envelope name
+  message?: string // Custom message in emails
+  documents: EnvelopeDocument[] // Documents to sign
+  recipients: Recipient[] // Signers
+  metadata?: Record<string, string> // Custom metadata
+  webhookUrl?: string // Override default webhook
+  routing?: 'parallel' | 'sequential' // Default: parallel
+}
+
+/**
+ * Create envelope result
+ */
+export interface CreateEnvelopeResult {
+  id: string // env_xxx
+  status: string // 'processing', 'pending', etc.
+  signingUrl?: string // URL for first signer
+}
+
+/**
+ * Void envelope parameters
+ */
+export interface VoidEnvelopeParams {
+  envelopeId: string
+  reason?: string
+}
+
+/**
+ * Void envelope result
+ */
+export interface VoidEnvelopeResult {
+  id: string
+  status: 'voided'
+}
+
+/**
+ * Download document parameters
+ */
+export interface DownloadDocumentParams {
+  envelopeId: string
+  documentType?: 'combined' | 'original' | 'audit' // Default: combined
+}
+
+/**
+ * Download document result
+ */
+export interface DownloadDocumentResult {
+  content: Buffer // PDF content
+  contentType: string // 'application/pdf'
+  filename: string // Suggested filename
+}
+
+/**
+ * Get envelope parameters
+ */
+export interface GetEnvelopeParams {
+  envelopeId: string
+}
+
+/**
+ * Get envelope result
+ */
+export interface GetEnvelopeResult {
+  id: string
+  title: string
+  status: 'processing' | 'pending' | 'completed' | 'declined' | 'voided'
+  createdAt: string
+  completedAt?: string
+  metadata: Record<string, string>
+  recipients: Array<{
+    key: string
+    name: string
+    email: string
+    status: 'pending' | 'signed' | 'declined'
+    signedAt?: string
+  }>
+}
+
+/**
+ * SignatureAPI error response
+ */
+export interface SignatureApiErrorResponse {
+  error: {
+    code: string
+    message: string
+    details?: unknown
+  }
+}
+
+// ============================================================================
+// Deliverable Types (for downloading signed documents)
+// ============================================================================
+
+/**
+ * Deliverable type - what's included in the PDF
+ */
+export type DeliverableType = 'standard' | 'simple'
+
+/**
+ * Deliverable status - processing lifecycle
+ */
+export type DeliverableStatus = 'pending' | 'processing' | 'generated' | 'failed'
+
+/**
+ * Deliverable object returned by SignatureAPI
+ */
+export interface Deliverable {
+  id: string // del_xxx
+  envelope_id: string
+  type: DeliverableType
+  status: DeliverableStatus
+  url: string | null // Pre-signed download URL (null until generated)
+  password?: string
+  created_at: string
+  generated_at: string | null
+  language?: string
+  timezone?: string
+  timestamp_format?: string
+}
+
+/**
+ * List deliverables response
+ */
+export interface ListDeliverablesResponse {
+  data: Deliverable[]
+  links: {
+    next?: string
+    previous?: string
+  }
+}
+
+/**
+ * Create deliverable parameters
+ */
+export interface CreateDeliverableParams {
+  envelopeId: string
+  type?: DeliverableType // Default: standard
+}
+
+/**
+ * Create deliverable result
+ */
+export type CreateDeliverableResult = Deliverable
+
+/**
+ * Get deliverable parameters
+ */
+export interface GetDeliverableParams {
+  deliverableId: string
+}
+
+/**
+ * Get deliverable result
+ */
+export type GetDeliverableResult = Deliverable

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

@@ -0,0 +1,90 @@
+import { ToolingError } from '../../../../../../types'
+import type { ExecutionContext } from '../../../../../../../base/types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { SignatureApiCredentials, VoidEnvelopeParams, VoidEnvelopeResult } from '../utils/types'
+
+const DEFAULT_API_URL = 'https://api.signatureapi.com/v1'
+
+/**
+ * Void/cancel a pending envelope
+ *
+ * @param credentials - SignatureAPI credentials (apiKey, optional apiUrl)
+ * @param params - Void parameters (envelopeId, optional reason)
+ * @param context - Execution context for logging
+ * @returns Envelope ID and voided status
+ * @throws ToolingError if voiding fails
+ */
+export async function voidEnvelope(
+  credentials: SignatureApiCredentials,
+  params: VoidEnvelopeParams,
+  context?: ExecutionContext
+): Promise<VoidEnvelopeResult> {
+  const { apiKey, apiUrl = DEFAULT_API_URL } = credentials
+  const { envelopeId, reason } = params
+
+  // Validate credentials
+  if (!apiKey) {
+    throw new ToolingError('credentials_invalid', 'SignatureAPI credentials must include apiKey', {
+      integration: 'signature-api',
+      method: 'voidEnvelope'
+    })
+  }
+
+  // Validate required params
+  if (!envelopeId) {
+    throw new ToolingError('validation_error', 'Envelope ID is required', {
+      integration: 'signature-api',
+      method: 'voidEnvelope'
+    })
+  }
+
+  try {
+    const response = await withRetry(async () => {
+      const res = await fetch(`${apiUrl}/envelopes/${envelopeId}/void`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': apiKey
+        },
+        body: JSON.stringify({ reason: reason || 'Voided by system' })
+      })
+
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'signature-api',
+          method: 'voidEnvelope',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res
+    }, DEFAULT_RETRY_POLICY)
+
+    const result = await response.json()
+
+    // Log success
+    if (context?.logger) {
+      context.logger.info(
+        `[SignatureApiAdapter] Envelope voided: organizationId=${context.organizationId} envelopeId=${envelopeId}`
+      )
+    }
+
+    return {
+      id: result.id,
+      status: 'voided'
+    }
+  } catch (error) {
+    // Re-throw ToolingError as-is
+    if (error instanceof ToolingError) {
+      throw error
+    }
+
+    // Wrap unknown errors
+    throw new ToolingError('api_error', `Failed to void envelope: ${(error as Error).message}`, {
+      integration: 'signature-api',
+      method: 'voidEnvelope',
+      organizationId: context?.organizationId,
+      originalError: error
+    })
+  }
+}