Workflow and Test APIs

Relevant source files - controllers/test.controller.js - controllers/workflow.controller.js - public/test.html - routes/test.routes.js - routes/workflow.routes.js - utils/email-template.js

This section documents the specialized endpoints used for managing asynchronous subscription renewal reminders and manual diagnostic testing of the email notification pipeline. These routes facilitate the integration between the Express.js server and Upstash QStash, as well as providing developer tools for verifying system health.

Subscription Workflow Endpoint

The POST /api/v1/workflows/subscription/reminder endpoint serves as the webhook receiver for Upstash Workflow. It is managed by the Upstash serve() handler, which handles the complex state management of long-running workflows, including retries and execution suspension controllers/workflow.controller.js3-10

Implementation Logic

The workflow is designed to execute over several days, sleeping until specific intervals defined in the REMINDERS constant [7, 5, 2, 1]controllers/workflow.controller.js8

1. Payload Extraction: The handler extracts the subscriptionId from the incoming request controllers/workflow.controller.js11
2. Data Retrieval: It uses context.run to fetch the subscription and populate user details from MongoDB controllers/workflow.controller.js35-39
3. Lifecycle Validation: If the subscription is no longer active or the renewal date has already passed, the workflow terminates immediately controllers/workflow.controller.js15-22

4. Scheduled Reminders: For each interval in the REMINDERS array, the system:

5. Calculates the reminderDatecontrollers/workflow.controller.js25

6. Uses context.sleepUntil to pause execution until that date controllers/workflow.controller.js41-45
7. Triggers the sendReminderEmail utility once the date is reached controllers/workflow.controller.js47-56

Workflow Execution Flow

The following diagram illustrates how the sendReminders controller interacts with the Upstash context and the database.

Workflow Logic and Data Flow

[Flowchart Diagram]

Sources:controllers/workflow.controller.js10-57routes/workflow.routes.js70

---

Test and Diagnostic APIs

The system provides dedicated routes for manual testing that bypass the Upstash scheduler to verify that the SMTP configuration and email templates are functioning correctly.

Manual Test Route

The POST /api/v1/test/send-reminder-email endpoint allows developers to trigger an immediate "1 day before" reminder for any active subscription routes/test.routes.js51

• Security: This route is protected by the authorize middleware, requiring a valid JWT Bearer token routes/test.routes.js51
• Validation: It ensures the subscriptionId exists and the status is active before attempting to send controllers/test.controller.js13-24
• Diagnostics: Before sending, it calls verifyTransporter() to check the connection to the Brevo SMTP server controllers/test.controller.js29-36

Local Test Handler

A secondary helper endpoint, POST /api/v1/workflows/subscription/reminder/test, is defined within the workflow routes. Unlike the standard test route, this is intended for local development where QStash signature verification might be bypassed routes/workflow.routes.js7-11

Test API Interaction

sequenceDiagram
    participant Dev as "Developer / API Tester"
    participant Auth as "authorize middleware"
    participant TestCtrl as "sendTestReminder"
    participant Mail as "sendReminderEmail"
    participant SMTP as "Brevo SMTP"
    Dev->>Auth: POST /test/send-reminder-email (with JWT)
    Auth->>TestCtrl: Proceed
    TestCtrl->>TestCtrl: verifyTransporter()
    TestCtrl->>Mail: Trigger "1 days before reminder"
    Mail->>SMTP: Send HTML Template
    SMTP-->>Dev: Email Received

Sources:routes/test.routes.js7-51controllers/test.controller.js5-49routes/workflow.routes.js11-44

---

API Documentation and UI

The workflow and test endpoints are documented using Swagger JSDoc and can be interacted with via a custom browser-based tester.

Swagger Annotations

Each route includes JSDoc blocks that define the request body schema and potential response codes (200, 400, 401, 404, 500).

• Workflows: Documented under the [Workflows] tag routes/workflow.routes.js49-69
• Test: Documented under the [Test] tag and explicitly marked with security: - bearerAuth: []routes/test.routes.js13-50

Browser-Based Tester (test.html)

The project includes a static public/test.html file that provides a GUI for these endpoints public/test.html1-6 It includes:

• Authentication Panel: Forms for Sign Up and Sign In to obtain the necessary JWT public/test.html94-157
• Test Email Panel: A simple interface to paste a subscriptionId and trigger the send-reminder-email endpoint public/test.html160-175
• Subscription Panel: A form to create new subscriptions, which subsequently triggers the actual Upstash workflow public/test.html178-235

Sources:routes/workflow.routes.js49-106routes/test.routes.js13-51public/test.html86-175