@reachy/audience-module 1.0.2 → 1.0.3

package/.gitlab-ci.yml

@@ -0,0 +1,138 @@
+image: node:20
+
+variables:
+  GIT_DEPTH: 0
+  GIT_STRATEGY: fetch
+
+stages:
+  - 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}
+    paths:
+      - node_modules/
+  before_script:
+    - npm ci
+  tags:
+    - docker
+
+lint_and_test:
+  stage: test
+  script:
+    - npm test -- --watch=false || echo "No tests configured"
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+build:
+  stage: build
+  script:
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+  needs:
+    - lint_and_test
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+create_tag:
+  stage: tag
+  needs:
+    - build
+  before_script: []
+  script:
+    - git config --global user.email "${GITLAB_USER_EMAIL:-ci@gitlab}"
+    - git config --global user.name "${GITLAB_USER_NAME:-gitlab-ci}"
+    - git fetch --all --tags
+    - VERSION=$(node -p "require('./package.json').version")
+    - TAG="v${VERSION}"
+    - if git rev-parse "$TAG" >/dev/null 2>&1; then echo "Tag $TAG already exists, skipping"; exit 0; fi
+    - |
+      if [ -z "${GITLAB_TOKEN:-}" ]; then
+        echo "GITLAB_TOKEN não configurado com permissão write_repository; não é possível criar tag."
+        exit 1
+      fi
+    - |
+      AUTH_USER="oauth2"
+      AUTH_TOKEN="$GITLAB_TOKEN"
+      REPO_URL="https://${AUTH_USER}:${AUTH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
+      git tag "$TAG"
+    - git push "$REPO_URL" "$TAG"
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+
+publish_npm:
+  stage: publish
+  needs:
+    - job: build
+      artifacts: true
+    - create_tag
+  script:
+    - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+    - npm publish --access public
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+      allow_failure: false
+
+notify:publish:
+  stage: notify
+  extends: [.slack-notify-template]
+  needs:
+    - job: publish_npm
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: on_success
+    - when: never
+  script:
+    - slack_post "#2EB67D" "Publicação npm concluída" ":white_check_mark:" \
+        "Pacote publicado a partir do branch main. Versão \`$(node -p \"require('./package.json').version\")\`."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reachy/audience-module",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Módulo reutilizável para consultas e criação de audiences",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/AudienceModule.ts

@@ -0,0 +1,353 @@
+import { StaticAudienceExecutor } from './executors/StaticAudienceExecutor'
+import { CriteriaParser } from './builders/CriteriaParser'
+import {
+  AudienceCriteria,
+  AudienceQueryOptions,
+  AudienceExecutionResult,
+  AudienceBuilderConfig,
+  CreateAudienceData,
+  UpdateAudienceData
+} from './types'
+
+/**
+ * Módulo centralizado para todas as operações de Audience
+ * 
+ * @example
+ * ```typescript
+ * const audienceModule = new AudienceModule()
+ * 
+ * // Configurar repositórios necessários
+ * audienceModule.setRepositories({
+ *   contactRepository,
+ *   audienceRepository,
+ *   memberRepository
+ * })
+ * 
+ * // Executar query de audiência
+ * const result = await audienceModule.executeQuery(criteria, {
+ *   organizationId: 'org-123',
+ *   projectId: 'proj-456'
+ * })
+ * ```
+ */
+export class AudienceModule {
+  private audienceRepository: any
+  private memberRepository: any
+  private contactRepository: any
+  private staticExecutor: StaticAudienceExecutor
+
+  constructor(config: AudienceBuilderConfig = {}) {
+    this.staticExecutor = new StaticAudienceExecutor()
+    
+    // Log config se debug estiver habilitado
+    if (config.enableDebugLogs) {
+      console.log('🔧 AudienceModule configurado:', config)
+    }
+  }
+
+  /**
+   * Configura os repositórios necessários
+   * Deve ser chamado antes de usar o módulo
+   */
+  setRepositories(repositories: {
+    contactRepository?: any
+    audienceRepository?: any
+    memberRepository?: any
+  }) {
+    if (repositories.contactRepository) {
+      this.contactRepository = repositories.contactRepository
+      this.staticExecutor.setContactRepository(repositories.contactRepository)
+    }
+    if (repositories.audienceRepository) {
+      this.audienceRepository = repositories.audienceRepository
+    }
+    if (repositories.memberRepository) {
+      this.memberRepository = repositories.memberRepository
+    }
+  }
+
+  // ===========================
+  // QUERY EXECUTION
+  // ===========================
+
+  /**
+   * Executa query de audiência e retorna resultados
+   */
+  async executeQuery(
+    criteria: string | AudienceCriteria,
+    options: AudienceQueryOptions
+  ): Promise<AudienceExecutionResult> {
+    const parsed = CriteriaParser.parse(criteria)
+    const type = CriteriaParser.getAudienceType(parsed)
+
+    if (type === 'static') {
+      return this.staticExecutor.execute(parsed, options)
+    } else {
+      return this.executeLiveQuery(parsed, options)
+    }
+  }
+
+  /**
+   * Retorna apenas a contagem de contatos (mais rápido)
+   */
+  async getContactCount(
+    criteria: string | AudienceCriteria,
+    options: Omit<AudienceQueryOptions, 'pagination'>
+  ): Promise<number> {
+    const parsed = CriteriaParser.parse(criteria)
+    return this.staticExecutor.executeCount(parsed, options)
+  }
+
+  /**
+   * Retorna IDs de contatos que atendem aos critérios
+   */
+  async getContactIds(
+    criteria: string | AudienceCriteria,
+    organizationId: string,
+    projectId: string
+  ): Promise<Set<string>> {
+    if (!this.contactRepository) {
+      throw new Error('ContactRepository não configurado')
+    }
+
+    const parsed = CriteriaParser.parse(criteria)
+    return this.contactRepository.getContactIdsByAudienceCriteriaV2(
+      organizationId,
+      projectId,
+      parsed
+    )
+  }
+
+  // ===========================
+  // CRUD OPERATIONS
+  // ===========================
+
+  /**
+   * Cria nova audiência
+   */
+  async createAudience(data: CreateAudienceData) {
+    if (!this.audienceRepository) {
+      throw new Error('AudienceRepository não configurado')
+    }
+
+    const validation = CriteriaParser.validate(data.criteria)
+    if (!validation.valid) {
+      throw new Error(`Critérios inválidos: ${validation.errors.join(', ')}`)
+    }
+
+    const { data: audience, error } = await this.audienceRepository.create(data)
+    if (error) throw error
+
+    const type = CriteriaParser.getAudienceType(data.criteria)
+    if (type === 'static') {
+      const count = await this.getContactCount(data.criteria, {
+        organizationId: data.organization_id,
+        projectId: data.project_id
+      })
+      
+      await this.audienceRepository.updateCount(audience!.id, count)
+      audience!.count = count
+    }
+
+    return { data: audience, error: null }
+  }
+
+  /**
+   * Atualiza audiência existente
+   */
+  async updateAudience(
+    id: string,
+    updateData: UpdateAudienceData,
+    organizationId: string,
+    projectId: string
+  ) {
+    if (!this.audienceRepository) {
+      throw new Error('AudienceRepository não configurado')
+    }
+
+    if (updateData.criteria) {
+      const validation = CriteriaParser.validate(updateData.criteria)
+      if (!validation.valid) {
+        throw new Error(`Critérios inválidos: ${validation.errors.join(', ')}`)
+      }
+    }
+
+    const { data: audience, error } = await this.audienceRepository.update(id, updateData)
+    if (error) throw error
+
+    if (updateData.criteria) {
+      const type = CriteriaParser.getAudienceType(updateData.criteria)
+      if (type === 'static') {
+        const count = await this.getContactCount(updateData.criteria, {
+          organizationId,
+          projectId
+        })
+        
+        await this.audienceRepository.updateCount(id, count)
+        audience!.count = count
+      }
+    }
+
+    return { data: audience, error: null }
+  }
+
+  /**
+   * Busca audiência por ID
+   */
+  async getAudienceById(id: string, organizationId: string, projectId: string) {
+    if (!this.audienceRepository) {
+      throw new Error('AudienceRepository não configurado')
+    }
+    return this.audienceRepository.findById(id, organizationId, projectId)
+  }
+
+  /**
+   * Deleta audiência
+   */
+  async deleteAudience(id: string) {
+    if (!this.audienceRepository) {
+      throw new Error('AudienceRepository não configurado')
+    }
+    return this.audienceRepository.delete(id)
+  }
+
+  // ===========================
+  // MEMBERS MANAGEMENT
+  // ===========================
+
+  /**
+   * Verifica se uma audience tem regra de evento específico
+   */
+  hasEventRule(criteria: any, eventName: string): boolean {
+    try {
+      // Parse do critério
+      let parsed = criteria
+      if (typeof criteria === 'string') {
+        try {
+          parsed = JSON.parse(criteria)
+        } catch {
+          return false
+        }
+      }
+
+      // Verificar formato V2 com groups/rules
+      if (parsed.groups && Array.isArray(parsed.groups)) {
+        for (const group of parsed.groups) {
+          if (group.rules && Array.isArray(group.rules)) {
+            const found = group.rules.some((rule: any) => 
+              rule.kind === 'event' && rule.eventName === eventName
+            )
+            if (found) return true
+          }
+        }
+      }
+
+      return false
+    } catch (error) {
+      console.error('Error checking event rule:', error)
+      return false
+    }
+  }
+
+  /**
+   * Adiciona contatos à audiência (bulk)
+   */
+  async addMembers(
+    audienceId: string,
+    contactIds: string[],
+    organizationId: string,
+    projectId: string,
+    origin: 'realtime' | 'backfill' = 'backfill'
+  ) {
+    if (!this.memberRepository) {
+      throw new Error('MemberRepository não configurado')
+    }
+
+    return this.memberRepository.bulkUpsert(
+      audienceId,
+      organizationId,
+      projectId,
+      contactIds,
+      origin
+    )
+  }
+
+  /**
+   * Lista membros da audiência
+   */
+  async getMembers(
+    audienceId: string,
+    organizationId: string,
+    projectId: string,
+    pagination?: { page?: number; limit?: number }
+  ) {
+    if (!this.memberRepository) {
+      throw new Error('MemberRepository não configurado')
+    }
+
+    return this.memberRepository.listMembers(
+      audienceId,
+      organizationId,
+      projectId,
+      pagination
+    )
+  }
+
+  // ===========================
+  // UTILITIES
+  // ===========================
+
+  /**
+   * Valida critérios de audiência
+   */
+  validateCriteria(criteria: string | AudienceCriteria) {
+    const parsed = CriteriaParser.parse(criteria)
+    return CriteriaParser.validate(parsed)
+  }
+
+  /**
+   * Detecta tipo de audiência
+   */
+  getAudienceType(criteria: string | AudienceCriteria): 'static' | 'live' {
+    const parsed = CriteriaParser.parse(criteria)
+    return CriteriaParser.getAudienceType(parsed)
+  }
+
+  // ===========================
+  // PRIVATE METHODS
+  // ===========================
+
+  /**
+   * Executa query de audiência live
+   */
+  private async executeLiveQuery(
+    _criteria: AudienceCriteria,
+    options: AudienceQueryOptions
+  ): Promise<AudienceExecutionResult> {
+    const startTime = Date.now()
+
+    if (!this.memberRepository) {
+      throw new Error('MemberRepository não configurado para audiences live')
+    }
+
+    const { data: members, count } = await this.memberRepository.listMembers(
+      '',
+      options.organizationId,
+      options.projectId,
+      options.pagination
+    )
+
+    const contactIds = new Set<string>(members?.map((m: any) => m.id) || [])
+
+    return {
+      contactIds,
+      contacts: members || [],
+      count: count || 0,
+      metadata: {
+        executionTime: Date.now() - startTime,
+        criteriaType: 'live'
+      }
+    }
+  }
+}
+

package/src/builders/CriteriaParser.ts

@@ -0,0 +1,88 @@
+import { AudienceCriteria } from '../types'
+
+/**
+ * Parser centralizado para normalizar diferentes formatos de critérios
+ */
+export class CriteriaParser {
+  /**
+   * Parse e normaliza critérios para formato padrão
+   */
+  static parse(criteria: string | AudienceCriteria): AudienceCriteria {
+    let parsed: AudienceCriteria
+
+    if (typeof criteria === 'string') {
+      try {
+        parsed = JSON.parse(criteria)
+      } catch (error) {
+        console.error('❌ Erro ao fazer parse de critérios:', error)
+        throw new Error('Critérios inválidos')
+      }
+    } else {
+      parsed = criteria
+    }
+
+    return this.normalizeCriteria(parsed)
+  }
+
+  /**
+   * Normaliza diferentes formatos de critérios para um formato único
+   */
+  private static normalizeCriteria(criteria: AudienceCriteria): AudienceCriteria {
+    if (criteria.filters && Array.isArray(criteria.filters)) {
+      return {
+        ...criteria,
+        conditions: criteria.filters.map(filter => ({
+          groupId: filter.id,
+          operator: filter.operator as 'AND' | 'OR',
+          conditions: filter.conditions.map(cond => ({
+            field: cond.field,
+            operator: cond.operator,
+            value: cond.value,
+            customFieldKey: cond.customFieldKey,
+            logicalOperator: cond.logicalOperator as 'AND' | 'OR' | undefined
+          }))
+        }))
+      }
+    }
+
+    if (criteria.groups) {
+      return criteria
+    }
+
+    return criteria
+  }
+
+  /**
+   * Detecta o tipo de audiência
+   */
+  static getAudienceType(criteria: AudienceCriteria): 'static' | 'live' {
+    const liveTypes = ['live-actions', 'live-page-visit', 'live-referrer', 'live-page-count']
+    return liveTypes.includes(criteria.type || '') ? 'live' : 'static'
+  }
+
+  /**
+   * Valida se os critérios são válidos
+   */
+  static validate(criteria: AudienceCriteria): { valid: boolean; errors: string[] } {
+    const errors: string[] = []
+
+    if (!criteria || typeof criteria !== 'object') {
+      errors.push('Critérios devem ser um objeto')
+      return { valid: false, errors }
+    }
+
+    const hasConditions = criteria.conditions && Array.isArray(criteria.conditions)
+    const hasFilters = criteria.filters && Array.isArray(criteria.filters)
+    const hasGroups = criteria.groups && Array.isArray(criteria.groups)
+
+    if (!hasConditions && !hasFilters && !hasGroups) {
+      errors.push('Critérios devem conter conditions, filters ou groups')
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    }
+  }
+}
+

package/src/builders/QueryBuilder.ts

@@ -0,0 +1,231 @@
+import { AudienceCriteria } from '../types'
+
+/**
+ * Construtor de queries para diferentes tipos de critérios
+ */
+export class QueryBuilder {
+  /**
+   * Constrói filtros Supabase baseado nos critérios
+   */
+  static buildFilters(query: any, criteria: AudienceCriteria, organizationId: string, projectId: string): any {
+    query = query
+      .eq('organization_id', organizationId)
+      .eq('project_id', projectId)
+
+    return this.applyAudienceCriteria(query, criteria)
+  }
+
+  /**
+   * Aplica critérios de audiência ao query
+   */
+  private static applyAudienceCriteria(query: any, criteria: AudienceCriteria): any {
+    if (criteria.groups && Array.isArray(criteria.groups)) {
+      return this.applyGroupsCriteria(query, criteria.groups)
+    }
+
+    if (criteria.filters && Array.isArray(criteria.filters)) {
+      return this.applyFiltersCriteria(query, criteria.filters)
+    }
+
+    if (criteria.conditions && Array.isArray(criteria.conditions)) {
+      return this.applyConditionsCriteria(query, criteria.conditions)
+    }
+
+    return query
+  }
+
+  /**
+   * Aplica filtros no formato 'groups' (v2)
+   */
+  private static applyGroupsCriteria(query: any, groups: any[]): any {
+    const orConditions: string[] = []
+
+    for (const group of groups) {
+      if (!group.rules || !Array.isArray(group.rules)) continue
+
+      const groupConditions: string[] = []
+
+      for (const rule of group.rules) {
+        const condition = this.buildConditionString(rule)
+        if (condition) {
+          groupConditions.push(condition)
+        }
+      }
+
+      if (groupConditions.length > 0) {
+        orConditions.push(groupConditions.join(','))
+      }
+    }
+
+    if (orConditions.length > 0) {
+      query = query.or(orConditions.join(','))
+    }
+
+    return query
+  }
+
+  /**
+   * Aplica filtros no formato 'filters' (v1)
+   */
+  private static applyFiltersCriteria(query: any, filters: any[]): any {
+    const orGroups = filters.filter(f => f.operator === 'OR')
+    const andGroups = filters.filter(f => f.operator !== 'OR')
+
+    if (orGroups.length > 0) {
+      const orConditions: string[] = []
+
+      for (const filterGroup of orGroups) {
+        const groupConditions: string[] = []
+
+        for (const condition of filterGroup.conditions) {
+          const condStr = this.buildConditionString(condition)
+          if (condStr) {
+            groupConditions.push(condStr)
+          }
+        }
+
+        if (groupConditions.length > 0) {
+          orConditions.push(groupConditions.join(','))
+        }
+      }
+
+      if (orConditions.length > 0) {
+        query = query.or(orConditions.join(','))
+      }
+    }
+
+    for (const filterGroup of andGroups) {
+      for (const condition of filterGroup.conditions) {
+        query = this.applyCondition(query, condition)
+      }
+    }
+
+    return query
+  }
+
+  /**
+   * Aplica critérios no formato 'conditions' (normalizado)
+   */
+  private static applyConditionsCriteria(query: any, conditions: any[]): any {
+    for (const group of conditions) {
+      if (group.operator === 'OR') {
+        const orConditions = group.conditions.map((c: any) => this.buildConditionString(c)).filter(Boolean)
+        if (orConditions.length > 0) {
+          query = query.or(orConditions.join(','))
+        }
+      } else {
+        for (const condition of group.conditions) {
+          query = this.applyCondition(query, condition)
+        }
+      }
+    }
+
+    return query
+  }
+
+  /**
+   * Aplica uma condição individual ao query
+   */
+  private static applyCondition(query: any, condition: any): any {
+    const { field, operator, value } = condition
+
+    const dbField = this.mapFieldToColumn(field, condition.customFieldKey)
+
+    switch (operator) {
+      case 'equals':
+      case 'eq':
+        return query.eq(dbField, value)
+      case 'not_equals':
+      case 'neq':
+        return query.neq(dbField, value)
+      case 'contains':
+      case 'ilike':
+        return query.ilike(dbField, `%${value}%`)
+      case 'not_contains':
+        return query.not.ilike(dbField, `%${value}%`)
+      case 'starts_with':
+        return query.ilike(dbField, `${value}%`)
+      case 'ends_with':
+        return query.ilike(dbField, `%${value}`)
+      case 'greater_than':
+      case 'gt':
+        return query.gt(dbField, value)
+      case 'less_than':
+      case 'lt':
+        return query.lt(dbField, value)
+      case 'is_empty':
+        return query.or(`${dbField}.is.null,${dbField}.eq.`)
+      case 'is_not_empty':
+        return query.not.is(dbField, null)
+      default:
+        console.warn(`⚠️ Operador desconhecido: ${operator}`)
+        return query
+    }
+  }
+
+  /**
+   * Constrói string de condição para uso em .or()
+   */
+  private static buildConditionString(condition: any): string | null {
+    const { field, operator, value } = condition
+
+    if (!field || !operator) return null
+
+    const dbField = this.mapFieldToColumn(field, condition.customFieldKey)
+
+    switch (operator) {
+      case 'equals':
+      case 'eq':
+        return `${dbField}.eq.${value}`
+      case 'not_equals':
+      case 'neq':
+        return `${dbField}.neq.${value}`
+      case 'contains':
+      case 'ilike':
+        return `${dbField}.ilike.*${value}*`
+      case 'not_contains':
+        return `${dbField}.not.ilike.*${value}*`
+      case 'starts_with':
+        return `${dbField}.ilike.${value}*`
+      case 'ends_with':
+        return `${dbField}.ilike.*${value}`
+      case 'greater_than':
+      case 'gt':
+        return `${dbField}.gt.${value}`
+      case 'less_than':
+      case 'lt':
+        return `${dbField}.lt.${value}`
+      case 'is_empty':
+        return `${dbField}.is.null`
+      case 'is_not_empty':
+        return `${dbField}.not.is.null`
+      default:
+        return null
+    }
+  }
+
+  /**
+   * Mapeia campo da audiência para coluna do banco
+   */
+  private static mapFieldToColumn(field: string, customFieldKey?: string): string {
+    if (field === 'custom_field' && customFieldKey) {
+      return `properties->>${customFieldKey}`
+    }
+
+    const fieldMap: Record<string, string> = {
+      email: 'email',
+      name: 'name',
+      phone: 'phone',
+      city: 'city',
+      state: 'state',
+      country: 'country',
+      created_at: 'created_at',
+      updated_at: 'updated_at',
+      opted_in: 'opted_in',
+      is_subscribed: 'is_subscribed'
+    }
+
+    return fieldMap[field] || field
+  }
+}
+

package/src/executors/StaticAudienceExecutor.ts

@@ -0,0 +1,105 @@
+import { AudienceCriteria, AudienceQueryOptions, AudienceExecutionResult } from '../types'
+import { CriteriaParser } from '../builders/CriteriaParser'
+
+/**
+ * Executor para audiências estáticas (baseadas em filtros)
+ * 
+ * NOTA: Este executor precisa de uma instância de ContactRepository
+ * que deve ser injetada externamente quando usado no reachy-api
+ */
+export class StaticAudienceExecutor {
+  private contactRepository: any
+
+  constructor(contactRepository?: any) {
+    this.contactRepository = contactRepository
+  }
+
+  /**
+   * Define o ContactRepository
+   */
+  setContactRepository(repository: any) {
+    this.contactRepository = repository
+  }
+
+  /**
+   * Executa query de audiência estática e retorna IDs de contatos
+   */
+  async execute(
+    criteria: AudienceCriteria,
+    options: AudienceQueryOptions
+  ): Promise<AudienceExecutionResult> {
+    const startTime = Date.now()
+
+    try {
+      if (!this.contactRepository) {
+        throw new Error('ContactRepository não foi configurado. Use setContactRepository() antes de executar.')
+      }
+
+      const parsed = CriteriaParser.parse(criteria)
+      const validation = CriteriaParser.validate(parsed)
+
+      if (!validation.valid) {
+        console.error('❌ Critérios inválidos:', validation.errors)
+        return {
+          contactIds: new Set(),
+          contacts: [],
+          count: 0,
+          metadata: {
+            executionTime: Date.now() - startTime,
+            criteriaType: 'static'
+          }
+        }
+      }
+
+      const contactIds = await this.contactRepository.getContactIdsByAudienceCriteriaV2(
+        options.organizationId,
+        options.projectId,
+        parsed
+      )
+
+      let contacts: any[] | undefined
+
+      if (options.includeCount || options.pagination) {
+        const { page = 1, limit = 10 } = options.pagination || {}
+        const contactIdsArray = Array.from(contactIds)
+
+        if (contactIdsArray.length > 0) {
+          const paginatedIds = contactIdsArray.slice((page - 1) * limit, page * limit)
+          
+          const { data } = await this.contactRepository.findByIds(
+            options.organizationId,
+            options.projectId,
+            paginatedIds
+          )
+
+          contacts = data || []
+        }
+      }
+
+      return {
+        contactIds,
+        contacts,
+        count: contactIds.size,
+        metadata: {
+          executionTime: Date.now() - startTime,
+          criteriaType: 'static'
+        }
+      }
+    } catch (error) {
+      console.error('❌ Erro ao executar audiência estática:', error)
+      throw error
+    }
+  }
+
+  /**
+   * Executa query e retorna apenas contagem (mais rápido)
+   */
+  async executeCount(
+    criteria: AudienceCriteria,
+    options: Omit<AudienceQueryOptions, 'pagination'>
+  ): Promise<number> {
+    const result = await this.execute(criteria, { ...options, includeCount: true })
+    return result.count
+  }
+}
+

package/src/index.ts

@@ -0,0 +1,6 @@
+export { AudienceModule } from './AudienceModule'
+export { CriteriaParser } from './builders/CriteriaParser'
+export { QueryBuilder } from './builders/QueryBuilder'
+export { StaticAudienceExecutor } from './executors/StaticAudienceExecutor'
+export * from './types'
+

package/src/types/index.ts

@@ -0,0 +1,112 @@
+// Interface flexível para suportar múltiplos formatos de critérios de audience
+export interface AudienceCriteria {
+  type?: string;
+  conditions?: Array<{
+    groupId?: string;
+    operator?: 'AND' | 'OR';
+    conditions?: Array<{
+      field: string;
+      operator: string;
+      value: any;
+      customFieldKey?: string;
+      logicalOperator?: 'AND' | 'OR';
+    }>;
+  }>;
+
+  groups?: Array<{
+    id?: string;
+    operator?: 'AND' | 'OR';
+    rules?: Array<{
+      kind?: string;
+      field?: string;
+      operator?: string;
+      value?: any;
+      eventName?: string;
+      customFieldKey?: string;
+    }>;
+  }>;
+
+  filters?: Array<{
+    id: string;
+    operator: string;
+    conditions: Array<{
+      id: string;
+      field: string;
+      value: string;
+      operator: string;
+      logicalOperator: string;
+      customFieldKey?: string;
+    }>;
+  }>;
+  segmentType?: string;
+
+  config?: {
+    name?: string;
+    type?: string;
+    pageUrl?: string;
+    isActive?: boolean;
+    eventType?: string;
+    pageCount?: string;
+    timeFrame?: string;
+    conditions?: any[];
+    description?: string;
+    referrerUrl?: string;
+    behaviorCriteria?: {
+      engaged?: boolean;
+      purchased?: boolean;
+      visitedPages?: boolean;
+    };
+  };
+
+  live_options?: {
+    include_past_behavior?: boolean;
+    window_days?: number;
+    [key: string]: any;
+  };
+  
+  isActive?: boolean;
+  [key: string]: any;
+}
+
+export interface AudienceQueryOptions {
+  organizationId: string
+  projectId: string
+  pagination?: {
+    page?: number
+    limit?: number
+  }
+  includeCount?: boolean
+}
+
+export interface AudienceExecutionResult {
+  contactIds: Set<string>
+  contacts?: any[]
+  count: number
+  metadata?: {
+    executionTime: number
+    criteriaType: string
+    cacheHit?: boolean
+  }
+}
+
+export interface AudienceBuilderConfig {
+  enableCache?: boolean
+  cacheTimeout?: number
+  enableDebugLogs?: boolean
+}
+
+export interface CreateAudienceData {
+  name: string;
+  description?: string;
+  criteria: AudienceCriteria;
+  organization_id: string;
+  project_id: string;
+  user_id: string;
+}
+
+export interface UpdateAudienceData {
+  name?: string;
+  description?: string;
+  criteria?: AudienceCriteria;
+}
+

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "removeComments": true,
+    "sourceMap": true,
+    "noImplicitAny": false,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+