@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/bulk-add-leads/__tests__/index.test.ts

@@ -0,0 +1,325 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { bulkAddLeads, type BulkAddLeadsParams } from '../index.js'
+import { ToolingError } from '../../../../../../../types.js'
+import type { ExecutionContext } from '../../../../../../../../base/types.js'
+
+// Mock fetch globally
+const mockFetch = vi.fn()
+vi.stubGlobal('fetch', mockFetch)
+
+const createMockContext = (): ExecutionContext => ({
+  executionId: 'exec-456',
+  organizationId: 'org-123',
+  organizationName: 'Test Org',
+  userId: 'user-789',
+  resourceId: 'test-resource',
+  executionDepth: 0,
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() },
+  store: new Map()
+})
+
+describe('bulkAddLeads', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  const validCredentials = { apiKey: 'test-api-key' }
+  const validParams: BulkAddLeadsParams = {
+    campaign_id: 'campaign-123',
+    leads: [
+      {
+        email: 'lead1@example.com',
+        first_name: 'Lead',
+        last_name: 'One',
+        company_name: 'Test Company'
+      }
+    ]
+  }
+
+  describe('Validation', () => {
+    it('should throw validation_error when campaign_id is empty', async () => {
+      const params = {
+        campaign_id: '',
+        leads: [{ email: 'test@example.com' }]
+      }
+
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Missing required parameter: campaign_id'
+      })
+    })
+
+    it('should throw validation_error when leads array is empty', async () => {
+      const params = {
+        campaign_id: 'campaign-123',
+        leads: []
+      }
+
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Must provide at least one lead'
+      })
+    })
+
+    it('should throw validation_error when leads count exceeds 1000', async () => {
+      const leads = Array.from({ length: 1001 }, (_, i) => ({
+        email: `lead${i}@example.com`
+      }))
+      const params = { campaign_id: 'campaign-123', leads }
+
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Cannot add more than 1,000 leads per request'
+      })
+    })
+
+    it('should throw validation_error when a lead is missing email', async () => {
+      const params = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: '' }]
+      }
+
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(bulkAddLeads(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Each lead must have an email address'
+      })
+    })
+  })
+
+  describe('Success Cases', () => {
+    it('should successfully add leads and return added_count from leads_uploaded', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ leads_uploaded: 5 })
+      })
+
+      const params: BulkAddLeadsParams = {
+        campaign_id: 'campaign-123',
+        leads: [
+          { email: 'a@example.com' },
+          { email: 'b@example.com' },
+          { email: 'c@example.com' },
+          { email: 'd@example.com' },
+          { email: 'e@example.com' }
+        ]
+      }
+
+      const context = createMockContext()
+      const result = await bulkAddLeads(validCredentials, params, context)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 5,
+        failed_count: 0
+      })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/leads/add',
+        expect.objectContaining({
+          method: 'POST',
+          headers: {
+            Authorization: 'Bearer test-api-key',
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({
+            campaign_id: 'campaign-123',
+            leads: [
+              {
+                email: 'a@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: undefined
+              },
+              {
+                email: 'b@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: undefined
+              },
+              {
+                email: 'c@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: undefined
+              },
+              {
+                email: 'd@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: undefined
+              },
+              {
+                email: 'e@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: undefined
+              }
+            ]
+          })
+        })
+      )
+    })
+
+    it('should handle wrapped response with data.leads_uploaded', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ data: { leads_uploaded: 3 } })
+      })
+
+      const params: BulkAddLeadsParams = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: 'a@example.com' }, { email: 'b@example.com' }, { email: 'c@example.com' }]
+      }
+
+      const result = await bulkAddLeads(validCredentials, params)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 3,
+        failed_count: 0
+      })
+    })
+
+    it('should handle uploaded response variant', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ uploaded: 2 })
+      })
+
+      const params: BulkAddLeadsParams = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: 'a@example.com' }, { email: 'b@example.com' }]
+      }
+
+      const result = await bulkAddLeads(validCredentials, params)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 2,
+        failed_count: 0
+      })
+    })
+
+    it('should return success false when failed_count is greater than 0', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            added_count: 8,
+            failed_count: 2,
+            errors: [
+              { email: 'bad1@example.com', error: 'Invalid email' },
+              { email: 'bad2@example.com', error: 'Duplicate lead' }
+            ]
+          })
+      })
+
+      const params: BulkAddLeadsParams = {
+        campaign_id: 'campaign-123',
+        leads: Array.from({ length: 10 }, (_, i) => ({ email: `lead${i}@example.com` }))
+      }
+
+      const result = await bulkAddLeads(validCredentials, params)
+
+      expect(result.success).toBe(false)
+      expect(result.added_count).toBe(8)
+      expect(result.failed_count).toBe(2)
+      expect(result.errors).toBeDefined()
+      expect(result.errors!.length).toBe(2)
+    })
+
+    it('should handle custom_variables in lead payload', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ leads_uploaded: 1 })
+      })
+
+      const params: BulkAddLeadsParams = {
+        campaign_id: 'campaign-123',
+        leads: [
+          {
+            email: 'custom@example.com',
+            first_name: 'Custom',
+            custom_variables: { industry: 'SaaS', role: 'CEO' }
+          }
+        ]
+      }
+
+      const result = await bulkAddLeads(validCredentials, params)
+
+      expect(result.success).toBe(true)
+      expect(result.added_count).toBe(1)
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/leads/add',
+        expect.objectContaining({
+          body: JSON.stringify({
+            campaign_id: 'campaign-123',
+            leads: [
+              {
+                email: 'custom@example.com',
+                first_name: 'Custom',
+                last_name: undefined,
+                company_name: undefined,
+                website: undefined,
+                custom_variables: { industry: 'SaaS', role: 'CEO' }
+              }
+            ]
+          })
+        })
+      )
+    })
+  })
+
+  describe('Error Cases', () => {
+    it('should throw when API returns 400 error', async () => {
+      mockFetch.mockResolvedValue({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        text: () => Promise.resolve('Invalid campaign ID')
+      })
+
+      await expect(bulkAddLeads(validCredentials, validParams)).rejects.toThrow(ToolingError)
+      await expect(bulkAddLeads(validCredentials, validParams)).rejects.toMatchObject({
+        errorType: 'validation_error'
+      })
+    })
+  })
+
+  describe('Logging', () => {
+    it('should log when context is provided', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ leads_uploaded: 1 })
+      })
+
+      const context = createMockContext()
+      await bulkAddLeads(validCredentials, validParams, context)
+
+      expect(context.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[InstantlyAdapter] Bulk adding leads to campaign:')
+      )
+
+      expect(context.logger.info).toHaveBeenCalledWith(expect.stringContaining('[InstantlyAdapter] Bulk leads added:'))
+    })
+  })
+})

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/bulk-add-leads/index.ts

@@ -0,0 +1,153 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface BulkAddLeadsLead {
+  email: string
+  first_name?: string
+  last_name?: string
+  company_name?: string
+  website?: string
+  custom_variables?: Record<string, string>
+}
+
+export interface BulkAddLeadsParams {
+  campaign_id: string
+  leads: BulkAddLeadsLead[]
+}
+
+export interface BulkAddLeadsError {
+  email: string
+  error: string
+}
+
+export interface BulkAddLeadsResult {
+  success: boolean
+  added_count: number
+  failed_count: number
+  errors?: BulkAddLeadsError[]
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Bulk add leads to an Instantly campaign
+ *
+ * Adds up to 1,000 leads in a single request to an existing campaign.
+ * Supports full lead profiles including custom variables. Each lead
+ * must have a valid email address.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Campaign ID and array of leads (max 1,000)
+ * @param context - Execution context for logging
+ * @returns Result with success status, added count, failed count, and per-lead errors
+ */
+export async function bulkAddLeads(
+  credentials: InstantlyCredentials,
+  params: BulkAddLeadsParams,
+  context?: ExecutionContext
+): Promise<BulkAddLeadsResult> {
+  const { apiKey } = credentials
+  const { campaign_id, leads } = params
+
+  // Validation
+  if (!campaign_id) {
+    throw new ToolingError('validation_error', 'Missing required parameter: campaign_id', {
+      integration: 'instantly',
+      method: 'bulkAddLeads'
+    })
+  }
+
+  if (!leads || leads.length === 0) {
+    throw new ToolingError('validation_error', 'Must provide at least one lead', {
+      integration: 'instantly',
+      method: 'bulkAddLeads'
+    })
+  }
+
+  if (leads.length > 1000) {
+    throw new ToolingError('validation_error', 'Cannot add more than 1,000 leads per request', {
+      integration: 'instantly',
+      method: 'bulkAddLeads'
+    })
+  }
+
+  // Validate each lead has an email
+  for (const lead of leads) {
+    if (!lead.email) {
+      throw new ToolingError('validation_error', 'Each lead must have an email address', {
+        integration: 'instantly',
+        method: 'bulkAddLeads'
+      })
+    }
+  }
+
+  const bulkLeadsUrl = `${INSTANTLY_API_BASE}/leads/add`
+
+  const requestBody = {
+    campaign_id,
+    leads: leads.map((lead) => ({
+      email: lead.email,
+      first_name: lead.first_name,
+      last_name: lead.last_name,
+      company_name: lead.company_name,
+      website: lead.website,
+      custom_variables: lead.custom_variables
+    }))
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Bulk adding leads to campaign: campaign_id=${campaign_id} lead_count=${leads.length} executionId=${context.executionId}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(bulkLeadsUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(requestBody)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'bulkAddLeads',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response.data ?? response
+
+  // Parse response - Instantly API v2 /leads/add returns:
+  // { status, total_sent, leads_uploaded, in_blocklist, duplicated_leads, skipped_count,
+  //   invalid_email_count, incomplete_count, duplicate_email_count, created_leads[] }
+  const added_count = data.leads_uploaded ?? data.added_count ?? data.uploaded ?? leads.length
+  const failed_count =
+    (data.invalid_email_count ?? 0) + (data.incomplete_count ?? 0) + (data.failed_count ?? data.failed ?? 0)
+  const errors: BulkAddLeadsError[] | undefined =
+    data.errors && Array.isArray(data.errors) && data.errors.length > 0 ? data.errors : undefined
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Bulk leads added: campaign_id=${campaign_id} added_count=${added_count} failed_count=${failed_count} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    success: failed_count === 0,
+    added_count,
+    failed_count,
+    ...(errors ? { errors } : {})
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/bulk-delete-leads/index.ts

@@ -0,0 +1,84 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface BulkDeleteLeadsParams {
+  ids?: string[]
+  campaign_id?: string
+  list_id?: string
+  limit?: number
+}
+
+export interface BulkDeleteLeadsResult {
+  deleted_count: number
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Bulk delete leads from Instantly
+ *
+ * Deletes leads matching the provided filters. At least one of ids,
+ * campaign_id, or list_id is recommended to avoid unintended broad deletions.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Deletion filters (IDs, campaign, list, or limit)
+ * @param context - Execution context for logging
+ * @returns Count of deleted leads
+ */
+export async function bulkDeleteLeads(
+  credentials: InstantlyCredentials,
+  params: BulkDeleteLeadsParams,
+  context?: ExecutionContext
+): Promise<BulkDeleteLeadsResult> {
+  const { apiKey } = credentials
+  const { ids, campaign_id, list_id, limit } = params
+
+  const body: Record<string, unknown> = {}
+  if (ids && ids.length > 0) body.ids = ids
+  if (campaign_id) body.campaign_id = campaign_id
+  if (list_id) body.list_id = list_id
+  if (limit !== undefined) body.limit = limit
+
+  const url = `${INSTANTLY_API_BASE}/leads`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Bulk deleting leads: ids_count=${ids?.length} campaign_id=${campaign_id} executionId=${context.executionId}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'bulkDeleteLeads',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const deleted_count = Number(response.deleted_count ?? response.count ?? 0)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Bulk delete leads complete: deleted_count=${deleted_count} executionId=${context.executionId}`
+    )
+  }
+
+  return { deleted_count }
+}

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/create-campaign/index.ts

@@ -0,0 +1,125 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface CreateCampaignParams {
+  name: string
+  sequences?: Array<{
+    steps: Array<{
+      type?: string
+      delay?: number
+      subject: string
+      body: string
+      variants?: Array<{
+        subject: string
+        body: string
+      }>
+    }>
+  }>
+  email_list?: string[]
+  campaign_schedule?: {
+    schedules: Array<{
+      name: string
+      timing: { from: string; to: string }
+      days: Record<string, boolean>
+      timezone: string
+    }>
+  }
+  daily_limit?: number
+  stop_on_reply?: boolean
+  stop_on_auto_reply?: boolean
+  track_opens?: boolean
+  track_clicks?: boolean
+  text_only?: boolean
+}
+
+export interface CreateCampaignResult {
+  success: boolean
+  campaign_id: string
+  name: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Create a new Instantly campaign
+ *
+ * Creates a new campaign with optional sequences, email list, and sending configuration.
+ * Returns the ID and name of the newly created campaign.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Campaign name (required) plus optional configuration
+ * @param context - Execution context for logging
+ * @returns Success status, campaign ID, and campaign name
+ */
+export async function createCampaign(
+  credentials: InstantlyCredentials,
+  params: CreateCampaignParams,
+  context?: ExecutionContext
+): Promise<CreateCampaignResult> {
+  const { apiKey } = credentials
+  const { name, ...optionalFields } = params
+
+  // Validation
+  if (!name) {
+    throw new ToolingError('validation_error', 'Missing required parameter: name', {
+      integration: 'instantly',
+      method: 'createCampaign'
+    })
+  }
+
+  const campaignsUrl = `${INSTANTLY_API_BASE}/campaigns`
+
+  // Build request body from all provided fields
+  const requestBody: Record<string, unknown> = { name }
+  for (const [key, value] of Object.entries(optionalFields)) {
+    if (value !== undefined) {
+      requestBody[key] = value
+    }
+  }
+
+  if (context?.logger) {
+    context.logger.info(`[InstantlyAdapter] Creating campaign: name=${name} executionId=${context.executionId}`)
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(campaignsUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(requestBody)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'createCampaign',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const data = response.data ?? response
+  const campaign_id = data.id || data.campaign_id || ''
+  const campaignName = data.name || name
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Campaign created successfully: campaign_id=${campaign_id} name=${campaignName} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    success: true,
+    campaign_id,
+    name: campaignName
+  }
+}