@elevasis/sdk 1.14.1 → 1.15.1

package/reference/scaffold/reference/contracts.md

@@ -888,6 +888,26 @@ export interface AcqContact {
 export type DealStage = 'interested' | 'proposal' | 'closing' | 'closed_won' | 'closed_lost' | 'nurturing'
 ```
 
+### `DealPriorityBucketKey`
+
+```typescript
+export type DealPriorityBucketKey = 'needs_response' | 'follow_up_due' | 'waiting' | 'stale' | 'closed_low'
+```
+
+### `DealPriority`
+
+```typescript
+export interface DealPriority {
+  bucketKey: DealPriorityBucketKey
+  rank: number
+  label: string
+  color: string
+  reason: string
+  latestActivityAt: string | null
+  nextActionAt: string | null
+}
+```
+
 ### `KanbanStageConfig`
 
 ```typescript
@@ -944,8 +964,11 @@ export interface DealFilters {
 
 ```typescript
 /** Deal list item with joined contact and company data */
-export interface DealListItem extends AcqDealRow {
-  contact: DealContact | null
+export interface DealListItem extends AcqDealRow {
+  priority: DealPriority
+  ownership: 'us' | 'them' | null
+  nextAction: string | null
+  contact: DealContact | null
 }
 ```
 
@@ -986,6 +1009,66 @@ export interface AcqDealTask {
 }
 ```
 
+### `CrmPriorityBucketKey`
+
+```typescript
+export type CrmPriorityBucketKey = 'needs_response' | 'follow_up_due' | 'waiting' | 'stale' | 'closed_low'
+```
+
+### `CrmPriorityBucketDefinition`
+
+```typescript
+export interface CrmPriorityBucketDefinition {
+  bucketKey: CrmPriorityBucketKey
+  label: string
+  /** Lower ranks sort first in deal lists and pipeline columns. */
+  rank: number
+  /** UI color token. Consumers may map this to their design system. */
+  color: string
+}
+```
+
+### `CrmPriorityRuleConfig`
+
+```typescript
+export interface CrmPriorityRuleConfig {
+  buckets: CrmPriorityBucketDefinition[]
+  closedStageKeys: string[]
+  followUpAfterDaysByStateKey: Record<string, number>
+  staleAfterDays: number
+}
+```
+
+### `CRM_PRIORITY_BUCKETS`
+
+```typescript
+export const CRM_PRIORITY_BUCKETS: CrmPriorityBucketDefinition[] = [
+  { bucketKey: 'needs_response', label: 'Needs Response', rank: 10, color: 'red' },
+  { bucketKey: 'follow_up_due', label: 'Follow-up Due', rank: 20, color: 'orange' },
+  { bucketKey: 'waiting', label: 'Waiting', rank: 30, color: 'blue' },
+  { bucketKey: 'stale', label: 'Stale', rank: 40, color: 'gray' },
+  { bucketKey: 'closed_low', label: 'Closed', rank: 50, color: 'dark' }
+]
+```
+
+### `DEFAULT_CRM_PRIORITY_RULE_CONFIG`
+
+```typescript
+export const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
+  buckets: CRM_PRIORITY_BUCKETS,
+  closedStageKeys: ['closed_won', 'closed_lost'],
+  followUpAfterDaysByStateKey: {
+    discovery_link_sent: 3,
+    discovery_nudging: 2,
+    reply_sent: 3,
+    followup_1_sent: 3,
+    followup_2_sent: 5,
+    followup_3_sent: 7
+  },
+  staleAfterDays: 14
+}
+```
+
 ### `DealStageSchema`
 
 ```typescript
@@ -1141,6 +1224,20 @@ export const DealContactSummarySchema = z.object({
 })
 ```
 
+### `DealPrioritySchema`
+
+```typescript
+export const DealPrioritySchema = z.object({
+  bucketKey: z.enum(['needs_response', 'follow_up_due', 'waiting', 'stale', 'closed_low']),
+  rank: z.number().int(),
+  label: z.string(),
+  color: z.string(),
+  reason: z.string(),
+  latestActivityAt: z.string().nullable(),
+  nextActionAt: z.string().nullable()
+})
+```
+
 ### `DealListItemSchema`
 
 ```typescript
@@ -1171,10 +1268,13 @@ export const DealListItemSchema = z.object({
   monthly_fee: z.number().nullable(),
   closed_lost_at: z.string().nullable(),
   closed_lost_reason: z.string().nullable(),
-  created_at: z.string(),
-  updated_at: z.string(),
-  // joined relation
-  contact: DealContactSummarySchema.nullable()
+  created_at: z.string(),
+  updated_at: z.string(),
+  priority: DealPrioritySchema,
+  ownership: z.enum(['us', 'them']).nullable(),
+  nextAction: z.string().nullable(),
+  // joined relation
+  contact: DealContactSummarySchema.nullable()
 })
 ```
 
@@ -1194,9 +1294,11 @@ export const DealListResponseSchema = z.object({
 ```typescript
 /**
  * Deal detail shape — currently the same as a list item (full joined record).
- * useDealDetail returns DealDetail which is typed as DealListItem.
+ * Additive fields keep existing DealListItem callers compatible.
  */
-export const DealDetailResponseSchema = DealListItemSchema
+export const DealDetailResponseSchema = DealListItemSchema.extend({
+  conversation: DealConversationSchema
+})
 ```
 
 ### `DealNoteResponseSchema`
@@ -1269,13 +1371,16 @@ export const DealSchemas = {
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
   TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionDealStateRequest: TransitionDealStateRequestSchema,
   ExecuteActionParams: ExecuteActionParamsSchema,
   ExecuteActionRequest: ExecuteActionRequestSchema,
 
   // Responses
+  DealPriority: DealPrioritySchema,
   DealListResponse: DealListResponseSchema,
   DealSummaryResponse: DealSummaryResponseSchema,
   DealLookupResponse: DealLookupResponseSchema,
+  ConversationMessage: ConversationMessageSchema,
   DealDetailResponse: DealDetailResponseSchema,
   DealNoteResponse: DealNoteResponseSchema,
   DealNoteListResponse: DealNoteListResponseSchema,
@@ -1297,12 +1402,12 @@ export interface Action {
 ### `ActionDef`
 
 ```typescript
-export interface ActionDef {
-  key: string
-  label: string
-  isAvailableFor: (deal: AcqDealRow) => boolean
-  workflowId: string
-  payloadSchema?: z.ZodTypeAny
+export interface ActionDef {
+  key: string
+  label: string
+  isAvailableFor: (deal: AcqDealRow) => boolean
+  workflowId: string
+  payloadSchema?: z.ZodTypeAny
 }
 ```
 
@@ -1343,20 +1448,22 @@ export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
     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'),
+    key: 'send_reply',
+    label: 'Send Reply',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' &&
+      isOurReplyAction(deal) &&
+      (deal.state_key === CRM_DISCOVERY_REPLIED_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_LINK_SENT_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey),
     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',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_REPLIED_STATE.stateKey,
     workflowId: 'crm-send-booking-link-workflow'
   },
   {
@@ -1364,13 +1471,15 @@ export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
     label: 'Send Nudge',
     isAvailableFor: (deal) =>
       deal.stage_key === 'interested' &&
-      (deal.state_key === 'discovery_link_sent' || deal.state_key === 'discovery_nudging'),
+      (deal.state_key === CRM_DISCOVERY_LINK_SENT_STATE.stateKey ||
+        deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey),
     workflowId: 'crm-send-nudge-workflow'
   },
   {
     key: 'mark_no_show',
     label: 'Mark No-Show',
-    isAvailableFor: (deal) => deal.stage_key === 'interested' && deal.state_key === 'discovery_nudging',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_NUDGING_STATE.stateKey,
     // 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.
@@ -1379,7 +1488,8 @@ export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
   {
     key: 'rebook',
     label: 'Rebook',
-    isAvailableFor: (deal) => deal.stage_key === 'interested' && deal.state_key === 'discovery_booking_cancelled',
+    isAvailableFor: (deal) =>
+      deal.stage_key === 'interested' && deal.state_key === CRM_DISCOVERY_BOOKING_CANCELLED_STATE.stateKey,
     workflowId: 'crm-rebook-workflow'
   }
 ]
@@ -1388,19 +1498,19 @@ export const DEFAULT_CRM_ACTIONS: ActionDef[] = [
 ### `CrmToolMap`
 
 ```typescript
-export type CrmToolMap = {
-  getRecentActivity: { params: CrmRecentActivityParams; result: RecentActivityEntry[] }
-  listDeals: { params: CrmListDealsParams; result: DealListItem[] }
-  getDeal: { params: CrmGetDealParams; result: DealDetail | null }
-  getDealByEmail: { params: CrmGetDealByEmailParams; result: DealDetail | null }
-  createDealNote: { params: CrmDealNoteParams; result: AcqDealNote }
-  listDealNotes: { params: Omit<ListDealNotesParams, 'organizationId'>; result: AcqDealNote[] }
-  createDealTask: { params: CrmDealTaskParams; result: AcqDealTask }
-  listDealTasks: { params: Omit<ListDealTasksParams, 'organizationId'>; result: AcqDealTask[] }
-  listDealTasksDue: { params: CrmTaskDueParams; result: AcqDealTask[] }
-  completeDealTask: { params: Omit<CompleteDealTaskParams, 'organizationId'>; result: AcqDealTask }
-  recordActivity: { params: CrmRecordActivityParams; result: void }
-  deleteDeal: { params: CrmDeleteDealParams; result: void }
+export type CrmToolMap = {
+  getRecentActivity: { params: CrmRecentActivityParams; result: RecentActivityEntry[] }
+  listDeals: { params: CrmListDealsParams; result: DealListItem[] }
+  getDeal: { params: CrmGetDealParams; result: DealDetail | null }
+  getDealByEmail: { params: CrmGetDealByEmailParams; result: DealDetail | null }
+  createDealNote: { params: CrmDealNoteParams; result: AcqDealNote }
+  listDealNotes: { params: Omit<ListDealNotesParams, 'organizationId'>; result: AcqDealNote[] }
+  createDealTask: { params: CrmDealTaskParams; result: AcqDealTask }
+  listDealTasks: { params: Omit<ListDealTasksParams, 'organizationId'>; result: AcqDealTask[] }
+  listDealTasksDue: { params: CrmTaskDueParams; result: AcqDealTask[] }
+  completeDealTask: { params: Omit<CompleteDealTaskParams, 'organizationId'>; result: AcqDealTask }
+  recordActivity: { params: CrmRecordActivityParams; result: void }
+  deleteDeal: { params: CrmDeleteDealParams; result: void }
 }
 ```
 
@@ -1556,7 +1666,7 @@ export interface AcqList {
   scrapingConfig: ScrapingConfig
   icp: IcpRubric
   pipelineConfig: PipelineConfig
-  metadata: Record<string, unknown>
+  metadata: AcqListMetadata
   launchedAt: Date | null
   completedAt: Date | null
   createdAt: Date
@@ -1642,6 +1752,7 @@ export interface AcqContact {
 /**
  * Live-scan aggregate telemetry for a single list, computed on demand from
  * the list junction tables and current contact deliverability state.
+ * `stageCounts` are attempted counts from list-row processing_state.
  */
 export interface ListTelemetry {
   listId: string
@@ -1672,6 +1783,8 @@ export interface ListTelemetry {
 
 ```typescript
 export const ListStageCountsSchema = z.object({
+  // Attempted counts by canonical lead-gen stage. The detailed status
+  // distribution lives on ListProgress; telemetry keeps the overview payload small.
   stageCounts: z.object({
     populated: z.number().int(),
     extracted: z.number().int(),
@@ -1720,6 +1833,7 @@ export const CreateListRequestSchema = z
     name: z.string().trim().min(1).max(255),
     description: z.string().trim().nullable().optional(),
     status: ListStatusSchema.optional(),
+    buildTemplateId: ProspectingBuildTemplateIdSchema.optional(),
     scrapingConfig: ScrapingConfigSchema.optional(),
     icp: IcpRubricSchema.optional(),
     pipelineConfig: PipelineConfigSchema.optional()
@@ -1734,11 +1848,24 @@ export const UpdateListRequestSchema = z
   .object({
     name: z.string().trim().min(1).max(255).optional(),
     description: z.string().trim().nullable().optional(),
-    batchIds: z.array(z.string()).optional()
+    batchIds: z.array(z.string()).optional(),
+    buildTemplateId: ProspectingBuildTemplateIdSchema.optional(),
+    confirmBuildTemplateChange: z.literal(true).optional()
   })
   .strict()
-  .refine((data) => data.name !== undefined || data.description !== undefined || data.batchIds !== undefined, {
-    message: 'At least one field (name, description, or batchIds) must be provided'
+  .refine(
+    (data) =>
+      data.name !== undefined ||
+      data.description !== undefined ||
+      data.batchIds !== undefined ||
+      data.buildTemplateId !== undefined,
+    {
+      message: 'At least one field (name, description, batchIds, or buildTemplateId) must be provided'
+    }
+  )
+  .refine((data) => data.buildTemplateId === undefined || data.confirmBuildTemplateChange === true, {
+    message: 'confirmBuildTemplateChange must be true when changing buildTemplateId',
+    path: ['confirmBuildTemplateChange']
   })
 ```
 
@@ -1815,12 +1942,11 @@ export const AcqListResponseSchema = z.object({
   organizationId: z.string(),
   name: z.string(),
   description: z.string().nullable(),
-  type: z.string(),
   batchIds: z.array(z.string()),
   instantlyCampaignId: z.string().nullable(),
   /** Lifecycle status (draft | enriching | launched | closing | archived). */
   status: ListStatusSchema,
-  metadata: z.record(z.string(), z.unknown()),
+  metadata: AcqListMetadataSchema,
   launchedAt: z.string().nullable(),
   completedAt: z.string().nullable(),
   createdAt: z.string(),
@@ -2354,6 +2480,10 @@ export const AcqListSchemas = {
   IcpRubric: IcpRubricSchema,
   PipelineConfig: PipelineConfigSchema,
   PipelineStage: PipelineStageSchema,
+  BuildPlanSnapshot: BuildPlanSnapshotSchema,
+  BuildPlanSnapshotStep: BuildPlanSnapshotStepSchema,
+  AcqListMetadata: AcqListMetadataSchema,
+  ProcessingStageStatus: ProcessingStageStatusSchema,
   ListStageCounts: ListStageCountsSchema,
   ListTelemetry: ListTelemetrySchema,
 
@@ -2449,134 +2579,134 @@ export const StatefulSchema = z.object({
 ### `StatefulStateDefinition`
 
 ```typescript
-/** One state within a stage — minimal shape: key + display label. */
-export interface StatefulStateDefinition {
-  /** Matches state_key values written by workflow steps. */
-  stateKey: string
-  label: string
+/** One state within a stage — minimal shape: key + display label. */
+export interface StatefulStateDefinition {
+  /** Matches state_key values written by workflow steps. */
+  stateKey: string
+  label: string
 }
 ```
 
 ### `StatefulStageDefinition`
 
 ```typescript
-/** One stage within a pipeline — has a stage_key and an ordered list of valid states. */
-export interface StatefulStageDefinition {
-  /** Matches stage_key values written by workflow steps. */
-  stageKey: string
-  label: string
-  states: StatefulStateDefinition[]
+/** One stage within a pipeline — has a stage_key and an ordered list of valid states. */
+export interface StatefulStageDefinition {
+  /** Matches stage_key values written by workflow steps. */
+  stageKey: string
+  label: string
+  states: StatefulStateDefinition[]
 }
 ```
 
 ### `StatefulPipelineDefinition`
 
 ```typescript
-/**
- * Pipeline definition for a single entity participating in the Stateful trait.
- * Parallel to acq_deals' pipeline_key concept but structured for lead-gen entities.
- */
-export interface StatefulPipelineDefinition {
-  /** Matches pipeline_key values in the database (e.g. 'lead-gen'). */
-  pipelineKey: string
-  label: string
-  /** Entity this pipeline applies to (e.g. 'acq.list', 'acq.list-member', 'acq.list-company'). */
-  entityKey: string
-  stages: StatefulStageDefinition[]
+/**
+ * Pipeline definition for a single entity participating in the Stateful trait.
+ * Parallel to acq_deals' pipeline_key concept but structured for lead-gen entities.
+ */
+export interface StatefulPipelineDefinition {
+  /** Matches pipeline_key values in the database (e.g. 'lead-gen'). */
+  pipelineKey: string
+  label: string
+  /** Entity this pipeline applies to (e.g. 'acq.list', 'acq.list-member', 'acq.list-company'). */
+  entityKey: string
+  stages: StatefulStageDefinition[]
 }
 ```
 
 ### `ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE`
 
 ```typescript
-/**
- * Lead-gen pipeline definition for acq_list_members (contacts).
- * Three stages matching the post-restructure sales subdomain tree.
- *
- * Note: members visit outreach and prospecting states depending on which
- * workflow last processed them. stage_key is set per-transition by the workflow.
- */
-export const ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
-  pipelineKey: 'lead-gen',
-  label: 'Lead Generation',
-  entityKey: 'acq.list-member',
-  stages: [
-    {
-      stageKey: 'outreach',
-      label: 'Outreach',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'personalized', label: 'Personalized' },
-        { stateKey: 'uploaded', label: 'Uploaded' },
-        { stateKey: 'interested', label: 'Interested' }
-      ]
-    },
-    {
-      stageKey: 'prospecting',
-      label: 'Prospecting',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'discovered', label: 'Discovered' },
-        { stateKey: 'verified', label: 'Verified' }
-      ]
-    },
-    {
-      stageKey: 'qualification',
-      label: 'Qualification',
-      states: [PENDING_STATE]
-    }
-  ]
+/**
+ * Lead-gen pipeline definition for acq_list_members (contacts).
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: members visit outreach and prospecting states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-member',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'personalized', label: 'Personalized' },
+        { stateKey: 'uploaded', label: 'Uploaded' },
+        { stateKey: 'interested', label: 'Interested' }
+      ]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'discovered', label: 'Discovered' },
+        { stateKey: 'verified', label: 'Verified' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE]
+    }
+  ]
 }
 ```
 
 ### `ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE`
 
 ```typescript
-/**
- * Lead-gen pipeline definition for acq_list_companies.
- * Three stages matching the post-restructure sales subdomain tree.
- *
- * Note: companies visit prospecting and qualification states depending on which
- * workflow last processed them. stage_key is set per-transition by the workflow.
- */
-export const ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
-  pipelineKey: 'lead-gen',
-  label: 'Lead Generation',
-  entityKey: 'acq.list-company',
-  stages: [
-    {
-      stageKey: 'outreach',
-      label: 'Outreach',
-      states: [PENDING_STATE]
-    },
-    {
-      stageKey: 'prospecting',
-      label: 'Prospecting',
-      states: [
-        PENDING_STATE,
-        { stateKey: 'populated', label: 'Populated' },
-        { stateKey: 'extracted', label: 'Extracted' }
-      ]
-    },
-    {
-      stageKey: 'qualification',
-      label: 'Qualification',
-      states: [PENDING_STATE, { stateKey: 'qualified', label: 'Qualified' }]
-    }
-  ]
+/**
+ * Lead-gen pipeline definition for acq_list_companies.
+ * Three stages matching the post-restructure sales subdomain tree.
+ *
+ * Note: companies visit prospecting and qualification states depending on which
+ * workflow last processed them. stage_key is set per-transition by the workflow.
+ */
+export const ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE: StatefulPipelineDefinition = {
+  pipelineKey: 'lead-gen',
+  label: 'Lead Generation',
+  entityKey: 'acq.list-company',
+  stages: [
+    {
+      stageKey: 'outreach',
+      label: 'Outreach',
+      states: [PENDING_STATE]
+    },
+    {
+      stageKey: 'prospecting',
+      label: 'Prospecting',
+      states: [
+        PENDING_STATE,
+        { stateKey: 'populated', label: 'Populated' },
+        { stateKey: 'extracted', label: 'Extracted' }
+      ]
+    },
+    {
+      stageKey: 'qualification',
+      label: 'Qualification',
+      states: [PENDING_STATE, { stateKey: 'qualified', label: 'Qualified' }]
+    }
+  ]
 }
 ```
 
 ### `LEAD_GEN_PIPELINE_DEFINITIONS`
 
 ```typescript
-/**
- * All lead-gen pipeline definitions indexed by entity key.
- * Use findPipeline() to locate a definition by pipeline_key within any of these arrays.
- */
-export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
-  'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
-  'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
+/**
+ * All lead-gen pipeline definitions indexed by entity key.
+ * Use findPipeline() to locate a definition by pipeline_key within any of these arrays.
+ */
+export const LEAD_GEN_PIPELINE_DEFINITIONS: Record<string, StatefulPipelineDefinition[]> = {
+  'acq.list-member': [ACQ_LIST_MEMBERS_LEAD_GEN_PIPELINE],
+  'acq.list-company': [ACQ_LIST_COMPANIES_LEAD_GEN_PIPELINE]
 }
 ```
 
@@ -2609,11 +2739,12 @@ export interface CreateListParams {
   description?: string
   type?: string
   batchIds?: string[]
-  instantlyCampaignId?: string
-  status?: ListStatus
-  metadata?: Record<string, unknown>
-  scrapingConfig?: ScrapingConfig
-  icp?: IcpRubric
+  instantlyCampaignId?: string
+  status?: ListStatus
+  buildTemplateId?: string
+  metadata?: Record<string, unknown>
+  scrapingConfig?: ScrapingConfig
+  icp?: IcpRubric
   pipelineConfig?: PipelineConfig
 }
 ```
@@ -2621,10 +2752,10 @@ export interface CreateListParams {
 ### `UpdateListParams`
 
 ```typescript
-export interface UpdateListParams {
-  name?: string
-  description?: string
-  batchIds?: string[]
+export interface UpdateListParams {
+  name?: string
+  description?: string
+  batchIds?: string[]
 }
 ```
 
@@ -2835,24 +2966,26 @@ export interface UpdateListConfigParams {
 ### `UpdateCompanyStageParams`
 
 ```typescript
-export interface UpdateCompanyStageParams {
-  organizationId: string
-  listId: string
-  companyId: string
-  stage: string
-  executionId?: string
+export interface UpdateCompanyStageParams {
+  organizationId: string
+  listId: string
+  companyId: string
+  stage: string
+  status?: ProcessingStageStatus
+  executionId?: string
 }
 ```
 
 ### `UpdateContactStageParams`
 
 ```typescript
-export interface UpdateContactStageParams {
-  organizationId: string
-  listId: string
-  contactId: string
-  stage: string
-  executionId?: string
+export interface UpdateContactStageParams {
+  organizationId: string
+  listId: string
+  contactId: string
+  stage: string
+  status?: ProcessingStageStatus
+  executionId?: string
 }
 ```
 
@@ -2976,157 +3109,159 @@ export interface BulkImportCompaniesResult {
 ### `LeadToolMap`
 
 ```typescript
-export type LeadToolMap = {
-  // List operations
-  listLists: { params: Record<string, never>; result: AcqList[] }
-  createList: { params: Omit<CreateListParams, 'organizationId'>; result: AcqList }
-  updateList: { params: { id: string } & UpdateListParams; result: AcqList }
-  deleteList: { params: { id: string }; result: void }
-  addContactsToList: { params: Omit<AddContactsToListParams, 'organizationId'>; result: AddContactsToListResult }
-  updateCompanyStage: {
-    params: Omit<UpdateCompanyStageParams, 'organizationId'>
-    result: void
-  }
-  updateContactStage: {
-    params: Omit<UpdateContactStageParams, 'organizationId'>
-    result: void
-  }
-  // Company operations
-  createCompany: { params: Omit<CreateCompanyParams, 'organizationId'>; result: AcqCompany }
-  upsertCompany: { params: Omit<UpsertCompanyParams, 'organizationId'>; result: AcqCompany }
-  updateCompany: { params: { id: string } & UpdateCompanyParams; result: AcqCompany }
-  getCompany: { params: { id: string }; result: AcqCompany | null }
-  listCompanies: { params: CompanyFilters; result: AcqCompany[] }
-  deleteCompany: { params: { id: string }; result: void }
-  // Contact operations
-  createContact: { params: Omit<CreateContactParams, 'organizationId'>; result: AcqContact }
-  upsertContact: { params: Omit<UpsertContactParams, 'organizationId'>; result: AcqContact }
-  updateContact: { params: { id: string } & UpdateContactParams; result: AcqContact }
-  getContact: { params: { id: string }; result: AcqContact | null }
-  getContactByEmail: { params: { email: string }; result: AcqContact | null }
-  listContacts: {
-    params: ContactFilters & { limit?: number; offset?: number }
-    result: PaginatedResult<AcqContact>
-  }
-  deleteContact: { params: { id: string }; result: void }
-  bulkImportContacts: { params: Omit<BulkImportParams, 'organizationId'>; result: BulkImportResult }
-  bulkImportCompanies: {
-    params: Omit<BulkImportCompaniesParams, 'organizationId'>
-    result: BulkImportCompaniesResult
-  }
-  deactivateContactsByCompany: {
-    params: { companyId: string }
-    result: { deactivated: number }
-  }
-  // Deal operations
-  upsertDeal: { params: Omit<UpsertDealParams, 'organizationId'>; result: AcqDeal }
-  getDealByEmail: { params: { email: string }; result: AcqDeal | null }
-  getDealByEnvelopeId: { params: { envelopeId: string }; result: AcqDeal | null }
-  updateDealEnvelopeId: { params: { dealId: string; envelopeId: string }; result: AcqDeal | null }
-  getDealById: { params: Omit<GetDealByIdParams, 'organizationId'>; result: AcqDeal | null }
-  getContactById: { params: Omit<GetContactByIdParams, 'organizationId'>; result: AcqContact | null }
-  getCompanyById: { params: Omit<GetCompanyByIdParams, 'organizationId'>; result: AcqCompany | null }
-  // Deal-sync operations
-  updateDiscoveryData: { params: Omit<UpdateDiscoveryDataParams, 'organizationId'>; result: void }
-  updateProposalData: { params: Omit<UpdateProposalDataParams, 'organizationId'>; result: void }
-  markProposalSent: { params: Omit<MarkProposalSentParams, 'organizationId'>; result: void }
-  markProposalReviewed: { params: Omit<MarkProposalReviewedParams, 'organizationId'>; result: void }
-  updateCloseLostReason: { params: Omit<UpdateCloseLostReasonParams, 'organizationId'>; result: void }
-  updateFees: { params: Omit<UpdateFeesParams, 'organizationId'>; result: void }
-  transitionItem: { params: Omit<TransitionItemParams, 'organizationId'>; result: void }
-  setContactNurture: { params: Omit<SetContactNurtureParams, 'organizationId'>; result: void }
-  cancelSchedulesAndHitlByEmail: {
-    params: Omit<CancelSchedulesAndHitlByEmailParams, 'organizationId'>
-    result: { schedulesCancelled: number; hitlDeleted: number }
-  }
-  cancelHitlByDealId: { params: Omit<CancelHitlByDealIdParams, 'organizationId'>; result: { hitlDeleted: number } }
-  clearDealFields: { params: Omit<ClearDealFieldsParams, 'organizationId'>; result: void }
-  deleteDeal: { params: Omit<DeleteDealParams, 'organizationId'>; result: void }
-  recordDealActivity: {
-    params: Omit<RecordDealActivityParams, 'organizationId'>
-    result: void
-  }
-  // Deal note operations
-  createDealNote: {
-    params: Omit<CreateDealNoteParams, 'organizationId'>
-    result: AcqDealNote
-  }
-  listDealNotes: {
-    params: Omit<ListDealNotesParams, 'organizationId'>
-    result: AcqDealNote[]
-  }
-  // Deal task operations
-  createDealTask: {
-    params: Omit<CreateDealTaskParams, 'organizationId'>
-    result: AcqDealTask
-  }
-  listDealTasks: {
-    params: Omit<ListDealTasksParams, 'organizationId'>
-    result: AcqDealTask[]
-  }
-  listDealTasksDue: {
-    params: Omit<ListDealTasksDueParams, 'organizationId'>
-    result: AcqDealTask[]
-  }
-  completeDealTask: {
-    params: Omit<CompleteDealTaskParams, 'organizationId'>
-    result: AcqDealTask
-  }
-  // Deal query & analytics operations
-  listDeals: { params: DealFilters; result: AcqDeal[] }
-  getDealPipelineAnalytics: { params: { recentLimit?: number }; result: DealPipelineAnalytics }
-  // Enrichment data operations
-  mergeEnrichmentData: {
-    params: { id: string; table: 'acq_companies' | 'acq_contacts'; data: Record<string, unknown> }
-    result: void
-  }
-  // Social monitoring operations
-  upsertSocialPosts: {
-    params: { posts: Omit<UpsertSocialPostParams, 'organizationId'>[] }
-    result: UpsertSocialPostsResult
-  }
-  setDealStateKey: {
-    params: {
-      dealId: string
-      stateKey: string
-    }
-    result: { ok: true }
-  }
-  // CRM workflow helpers
-  transitionDeal: {
-    params: {
-      dealId: string
-      toStage: string
-      toState?: string
-    }
-    result: { deal: AcqDeal }
-  }
-  loadDeal: {
-    params: { dealId: string }
-    result: DealDetail | null
-  }
+export type LeadToolMap = {
+  // List operations
+  listLists: { params: Record<string, never>; result: AcqList[] }
+  createList: { params: Omit<CreateListParams, 'organizationId'>; result: AcqList }
+  updateList: { params: { id: string } & UpdateListParams; result: AcqList }
+  deleteList: { params: { id: string }; result: void }
+  addContactsToList: { params: Omit<AddContactsToListParams, 'organizationId'>; result: AddContactsToListResult }
+  addCompaniesToList: { params: Omit<AddCompaniesToListParams, 'organizationId'>; result: AddCompaniesToListResult }
+  updateCompanyStage: {
+    params: Omit<UpdateCompanyStageParams, 'organizationId'>
+    result: void
+  }
+  updateContactStage: {
+    params: Omit<UpdateContactStageParams, 'organizationId'>
+    result: void
+  }
+  // Company operations
+  createCompany: { params: Omit<CreateCompanyParams, 'organizationId'>; result: AcqCompany }
+  upsertCompany: { params: Omit<UpsertCompanyParams, 'organizationId'>; result: AcqCompany }
+  updateCompany: { params: { id: string } & UpdateCompanyParams; result: AcqCompany }
+  getCompany: { params: { id: string }; result: AcqCompany | null }
+  listCompanies: { params: CompanyFilters; result: AcqCompany[] }
+  deleteCompany: { params: { id: string }; result: void }
+  // Contact operations
+  createContact: { params: Omit<CreateContactParams, 'organizationId'>; result: AcqContact }
+  upsertContact: { params: Omit<UpsertContactParams, 'organizationId'>; result: AcqContact }
+  updateContact: { params: { id: string } & UpdateContactParams; result: AcqContact }
+  getContact: { params: { id: string }; result: AcqContact | null }
+  getContactByEmail: { params: { email: string }; result: AcqContact | null }
+  listContacts: {
+    params: ContactFilters & { limit?: number; offset?: number }
+    result: PaginatedResult<AcqContact>
+  }
+  deleteContact: { params: { id: string }; result: void }
+  bulkImportContacts: { params: Omit<BulkImportParams, 'organizationId'>; result: BulkImportResult }
+  bulkImportCompanies: {
+    params: Omit<BulkImportCompaniesParams, 'organizationId'>
+    result: BulkImportCompaniesResult
+  }
+  deactivateContactsByCompany: {
+    params: { companyId: string }
+    result: { deactivated: number }
+  }
+  // Deal operations
+  upsertDeal: { params: Omit<UpsertDealParams, 'organizationId'>; result: AcqDeal }
+  getDealByEmail: { params: { email: string }; result: AcqDeal | null }
+  getDealByEnvelopeId: { params: { envelopeId: string }; result: AcqDeal | null }
+  updateDealEnvelopeId: { params: { dealId: string; envelopeId: string }; result: AcqDeal | null }
+  getDealById: { params: Omit<GetDealByIdParams, 'organizationId'>; result: AcqDeal | null }
+  getContactById: { params: Omit<GetContactByIdParams, 'organizationId'>; result: AcqContact | null }
+  getCompanyById: { params: Omit<GetCompanyByIdParams, 'organizationId'>; result: AcqCompany | null }
+  // Deal-sync operations
+  updateDiscoveryData: { params: Omit<UpdateDiscoveryDataParams, 'organizationId'>; result: void }
+  updateProposalData: { params: Omit<UpdateProposalDataParams, 'organizationId'>; result: void }
+  markProposalSent: { params: Omit<MarkProposalSentParams, 'organizationId'>; result: void }
+  markProposalReviewed: { params: Omit<MarkProposalReviewedParams, 'organizationId'>; result: void }
+  updateCloseLostReason: { params: Omit<UpdateCloseLostReasonParams, 'organizationId'>; result: void }
+  updateFees: { params: Omit<UpdateFeesParams, 'organizationId'>; result: void }
+  cacheInstantlyThreadIds: { params: Omit<CacheInstantlyThreadIdsParams, 'organizationId'>; result: void }
+  transitionItem: { params: Omit<TransitionItemParams, 'organizationId'>; result: void }
+  setContactNurture: { params: Omit<SetContactNurtureParams, 'organizationId'>; result: void }
+  cancelSchedulesAndHitlByEmail: {
+    params: Omit<CancelSchedulesAndHitlByEmailParams, 'organizationId'>
+    result: { schedulesCancelled: number; hitlDeleted: number }
+  }
+  cancelHitlByDealId: { params: Omit<CancelHitlByDealIdParams, 'organizationId'>; result: { hitlDeleted: number } }
+  clearDealFields: { params: Omit<ClearDealFieldsParams, 'organizationId'>; result: void }
+  deleteDeal: { params: Omit<DeleteDealParams, 'organizationId'>; result: void }
+  recordDealActivity: {
+    params: Omit<RecordDealActivityParams, 'organizationId'>
+    result: void
+  }
+  // Deal note operations
+  createDealNote: {
+    params: Omit<CreateDealNoteParams, 'organizationId'>
+    result: AcqDealNote
+  }
+  listDealNotes: {
+    params: Omit<ListDealNotesParams, 'organizationId'>
+    result: AcqDealNote[]
+  }
+  // Deal task operations
+  createDealTask: {
+    params: Omit<CreateDealTaskParams, 'organizationId'>
+    result: AcqDealTask
+  }
+  listDealTasks: {
+    params: Omit<ListDealTasksParams, 'organizationId'>
+    result: AcqDealTask[]
+  }
+  listDealTasksDue: {
+    params: Omit<ListDealTasksDueParams, 'organizationId'>
+    result: AcqDealTask[]
+  }
+  completeDealTask: {
+    params: Omit<CompleteDealTaskParams, 'organizationId'>
+    result: AcqDealTask
+  }
+  // Deal query & analytics operations
+  listDeals: { params: DealFilters; result: AcqDeal[] }
+  getDealPipelineAnalytics: { params: { recentLimit?: number }; result: DealPipelineAnalytics }
+  // Enrichment data operations
+  mergeEnrichmentData: {
+    params: { id: string; table: 'acq_companies' | 'acq_contacts'; data: Record<string, unknown> }
+    result: void
+  }
+  // Social monitoring operations
+  upsertSocialPosts: {
+    params: { posts: Omit<UpsertSocialPostParams, 'organizationId'>[] }
+    result: UpsertSocialPostsResult
+  }
+  setDealStateKey: {
+    params: {
+      dealId: string
+      stateKey: string
+    }
+    result: { ok: true }
+  }
+  // CRM workflow helpers
+  transitionDeal: {
+    params: {
+      dealId: string
+      toStage: string
+      toState?: string
+    }
+    result: { deal: AcqDeal }
+  }
+  loadDeal: {
+    params: { dealId: string }
+    result: DealDetail | null
+  }
 }
 ```
 
 ### `ListToolMap`
 
 ```typescript
-export type ListToolMap = {
-  getConfig: {
-    params: { listId: string }
-    result: { scrapingConfig: ScrapingConfig; icp: IcpRubric; pipelineConfig: PipelineConfig }
-  }
-  recordExecution: {
-    params: Omit<RecordListExecutionParams, 'organizationId'>
-    result: void
-  }
-  updateCompanyStage: {
-    params: Omit<UpdateCompanyStageParams, 'organizationId'>
-    result: void
-  }
-  updateContactStage: {
-    params: Omit<UpdateContactStageParams, 'organizationId'>
-    result: void
-  }
+export type ListToolMap = {
+  getConfig: {
+    params: { listId: string }
+    result: { scrapingConfig: ScrapingConfig; icp: IcpRubric; pipelineConfig: PipelineConfig }
+  }
+  recordExecution: {
+    params: Omit<RecordListExecutionParams, 'organizationId'>
+    result: void
+  }
+  updateCompanyStage: {
+    params: Omit<UpdateCompanyStageParams, 'organizationId'>
+    result: void
+  }
+  updateContactStage: {
+    params: Omit<UpdateContactStageParams, 'organizationId'>
+    result: void
+  }
 }
 ```