@reachy/audience-module 1.0.19 → 1.0.20

package/.gitlab/merge_request_templates/Default.md

@@ -0,0 +1,31 @@
+## Descrição
+
+<!-- Descreva de forma clara o que foi feito e por quê -->
+
+
+
+## Tipo de mudança
+
+- [ ] 🐛 Bug fix
+- [ ] ✨ Nova funcionalidade
+- [ ] ♻️ Refatoração
+- [ ] 📦 Dependências
+- [ ] ⚙️ CI/CD
+- [ ] 📝 Documentação
+
+## O que foi alterado
+
+- 
+- 
+
+## Como testar
+
+1. 
+2. 
+
+## Checklist
+
+- [ ] Código segue os padrões do projeto
+- [ ] Testei localmente e funciona
+- [ ] Não introduz breaking changes
+- [ ] Commits seguem Conventional Commits

package/.gitlab-ci.yml

@@ -1,60 +1,49 @@
 image: node:20
 
+workflow:
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH'
+      when: always
+
 variables:
   GIT_DEPTH: 0
   GIT_STRATEGY: fetch
 
+include:
+  # Módulos de qualidade
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/claude-review.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/mr-description-check.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/commit-lint.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/security.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/review-gate.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/approval-check.yml'
+    ref: 'main'
+  - project: 'kontrole1/cicd/pipeline'
+    file: 'ci/templates/notifications.yml'
+    ref: 'main'
+
 stages:
+  - .pre
+  - review
   - test
   - build
   - tag
   - publish
   - notify
 
-.slack-notify-template:
-  image: alpine:3.20
-  before_script:
-    - apk add --no-cache curl jq
-    - |
-      slack_post () {
-        [ -z "${SLACK_WEBHOOK_URL:-}" ] && { echo "SLACK_WEBHOOK_URL não configurada; pulando notificação."; return 0; }
-        local color="$1" title="$2" emoji="$3" msg="$4"
-        local short_sha="${CI_COMMIT_SHA:0:8}"
-        [ -f build_info.env ] && set -a && . build_info.env && set +a || true
-        payload="$(
-          jq -n \
-            --arg ch "${SLACK_CHANNEL:-}" \
-            --arg color "$color" --arg title "$title" --arg emoji "$emoji" \
-            --arg project "$CI_PROJECT_PATH" --arg branch "$CI_COMMIT_REF_NAME" \
-            --arg sha "$short_sha" --arg actor "${GITLAB_USER_NAME:-ci}" \
-            --arg job_url "$CI_JOB_URL" --arg pipe_url "$CI_PIPELINE_URL" \
-            --arg image "${NEW_IMAGE:-${IMAGE_REPO:-}<unknown>:${IMAGE_TAG:-}}" \
-            --arg service "${PORTAINER_SERVICE_NAME:-<desconhecido>}" \
-            --arg msg "$msg" '
-            def base:
-              { attachments: [ { color: $color, blocks: [
-                  { "type":"header", "text": { "type":"plain_text", "text": ($emoji+" "+$title) } },
-                  { "type":"section", "fields": [
-                      { "type":"mrkdwn", "text": ("*Projeto:*\n"+$project) },
-                      { "type":"mrkdwn", "text": ("*Branch:*\n"+$branch) },
-                      { "type":"mrkdwn", "text": ("*Commit:*\n"+$sha) },
-                      { "type":"mrkdwn", "text": ("*Autor:*\n"+$actor) },
-                      { "type":"mrkdwn", "text": ("*Serviço:*\n"+$service) },
-                      { "type":"mrkdwn", "text": ("*Imagem:*\n"+$image) }
-                  ] },
-                  { "type":"actions", "elements": [
-                      { "type":"button", "text": { "type":"plain_text","text":"Ver Job" }, "url": $job_url },
-                      { "type":"button", "text": { "type":"plain_text","text":"Ver Pipeline" }, "url": $pipe_url }
-                  ] }
-              ] } ] };
-            def add_msg(obj):
-              if ($msg|length) > 0 then obj | .attachments[0].blocks += [ { "type":"context", "elements":[ { "type":"mrkdwn", "text": $msg } ] } ] else obj end;
-            base | (if ($ch|length) > 0 then . + {channel:$ch} else . end) | add_msg(.)
-          '
-        )"
-        curl -sS -X POST -H 'Content-type: application/json' --data "$payload" "$SLACK_WEBHOOK_URL" >/dev/null || true
-      }
-
 default:
   cache:
     key: ${CI_COMMIT_REF_SLUG}
@@ -65,6 +54,17 @@ default:
   tags:
     - docker
 
+# Security scans
+sast:
+  extends: .sast-scan
+
+dependency-scan:
+  extends: .dependency-scan
+
+secret-detection:
+  extends: .secret-detection
+
+# Pipeline original preservada
 lint_and_test:
   stage: test
   script:
@@ -104,7 +104,7 @@ create_tag:
     - |
       AUTH_USER="oauth2"
       AUTH_TOKEN="$GITLAB_TOKEN"
-      REPO_URL="https://${AUTH_USER}:${AUTH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
+      REPO_URL="${CI_SERVER_PROTOCOL}://${AUTH_USER}:${AUTH_TOKEN}@${CI_SERVER_HOST}${CI_SERVER_PORT:+:$CI_SERVER_PORT}/${CI_PROJECT_PATH}.git"
       git tag "$TAG"
     - git push "$REPO_URL" "$TAG"
   rules:
@@ -124,15 +124,25 @@ publish_npm:
       when: manual
       allow_failure: false
 
+# Notificação unificada (Slack + Roam)
 notify:publish:
-  stage: notify
-  extends: [.slack-notify-template]
+  extends: .notify-success
   needs:
     - job: publish_npm
+  script:
+    - VERSION=$(jq -r '.version' package.json 2>/dev/null || echo "?")
+    - notify_all "#2EB67D" "Publicação npm @reachy/audience-module v${VERSION}" "✅" "Pacote publicado a partir da main."
   rules:
     - if: '$CI_COMMIT_BRANCH == "main"'
       when: on_success
     - when: never
+
+notify:failure:pipeline:
+  extends: .notify-failure
+  needs: []
   script:
-    - VERSION=$(jq -r '.version' package.json)
-    - slack_post "#2EB67D" "Publicação npm concluída" ":white_check_mark:" "Pacote publicado a partir do branch main. Versão \`${VERSION}\`."
+    - notify_all "#E01E5A" "Pipeline Audience Module falhou" "❌" ""
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_failure
+    - when: never

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reachy/audience-module",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "Módulo reutilizável para consultas e criação de audiences",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,6 +8,9 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "clean": "rm -rf dist",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "keywords": [
@@ -23,7 +26,10 @@
     "@supabase/supabase-js": "^2.x"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9",
     "typescript": "^5.0.0"
   },
   "repository": {
@@ -34,4 +40,3 @@
     "access": "public"
   }
 }
-

package/src/__tests__/AudienceModule.test.ts

@@ -0,0 +1,382 @@
+import { AudienceModule } from '../AudienceModule'
+import { AudienceCriteria } from '../types'
+
+function mockContactRepository(contactIds: Set<string> = new Set(['c1', 'c2'])) {
+  return {
+    getContactIdsByAudienceCriteriaV2: jest.fn().mockResolvedValue(contactIds),
+    matchesContactByAudienceCriteriaV2: jest.fn().mockImplementation(
+      (_org: string, _proj: string, _criteria: any, contactId: string) =>
+        Promise.resolve(contactIds.has(contactId))
+    ),
+    findByIds: jest.fn().mockResolvedValue({
+      data: Array.from(contactIds).map(id => ({ id, email: `${id}@test.com` })),
+      error: null,
+    }),
+  }
+}
+
+function mockAudienceRepository() {
+  return {
+    create: jest.fn().mockResolvedValue({ data: { id: 'aud-1', name: 'Test', count: 0 }, error: null }),
+    update: jest.fn().mockResolvedValue({ data: { id: 'aud-1', name: 'Updated' }, error: null }),
+    updateCount: jest.fn().mockResolvedValue(undefined),
+    findById: jest.fn().mockResolvedValue({ data: { id: 'aud-1' }, error: null }),
+    delete: jest.fn().mockResolvedValue({ data: null, error: null }),
+  }
+}
+
+function mockMemberRepository() {
+  return {
+    bulkUpsert: jest.fn().mockResolvedValue({ data: [], error: null }),
+    listMembers: jest.fn().mockResolvedValue({ data: [{ id: 'c1' }], count: 1 }),
+  }
+}
+
+const validCriteria: AudienceCriteria = {
+  groups: [{ operator: 'AND', rules: [{ kind: 'property', field: 'email', op: 'contains', value: '@' }] }]
+}
+
+describe('AudienceModule', () => {
+  describe('constructor', () => {
+    it('creates instance without config', () => {
+      const mod = new AudienceModule()
+      expect(mod).toBeInstanceOf(AudienceModule)
+    })
+
+    it('creates instance with supabaseClient and sets up internal repo', () => {
+      // Just verifying no throw — actual Supabase calls are mocked in integration tests
+      expect(() => new AudienceModule({ supabaseClient: {} })).not.toThrow()
+    })
+  })
+
+  describe('setRepositories', () => {
+    it('accepts contactRepository', () => {
+      const mod = new AudienceModule()
+      const repo = mockContactRepository()
+      mod.setRepositories({ contactRepository: repo })
+      // No error = success
+    })
+
+    it('accepts all repositories', () => {
+      const mod = new AudienceModule()
+      mod.setRepositories({
+        contactRepository: mockContactRepository(),
+        audienceRepository: mockAudienceRepository(),
+        memberRepository: mockMemberRepository(),
+      })
+    })
+  })
+
+  describe('executeQuery', () => {
+    it('executes static query and returns contactIds', async () => {
+      const mod = new AudienceModule()
+      const repo = mockContactRepository(new Set(['c1', 'c2', 'c3']))
+      mod.setRepositories({ contactRepository: repo })
+
+      const result = await mod.executeQuery(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(result.contactIds.size).toBe(3)
+      expect(result.count).toBe(3)
+      expect(result.metadata?.criteriaType).toBe('static')
+    })
+
+    it('parses JSON string criteria', async () => {
+      const mod = new AudienceModule()
+      const repo = mockContactRepository()
+      mod.setRepositories({ contactRepository: repo })
+
+      const result = await mod.executeQuery(JSON.stringify(validCriteria), {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(result.contactIds.size).toBe(2)
+    })
+
+    it('executes live query using memberRepository', async () => {
+      const mod = new AudienceModule()
+      const memberRepo = mockMemberRepository()
+      mod.setRepositories({ memberRepository: memberRepo })
+
+      const liveCriteria: AudienceCriteria = {
+        type: 'live-actions',
+        groups: [{ rules: [{ kind: 'event', eventName: 'click' }] }]
+      }
+
+      const result = await mod.executeQuery(liveCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(result.metadata?.criteriaType).toBe('live')
+      expect(memberRepo.listMembers).toHaveBeenCalled()
+    })
+
+    it('throws when memberRepository is not set for live query', async () => {
+      const mod = new AudienceModule()
+      const liveCriteria: AudienceCriteria = { type: 'live-page-visit', groups: [] }
+
+      await expect(mod.executeQuery(liveCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })).rejects.toThrow('MemberRepository não configurado')
+    })
+  })
+
+  describe('getContactCount', () => {
+    it('returns count of matching contacts', async () => {
+      const mod = new AudienceModule()
+      mod.setRepositories({ contactRepository: mockContactRepository(new Set(['c1', 'c2'])) })
+
+      const count = await mod.getContactCount(validCriteria, {
+        organizationId: 'org-1',
+        projectId: 'proj-1',
+      })
+
+      expect(count).toBe(2)
+    })
+  })
+
+  describe('getContactIds', () => {
+    it('returns Set of contact IDs', async () => {
+      const mod = new AudienceModule()
+      const repo = mockContactRepository(new Set(['c1', 'c2']))
+      mod.setRepositories({ contactRepository: repo })
+
+      const ids = await mod.getContactIds(validCriteria, 'org-1', 'proj-1')
+      expect(ids).toBeInstanceOf(Set)
+      expect(ids.size).toBe(2)
+      expect(repo.getContactIdsByAudienceCriteriaV2).toHaveBeenCalledWith('org-1', 'proj-1', expect.any(Object))
+    })
+
+    it('throws when contactRepository not configured', async () => {
+      const mod = new AudienceModule()
+      await expect(mod.getContactIds(validCriteria, 'org-1', 'proj-1'))
+        .rejects.toThrow('ContactRepository não configurado')
+    })
+  })
+
+  describe('matchesContact', () => {
+    it('returns true for matching contact', async () => {
+      const mod = new AudienceModule()
+      mod.setRepositories({ contactRepository: mockContactRepository(new Set(['c1', 'c2'])) })
+
+      const result = await mod.matchesContact(validCriteria, 'org-1', 'proj-1', 'c1')
+      expect(result).toBe(true)
+    })
+
+    it('returns false for non-matching contact', async () => {
+      const mod = new AudienceModule()
+      mod.setRepositories({ contactRepository: mockContactRepository(new Set(['c1'])) })
+
+      const result = await mod.matchesContact(validCriteria, 'org-1', 'proj-1', 'c99')
+      expect(result).toBe(false)
+    })
+
+    it('falls back to getContactIds when matchesContactByAudienceCriteriaV2 is missing', async () => {
+      const mod = new AudienceModule()
+      const repo = {
+        getContactIdsByAudienceCriteriaV2: jest.fn().mockResolvedValue(new Set(['c1'])),
+        findByIds: jest.fn(),
+      }
+      mod.setRepositories({ contactRepository: repo })
+
+      const result = await mod.matchesContact(validCriteria, 'org-1', 'proj-1', 'c1')
+      expect(result).toBe(true)
+      expect(repo.getContactIdsByAudienceCriteriaV2).toHaveBeenCalled()
+    })
+
+    it('throws when contactRepository not configured', async () => {
+      const mod = new AudienceModule()
+      await expect(mod.matchesContact(validCriteria, 'org-1', 'proj-1', 'c1'))
+        .rejects.toThrow('ContactRepository não configurado')
+    })
+  })
+
+  describe('CRUD operations', () => {
+    it('createAudience validates and creates', async () => {
+      const mod = new AudienceModule()
+      const audienceRepo = mockAudienceRepository()
+      const contactRepo = mockContactRepository()
+      mod.setRepositories({ contactRepository: contactRepo, audienceRepository: audienceRepo })
+
+      const result = await mod.createAudience({
+        name: 'Test Audience',
+        criteria: validCriteria,
+        organization_id: 'org-1',
+        project_id: 'proj-1',
+        user_id: 'user-1',
+      })
+
+      expect(result.data).toBeDefined()
+      expect(audienceRepo.create).toHaveBeenCalled()
+      expect(audienceRepo.updateCount).toHaveBeenCalled()
+    })
+
+    it('createAudience throws on invalid criteria', async () => {
+      const mod = new AudienceModule()
+      mod.setRepositories({ audienceRepository: mockAudienceRepository() })
+
+      await expect(mod.createAudience({
+        name: 'Bad',
+        criteria: {} as AudienceCriteria,
+        organization_id: 'org-1',
+        project_id: 'proj-1',
+        user_id: 'user-1',
+      })).rejects.toThrow('Critérios inválidos')
+    })
+
+    it('createAudience throws when audienceRepository not set', async () => {
+      const mod = new AudienceModule()
+      await expect(mod.createAudience({
+        name: 'Test',
+        criteria: validCriteria,
+        organization_id: 'org-1',
+        project_id: 'proj-1',
+        user_id: 'user-1',
+      })).rejects.toThrow('AudienceRepository não configurado')
+    })
+
+    it('updateAudience updates and recounts', async () => {
+      const mod = new AudienceModule()
+      const audienceRepo = mockAudienceRepository()
+      const contactRepo = mockContactRepository()
+      mod.setRepositories({ contactRepository: contactRepo, audienceRepository: audienceRepo })
+
+      const result = await mod.updateAudience('aud-1', { criteria: validCriteria }, 'org-1', 'proj-1')
+      expect(result.data).toBeDefined()
+      expect(audienceRepo.update).toHaveBeenCalled()
+      expect(audienceRepo.updateCount).toHaveBeenCalled()
+    })
+
+    it('getAudienceById delegates to repository', async () => {
+      const mod = new AudienceModule()
+      const audienceRepo = mockAudienceRepository()
+      mod.setRepositories({ audienceRepository: audienceRepo })
+
+      await mod.getAudienceById('aud-1', 'org-1', 'proj-1')
+      expect(audienceRepo.findById).toHaveBeenCalledWith('aud-1', 'org-1', 'proj-1')
+    })
+
+    it('deleteAudience delegates to repository', async () => {
+      const mod = new AudienceModule()
+      const audienceRepo = mockAudienceRepository()
+      mod.setRepositories({ audienceRepository: audienceRepo })
+
+      await mod.deleteAudience('aud-1')
+      expect(audienceRepo.delete).toHaveBeenCalledWith('aud-1')
+    })
+  })
+
+  describe('hasEventRule', () => {
+    it('returns true when event rule matches', () => {
+      const mod = new AudienceModule()
+      const criteria = {
+        groups: [{ rules: [{ kind: 'event', eventName: 'purchase' }] }]
+      }
+      expect(mod.hasEventRule(criteria, 'purchase')).toBe(true)
+    })
+
+    it('returns false when event name does not match', () => {
+      const mod = new AudienceModule()
+      const criteria = {
+        groups: [{ rules: [{ kind: 'event', eventName: 'click' }] }]
+      }
+      expect(mod.hasEventRule(criteria, 'purchase')).toBe(false)
+    })
+
+    it('returns false when no event rules exist', () => {
+      const mod = new AudienceModule()
+      const criteria = {
+        groups: [{ rules: [{ kind: 'property', field: 'email', op: 'equals', value: 'x' }] }]
+      }
+      expect(mod.hasEventRule(criteria, 'purchase')).toBe(false)
+    })
+
+    it('handles JSON string input', () => {
+      const mod = new AudienceModule()
+      const criteria = JSON.stringify({
+        groups: [{ rules: [{ kind: 'event', eventName: 'signup' }] }]
+      })
+      expect(mod.hasEventRule(criteria, 'signup')).toBe(true)
+    })
+
+    it('returns false for invalid JSON', () => {
+      const mod = new AudienceModule()
+      expect(mod.hasEventRule('invalid-json', 'signup')).toBe(false)
+    })
+
+    it('returns false for empty criteria', () => {
+      const mod = new AudienceModule()
+      expect(mod.hasEventRule({}, 'signup')).toBe(false)
+    })
+  })
+
+  describe('members management', () => {
+    it('addMembers delegates to memberRepository', async () => {
+      const mod = new AudienceModule()
+      const memberRepo = mockMemberRepository()
+      mod.setRepositories({ memberRepository: memberRepo })
+
+      await mod.addMembers('aud-1', ['c1', 'c2'], 'org-1', 'proj-1', 'realtime')
+      expect(memberRepo.bulkUpsert).toHaveBeenCalledWith('aud-1', 'org-1', 'proj-1', ['c1', 'c2'], 'realtime')
+    })
+
+    it('addMembers defaults origin to "backfill"', async () => {
+      const mod = new AudienceModule()
+      const memberRepo = mockMemberRepository()
+      mod.setRepositories({ memberRepository: memberRepo })
+
+      await mod.addMembers('aud-1', ['c1'], 'org-1', 'proj-1')
+      expect(memberRepo.bulkUpsert).toHaveBeenCalledWith('aud-1', 'org-1', 'proj-1', ['c1'], 'backfill')
+    })
+
+    it('addMembers throws when memberRepository not set', async () => {
+      const mod = new AudienceModule()
+      await expect(mod.addMembers('aud-1', ['c1'], 'org-1', 'proj-1'))
+        .rejects.toThrow('MemberRepository não configurado')
+    })
+
+    it('getMembers delegates to memberRepository', async () => {
+      const mod = new AudienceModule()
+      const memberRepo = mockMemberRepository()
+      mod.setRepositories({ memberRepository: memberRepo })
+
+      await mod.getMembers('aud-1', 'org-1', 'proj-1', { page: 1, limit: 10 })
+      expect(memberRepo.listMembers).toHaveBeenCalledWith('aud-1', 'org-1', 'proj-1', { page: 1, limit: 10 })
+    })
+  })
+
+  describe('utilities', () => {
+    it('validateCriteria returns valid for good criteria', () => {
+      const mod = new AudienceModule()
+      const result = mod.validateCriteria(validCriteria)
+      expect(result.valid).toBe(true)
+    })
+
+    it('validateCriteria returns invalid for empty criteria', () => {
+      const mod = new AudienceModule()
+      const result = mod.validateCriteria({ type: 'static' })
+      expect(result.valid).toBe(false)
+    })
+
+    it('validateCriteria parses JSON string', () => {
+      const mod = new AudienceModule()
+      const result = mod.validateCriteria(JSON.stringify(validCriteria))
+      expect(result.valid).toBe(true)
+    })
+
+    it('getAudienceType returns "static" for property criteria', () => {
+      const mod = new AudienceModule()
+      expect(mod.getAudienceType(validCriteria)).toBe('static')
+    })
+
+    it('getAudienceType returns "live" for live criteria', () => {
+      const mod = new AudienceModule()
+      expect(mod.getAudienceType({ type: 'live-actions', groups: [] })).toBe('live')
+    })
+  })
+})