@elevasis/core 0.14.0 → 0.15.1

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
+}

package/src/business/acquisition/crm-priority.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest'
+import { evaluateCrmDealPriority, resolveCrmPriorityRuleConfig } from './crm-priority'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEvent(type: string, timestamp: string): Record<string, unknown> {
+  return { type, timestamp }
+}
+
+const INBOUND = 'reply_received'
+const OUTBOUND = 'reply_sent_to_lead'
+const NOW = '2026-04-30T12:00:00.000Z'
+
+function makeDeal(
+  overrides: Partial<{
+    stage_key: string | null
+    state_key: string | null
+    activity_log: unknown[]
+    updated_at: string
+    created_at: string
+  }> = {}
+) {
+  return {
+    stage_key: overrides.stage_key ?? 'interested',
+    state_key: overrides.state_key ?? 'discovery_replied',
+    activity_log: overrides.activity_log ?? [],
+    updated_at: overrides.updated_at ?? NOW,
+    created_at: overrides.created_at ?? NOW
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Closed deals → closed_low
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — closed deals', () => {
+  it('returns closed_low for closed_won stage', () => {
+    const result = evaluateCrmDealPriority(makeDeal({ stage_key: 'closed_won' }), { now: NOW })
+    expect(result.bucketKey).toBe('closed_low')
+  })
+
+  it('returns closed_low for closed_lost stage', () => {
+    const result = evaluateCrmDealPriority(makeDeal({ stage_key: 'closed_lost' }), { now: NOW })
+    expect(result.bucketKey).toBe('closed_low')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// needs_response — ownership === 'us'
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — needs_response (ownership === us)', () => {
+  it('returns needs_response when lead replied last (inbound after outbound)', () => {
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'discovery_replied',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-28T10:00:00Z'), makeEvent(INBOUND, '2026-04-29T10:00:00Z')]
+      }),
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('needs_response')
+  })
+
+  it('returns needs_response when only inbound event present', () => {
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'discovery_replied',
+        activity_log: [makeEvent(INBOUND, '2026-04-29T10:00:00Z')]
+      }),
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('needs_response')
+  })
+
+  it('returns needs_response regardless of state_key when ownership is us', () => {
+    // reply_sent is normally a "we acted" state, but if a new inbound arrives ownership flips
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'reply_sent',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-27T10:00:00Z'), makeEvent(INBOUND, '2026-04-29T10:00:00Z')]
+      }),
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('needs_response')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// waiting — ownership === 'them' AND age < staleAfterDays
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — waiting (ownership === them, not stale)', () => {
+  it('returns waiting when we replied last and age is below staleAfterDays', () => {
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'reply_sent',
+        // No followUpAfterDaysByStateKey entry for reply_sent within window
+        activity_log: [makeEvent(OUTBOUND, '2026-04-29T10:00:00Z')]
+      }),
+      { now: NOW }
+    )
+    // Age = 1 day, staleAfterDays = 14 → waiting
+    // reply_sent has followUpAfterDaysByStateKey=3, nextActionAt is 2026-05-02, not yet due
+    expect(result.bucketKey).toBe('waiting')
+  })
+
+  it('returns follow_up_due when follow-up window elapses (ownership them)', () => {
+    // discovery_link_sent: followUpAfterDaysByStateKey = 3
+    // Activity at 2026-04-26, now = 2026-04-30 → age 4 days → nextActionAt = 2026-04-29 (past)
+    // updated_at set before activity so latestActivityAt comes from activity_log
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'discovery_link_sent',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-26T10:00:00Z')],
+        updated_at: '2026-04-25T00:00:00Z',
+        created_at: '2026-04-25T00:00:00Z'
+      }),
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('follow_up_due')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// stale — ownership === 'them' AND age >= staleAfterDays
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — stale (ownership them, age >= staleAfterDays)', () => {
+  it('returns stale when we sent last and age >= staleAfterDays', () => {
+    // Activity at 2026-04-10, now = 2026-04-30 → age 20 days >= staleAfterDays 14
+    // updated_at set before activity so latestActivityAt comes from activity_log
+    const result = evaluateCrmDealPriority(
+      makeDeal({
+        state_key: 'reply_sent',
+        activity_log: [makeEvent(OUTBOUND, '2026-04-10T10:00:00Z')],
+        updated_at: '2026-04-09T00:00:00Z',
+        created_at: '2026-04-09T00:00:00Z'
+      }),
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('stale')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// No activity (ownership null)
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — no ownership signal', () => {
+  it('returns waiting when no activity log', () => {
+    const result = evaluateCrmDealPriority(makeDeal({ activity_log: [] }), { now: NOW })
+    expect(result.bucketKey).toBe('waiting')
+  })
+
+  it('returns stale when no activity and updated_at is very old', () => {
+    const result = evaluateCrmDealPriority(
+      {
+        stage_key: 'interested',
+        state_key: 'discovery_replied',
+        activity_log: [],
+        updated_at: '2026-01-01T00:00:00Z',
+        created_at: '2026-01-01T00:00:00Z'
+      },
+      { now: NOW }
+    )
+    expect(result.bucketKey).toBe('stale')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// disabled config
+// ---------------------------------------------------------------------------
+
+describe('evaluateCrmDealPriority — disabled config', () => {
+  it('returns waiting when config.enabled is false', () => {
+    const config = resolveCrmPriorityRuleConfig({ enabled: false })
+    const result = evaluateCrmDealPriority(makeDeal({ activity_log: [makeEvent(INBOUND, '2026-04-29T10:00:00Z')] }), {
+      now: NOW,
+      config
+    })
+    expect(result.bucketKey).toBe('waiting')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// resolveCrmPriorityRuleConfig — override merging
+// ---------------------------------------------------------------------------
+
+describe('resolveCrmPriorityRuleConfig — override merging', () => {
+  it('merges staleAfterDays and closedStageKeys from org override', () => {
+    const config = resolveCrmPriorityRuleConfig({
+      crm: {
+        priority: {
+          staleAfterDays: 7,
+          closedStageKeys: ['custom_closed']
+        }
+      }
+    })
+    expect(config.staleAfterDays).toBe(7)
+    expect(config.closedStageKeys).toEqual(['custom_closed'])
+  })
+
+  it('falls back to defaults for invalid input', () => {
+    const config = resolveCrmPriorityRuleConfig('not-valid')
+    expect(config.staleAfterDays).toBe(14)
+    expect(config.enabled).toBe(true)
+  })
+
+  it('does not have needsResponseStateKeys or needsResponseActivityTypes', () => {
+    const config = resolveCrmPriorityRuleConfig()
+    expect(config).not.toHaveProperty('needsResponseStateKeys')
+    expect(config).not.toHaveProperty('needsResponseActivityTypes')
+  })
+})