Clashfinder Ingestion Worker & API Implementation

This document details the design and implementation of the Clashfinder JSON API contract, the Worker API ingestion endpoint (POST /api/ingest), and the relational data mapping to conform to the client storage contract.

Deliverables

1. API Contract Definition

Created 14-clashfinder-api-contract.md to define the TypeScript data mappings:

• Maps Clashfinder JSON schemas (event, days, stages, acts) to local D1 relational tables (festivals, stages, bands, sets).
• Normalizes date strings ('YYYY-MM-DD') and time strings ('HH:MM') to Unix epoch millisecond timestamps.

2. Edge Ingestion Endpoint

Implemented the POST /api/ingest route inside index.ts:

• Receives a JSON payload containing the parsed Clashfinder data.
• Relational Seeding:
  • Inserts/updates the festival into the festivals table and retrieves the unique ID.
  • Sequentially populates the stages table, storing mapped integer IDs.
  • Populates the bands table with unique band name records.
  • Inserts individual scheduled acts into the sets table using the mapped festival_id, stage_id, and band_id, resolving time collisions using SQL ON CONFLICT constraints.

3. Edge Data Retrieval Mapping

Updated the GET /api/data route inside index.ts:

• Refactored the band querying logic to perform an SQL JOIN between the sets and bands tables:

  SELECT 
    s.id as id,
    s.stage_id as stage_id,
    b.name as name,
    (s.date || 'T' || s.start_time || ':00') as start_time,
    (s.date || 'T' || s.end_time || ':00') as end_time
  FROM sets s
  JOIN bands b ON s.band_id = b.id;

• Formats dates and times dynamically on the Edge Worker to return epoch millisecond numbers for start_time and end_time, ensuring strict parity with the client PWA's Dexie schema contract.