@reachy/audience-module 1.0.18 → 1.0.20

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

package/src/__tests__/StaticAudienceExecutor.test.ts

@@ -0,0 +1,134 @@
+import { StaticAudienceExecutor } from '../executors/StaticAudienceExecutor'
+import { AudienceCriteria } from '../types'
+
+const validCriteria: AudienceCriteria = {
+  groups: [{ operator: 'AND', rules: [{ kind: 'property', field: 'email', op: 'contains', value: '@' }] }]
+}
+
+function mockRepo(ids: string[] = ['c1', 'c2', 'c3']) {
+  return {
+    getContactIdsByAudienceCriteriaV2: jest.fn().mockResolvedValue(new Set(ids)),
+    findByIds: jest.fn().mockResolvedValue({
+      data: ids.map(id => ({ id, email: `${id}@test.com` })),
+      error: null,
+    }),
+  }
+}
+
+describe('StaticAudienceExecutor', () => {
+  describe('execute', () => {
+    it('returns contactIds and count', async () => {
+      const executor = new StaticAudienceExecutor(mockRepo())
+      const result = await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(result.contactIds).toBeInstanceOf(Set)
+      expect(result.contactIds.size).toBe(3)
+      expect(result.count).toBe(3)
+      expect(result.metadata?.criteriaType).toBe('static')
+      expect(result.metadata?.executionTime).toBeGreaterThanOrEqual(0)
+    })
+
+    it('fetches contact details when pagination is set', async () => {
+      const repo = mockRepo(['c1', 'c2', 'c3', 'c4', 'c5'])
+      const executor = new StaticAudienceExecutor(repo)
+
+      await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+        pagination: { page: 1, limit: 2 },
+      })
+
+      expect(repo.findByIds).toHaveBeenCalled()
+      // Should request only first 2 ids
+      const calledIds = repo.findByIds.mock.calls[0][2]
+      expect(calledIds).toHaveLength(2)
+    })
+
+    it('fetches contact details when includeCount is true', async () => {
+      const repo = mockRepo()
+      const executor = new StaticAudienceExecutor(repo)
+
+      const result = await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+        includeCount: true,
+      })
+
+      expect(repo.findByIds).toHaveBeenCalled()
+      expect(result.contacts).toBeDefined()
+    })
+
+    it('does not fetch contact details without pagination or includeCount', async () => {
+      const repo = mockRepo()
+      const executor = new StaticAudienceExecutor(repo)
+
+      const result = await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(repo.findByIds).not.toHaveBeenCalled()
+      expect(result.contacts).toBeUndefined()
+    })
+
+    it('returns empty result for invalid criteria', async () => {
+      const executor = new StaticAudienceExecutor(mockRepo())
+      const result = await executor.execute({ type: 'static' }, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(result.contactIds.size).toBe(0)
+      expect(result.count).toBe(0)
+    })
+
+    it('throws when contactRepository not set', async () => {
+      const executor = new StaticAudienceExecutor()
+      await expect(executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })).rejects.toThrow('ContactRepository não foi configurado')
+    })
+
+    it('paginates correctly for page 2', async () => {
+      const repo = mockRepo(['c1', 'c2', 'c3', 'c4', 'c5'])
+      const executor = new StaticAudienceExecutor(repo)
+
+      await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+        pagination: { page: 2, limit: 2 },
+      })
+
+      const calledIds = repo.findByIds.mock.calls[0][2]
+      expect(calledIds).toEqual(['c3', 'c4'])
+    })
+  })
+
+  describe('executeCount', () => {
+    it('returns count only', async () => {
+      const executor = new StaticAudienceExecutor(mockRepo(['c1', 'c2']))
+      const count = await executor.executeCount(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+      expect(count).toBe(2)
+    })
+  })
+
+  describe('setContactRepository', () => {
+    it('allows setting repository after construction', async () => {
+      const executor = new StaticAudienceExecutor()
+      executor.setContactRepository(mockRepo())
+
+      const result = await executor.execute(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+      expect(result.count).toBe(3)
+    })
+  })
+})

package/src/__tests__/SupabaseContactRepository.test.ts

@@ -0,0 +1,81 @@
+import { SupabaseContactRepository } from '../repositories/SupabaseContactRepository'
+
+// Mock V2AudienceEngine since it requires real Supabase
+jest.mock('../engine/V2AudienceEngine', () => ({
+  V2AudienceEngine: jest.fn().mockImplementation(() => ({
+    getContactIdsByAudienceCriteriaV2: jest.fn().mockResolvedValue(new Set(['c1', 'c2'])),
+    matchesContactByAudienceCriteriaV2: jest.fn().mockResolvedValue(true),
+  })),
+}))
+
+function mockSupabase() {
+  const chainable = {
+    select: jest.fn().mockReturnThis(),
+    eq: jest.fn().mockReturnThis(),
+    in: jest.fn().mockResolvedValue({
+      data: [{ id: 'c1', email: 'a@b.com' }, { id: 'c2', email: 'c@d.com' }],
+      error: null,
+    }),
+  }
+  return {
+    from: jest.fn().mockReturnValue(chainable),
+    _chainable: chainable,
+  }
+}
+
+describe('SupabaseContactRepository', () => {
+  it('creates instance with supabase and clickhouse clients', () => {
+    const repo = new SupabaseContactRepository({
+      supabaseClient: mockSupabase(),
+      clickhouseClient: {},
+      debug: false,
+    })
+    expect(repo).toBeDefined()
+  })
+
+  describe('getContactIdsByAudienceCriteriaV2', () => {
+    it('delegates to V2AudienceEngine', async () => {
+      const repo = new SupabaseContactRepository({ supabaseClient: mockSupabase() })
+      const result = await repo.getContactIdsByAudienceCriteriaV2('org-1', 'proj-1', { groups: [] })
+
+      expect(result).toBeInstanceOf(Set)
+      expect(result.size).toBe(2)
+    })
+  })
+
+  describe('matchesContactByAudienceCriteriaV2', () => {
+    it('delegates to V2AudienceEngine', async () => {
+      const repo = new SupabaseContactRepository({ supabaseClient: mockSupabase() })
+      const result = await repo.matchesContactByAudienceCriteriaV2('org-1', 'proj-1', { groups: [] }, 'c1')
+
+      expect(result).toBe(true)
+    })
+  })
+
+  describe('findByIds', () => {
+    it('queries Supabase for contacts by IDs', async () => {
+      const supabase = mockSupabase()
+      const repo = new SupabaseContactRepository({ supabaseClient: supabase })
+
+      const { data } = await repo.findByIds('org-1', 'proj-1', ['c1', 'c2'])
+
+      expect(supabase.from).toHaveBeenCalledWith('contacts')
+      expect(supabase._chainable.select).toHaveBeenCalledWith('*')
+      expect(supabase._chainable.eq).toHaveBeenCalledWith('organization_id', 'org-1')
+      expect(supabase._chainable.eq).toHaveBeenCalledWith('project_id', 'proj-1')
+      expect(supabase._chainable.in).toHaveBeenCalledWith('id', ['c1', 'c2'])
+      expect(data).toHaveLength(2)
+    })
+
+    it('throws when Supabase returns an error', async () => {
+      const supabase = mockSupabase()
+      supabase._chainable.in = jest.fn().mockResolvedValue({
+        data: null,
+        error: new Error('DB error'),
+      })
+      const repo = new SupabaseContactRepository({ supabaseClient: supabase })
+
+      await expect(repo.findByIds('org-1', 'proj-1', ['c1'])).rejects.toThrow('DB error')
+    })
+  })
+})