@elevasis/core 0.1.0

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

@@ -0,0 +1,86 @@
+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 ActivateCampaignParams {
+  campaign_id: string
+}
+
+export interface ActivateCampaignResult {
+  success: boolean
+  campaign_id: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Activate a paused or draft Instantly campaign
+ *
+ * Activates a campaign so it begins (or resumes) sending emails to leads.
+ * A campaign must be activated before any emails are sent.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Campaign ID to activate
+ * @param context - Execution context for logging
+ * @returns Success status and campaign ID
+ */
+export async function activateCampaign(
+  credentials: InstantlyCredentials,
+  params: ActivateCampaignParams,
+  context?: ExecutionContext
+): Promise<ActivateCampaignResult> {
+  const { apiKey } = credentials
+  const { campaign_id } = params
+
+  // Validation
+  if (!campaign_id) {
+    throw new ToolingError('validation_error', 'Missing required parameter: campaign_id', {
+      integration: 'instantly',
+      method: 'activateCampaign'
+    })
+  }
+
+  const activateUrl = `${INSTANTLY_API_BASE}/campaigns/${campaign_id}/activate`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Activating campaign: campaign_id=${campaign_id} executionId=${context.executionId}`
+    )
+  }
+
+  await withRetry(async () => {
+    const res = await fetch(activateUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({})
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'activateCampaign',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Campaign activated successfully: campaign_id=${campaign_id} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    success: true,
+    campaign_id
+  }
+}

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

@@ -0,0 +1,289 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { addToCampaign, type AddToCampaignParams } 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('addToCampaign', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  const validCredentials = { apiKey: 'test-api-key' }
+  const validParams: AddToCampaignParams = {
+    campaign_id: 'campaign-123',
+    leads: [
+      {
+        email: 'test@example.com',
+        first_name: 'Test',
+        last_name: 'User',
+        company_name: 'Test Company'
+      }
+    ]
+  }
+
+  describe('Validation', () => {
+    it('should throw error when campaign_id is missing', async () => {
+      const params = {
+        campaign_id: '',
+        leads: [{ email: 'test@example.com' }]
+      }
+
+      await expect(addToCampaign(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(addToCampaign(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Missing required parameter: campaign_id'
+      })
+    })
+
+    it('should throw error when leads array is empty', async () => {
+      const params = {
+        campaign_id: 'campaign-123',
+        leads: []
+      }
+
+      await expect(addToCampaign(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(addToCampaign(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Must provide at least one lead'
+      })
+    })
+
+    it('should throw error when lead is missing email', async () => {
+      const params = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: '', first_name: 'Test' }]
+      }
+
+      await expect(addToCampaign(validCredentials, params)).rejects.toThrow(ToolingError)
+      await expect(addToCampaign(validCredentials, params)).rejects.toMatchObject({
+        errorType: 'validation_error',
+        message: 'Each lead must have an email address'
+      })
+    })
+  })
+
+  describe('Success Cases', () => {
+    it('should add single lead to campaign successfully', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'success', leads_uploaded: 1 })
+      })
+
+      const context = createMockContext()
+      const result = await addToCampaign(validCredentials, validParams, context)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 1,
+        errors: undefined
+      })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/leads',
+        expect.objectContaining({
+          method: 'POST',
+          headers: {
+            Authorization: 'Bearer test-api-key',
+            'Content-Type': 'application/json'
+          },
+          body: JSON.stringify({
+            campaign_id: 'campaign-123',
+            leads: [
+              {
+                email: 'test@example.com',
+                first_name: 'Test',
+                last_name: 'User',
+                company_name: 'Test Company'
+              }
+            ]
+          })
+        })
+      )
+    })
+
+    it('should add multiple leads to campaign', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'success', leads_uploaded: 3 })
+      })
+
+      const params: AddToCampaignParams = {
+        campaign_id: 'campaign-123',
+        leads: [
+          { email: 'lead1@example.com', first_name: 'Lead', last_name: 'One' },
+          { email: 'lead2@example.com', first_name: 'Lead', last_name: 'Two' },
+          { email: 'lead3@example.com' }
+        ]
+      }
+
+      const result = await addToCampaign(validCredentials, params)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 3,
+        errors: undefined
+      })
+    })
+
+    it('should handle response with uploaded field', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ uploaded: 5 })
+      })
+
+      const params: AddToCampaignParams = {
+        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 result = await addToCampaign(validCredentials, params)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 5,
+        errors: undefined
+      })
+    })
+
+    it('should handle wrapped response format', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ data: { leads_uploaded: 2 } })
+      })
+
+      const params: AddToCampaignParams = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: 'a@example.com' }, { email: 'b@example.com' }]
+      }
+
+      const result = await addToCampaign(validCredentials, params)
+
+      expect(result).toEqual({
+        success: true,
+        added_count: 2,
+        errors: undefined
+      })
+    })
+
+    it('should handle lead with only email', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'success', leads_uploaded: 1 })
+      })
+
+      const params: AddToCampaignParams = {
+        campaign_id: 'campaign-123',
+        leads: [{ email: 'minimal@example.com' }]
+      }
+
+      const result = await addToCampaign(validCredentials, params)
+
+      expect(result.success).toBe(true)
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.any(String),
+        expect.objectContaining({
+          body: JSON.stringify({
+            campaign_id: 'campaign-123',
+            leads: [
+              {
+                email: 'minimal@example.com',
+                first_name: undefined,
+                last_name: undefined,
+                company_name: undefined
+              }
+            ]
+          })
+        })
+      )
+    })
+  })
+
+  describe('Error Cases', () => {
+    it('should handle API error response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 400,
+        statusText: 'Bad Request',
+        text: () => Promise.resolve('Invalid campaign ID')
+      })
+
+      const result = await addToCampaign(validCredentials, validParams)
+
+      expect(result.success).toBe(false)
+      expect(result.added_count).toBe(0)
+      expect(result.errors).toBeDefined()
+      expect(result.errors!.length).toBeGreaterThan(0)
+    })
+
+    it('should handle network error', async () => {
+      // Mock repeated failures to exhaust retries
+      mockFetch.mockRejectedValue(new Error('Network error'))
+
+      const result = await addToCampaign(validCredentials, validParams)
+
+      expect(result.success).toBe(false)
+      expect(result.added_count).toBe(0)
+      expect(result.errors).toBeDefined()
+      expect(result.errors!.length).toBeGreaterThan(0)
+    })
+
+    it('should handle 401 unauthorized error', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        statusText: 'Unauthorized',
+        text: () => Promise.resolve('Invalid API key')
+      })
+
+      const result = await addToCampaign(validCredentials, validParams)
+
+      expect(result.success).toBe(false)
+      expect(result.errors).toBeDefined()
+    })
+  })
+
+  describe('Logging', () => {
+    it('should log when context is provided', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ status: 'success', leads_uploaded: 1 })
+      })
+
+      const context = createMockContext()
+      await addToCampaign(validCredentials, validParams, context)
+
+      expect(context.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[InstantlyAdapter] Adding leads to campaign:')
+      )
+
+      expect(context.logger.info).toHaveBeenCalledWith(
+        expect.stringContaining('[InstantlyAdapter] Leads added successfully:')
+      )
+    })
+  })
+})

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

@@ -0,0 +1,154 @@
+import { ToolingError } from '../../../../../../types'
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+/**
+ * Lead data for adding to an Instantly campaign
+ */
+export interface AddToCampaignLead {
+  email: string
+  first_name?: string
+  last_name?: string
+  company_name?: string
+}
+
+export interface AddToCampaignParams {
+  campaign_id: string
+  leads: AddToCampaignLead[]
+}
+
+export interface AddToCampaignResult {
+  success: boolean
+  added_count: number
+  errors?: string[]
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Add leads to an Instantly campaign
+ *
+ * Adds one or more leads to an existing campaign. When leads are added,
+ * they begin receiving the campaign sequence immediately (Day 0).
+ *
+ * @param credentials - Instantly API key
+ * @param params - Campaign ID and array of leads to add
+ * @param context - Execution context for logging
+ * @returns Result with success status and count of added leads
+ */
+export async function addToCampaign(
+  credentials: InstantlyCredentials,
+  params: AddToCampaignParams,
+  context?: ExecutionContext
+): Promise<AddToCampaignResult> {
+  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: 'addToCampaign'
+    })
+  }
+
+  if (!leads || leads.length === 0) {
+    throw new ToolingError('validation_error', 'Must provide at least one lead', {
+      integration: 'instantly',
+      method: 'addToCampaign'
+    })
+  }
+
+  // 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: 'addToCampaign'
+      })
+    }
+  }
+
+  const addLeadsUrl = `${INSTANTLY_API_BASE}/leads`
+
+  // Transform leads to Instantly API format
+  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
+    }))
+  }
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Adding leads to campaign: campaign_id=${campaign_id} lead_count=${leads.length} executionId=${context.executionId}`
+    )
+  }
+
+  const errors: string[] = []
+  let addedCount = 0
+
+  try {
+    const response = await withRetry(async () => {
+      const res = await fetch(addLeadsUrl, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(requestBody)
+      })
+
+      if (!res.ok) {
+        throw await createHttpError(res, {
+          integration: 'instantly',
+          method: 'addToCampaign',
+          organizationId: context?.organizationId
+        })
+      }
+
+      return res.json()
+    }, DEFAULT_RETRY_POLICY)
+
+    // Parse response - Instantly API returns different structures
+    // Common response: { status: 'success', leads_uploaded: N }
+    // Or: { uploaded: N, ... }
+    if (response.status === 'success' || response.uploaded || response.leads_uploaded) {
+      addedCount = response.leads_uploaded || response.uploaded || leads.length
+    } else if (response.data) {
+      // Wrapped response format
+      addedCount = response.data.leads_uploaded || response.data.uploaded || leads.length
+    } else {
+      // Assume success if no error was thrown
+      addedCount = leads.length
+    }
+
+    if (context?.logger) {
+      context.logger.info(
+        `[InstantlyAdapter] Leads added successfully: campaign_id=${campaign_id} added_count=${addedCount} executionId=${context.executionId}`
+      )
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error)
+    errors.push(errorMessage)
+
+    if (context?.logger) {
+      context.logger.error(
+        `[InstantlyAdapter] Failed to add leads: campaign_id=${campaign_id} error=${errorMessage} executionId=${context.executionId}`
+      )
+    }
+  }
+
+  return {
+    success: errors.length === 0,
+    added_count: addedCount,
+    errors: errors.length > 0 ? errors : undefined
+  }
+}