@elevasis/core 0.7.1 → 0.8.0

package/src/business/acquisition/types.ts

@@ -1,402 +1,402 @@
-import type { Database } from '../../supabase/database.types'
-
-// =============================================================================
-// Supabase-Generated Types (Re-exported from database.types)
-// =============================================================================
-
-/** Raw database row type for acq_lists table */
-export type AcqListRow = Database['public']['Tables']['acq_lists']['Row']
-/** Insert type for acq_lists table */
-export type AcqListInsert = Database['public']['Tables']['acq_lists']['Insert']
-
-/** Raw database row type for acq_companies table */
-export type AcqCompanyRow = Database['public']['Tables']['acq_companies']['Row']
-/** Insert type for acq_companies table */
-export type AcqCompanyInsert = Database['public']['Tables']['acq_companies']['Insert']
-
-/** Raw database row type for acq_contacts table */
-export type AcqContactRow = Database['public']['Tables']['acq_contacts']['Row']
-/** Insert type for acq_contacts table */
-export type AcqContactInsert = Database['public']['Tables']['acq_contacts']['Insert']
-
-/** Raw database row type for acq_deals table */
-export type AcqDealRow = Database['public']['Tables']['acq_deals']['Row']
-/** Insert type for acq_deals table */
-export type AcqDealInsert = Database['public']['Tables']['acq_deals']['Insert']
-
-/** Raw database row type for acq_deal_tasks table */
-export type AcqDealTaskRow = Database['public']['Tables']['acq_deal_tasks']['Row']
-/** Insert type for acq_deal_tasks table */
-export type AcqDealTaskInsert = Database['public']['Tables']['acq_deal_tasks']['Insert']
-
-// =============================================================================
-// Supporting Types
-// =============================================================================
-
-/**
- * Represents a web post from company website scraping.
- * Used for recent blog posts, news, or announcements.
- */
-export interface WebPost {
-  /** ISO date string of when the post was published */
-  date: string
-  /** Title of the web post */
-  title: string
-  /** Brief summary of the post content */
-  summary: string
-  /** AI-generated insight about the post's relevance */
-  aiInsight?: string
-}
-
-/**
- * Tracks pipeline status for a company across all processing stages.
- */
-export interface CompanyPipelineStatus {
-  acquired: boolean
-  enrichment: {
-    [source: string]: {
-      status: 'pending' | 'complete' | 'failed' | 'skipped'
-      completedAt?: string
-      error?: string
-    }
-  }
-}
-
-/**
- * Tracks pipeline status for a contact across all processing stages.
- */
-export interface ContactPipelineStatus {
-  enrichment: {
-    [source: string]: {
-      status: 'pending' | 'complete' | 'failed' | 'skipped'
-      completedAt?: string
-      error?: string
-    }
-  }
-  personalization: {
-    status: 'pending' | 'complete' | 'failed' | 'skipped'
-    completedAt?: string
-  }
-  outreach: {
-    status: 'pending' | 'sent' | 'replied' | 'bounced' | 'opted-out'
-    sentAt?: string
-    channel?: string
-    campaignId?: string
-  }
-}
-
-/**
- * Enrichment data collected for a company from various sources.
- */
-export interface CompanyEnrichmentData {
-  googleMaps?: {
-    placeId?: string
-    totalScore?: number
-    reviewsCount?: number
-    address?: string
-    phone?: string
-    categoryName?: string
-    googleMapsUrl?: string
-    scrapedAt?: string
-  }
-  websiteCrawl?: {
-    companyDescription?: string
-    services?: string[]
-    specialties?: string[]
-    staff?: Array<{ name: string; title?: string; email?: string }>
-    automationGaps?: string[]
-    targetAudience?: string
-    category?: string
-    segment?: string
-    recentWin?: string
-    emailCount?: number
-    pageCount?: number
-    totalChars?: number
-    crawledAt?: string
-    extractedAt?: string
-  }
-  website?: {
-    missionVision?: string
-    uniqueAttributes?: string
-    coreOfferings?: string
-    targetAudience?: string
-    companyValues?: string
-    businessDescription?: string
-    recentPosts?: Array<{ date?: string; title?: string; summary?: string; aiInsight?: string }>
-  }
-  tomba?: {
-    waterfallEmail?: {
-      email: string
-      name?: string
-      title?: string
-      department?: string
-    } | null
-    genericEmail?: string | null
-    totalFound?: number
-    searchedAt?: string
-  }
-}
-
-/**
- * Enrichment data collected for a contact from various sources.
- */
-export interface ContactEnrichmentData {
-  linkedin?: {
-    summary?: string
-    pastExperience?: string
-    education?: string
-    activity?: Array<{ date?: string; content?: string }>
-  }
-}
-
-// =============================================================================
-// Domain Types (camelCase transformations of database rows)
-// =============================================================================
-
-/**
- * Acquisition list for organizing contacts and companies.
- * Transformed from AcqListRow with camelCase properties.
- */
-export interface AcqList {
-  id: string
-  organizationId: string
-  name: string
-  description: string | null
-  type: string
-  batchIds: string[]
-  instantlyCampaignId: string | null
-  status: string
-  metadata: Record<string, unknown>
-  launchedAt: Date | null
-  completedAt: Date | null
-  createdAt: Date
-  config: ListConfig
-}
-
-/**
- * Company record in the acquisition database.
- * Contains enriched company data from various sources.
- * Transformed from AcqCompanyRow with camelCase properties.
- */
-export interface AcqCompany {
-  id: string
-  organizationId: string
-  name: string
-  domain: string | null
-  linkedinUrl: string | null
-  website: string | null
-  numEmployees: number | null
-  foundedYear: number | null
-  locationCity: string | null
-  locationState: string | null
-  category: string | null
-  categoryPain: string | null
-  segment: string | null
-  pipelineStatus: CompanyPipelineStatus | null
-  enrichmentData: CompanyEnrichmentData | null
-  source: string | null
-  batchId: string | null
-  status: 'active' | 'invalid'
-  verticalResearch: string | null
-  createdAt: Date
-  updatedAt: Date
-}
-
-/**
- * Contact record in the acquisition database.
- * Contains enriched contact data and personalization content.
- * Transformed from AcqContactRow with camelCase properties.
- */
-export interface AcqContact {
-  id: string
-  organizationId: string
-  companyId: string | null
-  email: string
-  emailValid: 'VALID' | 'INVALID' | 'RISKY' | 'UNKNOWN' | null
-  firstName: string | null
-  lastName: string | null
-  linkedinUrl: string | null
-  title: string | null
-  headline: string | null
-  filterReason: string | null
-  openingLine: string | null
-  source: string | null
-  sourceId: string | null
-  pipelineStatus: ContactPipelineStatus | null
-  enrichmentData: ContactEnrichmentData | null
-  /** Attio Person record ID - set when contact responds and is added to CRM */
-  attioPersonId: string | null
-  batchId: string | null
-  status: 'active' | 'invalid'
-  createdAt: Date
-  updatedAt: Date
-}
-
-// ─── Deal UI Types ───────────────────────────────────────────────────────────
-
-export type DealStage = 'interested' | 'proposal' | 'closing' | 'closed_won' | 'closed_lost' | 'nurturing'
-
-export interface KanbanStageConfig {
-  color: string // Mantine color token (e.g. 'blue', 'teal')
-  label?: string // Optional display label override
-}
-
-export type KanbanBoardConfig = Partial<Record<DealStage, KanbanStageConfig>>
-
-export interface DealContact {
-  id: string
-  first_name: string | null
-  last_name: string | null
-  email: string
-  title: string | null
-  headline: string | null
-  linkedin_url: string | null
-  pipeline_status: Record<string, unknown> | null
-  enrichment_data: Record<string, unknown> | null
-  company: {
-    id: string
-    name: string
-    domain: string | null
-    website: string | null
-    linkedin_url: string | null
-    segment: string | null
-    category: string | null
-    num_employees: number | null
-  } | null
-}
-
-export interface DealFilters {
-  stage?: DealStage
-  search?: string
-  limit?: number
-  offset?: number
-}
-
-/** Deal list item with joined contact and company data */
-export interface DealListItem extends AcqDealRow {
-  contact: DealContact | null
-}
-
-export type DealDetail = DealListItem
-
-/** Task kind options for a deal task (human follow-up action type) */
-export type AcqDealTaskKind = 'call' | 'email' | 'meeting' | 'other'
-
-/**
- * A CRM to-do item attached to a deal representing a human follow-up action.
- * Transformed from AcqDealTaskRow with camelCase properties.
- */
-export interface AcqDealTask {
-  id: string
-  organizationId: string
-  dealId: string
-  title: string
-  description: string | null
-  kind: AcqDealTaskKind
-  dueAt: string | null
-  assigneeUserId: string | null
-  completedAt: string | null
-  completedByUserId: string | null
-  createdAt: string
-  updatedAt: string
-  createdByUserId: string | null
-}
-
-// ─── List Config / Progress / Telemetry Types ────────────────────────────────
-
-/**
- * One ordered step in a list's pipeline. Maps to a deployed workflow
- * (e.g. 'lgn-03-company-qualification-workflow'). The `inputTemplate`
- * is merged with `{ listId }` at run time to form the workflow input.
- */
-export interface PipelineStep {
-  /** Stable key, e.g. 'scrape' | 'extract' | 'qualify' | 'discover' | 'verify' | 'personalize'. */
-  key: string
-  /** Human label rendered in the UI stepper. */
-  label: string
-  /** Deployed workflow resourceId (e.g. 'lgn-03-company-qualification-workflow'). */
-  resourceId: string
-  /** Input defaults merged with `{ listId }` at dispatch. */
-  inputTemplate: Record<string, unknown>
-  /** Whether the UI shows the Run button. */
-  enabled: boolean
-  /** Display order (ascending). */
-  order: number
-}
-
-export type CompanyListStage = 'populated' | 'extracted' | 'qualified'
-
-export type ContactListStage = 'discovered' | 'verified' | 'personalized' | 'uploaded'
-
-/**
- * Per-list pipeline configuration stored as jsonb in `acq_lists.config`.
- *
- * `qualification` is the only required subtree. Every other subtree is optional
- * and inherits global defaults when omitted: workflows resolve values as
- * `list.config.foo ?? globalDefaults.foo`. Seeded rows from
- * `20260413000100_backfill_list_configs.sql` only populate `qualification`
- * and `scraping`; the rest was intentionally omitted.
- */
-export interface ListConfig {
-  qualification: {
-    /** One-line description of the target vertical/segment. */
-    targetDescription: string
-    /** Minimum Google review count to qualify. */
-    minReviewCount: number
-    /** Minimum Google star rating to qualify (e.g. 3.0). */
-    minRating: number
-    /** Whether to exclude franchises/chains during qualification. */
-    excludeFranchises: boolean
-    /** Free-form LLM rules layered on top of the structured criteria. */
-    customRules: string
-  }
-  enrichment?: {
-    emailDiscovery?: {
-      primary: 'tomba' | 'anymailfinder'
-      credentialName?: string
-    }
-    emailVerification?: {
-      provider: 'millionverifier'
-      threshold?: 'ok' | 'ok+catch_all'
-    }
-  }
-  personalization?: {
-    industryContext?: string
-    /** Email body template with tags like {{opening_line}} / {{category_pain}}. */
-    emailBody?: string
-    creativeDirection?: string
-    /** Contradiction-prevention rules layered into the personalization prompt. */
-    exclusionRules?: string[]
-  }
-  pipeline?: {
-    steps: PipelineStep[]
-  }
-}
-
-/**
- * Live-scan aggregate telemetry for a single list, computed on demand from
- * the list junction tables and current contact deliverability state.
- */
-export interface ListTelemetry {
-  listId: string
-  totalCompanies: number
-  totalContacts: number
-  stageCounts: {
-    populated: number
-    extracted: number
-    qualified: number
-    discovered: number
-    verified: number
-    personalized: number
-    uploaded: number
-  }
-  deliverability: {
-    valid: number
-    risky: number
-    invalid: number
-    unknown: number
-    bounced: number
-  }
-  /** Reserved -- active workflow IDs associated with this list. */
-  activeWorkflows?: string[]
-}
+import type { Database } from '../../supabase/database.types'
+
+// =============================================================================
+// Supabase-Generated Types (Re-exported from database.types)
+// =============================================================================
+
+/** Raw database row type for acq_lists table */
+export type AcqListRow = Database['public']['Tables']['acq_lists']['Row']
+/** Insert type for acq_lists table */
+export type AcqListInsert = Database['public']['Tables']['acq_lists']['Insert']
+
+/** Raw database row type for acq_companies table */
+export type AcqCompanyRow = Database['public']['Tables']['acq_companies']['Row']
+/** Insert type for acq_companies table */
+export type AcqCompanyInsert = Database['public']['Tables']['acq_companies']['Insert']
+
+/** Raw database row type for acq_contacts table */
+export type AcqContactRow = Database['public']['Tables']['acq_contacts']['Row']
+/** Insert type for acq_contacts table */
+export type AcqContactInsert = Database['public']['Tables']['acq_contacts']['Insert']
+
+/** Raw database row type for acq_deals table */
+export type AcqDealRow = Database['public']['Tables']['acq_deals']['Row']
+/** Insert type for acq_deals table */
+export type AcqDealInsert = Database['public']['Tables']['acq_deals']['Insert']
+
+/** Raw database row type for acq_deal_tasks table */
+export type AcqDealTaskRow = Database['public']['Tables']['acq_deal_tasks']['Row']
+/** Insert type for acq_deal_tasks table */
+export type AcqDealTaskInsert = Database['public']['Tables']['acq_deal_tasks']['Insert']
+
+// =============================================================================
+// Supporting Types
+// =============================================================================
+
+/**
+ * Represents a web post from company website scraping.
+ * Used for recent blog posts, news, or announcements.
+ */
+export interface WebPost {
+  /** ISO date string of when the post was published */
+  date: string
+  /** Title of the web post */
+  title: string
+  /** Brief summary of the post content */
+  summary: string
+  /** AI-generated insight about the post's relevance */
+  aiInsight?: string
+}
+
+/**
+ * Tracks pipeline status for a company across all processing stages.
+ */
+export interface CompanyPipelineStatus {
+  acquired: boolean
+  enrichment: {
+    [source: string]: {
+      status: 'pending' | 'complete' | 'failed' | 'skipped'
+      completedAt?: string
+      error?: string
+    }
+  }
+}
+
+/**
+ * Tracks pipeline status for a contact across all processing stages.
+ */
+export interface ContactPipelineStatus {
+  enrichment: {
+    [source: string]: {
+      status: 'pending' | 'complete' | 'failed' | 'skipped'
+      completedAt?: string
+      error?: string
+    }
+  }
+  personalization: {
+    status: 'pending' | 'complete' | 'failed' | 'skipped'
+    completedAt?: string
+  }
+  outreach: {
+    status: 'pending' | 'sent' | 'replied' | 'bounced' | 'opted-out'
+    sentAt?: string
+    channel?: string
+    campaignId?: string
+  }
+}
+
+/**
+ * Enrichment data collected for a company from various sources.
+ */
+export interface CompanyEnrichmentData {
+  googleMaps?: {
+    placeId?: string
+    totalScore?: number
+    reviewsCount?: number
+    address?: string
+    phone?: string
+    categoryName?: string
+    googleMapsUrl?: string
+    scrapedAt?: string
+  }
+  websiteCrawl?: {
+    companyDescription?: string
+    services?: string[]
+    specialties?: string[]
+    staff?: Array<{ name: string; title?: string; email?: string }>
+    automationGaps?: string[]
+    targetAudience?: string
+    category?: string
+    segment?: string
+    recentWin?: string
+    emailCount?: number
+    pageCount?: number
+    totalChars?: number
+    crawledAt?: string
+    extractedAt?: string
+  }
+  website?: {
+    missionVision?: string
+    uniqueAttributes?: string
+    coreOfferings?: string
+    targetAudience?: string
+    companyValues?: string
+    businessDescription?: string
+    recentPosts?: Array<{ date?: string; title?: string; summary?: string; aiInsight?: string }>
+  }
+  tomba?: {
+    waterfallEmail?: {
+      email: string
+      name?: string
+      title?: string
+      department?: string
+    } | null
+    genericEmail?: string | null
+    totalFound?: number
+    searchedAt?: string
+  }
+}
+
+/**
+ * Enrichment data collected for a contact from various sources.
+ */
+export interface ContactEnrichmentData {
+  linkedin?: {
+    summary?: string
+    pastExperience?: string
+    education?: string
+    activity?: Array<{ date?: string; content?: string }>
+  }
+}
+
+// =============================================================================
+// Domain Types (camelCase transformations of database rows)
+// =============================================================================
+
+/**
+ * Acquisition list for organizing contacts and companies.
+ * Transformed from AcqListRow with camelCase properties.
+ */
+export interface AcqList {
+  id: string
+  organizationId: string
+  name: string
+  description: string | null
+  type: string
+  batchIds: string[]
+  instantlyCampaignId: string | null
+  status: string
+  metadata: Record<string, unknown>
+  launchedAt: Date | null
+  completedAt: Date | null
+  createdAt: Date
+  config: ListConfig
+}
+
+/**
+ * Company record in the acquisition database.
+ * Contains enriched company data from various sources.
+ * Transformed from AcqCompanyRow with camelCase properties.
+ */
+export interface AcqCompany {
+  id: string
+  organizationId: string
+  name: string
+  domain: string | null
+  linkedinUrl: string | null
+  website: string | null
+  numEmployees: number | null
+  foundedYear: number | null
+  locationCity: string | null
+  locationState: string | null
+  category: string | null
+  categoryPain: string | null
+  segment: string | null
+  pipelineStatus: CompanyPipelineStatus | null
+  enrichmentData: CompanyEnrichmentData | null
+  source: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  verticalResearch: string | null
+  createdAt: Date
+  updatedAt: Date
+}
+
+/**
+ * Contact record in the acquisition database.
+ * Contains enriched contact data and personalization content.
+ * Transformed from AcqContactRow with camelCase properties.
+ */
+export interface AcqContact {
+  id: string
+  organizationId: string
+  companyId: string | null
+  email: string
+  emailValid: 'VALID' | 'INVALID' | 'RISKY' | 'UNKNOWN' | null
+  firstName: string | null
+  lastName: string | null
+  linkedinUrl: string | null
+  title: string | null
+  headline: string | null
+  filterReason: string | null
+  openingLine: string | null
+  source: string | null
+  sourceId: string | null
+  pipelineStatus: ContactPipelineStatus | null
+  enrichmentData: ContactEnrichmentData | null
+  /** Attio Person record ID - set when contact responds and is added to CRM */
+  attioPersonId: string | null
+  batchId: string | null
+  status: 'active' | 'invalid'
+  createdAt: Date
+  updatedAt: Date
+}
+
+// ─── Deal UI Types ───────────────────────────────────────────────────────────
+
+export type DealStage = 'interested' | 'proposal' | 'closing' | 'closed_won' | 'closed_lost' | 'nurturing'
+
+export interface KanbanStageConfig {
+  color: string // Mantine color token (e.g. 'blue', 'teal')
+  label?: string // Optional display label override
+}
+
+export type KanbanBoardConfig = Partial<Record<DealStage, KanbanStageConfig>>
+
+export interface DealContact {
+  id: string
+  first_name: string | null
+  last_name: string | null
+  email: string
+  title: string | null
+  headline: string | null
+  linkedin_url: string | null
+  pipeline_status: Record<string, unknown> | null
+  enrichment_data: Record<string, unknown> | null
+  company: {
+    id: string
+    name: string
+    domain: string | null
+    website: string | null
+    linkedin_url: string | null
+    segment: string | null
+    category: string | null
+    num_employees: number | null
+  } | null
+}
+
+export interface DealFilters {
+  stage?: DealStage
+  search?: string
+  limit?: number
+  offset?: number
+}
+
+/** Deal list item with joined contact and company data */
+export interface DealListItem extends AcqDealRow {
+  contact: DealContact | null
+}
+
+export type DealDetail = DealListItem
+
+/** Task kind options for a deal task (human follow-up action type) */
+export type AcqDealTaskKind = 'call' | 'email' | 'meeting' | 'other'
+
+/**
+ * A CRM to-do item attached to a deal representing a human follow-up action.
+ * Transformed from AcqDealTaskRow with camelCase properties.
+ */
+export interface AcqDealTask {
+  id: string
+  organizationId: string
+  dealId: string
+  title: string
+  description: string | null
+  kind: AcqDealTaskKind
+  dueAt: string | null
+  assigneeUserId: string | null
+  completedAt: string | null
+  completedByUserId: string | null
+  createdAt: string
+  updatedAt: string
+  createdByUserId: string | null
+}
+
+// ─── List Config / Progress / Telemetry Types ────────────────────────────────
+
+/**
+ * One ordered step in a list's pipeline. Maps to a deployed workflow
+ * (e.g. 'lgn-03-company-qualification-workflow'). The `inputTemplate`
+ * is merged with `{ listId }` at run time to form the workflow input.
+ */
+export interface PipelineStep {
+  /** Stable key, e.g. 'scrape' | 'extract' | 'qualify' | 'discover' | 'verify' | 'personalize'. */
+  key: string
+  /** Human label rendered in the UI stepper. */
+  label: string
+  /** Deployed workflow resourceId (e.g. 'lgn-03-company-qualification-workflow'). */
+  resourceId: string
+  /** Input defaults merged with `{ listId }` at dispatch. */
+  inputTemplate: Record<string, unknown>
+  /** Whether the UI shows the Run button. */
+  enabled: boolean
+  /** Display order (ascending). */
+  order: number
+}
+
+export type CompanyListStage = 'populated' | 'extracted' | 'qualified'
+
+export type ContactListStage = 'discovered' | 'verified' | 'personalized' | 'uploaded'
+
+/**
+ * Per-list pipeline configuration stored as jsonb in `acq_lists.config`.
+ *
+ * `qualification` is the only required subtree. Every other subtree is optional
+ * and inherits global defaults when omitted: workflows resolve values as
+ * `list.config.foo ?? globalDefaults.foo`. Seeded rows from
+ * `20260413000100_backfill_list_configs.sql` only populate `qualification`
+ * and `scraping`; the rest was intentionally omitted.
+ */
+export interface ListConfig {
+  qualification: {
+    /** One-line description of the target vertical/segment. */
+    targetDescription: string
+    /** Minimum Google review count to qualify. */
+    minReviewCount: number
+    /** Minimum Google star rating to qualify (e.g. 3.0). */
+    minRating: number
+    /** Whether to exclude franchises/chains during qualification. */
+    excludeFranchises: boolean
+    /** Free-form LLM rules layered on top of the structured criteria. */
+    customRules: string
+  }
+  enrichment?: {
+    emailDiscovery?: {
+      primary: 'tomba' | 'anymailfinder'
+      credentialName?: string
+    }
+    emailVerification?: {
+      provider: 'millionverifier'
+      threshold?: 'ok' | 'ok+catch_all'
+    }
+  }
+  personalization?: {
+    industryContext?: string
+    /** Email body template with tags like {{opening_line}} / {{category_pain}}. */
+    emailBody?: string
+    creativeDirection?: string
+    /** Contradiction-prevention rules layered into the personalization prompt. */
+    exclusionRules?: string[]
+  }
+  pipeline?: {
+    steps: PipelineStep[]
+  }
+}
+
+/**
+ * Live-scan aggregate telemetry for a single list, computed on demand from
+ * the list junction tables and current contact deliverability state.
+ */
+export interface ListTelemetry {
+  listId: string
+  totalCompanies: number
+  totalContacts: number
+  stageCounts: {
+    populated: number
+    extracted: number
+    qualified: number
+    discovered: number
+    verified: number
+    personalized: number
+    uploaded: number
+  }
+  deliverability: {
+    valid: number
+    risky: number
+    invalid: number
+    unknown: number
+    bounced: number
+  }
+  /** Reserved -- active workflow IDs associated with this list. */
+  activeWorkflows?: string[]
+}