API Endpoints Overview

Relevant source files

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

• pages/api/store.ts
• pages/api/dispatch.ts
• tests/api/store.spec.ts
• tests/api/dispatch.spec.ts
• public/mails/email.html
• tests/api/watch.spec.tsx
• README.md

The Heyme application's backend is powered by a set of Next.js API routes. These endpoints are responsible for the core logic of the application: persisting video message details to a database and dispatching emails containing links to these videos at a user-specified future date. The system leverages a MySQL database for data storage and the Zeptomail service for sending transactional emails.

All primary API handlers are wrapped with a withHighlight higher-order function, indicating integration with the Highlight.run service for monitoring and error tracking.

Sources: README.md, pages/api/store.ts:27, pages/api/dispatch.ts:88

POST /api/store

This endpoint is responsible for receiving and persisting the details of a newly recorded video message into the database.

Sources: pages/api/store.ts

Data Flow

The process begins when a client sends a POST request with the video's metadata. The API handler validates the incoming data, establishes a database connection, inserts the new record, and then closes the connection.

Sources: pages/api/store.ts:6-25

Request Body

The endpoint expects a JSON object in the request body with the following fields. A 400 Bad Request response is returned if any of these fields are missing.

Parameter	Type	Description
video_url	string	The URL where the recorded video is stored.
email	string	The recipient's email address.
send_at	string	The date the message should be sent, formatted as YYYY-MM-DD.
send_to	string	Indicates the recipient, e.g., "yourself".
created_at	string	The timestamp when the message was created.

Sources: pages/api/store.ts:10-16, tests/api/store.spec.ts:5-12

Implementation Details

The handleStoreVideo function orchestrates the process. It uses two utility functions: createMysqlConnection to connect to the database and insertVideo to perform the SQL insertion.

// pages/api/store.ts
export async function handleStoreVideo(
  request: NextApiRequest,
  response: NextApiResponse
) {
  const data = request.body

  if (
    !data.video_url ||
    !data.email ||
    !data.send_at ||
    !data.send_to ||
    !data.created_at
  ) {
    return response.status(400).json({ message: "Invalid data provided." })
  }

  // connect to database
  const connection = createMysqlConnection()

  const result = await insertVideo(connection, data)

  await connection.destroy()

  response.json(result)
}

Sources: pages/api/store.ts:6-25

GET /api/dispatch

This endpoint is designed to be triggered periodically (e.g., by a daily cron job). Its purpose is to find all videos scheduled to be sent on the current day, email them to their respective recipients, and mark them as sent.

Sources: pages/api/dispatch.ts

Data Flow

The dispatch process involves querying the database, iterating through the results, generating personalized email content for each, sending the email via Zeptomail, and finally updating the video's status in the database.

Sources: pages/api/dispatch.ts:38-86

Core Functions

Function	Description	Source File
handleDispatchEmails	The main API handler that orchestrates the entire dispatch process.	pages/api/dispatch.ts:38-86
fetchAllVideosForToday	Executes a SQL query to select all records from the Videos table where the send_at column matches the current date.	pages/api/dispatch.ts:24-27
updateVideoToSent	Updates a video record in the database, setting the sent column to 1 to prevent duplicate emails.	pages/api/dispatch.ts:29-33
getEmailContent	Reads an HTML email template and populates it with dynamic data.	pages/api/dispatch.ts:11-22

Email Generation

The email content is generated by the getEmailContent function. It reads a template file and replaces placeholders with dynamic values.

• Template File: public/mails/email.html
• Placeholders:
  • {{REPLACE_WATCH_LINK_HERE}}: The unique URL to watch the video, constructed as ${process.env.SITE_URL}/watch/${video.id}.
  • {{REPLACE_GREETING_HERE}}: A personalized greeting.
  • {{REPLACE_BODY_HERE}}: The main body of the email.
  • {{REPLACE_OUTRO_HERE}}: A closing message.

The email subject and greeting are customized based on the send_to field of the video record, providing a different message if the user sent the video to themselves versus someone else.

Sources: pages/api/dispatch.ts:11-22, pages/api/dispatch.ts:65-81, public/mails/email.html, tests/api/watch.spec.tsx:50-53

External Service Integration

• Zeptomail: Used for sending transactional emails. It is configured using process.env.ZEPTOMAIL_TOKEN.
• MySQL: The application's primary database, managed using the knex query builder.

Sources: pages/api/dispatch.ts:49-51, pages/api/dispatch.ts:24-33, README.md