@elevasis/core 0.18.0 → 0.20.0

package/src/auth/multi-tenancy/organizations/api-schemas.ts

@@ -1,128 +1,136 @@
-/**
- * Organizations Domain - Zod Validation Schemas
- *
- * Validation schemas for organization management endpoints.
- * Includes request bodies, query params, and path params.
- *
- * Security:
- * - All schemas use .strict() to prevent mass assignment attacks
- * - UUID/WorkOS ID validation prevents invalid references
- * - String length limits prevent DoS
- * - Domain and metadata size limits
- */
-
-import { z } from 'zod'
-import { UuidSchema } from '../../../platform/utils/validation'
-
-// ============================================================================
-// Shared Schemas
-// ============================================================================
-
-/**
- * Organization name validation
- * - Alphanumeric, spaces, hyphens, underscores only
- * - 2-100 characters
- *
- * Security: Prevents injection, DoS via long names
- */
-export const OrganizationNameSchema = z.string()
-  .min(2, 'Organization name must be at least 2 characters')
-  .max(100, 'Organization name must be at most 100 characters')
-  .trim()
-  .regex(/^[a-zA-Z0-9\s\-_]+$/, 'Organization name must contain only letters, numbers, spaces, hyphens, and underscores')
-
-/**
- * Organization ID validation
- * Supports both UUID and WorkOS org_ prefixed IDs
- */
-export const OrganizationIdSchema = z.union([
-  UuidSchema,
-  z.string().regex(/^org_[a-zA-Z0-9]+$/, 'Invalid WorkOS organization ID')
-])
-
-/**
- * Organization domain data schema
- */
-export const OrganizationDomainSchema = z.object({
-  domain: z.string().min(3).max(255),
-  state: z.enum(['verified', 'pending', 'failed']).optional()
-})
-
-// ============================================================================
-// Path Parameters
-// ============================================================================
-
-/**
- * Validate organization ID in URL path
- * Used by: GET/PUT/DELETE /organizations/:id
- */
-export const OrganizationIdParamSchema = z
-  .object({
-    id: OrganizationIdSchema
-  })
-  .strict()
-
-// ============================================================================
-// Request Bodies
-// ============================================================================
-
-/**
- * Create new organization
- * POST /organizations
- *
- * Security:
- * - Name format validated (alphanumeric + spaces + hyphens + underscores)
- * - Domain array size limited (max 10)
- * - Metadata size limited (10KB)
- * - Strict mode prevents unknown field injection
- */
-export const CreateOrganizationSchema = z
-  .object({
-    name: OrganizationNameSchema,
-    domainData: z.array(OrganizationDomainSchema).max(10).optional(),
-    metadata: z.record(z.string(), z.unknown())
-      .refine(
-        val => JSON.stringify(val).length <= 10240,
-        'Metadata must be under 10KB'
-      )
-      .optional()
-  })
-  .strict()
-
-/**
- * Update organization
- * PUT /organizations/:id
- *
- * Security:
- * - All fields optional (partial update)
- * - Same validation as create
- */
-export const UpdateOrganizationSchema = CreateOrganizationSchema.partial().strict()
-
-// ============================================================================
-// Query Parameters
-// ============================================================================
-
-/**
- * List organizations with filters
- * GET /organizations
- *
- * Security:
- * - Limit bounded (prevents DoS)
- * - WorkOS pagination cursors
- */
-export const ListOrganizationsQuerySchema = z.object({
-  limit: z.coerce.number().int().min(1).max(100).default(20),
-  before: z.string().optional(), // WorkOS pagination cursor
-  after: z.string().optional()   // WorkOS pagination cursor
-})
-
-// ============================================================================
-// TypeScript Type Exports
-// ============================================================================
-
-// Export inferred types for use in route handlers
-export type CreateOrganizationInput = z.infer<typeof CreateOrganizationSchema>
-export type UpdateOrganizationInput = z.infer<typeof UpdateOrganizationSchema>
-export type ListOrganizationsQuery = z.infer<typeof ListOrganizationsQuerySchema>
-export type OrganizationIdParam = z.infer<typeof OrganizationIdParamSchema>
+/**
+ * Organizations Domain - Zod Validation Schemas
+ *
+ * Validation schemas for organization management endpoints.
+ * Includes request bodies, query params, and path params.
+ *
+ * Security:
+ * - All schemas use .strict() to prevent mass assignment attacks
+ * - UUID/WorkOS ID validation prevents invalid references
+ * - String length limits prevent DoS
+ * - Domain and metadata size limits
+ */
+
+import { z } from 'zod'
+import { UuidSchema } from '../../../platform/utils/validation'
+
+// ============================================================================
+// Shared Schemas
+// ============================================================================
+
+/**
+ * Organization name validation
+ * - Alphanumeric, spaces, hyphens, underscores only
+ * - 2-100 characters
+ *
+ * Security: Prevents injection, DoS via long names
+ */
+export const OrganizationNameSchema = z
+  .string()
+  .min(2, 'Organization name must be at least 2 characters')
+  .max(100, 'Organization name must be at most 100 characters')
+  .trim()
+  .regex(
+    /^[a-zA-Z0-9\s\-_]+$/,
+    'Organization name must contain only letters, numbers, spaces, hyphens, and underscores'
+  )
+
+/**
+ * Organization ID validation
+ * Supports both UUID and WorkOS org_ prefixed IDs
+ */
+export const OrganizationIdSchema = z.union([
+  UuidSchema,
+  z.string().regex(/^org_[a-zA-Z0-9]+$/, 'Invalid WorkOS organization ID')
+])
+
+/**
+ * Organization domain data schema
+ */
+export const OrganizationDomainSchema = z.object({
+  domain: z.string().min(3).max(255),
+  state: z.enum(['verified', 'pending', 'failed']).optional()
+})
+
+// ============================================================================
+// Path Parameters
+// ============================================================================
+
+/**
+ * Validate organization ID in URL path
+ * Used by: GET/PUT/DELETE /organizations/:id
+ */
+export const OrganizationIdParamSchema = z
+  .object({
+    id: OrganizationIdSchema
+  })
+  .strict()
+
+// ============================================================================
+// Request Bodies
+// ============================================================================
+
+/**
+ * Create new organization
+ * POST /organizations
+ *
+ * Security:
+ * - Name format validated (alphanumeric + spaces + hyphens + underscores)
+ * - Domain array size limited (max 10)
+ * - Metadata size limited (10KB)
+ * - Strict mode prevents unknown field injection
+ */
+export const CreateOrganizationSchema = z
+  .object({
+    name: OrganizationNameSchema,
+    domainData: z.array(OrganizationDomainSchema).max(10).optional(),
+    metadata: z
+      .record(z.string(), z.unknown())
+      .refine((val) => JSON.stringify(val).length <= 10240, 'Metadata must be under 10KB')
+      .optional()
+  })
+  .strict()
+
+/**
+ * Update organization
+ * PUT /organizations/:id
+ *
+ * Security:
+ * - All fields optional (partial update)
+ * - Same validation as create
+ * - At least one field required (matches documented Update schema convention,
+ *   see .claude/rules/core-package.md → "api-schemas.ts Pattern")
+ */
+export const UpdateOrganizationSchema = CreateOrganizationSchema.partial()
+  .strict()
+  .refine((data) => Object.keys(data).length > 0, {
+    message: 'At least one field (name, domainData, or metadata) must be provided'
+  })
+
+// ============================================================================
+// Query Parameters
+// ============================================================================
+
+/**
+ * List organizations with filters
+ * GET /organizations
+ *
+ * Security:
+ * - Limit bounded (prevents DoS)
+ * - WorkOS pagination cursors
+ */
+export const ListOrganizationsQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  before: z.string().optional(), // WorkOS pagination cursor
+  after: z.string().optional() // WorkOS pagination cursor
+})
+
+// ============================================================================
+// TypeScript Type Exports
+// ============================================================================
+
+// Export inferred types for use in route handlers
+export type CreateOrganizationInput = z.infer<typeof CreateOrganizationSchema>
+export type UpdateOrganizationInput = z.infer<typeof UpdateOrganizationSchema>
+export type ListOrganizationsQuery = z.infer<typeof ListOrganizationsQuerySchema>
+export type OrganizationIdParam = z.infer<typeof OrganizationIdParamSchema>

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
+  CRM_PIPELINE_DEFINITION,
   DEFAULT_CRM_PRIORITY_RULE_CONFIG,
   LEAD_GEN_PIPELINE_DEFINITIONS,
   LEAD_GEN_STAGE_CATALOG
@@ -13,11 +14,15 @@ import {
   AcqContactStatusSchema,
   AcqEmailValidSchema,
   AcqListResponseSchema,
+  BuildPlanSnapshotSchema,
   CreateArtifactRequestSchema,
   CreateCompanyRequestSchema,
   CreateContactRequestSchema,
   CreateDealNoteRequestSchema,
   CreateDealTaskRequestSchema,
+  CrmStageKeySchema,
+  CrmStateKeySchema,
+  CrmTransitionItemRequestSchema,
   CreateListRequestSchema,
   DealDetailResponseSchema,
   DealListItemSchema,
@@ -36,6 +41,7 @@ import {
   ListStatusSchema,
   PipelineStageSchema,
   ScrapingConfigSchema,
+  TransitionDealStateRequestSchema,
   TransitionItemRequestSchema,
   UpdateCompanyRequestSchema,
   UpdateContactRequestSchema,
@@ -43,6 +49,7 @@ import {
   UpdateListRequestSchema,
   UpdateListStatusRequestSchema
 } from './api-schemas'
+import { createBuildPlanSnapshotFromTemplateId } from './build-templates'
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -65,17 +72,31 @@ const PRIORITY = {
 // ---------------------------------------------------------------------------
 
 describe('DealStageSchema', () => {
-  it.each(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])(
-    'accepts canonical stage "%s"',
-    (stage) => {
-      expect(DealStageSchema.safeParse(stage).success).toBe(true)
-    }
-  )
+  const crmStageKeys = CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)
+  const crmStateKeys = CRM_PIPELINE_DEFINITION.stages.flatMap((stage) => stage.states.map((state) => state.stateKey))
+
+  it('derives CRM stage keys from CRM_PIPELINE_DEFINITION', () => {
+    expect(CrmStageKeySchema.options).toEqual(crmStageKeys)
+    expect(DealStageSchema.options).toEqual(crmStageKeys)
+  })
+
+  it('derives CRM state keys from CRM_PIPELINE_DEFINITION', () => {
+    expect(CrmStateKeySchema.options).toEqual(crmStateKeys)
+  })
+
+  it.each(crmStageKeys)('accepts canonical stage "%s"', (stage) => {
+    expect(DealStageSchema.safeParse(stage).success).toBe(true)
+  })
 
   it('rejects an unknown stage value', () => {
     expect(DealStageSchema.safeParse('open').success).toBe(false)
     expect(DealStageSchema.safeParse('').success).toBe(false)
   })
+
+  it('rejects unknown CRM state values', () => {
+    expect(CrmStateKeySchema.safeParse('custom_state').success).toBe(false)
+    expect(CrmStateKeySchema.safeParse('').success).toBe(false)
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -84,7 +105,7 @@ describe('DealStageSchema', () => {
 
 describe('TransitionItemRequestSchema', () => {
   const valid = {
-    pipelineKey: 'default',
+    pipelineKey: 'lead-gen',
     stageKey: 'interested',
     stateKey: null
   }
@@ -120,11 +141,16 @@ describe('TransitionItemRequestSchema', () => {
   })
 
   it('accepts all canonical CRM deal stages', () => {
-    const stages = ['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing']
-    for (const stageKey of stages) {
-      expect(TransitionItemRequestSchema.safeParse({ pipelineKey: 'default', stageKey, stateKey: null }).success).toBe(
-        true
-      )
+    for (const stageKey of CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)) {
+      expect(TransitionItemRequestSchema.safeParse({ pipelineKey: 'crm', stageKey, stateKey: null }).success).toBe(true)
+    }
+  })
+
+  it('accepts catalog-derived CRM state keys', () => {
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(TransitionItemRequestSchema.safeParse({ ...valid, stateKey }).success).toBe(true)
     }
   })
 
@@ -156,6 +182,11 @@ describe('TransitionItemRequestSchema', () => {
     expect(result.success).toBe(false)
   })
 
+  it('accepts unknown non-empty stage and state keys for generic substrate transitions', () => {
+    expect(TransitionItemRequestSchema.safeParse({ ...valid, stageKey: 'custom_stage' }).success).toBe(true)
+    expect(TransitionItemRequestSchema.safeParse({ ...valid, stateKey: 'custom_state' }).success).toBe(true)
+  })
+
   it('rejects unknown top-level fields (strict mode)', () => {
     const result = TransitionItemRequestSchema.safeParse({ ...valid, unknownField: 'x' })
     expect(result.success).toBe(false)
@@ -174,6 +205,64 @@ describe('TransitionItemRequestSchema', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// CrmTransitionItemRequestSchema
+// ---------------------------------------------------------------------------
+
+describe('CrmTransitionItemRequestSchema', () => {
+  const valid = {
+    pipelineKey: 'crm',
+    stageKey: 'interested',
+    stateKey: null
+  }
+
+  it('accepts catalog-derived CRM stage and state keys', () => {
+    for (const stageKey of CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)) {
+      expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stageKey }).success).toBe(true)
+    }
+
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stateKey }).success).toBe(true)
+    }
+  })
+
+  it('rejects non-CRM pipeline keys and unknown CRM keys', () => {
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, pipelineKey: 'lead-gen' }).success).toBe(false)
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stageKey: 'unknown_stage' }).success).toBe(false)
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stateKey: 'unknown_state' }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TransitionDealStateRequestSchema
+// ---------------------------------------------------------------------------
+
+describe('TransitionDealStateRequestSchema', () => {
+  it('accepts catalog-derived CRM state keys', () => {
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(TransitionDealStateRequestSchema.safeParse({ stateKey }).success).toBe(true)
+    }
+  })
+
+  it('rejects unknown state values', () => {
+    expect(TransitionDealStateRequestSchema.safeParse({ stateKey: 'unknown_state' }).success).toBe(false)
+    expect(TransitionDealStateRequestSchema.safeParse({ stateKey: '' }).success).toBe(false)
+  })
+
+  it('preserves strict request schema behavior', () => {
+    expect(
+      TransitionDealStateRequestSchema.safeParse({
+        stateKey: CRM_PIPELINE_DEFINITION.stages[0]?.states[0]?.stateKey,
+        extra: 'x'
+      }).success
+    ).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // ExecuteActionRequestSchema
 // ---------------------------------------------------------------------------
@@ -416,6 +505,22 @@ describe('UpdateContactRequestSchema', () => {
     )
   })
 
+  it('accepts processingState keyed by the stage catalog', () => {
+    const result = UpdateContactRequestSchema.safeParse({
+      processingState: {
+        [LEAD_GEN_STAGE_CATALOG.verified.key]: {
+          status: 'no_result'
+        }
+      }
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts deprecated pipelineStatus as a compatibility no-op', () => {
+    expect(UpdateContactRequestSchema.safeParse({ pipelineStatus: 'emailed' }).success).toBe(true)
+  })
+
   it('rejects unknown top-level fields (strict mode)', () => {
     expect(UpdateContactRequestSchema.safeParse({ firstName: 'Alice', unknown: 'x' }).success).toBe(false)
   })
@@ -680,7 +785,7 @@ describe('DealDetailResponseSchema (forward-compat)', () => {
     organization_id: VALID_UUID,
     contact_id: null,
     contact_email: 'test@example.com',
-    pipeline_key: 'default',
+    pipeline_key: 'crm',
     stage_key: null,
     state_key: null,
     activity_log: [],
@@ -743,7 +848,7 @@ describe('DealDetailResponseSchema (forward-compat)', () => {
         title: null,
         headline: null,
         linkedin_url: null,
-        pipeline_status: null,
+        processing_state: null,
         enrichment_data: null,
         company: null
       }
@@ -881,6 +986,58 @@ describe('PipelineStageSchema', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// BuildPlanSnapshotSchema
+// ---------------------------------------------------------------------------
+
+describe('BuildPlanSnapshotSchema', () => {
+  const validSnapshot = createBuildPlanSnapshotFromTemplateId('dtc-subscription-apollo-clickup')
+
+  it('accepts a snapshot generated from a prospecting build template', () => {
+    expect(validSnapshot).not.toBeNull()
+    expect(BuildPlanSnapshotSchema.safeParse(validSnapshot).success).toBe(true)
+  })
+
+  it('rejects a step stageKey outside LEAD_GEN_STAGE_CATALOG', () => {
+    const result = BuildPlanSnapshotSchema.safeParse({
+      ...validSnapshot,
+      steps: [{ ...validSnapshot!.steps[0], stageKey: 'made-up-stage' }]
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects a step capabilityKey outside CAPABILITY_REGISTRY', () => {
+    const result = BuildPlanSnapshotSchema.safeParse({
+      ...validSnapshot,
+      steps: [{ ...validSnapshot!.steps[0], capabilityKey: 'lead-gen.missing.capability' }]
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects duplicate step ids', () => {
+    const first = validSnapshot!.steps[0]!
+    const second = validSnapshot!.steps[1]!
+    const rest = validSnapshot!.steps.slice(2)
+    const result = BuildPlanSnapshotSchema.safeParse({
+      ...validSnapshot,
+      steps: [first, { ...second, id: first.id }, ...rest]
+    })
+
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects dependsOn references to unknown step ids', () => {
+    const result = BuildPlanSnapshotSchema.safeParse({
+      ...validSnapshot,
+      steps: [{ ...validSnapshot!.steps[0], dependsOn: ['missing-step'] }]
+    })
+
+    expect(result.success).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // ScrapingConfigSchema
 // ---------------------------------------------------------------------------
@@ -1255,6 +1412,33 @@ describe('UpdateCompanyRequestSchema', () => {
     expect(UpdateCompanyRequestSchema.safeParse({ status: 'invalid' }).success).toBe(true)
   })
 
+  it('accepts processingState keyed by the stage catalog', () => {
+    const result = UpdateCompanyRequestSchema.safeParse({
+      processingState: {
+        [LEAD_GEN_STAGE_CATALOG.qualified.key]: {
+          status: 'success',
+          data: { score: 92 }
+        }
+      }
+    })
+
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts deprecated pipelineStatus as a compatibility no-op', () => {
+    expect(UpdateCompanyRequestSchema.safeParse({ pipelineStatus: 'emailed' }).success).toBe(true)
+  })
+
+  it('rejects processingState keys outside the stage catalog', () => {
+    expect(
+      UpdateCompanyRequestSchema.safeParse({
+        processingState: {
+          madeUpStage: { status: 'success' }
+        }
+      }).success
+    ).toBe(false)
+  })
+
   it('accepts numEmployees of 0', () => {
     expect(UpdateCompanyRequestSchema.safeParse({ numEmployees: 0 }).success).toBe(true)
   })
@@ -1468,7 +1652,7 @@ describe('AcqContactResponseSchema (forward-compat)', () => {
     openingLine: null,
     source: null,
     sourceId: null,
-    pipelineStatus: null,
+    processingState: null,
     enrichmentData: null,
     attioPersonId: null,
     batchId: null,