API Reference: Handlers

This section provides a detailed API reference for the serverless handlers powering the TRMNL Salah Prayer Times Plugin. Each handler corresponds to a specific function within the plugin's lifecycle or data retrieval process.

For a broader understanding of the plugin's architecture and how these handlers fit into the overall system, please refer to the [Technical Architecture] documentation.

installation-handler

• Purpose: Handles the initial OAuth installation flow when a user adds the plugin to their TRMNL account. It exchanges the authorization code provided by TRMNL for an access token and redirects the user back to the TRMNL platform.
• Endpoint: /install
• Request Type: GET
• Schema Reference: Query Parameter Schema (installationQuerySchema)

• Example Request:

installation-success-handler

• Purpose: Receives a webhook from the TRMNL platform after a successful plugin installation. This handler acknowledges the installation and logs user information.
• Endpoint: /installation-success
• Request Type: POST
• Schema Reference: Request Body Schema (installationSuccessBodySchema)

• Example Request:

plugin-management-handler

• Purpose: Renders the HTML interface for users to configure their prayer times settings (city, country, calculation method, etc.) within the TRMNL dashboard.
• Endpoint: /manage
• Request Type: GET
• Schema Reference: Query Parameter Schema (pluginManagementQuerySchema)

• Example Request:

plugin-markup-handler

• Purpose: Generates and serves the dynamic HTML/Liquid markup for the TRMNL e-ink device displays (full, half, quadrant views) based on user settings and current prayer times.
• Endpoint: /plugin-markup
• Request Type: POST
• Schema Reference: Request Body Schema (pluginMarkupBodySchema)

• Example Request:

prayer-times-handler

• Purpose: Provides prayer times data, next prayer information, and Hijri date for a specified location, optionally customized by user settings.
• Endpoint: /prayer-times
• Request Type: GET
• Schema Reference: Query Parameter Schema (prayerTimesQuerySchema)

• Example Request:

save-settings-handler

• Purpose: Receives user-defined settings from the management interface and persists them to the Supabase database.
• Endpoint: /save-settings
• Request Type: GET (as submitted by the form in the management interface)
• Schema Reference: Query Parameter Schema (saveSettingsQuerySchema)

• Example Request:

uninstallation-handler

• Purpose: Receives a webhook from the TRMNL platform when a user uninstalls the plugin. This handler is responsible for deleting all associated user settings from the database.
• Endpoint: /uninstallation
• Request Type: POST
• Schema Reference: Request Body Schema (uninstallationBodySchema)

• Example Request: