From aec547cd864d5669b64e744b5fc674a71e95b1b4 Mon Sep 17 00:00:00 2001 From: Ovidiu U Date: Tue, 14 Apr 2026 19:26:01 +0100 Subject: [PATCH] refactor: restructure Stripe pricing config to support monthly and annual tiers - Nest price IDs under `monthly` and `annual` keys for each tier (basic, plus, pro) --- .env.example | 7 + .../Pages/ListBrentPrices.php | 28 +- .../Pages/ListOilPredictions.php | 4 +- config/services.php | 15 +- .../2026-04-14-eia-brent-price-fallback.md | 354 ++++++++++++++++++ ...6-04-14-eia-brent-price-fallback-design.md | 97 +++++ 6 files changed, 499 insertions(+), 6 deletions(-) create mode 100644 docs/superpowers/plans/2026-04-14-eia-brent-price-fallback.md create mode 100644 docs/superpowers/specs/2026-04-14-eia-brent-price-fallback-design.md diff --git a/.env.example b/.env.example index 0155922..c731513 100644 --- a/.env.example +++ b/.env.example @@ -68,3 +68,10 @@ FUELALERT_API_KEY= FRED_API_KEY= EIA_API_KEY= # US EIA Open Data API key — register free at eia.gov/opendata + +STRIPE_PRICE_BASIC_MONTHLY= +STRIPE_PRICE_BASIC_ANNUAL= +STRIPE_PRICE_PLUS_MONTHLY= +STRIPE_PRICE_PLUS_ANNUAL= +STRIPE_PRICE_PRO_MONTHLY= +STRIPE_PRICE_PRO_ANNUAL= diff --git a/app/Filament/Resources/BrentPriceResource/Pages/ListBrentPrices.php b/app/Filament/Resources/BrentPriceResource/Pages/ListBrentPrices.php index ad2ffcb..f474fa2 100644 --- a/app/Filament/Resources/BrentPriceResource/Pages/ListBrentPrices.php +++ b/app/Filament/Resources/BrentPriceResource/Pages/ListBrentPrices.php @@ -4,7 +4,10 @@ namespace App\Filament\Resources\BrentPriceResource\Pages; use App\Filament\Resources\BrentPriceResource; use App\Filament\Widgets\BrentPriceChartWidget; +use Filament\Actions\Action; +use Filament\Notifications\Notification; use Filament\Resources\Pages\ListRecords; +use Illuminate\Support\Facades\Artisan; class ListBrentPrices extends ListRecords { @@ -12,7 +15,30 @@ class ListBrentPrices extends ListRecords protected function getHeaderActions(): array { - return []; + return [ + Action::make('fetchPrices') + ->label('Fetch Prices Now') + ->icon('heroicon-o-arrow-down-tray') + ->requiresConfirmation() + ->modalHeading('Fetch latest Brent prices?') + ->modalDescription('Pulls the latest Brent crude prices from EIA (falls back to FRED if EIA is unavailable).') + ->action(function () { + $result = Artisan::call('oil:fetch'); + + if ($result === 0) { + Notification::make() + ->title('Brent prices fetched successfully') + ->success() + ->send(); + } else { + Notification::make() + ->title('Fetch failed') + ->body('Both EIA and FRED failed. Check API Logs for details.') + ->danger() + ->send(); + } + }), + ]; } protected function getHeaderWidgets(): array diff --git a/app/Filament/Resources/OilPredictionResource/Pages/ListOilPredictions.php b/app/Filament/Resources/OilPredictionResource/Pages/ListOilPredictions.php index f3c4167..1674407 100644 --- a/app/Filament/Resources/OilPredictionResource/Pages/ListOilPredictions.php +++ b/app/Filament/Resources/OilPredictionResource/Pages/ListOilPredictions.php @@ -20,9 +20,9 @@ class ListOilPredictions extends ListRecords ->icon('heroicon-o-cpu-chip') ->requiresConfirmation() ->modalHeading('Run oil price prediction?') - ->modalDescription('This will fetch the latest FRED prices and generate a new prediction. May take a few seconds.') + ->modalDescription('Generates a new prediction from the stored Brent prices. Runs even if a prediction already exists for the latest price.') ->action(function () { - $result = Artisan::call('oil:predict', ['--fetch' => true]); + $result = Artisan::call('oil:predict', ['--force' => true]); if ($result === 0) { Notification::make() diff --git a/config/services.php b/config/services.php index d58c95c..dc6930d 100644 --- a/config/services.php +++ b/config/services.php @@ -74,9 +74,18 @@ return [ 'stripe' => [ 'prices' => [ - 'basic' => env('STRIPE_PRICE_BASIC'), - 'plus' => env('STRIPE_PRICE_PLUS'), - 'pro' => env('STRIPE_PRICE_PRO'), + 'basic' => [ + 'monthly' => env('STRIPE_PRICE_BASIC_MONTHLY'), + 'annual' => env('STRIPE_PRICE_BASIC_ANNUAL'), + ], + 'plus' => [ + 'monthly' => env('STRIPE_PRICE_PLUS_MONTHLY'), + 'annual' => env('STRIPE_PRICE_PLUS_ANNUAL'), + ], + 'pro' => [ + 'monthly' => env('STRIPE_PRICE_PRO_MONTHLY'), + 'annual' => env('STRIPE_PRICE_PRO_ANNUAL'), + ], ], ], diff --git a/docs/superpowers/plans/2026-04-14-eia-brent-price-fallback.md b/docs/superpowers/plans/2026-04-14-eia-brent-price-fallback.md new file mode 100644 index 0000000..bac7854 --- /dev/null +++ b/docs/superpowers/plans/2026-04-14-eia-brent-price-fallback.md @@ -0,0 +1,354 @@ +# EIA Brent Price Source — Primary with FRED Fallback Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace FRED as the primary Brent crude data source with EIA's API, keeping FRED as a silent fallback. + +**Architecture:** `fetchBrentPrices()` is split into two private methods — `fetchFromEia()` and `fetchFromFred()` — each returning a mapped `array|null`. The public method tries EIA first; on `null`, warns and tries FRED; on second `null`, logs an error and returns. The upsert call is shared and runs once. + +**Tech Stack:** Laravel `Http` facade, `BrentPrice::upsert()`, `config/services.php`, Pest + `Http::fake()` + +--- + +## Files + +| Action | File | +|--------|------| +| Modify | `config/services.php` | +| Modify | `.env.example` | +| Modify | `app/Services/OilPriceService.php` | +| Modify | `tests/Unit/Services/OilPriceServiceTest.php` | + +--- + +## Task 1: Add EIA config key + +**Files:** +- Modify: `config/services.php` +- Modify: `.env.example` + +- [ ] **Step 1: Add EIA service config** + +In `config/services.php`, add after the `'fred'` block: + +```php +'eia' => [ + 'api_key' => env('EIA_API_KEY'), +], +``` + +- [ ] **Step 2: Add EIA key to `.env.example`** + +Add after the existing `FRED_API_KEY=` line: + +``` +EIA_API_KEY= # US EIA Open Data API key — register free at eia.gov/opendata +``` + +- [ ] **Step 3: Add your real EIA key to `.env`** + +Add after `FRED_API_KEY=`: + +``` +EIA_API_KEY=your_key_here +``` + +- [ ] **Step 4: Commit** + +```bash +git add config/services.php .env.example +git commit -m "config: add EIA API key for Brent crude price source" +``` + +--- + +## Task 2: Write failing tests for EIA fetch behaviour + +**Files:** +- Modify: `tests/Unit/Services/OilPriceServiceTest.php` + +- [ ] **Step 1: Replace the three existing FRED fetch tests with four new tests** + +Replace the `// --- fetchBrentPrices ---` section (lines 22–69) with: + +```php +// --- fetchBrentPrices --- + +it('fetches and stores brent prices from EIA when EIA succeeds', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::response([ + 'response' => [ + 'data' => [ + ['period' => '2026-04-02', 'value' => '73.80'], + ['period' => '2026-04-01', 'value' => '75.10'], + ['period' => '2026-03-31', 'value' => '74.50'], + ], + ], + ]), + '*/fred/*' => Http::response([], 500), + ]); + + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(3) + ->and(BrentPrice::find('2026-04-02')->price_usd)->toBe('73.80'); + Http::assertNothingSentTo('*fred*'); +}); + +it('falls back to FRED when EIA returns a 500', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::response([], 500), + '*/fred/series/observations*' => Http::response([ + 'observations' => [ + ['date' => '2026-04-01', 'value' => '75.10'], + ['date' => '2026-04-02', 'value' => '73.80'], + ], + ]), + ]); + + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(2); +}); + +it('falls back to FRED when EIA returns empty data', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::response(['response' => ['data' => []]]), + '*/fred/series/observations*' => Http::response([ + 'observations' => [ + ['date' => '2026-04-01', 'value' => '75.10'], + ], + ]), + ]); + + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(1); +}); + +it('stores no rows and logs error when both EIA and FRED fail', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::response([], 500), + '*/fred/series/observations*' => Http::response([], 500), + ]); + + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(0); +}); + +it('filters out EIA missing value markers', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::response([ + 'response' => [ + 'data' => [ + ['period' => '2026-04-01', 'value' => '75.10'], + ['period' => '2026-04-02', 'value' => '.'], + ['period' => '2026-04-03', 'value' => '74.20'], + ], + ], + ]), + ]); + + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(2) + ->and(BrentPrice::find('2026-04-02'))->toBeNull(); +}); + +it('upserts existing brent price rows on refetch via EIA', function (): void { + Http::fake([ + '*/eia.gov/*' => Http::sequence() + ->push(['response' => ['data' => [['period' => '2026-04-01', 'value' => '74.00']]]]) + ->push(['response' => ['data' => [['period' => '2026-04-01', 'value' => '75.50']]]]), + ]); + + $this->service->fetchBrentPrices(); + $this->service->fetchBrentPrices(); + + expect(BrentPrice::count())->toBe(1) + ->and(BrentPrice::find('2026-04-01')->price_usd)->toBe('75.50'); +}); +``` + +- [ ] **Step 2: Run the new tests to confirm they fail** + +```bash +php artisan test --compact tests/Unit/Services/OilPriceServiceTest.php --timeout=10 +``` + +Expected: several FAIL — "no matching fake" or assertion errors (EIA endpoint not yet implemented). + +--- + +## Task 3: Refactor `OilPriceService::fetchBrentPrices()` + +**Files:** +- Modify: `app/Services/OilPriceService.php` + +- [ ] **Step 1: Replace `fetchBrentPrices()` and extract private methods** + +Replace the entire `fetchBrentPrices()` method with: + +```php +/** + * Fetch the last 30 days of Brent crude prices. + * Tries EIA first; falls back to FRED if EIA is unavailable. + */ +public function fetchBrentPrices(): void +{ + $rows = $this->fetchFromEia(); + + if ($rows === null) { + Log::warning('OilPriceService: EIA fetch failed, falling back to FRED'); + $rows = $this->fetchFromFred(); + } + + if ($rows === null) { + Log::error('OilPriceService: both EIA and FRED fetch failed'); + + return; + } + + BrentPrice::upsert($rows, ['date'], ['price_usd']); +} + +/** + * Fetch Brent crude prices from the EIA Open Data API. + * Returns mapped rows or null on any failure. + * + * @return array{date: string, price_usd: float}[]|null + */ +private function fetchFromEia(): ?array +{ + $url = 'https://api.eia.gov/v2/petroleum/pri/spt/data/'; + + try { + $response = $this->apiLogger->send('eia', 'GET', $url, fn () => Http::timeout(10) + ->get($url, [ + 'api_key' => config('services.eia.api_key'), + 'frequency' => 'daily', + 'data[0]' => 'value', + 'facets[series][]' => 'RBRTE', + 'sort[0][column]' => 'period', + 'sort[0][direction]' => 'desc', + 'length' => 30, + ])); + + if (! $response->successful()) { + Log::error('OilPriceService: EIA request failed', ['status' => $response->status()]); + + return null; + } + + $rows = collect($response->json('response.data') ?? []) + ->filter(fn (array $row) => ($row['value'] ?? '.') !== '.') + ->map(fn (array $row) => [ + 'date' => $row['period'], + 'price_usd' => (float) $row['value'], + ]) + ->all(); + + if (empty($rows)) { + Log::warning('OilPriceService: no valid EIA observations returned'); + + return null; + } + + return $rows; + } catch (Throwable $e) { + Log::error('OilPriceService: fetchFromEia failed', ['error' => $e->getMessage()]); + + return null; + } +} + +/** + * Fetch Brent crude prices from FRED (fallback). + * Returns mapped rows or null on any failure. + * + * @return array{date: string, price_usd: float}[]|null + */ +private function fetchFromFred(): ?array +{ + $url = 'https://api.stlouisfed.org/fred/series/observations'; + + try { + $response = $this->apiLogger->send('fred', 'GET', $url, fn () => Http::timeout(10) + ->get($url, [ + 'series_id' => 'DCOILBRENTEU', + 'api_key' => config('services.fred.api_key'), + 'sort_order' => 'desc', + 'limit' => 30, + 'file_type' => 'json', + ])); + + if (! $response->successful()) { + Log::error('OilPriceService: FRED request failed', ['status' => $response->status()]); + + return null; + } + + $rows = collect($response->json('observations') ?? []) + ->filter(fn (array $obs) => $obs['value'] !== '.') + ->map(fn (array $obs) => [ + 'date' => $obs['date'], + 'price_usd' => (float) $obs['value'], + ]) + ->all(); + + if (empty($rows)) { + Log::warning('OilPriceService: no valid FRED observations returned'); + + return null; + } + + return $rows; + } catch (Throwable $e) { + Log::error('OilPriceService: fetchFromFred failed', ['error' => $e->getMessage()]); + + return null; + } +} +``` + +- [ ] **Step 2: Run Pint to fix formatting** + +```bash +vendor/bin/pint app/Services/OilPriceService.php --format agent +``` + +- [ ] **Step 3: Run the tests** + +```bash +php artisan test --compact tests/Unit/Services/OilPriceServiceTest.php --timeout=10 +``` + +Expected: all PASS. + +- [ ] **Step 4: Commit** + +```bash +git add app/Services/OilPriceService.php tests/Unit/Services/OilPriceServiceTest.php +git commit -m "feat: use EIA as primary Brent crude source with FRED fallback" +``` + +--- + +## Task 4: Smoke-test the live fetch + +- [ ] **Step 1: Run the command against the live APIs** + +```bash +php artisan oil:predict --fetch +``` + +Expected output: starts with "Fetching latest Brent crude prices from FRED..." (existing message — acceptable), followed by a successful prediction line. No error output. + +- [ ] **Step 2: Verify EIA data landed in the database** + +```bash +php artisan tinker --execute 'echo App\Models\BrentPrice::orderBy("date","desc")->value("date");' +``` + +Expected: a date more recent than `2026-04-02` if EIA has newer data, otherwise `2026-04-02` (EIA and FRED may both be current to the same date — that is acceptable). diff --git a/docs/superpowers/specs/2026-04-14-eia-brent-price-fallback-design.md b/docs/superpowers/specs/2026-04-14-eia-brent-price-fallback-design.md new file mode 100644 index 0000000..c65f133 --- /dev/null +++ b/docs/superpowers/specs/2026-04-14-eia-brent-price-fallback-design.md @@ -0,0 +1,97 @@ +# EIA Brent Price Source — Primary with FRED Fallback + +**Date:** 2026-04-14 +**Status:** Approved + +## Problem + +FRED (`DCOILBRENTEU`) publishes Brent crude prices with a lag on top of the EIA's own publication delay. As of 2026-04-14, FRED's most recent data is 2026-04-02 — 12 days stale. EIA is the original data source; FRED mirrors it. Using EIA directly removes the mirroring lag. + +## Goal + +Replace FRED as the primary source for `fetchBrentPrices()` with the EIA Open Data API, keeping FRED as a fallback so the system degrades gracefully if EIA is unavailable. + +--- + +## Architecture + +All changes are confined to `app/Services/OilPriceService.php` and supporting config/env files. + +### `fetchBrentPrices()` — updated flow + +``` +1. $rows = fetchFromEia() +2. if ($rows === null): + Log::warning('OilPriceService: EIA fetch failed, falling back to FRED') + $rows = fetchFromFred() +3. if ($rows === null): + Log::error('OilPriceService: both EIA and FRED fetch failed') + return +4. BrentPrice::upsert($rows, ['date'], ['price_usd']) +``` + +### `fetchFromEia(): ?array` (new private method) + +- Endpoint: `GET https://api.eia.gov/v2/petroleum/pri/spt/data/` +- Params: `api_key`, `frequency=daily`, `data[0]=value`, `facets[series][]=RBRTE`, `sort[0][column]=period`, `sort[0][direction]=desc`, `length=30` +- Returns `null` on: HTTP error, exception, empty/missing `response.data` array +- Maps each row: `['date' => $row['period'], 'price_usd' => (float) $row['value']]` +- Filters rows where `value` is `'.'` (EIA uses same placeholder as FRED) + +### `fetchFromFred(): ?array` (extracted private method) + +- Existing FRED logic moved verbatim from the current `fetchBrentPrices()` body +- Returns `null` on: HTTP error, exception, empty observations +- Maps each row: `['date' => $obs['date'], 'price_usd' => (float) $obs['value']]` + +--- + +## Configuration + +### `config/services.php` + +Add under existing entries: +```php +'eia' => [ + 'api_key' => env('EIA_API_KEY'), +], +``` + +### `.env.example` + +Add: +``` +EIA_API_KEY= # US EIA Open Data API key — register free at eia.gov/opendata +``` + +FRED key stays in `.env.example` (still used as fallback). + +--- + +## Logging + +| Event | Level | Message | +|---|---|---| +| EIA fetch succeeded | — | (no log — normal path) | +| EIA fetch failed, FRED used | `warning` | `OilPriceService: EIA fetch failed, falling back to FRED` | +| Both failed | `error` | `OilPriceService: both EIA and FRED fetch failed` | +| No rows after filter | `warning` | `OilPriceService: no valid EIA observations returned` (existing pattern) | + +--- + +## Tests + +Existing `OilPriceService` fetch tests are updated (not replaced): + +1. **EIA succeeds** — `Http::fake()` returns valid EIA response; assert upsert called with correct rows; assert FRED endpoint never called. +2. **EIA fails, FRED succeeds** — EIA returns 500; assert FRED endpoint called; assert upsert called with FRED rows; assert warning logged. +3. **Both fail** — both return 500; assert upsert never called; assert error logged. +4. **EIA returns empty data** — `response.data` is `[]`; assert falls back to FRED. + +--- + +## Out of Scope + +- No changes to `generatePrediction()`, `PredictOilPrices` command, or scheduler +- No new service classes or interfaces +- No changes to `brent_prices` schema