Scheduled Tasks (Cron Jobs)

Relevant source files

The following files were used as context for generating this wiki page:

• vercel.json
• pages/api/dispatch.ts
• tests/api/dispatch.spec.ts
• public/mails/email.html
• package.json
• README.md

The Heyme application utilizes a scheduled task, implemented as a Vercel Cron Job, to handle the timely dispatch of video message emails. This system is central to the core feature of sending a message to one's future self. The cron job triggers a serverless function daily, which queries the database for messages scheduled for that day, formats a personalized email, sends it using the Zeptomail service, and marks the message as sent.

This process ensures that users receive their scheduled video messages on the exact day they intended, fulfilling the application's promise of connecting them with their past selves.

Architecture and Flow

The scheduled task is defined in the Vercel deployment configuration and points to a dedicated API endpoint responsible for the entire dispatch logic.

Cron Job Configuration

The scheduling is configured in vercel.json. A single cron job is defined to run at a specific time every day.

{
  "crons": [
    {
      "path": "/api/dispatch",
      "schedule": "0 12 * * *"
    }
  ]
}

Sources: vercel.json:1-7

This configuration instructs Vercel to send a GET request to the /api/dispatch endpoint at 12:00 PM (noon) UTC every day.

Execution Flow Diagram

This diagram illustrates the step-by-step process initiated by the Vercel cron job.

Sequence of Interactions

The following sequence diagram shows the interactions between the different services involved in the dispatch process.

Core Components

The dispatch logic is encapsulated within the pages/api/dispatch.ts file, which contains several key functions.

API Handler: handleDispatchEmails

This is the main function executed by the serverless environment when the /api/dispatch endpoint is hit.

Responsibilities:

1. Establishes a connection to the MySQL database.
2. Fetches all video records scheduled to be sent on the current day.
3. If no videos are found, it closes the connection and exits.
4. Initializes the Zeptomail client for sending transactional emails.
5. Iterates through each video record.
6. For each video, it constructs and sends a personalized email.
7. Updates the video's status to sent in the database.
8. Destroys the database connection upon completion.

Sources: pages/api/dispatch.ts:36-93

Database Interaction

Two primary functions handle communication with the MySQL database using the knex query builder.

Function	Description
fetchAllVideosForToday	Executes SELECT * FROM Videos WHERE send_at = [current_date] to retrieve all relevant video records.
updateVideoToSent	Executes UPDATE Videos SET sent = 1 WHERE id = [video_id] to mark a video as dispatched.

Sources: pages/api/dispatch.ts:25-34

Email Content Generation: getEmailContent

This function is responsible for populating the HTML email template with dynamic data for each recipient.

1. It reads the base template from public/mails/email.html.
2. It replaces placeholders in the template with video-specific information.

The following placeholders are used in the email.html template:

Placeholder	Replaced With
{{REPLACE_WATCH_LINK_HERE}}	The unique URL to watch the video, e.g., https://heyme.io/watch/{video.id}.
{{REPLACE_GREETING_HERE}}	A dynamic greeting. It differs based on whether the user sent the message to themselves or someone else. For example: Do you still remember sending yourself a message on {creation_date}?
{{REPLACE_BODY_HERE}}	A static body text: This message was sent using our future message service called <a href="https://heyme.io" target="_blank">heyme</a>.
{{REPLACE_OUTRO_HERE}}	A static closing: Thank you for using our service.

Sources: pages/api/dispatch.ts:10-23, public/mails/email.html

Testing

A unit test exists to verify the functionality of the getEmailContent function. The test ensures that all placeholders are correctly replaced with the provided data, confirming the email body is generated as expected before being sent.

Sources: tests/api/dispatch.spec.ts:4-23

Dependencies

The scheduled task functionality relies on several key libraries defined in package.json.

Package	Version	Usage
knex	^2.4.2	SQL query builder for interacting with the MySQL database.
mysql	^2.18.1	MySQL database driver.
dayjs	^1.11.7	Used for date formatting, specifically to get the current date in YYYY-MM-DD format for the database query.
zeptomail	^3.0.3	The client library for the Zeptomail transactional email service.

Sources: package.json, pages/api/dispatch.ts

Summary

The cron job system is a critical, automated component of the Heyme application. By leveraging Vercel's scheduling capabilities, a serverless function, a MySQL database, and the Zeptomail service, it reliably delivers video messages at the user-specified future date. The implementation is self-contained within the /api/dispatch endpoint, making it a clear and maintainable piece of the application's architecture.

Sources: README.md, pages/api/dispatch.ts, vercel.json