@elevasis/core 0.1.0

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/list-campaigns/__tests__/index.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { listCampaigns } from '../index.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('listCampaigns', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.resetAllMocks()
+  })
+
+  const validCredentials = { apiKey: 'test-api-key' }
+
+  describe('Success Cases', () => {
+    it('should return campaigns from array response', async () => {
+      const campaignData = [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(campaignData)
+      })
+
+      const context = createMockContext()
+      const result = await listCampaigns(validCredentials, {}, context)
+
+      expect(result).toEqual({
+        campaigns: [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      })
+    })
+
+    it('should handle wrapped { data: [...] } response', async () => {
+      const campaignData = [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ data: campaignData })
+      })
+
+      const result = await listCampaigns(validCredentials, {})
+
+      expect(result).toEqual({
+        campaigns: [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      })
+    })
+
+    it('should handle { campaigns: [...] } response shape', async () => {
+      const campaignData = [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ campaigns: campaignData })
+      })
+
+      const result = await listCampaigns(validCredentials, {})
+
+      expect(result).toEqual({
+        campaigns: [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      })
+    })
+
+    it('should handle { items: [...] } response shape', async () => {
+      const campaignData = [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ items: campaignData })
+      })
+
+      const result = await listCampaigns(validCredentials, {})
+
+      expect(result).toEqual({
+        campaigns: [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      })
+    })
+
+    it('should return next_starting_after when present in response', async () => {
+      const campaignData = [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }]
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({ campaigns: campaignData, next_starting_after: 'cursor-abc' })
+      })
+
+      const result = await listCampaigns(validCredentials, {})
+
+      expect(result).toEqual({
+        campaigns: [{ id: 'c1', name: 'Campaign 1', status: 'active', created_at: '2026-01-01' }],
+        next_starting_after: 'cursor-abc'
+      })
+    })
+
+    it('should return empty campaigns for empty response {}', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve({})
+      })
+
+      const result = await listCampaigns(validCredentials, {})
+
+      expect(result).toEqual({ campaigns: [] })
+    })
+  })
+
+  describe('URL Construction', () => {
+    it('should call exact base URL with no query string when no params provided', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([])
+      })
+
+      await listCampaigns(validCredentials, {})
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/campaigns',
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer test-api-key'
+          }
+        })
+      )
+    })
+
+    it('should include limit and status as query params', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([])
+      })
+
+      await listCampaigns(validCredentials, { limit: 10, status: 'active' })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/campaigns?limit=10&status=active',
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer test-api-key'
+          }
+        })
+      )
+    })
+
+    it('should include search as query param', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([])
+      })
+
+      await listCampaigns(validCredentials, { search: 'vet' })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/campaigns?search=vet',
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer test-api-key'
+          }
+        })
+      )
+    })
+
+    it('should include starting_after as query param', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([])
+      })
+
+      await listCampaigns(validCredentials, { starting_after: 'cursor123' })
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://api.instantly.ai/api/v2/campaigns?starting_after=cursor123',
+        expect.objectContaining({
+          headers: {
+            Authorization: 'Bearer test-api-key'
+          }
+        })
+      )
+    })
+  })
+})

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/list-campaigns/index.ts

@@ -0,0 +1,87 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface ListCampaignsParams {
+  limit?: number
+  starting_after?: string
+  search?: string
+  status?: number
+}
+
+export interface ListCampaignsResult {
+  campaigns: Array<{ id: string; name: string; status: string; created_at: string; [key: string]: unknown }>
+  next_starting_after?: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * List campaigns from Instantly workspace
+ *
+ * Retrieves a paginated list of campaigns with optional filtering by status or search term.
+ * Uses cursor-based pagination via starting_after.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Pagination and filter options
+ * @param context - Execution context for logging
+ * @returns Campaigns array and optional next cursor for pagination
+ */
+export async function listCampaigns(
+  credentials: InstantlyCredentials,
+  params: ListCampaignsParams,
+  context?: ExecutionContext
+): Promise<ListCampaignsResult> {
+  const { apiKey } = credentials
+  const { limit, starting_after, search, status } = params
+
+  const queryParams = new URLSearchParams()
+  if (limit) queryParams.set('limit', String(limit))
+  if (starting_after) queryParams.set('starting_after', starting_after)
+  if (search) queryParams.set('search', search)
+  if (status !== undefined) queryParams.set('status', String(status))
+
+  const listUrl = `${INSTANTLY_API_BASE}/campaigns${queryParams.toString() ? `?${queryParams.toString()}` : ''}`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Listing campaigns: limit=${limit} status=${status} executionId=${context.executionId}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(listUrl, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`
+      }
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'listCampaigns',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const rawData = response.data ?? response
+  const campaigns = Array.isArray(rawData) ? rawData : rawData?.items || rawData?.campaigns || []
+  const next_starting_after = response.next_starting_after || response.data?.next_starting_after
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Campaigns fetched: count=${campaigns.length} next=${next_starting_after || 'none'} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    campaigns,
+    ...(next_starting_after ? { next_starting_after } : {})
+  }
+}

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

@@ -0,0 +1,112 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface ListLeadsParams {
+  campaign_id?: string
+  email?: string
+  limit?: number
+  starting_after?: string
+}
+
+export interface ListLeadsResult {
+  items: Array<{
+    id: string
+    email: string
+    first_name?: string
+    last_name?: string
+    company_name?: string
+    status: string
+    campaign_id?: string
+    timestamp_created?: string
+  }>
+  next_starting_after?: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * List leads in Instantly with optional filtering and pagination
+ *
+ * Uses a POST endpoint per Instantly API design — complex filter arguments
+ * are expressed as a JSON body rather than query parameters.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Optional filters and pagination cursor
+ * @param context - Execution context for logging
+ * @returns Paginated list of leads
+ */
+export async function listLeads(
+  credentials: InstantlyCredentials,
+  params: ListLeadsParams,
+  context?: ExecutionContext
+): Promise<ListLeadsResult> {
+  const { apiKey } = credentials
+  const { campaign_id, email, limit, starting_after } = params
+
+  const body: Record<string, unknown> = {}
+  if (campaign_id) body.campaign = campaign_id
+  if (email) body.contacts = [email]
+  if (limit !== undefined) body.limit = limit
+  if (starting_after) body.starting_after = starting_after
+
+  const url = `${INSTANTLY_API_BASE}/leads/list`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Listing leads: campaign_id=${campaign_id} email=${email} limit=${limit} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'listLeads',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  const rawItems: Array<Record<string, unknown>> = Array.isArray(response.items)
+    ? response.items
+    : Array.isArray(response)
+      ? response
+      : []
+
+  const items = rawItems.map((item) => ({
+    id: String(item.id ?? ''),
+    email: String(item.email ?? ''),
+    first_name: item.first_name !== undefined ? String(item.first_name) : undefined,
+    last_name: item.last_name !== undefined ? String(item.last_name) : undefined,
+    company_name: item.company_name !== undefined ? String(item.company_name) : undefined,
+    status: String(item.status ?? ''),
+    campaign_id: item.campaign_id !== undefined ? String(item.campaign_id) : undefined,
+    timestamp_created: item.timestamp_created !== undefined ? String(item.timestamp_created) : undefined
+  }))
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Leads listed: count=${items.length} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    items,
+    next_starting_after: response.next_starting_after !== undefined ? String(response.next_starting_after) : undefined
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/patch-lead/index.ts

@@ -0,0 +1,76 @@
+import { withRetry, createHttpError, DEFAULT_RETRY_POLICY } from '../../../../../../../../../platform/resilience'
+import type { ExecutionContext } from '../../../../../../../base/types'
+
+interface InstantlyCredentials {
+  apiKey: string
+}
+
+export interface PatchLeadParams {
+  lead_id: string
+  custom_variables: Record<string, string>
+}
+
+export interface PatchLeadResult {
+  id: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Patch a lead's custom variables in Instantly
+ *
+ * Uses PATCH /api/v2/leads/{id} — custom_variables are merged additively,
+ * so existing keys (e.g. opening_line) are preserved.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Lead ID and custom variables to set
+ * @param context - Execution context for logging
+ * @returns Object containing the updated lead's ID
+ */
+export async function patchLead(
+  credentials: InstantlyCredentials,
+  params: PatchLeadParams,
+  context?: ExecutionContext
+): Promise<PatchLeadResult> {
+  const { apiKey } = credentials
+  const { lead_id, custom_variables } = params
+
+  const url = `${INSTANTLY_API_BASE}/leads/${lead_id}`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Patching lead: lead_id=${lead_id} keys=[${Object.keys(custom_variables).join(', ')}] organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  const response = await withRetry(async () => {
+    const res = await fetch(url, {
+      method: 'PATCH',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ custom_variables })
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'patchLead',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Lead patched: lead_id=${lead_id} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    id: String(response.id ?? lead_id)
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/pause-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 PauseCampaignParams {
+  campaign_id: string
+}
+
+export interface PauseCampaignResult {
+  success: boolean
+  campaign_id: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Pause an active Instantly campaign
+ *
+ * Pauses a running campaign, stopping further email sends until the campaign is activated again.
+ * Leads already in progress are not affected until the next scheduled send.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Campaign ID to pause
+ * @param context - Execution context for logging
+ * @returns Success status and campaign ID
+ */
+export async function pauseCampaign(
+  credentials: InstantlyCredentials,
+  params: PauseCampaignParams,
+  context?: ExecutionContext
+): Promise<PauseCampaignResult> {
+  const { apiKey } = credentials
+  const { campaign_id } = params
+
+  // Validation
+  if (!campaign_id) {
+    throw new ToolingError('validation_error', 'Missing required parameter: campaign_id', {
+      integration: 'instantly',
+      method: 'pauseCampaign'
+    })
+  }
+
+  const pauseUrl = `${INSTANTLY_API_BASE}/campaigns/${campaign_id}/pause`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Pausing campaign: campaign_id=${campaign_id} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  await withRetry(async () => {
+    const res = await fetch(pauseUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({})
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'pauseCampaign',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Campaign paused successfully: campaign_id=${campaign_id} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    success: true,
+    campaign_id
+  }
+}

package/src/execution/engine/tools/integration/server/adapters/instantly/fetch/remove-from-subsequence/index.ts

@@ -0,0 +1,98 @@
+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 RemoveFromSubsequenceParams {
+  lead_email: string
+  campaign_id: string
+}
+
+export interface RemoveFromSubsequenceResult {
+  success: boolean
+  lead_email: string
+  campaign_id: string
+}
+
+const INSTANTLY_API_BASE = 'https://api.instantly.ai/api/v2'
+
+/**
+ * Remove a lead from a campaign subsequence
+ *
+ * Stops a lead from receiving further emails in a campaign sequence.
+ * Useful for removing leads who have replied or are no longer qualified.
+ *
+ * @param credentials - Instantly API key
+ * @param params - Lead email and campaign ID
+ * @param context - Execution context for logging
+ * @returns Removal confirmation
+ */
+export async function removeFromSubsequence(
+  credentials: InstantlyCredentials,
+  params: RemoveFromSubsequenceParams,
+  context?: ExecutionContext
+): Promise<RemoveFromSubsequenceResult> {
+  const { apiKey } = credentials
+  const { lead_email, campaign_id } = params
+
+  if (!lead_email) {
+    throw new ToolingError('validation_error', 'Missing required parameter: lead_email', {
+      integration: 'instantly',
+      method: 'removeFromSubsequence'
+    })
+  }
+
+  if (!campaign_id) {
+    throw new ToolingError('validation_error', 'Missing required parameter: campaign_id', {
+      integration: 'instantly',
+      method: 'removeFromSubsequence'
+    })
+  }
+
+  const removeUrl = `${INSTANTLY_API_BASE}/leads/subsequence/remove`
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Removing lead from subsequence: lead_email=${lead_email} campaign_id=${campaign_id} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  await withRetry(async () => {
+    const res = await fetch(removeUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        lead_email,
+        campaign_id
+      })
+    })
+
+    if (!res.ok) {
+      throw await createHttpError(res, {
+        integration: 'instantly',
+        method: 'removeFromSubsequence',
+        organizationId: context?.organizationId
+      })
+    }
+
+    return res.json()
+  }, DEFAULT_RETRY_POLICY)
+
+  if (context?.logger) {
+    context.logger.info(
+      `[InstantlyAdapter] Lead removed successfully: lead_email=${lead_email} campaign_id=${campaign_id} organizationId=${context.organizationId} executionId=${context.executionId}`
+    )
+  }
+
+  return {
+    success: true,
+    lead_email,
+    campaign_id
+  }
+}