@elevasis/core 0.12.0 → 0.14.0

package/src/business/acquisition/api-schemas.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
-import { UuidSchema } from '../../platform/utils/validation'
+import { UuidSchema, NonEmptyStringSchema } from '../../platform/utils/validation'
+import { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
 
 /**
  * Deal Management API Schemas
@@ -38,21 +39,21 @@ export const DealTaskIdParamsSchema = z.object({
 // Query schemas (coerce strings from query params)
 // ---------------------------------------------------------------------------
 
-export const ListDealsQuerySchema = z
-  .object({
-    stage: DealStageSchema.optional(),
-    search: z.string().optional(),
-    limit: z.coerce.number().int().positive().default(50),
-    offset: z.coerce.number().int().min(0).default(0)
-  })
-  .strict()
-
-export const DealLookupQuerySchema = z
-  .object({
-    search: z.string().trim().min(1).max(200).optional(),
-    limit: z.coerce.number().int().min(1).max(25).default(10)
-  })
-  .strict()
+export const ListDealsQuerySchema = z
+  .object({
+    stage: DealStageSchema.optional(),
+    search: z.string().optional(),
+    limit: z.coerce.number().int().positive().default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+
+export const DealLookupQuerySchema = z
+  .object({
+    search: z.string().trim().min(1).max(200).optional(),
+    limit: z.coerce.number().int().min(1).max(25).default(10)
+  })
+  .strict()
 
 export const ListDealTasksDueQuerySchema = z
   .object({
@@ -81,9 +82,26 @@ export const CreateDealTaskRequestSchema = z
   })
   .strict()
 
-export const SyncDealStageRequestSchema = z
+export const TransitionItemRequestSchema = z
   .object({
-    stage: DealStageSchema
+    pipelineKey: z.string().min(1),
+    stageKey: z.string().min(1),
+    stateKey: z.string().nullable().optional(),
+    reason: z.string().optional(),
+    expectedUpdatedAt: z.string().datetime().optional()
+  })
+  .strict()
+
+export const ExecuteActionParamsSchema = z
+  .object({
+    dealId: UuidSchema,
+    actionKey: NonEmptyStringSchema
+  })
+  .strict()
+
+export const ExecuteActionRequestSchema = z
+  .object({
+    payload: z.record(z.string(), z.unknown()).optional()
   })
   .strict()
 
@@ -123,19 +141,20 @@ export const DealContactSummarySchema = z.object({
  * Deal list item with joined contact (and company via contact).
  * Matches DealListItem from @repo/core types.
  */
-export const DealListItemSchema = z.object({
+export const DealListItemSchema = z.object({
   // acq_deals columns
   id: z.string(),
   organization_id: z.string(),
   contact_id: z.string().nullable(),
   contact_email: z.string(),
-  cached_stage: z.string().nullable(),
+  pipeline_key: z.string(),
+  stage_key: z.string().nullable(),
+  state_key: z.string().nullable(),
   activity_log: z.unknown(),
   discovery_data: z.unknown().nullable(),
   discovery_submitted_at: z.string().nullable(),
   discovery_submitted_by: z.string().nullable(),
   proposal_data: z.unknown().nullable(),
-  proposal_status: z.string().nullable(),
   proposal_sent_at: z.string().nullable(),
   proposal_pdf_url: z.string().nullable(),
   signature_envelope_id: z.string().nullable(),
@@ -148,54 +167,55 @@ export const DealListItemSchema = z.object({
   created_at: z.string(),
   updated_at: z.string(),
   // joined relation
-  contact: DealContactSummarySchema.nullable()
-})
-
-export const DealListResponseSchema = z.object({
-  data: z.array(DealListItemSchema),
-  total: z.number().int(),
-  limit: z.number().int(),
-  offset: z.number().int()
-})
-
-export const DealStageSummarySchema = z.object({
-  stage: z.string(),
-  count: z.number().int(),
-  oldestUpdatedAt: z.string().nullable(),
-  newestUpdatedAt: z.string().nullable()
-})
-
-export const StaleDealSummarySchema = z.object({
-  id: z.string(),
-  contactEmail: z.string(),
-  cachedStage: z.string(),
-  updatedAt: z.string(),
-  daysStale: z.number().int()
-})
-
-export const DealSummaryResponseSchema = z.object({
-  totalDeals: z.number().int(),
-  openDeals: z.number().int(),
-  wonDeals: z.number().int(),
-  lostDeals: z.number().int(),
-  winRate: z.number(),
-  avgDealSize: z.number(),
-  totalPipelineValue: z.number(),
-  stageSummary: z.array(DealStageSummarySchema),
-  staleDeals: z.array(StaleDealSummarySchema)
-})
-
-export const DealLookupItemSchema = z.object({
-  id: z.string(),
-  contactEmail: z.string(),
-  cachedStage: z.string().nullable(),
-  updatedAt: z.string(),
-  contactName: z.string().nullable(),
-  companyName: z.string().nullable(),
-  displayLabel: z.string()
-})
-
-export const DealLookupResponseSchema = z.array(DealLookupItemSchema)
+  contact: DealContactSummarySchema.nullable()
+})
+
+export const DealListResponseSchema = z.object({
+  data: z.array(DealListItemSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+
+export const DealStageSummarySchema = z.object({
+  stage: z.string(),
+  count: z.number().int(),
+  totalValue: z.number(),
+  oldestUpdatedAt: z.string().nullable(),
+  newestUpdatedAt: z.string().nullable()
+})
+
+export const StaleDealSummarySchema = z.object({
+  id: z.string(),
+  contactEmail: z.string(),
+  stageKey: z.string(),
+  updatedAt: z.string(),
+  daysStale: z.number().int()
+})
+
+export const DealSummaryResponseSchema = z.object({
+  totalDeals: z.number().int(),
+  openDeals: z.number().int(),
+  wonDeals: z.number().int(),
+  lostDeals: z.number().int(),
+  winRate: z.number(),
+  avgDealSize: z.number(),
+  totalPipelineValue: z.number(),
+  stageSummary: z.array(DealStageSummarySchema),
+  staleDeals: z.array(StaleDealSummarySchema)
+})
+
+export const DealLookupItemSchema = z.object({
+  id: z.string(),
+  contactEmail: z.string(),
+  stageKey: z.string().nullable(),
+  updatedAt: z.string(),
+  contactName: z.string().nullable(),
+  companyName: z.string().nullable(),
+  displayLabel: z.string()
+})
+
+export const DealLookupResponseSchema = z.array(DealLookupItemSchema)
 
 /**
  * Deal detail shape — currently the same as a list item (full joined record).
@@ -250,20 +270,22 @@ export const DealSchemas = {
   DealTaskIdParams: DealTaskIdParamsSchema,
 
   // Queries
-  ListDealsQuery: ListDealsQuerySchema,
-  DealLookupQuery: DealLookupQuerySchema,
-  ListDealTasksDueQuery: ListDealTasksDueQuerySchema,
+  ListDealsQuery: ListDealsQuerySchema,
+  DealLookupQuery: DealLookupQuerySchema,
+  ListDealTasksDueQuery: ListDealTasksDueQuerySchema,
 
   // Request bodies
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
-  SyncDealStageRequest: SyncDealStageRequestSchema,
+  TransitionItemRequest: TransitionItemRequestSchema,
+  ExecuteActionParams: ExecuteActionParamsSchema,
+  ExecuteActionRequest: ExecuteActionRequestSchema,
 
   // Responses
-  DealListResponse: DealListResponseSchema,
-  DealSummaryResponse: DealSummaryResponseSchema,
-  DealLookupResponse: DealLookupResponseSchema,
-  DealDetailResponse: DealDetailResponseSchema,
+  DealListResponse: DealListResponseSchema,
+  DealSummaryResponse: DealSummaryResponseSchema,
+  DealLookupResponse: DealLookupResponseSchema,
+  DealDetailResponse: DealDetailResponseSchema,
   DealNoteResponse: DealNoteResponseSchema,
   DealNoteListResponse: DealNoteListResponseSchema,
   DealTaskResponse: DealTaskResponseSchema,
@@ -278,17 +300,19 @@ export type DealStage = z.infer<typeof DealStageSchema>
 export type AcqDealTaskKind = z.infer<typeof AcqDealTaskKindSchema>
 export type DealIdParams = z.infer<typeof DealIdParamsSchema>
 export type DealTaskIdParams = z.infer<typeof DealTaskIdParamsSchema>
-export type ListDealsQuery = z.infer<typeof ListDealsQuerySchema>
-export type DealLookupQuery = z.infer<typeof DealLookupQuerySchema>
-export type ListDealTasksDueQuery = z.infer<typeof ListDealTasksDueQuerySchema>
+export type ListDealsQuery = z.infer<typeof ListDealsQuerySchema>
+export type DealLookupQuery = z.infer<typeof DealLookupQuerySchema>
+export type ListDealTasksDueQuery = z.infer<typeof ListDealTasksDueQuerySchema>
 export type CreateDealNoteRequest = z.infer<typeof CreateDealNoteRequestSchema>
 export type CreateDealTaskRequest = z.infer<typeof CreateDealTaskRequestSchema>
-export type SyncDealStageRequest = z.infer<typeof SyncDealStageRequestSchema>
-export type DealListResponse = z.infer<typeof DealListResponseSchema>
-export type DealSummaryResponse = z.infer<typeof DealSummaryResponseSchema>
-export type DealLookupItem = z.infer<typeof DealLookupItemSchema>
-export type DealLookupResponse = z.infer<typeof DealLookupResponseSchema>
-export type DealDetailResponse = z.infer<typeof DealDetailResponseSchema>
+export type TransitionItemRequest = z.infer<typeof TransitionItemRequestSchema>
+export type ExecuteActionParams = z.infer<typeof ExecuteActionParamsSchema>
+export type ExecuteActionRequest = z.infer<typeof ExecuteActionRequestSchema>
+export type DealListResponse = z.infer<typeof DealListResponseSchema>
+export type DealSummaryResponse = z.infer<typeof DealSummaryResponseSchema>
+export type DealLookupItem = z.infer<typeof DealLookupItemSchema>
+export type DealLookupResponse = z.infer<typeof DealLookupResponseSchema>
+export type DealDetailResponse = z.infer<typeof DealDetailResponseSchema>
 export type DealNoteResponse = z.infer<typeof DealNoteResponseSchema>
 export type DealNoteListResponse = z.infer<typeof DealNoteListResponseSchema>
 export type DealTaskResponse = z.infer<typeof DealTaskResponseSchema>
@@ -308,61 +332,61 @@ export type DealTaskListResponse = z.infer<typeof DealTaskListResponseSchema>
 // ---------------------------------------------------------------------------
 
 // ---------------------------------------------------------------------------
-// Primitives — list config subtrees
+// Primitives — list status enum + jsonb config schemas
 // ---------------------------------------------------------------------------
 
-export const ListQualificationSchema = z.object({
-  targetDescription: z.string(),
-  minReviewCount: z.number().int().min(0),
-  minRating: z.number().min(0).max(5),
-  excludeFranchises: z.boolean(),
-  customRules: z.string()
-})
-
-export const ListEnrichmentSchema = z.object({
-  emailDiscovery: z
-    .object({
-      primary: z.enum(['tomba', 'anymailfinder']),
-      credentialName: z.string().optional()
-    })
-    .optional(),
-  emailVerification: z
-    .object({
-      provider: z.literal('millionverifier'),
-      threshold: z.enum(['ok', 'ok+catch_all']).optional()
-    })
-    .optional()
-})
+/**
+ * Lifecycle status enum for `acq_lists.status` (mirrors DB CHECK constraint
+ * from migration 20260428000003_lead_gen_acq_lists_status_and_config.sql).
+ */
+export const ListStatusSchema = z.enum(['draft', 'enriching', 'launched', 'closing', 'archived'])
 
-export const ListPersonalizationSchema = z.object({
-  industryContext: z.string().optional(),
-  emailBody: z.string().optional(),
-  creativeDirection: z.string().optional(),
-  exclusionRules: z.array(z.string()).optional()
+/**
+ * Scraping criteria stored in `acq_lists.scraping_config` jsonb.
+ * Edited via the UI; consumed by lgn-01 prospecting workflows (Apify input shape,
+ * geography, vertical, size). All fields are optional — empty config is valid.
+ */
+export const ScrapingConfigSchema = z.object({
+  vertical: z.string().trim().max(255).optional(),
+  geography: z.string().trim().max(500).optional(),
+  size: z.string().trim().max(255).optional(),
+  apifyInput: z.record(z.string(), z.unknown()).optional()
 })
 
-export const PipelineStepSchema = z.object({
-  key: z.string(),
-  label: z.string(),
-  resourceId: z.string(),
-  inputTemplate: z.record(z.string(), z.unknown()),
-  enabled: z.boolean(),
-  order: z.number().int()
+/**
+ * ICP / qualification rubric stored in `acq_lists.icp` jsonb.
+ * Replaces the legacy `config.qualification` blob. Consumed by the
+ * company-qualification workflow.
+ */
+export const IcpRubricSchema = z.object({
+  qualificationRubricKey: z.string().trim().max(255).nullish(),
+  targetDescription: z.string().optional(),
+  minReviewCount: z.number().int().min(0).optional(),
+  minRating: z.number().min(0).max(5).optional(),
+  excludeFranchises: z.boolean().optional(),
+  customRules: z.string().optional()
 })
 
-export const ListPipelineSchema = z.object({
-  steps: z.array(PipelineStepSchema)
+/**
+ * One stage entry in a list's `pipeline_config.stages[]`. The `key` is
+ * validated against `LEAD_GEN_STAGE_CATALOG` so list pipeline definitions
+ * stay aligned with the org-os semantic layer.
+ */
+export const PipelineStageSchema = z.object({
+  key: z.string().refine((value) => Object.prototype.hasOwnProperty.call(LEAD_GEN_STAGE_CATALOG, value), {
+    message: 'pipeline stage key must match LEAD_GEN_STAGE_CATALOG'
+  }),
+  label: z.string().optional(),
+  enabled: z.boolean().optional(),
+  order: z.number().int().optional()
 })
 
 /**
- * Full ListConfig shape. `qualification` is required; everything else optional.
- * Matches `acq_lists.config` jsonb and ListConfig type in types.ts.
+ * Pipeline presentation contract stored in `acq_lists.pipeline_config` jsonb.
+ * `stages[].key` validates against the catalog; the rest is presentation only.
  */
-export const ListConfigSchema = z.object({
-  qualification: ListQualificationSchema,
-  enrichment: ListEnrichmentSchema.optional(),
-  personalization: ListPersonalizationSchema.optional(),
-  pipeline: ListPipelineSchema.optional()
+export const PipelineConfigSchema = z.object({
+  stages: z.array(PipelineStageSchema).optional()
 })
 
 // ---------------------------------------------------------------------------
@@ -413,44 +437,49 @@ export const CreateListRequestSchema = z
   .object({
     name: z.string().trim().min(1).max(255),
     description: z.string().trim().nullable().optional(),
-    type: z.string().default('manual'),
-    config: ListConfigSchema.optional()
+    status: ListStatusSchema.optional(),
+    scrapingConfig: ScrapingConfigSchema.optional(),
+    icp: IcpRubricSchema.optional(),
+    pipelineConfig: PipelineConfigSchema.optional()
+  })
+  .strict()
+
+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()
   })
   .strict()
+  .refine((data) => data.name !== undefined || data.description !== undefined || data.batchIds !== undefined, {
+    message: 'At least one field (name, description, or batchIds) must be provided'
+  })
 
-export const UpdateListRequestSchema = z
-  .object({
-    name: z.string().trim().min(1).max(255).optional(),
-    description: z.string().trim().nullable().optional(),
-    status: z.string().optional(),
-    batchIds: z.array(z.string()).optional()
-  })
-  .strict()
-  .refine(
-    (data) =>
-      data.name !== undefined ||
-      data.description !== undefined ||
-      data.status !== undefined ||
-      data.batchIds !== undefined,
-    {
-      message: 'At least one field (name, description, status, or batchIds) must be provided'
-    }
-  )
+/**
+ * Status-only PATCH body for `/acquisition/lists/:listId/status`.
+ * Replaces the previous `transitionList` flow.
+ */
+export const UpdateListStatusRequestSchema = z
+  .object({
+    status: ListStatusSchema
+  })
+  .strict()
 
 /**
- * Partial patch for list.config — UI sends only the edited tab's subtree.
- * Zod v4: use .partial() on each subtree and remake the root schema.
- * Since the root ListConfigSchema marks `qualification` as required, we must
- * produce a manually-built deep-partial that makes qualification optional too.
+ * Partial patch for the three jsonb config columns. UI sends only the edited
+ * subtree; server writes the field as-is (no deep merge — each column is
+ * replaced atomically when present in the patch).
  */
 export const UpdateListConfigRequestSchema = z
   .object({
-    qualification: ListQualificationSchema.partial().optional(),
-    enrichment: ListEnrichmentSchema.partial().optional(),
-    personalization: ListPersonalizationSchema.partial().optional(),
-    pipeline: ListPipelineSchema.partial().optional()
+    scrapingConfig: ScrapingConfigSchema.partial().optional(),
+    icp: IcpRubricSchema.partial().optional(),
+    pipelineConfig: PipelineConfigSchema.partial().optional()
   })
   .strict()
+  .refine((data) => data.scrapingConfig !== undefined || data.icp !== undefined || data.pipelineConfig !== undefined, {
+    message: 'At least one of scrapingConfig, icp, or pipelineConfig must be provided'
+  })
 
 export const AddCompaniesToListRequestSchema = z
   .object({
@@ -493,12 +522,18 @@ export const AcqListResponseSchema = z.object({
   type: z.string(),
   batchIds: z.array(z.string()),
   instantlyCampaignId: z.string().nullable(),
-  status: z.string(),
+  /** Lifecycle status (draft | enriching | launched | closing | archived). */
+  status: ListStatusSchema,
   metadata: z.record(z.string(), z.unknown()),
   launchedAt: z.string().nullable(),
   completedAt: z.string().nullable(),
   createdAt: z.string(),
-  config: ListConfigSchema
+  /** Scraping criteria stored as jsonb on the row. */
+  scrapingConfig: ScrapingConfigSchema,
+  /** ICP / qualification rubric stored as jsonb on the row. */
+  icp: IcpRubricSchema,
+  /** Pipeline presentation contract stored as jsonb on the row. */
+  pipelineConfig: PipelineConfigSchema
 })
 
 export const AcqListListResponseSchema = z.array(AcqListResponseSchema)
@@ -507,6 +542,28 @@ export const ListTelemetryResponseSchema = ListTelemetrySchema
 
 export const ListTelemetryListResponseSchema = z.array(ListTelemetrySchema)
 
+/**
+ * Per-stage progress aggregate for a single pipeline stage.
+ * `done` = count of members/companies where `(processing_state->>'<key>')::boolean` is true.
+ * `total` = total member/company count for the list.
+ */
+export const ListStageProgressSchema = z.object({
+  done: z.number().int().min(0),
+  total: z.number().int().min(0)
+})
+
+/**
+ * Progress response for GET /acquisition/lists/:listId/progress.
+ * Aggregated on-demand via COUNT(*) FILTER over processing_state flags (Decision #4).
+ * `byStage` keys are driven by the list's pipeline_config.stages[].key.
+ */
+export const ListProgressResponseSchema = z.object({
+  totalMembers: z.number().int().min(0),
+  totalCompanies: z.number().int().min(0),
+  byCompanyStage: z.record(z.string(), ListStageProgressSchema),
+  byContactStage: z.record(z.string(), ListStageProgressSchema)
+})
+
 /**
  * Row from acq_list_executions joined with the execution summary,
  * shaped for the /lists/:id/executions response.
@@ -544,21 +601,21 @@ export const ContactIdParamsSchema = z.object({
   contactId: UuidSchema
 })
 
-export const ListCompaniesQuerySchema = z
-  .object({
-    search: z.string().trim().min(1).max(200).optional(),
-    listId: UuidSchema.optional(),
-    domain: z.string().trim().min(1).max(255).optional(),
+export const ListCompaniesQuerySchema = z
+  .object({
+    search: z.string().trim().min(1).max(200).optional(),
+    listId: UuidSchema.optional(),
+    domain: z.string().trim().min(1).max(255).optional(),
     website: z.string().trim().min(1).max(2048).optional(),
     segment: z.string().trim().min(1).max(255).optional(),
-    category: z.string().trim().min(1).max(255).optional(),
-    batchId: z.string().trim().min(1).max(255).optional(),
-    status: AcqCompanyStatusSchema.optional(),
-    includeAll: QueryBooleanSchema.optional(),
-    limit: z.coerce.number().int().min(1).max(5000).default(50),
-    offset: z.coerce.number().int().min(0).default(0)
-  })
-  .strict()
+    category: z.string().trim().min(1).max(255).optional(),
+    batchId: z.string().trim().min(1).max(255).optional(),
+    status: AcqCompanyStatusSchema.optional(),
+    includeAll: QueryBooleanSchema.optional(),
+    limit: z.coerce.number().int().min(1).max(5000).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
 
 export const ListContactsQuerySchema = z
   .object({
@@ -681,10 +738,10 @@ export const UpdateContactRequestSchema = z
     }
   )
 
-export const AcqCompanyResponseSchema = z.object({
-  id: z.string(),
-  organizationId: z.string(),
-  name: z.string(),
+export const AcqCompanyResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  name: z.string(),
   domain: z.string().nullable(),
   linkedinUrl: z.string().nullable(),
   website: z.string().nullable(),
@@ -698,41 +755,41 @@ export const AcqCompanyResponseSchema = z.object({
   pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
   source: z.string().nullable(),
-  batchId: z.string().nullable(),
-  status: AcqCompanyStatusSchema,
-  contactCount: z.number().int().min(0),
-  verticalResearch: z.string().nullable(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-})
-
-export const AcqCompanyListResponseSchema = z.object({
-  data: z.array(AcqCompanyResponseSchema),
-  total: z.number().int(),
-  limit: z.number().int(),
-  offset: z.number().int()
-})
-
-export const AcqCompanyFacetsResponseSchema = z.object({
-  segments: z.array(z.string()),
-  categories: z.array(z.string()),
-  statuses: z.array(AcqCompanyStatusSchema)
-})
-
-export const AcqContactCompanySummarySchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  domain: z.string().nullable(),
-  website: z.string().nullable(),
-  linkedinUrl: z.string().nullable(),
-  segment: z.string().nullable(),
-  category: z.string().nullable(),
-  status: AcqCompanyStatusSchema
-})
-
-export const AcqContactResponseSchema = z.object({
-  id: z.string(),
-  organizationId: z.string(),
+  batchId: z.string().nullable(),
+  status: AcqCompanyStatusSchema,
+  contactCount: z.number().int().min(0),
+  verticalResearch: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
+
+export const AcqCompanyListResponseSchema = z.object({
+  data: z.array(AcqCompanyResponseSchema),
+  total: z.number().int(),
+  limit: z.number().int(),
+  offset: z.number().int()
+})
+
+export const AcqCompanyFacetsResponseSchema = z.object({
+  segments: z.array(z.string()),
+  categories: z.array(z.string()),
+  statuses: z.array(AcqCompanyStatusSchema)
+})
+
+export const AcqContactCompanySummarySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  domain: z.string().nullable(),
+  website: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  segment: z.string().nullable(),
+  category: z.string().nullable(),
+  status: AcqCompanyStatusSchema
+})
+
+export const AcqContactResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
   companyId: z.string().nullable(),
   email: z.string(),
   emailValid: AcqEmailValidSchema.nullable(),
@@ -747,13 +804,13 @@ export const AcqContactResponseSchema = z.object({
   sourceId: z.string().nullable(),
   pipelineStatus: z.record(z.string(), z.unknown()).nullable(),
   enrichmentData: z.record(z.string(), z.unknown()).nullable(),
-  attioPersonId: z.string().nullable(),
-  batchId: z.string().nullable(),
-  status: AcqContactStatusSchema,
-  company: AcqContactCompanySummarySchema.nullable().optional(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-})
+  attioPersonId: z.string().nullable(),
+  batchId: z.string().nullable(),
+  status: AcqContactStatusSchema,
+  company: AcqContactCompanySummarySchema.nullable().optional(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+})
 
 export const AcqContactListResponseSchema = z.object({
   data: z.array(AcqContactResponseSchema),
@@ -762,15 +819,124 @@ export const AcqContactListResponseSchema = z.object({
   offset: z.number().int()
 })
 
+// ---------------------------------------------------------------------------
+// Track A: Artifacts API Schemas
+// ---------------------------------------------------------------------------
+
+export const AcqArtifactOwnerKindSchema = z.enum(['company', 'contact', 'deal', 'list', 'list_member'])
+
+export const ListArtifactsQuerySchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema
+  })
+  .strict()
+
+export const CreateArtifactRequestSchema = z
+  .object({
+    ownerKind: AcqArtifactOwnerKindSchema,
+    ownerId: UuidSchema,
+    kind: z.string().trim().min(1).max(255),
+    content: z.record(z.string(), z.unknown()),
+    sourceExecutionId: UuidSchema.optional()
+  })
+  .strict()
+
+export const AcqArtifactResponseSchema = z.object({
+  id: z.string(),
+  organizationId: z.string(),
+  ownerKind: z.string(),
+  ownerId: z.string(),
+  kind: z.string(),
+  content: z.record(z.string(), z.unknown()),
+  sourceExecutionId: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  version: z.number().int()
+})
+
+export const AcqArtifactListResponseSchema = z.object({
+  artifacts: z.array(AcqArtifactResponseSchema)
+})
+
+// ---------------------------------------------------------------------------
+// Track B: List Members API Schemas
+// ---------------------------------------------------------------------------
+
+export const ListMembersQuerySchema = z
+  .object({
+    limit: z.coerce.number().int().min(1).max(500).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+  })
+  .strict()
+
+export const MemberIdParamsSchema = z.object({
+  memberId: UuidSchema
+})
+
+export const AcqListMemberContactSummarySchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  firstName: z.string().nullable(),
+  lastName: z.string().nullable(),
+  title: z.string().nullable(),
+  linkedinUrl: z.string().nullable(),
+  companyId: z.string().nullable()
+})
+
+export const AcqListMemberResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  contactId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable(),
+  contact: AcqListMemberContactSummarySchema.nullable()
+})
+
+export const AcqListMembersResponseSchema = z.object({
+  members: z.array(AcqListMemberResponseSchema)
+})
+
+// ---------------------------------------------------------------------------
+// Track B: List Companies API Schemas
+// ---------------------------------------------------------------------------
+
+export const ListCompanyIdParamsSchema = z.object({
+  listCompanyId: UuidSchema
+})
+
+export const AcqListCompanyResponseSchema = z.object({
+  id: z.string(),
+  listId: z.string(),
+  companyId: z.string(),
+  pipelineKey: z.string(),
+  stageKey: z.string(),
+  stateKey: z.string(),
+  activityLog: z.unknown(),
+  addedAt: z.string(),
+  addedBy: z.string().nullable(),
+  sourceExecutionId: z.string().nullable()
+})
+
+// ---------------------------------------------------------------------------
+// Track B: Transition Request (shared by list, list-member, list-company)
+// TransitionItemRequestSchema already exists above (for deals) — reuse it.
+// ---------------------------------------------------------------------------
+
 export const AcqCompanySchemas = {
   CompanyIdParams: CompanyIdParamsSchema,
   ListCompaniesQuery: ListCompaniesQuerySchema,
   CreateCompanyRequest: CreateCompanyRequestSchema,
-  UpdateCompanyRequest: UpdateCompanyRequestSchema,
-  AcqCompanyResponse: AcqCompanyResponseSchema,
-  AcqCompanyListResponse: AcqCompanyListResponseSchema,
-  AcqCompanyFacetsResponse: AcqCompanyFacetsResponseSchema
-}
+  UpdateCompanyRequest: UpdateCompanyRequestSchema,
+  AcqCompanyResponse: AcqCompanyResponseSchema,
+  AcqCompanyListResponse: AcqCompanyListResponseSchema,
+  AcqCompanyFacetsResponse: AcqCompanyFacetsResponseSchema
+}
 
 export const AcqContactSchemas = {
   ContactIdParams: ContactIdParamsSchema,
@@ -792,12 +958,12 @@ export type CreateCompanyRequest = z.infer<typeof CreateCompanyRequestSchema>
 export type UpdateCompanyRequest = z.infer<typeof UpdateCompanyRequestSchema>
 export type CreateContactRequest = z.infer<typeof CreateContactRequestSchema>
 export type UpdateContactRequest = z.infer<typeof UpdateContactRequestSchema>
-export type AcqCompanyResponse = z.infer<typeof AcqCompanyResponseSchema>
-export type AcqCompanyListResponse = z.infer<typeof AcqCompanyListResponseSchema>
-export type AcqCompanyFacetsResponse = z.infer<typeof AcqCompanyFacetsResponseSchema>
-export type AcqContactCompanySummary = z.infer<typeof AcqContactCompanySummarySchema>
-export type AcqContactResponse = z.infer<typeof AcqContactResponseSchema>
-export type AcqContactListResponse = z.infer<typeof AcqContactListResponseSchema>
+export type AcqCompanyResponse = z.infer<typeof AcqCompanyResponseSchema>
+export type AcqCompanyListResponse = z.infer<typeof AcqCompanyListResponseSchema>
+export type AcqCompanyFacetsResponse = z.infer<typeof AcqCompanyFacetsResponseSchema>
+export type AcqContactCompanySummary = z.infer<typeof AcqContactCompanySummarySchema>
+export type AcqContactResponse = z.infer<typeof AcqContactResponseSchema>
+export type AcqContactListResponse = z.infer<typeof AcqContactListResponseSchema>
 
 // ---------------------------------------------------------------------------
 // Bundled export
@@ -808,14 +974,18 @@ export const AcqListSchemas = {
   ListIdParams: ListIdParamsSchema,
 
   // Primitives (for UI / tests)
-  ListConfig: ListConfigSchema,
+  ListStatus: ListStatusSchema,
+  ScrapingConfig: ScrapingConfigSchema,
+  IcpRubric: IcpRubricSchema,
+  PipelineConfig: PipelineConfigSchema,
+  PipelineStage: PipelineStageSchema,
   ListStageCounts: ListStageCountsSchema,
   ListTelemetry: ListTelemetrySchema,
-  PipelineStep: PipelineStepSchema,
 
   // Requests
   CreateListRequest: CreateListRequestSchema,
   UpdateListRequest: UpdateListRequestSchema,
+  UpdateListStatusRequest: UpdateListStatusRequestSchema,
   UpdateListConfigRequest: UpdateListConfigRequestSchema,
   AddCompaniesToListRequest: AddCompaniesToListRequestSchema,
   RemoveCompaniesFromListRequest: RemoveCompaniesFromListRequestSchema,
@@ -827,20 +997,69 @@ export const AcqListSchemas = {
   AcqListListResponse: AcqListListResponseSchema,
   ListTelemetryResponse: ListTelemetryResponseSchema,
   ListTelemetryListResponse: ListTelemetryListResponseSchema,
-  ListExecutionsResponse: ListExecutionsResponseSchema
+  ListExecutionsResponse: ListExecutionsResponseSchema,
+  ListProgressResponse: ListProgressResponseSchema
+}
+
+// ---------------------------------------------------------------------------
+// Track A/B bundled schemas
+// ---------------------------------------------------------------------------
+
+export const AcqSubstrateSchemas = {
+  // Artifacts
+  ListArtifactsQuery: ListArtifactsQuerySchema,
+  CreateArtifactRequest: CreateArtifactRequestSchema,
+  AcqArtifactResponse: AcqArtifactResponseSchema,
+  AcqArtifactListResponse: AcqArtifactListResponseSchema,
+
+  // List members
+  ListMembersQuery: ListMembersQuerySchema,
+  MemberIdParams: MemberIdParamsSchema,
+  AcqListMemberResponse: AcqListMemberResponseSchema,
+  AcqListMembersResponse: AcqListMembersResponseSchema,
+
+  // List companies
+  ListCompanyIdParams: ListCompanyIdParamsSchema,
+  AcqListCompanyResponse: AcqListCompanyResponseSchema,
+
+  // Transition (shared with deals — TransitionItemRequestSchema)
+  TransitionItemRequest: TransitionItemRequestSchema
 }
 
 // ---------------------------------------------------------------------------
 // Inferred types
 // ---------------------------------------------------------------------------
 
-export type ListConfigInput = z.infer<typeof ListConfigSchema>
+// ---------------------------------------------------------------------------
+// Inferred types — Track A/B substrate
+// ---------------------------------------------------------------------------
+
+export type AcqArtifactOwnerKind = z.infer<typeof AcqArtifactOwnerKindSchema>
+export type ListArtifactsQuery = z.infer<typeof ListArtifactsQuerySchema>
+export type CreateArtifactRequest = z.infer<typeof CreateArtifactRequestSchema>
+export type AcqArtifactResponse = z.infer<typeof AcqArtifactResponseSchema>
+export type AcqArtifactListResponse = z.infer<typeof AcqArtifactListResponseSchema>
+export type ListMembersQuery = z.infer<typeof ListMembersQuerySchema>
+export type MemberIdParams = z.infer<typeof MemberIdParamsSchema>
+export type AcqListMemberContactSummary = z.infer<typeof AcqListMemberContactSummarySchema>
+export type AcqListMemberResponse = z.infer<typeof AcqListMemberResponseSchema>
+export type AcqListMembersResponse = z.infer<typeof AcqListMembersResponseSchema>
+export type ListCompanyIdParams = z.infer<typeof ListCompanyIdParamsSchema>
+export type AcqListCompanyResponse = z.infer<typeof AcqListCompanyResponseSchema>
+
+// ---------------------------------------------------------------------------
+
+export type ListStatus = z.infer<typeof ListStatusSchema>
+export type ScrapingConfig = z.infer<typeof ScrapingConfigSchema>
+export type IcpRubric = z.infer<typeof IcpRubricSchema>
+export type PipelineStage = z.infer<typeof PipelineStageSchema>
+export type PipelineConfig = z.infer<typeof PipelineConfigSchema>
 export type ListStageCountsInput = z.infer<typeof ListStageCountsSchema>['stageCounts']
 export type ListTelemetryInput = z.infer<typeof ListTelemetrySchema>
-export type PipelineStepInput = z.infer<typeof PipelineStepSchema>
 export type ListIdParams = z.infer<typeof ListIdParamsSchema>
 export type CreateListRequest = z.infer<typeof CreateListRequestSchema>
 export type UpdateListRequest = z.infer<typeof UpdateListRequestSchema>
+export type UpdateListStatusRequest = z.infer<typeof UpdateListStatusRequestSchema>
 export type UpdateListConfigRequest = z.infer<typeof UpdateListConfigRequestSchema>
 export type AddCompaniesToListRequest = z.infer<typeof AddCompaniesToListRequestSchema>
 export type RemoveCompaniesFromListRequest = z.infer<typeof RemoveCompaniesFromListRequestSchema>
@@ -852,3 +1071,5 @@ export type ListTelemetryResponse = z.infer<typeof ListTelemetryResponseSchema>
 export type ListTelemetryListResponse = z.infer<typeof ListTelemetryListResponseSchema>
 export type ListExecutionSummaryInput = z.infer<typeof ListExecutionSummarySchema>
 export type ListExecutionsResponse = z.infer<typeof ListExecutionsResponseSchema>
+export type ListStageProgress = z.infer<typeof ListStageProgressSchema>
+export type ListProgress = z.infer<typeof ListProgressResponseSchema>