@elevasis/core 0.1.0

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

@@ -0,0 +1,309 @@
+import { z } from 'zod'
+import type { Tool } from '../../../../types'
+import { createIntegrationTool } from '../../../tool'
+
+/**
+ * Create a tool that generates Stripe payment links
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeCreatePaymentLinkTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   priceId: 'price_xxx',
+ *   metadata: { deal_id: 'deal-123' },
+ *   redirectUrl: 'https://app.elevasis.io/payment-success'
+ * }, context)
+ * ```
+ */
+export function createStripeCreatePaymentLinkTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_create_payment_link',
+    description: `Create a Stripe payment link for collecting payments.
+
+Use this tool to generate a payment URL that can be sent to customers.
+The link directs to Stripe's hosted checkout page.
+
+Examples:
+- Create link for proposal payment: priceId, metadata with deal_id, redirectUrl
+- Create link with invoice: set invoiceCreation=true`,
+    inputSchema: z.object({
+      priceId: z.string().describe('Stripe price ID (price_xxx)'),
+      quantity: z.number().optional().default(1).describe('Quantity of items'),
+      metadata: z.record(z.string(), z.string()).optional().describe('Custom metadata'),
+      afterCompletionType: z
+        .enum(['redirect', 'hosted_confirmation'])
+        .optional()
+        .describe('What happens after payment'),
+      redirectUrl: z.string().url().optional().describe('URL to redirect after payment'),
+      allowPromotionCodes: z.boolean().optional().describe('Allow promo codes'),
+      automaticTax: z.boolean().optional().describe('Enable automatic tax'),
+      billingAddressCollection: z.enum(['auto', 'required']).optional().describe('Billing address mode'),
+      invoiceCreation: z.boolean().optional().describe('Generate invoice')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Payment link ID (plink_xxx)'),
+      url: z.string().describe('Shareable payment URL'),
+      active: z.boolean().describe('Whether the link is active'),
+      livemode: z.boolean().describe('Whether in production mode')
+    }),
+    integration: 'stripe' as const,
+    method: 'createPaymentLink' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that retrieves a Stripe payment link
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeGetPaymentLinkTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   paymentLinkId: 'plink_xxx'
+ * }, context)
+ * ```
+ */
+export function createStripeGetPaymentLinkTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_get_payment_link',
+    description: `Get details of a Stripe payment link.
+
+Use this tool to retrieve information about an existing payment link,
+including its URL, status, and metadata.
+
+Useful for:
+- Checking if a payment link is still active
+- Retrieving the URL for a previously created link
+- Accessing metadata associated with the link`,
+    inputSchema: z.object({
+      paymentLinkId: z.string().describe('Payment link ID (plink_xxx)')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Payment link ID'),
+      url: z.string().describe('Shareable payment URL'),
+      active: z.boolean().describe('Whether the link is active'),
+      livemode: z.boolean().describe('Whether in production mode'),
+      metadata: z.record(z.string(), z.string()).describe('Custom metadata')
+    }),
+    integration: 'stripe' as const,
+    method: 'getPaymentLink' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that updates a Stripe payment link
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeUpdatePaymentLinkTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   paymentLinkId: 'plink_xxx',
+ *   active: false // Deactivate the link
+ * }, context)
+ * ```
+ */
+export function createStripeUpdatePaymentLinkTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_update_payment_link',
+    description: `Update a Stripe payment link.
+
+Use this tool to modify an existing payment link.
+Common operations:
+- Deactivate a link (set active=false)
+- Update metadata
+
+Note: You cannot change the price after creation.`,
+    inputSchema: z.object({
+      paymentLinkId: z.string().describe('Payment link ID (plink_xxx)'),
+      active: z.boolean().optional().describe('Enable or disable the link'),
+      metadata: z.record(z.string(), z.string()).optional().describe('Update metadata')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Payment link ID'),
+      active: z.boolean().describe('Whether the link is active'),
+      url: z.string().describe('Shareable payment URL')
+    }),
+    integration: 'stripe' as const,
+    method: 'updatePaymentLink' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that lists Stripe payment links
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeListPaymentLinksTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   active: true,
+ *   limit: 10
+ * }, context)
+ * ```
+ */
+export function createStripeListPaymentLinksTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_list_payment_links',
+    description: `List Stripe payment links.
+
+Use this tool to retrieve a list of payment links.
+Supports filtering by active status and pagination.
+
+Useful for:
+- Finding active payment links
+- Auditing created links
+- Paginating through large numbers of links`,
+    inputSchema: z.object({
+      active: z.boolean().optional().describe('Filter by active status'),
+      limit: z.number().min(1).max(100).optional().describe('Number of links to return (1-100)'),
+      startingAfter: z.string().optional().describe('Cursor for pagination (payment link ID)'),
+      endingBefore: z.string().optional().describe('Cursor for pagination (payment link ID)')
+    }),
+    outputSchema: z.object({
+      data: z
+        .array(
+          z.object({
+            id: z.string().describe('Payment link ID'),
+            url: z.string().describe('Shareable payment URL'),
+            active: z.boolean().describe('Whether the link is active'),
+            metadata: z.record(z.string(), z.string()).describe('Custom metadata')
+          })
+        )
+        .describe('List of payment links'),
+      hasMore: z.boolean().describe('Whether more results are available')
+    }),
+    integration: 'stripe' as const,
+    method: 'listPaymentLinks' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that generates Stripe checkout sessions for custom amounts
+ *
+ * Use this for variable/custom pricing where the amount comes from the proposal.
+ * Unlike payment links (which require pre-defined price IDs), checkout sessions
+ * support price_data with any unit_amount.
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeCheckoutSessionTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   amount: 2400000, // $24,000 in cents
+ *   metadata: { deal_id: 'deal-123' },
+ *   successUrl: 'https://app.elevasis.io/payment-success',
+ *   cancelUrl: 'https://app.elevasis.io/payment-cancelled'
+ * }, context)
+ * ```
+ */
+export function createStripeCheckoutSessionTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_create_checkout_session',
+    description: `Create a Stripe checkout session for custom-amount payments.
+
+Use this tool for variable pricing where the amount comes from the proposal.
+Creates a one-time payment URL that expires in 24 hours.
+
+Key differences from payment links:
+- Supports any amount (no pre-defined price IDs needed)
+- URL expires in 24 hours (must recreate if needed)
+- Created per-transaction (not reusable)
+
+Examples:
+- Collect payment for signed proposal: amount from proposal, metadata with deal_id
+- Customer receives hosted Stripe checkout page`,
+    inputSchema: z.object({
+      amount: z.number().int().positive().describe('Amount in cents (e.g., 2400000 for $24,000)'),
+      currency: z.string().optional().default('usd').describe('Currency code (default: usd)'),
+      productName: z.string().optional().describe('Product name shown in checkout'),
+      productDescription: z.string().optional().describe('Product description'),
+      metadata: z.record(z.string(), z.string()).optional().describe('Metadata (deal_id, etc.)'),
+      successUrl: z.string().url().describe('URL after successful payment'),
+      cancelUrl: z.string().url().describe('URL if customer cancels'),
+      customerEmail: z.string().email().optional().describe('Pre-fill customer email')
+    }),
+    outputSchema: z.object({
+      id: z.string().describe('Session ID (cs_xxx)'),
+      url: z.string().describe('Payment URL (expires in 24h)'),
+      expiresAt: z.number().describe('Expiration timestamp (Unix seconds)')
+    }),
+    integration: 'stripe' as const,
+    method: 'createCheckoutSession' as const,
+    credentialName
+  })
+}
+
+/**
+ * Create a tool that generates Stripe payment links with dynamic pricing
+ *
+ * Unlike standard payment links (which require pre-created Price IDs),
+ * this tool uses inline price_data for dynamic pricing. Supports both
+ * one-time setup fees and recurring monthly subscriptions.
+ *
+ * @param credentialName - Name of the Stripe credential to use
+ * @returns Tool instance
+ *
+ * @example
+ * ```typescript
+ * const tool = createStripeAutoPaymentLinkTool('elevasis-stripe')
+ * const result = await tool.execute({
+ *   dealId: 'deal-123',
+ *   companyName: 'Acme Corp',
+ *   contactEmail: 'john@acme.com',
+ *   initialFee: 3000,  // $3,000 one-time
+ *   monthlyFee: 500    // $500/month recurring
+ * }, context)
+ * ```
+ */
+export function createStripeAutoPaymentLinkTool(credentialName: string): Tool {
+  return createIntegrationTool({
+    name: 'stripe_create_auto_payment_link',
+    description: `Create a Stripe payment link with dynamic pricing (inline price_data).
+
+Use this tool for variable pricing with both one-time and recurring fees.
+URLs NEVER EXPIRE - same link can be used in all reminder emails.
+
+Key features:
+- Supports dynamic amounts (no pre-defined Price IDs needed)
+- Can include both one-time setup fee AND monthly recurring in one link
+- URL never expires (unlike checkout sessions)
+- Metadata propagates to all webhooks (checkout.session.completed, etc.)
+
+Examples:
+- Setup + monthly: initialFee=3000, monthlyFee=500 ($3,000 one-time + $500/month)
+- Monthly only: initialFee=0, monthlyFee=500 ($500/month subscription)
+- One-time only: initialFee=3000, monthlyFee=0 ($3,000 one-time payment)`,
+    inputSchema: z.object({
+      dealId: z.string().describe('Local deal ID for metadata'),
+      companyName: z.string().describe('Company name for product description'),
+      contactEmail: z.string().email().describe('Contact email for metadata'),
+      initialFee: z.number().min(0).describe('One-time setup fee in dollars (e.g., 3000 for $3,000)'),
+      monthlyFee: z.number().min(0).describe('Recurring monthly fee in dollars (e.g., 500 for $500/month)')
+    }),
+    outputSchema: z.object({
+      paymentLinkId: z.string().describe('Payment link ID (plink_xxx)'),
+      url: z.string().describe('Payment URL (NEVER EXPIRES)'),
+      hasInitialFee: z.boolean().describe('Whether link includes one-time fee'),
+      hasRecurring: z.boolean().describe('Whether link includes recurring subscription')
+    }),
+    integration: 'stripe' as const,
+    method: 'createAutoPaymentLink' as const,
+    credentialName
+  })
+}

package/src/execution/engine/tools/integration/server/adapters/tomba/fetch/domain-search/index.ts

@@ -0,0 +1,133 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface TombaCredentials {
+  apiKey: string
+  apiSecret: string
+}
+
+export interface DomainSearchParams {
+  domain: string
+  limit?: number
+  department?: string
+  type?: 'personal' | 'generic'
+}
+
+export interface DomainSearchEmail {
+  email: string
+  firstName: string
+  lastName: string
+  fullName: string
+  position: string
+  department: string
+  verificationDate: string
+  verificationStatus: string
+  sources: Array<{
+    uri: string
+    extractedOn: string
+    lastSeenOn: string
+    stillOnPage: boolean
+  }>
+}
+
+export interface DomainSearchResult {
+  organizationName: string
+  domain: string
+  emails: DomainSearchEmail[]
+}
+
+const TOMBA_API_BASE = 'https://api.tomba.io/v1'
+
+/**
+ * Find all email addresses at a company domain via Tomba
+ *
+ * Searches for all known email addresses at the given domain. Optionally filter
+ * by department. Returns enriched data per email including position and
+ * verification status.
+ *
+ * @param credentials - Tomba API key and secret
+ * @param params - Domain, optional limit, and optional department filter
+ * @param context - Execution context for logging
+ * @returns Organization name, domain, and list of found email records
+ */
+export async function domainSearch(
+  credentials: TombaCredentials,
+  params: DomainSearchParams,
+  context?: ExecutionContext
+): Promise<DomainSearchResult> {
+  const { apiKey, apiSecret } = credentials
+  const { domain, limit, department, type } = params
+
+  if (!domain) {
+    throw new Error('domain is required for domainSearch')
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] domainSearch: domain=${domain} limit=${limit} department=${department} type=${type} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const url = new URL(`${TOMBA_API_BASE}/domain-search`)
+  url.searchParams.set('domain', domain)
+  if (limit !== undefined) {
+    url.searchParams.set('limit', String(limit))
+  }
+  if (department) {
+    url.searchParams.set('department', department)
+  }
+  if (type) {
+    url.searchParams.set('type', type)
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'X-Tomba-Key': apiKey,
+        'X-Tomba-Secret': apiSecret
+      },
+      signal: AbortSignal.timeout(60_000)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'tomba',
+        method: 'domainSearch',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response.data ?? {}
+  const rawEmails: Array<Record<string, unknown>> = data.emails ?? []
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] domainSearch complete: domain=${domain} emailCount=${rawEmails.length} organizationId=${context.organizationId}`
+    )
+  }
+
+  return {
+    organizationName: data.organization_name ?? '',
+    domain: data.domain ?? domain,
+    emails: rawEmails.map((e) => ({
+      email: (e.email as string) ?? '',
+      firstName: (e.first_name as string) ?? '',
+      lastName: (e.last_name as string) ?? '',
+      fullName: (e.full_name as string) ?? '',
+      position: (e.position as string) ?? '',
+      department: (e.department as string) ?? '',
+      verificationDate: ((e.verification as Record<string, unknown>)?.date as string) ?? '',
+      verificationStatus: ((e.verification as Record<string, unknown>)?.status as string) ?? '',
+      sources: ((e.sources as Array<Record<string, unknown>>) ?? []).map((s) => ({
+        uri: (s.uri as string) ?? '',
+        extractedOn: (s.extracted_on as string) ?? '',
+        lastSeenOn: (s.last_seen_on as string) ?? '',
+        stillOnPage: (s.still_on_page as boolean) ?? false
+      }))
+    }))
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/tomba/fetch/email-finder/index.ts

@@ -0,0 +1,122 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface TombaCredentials {
+  apiKey: string
+  apiSecret: string
+}
+
+export interface EmailFinderParams {
+  domain: string
+  firstName: string
+  lastName: string
+}
+
+export interface EmailFinderResult {
+  email: string
+  firstName: string
+  lastName: string
+  fullName: string
+  position: string
+  company: string
+  country: string
+  score: number
+  verificationDate: string
+  verificationStatus: string
+  sources: Array<{
+    uri: string
+    extractedOn: string
+    lastSeenOn: string
+    stillOnPage: boolean
+  }>
+}
+
+const TOMBA_API_BASE = 'https://api.tomba.io/v1'
+
+/**
+ * Find a person's email address via Tomba
+ *
+ * Searches for a specific person's email by combining their first/last name
+ * with a company domain. Returns enriched data including position, score, and
+ * verification status.
+ *
+ * @param credentials - Tomba API key and secret
+ * @param params - Domain, first name, and last name
+ * @param context - Execution context for logging
+ * @returns Email address with enrichment data and verification status
+ */
+export async function emailFinder(
+  credentials: TombaCredentials,
+  params: EmailFinderParams,
+  context?: ExecutionContext
+): Promise<EmailFinderResult> {
+  const { apiKey, apiSecret } = credentials
+  const { domain, firstName, lastName } = params
+
+  if (!domain) {
+    throw new Error('domain is required for emailFinder')
+  }
+
+  if (!firstName || !lastName) {
+    throw new Error('firstName and lastName are required for emailFinder')
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] emailFinder: domain=${domain} firstName=${firstName} lastName=${lastName} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const url = new URL(`${TOMBA_API_BASE}/email-finder`)
+  url.searchParams.set('domain', domain)
+  url.searchParams.set('first_name', firstName)
+  url.searchParams.set('last_name', lastName)
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'X-Tomba-Key': apiKey,
+        'X-Tomba-Secret': apiSecret
+      },
+      signal: AbortSignal.timeout(60_000)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'tomba',
+        method: 'emailFinder',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response.data ?? {}
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] emailFinder complete: email=${data.email ? '[found]' : '[not found]'} score=${data.score ?? 0} organizationId=${context.organizationId}`
+    )
+  }
+
+  return {
+    email: data.email ?? '',
+    firstName: data.first_name ?? '',
+    lastName: data.last_name ?? '',
+    fullName: data.full_name ?? '',
+    position: data.position ?? '',
+    company: data.company ?? '',
+    country: data.country ?? '',
+    score: data.score ?? 0,
+    verificationDate: data.verification?.date ?? '',
+    verificationStatus: data.verification?.status ?? '',
+    sources: (data.sources ?? []).map((s: Record<string, unknown>) => ({
+      uri: s.uri ?? '',
+      extractedOn: s.extracted_on ?? '',
+      lastSeenOn: s.last_seen_on ?? '',
+      stillOnPage: s.still_on_page ?? false
+    }))
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/tomba/fetch/email-verifier/index.ts

@@ -0,0 +1,111 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface TombaCredentials {
+  apiKey: string
+  apiSecret: string
+}
+
+export interface EmailVerifierParams {
+  email: string
+}
+
+export interface EmailVerifierResult {
+  email: string
+  result: string
+  status: string
+  score: number
+  mxRecords: boolean
+  smtpServer: boolean
+  smtpCheck: boolean
+  acceptAll: boolean
+  block: boolean
+  gibberish: boolean
+  disposable: boolean
+  webmail: boolean
+  regex: boolean
+}
+
+const TOMBA_API_BASE = 'https://api.tomba.io/v1'
+
+/**
+ * Verify an email address deliverability via Tomba
+ *
+ * Checks whether the given email address is valid and deliverable. Performs
+ * MX record lookup, SMTP server check, and other validation signals.
+ *
+ * @param credentials - Tomba API key and secret
+ * @param params - Email address to verify
+ * @param context - Execution context for logging
+ * @returns Detailed verification result including deliverability signals
+ */
+export async function emailVerifier(
+  credentials: TombaCredentials,
+  params: EmailVerifierParams,
+  context?: ExecutionContext
+): Promise<EmailVerifierResult> {
+  const { apiKey, apiSecret } = credentials
+  const { email } = params
+
+  if (!email) {
+    throw new ToolingError('validation_error', 'Missing required parameter: email', {
+      integration: 'tomba',
+      method: 'emailVerifier'
+    })
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] emailVerifier: email=${email} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const url = new URL(`${TOMBA_API_BASE}/email-verifier`)
+  url.searchParams.set('email', email)
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'X-Tomba-Key': apiKey,
+        'X-Tomba-Secret': apiSecret
+      },
+      signal: AbortSignal.timeout(60_000)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'tomba',
+        method: 'emailVerifier',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = (response.data?.email as Record<string, unknown>) ?? {}
+
+  if (context?.logger) {
+    context.logger.info(
+      `[TombaAdapter] emailVerifier complete: email=${email} result=${data.result ?? ''} status=${data.status ?? ''} organizationId=${context.organizationId}`
+    )
+  }
+
+  return {
+    email: (data.email as string) ?? email,
+    result: (data.result as string) ?? '',
+    status: (data.status as string) ?? '',
+    score: (data.score as number) ?? 0,
+    mxRecords: (data.mx_records as boolean) ?? false,
+    smtpServer: (data.smtp_server as boolean) ?? false,
+    smtpCheck: (data.smtp_check as boolean) ?? false,
+    acceptAll: (data.accept_all as boolean) ?? false,
+    block: (data.block as boolean) ?? false,
+    gibberish: (data.gibberish as boolean) ?? false,
+    disposable: (data.disposable as boolean) ?? false,
+    webmail: (data.webmail as boolean) ?? false,
+    regex: (data.regex as boolean) ?? false
+  }
+}

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

@@ -0,0 +1,11 @@
+// ============================================================================
+// TOMBA ADAPTER
+// ============================================================================
+
+export { TombaAdapter } from './tomba-adapter'
+
+// ============================================================================
+// TOMBA TOOLS
+// ============================================================================
+
+export { createTombaEmailFinderTool, createTombaDomainSearchTool, createTombaEmailVerifierTool } from './tomba-tools'