# Source Integration

> Source integration

- Skill: `aibot88/source-integration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add aibot88/source-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aibot88/source-integration/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: aibot88 (https://skillmd.com/u/aibot88)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/aibot88/source-integration

---


# Source integration

## Cel

Dostarczyć spójny kontrakt źródła: wejście, normalizacja, błędy, output — plus punkt integracji w `src/vesttracker/sources/` i zsynchronizowane `docs/sources.md`.

## Constraints

- warstwa pobierania nie miesza logiki domenowej z integracją źródła
- znane pułapki, ograniczenia jakości danych i zależności od API zapisuj jawnie w `docs/sources.md` — nie ukrywaj ich w kodzie
- `Faza 1` ogranicza scope do: `xtb`, `gold`, `bond`, `manual`
- nowe źródło = dokumentacja kontraktu w `docs/sources.md` + minimalny test, nie tylko kod
- idempotentność: ponowny import tego samego pliku nie duplikuje transakcji (`source_ref` jako unikalny klucz)

## Non-goals

- nie wprowadza frameworka plugin-system dla "dowolnego źródła"
- nie buduje retry/backoff na zapas jeśli źródło realnie tego nie wymaga
- nie zmienia schematu DB razem z integracją — to osobny change set

## Gotchas

- format CSV XTB nie jest jeszcze znany — czeka na przykładowy plik; nie wymyślaj nazw kolumn przed jego analizą
- cena złota wymaga dwóch API (Yahoo Finance `GC=F` + NBP `USD/PLN`) — oba mogą nie zwrócić danych dla weekendu lub święta; obsłuż fallback gracefully
- obligacje skarbowe nie mają tickera na Catalyst — wycena wyłącznie analityczna, nigdy nie szukaj ceny rynkowej
- `price_cache` ma unikalność `(symbol, date, source)` — przy zapisie używaj `INSERT OR REPLACE`