feat(flow): compra aprovada vira evento purchase.approved no catálogo (CRM-316)

[nickoliveira23]

Summary

• Novo evento purchase.approved (categoria purchase) no enum EVENT_NAMES e no catálogo do manifesto: uma compra aprovada numa plataforma de pagamento, capturada como lead pelo webhook de compras do CRM.
• Schema tipado: provider, purchase_id, pipeline_id, pipeline_item_id, source obrigatórios; product, amount (número, unidade maior da moeda, nunca centavos), currency, platform_event, outcome, new_contact, contact_id, funil/etapa opcionais.
• Com isso uma jornada pode disparar em "comprou o produto X" e um segmento pode filtrar "gastou mais que Y". Antes a compra só chegava enterrada em custom_fields do campaign.triggered.
• Nova lane de CI events-contract: roda src/modules/events (catálogo + pipe de validação) quando o módulo muda. Nenhuma lane cobria esse contrato.

Security

• Sem mudança de auth ou de superfície HTTP: o evento entra pelo POST /events/track já existente, com a mesma validação de schema.
• O payload não carrega dados do comprador (nome/e-mail/telefone): só ids da compra e do CRM.

Test plan

• npx jest --runInBand src/modules/events (64/64)
• npx tsc --noEmit
• E2E local: webhook de compra no CRM → purchase.approved no ClickHouse (contact_events) com produto, valor numérico e contato resolvido, nos dois desfechos (created e already_in_pipeline).

Ordem de deploy

evo-flow antes do CRM. Se o CRM emitir primeiro, o pipe responde 400 (evento desconhecido) e o job do CRM retenta até o Dead Set.

Changed Files

• src/modules/events/event-names.enum.ts
• src/modules/events/manifest/event-schema.types.ts
• src/modules/events/manifest/event-catalog.ts
• src/modules/events/manifest/event-catalog.spec.ts
• src/modules/events/pipes/event-schema-validation.pipe.spec.ts
• .github/workflows/events-contract.yml

Related PRs

• evo-flow (deploy primeiro): feat(flow): compra aprovada vira evento purchase.approved no catálogo (CRM-316) #124
• CRM: feat(crm): webhook de compra emite purchase.approved para o evo-flow (CRM-316) evo-ai-crm-community#345
• frontend (vendor/crm): feat(frontend): evento Compra aprovada no manifesto de eventos (CRM-316) evo-ai-frontend-community#369

Linked Issue

• CRM-316

🤖 Generated with Claude Code

https://claude.ai/code/session_01JxYjUwr2vV69kYddiXJHRo

Summary by Sourcery

Expose approved purchases as a first-class, schema-validated event for journeys and segmentation.

New Features:

• Add the purchase.approved track event to the events catalog, including purchase-specific categorization and a typed schema for CRM-captured approved purchases.

Enhancements:

• Extend event categories to include purchases and validate required purchase identifiers and numeric amounts through the existing schema pipeline.

CI:

• Add a dedicated CI workflow to run events catalog and schema contract tests whenever the events module changes.

Tests:

• Add catalog and schema validation coverage for valid and invalid purchase.approved payloads.

[sourcery-ai]

Reviewer's Guide

Introduces the typed purchase.approved track event and purchase category, with catalog and validation tests that enforce the CRM payload contract, plus a path-filtered CI lane to prevent contract drift.

Sequence diagram for approved purchase event ingestion

sequenceDiagram
    participant CRM as CRM purchase webhook
    participant API as POST /events/track
    participant Pipe as EventSchemaValidationPipe
    participant Catalog as Event catalog
    participant Store as contact_events

    CRM->>API: Submit purchase.approved
    API->>Pipe: transform(payload)
    Pipe->>Catalog: getEvent(purchase.approved)
    Catalog-->>Pipe: purchase schema
    alt valid CRM payload
        Pipe-->>API: Accept numeric amount and required IDs
        API->>Store: Persist purchase.approved
    else missing purchase_id or string amount
        Pipe-->>API: BadRequestException
    end

Loading

File-Level Changes

Change	Details	Files
Adds purchase.approved as a first-class, typed track event for approved purchases captured by the CRM.	Registers the event name and purchase category. Defines required purchase/CRM identifiers and source fields. Defines optional product, amount, currency, platform, outcome, contact, and pipeline metadata. Adds catalog coverage for category, DTO type, required fields, and optional field types.	src/modules/events/event-names.enum.ts src/modules/events/manifest/event-schema.types.ts src/modules/events/manifest/event-catalog.ts src/modules/events/manifest/event-catalog.spec.ts
Validates the CRM purchase payload contract, including required identifiers and numeric currency amounts.	Covers acceptance of the representative CRM payload. Rejects missing purchase_id. Rejects string-valued amount to enforce major-unit numeric values.	src/modules/events/pipes/event-schema-validation.pipe.spec.ts
Introduces CI coverage for the events catalog and schema-validation contract.	Runs the events Jest suite on relevant pull requests and pushes. Scopes execution to changes in the events module or workflow.	.github/workflows/events-contract.yml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Sourcery assessment

Needs a human reviewer. This changes runtime schema acceptance and makes purchase.approved available to downstream journey and segment processing. If the catalog or field contract is wrong, events could be rejected or trigger downstream processing with incorrect data; reverting restores the prior validation behavior, but events or automated actions that occurred while it was live cannot be recovered by the revert alone.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook