pi-finance-tr 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Tüm önemli değişiklikler bu dosyada belgelenir.
+Format [Keep a Changelog](https://keepachangelog.com/tr/1.1.0/) standardını takip eder.
+
+## [0.1.0] — 2026-05-14
+
+### Eklendi
+- `finance_tr_kripto_fiyat` aracı: CoinGecko üzerinden kripto para fiyatları (TRY + USD, 24 saatlik değişim)
+  - 25 popüler coin için BTC/ETH/SOL/BNB/XRP/DOGE/ADA/AVAX ve diğerleri
+  - 60 saniyelik TTL önbellekleme
+  - `UnknownCoinError`, `RateLimitError` hata sınıfları
+- GitHub Actions CI: `ci.yml` — push/PR tetikleyici, Node 18/20/22 matris
+- GitHub Actions entegrasyon testleri: `integration.yml` — haftalık Pazartesi + `workflow_dispatch`
+- TCMB XML fixture'ı güncellendi: USD, AUD, EUR, GBP, JPY, CHF (2025-11-03)
+- Retry mekanizması birim testi (2 ağ başarısızlığı + 1 başarı)
+- Cache hit birim testi (aynı sorgu, tek fetch)
+
+### Değişti
+- `finance_tr_doviz_kur` çıktısı: her yanıtın sonuna TCMB sorumluluk reddi eklendi
+- Hata mesajları kullanıcı dostu Türkçe'ye dönüştürüldü:
+  - `TatilGunuError`: "TCMB bu tarihte bülten yayımlamamış (tatil/hafta sonu olabilir)…"
+  - `UnknownCurrencyError`: desteklenen kurlar listeleniyor
+  - Timeout/AbortError: bağlantı önerisi
+- ESLint kuralı: `_` önekli kullanılmayan parametreler artık hata üretmiyor
+- Paket mimarisi netleştirildi: **Yol A** (TypeScript kaynak olarak yayın) — pi runtime `.ts` dosyalarını doğrudan çalıştırır, build adımı yoktur
+
+### Döküman
+- README: CI/lisans/node badge'leri
+- README: "Niçin pi-finance-tr?" konumlandırma paragrafı
+- README: Kripto aracı kullanım örnekleri ve parametre tablosu
+- README: Roadmap tablosu (v0.1.0 → v1.0.0)
+- README: Katkı bölümü
+- CONTRIBUTING.md: issue şablonu, geliştirme ortamı, PR akışı, mimari notu
+
+## [0.0.1-alpha.0] — 2026-05-14
+
+### Eklendi
+- `finance_tr_doviz_kur` aracı: TCMB üzerinden güncel ve geçmiş döviz kurları (USD, EUR, GBP vb.)
+- TTL'li in-memory önbellekleme (varsayılan 1 saat)
+- Timeout + otomatik yeniden deneme ile HTTP istemcisi
+- TCMB XML ayrıştırıcı (`xml2js`)
+- `borsa`, `emtia`, `kripto`, `kap` modülleri için iskelet yapı (v0.1.0'da implemente edilecek)
+- Birim testleri (config, cache, kur servisi) ve gerçek TCMB entegrasyon testi

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ulusoyomer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# pi-finance-tr
+
+[![CI](https://github.com/burcineren/pi-finance-tr/actions/workflows/ci.yml/badge.svg)](https://github.com/burcineren/pi-finance-tr/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
+
+Türk finans verilerini pi için MCP araçları olarak sunan paket.
+
+---
+
+> ## ⚠️ Önemli Uyarı
+>
+> **Bu paket yatırım tavsiyesi değildir ve SPK lisansı yoktur. Sunulan veriler yalnızca bilgilendirme amaçlıdır. Finansal kararlarınızı lisanslı yatırım danışmanlarınıza danışarak alınız. Veri gecikmeli veya hatalı olabilir; her türlü sorumluluk kullanıcıya aittir.**
+
+---
+
+## Niçin pi-finance-tr?
+
+Türkçe pi kullanıcısı için sade, terminal-dostu günlük finans araçları sunar: TCMB döviz kurları, kripto fiyatları, kira artış hesabı, kredi taksiti gibi pratik ihtiyaçlar. `borsa-mcp` gibi profesyonel teknik analiz odaklı bağımsız MCP sunucularına alternatif değildir; pi ekosistemine native entegre olur ve tek komutla kurulur.
+
+## Araçlar
+
+### Döviz (kur modülü — tam)
+| Araç | Açıklama |
+|------|----------|
+| `finance_tr_doviz_kur` | TCMB resmi döviz kuru (güncel veya geçmiş tarih) |
+
+### Kripto (v0.1.0 — tam)
+| Araç | Açıklama |
+|------|----------|
+| `finance_tr_kripto_fiyat` | CoinGecko üzerinden kripto fiyatları (TRY + USD, 24s değişim) |
+
+### Borsa (v0.2.0'da)
+| Araç | Açıklama |
+|------|----------|
+| `finance_tr_borsa_hisse` | BIST hisse senedi fiyatı |
+
+### Emtia (v0.3.0'da)
+| Araç | Açıklama |
+|------|----------|
+| `finance_tr_emtia_fiyat` | Altın, gümüş vb. emtia fiyatları |
+
+### KAP (v0.3.0'da)
+| Araç | Açıklama |
+|------|----------|
+| `finance_tr_kap_bildirim` | KAP bildirimleri ve özel durum açıklamaları |
+
+## Gereksinimler
+
+- [pi](https://github.com/badlogic/pi-mono)
+- Node.js >= 18
+
+## Kurulum
+
+```bash
+pi install npm:pi-finance-tr
+```
+
+Yerel kaynak koddan kurulum:
+
+```bash
+pi install /path/to/pi-finance-tr
+```
+
+## Yapılandırma
+
+`examples.env` dosyasını başlangıç noktası olarak kullanabilirsiniz.
+
+### Ortam Değişkenleri
+
+| Değişken | Açıklama | Varsayılan |
+|----------|----------|------------|
+| `FINANCE_TR_ENABLED_MODULES` | Açık modüller (virgülle ayrılmış) | tümü |
+| `FINANCE_TR_EVDS_KEY` | TCMB EVDS API anahtarı (borsa/emtia için) | — |
+| `FINANCE_TR_CACHE_TTL_OVERRIDE` | Önbellek süresi (saniye) | `3600` |
+| `FINANCE_TR_USER_AGENT` | HTTP User-Agent başlığı | `pi-finance-tr/0.1.0` |
+| `FINANCE_TR_TIMEOUT_MS` | HTTP istek zaman aşımı (ms) | `15000` |
+
+### Örnek
+
+```bash
+# Yalnızca kur ve kripto modüllerini aç
+export FINANCE_TR_ENABLED_MODULES=kur,kripto
+
+# Önbelleği 30 dakikaya düşür
+export FINANCE_TR_CACHE_TTL_OVERRIDE=1800
+```
+
+## Modül eşleşmesi
+
+| Modül | Araç(lar) |
+|-------|-----------|
+| `kur` | `finance_tr_doviz_kur` |
+| `kripto` | `finance_tr_kripto_fiyat` |
+| `borsa` | `finance_tr_borsa_hisse` |
+| `emtia` | `finance_tr_emtia_fiyat` |
+| `kap` | `finance_tr_kap_bildirim` |
+
+## Kullanım Örnekleri
+
+### Döviz kuru sorgulama
+
+- "Dolar bugün kaç TL?"
+- "Euro alış ve satış kurları nedir?"
+- "Geçen ay 15'inde pound kaçtı?"
+- "2025-11-03 tarihinde USD satış kuru ne idi?"
+- "Japon yeni kuru bugün TCMB'ye göre kaç?"
+
+### Kripto fiyat sorgulama
+
+- "Bitcoin kaç TL?"
+- "ETH son 24 saatte ne kadar değişti?"
+- "SOL fiyatı dolar ve TL cinsinden nedir?"
+
+## Araç Parametreleri
+
+### `finance_tr_doviz_kur`
+| Parametre | Tip | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `currency` | `string` | evet | Döviz kodu (USD, EUR, GBP, JPY, CHF vb.) |
+| `date` | `string` | hayır | Tarih (YYYY-MM-DD; belirtilmezse bugünkü kur) |
+
+**Not:** TCMB tatil ve hafta sonlarında bülten yayımlamaz. Bu günlere ait kur sorgusu Türkçe hata mesajı döner.
+
+### `finance_tr_kripto_fiyat`
+| Parametre | Tip | Zorunlu | Açıklama |
+|-----------|-----|---------|----------|
+| `coin` | `string` | evet | Kripto para kodu (BTC, ETH, SOL vb.) veya CoinGecko ID |
+| `currencies` | `string[]` | hayır | Karşılaştırma para birimleri (varsayılan: `["try", "usd"]`) |
+
+## Roadmap
+
+| Versiyon | İçerik |
+|----------|--------|
+| **v0.1.0** (mevcut) | Kripto modülü — CoinGecko, TRY+USD, 24s değişim |
+| **v0.2.0** | Borsa modülü — BigPara + Investing fallback |
+| **v0.3.0** | KAP scraping + altın/gümüş emtia |
+| **v1.0.0** | Kişisel finans hesaplayıcıları (kira artışı, kredi taksit, BES) |
+
+## Sorun Giderme
+
+### Modül çalışmıyor
+
+`FINANCE_TR_ENABLED_MODULES` değişkenini kontrol edin. Değer belirtilmezse tüm modüller açık olur.
+
+### Zaman aşımı hatası
+
+```bash
+export FINANCE_TR_TIMEOUT_MS=30000
+```
+
+### TCMB'den veri gelmiyor
+
+- İş günü olduğundan ve TCMB'nin bülteni yayımladığından emin olun (genellikle 15:30'dan sonra).
+- Tarih formatının `YYYY-MM-DD` olduğunu kontrol edin.
+- Döviz kodunun TCMB'nin kabul ettiği kodlardan biri olduğunu doğrulayın (USD, EUR, GBP, JPY, CHF vb.).
+
+## Katkı
+
+Issue açmak için [GitHub Issues](https://github.com/burcineren/pi-finance-tr/issues) sayfasını kullanın. Lütfen şunları belirtin:
+- Hangi modül/araçla ilgili
+- Beklenen ve gerçekleşen davranış
+- Node.js versiyonu
+
+### PR akışı
+
+1. Repo'yu fork edin
+2. `git checkout -b feat/açıklayıcı-isim`
+3. Değişikliklerinizi yapın
+4. `npm run typecheck && npm run lint && npm test` geçtiğinden emin olun
+5. PR açın — ADIM'lara karşılık gelen commit'ler tercih edilir
+
+Detaylar için [CONTRIBUTING.md](CONTRIBUTING.md) dosyasına bakın.
+
+## Lisans
+
+MIT

package/examples.env

@@ -0,0 +1,25 @@
+# pi-finance-tr yapılandırma örneği
+# Bu dosyayı kopyalayıp .env olarak kaydedin: cp examples.env .env
+
+# Etkinleştirilecek modüller (virgülle ayırın)
+# Boş bırakılırsa tüm modüller açık olur.
+# Geçerli değerler: kur, borsa, emtia, kripto, kap
+# FINANCE_TR_ENABLED_MODULES=kur,borsa,emtia,kripto,kap
+
+# TCMB EVDS API anahtarı
+# Borsa ve emtia modülleri için gerekecek (şu an stub, v0.1.0'da aktif olacak)
+# Ücretsiz hesap: https://evds2.tcmb.gov.tr
+# FINANCE_TR_EVDS_KEY=your_evds_key_here
+
+# Önbellek TTL (saniye)
+# Varsayılan: 3600 (1 saat)
+# Kur verilerinin ne kadar süre önbellekte tutulacağını belirler.
+# FINANCE_TR_CACHE_TTL_OVERRIDE=3600
+
+# User-Agent başlığı
+# Varsayılan: pi-finance-tr/0.0.1-alpha.0
+# FINANCE_TR_USER_AGENT=pi-finance-tr/0.0.1-alpha.0
+
+# HTTP istek zaman aşımı (milisaniye)
+# Varsayılan: 15000 (15 saniye)
+# FINANCE_TR_TIMEOUT_MS=15000

package/extensions/pi-finance-tr.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { loadConfig } from '../src/config.ts';
+import type { EnvSource } from '../src/types.ts';
+import { registerKurModule } from '../src/modules/kur/index.ts';
+import { registerBorsaModule } from '../src/modules/borsa/index.ts';
+import { registerEmtiaModule } from '../src/modules/emtia/index.ts';
+import { registerKriptoModule } from '../src/modules/kripto/index.ts';
+import { registerKapModule } from '../src/modules/kap/index.ts';
+import { registerAntigravityModule } from '../src/modules/antigravity/index.ts';
+
+interface ExtensionOptions {
+  env?: EnvSource;
+}
+
+export default function financeTrExtension(pi: ExtensionAPI, options?: ExtensionOptions): void {
+  const config = loadConfig(options?.env);
+
+  if (config.enabledModules.has('kur')) {
+    registerKurModule(pi, config);
+  }
+  if (config.enabledModules.has('borsa')) {
+    registerBorsaModule(pi, config);
+  }
+  if (config.enabledModules.has('emtia')) {
+    registerEmtiaModule(pi, config);
+  }
+  if (config.enabledModules.has('kripto')) {
+    registerKriptoModule(pi, config);
+  }
+  if (config.enabledModules.has('kap')) {
+    registerKapModule(pi, config);
+  }
+  if (config.enabledModules.has('antigravity')) {
+    registerAntigravityModule(pi, config);
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-finance-tr",
+  "version": "0.1.0",
+  "description": "Türk finans verilerini (TCMB, BIST, KAP, altın, kripto) pi için MCP araçları olarak sunan paket.",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "mcp",
+    "finance",
+    "turkey",
+    "tcmb",
+    "bist",
+    "kap",
+    "doviz",
+    "altin"
+  ],
+  "license": "MIT",
+  "author": "burcineren",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/burcineren/pi-finance-tr.git"
+  },
+  "homepage": "https://github.com/burcineren/pi-finance-tr#readme",
+  "bugs": {
+    "url": "https://github.com/burcineren/pi-finance-tr/issues"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "examples.env"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:integration": "RUN_INTEGRATION=1 vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src extensions test"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "dependencies": {
+    "xml2js": "^0.6.2"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "^0.34.41",
+    "@types/node": "^22.0.0",
+    "@types/xml2js": "^0.4.14",
+    "eslint": "^9.0.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^3.2.4"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,31 @@
+export class TtlCache<V> {
+  private readonly store = new Map<string, { value: V; expiresAt: number }>();
+  private readonly defaultTtlMs: number;
+
+  constructor(defaultTtlSeconds: number) {
+    this.defaultTtlMs = defaultTtlSeconds * 1_000;
+  }
+
+  get(key: string): V | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  set(key: string, value: V, ttlSeconds?: number): void {
+    const ttlMs = ttlSeconds !== undefined ? ttlSeconds * 1_000 : this.defaultTtlMs;
+    this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
+  }
+
+  has(key: string): boolean {
+    return this.get(key) !== undefined;
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}

package/src/config.ts

@@ -0,0 +1,56 @@
+import { DEFAULT_TIMEOUT_MS, DEFAULT_USER_AGENT, ENABLED_MODULES } from './constants.ts';
+import type { EnabledModule, EnvSource } from './types.ts';
+
+export interface FinanceTrConfig {
+  enabledModules: Set<EnabledModule>;
+  evdsKey?: string;
+  cacheTtlOverrideSeconds?: number;
+  userAgent: string;
+  timeoutMs: number;
+}
+
+function parseEnabledModules(value?: string): Set<EnabledModule> {
+  if (!value?.trim()) return new Set(ENABLED_MODULES);
+
+  const valid = new Set<string>(ENABLED_MODULES);
+  const parts = value
+    .split(',')
+    .map((p) => p.trim().toLowerCase())
+    .filter(Boolean);
+
+  for (const m of parts) {
+    if (!valid.has(m)) {
+      throw new Error(`Bilinmeyen modül: ${m}. Geçerli değerler: ${ENABLED_MODULES.join(', ')}`);
+    }
+  }
+
+  return new Set(parts as EnabledModule[]);
+}
+
+function parseCacheTtl(value?: string): number | undefined {
+  if (!value?.trim()) return undefined;
+  const parsed = parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error('FINANCE_TR_CACHE_TTL_OVERRIDE pozitif tam sayı olmalıdır');
+  }
+  return parsed;
+}
+
+function parseTimeoutMs(value?: string): number {
+  if (!value?.trim()) return DEFAULT_TIMEOUT_MS;
+  const parsed = parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error('FINANCE_TR_TIMEOUT_MS pozitif tam sayı olmalıdır');
+  }
+  return parsed;
+}
+
+export function loadConfig(env: EnvSource = process.env): FinanceTrConfig {
+  return {
+    enabledModules: parseEnabledModules(env.FINANCE_TR_ENABLED_MODULES),
+    evdsKey: env.FINANCE_TR_EVDS_KEY?.trim() || undefined,
+    cacheTtlOverrideSeconds: parseCacheTtl(env.FINANCE_TR_CACHE_TTL_OVERRIDE),
+    userAgent: env.FINANCE_TR_USER_AGENT?.trim() || DEFAULT_USER_AGENT,
+    timeoutMs: parseTimeoutMs(env.FINANCE_TR_TIMEOUT_MS),
+  };
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+export const ENABLED_MODULES = ['kur', 'borsa', 'emtia', 'kripto', 'kap', 'antigravity'] as const;
+
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const DEFAULT_USER_AGENT = 'pi-finance-tr/0.1.0';
+
+export const KUR_CACHE_TTL_SECONDS = 3_600;
+export const TCMB_BASE_URL = 'https://www.tcmb.gov.tr/kurlar';

package/src/modules/antigravity/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createAntigravityTool } from './tools.ts';
+
+export function registerAntigravityModule(pi: ExtensionAPI, _config: FinanceTrConfig): void {
+  pi.registerTool(createAntigravityTool());
+}

package/src/modules/antigravity/tools.ts

@@ -0,0 +1,48 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+
+const QUOTES = [
+  'Borsa yerçekimine meydan okur — ne yazık ki yalnızca düşerken.',
+  'Altın ağırdır, portföyünüz ise hafifler.',
+  '"Piyasalar mantıksız kalabilir, siz iflas olana kadar." — Keynes',
+  'Kripto: yerçekimi yoktur, taban da.',
+  'TCMB döviz kurları antigravity değil, ama bazen öyle hissettiriyor.',
+  'https://xkcd.com/353/',
+];
+
+export function createAntigravityTool() {
+  return {
+    name: 'finance_tr_antigravity',
+    label: 'Antigravity',
+    description: 'Finansal yerçekimine meydan okur. import antigravity',
+    parameters: Type.Object({
+      wish: Type.Optional(Type.String({ description: 'Bir dilek tut' })),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { wish?: string },
+      _signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      if (onUpdate) {
+        onUpdate({
+          content: [{ type: 'text' as const, text: '🚀 Yerçekimi hesaplanıyor...' }],
+          details: undefined,
+        });
+      }
+
+      const quote = QUOTES[Math.floor(Math.random() * QUOTES.length)];
+      const wish = params.wish ? `\n\nDileğin: "${params.wish}" — piyasa duydu, not aldı.` : '';
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `🪂 Antigravity aktif.\n\n${quote}${wish}`,
+          },
+        ],
+        details: { quote, xkcd: 'https://xkcd.com/353/' },
+      };
+    },
+  };
+}

package/src/modules/borsa/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createBorsaTool } from './tools.ts';
+
+export function registerBorsaModule(pi: ExtensionAPI, _config: FinanceTrConfig): void {
+  pi.registerTool(createBorsaTool());
+}

package/src/modules/borsa/service.ts

@@ -0,0 +1,7 @@
+export function createBorsaService(_config: unknown) {
+  return {
+    fetchHisse(_symbol: string): never {
+      throw new Error('Not yet implemented — see ROADMAP.md');
+    },
+  };
+}

package/src/modules/borsa/tools.ts

@@ -0,0 +1,29 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+
+export function createBorsaTool() {
+  return {
+    name: 'finance_tr_borsa_hisse',
+    label: 'BIST Hisse Fiyatı',
+    description: 'BIST hisse senedi fiyatı sorgular. (Yakında — v0.1.0)',
+    parameters: Type.Object({
+      symbol: Type.String({ description: 'Hisse kodu (ör. THYAO, GARAN, AKBNK)' }),
+    }),
+    async execute(
+      _toolCallId: string,
+      _params: { symbol: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: 'Borsa modülü henüz tamamlanmadı. v0.1.0 sürümünde eklenecek.',
+          },
+        ],
+        details: {},
+      };
+    },
+  };
+}

package/src/modules/emtia/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createEmtiaTool } from './tools.ts';
+
+export function registerEmtiaModule(pi: ExtensionAPI, _config: FinanceTrConfig): void {
+  pi.registerTool(createEmtiaTool());
+}

package/src/modules/emtia/service.ts

@@ -0,0 +1,7 @@
+export function createEmtiaService(_config: unknown) {
+  return {
+    fetchEmtia(_symbol: string): never {
+      throw new Error('Not yet implemented — see ROADMAP.md');
+    },
+  };
+}

package/src/modules/emtia/tools.ts

@@ -0,0 +1,29 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+
+export function createEmtiaTool() {
+  return {
+    name: 'finance_tr_emtia_fiyat',
+    label: 'Emtia Fiyatı',
+    description: 'Altın, gümüş ve diğer emtia fiyatlarını sorgular. (Yakında — v0.1.0)',
+    parameters: Type.Object({
+      symbol: Type.String({ description: 'Emtia kodu (ör. ALTIN, GUMUS, PLATINUM)' }),
+    }),
+    async execute(
+      _toolCallId: string,
+      _params: { symbol: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: 'Emtia modülü henüz tamamlanmadı. v0.1.0 sürümünde eklenecek.',
+          },
+        ],
+        details: {},
+      };
+    },
+  };
+}

package/src/modules/kap/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createKapTool } from './tools.ts';
+
+export function registerKapModule(pi: ExtensionAPI, _config: FinanceTrConfig): void {
+  pi.registerTool(createKapTool());
+}

package/src/modules/kap/service.ts

@@ -0,0 +1,7 @@
+export function createKapService(_config: unknown) {
+  return {
+    fetchBildirim(_query: string): never {
+      throw new Error('Not yet implemented — see ROADMAP.md');
+    },
+  };
+}

package/src/modules/kap/tools.ts

@@ -0,0 +1,33 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+
+export function createKapTool() {
+  return {
+    name: 'finance_tr_kap_bildirim',
+    label: 'KAP Bildirimi',
+    description:
+      'Kamuyu Aydınlatma Platformu (KAP) bildirimleri ve özel durum açıklamaları. (Yakında — v0.1.0)',
+    parameters: Type.Object({
+      query: Type.String({ description: 'Şirket adı veya hisse kodu (ör. THYAO, Türk Hava)' }),
+      limit: Type.Optional(
+        Type.Number({ description: 'Maksimum sonuç sayısı (varsayılan 10)', minimum: 1, maximum: 50 }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      _params: { query: string; limit?: number },
+      _signal: AbortSignal | undefined,
+      _onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: 'KAP modülü henüz tamamlanmadı. v0.1.0 sürümünde eklenecek.',
+          },
+        ],
+        details: {},
+      };
+    },
+  };
+}

package/src/modules/kripto/index.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createKriptoService } from './service.ts';
+import { createKriptoFiyatTool } from './tools.ts';
+
+export function registerKriptoModule(pi: ExtensionAPI, config: FinanceTrConfig): void {
+  const service = createKriptoService(config);
+  pi.registerTool(createKriptoFiyatTool(service));
+}

package/src/modules/kripto/service.ts

@@ -0,0 +1,148 @@
+import { TtlCache } from '../../cache.ts';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createHttpClient, HttpError } from '../../utils/http.ts';
+
+export interface KriptoFiyatResult {
+  coin: string;
+  symbol: string;
+  fiyatTry: number;
+  fiyatUsd: number;
+  degisim24sYuzde: number;
+  sonGuncelleme: string;
+}
+
+const KRIPTO_CACHE_TTL_SECONDS = 60;
+
+const COINGECKO_BASE = 'https://api.coingecko.com/api/v3';
+
+export const COIN_ID_MAP: Record<string, string> = {
+  BTC: 'bitcoin',
+  ETH: 'ethereum',
+  SOL: 'solana',
+  BNB: 'binancecoin',
+  XRP: 'ripple',
+  DOGE: 'dogecoin',
+  ADA: 'cardano',
+  AVAX: 'avalanche-2',
+  DOT: 'polkadot',
+  MATIC: 'matic-network',
+  LINK: 'chainlink',
+  LTC: 'litecoin',
+  UNI: 'uniswap',
+  ATOM: 'cosmos',
+  ETC: 'ethereum-classic',
+  XLM: 'stellar',
+  ALGO: 'algorand',
+  NEAR: 'near',
+  SHIB: 'shiba-inu',
+  TRX: 'tron',
+  BCH: 'bitcoin-cash',
+  FIL: 'filecoin',
+  HBAR: 'hedera-hashgraph',
+  ICP: 'internet-computer',
+  VET: 'vechain',
+};
+
+export class UnknownCoinError extends Error {
+  constructor(coin: string) {
+    const examples = Object.keys(COIN_ID_MAP).slice(0, 8).join(', ');
+    super(
+      `Bilinmeyen kripto kodu: "${coin}". Desteklenenlerden bazıları: ${examples}. ` +
+        'CoinGecko ID de kullanabilirsiniz (ör. "avalanche-2").',
+    );
+    this.name = 'UnknownCoinError';
+  }
+}
+
+export class RateLimitError extends Error {
+  constructor(readonly retryAfterSeconds: number) {
+    super(
+      `CoinGecko rate limit aşıldı. ${retryAfterSeconds} saniye sonra tekrar deneyin.`,
+    );
+    this.name = 'RateLimitError';
+  }
+}
+
+function resolveCoinId(input: string): string {
+  const upper = input.toUpperCase().trim();
+  return COIN_ID_MAP[upper] ?? input.toLowerCase().trim();
+}
+
+function formatNum(n: number): number {
+  return Number.isFinite(n) ? n : 0;
+}
+
+interface CoinGeckoEntry {
+  try?: number;
+  usd?: number;
+  usd_24h_change?: number;
+  try_24h_change?: number;
+  last_updated_at?: number;
+}
+
+export function createKriptoService(config: FinanceTrConfig) {
+  const cache = new TtlCache<KriptoFiyatResult>(KRIPTO_CACHE_TTL_SECONDS);
+  const http = createHttpClient(config);
+
+  async function fetchKriptoFiyat(
+    coin: string,
+    currencies: string[] = ['try', 'usd'],
+  ): Promise<KriptoFiyatResult> {
+    const coinId = resolveCoinId(coin);
+    const symbol = coin.toUpperCase().trim();
+    const sortedCurrencies = [...currencies].sort();
+    const cacheKey = `${coinId}:${sortedCurrencies.join(',')}`;
+
+    const cached = cache.get(cacheKey);
+    if (cached) return cached;
+
+    const vs = sortedCurrencies.join(',');
+    const url =
+      `${COINGECKO_BASE}/simple/price` +
+      `?ids=${coinId}&vs_currencies=${vs}` +
+      `&include_24hr_change=true&include_last_updated_at=true`;
+
+    let response: Response;
+    try {
+      response = await http.fetchWithRetry(url);
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 429) {
+        throw new RateLimitError(60);
+      }
+      throw err;
+    }
+
+    if (response.status === 429) {
+      const retryAfter = parseInt(response.headers.get('Retry-After') ?? '60', 10);
+      throw new RateLimitError(Number.isFinite(retryAfter) ? retryAfter : 60);
+    }
+
+    const data = (await response.json()) as Record<string, CoinGeckoEntry>;
+
+    if (!data[coinId] || Object.keys(data[coinId]).length === 0) {
+      throw new UnknownCoinError(coin);
+    }
+
+    const entry = data[coinId];
+    const change =
+      entry.usd_24h_change !== undefined
+        ? entry.usd_24h_change
+        : (entry.try_24h_change ?? 0);
+
+    const result: KriptoFiyatResult = {
+      coin: coinId,
+      symbol,
+      fiyatTry: formatNum(entry.try ?? 0),
+      fiyatUsd: formatNum(entry.usd ?? 0),
+      degisim24sYuzde: formatNum(change),
+      sonGuncelleme: new Date(
+        (entry.last_updated_at ?? Math.floor(Date.now() / 1000)) * 1000,
+      ).toISOString(),
+    };
+
+    cache.set(cacheKey, result);
+    return result;
+  }
+
+  return { fetchKriptoFiyat };
+}

package/src/modules/kripto/tools.ts

@@ -0,0 +1,103 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import type { createKriptoService } from './service.ts';
+import { UnknownCoinError, RateLimitError, COIN_ID_MAP } from './service.ts';
+
+const DISCLAIMER =
+  'ℹ️ CoinGecko verileri — bilgilendirme amaçlıdır, yatırım tavsiyesi değildir.';
+
+function formatKripto(n: number): string {
+  const fractionDigits = n === 0 ? 2 : n < 0.0001 ? 8 : n < 0.01 ? 6 : n < 1 ? 4 : 2;
+  return n.toLocaleString('tr-TR', {
+    minimumFractionDigits: fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  });
+}
+
+function formatDegisim(pct: number): string {
+  const sign = pct >= 0 ? '+' : '';
+  const formatted = Math.abs(pct).toLocaleString('tr-TR', {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  });
+  return `${sign}%${pct >= 0 ? '' : '-'}${formatted}`;
+}
+
+function formatError(err: unknown): string {
+  if (err instanceof UnknownCoinError) {
+    return err.message;
+  }
+  if (err instanceof RateLimitError) {
+    return err.message;
+  }
+  if (err instanceof Error && (err.name === 'AbortError' || err.message.toLowerCase().includes('abort'))) {
+    return "CoinGecko'ya ulaşılamıyor (timeout). İnternet bağlantınızı kontrol edin.";
+  }
+  if (err instanceof Error) {
+    return `Hata: ${err.message}`;
+  }
+  return 'Beklenmeyen bir hata oluştu.';
+}
+
+export function createKriptoFiyatTool(service: ReturnType<typeof createKriptoService>) {
+  return {
+    name: 'finance_tr_kripto_fiyat',
+    label: 'Kripto Para Fiyatı',
+    description:
+      'CoinGecko üzerinden kripto para fiyatları. TRY ve USD karşılığı, 24 saatlik değişim.',
+    parameters: Type.Object({
+      coin: Type.String({
+        description: `Kripto para kodu (ör. BTC, ETH, SOL) veya CoinGecko ID. Desteklenenler: ${Object.keys(COIN_ID_MAP).join(', ')}`,
+      }),
+      currencies: Type.Optional(
+        Type.Array(Type.String(), {
+          description: 'Karşılaştırma para birimleri (varsayılan: ["try", "usd"])',
+        }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { coin: string; currencies?: string[] },
+      _signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      const symbol = params.coin.toUpperCase();
+
+      if (onUpdate) {
+        onUpdate({
+          content: [{ type: 'text' as const, text: `CoinGecko'dan ${symbol} fiyatı alınıyor...` }],
+          details: undefined,
+        });
+      }
+
+      try {
+        const result = await service.fetchKriptoFiyat(params.coin, params.currencies);
+
+        const tryStr = result.fiyatTry > 0 ? `${formatKripto(result.fiyatTry)} TRY` : null;
+        const usdStr = result.fiyatUsd > 0 ? `${formatKripto(result.fiyatUsd)} USD` : null;
+        const parts = [tryStr, usdStr].filter(Boolean).join('  |  ');
+        const degisim = formatDegisim(result.degisim24sYuzde);
+
+        const headline = `${result.symbol} (${result.coin}): ${parts}  |  24s: ${degisim}`;
+
+        if (onUpdate) {
+          onUpdate({
+            content: [{ type: 'text' as const, text: headline }],
+            details: undefined,
+          });
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: `${headline}\n\n${DISCLAIMER}` }],
+          details: result,
+        };
+      } catch (err) {
+        const msg = formatError(err);
+        return {
+          content: [{ type: 'text' as const, text: msg }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/modules/kur/index.ts

@@ -0,0 +1,9 @@
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createKurService } from './service.ts';
+import { createDovizKurTool } from './tools.ts';
+
+export function registerKurModule(pi: ExtensionAPI, config: FinanceTrConfig): void {
+  const service = createKurService(config);
+  pi.registerTool(createDovizKurTool(service));
+}

package/src/modules/kur/service.ts

@@ -0,0 +1,125 @@
+import { TtlCache } from '../../cache.ts';
+import { KUR_CACHE_TTL_SECONDS, TCMB_BASE_URL } from '../../constants.ts';
+import type { FinanceTrConfig } from '../../config.ts';
+import { createHttpClient, HttpError } from '../../utils/http.ts';
+import { parseXml } from '../../utils/xml.ts';
+
+export interface DovizKurResult {
+  currency: string;
+  date: string;
+  alis: number;
+  satis: number;
+  banknotAlis: number;
+  banknotSatis: number;
+  capraz?: number;
+}
+
+export class UnknownCurrencyError extends Error {
+  constructor(currency: string) {
+    super(`Bilinmeyen döviz kodu: ${currency}. Örnek geçerli kodlar: USD, EUR, GBP, JPY`);
+    this.name = 'UnknownCurrencyError';
+  }
+}
+
+export class TatilGunuError extends Error {
+  constructor(label: string) {
+    super(`${label} için TCMB kur verisi yok (tatil veya hafta sonu olabilir)`);
+    this.name = 'TatilGunuError';
+  }
+}
+
+interface TcmbCurrency {
+  $: { CrossOrder: string; Kod: string; CurrencyCode: string };
+  Unit: string;
+  Isim: string;
+  CurrencyName: string;
+  ForexBuying: string;
+  ForexSelling: string;
+  BanknoteBuying: string;
+  BanknoteSelling: string;
+  CrossRateUSD: string;
+  CrossRateOther: string;
+}
+
+interface TcmbXmlRoot {
+  Tarih_Date: {
+    $: { Tarih: string; Date: string; Bulten_No: string };
+    Currency: TcmbCurrency | TcmbCurrency[];
+  };
+}
+
+function buildUrl(date?: string): string {
+  if (!date) return `${TCMB_BASE_URL}/today.xml`;
+  // YYYY-MM-DD → YYYYMM/DDMMYYYY
+  const [year, month, day] = date.split('-');
+  return `${TCMB_BASE_URL}/${year}${month}/${day}${month}${year}.xml`;
+}
+
+function tcmbDateToIso(tcmbDate: string): string {
+  // "14.05.2026" → "2026-05-14"
+  const [day, month, year] = tcmbDate.split('.');
+  return `${year}-${month}-${day}`;
+}
+
+function parseNum(value: string | undefined): number {
+  if (!value) return 0;
+  const n = parseFloat(value.trim());
+  return Number.isNaN(n) ? 0 : n;
+}
+
+function pickCrossRate(c: TcmbCurrency): number | undefined {
+  const usd = c.CrossRateUSD?.trim();
+  if (usd) return parseNum(usd);
+  const other = c.CrossRateOther?.trim();
+  if (other) return parseNum(other);
+  return undefined;
+}
+
+export function createKurService(config: FinanceTrConfig) {
+  const ttlSeconds = config.cacheTtlOverrideSeconds ?? KUR_CACHE_TTL_SECONDS;
+  const cache = new TtlCache<DovizKurResult>(ttlSeconds);
+  const http = createHttpClient(config);
+
+  async function fetchDovizKur(currency: string, date?: string): Promise<DovizKurResult> {
+    const code = currency.toUpperCase().trim();
+    const cacheKey = `${code}:${date ?? 'today'}`;
+
+    const cached = cache.get(cacheKey);
+    if (cached) return cached;
+
+    const url = buildUrl(date);
+    let xmlText: string;
+
+    try {
+      const response = await http.fetchWithRetry(url);
+      xmlText = await response.text();
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 404) {
+        throw new TatilGunuError(date ?? 'bugün');
+      }
+      throw err;
+    }
+
+    const parsed = await parseXml<TcmbXmlRoot>(xmlText);
+    const raw = parsed.Tarih_Date.Currency;
+    const currencies = Array.isArray(raw) ? raw : [raw];
+
+    const found = currencies.find((c) => c.$.CurrencyCode === code);
+    if (!found) throw new UnknownCurrencyError(code);
+
+    const result: DovizKurResult = {
+      currency: code,
+      date: tcmbDateToIso(parsed.Tarih_Date.$.Tarih),
+      alis: parseNum(found.ForexBuying),
+      satis: parseNum(found.ForexSelling),
+      banknotAlis: parseNum(found.BanknoteBuying),
+      banknotSatis: parseNum(found.BanknoteSelling),
+      capraz: pickCrossRate(found),
+    };
+
+    cache.set(cacheKey, result);
+    return result;
+  }
+
+  return { fetchDovizKur };
+}

package/src/modules/kur/tools.ts

@@ -0,0 +1,106 @@
+import type { AgentToolUpdateCallback } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import type { createKurService } from './service.ts';
+import { UnknownCurrencyError, TatilGunuError } from './service.ts';
+import { HttpError } from '../../utils/http.ts';
+
+const DISCLAIMER =
+  'ℹ️ TCMB resmi bülten — bilgilendirme amaçlıdır, yatırım tavsiyesi değildir.';
+
+const DESTEKLENEN_KURLAR =
+  'USD, EUR, GBP, JPY, CHF, AUD, CAD, DKK, NOK, SEK, SAR, KWD ve diğerleri';
+
+function formatTr(n: number): string {
+  return n.toLocaleString('tr-TR', { minimumFractionDigits: 4, maximumFractionDigits: 4 });
+}
+
+function formatError(err: unknown, date?: string): string {
+  if (err instanceof UnknownCurrencyError) {
+    return `Bilinmeyen döviz kodu. Desteklenenler: ${DESTEKLENEN_KURLAR}.`;
+  }
+  if (err instanceof TatilGunuError) {
+    const tarih = date ? `"${date}" tarihinde` : 'bu tarihte';
+    return `TCMB ${tarih} bülten yayımlamamış (tatil/hafta sonu olabilir). Önceki iş gününü deneyin.`;
+  }
+  if (err instanceof HttpError && err.status === 408) {
+    return "TCMB'ye ulaşılamıyor (timeout). İnternet bağlantınızı kontrol edin.";
+  }
+  if (err instanceof Error && (err.name === 'AbortError' || err.message.toLowerCase().includes('abort'))) {
+    return "TCMB'ye ulaşılamıyor (timeout). İnternet bağlantınızı kontrol edin.";
+  }
+  if (err instanceof Error) {
+    return `Hata: ${err.message}`;
+  }
+  return 'Beklenmeyen bir hata oluştu.';
+}
+
+export function createDovizKurTool(service: ReturnType<typeof createKurService>) {
+  return {
+    name: 'finance_tr_doviz_kur',
+    label: 'TCMB Döviz Kuru',
+    description:
+      "TCMB'nin yayımladığı güncel veya geçmiş döviz kuru. USD, EUR, GBP vb. desteklenir.",
+    parameters: Type.Object({
+      currency: Type.String({ description: 'Döviz kodu (ör. USD, EUR, GBP, JPY)' }),
+      date: Type.Optional(
+        Type.String({ description: 'Tarih (YYYY-MM-DD formatında; belirtilmezse bugünkü kur)' }),
+      ),
+    }),
+    async execute(
+      _toolCallId: string,
+      params: { currency: string; date?: string },
+      _signal: AbortSignal | undefined,
+      onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+    ) {
+      const code = params.currency.toUpperCase();
+
+      if (onUpdate) {
+        onUpdate({
+          content: [{ type: 'text' as const, text: `TCMB'den ${code} kuru alınıyor...` }],
+          details: undefined,
+        });
+      }
+
+      try {
+        const result = await service.fetchDovizKur(params.currency, params.date);
+
+        const lines = [
+          `${result.currency}/TRY — ${result.date}`,
+          `Döviz Alış:     ${formatTr(result.alis)} TL`,
+          `Döviz Satış:    ${formatTr(result.satis)} TL`,
+          `Banknot Alış:   ${formatTr(result.banknotAlis)} TL`,
+          `Banknot Satış:  ${formatTr(result.banknotSatis)} TL`,
+        ];
+
+        if (result.capraz !== undefined) {
+          lines.push(`Çapraz Kur:     ${formatTr(result.capraz)}`);
+        }
+
+        lines.push('', DISCLAIMER);
+
+        if (onUpdate) {
+          onUpdate({
+            content: [
+              {
+                type: 'text' as const,
+                text: `${result.currency}/TRY ${result.date}: ${formatTr(result.satis)} TL (satış)`,
+              },
+            ],
+            details: undefined,
+          });
+        }
+
+        return {
+          content: [{ type: 'text' as const, text: lines.join('\n') }],
+          details: result,
+        };
+      } catch (err) {
+        const msg = formatError(err, params.date);
+        return {
+          content: [{ type: 'text' as const, text: msg }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,4 @@
+import type { ENABLED_MODULES } from './constants.ts';
+
+export type EnabledModule = (typeof ENABLED_MODULES)[number];
+export type EnvSource = Record<string, string | undefined>;

package/src/utils/http.ts

@@ -0,0 +1,64 @@
+export class HttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'HttpError';
+  }
+}
+
+const RETRY_DELAYS_MS = [200, 400, 800];
+
+export function createHttpClient(config: { userAgent: string; timeoutMs: number }) {
+  const { userAgent, timeoutMs } = config;
+
+  async function fetchWithRetry(
+    url: string,
+    opts?: RequestInit,
+    retries = 3,
+  ): Promise<Response> {
+    let lastError: unknown;
+
+    for (let attempt = 0; attempt < retries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+      try {
+        const response = await fetch(url, {
+          ...opts,
+          headers: { 'User-Agent': userAgent, ...opts?.headers },
+          signal: controller.signal,
+        });
+
+        if (response.status >= 400 && response.status < 500) {
+          throw new HttpError(response.status, `HTTP ${response.status}: ${url}`);
+        }
+
+        if (response.status >= 500) {
+          throw new HttpError(response.status, `HTTP ${response.status}: ${url}`);
+        }
+
+        return response;
+      } catch (err) {
+        if (err instanceof HttpError && err.status >= 400 && err.status < 500) {
+          throw err;
+        }
+        lastError = err;
+        if (attempt < retries - 1) {
+          await sleep(RETRY_DELAYS_MS[attempt] ?? 800);
+        }
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+
+    throw lastError;
+  }
+
+  return { fetchWithRetry };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/utils/xml.ts

@@ -0,0 +1,5 @@
+import xml2js from 'xml2js';
+
+export async function parseXml<T>(xmlString: string): Promise<T> {
+  return xml2js.parseStringPromise(xmlString, { explicitArray: false }) as Promise<T>;
+}