/**
 * Worker API implementation
 * 
 * This file implements the server-side API for Skraak using Hono on Cloudflare Workers.
 * It provides authentication middleware and several API endpoints for retrieving data
 * from the Neon PostgreSQL database.
 */

/**
 * Environment variables required for the Worker
 */

  /** Connection string for the Neon PostgreSQL database */

  /** URL of the Kinde identity provider (for JWT verification) */

/**
 * Structure of the JWT token payload
 * Contains standard JWT claims plus any additional custom claims
 */

/**
 * Main Hono application instance with environment bindings
 */

// Public API route - no auth required

/**
 * Public API health check endpoint
 * No authentication required
 */

// Authentication middleware for protected routes

/**
 * Authentication middleware for protected routes
 * 
 * Verifies JWT tokens from the Kinde identity provider using JWKS.
 * On successful verification, adds the JWT payload to the context
 * for use in route handlers.
 * 
 * @param c - Hono context containing request, response, and environment bindings
 * @param next - Next middleware in the chain
 * @returns Response with 401 status on auth failure, or passes to next middleware
 */

// Protected datasets API route

/**
 * Protected API route to fetch datasets
 * Returns datasets owned by the authenticated user
 */

// locations API route

/**
 * Protected API route to fetch locations for a specific dataset
 * Supports pagination with optional page and pageSize parameters
 */

// clusters API route

/**
 * Protected API route to fetch clusters for a specific location
 * Includes associated recording patterns through a LEFT JOIN
 */

// Files API route - paginated by cluster ID

/**
 * Protected API route to fetch audio files for a specific cluster
 * 
 * Supports pagination and filtering by:
 * - Solar night (true/false)
 * - Civil night (true/false)
 * - Species ID (for files with selections labeled with a specific species)
 * 
 * Returns file data with metadata, moth metadata, and associated species
 */

// Species API route - get species and call types for a dataset

/**
 * Protected API route to fetch species and call types for a dataset
 * 
 * Returns a nested structure with species and their associated call types
 * Uses a JOIN approach to efficiently fetch related data in a single query
 */

// Selections API route with flexible filtering by dataset and species

/**
 * Protected API route to fetch files with selections for a specific dataset and species
 * 
 * Supports pagination and filtering by:
 * - Solar night (true/false)
 * - Civil night (true/false)
 * 
 * Returns file data with metadata, moth metadata, and associated species
 */

/**
 * Export the Hono app to be used by the Cloudflare Workers runtime
 */