@reachy/audience-module 1.0.19 → 1.0.21

package/src/__tests__/QueryBuilder.test.ts

@@ -0,0 +1,198 @@
+import { QueryBuilder } from '../builders/QueryBuilder'
+
+function createMockQuery() {
+  const calls: Array<{ method: string; args: any[] }> = []
+  const handler: ProxyHandler<any> = {
+    get(_target, prop) {
+      if (prop === '_calls') return calls
+      return (...args: any[]) => {
+        calls.push({ method: String(prop), args })
+        return new Proxy({}, handler)
+      }
+    }
+  }
+  return new Proxy({}, handler)
+}
+
+describe('QueryBuilder', () => {
+  describe('buildFilters', () => {
+    it('adds organization_id and project_id to query', () => {
+      const query = createMockQuery()
+      QueryBuilder.buildFilters(query, { groups: [] }, 'org-1', 'proj-1')
+      const calls = (query as any)._calls
+      expect(calls[0]).toEqual({ method: 'eq', args: ['organization_id', 'org-1'] })
+    })
+
+    it('applies groups criteria with OR', () => {
+      const query = createMockQuery()
+      const criteria = {
+        groups: [{
+          rules: [
+            { field: 'email', operator: 'equals', value: 'a@b.com' },
+            { field: 'name', operator: 'contains', value: 'John' }
+          ]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      // Should end up calling .or() at some point
+      const allCalls = (query as any)._calls
+      expect(allCalls.length).toBeGreaterThan(0)
+    })
+
+    it('returns query unchanged when no criteria format matches', () => {
+      const query = createMockQuery()
+      QueryBuilder.buildFilters(query, {} as any, 'org', 'proj')
+      const calls = (query as any)._calls
+      // Only eq calls for org/proj
+      expect(calls[0].method).toBe('eq')
+    })
+  })
+
+  describe('buildConditionString (via groups)', () => {
+    function buildCondition(field: string, operator: string, value: any): string | null {
+      const query = createMockQuery()
+      const criteria = {
+        groups: [{ rules: [{ field, operator, value }] }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      // The last call should be or() with the condition string
+      const allCalls = (query as any)._calls
+      const orCall = allCalls.find((c: any) => c.method === 'or')
+      return orCall ? orCall.args[0] : null
+    }
+
+    it('builds equals condition', () => {
+      expect(buildCondition('email', 'equals', 'a@b.com')).toBe('email.eq.a@b.com')
+    })
+
+    it('builds eq alias condition', () => {
+      expect(buildCondition('email', 'eq', 'a@b.com')).toBe('email.eq.a@b.com')
+    })
+
+    it('builds not_equals condition', () => {
+      expect(buildCondition('email', 'not_equals', 'x')).toBe('email.neq.x')
+    })
+
+    it('builds contains/ilike condition', () => {
+      expect(buildCondition('name', 'contains', 'john')).toBe('name.ilike.*john*')
+    })
+
+    it('builds starts_with condition', () => {
+      expect(buildCondition('name', 'starts_with', 'Jo')).toBe('name.ilike.Jo*')
+    })
+
+    it('builds ends_with condition', () => {
+      expect(buildCondition('name', 'ends_with', 'hn')).toBe('name.ilike.*hn')
+    })
+
+    it('builds greater_than condition', () => {
+      expect(buildCondition('age', 'greater_than', 18)).toBe('age.gt.18')
+    })
+
+    it('builds less_than condition', () => {
+      expect(buildCondition('age', 'less_than', 65)).toBe('age.lt.65')
+    })
+
+    it('builds is_empty condition', () => {
+      expect(buildCondition('phone', 'is_empty', null)).toBe('phone.is.null')
+    })
+
+    it('builds is_not_empty condition', () => {
+      expect(buildCondition('phone', 'is_not_empty', null)).toBe('phone.not.is.null')
+    })
+
+    it('returns null for unknown operator', () => {
+      expect(buildCondition('x', 'unknown_op', 'y')).toBeNull()
+    })
+
+    it('returns null when field is missing', () => {
+      expect(buildCondition('', 'equals', 'x')).toBeNull()
+    })
+
+    it('maps custom_field with customFieldKey', () => {
+      const query = createMockQuery()
+      const criteria = {
+        groups: [{
+          rules: [{ field: 'custom_field', operator: 'equals', value: 'vip', customFieldKey: 'plan' }]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      const allCalls = (query as any)._calls
+      const orCall = allCalls.find((c: any) => c.method === 'or')
+      expect(orCall?.args[0]).toContain('properties->>plan')
+    })
+  })
+
+  describe('filters format (v1)', () => {
+    it('applies OR filter groups', () => {
+      const query = createMockQuery()
+      const criteria = {
+        filters: [{
+          id: 'f1',
+          operator: 'OR',
+          conditions: [
+            { id: 'c1', field: 'email', operator: 'equals', value: 'a@b.com', logicalOperator: 'OR' },
+            { id: 'c2', field: 'name', operator: 'contains', value: 'Jo', logicalOperator: 'OR' }
+          ]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      const allCalls = (query as any)._calls
+      const orCall = allCalls.find((c: any) => c.method === 'or')
+      expect(orCall).toBeDefined()
+    })
+
+    it('applies AND filter groups as individual conditions', () => {
+      const query = createMockQuery()
+      const criteria = {
+        filters: [{
+          id: 'f1',
+          operator: 'AND',
+          conditions: [
+            { id: 'c1', field: 'email', operator: 'equals', value: 'a@b.com', logicalOperator: 'AND' }
+          ]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      const allCalls = (query as any)._calls
+      const eqCalls = allCalls.filter((c: any) => c.method === 'eq')
+      expect(eqCalls.length).toBeGreaterThanOrEqual(2) // org + proj + email
+    })
+  })
+
+  describe('conditions format', () => {
+    it('applies OR conditions using .or()', () => {
+      const query = createMockQuery()
+      const criteria = {
+        conditions: [{
+          groupId: 'g1',
+          operator: 'OR',
+          conditions: [
+            { field: 'email', operator: 'equals', value: 'a@b.com' }
+          ]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      const allCalls = (query as any)._calls
+      const orCall = allCalls.find((c: any) => c.method === 'or')
+      expect(orCall).toBeDefined()
+    })
+
+    it('applies AND conditions individually', () => {
+      const query = createMockQuery()
+      const criteria = {
+        conditions: [{
+          groupId: 'g1',
+          operator: 'AND',
+          conditions: [
+            { field: 'is_subscribed', operator: 'eq', value: true }
+          ]
+        }]
+      }
+      QueryBuilder.buildFilters(query, criteria as any, 'org', 'proj')
+      const allCalls = (query as any)._calls
+      const eqCalls = allCalls.filter((c: any) => c.method === 'eq')
+      expect(eqCalls.length).toBeGreaterThanOrEqual(2)
+    })
+  })
+})

package/src/__tests__/RfmEngine.test.ts

@@ -0,0 +1,284 @@
+import { RfmEngine, RfmContactRow, RfmEventRow, RfmComputeOptions, RfmScoredContact } from '../engine/RfmEngine'
+
+const NOW = new Date('2025-03-01T00:00:00Z')
+
+function makeContacts(count: number): RfmContactRow[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `c${i + 1}`,
+    reachy_id: `r${i + 1}`,
+    email: `user${i + 1}@test.com`,
+    phone: `+5511${String(i + 1).padStart(9, '0')}`,
+    is_subscribed: true,
+  }))
+}
+
+function makeEvents(contactId: string, eventName: string, dates: string[]): RfmEventRow[] {
+  return dates.map(d => ({
+    contact_id: contactId,
+    event_name: eventName,
+    event_timestamp: d,
+  }))
+}
+
+describe('RfmEngine', () => {
+  describe('aggregateFromEvents', () => {
+    const contacts = makeContacts(3)
+    const opts: RfmComputeOptions = {
+      from: '2025-01-01T00:00:00Z',
+      to: '2025-03-01T00:00:00Z',
+      rfEventName: 'purchase',
+    }
+
+    it('aggregates events per contact within time window', () => {
+      const events: RfmEventRow[] = [
+        ...makeEvents('c1', 'purchase', ['2025-01-15', '2025-02-20']),
+        ...makeEvents('c2', 'purchase', ['2025-02-01']),
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, opts)
+      expect(result).toHaveLength(2)
+
+      const c1 = result.find(r => r.contact_id === 'c1')!
+      expect(c1.event_count).toBe(2)
+      expect(c1.last_ts).toEqual(new Date('2025-02-20'))
+
+      const c2 = result.find(r => r.contact_id === 'c2')!
+      expect(c2.event_count).toBe(1)
+    })
+
+    it('filters events by rfEventName', () => {
+      const events: RfmEventRow[] = [
+        ...makeEvents('c1', 'purchase', ['2025-01-15']),
+        ...makeEvents('c1', 'page_view', ['2025-01-16']),
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, opts)
+      expect(result).toHaveLength(1)
+      expect(result[0].event_count).toBe(1)
+    })
+
+    it('excludes events outside time window', () => {
+      const events: RfmEventRow[] = [
+        ...makeEvents('c1', 'purchase', ['2024-12-31']), // before from
+        ...makeEvents('c1', 'purchase', ['2025-03-02']), // after to
+        ...makeEvents('c1', 'purchase', ['2025-02-01']), // within
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, opts)
+      expect(result).toHaveLength(1)
+      expect(result[0].event_count).toBe(1)
+    })
+
+    it('resolves contact via reachy_id when contact_id is missing', () => {
+      const events: RfmEventRow[] = [
+        { reachy_id: 'r1', event_name: 'purchase', event_timestamp: '2025-02-01' },
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, opts)
+      expect(result).toHaveLength(1)
+      expect(result[0].contact_id).toBe('c1')
+    })
+
+    it('ignores events with no resolvable contact', () => {
+      const events: RfmEventRow[] = [
+        { contact_id: 'nonexistent', event_name: 'purchase', event_timestamp: '2025-02-01' },
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, opts)
+      expect(result).toHaveLength(0)
+    })
+
+    it('filters by filterContactIds when provided', () => {
+      const events: RfmEventRow[] = [
+        ...makeEvents('c1', 'purchase', ['2025-02-01']),
+        ...makeEvents('c2', 'purchase', ['2025-02-01']),
+      ]
+
+      const result = RfmEngine.aggregateFromEvents(contacts, events, {
+        ...opts,
+        filterContactIds: new Set(['c1']),
+      })
+      expect(result).toHaveLength(1)
+      expect(result[0].contact_id).toBe('c1')
+    })
+
+    it('returns empty array for empty events', () => {
+      const result = RfmEngine.aggregateFromEvents(contacts, [], opts)
+      expect(result).toHaveLength(0)
+    })
+
+    it('returns empty array for empty contacts', () => {
+      const events = makeEvents('c1', 'purchase', ['2025-02-01'])
+      const result = RfmEngine.aggregateFromEvents([], events, opts)
+      expect(result).toHaveLength(0)
+    })
+  })
+
+  describe('scoreAggregates', () => {
+    const contacts = makeContacts(5)
+
+    it('assigns R and F scores 1-5 based on percentiles', () => {
+      const aggregates = [
+        { contact_id: 'c1', last_ts: new Date('2025-02-28'), event_count: 50 }, // very recent, high freq
+        { contact_id: 'c2', last_ts: new Date('2025-02-20'), event_count: 30 },
+        { contact_id: 'c3', last_ts: new Date('2025-02-01'), event_count: 10 },
+        { contact_id: 'c4', last_ts: new Date('2025-01-15'), event_count: 5 },
+        { contact_id: 'c5', last_ts: new Date('2025-01-01'), event_count: 1 }, // oldest, lowest freq
+      ]
+
+      const { scored, r_days_cuts, f_count_cuts } = RfmEngine.scoreAggregates(contacts, aggregates, { to: NOW })
+
+      expect(scored).toHaveLength(5)
+      expect(r_days_cuts).toHaveLength(4)
+      expect(f_count_cuts).toHaveLength(4)
+
+      // Most recent contact should have highest R score
+      const c1 = scored.find(s => s.contact_id === 'c1')!
+      expect(c1.r_score).toBe(5)
+      expect(c1.f_score).toBe(5)
+
+      // Oldest with lowest freq should have lowest scores
+      const c5 = scored.find(s => s.contact_id === 'c5')!
+      expect(c5.r_score).toBe(1)
+      expect(c5.f_score).toBe(1)
+
+      // All should have a valid segment key
+      for (const s of scored) {
+        expect(s.segment_key).toBeTruthy()
+        expect([1, 2, 3, 4, 5]).toContain(s.r_score)
+        expect([1, 2, 3, 4, 5]).toContain(s.f_score)
+      }
+    })
+
+    it('computes segment_key as "new_users" for single high-recency low-freq contact', () => {
+      // With only 1 contact, percentile puts it at R=5, F=1 → new_users
+      const aggregates = [
+        { contact_id: 'c1', last_ts: new Date('2025-02-28'), event_count: 100 },
+      ]
+      const { scored } = RfmEngine.scoreAggregates(contacts, aggregates, { to: NOW })
+      // Single element: R=5 (most recent), F=1 (single bucket) → R=5,F=1 → new_users
+      expect(scored[0].r_score).toBe(5)
+      expect(scored[0].f_score).toBe(1)
+      expect(scored[0].segment_key).toBe('new_users')
+    })
+
+    it('determines email_ok and sms_ok from contact data', () => {
+      const contactsWithPrefs: RfmContactRow[] = [
+        { id: 'c1', email: 'a@b.com', phone: '+5511999', is_subscribed: true },
+        { id: 'c2', email: '', phone: '', is_subscribed: false },
+      ]
+      const aggregates = [
+        { contact_id: 'c1', last_ts: new Date('2025-02-28'), event_count: 10 },
+        { contact_id: 'c2', last_ts: new Date('2025-02-28'), event_count: 5 },
+      ]
+      const { scored } = RfmEngine.scoreAggregates(contactsWithPrefs, aggregates, { to: NOW })
+
+      const c1 = scored.find(s => s.contact_id === 'c1')!
+      expect(c1.email_ok).toBe(1)
+      expect(c1.sms_ok).toBe(1)
+
+      const c2 = scored.find(s => s.contact_id === 'c2')!
+      expect(c2.email_ok).toBe(0) // is_subscribed=false
+      expect(c2.sms_ok).toBe(0)
+    })
+
+    it('skips aggregates for contacts not in contact list', () => {
+      const aggregates = [
+        { contact_id: 'c1', last_ts: new Date('2025-02-28'), event_count: 10 },
+        { contact_id: 'nonexistent', last_ts: new Date('2025-02-28'), event_count: 5 },
+      ]
+      const { scored } = RfmEngine.scoreAggregates(contacts, aggregates, { to: NOW })
+      expect(scored).toHaveLength(1)
+    })
+  })
+
+  describe('thresholdsFromScored', () => {
+    it('extracts min/max per R and F score', () => {
+      const scored: RfmScoredContact[] = [
+        { contact_id: 'c1', last_ts: new Date(), event_count: 50, recency_days: 1, r_score: 5, f_score: 5, segment_key: 'champions', email_ok: 1, sms_ok: 1 },
+        { contact_id: 'c2', last_ts: new Date(), event_count: 30, recency_days: 3, r_score: 5, f_score: 4, segment_key: 'champions', email_ok: 1, sms_ok: 1 },
+        { contact_id: 'c3', last_ts: new Date(), event_count: 1, recency_days: 90, r_score: 1, f_score: 1, segment_key: 'hibernating', email_ok: 1, sms_ok: 0 },
+      ]
+
+      const thresholds = RfmEngine.thresholdsFromScored(scored)
+
+      expect(thresholds.length).toBeGreaterThan(0)
+
+      // Sorted by kind (f before r), then by score
+      const first = thresholds[0]
+      expect(first.kind).toBe('f')
+
+      // R score 5 should have min=1, max=3
+      const r5 = thresholds.find(t => t.kind === 'r' && t.score === 5)
+      expect(r5).toBeDefined()
+      expect(r5!.min_value).toBe(1)
+      expect(r5!.max_value).toBe(3)
+    })
+
+    it('returns empty array for empty scored', () => {
+      expect(RfmEngine.thresholdsFromScored([])).toEqual([])
+    })
+  })
+
+  describe('previewFromScored', () => {
+    it('returns all 10 segments with counts and percentages', () => {
+      const scored: RfmScoredContact[] = [
+        { contact_id: 'c1', last_ts: new Date(), event_count: 50, recency_days: 1, r_score: 5, f_score: 5, segment_key: 'champions', email_ok: 1, sms_ok: 1 },
+        { contact_id: 'c2', last_ts: new Date(), event_count: 1, recency_days: 90, r_score: 1, f_score: 1, segment_key: 'hibernating', email_ok: 0, sms_ok: 0 },
+      ]
+
+      const preview = RfmEngine.previewFromScored(scored)
+      expect(preview).toHaveLength(10)
+
+      const champions = preview.find(p => p.segment_key === 'champions')!
+      expect(champions.users).toBe(1)
+      expect(champions.percent).toBe(50)
+      expect(champions.email_reachability).toBe(1)
+
+      const hibernating = preview.find(p => p.segment_key === 'hibernating')!
+      expect(hibernating.users).toBe(1)
+      expect(hibernating.email_reachability).toBe(0)
+
+      // All other segments should have 0 users
+      const empties = preview.filter(p => !['champions', 'hibernating'].includes(p.segment_key))
+      for (const seg of empties) {
+        expect(seg.users).toBe(0)
+        expect(seg.percent).toBe(0)
+      }
+    })
+
+    it('returns all zeros for empty scored', () => {
+      const preview = RfmEngine.previewFromScored([])
+      expect(preview).toHaveLength(10)
+      for (const seg of preview) {
+        expect(seg.users).toBe(0)
+        expect(seg.percent).toBe(0)
+      }
+    })
+  })
+
+  describe('computeFromEvents', () => {
+    it('orchestrates aggregate → score → thresholds → preview', () => {
+      const contacts = makeContacts(3)
+      const events: RfmEventRow[] = [
+        ...makeEvents('c1', 'purchase', ['2025-02-28', '2025-02-25', '2025-02-20']),
+        ...makeEvents('c2', 'purchase', ['2025-01-15']),
+        ...makeEvents('c3', 'purchase', ['2025-01-01', '2025-01-02']),
+      ]
+      const opts: RfmComputeOptions = {
+        from: '2025-01-01',
+        to: '2025-03-01',
+        rfEventName: 'purchase',
+      }
+
+      const { segments, thresholds, scored } = RfmEngine.computeFromEvents(contacts, events, opts)
+
+      expect(scored).toHaveLength(3)
+      expect(segments).toHaveLength(10)
+      expect(thresholds.length).toBeGreaterThan(0)
+
+      const totalUsers = segments.reduce((sum, s) => sum + s.users, 0)
+      expect(totalUsers).toBe(3)
+    })
+  })
+})

package/src/__tests__/RfmSegmentBuilder.test.ts

@@ -0,0 +1,210 @@
+import { RfmSegmentBuilder, RfmThresholdRowLike } from '../builders/RfmSegmentBuilder'
+
+describe('RfmSegmentBuilder', () => {
+  describe('getSegmentScoreRanges', () => {
+    const expected: Record<string, { r: { minScore: number; maxScore: number }; f: { minScore: number; maxScore: number } }> = {
+      champions: { r: { minScore: 4, maxScore: 5 }, f: { minScore: 4, maxScore: 5 } },
+      loyal_users: { r: { minScore: 3, maxScore: 3 }, f: { minScore: 4, maxScore: 5 } },
+      potential_loyalists: { r: { minScore: 4, maxScore: 5 }, f: { minScore: 2, maxScore: 3 } },
+      new_users: { r: { minScore: 5, maxScore: 5 }, f: { minScore: 1, maxScore: 1 } },
+      promising: { r: { minScore: 4, maxScore: 4 }, f: { minScore: 1, maxScore: 1 } },
+      needing_attention: { r: { minScore: 3, maxScore: 3 }, f: { minScore: 3, maxScore: 3 } },
+      about_to_sleep: { r: { minScore: 3, maxScore: 3 }, f: { minScore: 1, maxScore: 2 } },
+      cannot_lose_them: { r: { minScore: 1, maxScore: 2 }, f: { minScore: 5, maxScore: 5 } },
+      at_risk: { r: { minScore: 1, maxScore: 2 }, f: { minScore: 3, maxScore: 4 } },
+      hibernating: { r: { minScore: 1, maxScore: 2 }, f: { minScore: 1, maxScore: 2 } },
+    }
+
+    it.each(Object.entries(expected))('returns correct ranges for "%s"', (key, ranges) => {
+      expect(RfmSegmentBuilder.getSegmentScoreRanges(key)).toEqual(ranges)
+    })
+
+    it('returns null for unknown segment key', () => {
+      expect(RfmSegmentBuilder.getSegmentScoreRanges('unknown')).toBeNull()
+    })
+
+    it('returns null for empty string', () => {
+      expect(RfmSegmentBuilder.getSegmentScoreRanges('')).toBeNull()
+    })
+
+    it('handles whitespace in key', () => {
+      expect(RfmSegmentBuilder.getSegmentScoreRanges(' champions ')).toEqual(expected.champions)
+    })
+  })
+
+  describe('getSegmentName', () => {
+    it('returns "Champions" for "champions"', () => {
+      expect(RfmSegmentBuilder.getSegmentName('champions')).toBe('Champions')
+    })
+
+    it('returns "At Risk" for "at_risk"', () => {
+      expect(RfmSegmentBuilder.getSegmentName('at_risk')).toBe('At Risk')
+    })
+
+    it('returns the key itself for unknown segment', () => {
+      expect(RfmSegmentBuilder.getSegmentName('custom_segment')).toBe('custom_segment')
+    })
+
+    it('returns "Segment" for empty/null input', () => {
+      expect(RfmSegmentBuilder.getSegmentName('')).toBe('Segment')
+      expect(RfmSegmentBuilder.getSegmentName(null as any)).toBe('Segment')
+    })
+  })
+
+  describe('clampInt', () => {
+    it('clamps within range', () => {
+      expect(RfmSegmentBuilder.clampInt(5, 1, 10)).toBe(5)
+    })
+
+    it('clamps below min', () => {
+      expect(RfmSegmentBuilder.clampInt(-1, 0, 10)).toBe(0)
+    })
+
+    it('clamps above max', () => {
+      expect(RfmSegmentBuilder.clampInt(100, 0, 10)).toBe(10)
+    })
+
+    it('truncates decimals', () => {
+      expect(RfmSegmentBuilder.clampInt(5.9, 1, 10)).toBe(5)
+    })
+
+    it('returns min for NaN', () => {
+      expect(RfmSegmentBuilder.clampInt(NaN, 1, 10)).toBe(1)
+    })
+
+    it('returns min for Infinity', () => {
+      expect(RfmSegmentBuilder.clampInt(Infinity, 1, 10)).toBe(1)
+    })
+  })
+
+  describe('buildDefinition', () => {
+    const thresholds: RfmThresholdRowLike[] = [
+      // Recency thresholds (score → max_days)
+      { kind: 'r', score: 5, min_value: 0, max_value: 7 },
+      { kind: 'r', score: 4, min_value: 8, max_value: 14 },
+      { kind: 'r', score: 3, min_value: 15, max_value: 30 },
+      { kind: 'r', score: 2, min_value: 31, max_value: 60 },
+      { kind: 'r', score: 1, min_value: 61, max_value: 90 },
+      // Frequency thresholds (score → min/max count)
+      { kind: 'f', score: 1, min_value: 1, max_value: 2 },
+      { kind: 'f', score: 2, min_value: 3, max_value: 5 },
+      { kind: 'f', score: 3, min_value: 6, max_value: 10 },
+      { kind: 'f', score: 4, min_value: 11, max_value: 20 },
+      { kind: 'f', score: 5, min_value: 21, max_value: 50 },
+    ]
+
+    it('builds a valid definition for champions', () => {
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'champions',
+        thresholds,
+      })
+
+      expect(def.segment_key).toBe('champions')
+      expect(def.segment_name).toBe('Champions')
+      expect(def.window_days).toBe(90)
+      expect(def.criteria).toBeDefined()
+      expect(def.criteria.type).toBe('past-behavior')
+      expect(def.criteria.groups).toBeDefined()
+      expect(def.criteria.groups.length).toBeGreaterThanOrEqual(1)
+
+      // Frequency: score 4-5 → op >= minCount
+      expect(def.frequency.op).toBe('>=')
+      expect(def.frequency.value).toBeGreaterThanOrEqual(1)
+    })
+
+    it('builds a valid definition for hibernating (low R, low F)', () => {
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'hibernating',
+        thresholds,
+      })
+
+      expect(def.segment_key).toBe('hibernating')
+      expect(def.frequency.op).toBe('<=')
+    })
+
+    it('builds a definition with between frequency for mid-range segments', () => {
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'at_risk',
+        thresholds,
+      })
+
+      expect(def.frequency.op).toBe('between')
+      expect(def.frequency.value2).not.toBeNull()
+    })
+
+    it('throws for invalid segment key', () => {
+      expect(() => RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'nonexistent',
+        thresholds,
+      })).toThrow('segment_key inválido')
+    })
+
+    it('throws when no recency thresholds match the range', () => {
+      expect(() => RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'champions',
+        thresholds: thresholds.filter(t => t.kind === 'f'), // no recency
+      })).toThrow()
+    })
+
+    it('throws when no frequency thresholds match the range', () => {
+      expect(() => RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'champions',
+        thresholds: thresholds.filter(t => t.kind === 'r'), // no frequency
+      })).toThrow()
+    })
+
+    it('includes recency negate rule when rMax < 5', () => {
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'hibernating', // r: 1-2
+        thresholds,
+      })
+
+      const rfmGroup = def.criteria.groups[0]
+      const negateRule = rfmGroup.rules.find((r: any) => r.negate === true)
+      expect(negateRule).toBeDefined()
+    })
+
+    it('does not include negate rule when rMax >= 5', () => {
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'champions', // r: 4-5
+        thresholds,
+      })
+
+      const rfmGroup = def.criteria.groups[0]
+      const negateRule = rfmGroup.rules.find((r: any) => r.negate === true)
+      expect(negateRule).toBeUndefined()
+    })
+
+    it('merges filterCriteria groups when provided', () => {
+      const filterCriteria = {
+        groups: [{ operator: 'AND', rules: [{ kind: 'property', field: 'is_subscribed', op: 'equals', value: true }] }]
+      }
+      const def = RfmSegmentBuilder.buildDefinition({
+        rfEventName: 'purchase',
+        windowDays: 90,
+        segmentKey: 'champions',
+        thresholds,
+        filterCriteria,
+      })
+
+      // Should have the filter group + rfm group
+      expect(def.criteria.groups.length).toBe(2)
+    })
+  })
+})