@elevasis/core 0.1.0

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

@@ -0,0 +1,38 @@
+/**
+ * SignatureAPI Integration - Barrel Export
+ *
+ * Exports SignatureAPI adapter, tool factory functions, and types.
+ */
+
+// ============================================================================
+// SIGNATURE API ADAPTER
+// ============================================================================
+
+export { SignatureApiAdapter } from './signature-api-adapter'
+
+// ============================================================================
+// SIGNATURE API TOOLS
+// ============================================================================
+
+export {
+  createSignatureApiCreateEnvelopeTool,
+  createSignatureApiVoidEnvelopeTool,
+  createSignatureApiDownloadDocumentTool
+} from './signature-api-tools'
+
+// ============================================================================
+// SIGNATURE API TYPES
+// ============================================================================
+
+export type {
+  SignatureApiCredentials,
+  CreateEnvelopeParams,
+  CreateEnvelopeResult,
+  VoidEnvelopeParams,
+  VoidEnvelopeResult,
+  DownloadDocumentParams,
+  DownloadDocumentResult,
+  EnvelopeDocument,
+  Recipient,
+  SigningPlace
+} from './fetch/utils/types'

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

@@ -0,0 +1,87 @@
+import type { BaseIntegrationAdapter } from '../../../base-integration-adapter'
+import { ToolingError } from '../../../../types'
+import type { ExecutionContext } from '../../../../../base/types'
+import { createEnvelope } from './fetch/create-envelope'
+import { voidEnvelope } from './fetch/void-envelope'
+import { downloadDocument } from './fetch/download-document'
+import { getEnvelope } from './fetch/get-envelope'
+import type {
+  SignatureApiCredentials,
+  CreateEnvelopeParams,
+  VoidEnvelopeParams,
+  DownloadDocumentParams,
+  GetEnvelopeParams
+} from './fetch/utils/types'
+
+/**
+ * SignatureAPI integration adapter
+ *
+ * Provides access to SignatureAPI for electronic signatures.
+ * Uses raw fetch (no official SDK) with platform retry/error patterns.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new SignatureApiAdapter()
+ * const result = await adapter.call(
+ *   'createEnvelope',
+ *   { title: 'Contract', documents: [...], recipients: [...] },
+ *   { apiKey: 'key_test_xxx' },
+ *   context
+ * )
+ * ```
+ */
+export class SignatureApiAdapter implements BaseIntegrationAdapter {
+  readonly name = 'signature-api'
+
+  /**
+   * Call SignatureAPI 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 SignatureAPI credentials', {
+        integration: this.name,
+        organizationId: context?.organizationId
+      })
+    }
+
+    // Safe to cast after validation confirms apiKey exists and is valid
+    const creds = credentials as unknown as SignatureApiCredentials
+
+    // Route to method handler - delegate to fetch functions
+    switch (method) {
+      case 'createEnvelope':
+        return createEnvelope(creds, params as CreateEnvelopeParams, context)
+      case 'voidEnvelope':
+        return voidEnvelope(creds, params as VoidEnvelopeParams, context)
+      case 'downloadDocument':
+        return downloadDocument(creds, params as DownloadDocumentParams, context)
+      case 'getEnvelope':
+        return getEnvelope(creds, params as GetEnvelopeParams, context)
+      default:
+        throw new ToolingError('method_not_found', `Unknown SignatureAPI method: ${method}`, {
+          integration: this.name,
+          method,
+          organizationId: context?.organizationId
+        })
+    }
+  }
+
+  /**
+   * Validate SignatureAPI credentials
+   */
+  validateCredentials(credentials: Record<string, unknown>): boolean {
+    const creds = credentials as unknown as SignatureApiCredentials
+    // API key should start with 'key_'
+    return (
+      !!creds.apiKey &&
+      typeof creds.apiKey === 'string' &&
+      creds.apiKey.startsWith('key_')
+    )
+  }
+}

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

@@ -0,0 +1,179 @@
+import { z } from 'zod'
+import type { Tool } from '../../../../types'
+import { createIntegrationTool } from '../../../tool'
+
+/**
+ * Create a tool that creates SignatureAPI envelopes for electronic signatures
+ *
+ * @param credentialName - Name of the SignatureAPI credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createSignatureApiCreateEnvelopeTool('signatureapi-prod')
+ * const result = await tool.execute({
+ *   input: {
+ *     title: 'Elevasis Proposal - Acme Corp',
+ *     documents: [{ name: 'proposal.pdf', url: 'https://...', places: [...] }],
+ *     recipients: [{ key: 'signer1', type: 'signer', name: 'John', email: 'john@acme.com' }]
+ *   },
+ *   executionContext: context
+ * })
+ * // result: { id: 'env_xxx', status: 'processing', signingUrl: 'https://...' }
+ * ```
+ */
+export function createSignatureApiCreateEnvelopeTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'signatureapi_create_envelope',
+    description: `Create a SignatureAPI envelope for electronic signatures.
+
+Use this tool to send documents for signing. An envelope is a container
+that holds documents and manages the signing process.
+
+Examples:
+- Create proposal envelope: title, documents with PDF URLs, recipients with signers
+- Include signature fields: specify page, x, y positions for signature placement
+- Use 'date' for auto-populated signing date (maps to recipient_completed_date)
+
+The envelope will be sent to recipients via email with a signing link.`,
+    inputSchema: z.object({
+      title: z.string().describe('Envelope title (shown in emails)'),
+      message: z.string().optional().describe('Custom message for recipient emails'),
+      documents: z
+        .array(
+          z.object({
+            name: z.string().describe('Document filename'),
+            url: z.string().url().describe('Publicly accessible URL to PDF document'),
+            places: z
+              .array(
+                z.object({
+                  recipientKey: z.string().describe('Links to recipient key'),
+                  type: z.enum(['signature', 'date', 'text', 'initials']).describe('Field type (date maps to recipient_completed_date)'),
+                  page: z.number().describe('Page number (1-indexed, -1 for last)'),
+                  x: z.number().describe('X position in points'),
+                  y: z.number().describe('Y position in points'),
+                  width: z.number().optional(),
+                  height: z.number().optional()
+                })
+              )
+              .optional()
+              .describe('Signature field placements')
+          })
+        )
+        .describe('Documents to sign'),
+      recipients: z
+        .array(
+          z.object({
+            key: z.string().describe('Unique identifier for this recipient'),
+            type: z.enum(['signer', 'viewer', 'approver']),
+            name: z.string().describe('Recipient full name'),
+            email: z.string().email().describe('Recipient email'),
+            language: z.string().optional().describe('Language code (en, es, fr)')
+          })
+        )
+        .describe('Recipients/signers'),
+      metadata: z.record(z.string(), z.string()).optional().describe('Custom metadata (e.g., deal_id)'),
+      webhookUrl: z.string().url().optional().describe('Override default webhook URL'),
+      routing: z.enum(['parallel', 'sequential']).optional().describe('How to route to multiple recipients')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Envelope ID (env_xxx)'),
+      status: z.string().describe('Envelope status'),
+      signingUrl: z.string().optional().describe('URL for first signer')
+    }),
+    integration: 'signature-api' as const,
+    method: 'createEnvelope' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that voids/cancels SignatureAPI envelopes
+ *
+ * @param credentialName - Name of the SignatureAPI credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createSignatureApiVoidEnvelopeTool('signatureapi-prod')
+ * const result = await tool.execute({
+ *   input: {
+ *     envelopeId: 'env_xxx',
+ *     reason: 'Revision requested by recipient'
+ *   },
+ *   executionContext: context
+ * })
+ * // result: { id: 'env_xxx', status: 'voided' }
+ * ```
+ */
+export function createSignatureApiVoidEnvelopeTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'signatureapi_void_envelope',
+    description: `Void/cancel a pending SignatureAPI envelope.
+
+Use this tool to cancel an envelope that hasn't been completed yet.
+Voided envelopes cannot be signed.
+
+Common reasons:
+- Revision requested by recipient
+- Error in document content
+- Deal cancelled`,
+    inputSchema: z.object({
+      envelopeId: z.string().describe('Envelope ID to void (env_xxx)'),
+      reason: z.string().optional().describe('Reason for voiding')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Envelope ID'),
+      status: z.literal('voided').describe('Status after voiding')
+    }),
+    integration: 'signature-api' as const,
+    method: 'voidEnvelope' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that downloads signed documents from SignatureAPI
+ *
+ * @param credentialName - Name of the SignatureAPI credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createSignatureApiDownloadDocumentTool('signatureapi-prod')
+ * const result = await tool.execute({
+ *   input: {
+ *     envelopeId: 'env_xxx',
+ *     documentType: 'combined'
+ *   },
+ *   executionContext: context
+ * })
+ * // result: { content: Buffer, contentType: 'application/pdf', filename: 'env_xxx-signed.pdf' }
+ * ```
+ */
+export function createSignatureApiDownloadDocumentTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'signatureapi_download_document',
+    description: `Download signed document from a completed envelope.
+
+Use this tool to retrieve the signed PDF after all recipients have signed.
+The combined document includes all documents and an audit trail.
+
+Document types:
+- combined: All documents merged with audit trail (default)
+- original: Original unsigned documents
+- audit: Audit trail only`,
+    inputSchema: z.object({
+      envelopeId: z.string().describe('Envelope ID (env_xxx)'),
+      documentType: z.enum(['combined', 'original', 'audit']).optional().describe('Type of document to download')
+    }),
+    outputSchema: z.object({
+      content: z.instanceof(Buffer).describe('PDF content as Buffer'),
+      contentType: z.string().describe('MIME type'),
+      filename: z.string().describe('Suggested filename')
+    }),
+    integration: 'signature-api' as const,
+    method: 'downloadDocument' as const,
+    credentialName
+  })
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Stripe API Types
+ *
+ * Type definitions for Stripe Payment Links operations.
+ */
+
+/**
+ * Stripe credentials format
+ * Stored in credentials table, encrypted
+ */
+export interface StripeCredentials {
+  apiKey: string // sk_live_xxx or sk_test_xxx
+}
+
+/**
+ * Create payment link parameters
+ */
+export interface CreatePaymentLinkParams {
+  priceId: string // Stripe price ID (price_xxx)
+  quantity?: number // Default: 1
+  metadata?: Record<string, string> // Custom metadata
+  afterCompletionType?: 'redirect' | 'hosted_confirmation' // What to show after payment
+  redirectUrl?: string // Required if afterCompletionType is 'redirect'
+  allowPromotionCodes?: boolean // Allow promo codes at checkout
+  automaticTax?: boolean // Enable automatic tax calculation
+  billingAddressCollection?: 'auto' | 'required' // Billing address requirement
+  invoiceCreation?: boolean // Generate invoice for payment
+}
+
+/**
+ * Create payment link result
+ */
+export interface CreatePaymentLinkResult {
+  id: string // plink_xxx
+  url: string // https://checkout.stripe.com/...
+  active: boolean
+  livemode: boolean
+}
+
+/**
+ * Get payment link parameters
+ */
+export interface GetPaymentLinkParams {
+  paymentLinkId: string // Payment link ID to retrieve
+}
+
+/**
+ * Get payment link result
+ */
+export interface GetPaymentLinkResult {
+  id: string
+  url: string
+  active: boolean
+  livemode: boolean
+  metadata: Record<string, string>
+}
+
+/**
+ * Update payment link parameters
+ */
+export interface UpdatePaymentLinkParams {
+  paymentLinkId: string // Payment link ID to update
+  active?: boolean // Enable or disable the link
+  metadata?: Record<string, string> // Update metadata
+}
+
+/**
+ * Update payment link result
+ */
+export interface UpdatePaymentLinkResult {
+  id: string
+  active: boolean
+  url: string
+}
+
+/**
+ * List payment links parameters
+ */
+export interface ListPaymentLinksParams {
+  active?: boolean // Filter by active status
+  limit?: number // Default: 10, max: 100
+  startingAfter?: string // Cursor for pagination (payment link ID)
+  endingBefore?: string // Cursor for pagination (payment link ID)
+}
+
+/**
+ * List payment links result
+ */
+export interface ListPaymentLinksResult {
+  data: Array<{
+    id: string
+    url: string
+    active: boolean
+    metadata: Record<string, string>
+  }>
+  hasMore: boolean
+}
+
+/**
+ * Stripe API response for create payment link
+ */
+export interface StripeCreatePaymentLinkResponse {
+  id: string
+  url: string
+  active: boolean
+  livemode: boolean
+}
+
+/**
+ * Stripe API response for get payment link
+ */
+export interface StripeGetPaymentLinkResponse {
+  id: string
+  url: string
+  active: boolean
+  livemode: boolean
+  metadata: Record<string, string>
+}
+
+/**
+ * Stripe API response for list payment links
+ */
+export interface StripeListPaymentLinksResponse {
+  object: 'list'
+  data: Array<{
+    id: string
+    url: string
+    active: boolean
+    metadata: Record<string, string>
+  }>
+  has_more: boolean
+}
+
+// =============================================================================
+// Auto Payment Links (Dynamic Pricing)
+// =============================================================================
+
+/**
+ * Create auto payment link parameters
+ *
+ * For dynamic pricing with inline price_data (one-time + recurring).
+ * Unlike standard payment links, these don't require pre-created Price objects.
+ */
+export interface CreateAutoPaymentLinkParams {
+  /** Local deal ID for metadata */
+  dealId: string
+  /** Company name for product description */
+  companyName: string
+  /** Contact email for metadata */
+  contactEmail: string
+  /** One-time setup fee in dollars (e.g., 3000 for $3,000) */
+  initialFee: number
+  /** Recurring monthly fee in dollars (e.g., 500 for $500/month) */
+  monthlyFee: number
+}
+
+/**
+ * Create auto payment link result
+ */
+export interface CreateAutoPaymentLinkResult {
+  /** Payment link ID (plink_xxx) */
+  paymentLinkId: string
+  /** Payment URL (NEVER EXPIRES) */
+  url: string
+  /** Whether link includes one-time fee */
+  hasInitialFee: boolean
+  /** Whether link includes recurring subscription */
+  hasRecurring: boolean
+}
+
+// =============================================================================
+// Checkout Sessions
+// =============================================================================
+
+/**
+ * Create checkout session parameters
+ *
+ * For variable/custom pricing where the amount comes from the proposal.
+ * Uses price_data instead of a pre-defined price ID.
+ */
+export interface CreateCheckoutSessionParams {
+  /** Amount in cents (e.g., 2400000 for $24,000) */
+  amount: number
+  /** Currency code (default: 'usd') */
+  currency?: string
+  /** Product name shown in checkout (default: 'AI Automation Services') */
+  productName?: string
+  /** Product description shown in checkout */
+  productDescription?: string
+  /** Metadata for webhook lookup (deal_id, etc.) */
+  metadata?: Record<string, string>
+  /** URL after successful payment */
+  successUrl: string
+  /** URL if customer cancels */
+  cancelUrl: string
+  /** Pre-fill customer email in checkout */
+  customerEmail?: string
+}
+
+/**
+ * Create checkout session result
+ */
+export interface CreateCheckoutSessionResult {
+  /** Session ID (cs_xxx) */
+  id: string
+  /** Payment URL (expires in 24 hours) */
+  url: string
+  /** Expiration timestamp (Unix seconds) */
+  expiresAt: number
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Stripe Integration - Barrel Export
+ *
+ * Exports Stripe adapter and tool factory functions.
+ */
+
+// ============================================================================
+// STRIPE ADAPTER
+// ============================================================================
+
+export { StripeAdapter } from './stripe-adapter'
+
+// ============================================================================
+// STRIPE TOOLS
+// ============================================================================
+
+export {
+  createStripeCreatePaymentLinkTool,
+  createStripeGetPaymentLinkTool,
+  createStripeUpdatePaymentLinkTool,
+  createStripeListPaymentLinksTool,
+  createStripeCheckoutSessionTool,
+  createStripeAutoPaymentLinkTool
+} from './stripe-tools'
+
+// ============================================================================
+// STRIPE TYPES
+// ============================================================================
+
+export type {
+  StripeCredentials,
+  CreatePaymentLinkParams,
+  CreatePaymentLinkResult,
+  GetPaymentLinkParams,
+  GetPaymentLinkResult,
+  UpdatePaymentLinkParams,
+  UpdatePaymentLinkResult,
+  ListPaymentLinksParams,
+  ListPaymentLinksResult,
+  CreateCheckoutSessionParams,
+  CreateCheckoutSessionResult,
+  CreateAutoPaymentLinkParams,
+  CreateAutoPaymentLinkResult
+} from './fetch/utils/types'