API: /api/store

Relevant source files

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

• pages/api/store.ts
• tests/api/store.spec.ts
• pages/api/dispatch.ts
• README.md
• package.json
• pages/watch/[id].tsx

The /api/store endpoint is a Next.js API route that serves as the primary mechanism for persisting video message metadata within the Heyme application. Its main responsibility is to receive details about a recorded video message, validate the incoming data, and insert it into the Videos table in the project's MySQL database. This stored information is later retrieved by other services, such as the email dispatch system, to deliver the message to the recipient at the scheduled time.

This endpoint is a critical component of the application's core feature: allowing users to send messages to their future selves. It is wrapped with the withHighlight higher-order function, indicating integration with the Highlight.run service for monitoring and error tracking.

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

Request Handling

The endpoint is handled by the handleStoreVideo function, which processes incoming POST requests. The function's logic follows a clear sequence: validation, database connection, data insertion, and connection termination.

Sources: pages/api/store.ts:7-27

Data Flow

The following diagram illustrates the process flow for a request to the /api/store endpoint.

Sequence Diagram

This diagram shows the sequence of interactions between the client, the API, and the database.

Request Payload

The endpoint expects a JSON object in the request body with specific fields containing the video message's metadata.

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

Sources: pages/api/store.ts:11-17, tests/api/store.spec.ts:5-12

Validation

A basic validation check is performed at the beginning of the handleStoreVideo function. It ensures that all required fields (video_url, email, send_at, send_to, created_at) are present in the request body. If any of these fields are missing or falsy, the API immediately responds with a 400 Bad Request status and a JSON error message.

// pages/api/store.ts:10-17
  if (
    !data.video_url ||
    !data.email ||
    !data.send_at ||
    !data.send_to ||
    !data.created_at
  ) {
    return response.status(400).json({ message: "Invalid data provided." })
  }

This behavior is verified by a unit test in tests/api/store.spec.ts, which sends a request with empty fields and asserts that the response status is 400.

Sources: pages/api/store.ts:10-17, tests/api/store.spec.ts:19-22

Database Interaction

The endpoint relies on a MySQL database to store video metadata. The interaction is managed using the knex query builder.

Sources: README.md, package.json, pages/api/store.ts:20-24

Connection Management

A new database connection is established for each request using the createMysqlConnection() utility function. After the database operation is complete, the connection is explicitly closed with connection.destroy() to release resources.

Sources: pages/api/store.ts:20, pages/api/store.ts:24

Data Insertion

The validated data from the request body is passed to the insertVideo() utility function. This function is responsible for executing the SQL INSERT command to add a new record to the Videos table. The result of this operation is then sent back to the client as the API's JSON response.

The structure of the data being inserted is implicitly defined by the fields checked during validation and is later queried by other parts of the application, such as the video watch page and the email dispatch service.

Sources: pages/api/store.ts:22, pages/api/dispatch.ts:28-30, pages/watch/[id].tsx:64-66