commafeed-podcasts/changelog/plans/plan-basic-episodes.md

Basic Episodes Fetch

Overview

This plan focuses on adding a minimal episodes‑fetch feature that pulls podcast episodes from the CommaFeed backend using environment variables for configuration.

The plan is derived from:

• docs/dev/README.md (API endpoints, authentication)
• src/ structure and existing route system
• Build scripts in bs/ – only linting is required at this stage.

Tasks

1. Environment handling (TODO)
   • Create a small helper (@core/env.ts) that reads .env.ts (or falls back to process.env).
   • Expose constants: COMMAFEED_URL, USERNAME, PASSWORD.
2. API client (TODO)
   • Adds src/api folder to the project structure (update also @src/README.md).
   • Implement a lightweight wrapper around fetch in src/api/index.ts.
   • Build authHeader() that returns the Basic‑Auth header using env vars.
3. Episode service (TODO)
   • Add src/api/episodes.ts with getEpisodes(feedId) and getEpisode(id).
   • Add data types
   • Use /rest/feed/entries?feed_id=${feedId} endpoint.
4. Route integration (TODO)
   • In app-episodes/routes.ts, call the service during enter() to pre‑fetch episodes.
   • Pass fetched data via route context or set a global state (e.g., using Lit Labs signals).
5. Page update (TODO)
   • Update <app-episodes> to reflect loading state(s).
   • Add episode list item component.
   • Update <app-episodes> to render the episode list received from the route context.
6. Testing (TODO)
   • Add unit tests for api/*.ts using project test setup.
   • Add unit test for created component(s)
7. Linting (TODO)
   • Ensure all new files satisfy the lint rule defined in bs/dev/lint.

Expected Output

• Visiting /episodes/ will display a list of episodes fetched from CommaFeed.
• Episodes are identified by their id and displayed with title, publish date, and an audio link if available.
• Authentication uses the env variables; no credentials are hard‑coded in source.

---

Note

: This plan intentionally keeps external dependencies minimal. It can be extended later for pagination, caching, or offline support.