Complete the Notifications Flow (wire all lifecycle events)

[ManuelJG1999]

Complete the Notifications Flow (wire all lifecycle events)

Depends on: —

Task Description

The notifications module is partially wired. NotificationsService already has methods for created, funded, completed, evidence submitted, milestone approved, dispute opened, and dispute resolved. However, NotificationsListener only subscribes to 3 events (agreement.created, agreement.funded, agreement.completed), so several notification methods are effectively dead code — nothing triggers them end-to-end. This issue closes the gaps so every lifecycle event actually reaches the user.

Background / Current State

Verified against main:

1. Dispute notifications not wired: disputes.service.ts emits DISPUTE_OPENED and DISPUTE_RESOLVED, and the service has notifyDisputeOpened / notifyDisputeResolved, but NotificationsListener has no handlers for them.
2. Evidence & milestone events never emitted: notifyEvidenceSubmitted / notifyMilestoneApproved (and handleEvidenceSubmitted / handleMilestoneApproved) exist, but no code emits evidence_submitted or milestone_approved.
3. Fragmented event constants: AGREEMENT_EVENTS only defines CREATED/FUNDED/COMPLETED, while disputes use separate DISPUTE_OPENED/DISPUTE_RESOLVED constants in another file.

Deliverable

A fully wired event → listener → email flow covering all agreement lifecycle events.

Requirements

• Wire dispute notifications: add @OnEvent handlers for DISPUTE_OPENED and DISPUTE_RESOLVED.
• Emit evidence/milestone events: emit evidence_submitted and milestone_approved from the milestone update path in agreements.service.ts.
• Consolidate event constants: merge into one events constants source used by both agreements and disputes.

Validation System

• Opening a dispute sends the dispute-opened email; resolving sends dispute-resolved.
• Approving a milestone and submitting evidence each trigger their emails.
• Created/funded/completed continue to work (including the webhook-driven funded/completed path in webhooks.service.ts).
• Listener failures are logged but do not crash the request (keep the existing try/catch pattern).

Technical Requirements

• EventEmitterModule is already registered — reuse it; no new infra.
• Extend NotificationsListener with the missing @OnEvent handlers.
• Emit missing events from the correct service methods (not from controllers).
• Update/extend notifications.listener.spec.ts to cover the new handlers.

Additional Notes

Scope is wiring, not new templates — the email templates and service methods already exist. This is why emails "aren't arriving" for disputes/milestones today: the events are never delivered to the service.

Testing (required)

• Unit test: each new @OnEvent handler invokes the correct notification method.
• Integration test: dispute open/resolve, milestone approved, and evidence submitted each produce their email end-to-end.
• Regression test: created/funded/completed (including the webhook path) still fire.
• Resilience test: a listener failure is logged and does not crash the request.

Proof of Completion (required)

• Link the merged PR.
• Paste passing test output (including the extended notifications.listener.spec.ts).
• Attach evidence (logs/screenshots or Resend dashboard) showing dispute and milestone/evidence emails actually sent.
• Confirm (link/diff) the consolidated event-constants source.

[Lspnjr1]

Hi @maintainace

I’m Lspnjr1

Create end-to-end integration tests for the full agreement lifecycle that validate NotificationsService behavior at each stage. The test scope should cover evidence submission, milestone approval, dispute opening, and dispute resolution, and confirm that each event triggers the correct notification flow. For every case, assert the intended recipients, message content, and delivery outcome so any regression in notification handling is detected early.

[Johnpii1]

Hello,

I'd like to work on this issue.

I have experience building event-driven backend systems with NestJS, TypeScript, and EventEmitter-based architectures. I'm comfortable tracing event flows end-to-end, wiring listeners, and ensuring notifications are delivered reliably without impacting request processing.

For this task, I will:

Complete the notification lifecycle by wiring every agreement and dispute event to the existing notification service.
Add the missing @onevent handlers in NotificationsListener for:
DISPUTE_OPENED
DISPUTE_RESOLVED
Emit the missing evidence_submitted and milestone_approved events from the appropriate methods in agreements.service.ts, ensuring events originate from the service layer rather than controllers.
Consolidate agreement and dispute event constants into a single shared source so all producers and consumers use the same definitions.
Preserve the existing error-handling behavior so listener failures are logged without interrupting the request lifecycle.
Keep the implementation focused on wiring only, reusing the existing notification templates and NotificationsService methods.

Before submitting the pull request, I will:

Add unit tests verifying each new @onevent handler invokes the correct notification method.
Add integration tests confirming that:
Opening a dispute sends the dispute-opened notification.
Resolving a dispute sends the dispute-resolved notification.
Evidence submission triggers the corresponding notification.
Milestone approval triggers the corresponding notification.
Run regression tests to ensure the existing created, funded, and completed notification flows—including the webhook-driven path—continue to function correctly.
Verify that listener exceptions are logged and do not crash the originating request.
Provide the required proof of completion, including:
Passing test output.
Evidence that dispute and milestone/evidence emails were successfully sent.
A reference to the consolidated event constants implementation.
Ensure all project checks pass successfully.
Include Closes # in the PR description.

Thank you for considering my application!

[Praiz089017]

I would love to work on this issue within an hour, providing a high quality pr👌

[Glam26]

Hi! I'd like to work on this.

My plan is to:

• Review the existing implementation and identify the accessibility gaps described in the issue.
• Implement the required semantic and ARIA improvements while preserving the current UI and behavior.
• Add or update tests covering the new accessibility behavior and edge cases.
• Run the project's linting, test suite, and build to ensure there are no regressions.
• Open a PR with a summary of the implementation, test results, and any relevant notes.

Looking forward to contributing!

[Gozirimdev]

Hi Maintainer , I have reviewed this and it is something I can handle please can I work on this ?

[salazarsebas]

Hello Thalos Team,

My background

My name is Sebastián, and I'm a founder of Acachete Labs 💻.
I'm confident about the opportunity to contribute to your Stellar-based project and specifically to this issue. ☑

Experience

I'm a full-stack developer with solid experience in blockchain and Web3 technologies, particularly in projects involving smart contracts and decentralized solutions.
I have worked on several projects mainly based on Stellar, and I'm ready to apply that knowledge here.

I am motivated by the opportunity to improve my skills while delivering real value to the project.

Links

You can find my profiles and links here:

GitHub: https://github.com/salazarsebas
LinkedIn: https://www.linkedin.com/in/sebastian-salazar-solano/

Thank you for considering my contribution. I'm excited to work on this issue and create a positive impact. Please let me know if you have any questions or need additional information.

Best regards,
Sebastián

[grantfox-oss]

🦊 GrantFox — @salazarsebas has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #89)
2. Your PR will be reviewed by the Thalos-Infrastructure maintainers

Good luck! Track your progress on GrantFox.

[ManuelJG1999]

🎉 Congratulations @salazarsebas ! This issue has been assigned to you.

Before you start, make sure you understand the requirements. If you have any questions, ask us in our community chat:
https://t.me/ThalosOSSCommunity

Please keep us updated on your progress. If there's no activity or communication within 48 hours, the issue may be reassigned to another contributor.

Happy coding, and thanks for contributing to Thalos! 🐉