agents.md

Project: DropDate

Goal: Build a lightweight Cloudflare Worker (TypeScript) that provides a calendar-style API and/or frontend for past and upcoming music album releases using Spotify's API as the data source.

Overview

DropDate (or DropD8) is an app that helps users see music album release dates — both past and upcoming — presented in a calendar-like format.

The project will be a serverless application running on Cloudflare Workers, fetching and caching data from the Spotify Web API. It should expose a JSON API (for front-end or third-party use) and optionally serve a minimal web page or static JSON response.

Tech Stack

Runtime: Cloudflare Workers
Language: TypeScript
Build tool: Wrangler
API source: Spotify Web API
Auth: Spotify client credentials flow
Data caching: Cloudflare KV or Workers Cache API
Output: JSON endpoints and/or minimal HTML frontend
Frontend Using Bootstrap 5 with a modern feel for the theme

Core Features

Album Release Endpoint
- Fetch recent and upcoming albums from Spotify.
- Filter by artist, genre, or release date.
- Paginate results and support query parameters like:
  - ```
  ?from=2024-01-01
```
- ```
?to=2025-12-31
```
  - ```
  ?artist=Taylor%20Swift
```
- ```
?type=album,single
```
Caching
- Cache responses for 6–12 hours using Cloudflare’s native cache.
- Provide a manual cache purge function or endpoint.
API Authentication
- Use Spotify’s Client Credentials flow.
- Store tokens in memory or KV storage.
- Refresh tokens automatically before expiry.
Optional Frontend
- Simple calendar view using plain HTML + JS.
- Fetch data from
```
/api/releases
```
  and render by month.
- Use Bootstrap or Tailwind for layout.
Error Handling
- Graceful error messages for Spotify rate limits or network errors.
- Return standard HTTP status codes and JSON error objects.

Suggested Folder Structure

/src
  ├─ index.ts             # Cloudflare Worker entry
  ├─ api/
  │   └─ releases.ts      # Main API handler
  ├─ utils/
  │   ├─ spotify.ts       # Spotify API wrapper
  │   ├─ cache.ts         # Cache helpers
  │   └─ date.ts          # Date parsing and formatting helpers
  ├─ types/
  │   └─ spotify.ts       # Type definitions for Spotify objects
/public
  └─ index.html           # Optional minimal frontend
wrangler.toml             # Cloudflare config
package.json
tsconfig.json

Example API Contract

GET /api/releases

Parameters:

Name	Type	Description
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`artist`	string	Filter by artist name
`limit`	number	Number of results per page
`offset`	number	Pagination offset

Example response:

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "count": 25,
  "results": [
    {
      "name": "The Tortured Poets Department",
      "artist": "Taylor Swift",
      "release_date": "2025-01-19",
      "spotify_url": "https://open.spotify.com/album/...",
      "cover_url": "https://i.scdn.co/image/..."
    }
  ]
}

Developer Notes for Copilot

Use async/await syntax for Spotify API calls.
Always validate and sanitise query parameters.
Use fetch() within the Worker (no Node.js libraries).
Add helper comments to guide Copilot completion (e.g.
```
// Fetch Spotify access token
```
).
Ensure TypeScript types are well-defined for API responses.
Handle Spotify rate limiting (HTTP 429) with exponential backoff or retry delay.
When writing tests, mock Spotify API calls.
When writing client-side static pages, make sure the custom CSS and JS are saved in separate files for maintainability.
- Use modern JavaScript (ES6+) features for cleaner code.

Example Prompt for Copilot

Write a TypeScript function
fetchReleases(from: string, to: string)
that queries the Spotify Web API for albums released within a date range. The function should use the client credentials flow for authentication, cache results for 12 hours using Cloudflare Cache API, and return a normalised list of releases with
name
,
artist
,
release_date
,
spotify_url
, and
cover_url
.

Future Enhancements

Support multiple data sources (e.g. Apple Music, Bandcamp).
Build a full calendar UI (React or SvelteKit frontend).
Add RSS/Atom feed of new releases.
Provide “Artist Watchlist” feature using KV for user preferences.

Deployment

Configure

wrangler.toml

name = "dropdate"
main = "src/index.ts"
compatibility_date = "2025-10-01"
kv_namespaces = [
  { binding = "DROP_CACHE", id = "xxxxxxxx" }
]

Set Spotify credentials in Wrangler secrets:

wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET

Deploy:
```
wrangler deploy
```

Maintainers

Jack Gilmore — Technical Lead / Creator

agents.md

Runtime: Cloudflare Workers
Language: TypeScript
Build tool: Wrangler
API source: Spotify Web API
Auth: Spotify client credentials flow
Data caching: Cloudflare KV or Workers Cache API
Output: JSON endpoints and/or minimal HTML frontend
Frontend Using Bootstrap 5 with a modern feel for the theme

Core Features

Album Release Endpoint
- Fetch recent and upcoming albums from Spotify.
- Filter by artist, genre, or release date.
- Paginate results and support query parameters like:
  - ```
  ?from=2024-01-01
```
- ```
?to=2025-12-31
```
  - ```
  ?artist=Taylor%20Swift
```
- ```
?type=album,single
```
Caching
- Cache responses for 6–12 hours using Cloudflare’s native cache.
- Provide a manual cache purge function or endpoint.
API Authentication
- Use Spotify’s Client Credentials flow.
- Store tokens in memory or KV storage.
- Refresh tokens automatically before expiry.
Optional Frontend
- Simple calendar view using plain HTML + JS.
- Fetch data from
```
/api/releases
```
  and render by month.
- Use Bootstrap or Tailwind for layout.
Error Handling
- Graceful error messages for Spotify rate limits or network errors.
- Return standard HTTP status codes and JSON error objects.

Suggested Folder Structure

/src
  ├─ index.ts             # Cloudflare Worker entry
  ├─ api/
  │   └─ releases.ts      # Main API handler
  ├─ utils/
  │   ├─ spotify.ts       # Spotify API wrapper
  │   ├─ cache.ts         # Cache helpers
  │   └─ date.ts          # Date parsing and formatting helpers
  ├─ types/
  │   └─ spotify.ts       # Type definitions for Spotify objects
/public
  └─ index.html           # Optional minimal frontend
wrangler.toml             # Cloudflare config
package.json
tsconfig.json

Example API Contract

GET /api/releases

Parameters:

Name	Type	Description
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`artist`	string	Filter by artist name
`limit`	number	Number of results per page
`offset`	number	Pagination offset

Example response:

{
  "from": "2025-01-01",
  "to": "2025-01-31",
  "count": 25,
  "results": [
    {
      "name": "The Tortured Poets Department",
      "artist": "Taylor Swift",
      "release_date": "2025-01-19",
      "spotify_url": "https://open.spotify.com/album/...",
      "cover_url": "https://i.scdn.co/image/..."
    }
  ]
}

Developer Notes for Copilot

Use async/await syntax for Spotify API calls.
Always validate and sanitise query parameters.
Use fetch() within the Worker (no Node.js libraries).
Add helper comments to guide Copilot completion (e.g.
```
// Fetch Spotify access token
```
).
Ensure TypeScript types are well-defined for API responses.
Handle Spotify rate limiting (HTTP 429) with exponential backoff or retry delay.
When writing tests, mock Spotify API calls.
When writing client-side static pages, make sure the custom CSS and JS are saved in separate files for maintainability.
- Use modern JavaScript (ES6+) features for cleaner code.

Example Prompt for Copilot

Write a TypeScript function
fetchReleases(from: string, to: string)
that queries the Spotify Web API for albums released within a date range. The function should use the client credentials flow for authentication, cache results for 12 hours using Cloudflare Cache API, and return a normalised list of releases with
name
,
artist
,
release_date
,
spotify_url
, and
cover_url
.

Future Enhancements

Support multiple data sources (e.g. Apple Music, Bandcamp).
Build a full calendar UI (React or SvelteKit frontend).
Add RSS/Atom feed of new releases.
Provide “Artist Watchlist” feature using KV for user preferences.

Deployment

Configure

wrangler.toml

name = "dropdate"
main = "src/index.ts"
compatibility_date = "2025-10-01"
kv_namespaces = [
  { binding = "DROP_CACHE", id = "xxxxxxxx" }
]

Set Spotify credentials in Wrangler secrets:

wrangler secret put SPOTIFY_CLIENT_ID
wrangler secret put SPOTIFY_CLIENT_SECRET

Deploy:
```
wrangler deploy
```

Maintainers

Jack Gilmore — Technical Lead / Creator

agents.md

agents.md

Project: DropDate

Overview

Tech Stack

Core Features

Suggested Folder Structure

Example API Contract

GET /api/releases

Developer Notes for Copilot

Example Prompt for Copilot

Future Enhancements

Deployment

Maintainers

Related Skills

Markdown Converter

Nano Banana Pro

1password

agents.md

Project: DropDate

Overview

Tech Stack

Core Features

Suggested Folder Structure

Example API Contract

GET /api/releases

Developer Notes for Copilot

Example Prompt for Copilot

Future Enhancements

Deployment

Maintainers