@elevasis/core 0.15.0 → 0.15.1

package/src/business/acquisition/build-templates.ts

@@ -0,0 +1,44 @@
+import { DEFAULT_ORGANIZATION_MODEL_PROSPECTING } from '../../organization-model/domains/prospecting'
+import type { BuildPlanSnapshot, BuildPlanSnapshotStep } from './types'
+
+export const PROSPECTING_BUILD_TEMPLATE_OPTIONS = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates.map(
+  ({ id, label, description }) => ({
+    id,
+    label,
+    description
+  })
+)
+
+export const DEFAULT_PROSPECTING_BUILD_TEMPLATE_ID = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.defaultBuildTemplateId
+
+export function isProspectingBuildTemplateId(value: string): boolean {
+  return PROSPECTING_BUILD_TEMPLATE_OPTIONS.some((template) => template.id === value)
+}
+
+export function createBuildPlanSnapshotFromTemplateId(templateId: string): BuildPlanSnapshot | null {
+  const template = DEFAULT_ORGANIZATION_MODEL_PROSPECTING.buildTemplates.find((item) => item.id === templateId)
+  if (!template) return null
+
+  return {
+    templateId: template.id,
+    templateLabel: template.label,
+    steps: template.steps.map((step): BuildPlanSnapshotStep => {
+      const snapshotStep: BuildPlanSnapshotStep = {
+        id: step.id,
+        label: step.label,
+        primaryEntity: step.primaryEntity,
+        outputs: [...step.outputs],
+        stageKey: step.stageKey,
+        dependencyMode: step.dependencyMode,
+        capabilityKey: step.capabilityKey,
+        defaultBatchSize: step.defaultBatchSize,
+        maxBatchSize: step.maxBatchSize
+      }
+
+      if (step.description) snapshotStep.description = step.description
+      if (step.dependsOn?.length) snapshotStep.dependsOn = [...step.dependsOn]
+
+      return snapshotStep
+    })
+  }
+}

package/src/business/acquisition/crm-next-action.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from 'vitest'
+import { evaluateCrmDealNextAction, resolveCrmNextActionRuleConfig } from './crm-next-action'
+import { DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG } from '../../organization-model/domains/sales'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEvent(type: string, timestamp: string): Record<string, unknown> {
+  return { type, timestamp }
+}
+
+const INBOUND = 'reply_received'
+const OUTBOUND = 'reply_sent_to_lead'
+
+// ---------------------------------------------------------------------------
+// Closed deals → null
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealNextAction — closed deals', () => {
+  it('returns null for closed_won regardless of activity', () => {
+    expect(
+      evaluateCrmDealNextAction({
+        stage_key: 'interested',
+        state_key: 'closed_won',
+        activity_log: [makeEvent(INBOUND, '2026-01-10T10:00:00Z')]
+      })
+    ).toBeNull()
+  })
+
+  it('returns null for closed_lost regardless of activity', () => {
+    expect(
+      evaluateCrmDealNextAction({
+        stage_key: 'interested',
+        state_key: 'closed_lost',
+        activity_log: [makeEvent(INBOUND, '2026-01-10T10:00:00Z')]
+      })
+    ).toBeNull()
+  })
+
+  it('returns null for closed stages even when state_key is still actionable', () => {
+    expect(
+      evaluateCrmDealNextAction({
+        stage_key: 'closed_won',
+        state_key: 'discovery_replied',
+        activity_log: [makeEvent(INBOUND, '2026-01-10T10:00:00Z')]
+      })
+    ).toBeNull()
+  })
+
+  it('returns null when activity_log is empty (ownership null)', () => {
+    expect(
+      evaluateCrmDealNextAction({
+        stage_key: 'interested',
+        state_key: 'discovery_replied',
+        activity_log: []
+      })
+    ).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// (state_key, ownership) mapping table
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealNextAction — mapping table', () => {
+  it('(discovery_replied, us) → send_reply', () => {
+    const result = evaluateCrmDealNextAction({
+      stage_key: 'interested',
+      state_key: 'discovery_replied',
+      activity_log: [makeEvent(INBOUND, '2026-04-20T10:00:00Z')]
+    })
+    expect(result).toBe('send_reply')
+  })
+
+  it('(discovery_nudging, them) → send_nudge', () => {
+    const result = evaluateCrmDealNextAction({
+      stage_key: 'interested',
+      state_key: 'discovery_nudging',
+      activity_log: [makeEvent(OUTBOUND, '2026-04-20T10:00:00Z')]
+    })
+    expect(result).toBe('send_nudge')
+  })
+
+  it('(discovery_link_sent, them) → send_nudge only after staleAfterDays', () => {
+    const recentActivity = '2026-04-29T10:00:00Z'
+    const now = new Date('2026-04-30T10:00:00Z')
+
+    // Age = 1 day — below staleAfterDays (14), no mapping fires → null fallback
+    // ownership === 'them' and no stale match → falls through to null
+    const notStale = evaluateCrmDealNextAction(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_link_sent',
+        activity_log: [makeEvent(OUTBOUND, recentActivity)]
+      },
+      { now }
+    )
+    expect(notStale).toBeNull()
+  })
+
+  it('(discovery_link_sent, them) → send_nudge when age >= staleAfterDays', () => {
+    const oldActivity = '2026-04-01T10:00:00Z'
+    const now = new Date('2026-04-30T10:00:00Z') // 29 days later
+
+    const stale = evaluateCrmDealNextAction(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_link_sent',
+        activity_log: [makeEvent(OUTBOUND, oldActivity)]
+      },
+      { now }
+    )
+    expect(stale).toBe('send_nudge')
+  })
+
+  it('(*, us) → ownershipUsFallback send_reply when no explicit mapping matches', () => {
+    // reply_sent + inbound → ownership=us, state_key not in explicit mappings
+    const result = evaluateCrmDealNextAction({
+      stage_key: 'interested',
+      state_key: 'reply_sent',
+      activity_log: [makeEvent(INBOUND, '2026-04-20T10:00:00Z')]
+    })
+    expect(result).toBe('send_reply')
+  })
+
+  it('(followup_1_sent, us) → send_reply via fallback', () => {
+    const result = evaluateCrmDealNextAction({
+      stage_key: 'interested',
+      state_key: 'followup_1_sent',
+      activity_log: [makeEvent(INBOUND, '2026-04-20T10:00:00Z')]
+    })
+    expect(result).toBe('send_reply')
+  })
+
+  it('returns null when ownership is them and no mapping matches and not stale', () => {
+    const result = evaluateCrmDealNextAction({
+      stage_key: 'interested',
+      state_key: 'followup_2_sent',
+      activity_log: [makeEvent(OUTBOUND, '2026-04-29T10:00:00Z')]
+    })
+    expect(result).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// ageDays option
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealNextAction — ageDays option', () => {
+  it('uses supplied ageDays instead of computing from activity_log', () => {
+    // discovery_link_sent + them + ageDays=20 (>=14) → send_nudge
+    const result = evaluateCrmDealNextAction(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_link_sent',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-29T10:00:00Z')]
+      },
+      { ageDays: 20 }
+    )
+    expect(result).toBe('send_nudge')
+  })
+
+  it('requiresStale blocks when ageDays=0', () => {
+    const result = evaluateCrmDealNextAction(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_link_sent',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-29T10:00:00Z')]
+      },
+      { ageDays: 0 }
+    )
+    expect(result).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// resolveCrmNextActionRuleConfig — defaults
+// ---------------------------------------------------------------------------
+
+describe('resolveCrmNextActionRuleConfig — defaults', () => {
+  it('returns default config when called with no input', () => {
+    const config = resolveCrmNextActionRuleConfig()
+    expect(config.ownershipUsFallback).toBe(DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.ownershipUsFallback)
+    expect(config.mappings).toHaveLength(DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.mappings.length)
+  })
+
+  it('returns default config for invalid input', () => {
+    const config = resolveCrmNextActionRuleConfig('not-an-object')
+    expect(config.ownershipUsFallback).toBe(DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.ownershipUsFallback)
+  })
+
+  it('accepts a full CrmNextActionRuleConfig directly', () => {
+    const full = {
+      mappings: [{ stateKey: 'foo', ownership: 'us' as const, actionKey: 'bar' }],
+      ownershipUsFallback: 'bar'
+    }
+    const config = resolveCrmNextActionRuleConfig(full)
+    expect(config.ownershipUsFallback).toBe('bar')
+    expect(config.mappings).toHaveLength(1)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Per-org override merging
+// ---------------------------------------------------------------------------
+
+describe('resolveCrmNextActionRuleConfig — per-org override', () => {
+  it('prepends org mappings before defaults (org rules win on first-match)', () => {
+    const orgConfig = {
+      crm: {
+        next_actions: {
+          mappings: [{ stateKey: 'discovery_replied', ownership: 'us' as const, actionKey: 'custom_action' }]
+        }
+      }
+    }
+    const config = resolveCrmNextActionRuleConfig(orgConfig)
+    // Org mapping should appear first
+    expect(config.mappings[0].actionKey).toBe('custom_action')
+    // Default mappings still present after org ones
+    expect(config.mappings.length).toBeGreaterThan(1)
+  })
+
+  it('overrides ownershipUsFallback when supplied', () => {
+    const orgConfig = {
+      crm: {
+        next_actions: {
+          ownershipUsFallback: 'org_custom_reply'
+        }
+      }
+    }
+    const config = resolveCrmNextActionRuleConfig(orgConfig)
+    expect(config.ownershipUsFallback).toBe('org_custom_reply')
+  })
+
+  it('org override fires over default for same (state_key, ownership) pair', () => {
+    // Org remaps (discovery_replied, us) → 'org_reply'
+    const result = evaluateCrmDealNextAction(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_replied',
+        activity_log: [makeEvent(INBOUND, '2026-04-20T10:00:00Z')]
+      },
+      {
+        config: {
+          crm: {
+            next_actions: {
+              mappings: [{ stateKey: 'discovery_replied', ownership: 'us', actionKey: 'org_reply' }]
+            }
+          }
+        }
+      }
+    )
+    expect(result).toBe('org_reply')
+  })
+
+  it('falls back to defaults when org override is empty object', () => {
+    const config = resolveCrmNextActionRuleConfig({ crm: { next_actions: {} } })
+    expect(config.mappings).toHaveLength(DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.mappings.length)
+    expect(config.ownershipUsFallback).toBe(DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.ownershipUsFallback)
+  })
+})

package/src/business/acquisition/crm-next-action.ts

@@ -0,0 +1,220 @@
+// ---------------------------------------------------------------------------
+// CRM Next-Action evaluator — mirrors the crm-priority.ts resolver/evaluator
+// pattern. Maps (state_key, ownership) → suggested action key string.
+//
+// Per-org overrides live at organizations.config.crm.next_actions and are
+// merged at evaluator read time via resolveCrmNextActionRuleConfig.
+// ---------------------------------------------------------------------------
+
+import { z } from 'zod'
+import {
+  DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG,
+  type CrmNextActionRuleConfig,
+  type CrmNextActionMapping
+} from '../../organization-model/domains/sales'
+import { getDealOwnership } from './deal-ownership'
+import type { DealOwnership } from './deal-ownership'
+
+export interface CrmNextActionInput {
+  stage_key: string | null
+  state_key: string | null
+  activity_log: unknown
+}
+
+export interface EvaluateCrmDealNextActionOptions {
+  config?: CrmNextActionRuleConfig | unknown
+  now?: Date | string
+  /** Current age in days — computed from activity_log if not supplied. */
+  ageDays?: number
+}
+
+// ---------------------------------------------------------------------------
+// Zod schemas for the rule config (used by the resolver)
+// ---------------------------------------------------------------------------
+
+const CrmNextActionMappingSchema = z
+  .object({
+    stateKey: z.string().trim().min(1).max(120),
+    ownership: z.enum(['us', 'them', '*']),
+    actionKey: z.string().trim().min(1).max(120),
+    requiresStale: z.boolean().optional()
+  })
+  .strict()
+
+const CrmNextActionRuleConfigSchema = z
+  .object({
+    mappings: z.array(CrmNextActionMappingSchema),
+    ownershipUsFallback: z.string().trim().min(1).max(120)
+  })
+  .strict()
+
+// Partial override shape accepted from organizations.config.crm.next_actions
+export const CrmNextActionOverrideSchema = z
+  .object({
+    mappings: z.array(CrmNextActionMappingSchema).optional(),
+    ownershipUsFallback: z.string().trim().min(1).max(120).optional()
+  })
+  .strict()
+
+export type CrmNextActionOverride = z.infer<typeof CrmNextActionOverrideSchema>
+
+/**
+ * Resolved next-action config. Always has all required fields populated.
+ * `mappings` is the merged list: org overrides prepended before defaults so
+ * org-specific rules win on first-match evaluation.
+ */
+export type ResolvedCrmNextActionRuleConfig = CrmNextActionRuleConfig
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluates the suggested next action for a deal.
+ *
+ * Returns the action key string (matching a key in DEFAULT_CRM_ACTIONS), or
+ * null for closed deals or when no mapping matches.
+ *
+ * Closed deals (ownership === null due to closed stage_key) return null
+ * immediately — ownership derivation short-circuits on closed_won/closed_lost.
+ */
+export function evaluateCrmDealNextAction(
+  input: CrmNextActionInput,
+  options: EvaluateCrmDealNextActionOptions = {}
+): string | null {
+  if (isClosedDeal(input)) return null
+
+  const config = resolveCrmNextActionRuleConfig(options.config)
+  const ownership = getDealOwnership(input)
+
+  // No ownership signal: staleAfterDays fallback is intentionally not applied here.
+  if (ownership === null) return null
+
+  const ageDays = options.ageDays ?? computeAgeDays(input, options.now)
+
+  return (
+    evaluateMappings(config.mappings, input.state_key, ownership, ageDays, 14) ??
+    (ownership === 'us' ? config.ownershipUsFallback : null)
+  )
+}
+
+/**
+ * Resolves the next-action rule config from an org config input.
+ *
+ * Accepts:
+ * - Full CrmNextActionRuleConfig (used directly after validation)
+ * - Partial CrmNextActionOverride (merged on top of defaults)
+ * - Nested org config: { crm: { next_actions: ... } }
+ * - Any other value → falls back to defaults
+ */
+export function resolveCrmNextActionRuleConfig(input?: unknown): ResolvedCrmNextActionRuleConfig {
+  const candidate = extractNextActionOverride(input)
+  const fullResult = CrmNextActionRuleConfigSchema.safeParse(candidate)
+
+  if (fullResult.success) return fullResult.data
+
+  const overrideResult = CrmNextActionOverrideSchema.safeParse(candidate)
+
+  if (!overrideResult.success) return { ...DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG }
+
+  return mergeNextActionOverride(overrideResult.data)
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function evaluateMappings(
+  mappings: CrmNextActionMapping[],
+  stateKey: string | null,
+  ownership: Exclude<DealOwnership, null>,
+  ageDays: number,
+  staleAfterDays: number
+): string | null {
+  for (const mapping of mappings) {
+    const stateMatches = mapping.stateKey === '*' || mapping.stateKey === stateKey
+    const ownershipMatches = mapping.ownership === '*' || mapping.ownership === ownership
+    const staleOk = !mapping.requiresStale || ageDays >= staleAfterDays
+
+    if (stateMatches && ownershipMatches && staleOk) {
+      return mapping.actionKey
+    }
+  }
+
+  return null
+}
+
+function isClosedDeal(input: CrmNextActionInput): boolean {
+  return (
+    input.stage_key === 'closed_won' ||
+    input.stage_key === 'closed_lost' ||
+    input.state_key === 'closed_won' ||
+    input.state_key === 'closed_lost'
+  )
+}
+
+function mergeNextActionOverride(override: CrmNextActionOverride): ResolvedCrmNextActionRuleConfig {
+  // Org mappings are prepended so they win on first-match evaluation.
+  const mappings = [...(override.mappings ?? []), ...DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.mappings]
+
+  return {
+    mappings,
+    ownershipUsFallback: override.ownershipUsFallback ?? DEFAULT_CRM_NEXT_ACTION_RULE_CONFIG.ownershipUsFallback
+  }
+}
+
+function extractNextActionOverride(input: unknown): unknown {
+  if (!isPlainRecord(input)) return input
+
+  const crm = input.crm
+  if (isPlainRecord(crm) && Object.prototype.hasOwnProperty.call(crm, 'next_actions')) {
+    return crm.next_actions
+  }
+
+  return input
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function computeAgeDays(input: CrmNextActionInput, now?: Date | string): number {
+  const nowMs = parseMs(now ?? new Date())
+  if (nowMs === null) return 0
+
+  if (!Array.isArray(input.activity_log) || input.activity_log.length === 0) return 0
+
+  let latestMs: number | null = null
+
+  for (const entry of input.activity_log) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue
+
+    const record = entry as Record<string, unknown>
+    const ms =
+      parseMs(record.timestamp) ??
+      parseMs(record.occurredAt) ??
+      parseMs(record.createdAt) ??
+      parseMs(record.updatedAt) ??
+      parseMs(record.sentAt)
+
+    if (ms !== null && (latestMs === null || ms > latestMs)) {
+      latestMs = ms
+    }
+  }
+
+  if (latestMs === null) return 0
+
+  return Math.max(0, (nowMs - latestMs) / MS_PER_DAY)
+}
+
+function parseMs(value: unknown): number | null {
+  if (value instanceof Date) {
+    const ms = value.getTime()
+    return Number.isNaN(ms) ? null : ms
+  }
+  if (typeof value !== 'string') return null
+  const ms = new Date(value).getTime()
+  return Number.isNaN(ms) ? null : ms
+}