initial commit

_bmad-output/implementation-artifacts/3-1-fiat-currency-provider.md

@@ -0,0 +1,45 @@
+---
+epic: 3
+story: 3.1
+title: "Fiat Currency Provider"
+status: draft
+---
+
+## Epic 3 — Currency & Cryptocurrency
+**Goal:** Real-time and historical currency conversion with 180+ fiat and 50+ crypto.
+
+### Story 3.1: Fiat Currency Provider
+
+As a CalcPad user,
+I want live exchange rates for 180+ fiat currencies that are cached locally for offline use,
+So that currency conversions are accurate and available even without internet.
+
+**Acceptance Criteria:**
+
+**Given** the engine is initialized with network access
+**When** currency rates are requested for the first time
+**Then** it fetches live rates from the configured provider (Open Exchange Rates or exchangerate.host)
+**And** the rates cover at least 180 fiat currencies
+
+**Given** rates have been fetched successfully
+**When** the rates are stored
+**Then** they are cached locally on disk with a timestamp
+**And** the cache includes the provider name and base currency
+
+**Given** cached rates exist and are less than the configured staleness threshold (e.g., 1 hour)
+**When** currency conversion is requested
+**Then** the cached rates are used without a network call
+
+**Given** the device is offline
+**When** a currency conversion is requested
+**Then** the engine uses the most recent cached rates
+**And** the result metadata indicates "offline -- rates from [timestamp]"
+
+**Given** a successful rate fetch
+**When** the result is displayed to the user
+**Then** metadata includes "rates updated [relative time, e.g., '5 minutes ago']"
+
+**Given** the rate provider API is unreachable and no cache exists
+**When** a currency conversion is requested
+**Then** the engine returns a `CalcResult::Error` indicating rates are unavailable
+**And** non-currency calculations on the sheet are unaffected