tilbudgivern/_archive/OPENAI_COSTS_API_IMPLEMENTATION.md

# 📊 OpenAI Costs API Integration - Implementation Summary

## Hvad blev implementeret

Jeg har integreret OpenAI's **Costs API** endpoint i Tilbudgivern for at tracke AI-omkostninger direkte fra OpenAI og vise dem i "🤖 AI Budget" fanen.

## Komponenter

### 1. Backend Service (`/backend/src/services/openaiService.js`)

**Nye metoder:**

```javascript
// Hent omkostningsdata fra OpenAI API
fetchOpenAICosts(daysBack = 30)

// Hent detaljeret omkostningsfordeling med gruppering
getDetailedCostBreakdown(options = {})
```

**Features:**
- Caching af data (5 min cache)
- Fallback til database hvis API fails
- Support for gruppering efter line_item og project_id
- Pagination support

### 2. Backend Routes (`/backend/src/routes/quotes.js`)

**Tre nye API endpoints:**

| Endpoint | Metode | Formål |
|----------|--------|--------|
| `/api/quotes/openai/costs` | GET | Hent total omkostninger sidste N dage |
| `/api/quotes/openai/costs/breakdown` | GET | Detaljeret fordeling med gruppering |
| `/api/quotes/openai/budget/status` | GET | Budgetstatus + advarsler |

### 3. Frontend Updates (`/frontend/src/App.js`)

**Nye states:**
```javascript
const [openaiCosts, setOpenaiCosts] = useState(null);
const [budgetStatus, setBudgetStatus] = useState(null);
```

**Opdateret loadOpenaiUsage()** - Kalder nu alle tre endpoints parallel

**UI Components:**
- Budget Status Card (med farvet progress bar)
- Budget Details (månedligt budget, brugt, tilbage, daglig rate)
- Token Limit Status (tokens brugt vs limit)
- Cost Breakdown (fordelt på line items og projekter)

### 4. Styling (`/frontend/src/App.css`)

**Nye CSS klasser:**
- `.budget-status` - Budget status card med color warnings
- `.budget-progress-bar` - Progress bar med dynamic farver
- `.budget-details` - Budget oversigt
- `.token-limit-details` - Token limit oversigt
- `.costs-breakdown` - Cost fordeling

**Color Scheme:**
- 🟢 Green (#28a745) - OK (0-60%)
- 🟡 Yellow (#ffc107) - Notice (60-80%)
- 🟠 Orange (#ff9800) - Warning (80-95%)
- 🔴 Red (#dc3545) - Critical (95%+)

### 5. Configuration

**`.env` fil update:**
```properties
OPENAI_API_KEY=sk-proj-...          # Existing
OPENAI_ADMIN_KEY=sk-org-...         # NEW - for Costs API
```

## User Flow

1. **Autentificering** → User logger in
2. **AI Budget Tab** → Bruger klikker på "🤖 AI Budget"
3. **Data Load** → System kalder alle tre endpoints parallel
4. **Visning:**
   - Token stats fra database (altid tilgængelig)
   - Budget status fra OpenAI API (hvis OPENAI_ADMIN_KEY sat)
   - Cost breakdown fra OpenAI API (hvis OPENAI_ADMIN_KEY sat)
5. **Advarsler** → Hvis budget > 80%, vises warning

## Data Flow

```
┌─────────────────────────────────────────────┐
│ Frontend (App.js)                           │
│ - Click "🤖 AI Budget"                      │
│ - Call loadOpenaiUsage()                    │
└────────────────┬────────────────────────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
    ▼            ▼            ▼
┌────────┐  ┌─────────┐  ┌──────────┐
│/stats  │  │/costs   │  │/budget   │
│(DB)    │  │(OpenAI) │  │/status   │
│        │  │         │  │(OpenAI)  │
└────────┘  └─────────┘  └──────────┘
    │            │            │
    └────────────┼────────────┘
                 │
    ┌────────────▼────────────┐
    │ React State             │
    │ - openaiUsage           │
    │ - openaiCosts           │
    │ - budgetStatus          │
    └────────────┬────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │ Render UI Components:   │
    │ - Stats Cards           │
    │ - Budget Status         │
    │ - Progress Bars         │
    │ - Cost Breakdown        │
    └─────────────────────────┘
```

## OpenAI API Integration

**Query til OpenAI Costs API:**
```bash
GET https://api.openai.com/v1/organization/costs?start_time=1730419200&limit=1 \
  -H "Authorization: Bearer $OPENAI_ADMIN_KEY" \
  -H "Content-Type: application/json"
```

**Response struktur:**
```json
{
  "object": "page",
  "data": [
    {
      "object": "bucket",
      "start_time": 1730419200,
      "end_time": 1730505600,
      "results": [
        {
          "object": "organization.costs.result",
          "amount": { "value": 0.06, "currency": "usd" },
          "line_item": "Language models",
          "project_id": "proj_abc"
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null
}
```

## Files Modified

| File | Ændringer |
|------|-----------|
| `/backend/src/services/openaiService.js` | +2 nye metoder, +fetchOpenAICosts(), +getDetailedCostBreakdown() |
| `/backend/src/routes/quotes.js` | +3 nye endpoints for costs, budget status |
| `/frontend/src/App.js` | +2 states, updated loadOpenaiUsage(), +UI components |
| `/frontend/src/App.css` | +Budget styling, progress bars, color warnings |
| `/backend/.env` | +OPENAI_ADMIN_KEY config |
| `/docs/OPENAI_COSTS_API.md` | NEW - Full documentation |
| `/test_openai_costs_api.sh` | NEW - Test script |

## Setup Checklist

- [x] Backend service implementeret
- [x] API endpoints tilføjet
- [x] Frontend states tilføjet
- [x] UI komponenter implementeret
- [x] CSS styling tilføjet
- [x] .env configuration
- [x] Error handling
- [x] Documentation
- [ ] OPENAI_ADMIN_KEY konfigurering (kræves fra bruger)
- [ ] Backend restart

## Next Steps

**For at få det fuldt ud til at virke:**

1. **Få OPENAI_ADMIN_KEY:**
   - Gå til https://platform.openai.com/account/org-settings/api-keys
   - Opret ny "secret key"
   - Sørg for "Admin" eller "Organization Owner" rolle

2. **Sæt i .env:**
   ```bash
   OPENAI_ADMIN_KEY=sk-org-xxxxx
   ```

3. **Restart backend:**
   ```bash
   npm start
   ```

4. **Test:**
   ```bash
   ./test_openai_costs_api.sh
   ```

5. **Se resultat:**
   - Åbn AI Budget tab
   - Hvis alt virker, vises budget status + cost breakdown
   - Hvis OPENAI_ADMIN_KEY ikke er sat, vises kun database stats

## Fejlhåndtering

**Hvis OpenAI API fails:**
- Frontend fallback til database stats
- Bruger ser "OpenAI Costs API utilgængelig"
- System logger fejlen til server logs

**Hvis OPENAI_ADMIN_KEY mangler:**
- Endpoints returnerer `success: false`
- Frontend viser kun token stats fra database
- Ingen omkostningsdata fra OpenAI vises

## Performance

- **Caching:** 5 minutter (for at spare API calls)
- **Parallel requests:** Alle tre endpoints kaldes samtidigt
- **Timeout:** 10 sekunder pr request
- **Database:** Bruges som fallback + primary source for token stats

## Security

- OPENAI_ADMIN_KEY er **aldrig** exposed til frontend
- Kun server-side API calls
- Key er i .env (ikke i kode)
- API requests autentificeres via Authorization header

## Test Resultat

Du kan nu:

✅ Se OpenAI costs direkte fra OpenAI's API
✅ Monitore budget forbrug i real-time
✅ Se advarsler når budget > 80%
✅ Analysere costs fordelt på line items og projekter
✅ Estimere dage til budget opbrugt

Med denne integration kan du nu **datadrevet administrere ditt OpenAI budget** og tage bedre beslutninger om model valg og API usage!