@elevasis/core 0.13.0 → 0.14.0

package/src/business/acquisition/derive-actions.ts

@@ -1,90 +1,103 @@
-import type { AcqDealRow } from './types'
-
-export interface Action {
-  key: string
-  label: string
-  kind: 'transition' | 'edit' | 'modal'
-  payload?: Record<string, unknown>
-}
-
-// Stage order inlined from DEFAULT_ORGANIZATION_MODEL_SALES (single caller).
-// Update here if the default pipeline changes.
-const STAGE_ORDER = ['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'] as const
-
-type DefaultStageKey = (typeof STAGE_ORDER)[number]
-
-function isDefaultStage(key: string | null | undefined): key is DefaultStageKey {
-  return STAGE_ORDER.includes(key as DefaultStageKey)
-}
-
-function transitionAction(stageKey: DefaultStageKey): Action {
-  const labels: Record<DefaultStageKey, string> = {
-    interested: 'Move to Interested',
-    proposal: 'Move to Proposal',
-    closing: 'Move to Closing',
-    closed_won: 'Close Won',
-    closed_lost: 'Close Lost',
-    nurturing: 'Move to Nurturing'
-  }
-  return {
-    key: `move_to_${stageKey}`,
-    label: labels[stageKey],
-    kind: 'transition',
-    payload: { stageKey }
-  }
-}
-
-function interestedActions(stateKey: string | null | undefined): Action[] {
-  const base: Action[] = [transitionAction('proposal'), transitionAction('closed_lost'), transitionAction('nurturing')]
-
-  if (stateKey === 'discovery_replied') {
-    return [...base, { key: 'send_link', label: 'Send Booking Link', kind: 'modal' }]
-  }
-
-  if (stateKey === 'discovery_link_sent') {
-    return [...base, { key: 'send_nudge', label: 'Send Nudge', kind: 'modal' }]
-  }
-
-  if (stateKey === 'discovery_nudging') {
-    return [
-      ...base,
-      { key: 'send_nudge', label: 'Send Nudge', kind: 'modal' },
-      { key: 'mark_no_show', label: 'Mark No-Show', kind: 'transition' }
-    ]
-  }
-
-  if (stateKey === 'discovery_booking_cancelled') {
-    return [...base, { key: 'rebook', label: 'Rebook', kind: 'modal' }]
-  }
-
-  return base
-}
-
-function proposalActions(): Action[] {
-  return [transitionAction('closing'), transitionAction('closed_lost'), transitionAction('nurturing')]
-}
-
-function closingActions(): Action[] {
-  return [transitionAction('closed_won'), transitionAction('closed_lost'), transitionAction('nurturing')]
-}
-
-export function deriveActions(deal: AcqDealRow): Action[] {
-  const stage = deal.stage_key
-
-  if (!isDefaultStage(stage)) {
-    return []
-  }
-
-  switch (stage) {
-    case 'interested':
-      return interestedActions(deal.state_key)
-    case 'proposal':
-      return proposalActions()
-    case 'closing':
-      return closingActions()
-    case 'closed_won':
-    case 'closed_lost':
-    case 'nurturing':
-      return []
-  }
-}
+import { z } from 'zod'
+import type { AcqDealRow } from './types'
+
+export interface Action {
+  key: string
+  label: string
+  payloadSchema?: z.ZodTypeAny
+}
+
+export interface ActionDef {
+  key: string
+  label: string
+  isAvailableFor: (deal: AcqDealRow) => boolean
+  workflowId: string
+  payloadSchema?: z.ZodTypeAny
+}
+
+export const SendReplyActionPayloadSchema = z
+  .object({
+    replyBody: z.string().trim().min(1).max(10000)
+  })
+  .strict()
+
+export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
+  {
+    key: 'move_to_proposal',
+    label: 'Move to Proposal',
+    isAvailableFor: (deal) => deal.stage_key === 'interested',
+    workflowId: 'move_to_proposal-workflow'
+  },
+  {
+    key: 'move_to_closing',
+    label: 'Move to Closing',
+    isAvailableFor: (deal) => deal.stage_key === 'proposal',
+    workflowId: 'move_to_closing-workflow'
+  },
+  {
+    key: 'move_to_closed_won',
+    label: 'Close Won',
+    isAvailableFor: (deal) => deal.stage_key === 'closing',
+    workflowId: 'move_to_closed_won-workflow'
+  },
+  {
+    key: 'move_to_closed_lost',
+    label: 'Close Lost',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' || deal.stage_key === 'proposal' || deal.stage_key === 'closing',
+    workflowId: 'move_to_closed_lost-workflow'
+  },
+  {
+    key: 'move_to_nurturing',
+    label: 'Move to Nurturing',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' || deal.stage_key === 'proposal' || deal.stage_key === 'closing',
+    workflowId: 'move_to_nurturing-workflow'
+  },
+  {
+    key: 'send_reply',
+    label: 'Send Reply',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' &&
+      (deal.state_key === 'discovery_replied' ||
+        deal.state_key === 'discovery_link_sent' ||
+        deal.state_key === 'discovery_nudging'),
+    workflowId: 'crm-send-reply-workflow',
+    payloadSchema: SendReplyActionPayloadSchema
+  },
+  {
+    key: 'send_link',
+    label: 'Send Booking Link',
+    isAvailableFor: (deal) => deal.stage_key === 'interested' && deal.state_key === 'discovery_replied',
+    workflowId: 'crm-send-booking-link-workflow'
+  },
+  {
+    key: 'send_nudge',
+    label: 'Send Nudge',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' &&
+      (deal.state_key === 'discovery_link_sent' || deal.state_key === 'discovery_nudging'),
+    workflowId: 'crm-send-nudge-workflow'
+  },
+  {
+    key: 'mark_no_show',
+    label: 'Mark No-Show',
+    isAvailableFor: (deal) => deal.stage_key === 'interested' && deal.state_key === 'discovery_nudging',
+    // Mirrors the auto-timeout precedent in operations/sales/crm/pipeline/timeout-actions.ts:
+    // both manual-click and timeout move the deal to closed_lost. The action_taken activity
+    // event captures operator intent and distinguishes the manual variant from the timed one.
+    workflowId: 'mark_no_show-workflow'
+  },
+  {
+    key: 'rebook',
+    label: 'Rebook',
+    isAvailableFor: (deal) => deal.stage_key === 'interested' && deal.state_key === 'discovery_booking_cancelled',
+    workflowId: 'crm-rebook-workflow'
+  }
+]
+
+export function deriveActions(deal: AcqDealRow, actions: ActionDef[] = DEFAULT_CRM_ACTIONS): Action[] {
+  return actions
+    .filter((a) => a.isAvailableFor(deal))
+    .map(({ key, label, payloadSchema }) => ({ key, label, payloadSchema }))
+}

package/src/business/acquisition/index.ts

@@ -1,111 +1,149 @@
-export * from './types'
-export * from './activity-events'
-export * from './derive-actions'
-// Export api-schemas selectively to avoid re-exporting names already defined in types.ts
-// (DealStage, AcqDealTaskKind are declared as union types there; api-schemas re-infers them from Zod)
-export {
-  AcqCompanyStatusSchema,
-  AcqContactStatusSchema,
-  AcqEmailValidSchema,
-  CompanyIdParamsSchema,
-  ContactIdParamsSchema,
-  ListCompaniesQuerySchema,
-  ListContactsQuerySchema,
-  CreateCompanyRequestSchema,
-  UpdateCompanyRequestSchema,
-  CreateContactRequestSchema,
-  UpdateContactRequestSchema,
-  AcqCompanyResponseSchema,
-  AcqCompanyListResponseSchema,
-  AcqContactResponseSchema,
-  AcqContactListResponseSchema,
-  AcqCompanySchemas,
-  AcqContactSchemas,
-  DealStageSchema,
-  AcqDealTaskKindSchema,
-  DealIdParamsSchema,
-  DealTaskIdParamsSchema,
-  ListDealsQuerySchema,
-  ListDealTasksDueQuerySchema,
-  CreateDealNoteRequestSchema,
-  CreateDealTaskRequestSchema,
-  TransitionItemRequestSchema,
-  DealContactSummarySchema,
-  DealListItemSchema,
-  DealListResponseSchema,
-  DealDetailResponseSchema,
-  DealNoteResponseSchema,
-  DealNoteListResponseSchema,
-  DealTaskResponseSchema,
-  DealTaskListResponseSchema,
-  DealSchemas,
-  ListQualificationSchema,
-  ListEnrichmentSchema,
-  ListPersonalizationSchema,
-  PipelineStepSchema,
-  ListPipelineSchema,
-  ListConfigSchema,
-  ListStageCountsSchema,
-  ListTelemetrySchema,
-  ListIdParamsSchema,
-  CreateListRequestSchema,
-  UpdateListRequestSchema,
-  UpdateListConfigRequestSchema,
-  AddCompaniesToListRequestSchema,
-  RemoveCompaniesFromListRequestSchema,
-  AddContactsToListRequestSchema,
-  RecordListExecutionRequestSchema,
-  AcqListResponseSchema,
-  AcqListListResponseSchema,
-  ListTelemetryResponseSchema,
-  ListTelemetryListResponseSchema,
-  ListExecutionSummarySchema,
-  ListExecutionsResponseSchema,
-  AcqListSchemas,
-  type CompanyIdParams,
-  type ContactIdParams,
-  type ListCompaniesQuery,
-  type ListContactsQuery,
-  type CreateCompanyRequest,
-  type UpdateCompanyRequest,
-  type CreateContactRequest,
-  type UpdateContactRequest,
-  type AcqCompanyResponse,
-  type AcqCompanyListResponse,
-  type AcqContactResponse,
-  type AcqContactListResponse,
-  type AcqCompanyStatus,
-  type AcqContactStatus,
-  type AcqEmailValid,
-  type DealIdParams,
-  type DealTaskIdParams,
-  type ListDealsQuery,
-  type ListDealTasksDueQuery,
-  type CreateDealNoteRequest,
-  type CreateDealTaskRequest,
-  type TransitionItemRequest,
-  type DealListResponse,
-  type DealDetailResponse,
-  type DealNoteResponse,
-  type DealNoteListResponse,
-  type DealTaskResponse,
-  type DealTaskListResponse,
-  type ListConfigInput,
-  type ListStageCountsInput,
-  type ListTelemetryInput,
-  type PipelineStepInput,
-  type ListIdParams,
-  type CreateListRequest,
-  type UpdateListRequest,
-  type UpdateListConfigRequest,
-  type AddCompaniesToListRequest,
-  type RemoveCompaniesFromListRequest,
-  type AddContactsToListRequest,
-  type RecordListExecutionRequest,
-  type AcqListResponse,
-  type AcqListListResponse,
-  type ListTelemetryResponse,
-  type ListTelemetryListResponse,
-  type ListExecutionSummaryInput,
-  type ListExecutionsResponse
-} from './api-schemas'
+export * from './types'
+export * from './activity-events'
+export * from './derive-actions'
+export * from './stateful'
+// Export api-schemas selectively to avoid re-exporting names already defined in types.ts
+// (DealStage, AcqDealTaskKind are declared as union types there; api-schemas re-infers them from Zod)
+export {
+  AcqCompanyStatusSchema,
+  AcqContactStatusSchema,
+  AcqEmailValidSchema,
+  CompanyIdParamsSchema,
+  ContactIdParamsSchema,
+  ListCompaniesQuerySchema,
+  ListContactsQuerySchema,
+  CreateCompanyRequestSchema,
+  UpdateCompanyRequestSchema,
+  CreateContactRequestSchema,
+  UpdateContactRequestSchema,
+  AcqCompanyResponseSchema,
+  AcqCompanyListResponseSchema,
+  AcqContactResponseSchema,
+  AcqContactListResponseSchema,
+  AcqCompanySchemas,
+  AcqContactSchemas,
+  DealStageSchema,
+  AcqDealTaskKindSchema,
+  DealIdParamsSchema,
+  DealTaskIdParamsSchema,
+  ListDealsQuerySchema,
+  ListDealTasksDueQuerySchema,
+  CreateDealNoteRequestSchema,
+  CreateDealTaskRequestSchema,
+  TransitionItemRequestSchema,
+  ExecuteActionParamsSchema,
+  ExecuteActionRequestSchema,
+  DealContactSummarySchema,
+  DealListItemSchema,
+  DealListResponseSchema,
+  DealDetailResponseSchema,
+  DealNoteResponseSchema,
+  DealNoteListResponseSchema,
+  DealTaskResponseSchema,
+  DealTaskListResponseSchema,
+  DealSchemas,
+  ListStatusSchema,
+  ScrapingConfigSchema,
+  IcpRubricSchema,
+  PipelineStageSchema,
+  PipelineConfigSchema,
+  ListStageCountsSchema,
+  ListTelemetrySchema,
+  ListIdParamsSchema,
+  CreateListRequestSchema,
+  UpdateListRequestSchema,
+  UpdateListStatusRequestSchema,
+  UpdateListConfigRequestSchema,
+  AddCompaniesToListRequestSchema,
+  RemoveCompaniesFromListRequestSchema,
+  AddContactsToListRequestSchema,
+  RecordListExecutionRequestSchema,
+  AcqListResponseSchema,
+  AcqListListResponseSchema,
+  ListTelemetryResponseSchema,
+  ListTelemetryListResponseSchema,
+  ListExecutionSummarySchema,
+  ListExecutionsResponseSchema,
+  ListStageProgressSchema,
+  ListProgressResponseSchema,
+  AcqListSchemas,
+  AcqSubstrateSchemas,
+  AcqArtifactOwnerKindSchema,
+  ListArtifactsQuerySchema,
+  CreateArtifactRequestSchema,
+  AcqArtifactResponseSchema,
+  AcqArtifactListResponseSchema,
+  ListMembersQuerySchema,
+  MemberIdParamsSchema,
+  AcqListMemberContactSummarySchema,
+  AcqListMemberResponseSchema,
+  AcqListMembersResponseSchema,
+  ListCompanyIdParamsSchema,
+  AcqListCompanyResponseSchema,
+  type AcqArtifactOwnerKind,
+  type ListArtifactsQuery,
+  type CreateArtifactRequest,
+  type AcqArtifactResponse,
+  type AcqArtifactListResponse,
+  type ListMembersQuery,
+  type MemberIdParams,
+  type AcqListMemberContactSummary,
+  type AcqListMemberResponse,
+  type AcqListMembersResponse,
+  type ListCompanyIdParams,
+  type AcqListCompanyResponse,
+  type CompanyIdParams,
+  type ContactIdParams,
+  type ListCompaniesQuery,
+  type ListContactsQuery,
+  type CreateCompanyRequest,
+  type UpdateCompanyRequest,
+  type CreateContactRequest,
+  type UpdateContactRequest,
+  type AcqCompanyResponse,
+  type AcqCompanyListResponse,
+  type AcqContactResponse,
+  type AcqContactListResponse,
+  type AcqCompanyStatus,
+  type AcqContactStatus,
+  type AcqEmailValid,
+  type DealIdParams,
+  type DealTaskIdParams,
+  type ListDealsQuery,
+  type ListDealTasksDueQuery,
+  type CreateDealNoteRequest,
+  type CreateDealTaskRequest,
+  type TransitionItemRequest,
+  type ExecuteActionParams,
+  type ExecuteActionRequest,
+  type DealListResponse,
+  type DealDetailResponse,
+  type DealNoteResponse,
+  type DealNoteListResponse,
+  type DealTaskResponse,
+  type DealTaskListResponse,
+  type ListStatus,
+  type ScrapingConfig,
+  type IcpRubric,
+  type PipelineStage,
+  type PipelineConfig,
+  type ListStageCountsInput,
+  type ListTelemetryInput,
+  type ListIdParams,
+  type CreateListRequest,
+  type UpdateListRequest,
+  type UpdateListStatusRequest,
+  type UpdateListConfigRequest,
+  type AddCompaniesToListRequest,
+  type RemoveCompaniesFromListRequest,
+  type AddContactsToListRequest,
+  type RecordListExecutionRequest,
+  type AcqListResponse,
+  type AcqListListResponse,
+  type ListTelemetryResponse,
+  type ListTelemetryListResponse,
+  type ListExecutionSummaryInput,
+  type ListExecutionsResponse,
+  type ListStageProgress,
+  type ListProgress
+} from './api-schemas'

package/src/business/acquisition/stateful.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { ActivityEventSchema, type ActivityEvent } from './activity-events'
+
+/**
+ * Stateful trait — the (pipeline_key, stage_key, state_key, activity_log) quartet
+ * applied to acq_deals (CRM HITL, shipped 2026-04-27) and being generalized to
+ * acq_lists / acq_list_members / acq_list_companies via Track B.
+ */
+export interface Stateful {
+  pipeline_key: string
+  stage_key: string
+  state_key: string
+  activity_log: ActivityEvent[]
+}
+
+export const StatefulSchema = z.object({
+  pipeline_key: z.string(),
+  stage_key: z.string(),
+  state_key: z.string(),
+  activity_log: z.array(ActivityEventSchema)
+})
+
+/** Generic transition shape — concrete per-entity transitionItem implementations satisfy this. */
+export type TransitionItem<T extends Stateful, TEvent extends ActivityEvent> = (
+  item: T,
+  transition: { stage_key?: string; state_key?: string; event: TEvent }
+) => T
+
+/** Generic action-derivation shape — concrete per-entity deriveActions implementations satisfy this. */
+export type DeriveActions<T extends Stateful, TAction> = (item: T) => TAction[]

package/src/business/acquisition/types.ts

@@ -153,24 +153,54 @@ export interface ContactEnrichmentData {
 // Domain Types (camelCase transformations of database rows)
 // =============================================================================
 
-/**
- * Acquisition list for organizing contacts and companies.
- * Transformed from AcqListRow with camelCase properties.
- */
+export type ListStatus = 'draft' | 'enriching' | 'launched' | 'closing' | 'archived'
+
+export interface ScrapingConfig {
+  source?: string
+  query?: string
+  filters?: Record<string, unknown>
+  [key: string]: unknown
+}
+
+export interface IcpRubric {
+  targetDescription?: string
+  minReviewCount?: number
+  minRating?: number
+  excludeFranchises?: boolean
+  customRules?: string
+  qualificationRubricKey?: string | null
+  [key: string]: unknown
+}
+
+export interface PipelineStage {
+  key: string
+  label?: string
+  description?: string
+  resourceId?: string
+  inputTemplate?: Record<string, unknown>
+  enabled?: boolean
+  order?: number
+}
+
+export interface PipelineConfig {
+  stages: PipelineStage[]
+}
+
 export interface AcqList {
   id: string
   organizationId: string
   name: string
   description: string | null
-  type: string
   batchIds: string[]
   instantlyCampaignId: string | null
-  status: string
+  status: ListStatus
+  scrapingConfig: ScrapingConfig
+  icp: IcpRubric
+  pipelineConfig: PipelineConfig
   metadata: Record<string, unknown>
   launchedAt: Date | null
   completedAt: Date | null
   createdAt: Date
-  config: ListConfig
 }
 
 /**
@@ -198,6 +228,12 @@ export interface AcqCompany {
   batchId: string | null
   status: 'active' | 'invalid'
   verticalResearch: string | null
+  /** Track A: flat qualification score (null until a scoring rubric is defined). Added by W1 migration. */
+  qualificationScore: number | null
+  /** Track A: flat qualification signals jsonb preserving the result payload shape. Added by W1 migration. */
+  qualificationSignals: Record<string, unknown> | null
+  /** Track A: key identifying the rubric used for qualification. Added by W1 migration. */
+  qualificationRubricKey: string | null
   createdAt: Date
   updatedAt: Date
 }
@@ -302,76 +338,7 @@ export interface AcqDealTask {
   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[]
-  }
-}
+// ─── Progress / Telemetry Types ──────────────────────────────────────────────
 
 /**
  * Live-scan aggregate telemetry for a single list, computed on demand from