@elevasis/core 0.1.0

package/src/execution/engine/tools/platform/acquisition/company-tools.ts

@@ -0,0 +1,248 @@
+import { getToolServices } from '../../registry'
+import { serviceUnavailable } from '../../types'
+import type { Tool } from '../../types'
+import {
+  CreateCompanyInputSchema,
+  UpdateCompanyInputSchema,
+  UpsertCompanyInputSchema,
+  GetCompanyInputSchema,
+  ListCompaniesInputSchema,
+  DeleteCompanyInputSchema,
+  CompanyOutputSchema,
+  CompanyArrayOutputSchema,
+  DeleteResultSchema,
+  type CreateCompanyInput,
+  type UpdateCompanyInput,
+  type UpsertCompanyInput,
+  type GetCompanyInput,
+  type ListCompaniesInput,
+  type DeleteCompanyInput
+} from './types'
+
+/**
+ * Helper to transform company result to output format
+ * Converts Date objects to ISO strings for consistent API responses
+ */
+function toCompanyOutput(result: any) {
+  return {
+    id: result.id,
+    organizationId: result.organizationId,
+    name: result.name,
+    domain: result.domain,
+    linkedinUrl: result.linkedinUrl,
+    website: result.website,
+    numEmployees: result.numEmployees,
+    foundedYear: result.foundedYear,
+    locationCity: result.locationCity,
+    locationState: result.locationState,
+    category: result.category,
+    categoryPain: result.categoryPain ?? null,
+    segment: result.segment,
+    pipelineStatus: result.pipelineStatus,
+    enrichmentData: result.enrichmentData,
+    tags: result.tags,
+    source: result.source,
+    batchId: result.batchId ?? null,
+    status: result.status,
+    createdAt: result.createdAt instanceof Date ? result.createdAt.toISOString() : result.createdAt,
+    updatedAt: result.updatedAt instanceof Date ? result.updatedAt.toISOString() : result.updatedAt
+  }
+}
+
+/**
+ * Create a tool for creating new company records
+ *
+ * @returns Tool that creates a company
+ *
+ * @example
+ * const tool = createAcqCompanyCreateTool()
+ * const result = await tool.execute({
+ *   input: { name: 'Acme Corp', domain: 'acme.com' },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyCreateTool(): Tool {
+  return {
+    name: 'acq_company_create',
+    description: 'Create a new company record for lead tracking.',
+    inputSchema: CreateCompanyInputSchema,
+    outputSchema: CompanyOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as CreateCompanyInput
+      const result = await leadService.createCompany({
+        organizationId: executionContext.organizationId,
+        ...typedInput
+      })
+
+      return toCompanyOutput(result)
+    }
+  }
+}
+
+/**
+ * Create a tool for updating existing company records
+ *
+ * @returns Tool that updates a company
+ *
+ * @example
+ * const tool = createAcqCompanyUpdateTool()
+ * const result = await tool.execute({
+ *   input: { id: 'company-123', numEmployees: 500 },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyUpdateTool(): Tool {
+  return {
+    name: 'acq_company_update',
+    description: 'Update an existing company record with new data (e.g., enrichment data, firmographics).',
+    inputSchema: UpdateCompanyInputSchema,
+    outputSchema: CompanyOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as UpdateCompanyInput
+      const { id, ...params } = typedInput
+      const result = await leadService.updateCompany(id, params)
+
+      return toCompanyOutput(result)
+    }
+  }
+}
+
+/**
+ * Create a tool for upserting companies by domain
+ * Creates new record if domain does not exist, otherwise updates existing
+ *
+ * @returns Tool that upserts a company
+ *
+ * @example
+ * const tool = createAcqCompanyUpsertTool()
+ * const result = await tool.execute({
+ *   input: { name: 'Acme Corp', domain: 'acme.com' },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyUpsertTool(): Tool {
+  return {
+    name: 'acq_company_upsert',
+    description: 'Upsert a company by domain. Creates new record if domain does not exist, otherwise updates existing.',
+    inputSchema: UpsertCompanyInputSchema,
+    outputSchema: CompanyOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as UpsertCompanyInput
+      const result = await leadService.upsertCompany({
+        organizationId: executionContext.organizationId,
+        ...typedInput
+      })
+
+      return toCompanyOutput(result)
+    }
+  }
+}
+
+/**
+ * Create a tool for getting a single company by ID
+ *
+ * @returns Tool that retrieves a company
+ *
+ * @example
+ * const tool = createAcqCompanyGetTool()
+ * const result = await tool.execute({
+ *   input: { id: 'company-123' },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyGetTool(): Tool {
+  return {
+    name: 'acq_company_get',
+    description: 'Get a single company by ID.',
+    inputSchema: GetCompanyInputSchema,
+    outputSchema: CompanyOutputSchema.nullable(),
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as GetCompanyInput
+      const result = await leadService.getCompany(typedInput.id, executionContext.organizationId)
+      return result ? toCompanyOutput(result) : null
+    }
+  }
+}
+
+/**
+ * Create a tool for listing companies with optional filters
+ *
+ * @returns Tool that lists companies
+ *
+ * @example
+ * const tool = createAcqCompanyListTool()
+ * const result = await tool.execute({
+ *   input: { segment: 'smb', category: 'saas' },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyListTool(): Tool {
+  return {
+    name: 'acq_company_list',
+    description: 'List companies with optional filters for category, segment, or pipeline status.',
+    inputSchema: ListCompaniesInputSchema,
+    outputSchema: CompanyArrayOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as ListCompaniesInput
+      const results = await leadService.listCompanies(executionContext.organizationId, typedInput)
+      return results.map(toCompanyOutput)
+    }
+  }
+}
+
+/**
+ * Create a tool for deleting company records
+ * Associated contacts will have their company_id set to null
+ *
+ * @returns Tool that deletes a company
+ *
+ * @example
+ * const tool = createAcqCompanyDeleteTool()
+ * const result = await tool.execute({
+ *   input: { id: 'company-123' },
+ *   executionContext: { organizationId: 'org-123', ... }
+ * })
+ */
+export function createAcqCompanyDeleteTool(): Tool {
+  return {
+    name: 'acq_company_delete',
+    description: 'Delete a company record. Associated contacts will have their company_id set to null.',
+    inputSchema: DeleteCompanyInputSchema,
+    outputSchema: DeleteResultSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const typedInput = input as DeleteCompanyInput
+      await leadService.deleteCompany(typedInput.id, executionContext.organizationId)
+      return { success: true }
+    }
+  }
+}

package/src/execution/engine/tools/platform/acquisition/contact-tools.ts

@@ -0,0 +1,319 @@
+/**
+ * Contact Platform Tools
+ *
+ * Platform tools for contact CRUD operations in the acquisition domain.
+ * Used by AI agents to manage contact records with multi-tenant isolation.
+ *
+ * All operations require organizationId from ExecutionContext for RLS enforcement.
+ */
+
+import { getToolServices } from '../../registry'
+import { serviceUnavailable } from '../../types'
+import type { Tool } from '../../types'
+import {
+  CreateContactInputSchema,
+  UpdateContactInputSchema,
+  UpsertContactInputSchema,
+  GetContactInputSchema,
+  ListContactsInputSchema,
+  DeleteContactInputSchema,
+  BulkImportInputSchema,
+  ContactOutputSchema,
+  PaginatedContactsOutputSchema,
+  BulkImportResultSchema,
+  DeleteResultSchema,
+  DeactivateContactsByCompanyInputSchema,
+  DeactivateContactsByCompanyResultSchema
+} from './types'
+
+/**
+ * Transform contact result to output format
+ * Converts Date objects to ISO strings for JSON serialization
+ */
+function toContactOutput(result: any) {
+  return {
+    id: result.id,
+    organizationId: result.organizationId,
+    companyId: result.companyId,
+    email: result.email,
+    emailValid: result.emailValid,
+    firstName: result.firstName,
+    lastName: result.lastName,
+    linkedinUrl: result.linkedinUrl,
+    title: result.title,
+    headline: result.headline,
+    filterReason: result.filterReason,
+    openingLine: result.openingLine,
+    source: result.source,
+    sourceId: result.sourceId,
+    pipelineStatus: result.pipelineStatus,
+    enrichmentData: result.enrichmentData,
+    tags: result.tags,
+    batchId: result.batchId ?? null,
+    status: result.status ?? 'active',
+    createdAt: result.createdAt instanceof Date ? result.createdAt.toISOString() : result.createdAt,
+    updatedAt: result.updatedAt instanceof Date ? result.updatedAt.toISOString() : result.updatedAt
+  }
+}
+
+/**
+ * Create a new contact record
+ *
+ * @returns Tool for creating contacts
+ */
+export function createAcqContactCreateTool(): Tool {
+  return {
+    name: 'acq_contact_create',
+    description: 'Create a new contact record.',
+    inputSchema: CreateContactInputSchema,
+    outputSchema: ContactOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const validated = input as {
+        email: string
+        companyId?: string
+        firstName?: string
+        lastName?: string
+        linkedinUrl?: string
+        title?: string
+        source?: string
+        sourceId?: string
+        batchId?: string
+      }
+
+      const result = await leadService.createContact({
+        organizationId: executionContext.organizationId,
+        ...validated
+      })
+
+      return toContactOutput(result)
+    }
+  }
+}
+
+/**
+ * Update an existing contact with new data
+ *
+ * @returns Tool for updating contacts (enrichment, personalization, campaign status)
+ */
+export function createAcqContactUpdateTool(): Tool {
+  return {
+    name: 'acq_contact_update',
+    description: 'Update an existing contact with new data (enrichment, personalization, campaign status).',
+    inputSchema: UpdateContactInputSchema,
+    outputSchema: ContactOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { id, ...params } = input as { id: string; [key: string]: unknown }
+      const result = await leadService.updateContact(id, params)
+
+      return toContactOutput(result)
+    }
+  }
+}
+
+/**
+ * Upsert a contact by email
+ *
+ * @returns Tool for upserting contacts (creates new or updates existing by email)
+ */
+export function createAcqContactUpsertTool(): Tool {
+  return {
+    name: 'acq_contact_upsert',
+    description: 'Upsert a contact by email. Creates new contact if email does not exist, otherwise updates existing.',
+    inputSchema: UpsertContactInputSchema,
+    outputSchema: ContactOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const validated = input as {
+        email: string
+        companyId?: string
+        firstName?: string
+        lastName?: string
+        linkedinUrl?: string
+        title?: string
+        source?: string
+        sourceId?: string
+        batchId?: string
+      }
+
+      const result = await leadService.upsertContact({
+        organizationId: executionContext.organizationId,
+        ...validated
+      })
+
+      return toContactOutput(result)
+    }
+  }
+}
+
+/**
+ * Get a single contact by ID
+ *
+ * @returns Tool for retrieving a contact by ID
+ */
+export function createAcqContactGetTool(): Tool {
+  return {
+    name: 'acq_contact_get',
+    description: 'Get a single contact by ID.',
+    inputSchema: GetContactInputSchema,
+    outputSchema: ContactOutputSchema.nullable(),
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { id } = input as { id: string }
+      const result = await leadService.getContact(id, executionContext.organizationId)
+      return result ? toContactOutput(result) : null
+    }
+  }
+}
+
+/**
+ * List contacts with filters and pagination
+ *
+ * @returns Tool for listing contacts with optional filters (list, qualification, campaign)
+ */
+export function createAcqContactListTool(): Tool {
+  return {
+    name: 'acq_contact_list',
+    description: 'List contacts with optional filters (list, qualification, campaign) and pagination.',
+    inputSchema: ListContactsInputSchema,
+    outputSchema: PaginatedContactsOutputSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { limit, offset, ...filters } = input as {
+        limit?: number
+        offset?: number
+        openingLineIsNull?: boolean
+        batchId?: string
+        contactStatus?: 'active' | 'invalid'
+      }
+      const result = await leadService.listContacts(executionContext.organizationId, filters, {
+        limit: limit ?? 100,
+        offset: offset ?? 0
+      })
+
+      return {
+        data: result.data.map(toContactOutput),
+        total: result.total,
+        limit: result.limit,
+        offset: result.offset
+      }
+    }
+  }
+}
+
+/**
+ * Delete a contact record
+ *
+ * @returns Tool for deleting contacts
+ */
+export function createAcqContactDeleteTool(): Tool {
+  return {
+    name: 'acq_contact_delete',
+    description: 'Delete a contact record.',
+    inputSchema: DeleteContactInputSchema,
+    outputSchema: DeleteResultSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { id } = input as { id: string }
+      await leadService.deleteContact(id, executionContext.organizationId)
+      return { success: true }
+    }
+  }
+}
+
+/**
+ * Batch import contacts with automatic deduplication
+ *
+ * @returns Tool for bulk importing contacts (creates new or updates existing by email)
+ */
+export function createAcqContactBulkImportTool(): Tool {
+  return {
+    name: 'acq_contact_bulk_import',
+    description:
+      'Batch import contacts with automatic deduplication. Creates new contacts or updates existing by email.',
+    inputSchema: BulkImportInputSchema,
+    outputSchema: BulkImportResultSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { contacts } = input as {
+        contacts: Array<{
+          email: string
+          companyId?: string
+          firstName?: string
+          lastName?: string
+          linkedinUrl?: string
+          title?: string
+          source?: string
+          sourceId?: string
+          batchId?: string
+        }>
+      }
+
+      const result = await leadService.bulkImportContacts({
+        organizationId: executionContext.organizationId,
+        contacts: contacts.map((c) => ({
+          organizationId: executionContext.organizationId,
+          ...c
+        }))
+      })
+
+      return result
+    }
+  }
+}
+
+/**
+ * Deactivate all active contacts belonging to a company.
+ * Used by qualification workflow to cascade company disqualification.
+ *
+ * @returns Tool for bulk deactivating contacts by company
+ */
+export function createAcqContactDeactivateByCompanyTool(): Tool {
+  return {
+    name: 'acq_contact_deactivate_by_company',
+    description: 'Deactivate all active contacts belonging to a company. Used to cascade company disqualification.',
+    inputSchema: DeactivateContactsByCompanyInputSchema,
+    outputSchema: DeactivateContactsByCompanyResultSchema,
+    execute: async ({ input, executionContext }) => {
+      const leadService = getToolServices().leadService
+      if (!leadService) throw serviceUnavailable('LeadService')
+      if (!executionContext?.organizationId)
+        throw serviceUnavailable('ExecutionContext', { reason: 'organizationId required for multi-tenant isolation' })
+
+      const { companyId } = input as { companyId: string }
+      return leadService.deactivateContactsByCompany({
+        organizationId: executionContext.organizationId,
+        companyId
+      })
+    }
+  }
+}

package/src/execution/engine/tools/platform/acquisition/index.ts

@@ -0,0 +1,43 @@
+/**
+ * Acquisition Platform Tools
+ * Tools for managing leads, companies, and contacts in the acquisition database.
+ *
+ * These tools are used by agents and workflows for:
+ * - Organizing contacts into lists
+ * - Managing company records and enrichment
+ * - Tracking contact personalization and campaigns
+ * - Bulk importing leads
+ */
+
+// Export all types and schemas
+export * from './types'
+
+// List tools
+export {
+  createAcqListCreateTool,
+  createAcqListUpdateTool,
+  createAcqListDeleteTool,
+  createAcqListListTool
+} from './list-tools'
+
+// Company tools
+export {
+  createAcqCompanyCreateTool,
+  createAcqCompanyUpdateTool,
+  createAcqCompanyUpsertTool,
+  createAcqCompanyGetTool,
+  createAcqCompanyListTool,
+  createAcqCompanyDeleteTool
+} from './company-tools'
+
+// Contact tools
+export {
+  createAcqContactCreateTool,
+  createAcqContactUpdateTool,
+  createAcqContactUpsertTool,
+  createAcqContactGetTool,
+  createAcqContactListTool,
+  createAcqContactDeleteTool,
+  createAcqContactBulkImportTool,
+  createAcqContactDeactivateByCompanyTool
+} from './contact-tools'