prayer-times: data repository, monthly calendar fetch, and cache

Goal

Build prayer-time data repository with remote fetch, normalized models, and offline cache.

Depends On

• Provider decision in #9
• Location/timezone foundation from #10

Scope

• Define PrayerTimesDataSource interface.
• Implement AlAdhanDataSource as primary remote source.
• Keep adapter entry point for fallback provider (EzanVaktiDataSource).
• Fetch monthly calendar for current user location.
• Normalize provider payload into app model.
• Local cache storage + freshness policy.
• Return cached data on offline/failure path.

API/Model Contract

Normalized model per day:

• date
• timezone
• method
• fajr
• sunrise
• dhuhr
• asr
• maghrib
• isha

Required metadata:

• provider (aladhan / fallback)
• fetchedAt

Provider Rules

• Primary fetch: AlAdhan (timingsByCity/calendarByCity) with configured method (13 for Turkey default path).
• Fallback hook: EzanVakti adapter, disabled by default until activated.
• Mapping for fallback when used:
  • Imsak->Fajr, GunesDogus->Sunrise, Ogle->Dhuhr, Ikindi->Asr, Aksam->Maghrib, Yatsi->Isha

Cache Policy (MVP)

• Monthly calendar cached by year-month-location-method key.
• Freshness: refresh on day change or explicit force refresh.
• Offline behavior: return last valid cached month and flag stale state.

Error Handling

• Distinguish:
  • network error
  • parsing/schema error
  • invalid location input
  • provider unavailable
• Expose typed failure for UI/domain layers.

Acceptance Criteria

• Monthly prayer calendar is fetched and normalized.
• Cache is read when offline and when remote fails.
• Freshness/invalidation policy works as defined.
• Repository keeps provider abstraction and supports future fallback.
• Unit tests cover mapping, cache, and error paths.

Task Checklist

• Define repository + datasource interfaces.
• Implement AlAdhan remote datasource.
• Implement local cache datasource.
• Add normalization mappers.
• Add fallback datasource interface scaffold.
• Add unit tests for mapping/cache/errors.

Test Cases

• Valid monthly API response -> normalized 31-day model.
• Cache hit while offline -> data returned with stale marker.
• Invalid payload -> parser failure type returned.
• Method change -> cache key separation and refetch.

References

• #9
• #10
• https://api.aladhan.com/v1/documentation/openapi/prayer-times/yaml
• https://api.aladhan.com/v1/calendarByCity/2026/3?city=Istanbul&country=Turkey&method=13

Start by resolving the provider decision in #9 and the location/timezone foundation in #10, then review the AlAdhan calendarByCity API contract. Define the repository and datasource interfaces, normalization and cache behavior described here, and add unit tests for mapping, cache, invalid payloads, offline fallback, and method-specific keys. Done means the acceptance criteria and listed test cases pass.