borsajs 0.1.4 → 0.1.5

package/README.en.md

@@ -39,6 +39,8 @@ const cryptoList = await cryptoSymbols(); // → ['BTCTRY', 'ETHTRY', ...] (173
 
 ### Ticker (Stocks)
 
+**Get real-time BIST stock prices and volume data in seconds.** The Ticker API provides instant access to current price, daily change, volume, and OHLC (Open-High-Low-Close) values for any stock. Perfect for technical analysis, portfolio tracking, or automated trading strategies.
+
 ```typescript
 import { Ticker } from 'borsajs';
 
@@ -83,6 +85,8 @@ const history = await stock.getHistory({ period: '5d', interval: '1d' });
 
 ### FX (Forex & Commodities)
 
+**Track live exchange rates and commodity prices effortlessly.** Access real-time data for major currencies (USD, EUR, GBP) and precious metals (gold, silver). Essential for currency arbitrage, gold investment strategies, or exchange rate monitoring.
+
 ```typescript
 import { FX, fxSymbols } from 'borsajs';
 
@@ -107,6 +111,8 @@ const current = await usd.getCurrent();
 
 ### Crypto
 
+**Live data from Turkey's largest crypto exchange, BtcTurk.** Access price, volume, and change information for 173 cryptocurrency pairs. The fastest way to track Bitcoin, Ethereum, and other cryptos in Turkish Lira.
+
 ```typescript
 import { Crypto, cryptoSymbols } from 'borsajs';
 
@@ -136,6 +142,8 @@ const current = await btc.getCurrent();
 
 ### Index
 
+**Monitor BIST indices in real-time.** Get current values and percentage changes for market and sector indices like XU100, XU030, XBANK. Essential for analyzing market trends and comparing sectoral performance.
+
 ```typescript
 import { Index, indexSymbols } from 'borsajs';
 
@@ -163,6 +171,8 @@ const info = await xu100.getInfo();
 
 ### Fund (Investment Funds)
 
+**Search and track Turkish investment funds from TEFAS.** Access fund prices, returns, and performance metrics. Compare funds and make informed investment decisions with official data.
+
 ```typescript
 import { Fund, searchFunds } from 'borsajs';
 
@@ -186,6 +196,8 @@ const info = await fund.getInfo();
 
 ### Inflation
 
+**Access official inflation data directly from TCMB (Central Bank).** Query monthly and annual CPI rates, or calculate inflation between any two dates. Critical for evaluating investments on a real return basis.
+
 ```typescript
 import { Inflation } from 'borsajs';
 
@@ -220,6 +232,14 @@ const calc = await inflation.calculate(100000, '2020-01', '2024-01');
 
 ### KAP (Public Disclosure Platform)
 
+**One-stop access to official company announcements and disclosures.** Query disclosures, expected report calendars, and corporate information for all 731 BIST companies. Make investment decisions based on official company statements.
+
+**Features:**
+- 🏢 **731 BIST Companies** - Complete list with details
+- 📢 **Live Disclosures** - All company announcements
+- 📅 **Disclosure Calendar** - Financial report dates
+- 🏛️ **Corporate Info** - Sector, market, website
+
 ```typescript
 import { getKapProvider } from 'borsajs';
 
@@ -301,6 +321,8 @@ const details = await kap.getCompanyDetails('THYAO');
 
 ### Symbols
 
+**Access all market symbols in a single call.** Get comprehensive lists of stocks, cryptocurrencies, currencies, and indices. Perfect starting point for automated data collection or screening algorithms.
+
 ```typescript
 import { symbols, searchSymbols, cryptoSymbols, fxSymbols, indexSymbols } from 'borsajs';
 
@@ -320,17 +342,52 @@ console.log(indexSymbols); // → 19 indices
 
 ### VIOP (Derivatives)
 
+**Track Turkish derivatives market (futures and options).** Access real-time data for stock futures, index futures, currency futures, and options contracts. Essential for hedging strategies and derivatives trading.
+
 ```typescript
 import { VIOP } from 'borsajs';
 
 const viop = new VIOP();
+
+// Get all futures
 const futures = await viop.getFutures();
+
+// Stock futures
+const stockFutures = await viop.getStockFutures();
+
+// Index futures (XU100, XU030, etc.)
+const indexFutures = await viop.getIndexFutures();
+
+// Currency futures (USD, EUR)
+const currencyFutures = await viop.getCurrencyFutures();
+
+// Commodity futures (Gold)
+const commodityFutures = await viop.getCommodityFutures();
+
+// Options
 const options = await viop.getOptions();
-const thyao = await viop.getBySymbol('THYAO');
+
+// Contracts for specific stock
+const thyaoContracts = await viop.getBySymbol('THYAO');
+```
+
+**Response (Contract Data):**
+```json
+{
+  "code": "THYAO",
+  "contract": "THYAO0226",
+  "price": 275.5,
+  "change": 1.25,
+  "volumeTl": 15420000,
+  "volumeQty": 56000,
+  "category": "stock"
+}
 ```
 
 ### Download (Multiple Tickers)
 
+**Batch download historical data for multiple stocks at once.** Efficient way to collect OHLCV data for portfolio analysis or backtesting strategies. Get data for dozens of stocks in a single request.
+
 ```typescript
 import { download, Tickers } from 'borsajs';
 

package/README.md

@@ -39,6 +39,8 @@ const cryptoList = await cryptoSymbols(); // → ['BTCTRY', 'ETHTRY', ...] (173
 
 ### Ticker (Hisse Senedi)
 
+**BIST hisselerinin anlık fiyat ve hacim verilerine saniyeler içinde ulaşın.** Ticker API, bir hisse senedinin güncel fiyatı, günlük değişimi, işlem hacmi ve OHLC (açılış-en yüksek-en düşük-kapanış) değerlerini kolayca almanızı sağlar. Teknik analiz, portföy takibi veya otomatik alım-satım stratejileri için ideal.
+
 ```typescript
 import { Ticker } from 'borsajs';
 
@@ -65,6 +67,8 @@ const info = await stock.getInfo();
 
 ### FX (Döviz & Emtia)
 
+**Döviz kurları ve emtia fiyatlarını canlı takip edin.** FX API ile USD, EUR gibi döviz kurlarının yanı sıra altın, gümüş ve ons fiyatlarına anında erişebilirsiniz. Kur takibi, döviz arbitrajı veya altın yatırım stratejileri için güvenilir veri kaynağı.
+
 ```typescript
 import { FX, fxSymbols } from 'borsajs';
 
@@ -89,6 +93,8 @@ const current = await usd.getCurrent();
 
 ### Crypto (Kripto Para)
 
+**Türkiye'nin en büyük kripto borsası BtcTurk'ten anlık veriler.** 173 kripto para çiftinin fiyat, hacim ve değişim bilgilerine erişin. Bitcoin, Ethereum ve diğer kripto paraların TRY karşılığını takip etmek için en hızlı yol.
+
 ```typescript
 import { Crypto, cryptoSymbols } from 'borsajs';
 
@@ -118,6 +124,8 @@ const current = await btc.getCurrent();
 
 ### Index (Endeksler)
 
+**BIST endekslerini gerçek zamanlı izleyin.** XU100, XU030, XBANK gibi sektör ve piyasa endekslerinin güncel değerleri ve yüzdesel değişimlerini alın. Piyasa trendlerini analiz etmek ve sektörel performansı karşılaştırmak için vazgeçilmez.
+
 ```typescript
 import { Index, indexSymbols } from 'borsajs';
 
@@ -145,6 +153,8 @@ const info = await xu100.getInfo();
 
 ### Inflation (Enflasyon)
 
+**TCMB'nin resmi enflasyon verilerine doğrudan erişin.** Aylık ve yıllık TÜFE oranlarını sorgulayın veya geçmiş tarihler arasında enflasyon hesaplayın. Yatırım kararlarınızı reel getiri bazında değerlendirmek için kritik.
+
 ```typescript
 import { Inflation } from 'borsajs';
 
@@ -179,6 +189,14 @@ const calc = await inflation.calculate(100000, '2020-01', '2024-01');
 
 ### KAP (Kamu Aydınlatma Platformu)
 
+**Şirketlerin resmi açıklamalarına ve bildirimlerine tek noktadan ulaşın.** KAP API ile 731 BIST şirketinin bildirimlerini, beklenen rapor takvimlerini ve kurumsal bilgilerini sorgulayabilirsiniz. Yatırım kararlarınızı şirketlerin resmi açıklamaları ışığında alın.
+
+**Özellikler:**
+- 🏢 **731 BIST şirketi** - Tüm halka açık şirketlerin listesi ve bilgileri
+- 📢 **Anlık Bildirimler** - Şirketlerin KAP'a yaptığı tüm açıklamalar
+- 📅 **Bildirim Takvimi** - Finansal rapor ve açıklama tarihleri
+- 🏛️ **Kurumsal Bilgiler** - Sektör, pazar, web sitesi bilgileri
+
 ```typescript
 import { getKapProvider } from 'borsajs';
 
@@ -258,8 +276,54 @@ const details = await kap.getCompanyDetails('THYAO');
 }
 ```
 
+### VIOP (Vadeli İşlem ve Opsiyon Piyasası)
+
+**Türk türev piyasasını gerçek zamanlı takip edin.** Hisse senedi vadeli işlemleri, endeks vadeli işlemleri, döviz ve emtia kontratlarına anında erişin. Riskten korunma (hedging) stratejileri ve türev ürün ticareti için vazgeçilmez.
+
+```typescript
+import { VIOP } from 'borsajs';
+
+const viop = new VIOP();
+
+// Tüm vadeli işlemleri al
+const futures = await viop.getFutures();
+
+// Hisse senedi vadeli işlemleri
+const stockFutures = await viop.getStockFutures();
+
+// Endeks vadeli işlemleri
+const indexFutures = await viop.getIndexFutures();
+
+// Döviz vadeli işlemleri
+const currencyFutures = await viop.getCurrencyFutures();
+
+// Emtia vadeli işlemleri
+const commodityFutures = await viop.getCommodityFutures();
+
+// Opsiyonlar
+const options = await viop.getOptions();
+
+// Belirli bir hisse için kontratlar
+const thyaoContracts = await viop.getBySymbol('THYAO');
+```
+
+**Response (Contract Data):**
+```json
+{
+  "code": "THYAO",
+  "contract": "THYAO0226",
+  "price": 275.5,
+  "change": 1.25,
+  "volumeTl": 15420000,
+  "volumeQty": 56000,
+  "category": "stock"
+}
+```
+
 ### Symbols (Sembol Listeleri)
 
+**Tüm piyasa sembollerine tek çağrıda erişin.** Hisse senetleri, kripto paralar, dövizler ve endekslerin sembol listelerini alın. Otomatik veri çekme veya tarama algoritmaları için mükemmel başlangıç noktası.
+
 ```typescript
 import { symbols, searchSymbols, cryptoSymbols, fxSymbols, indexSymbols } from 'borsajs';
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "borsajs",
-    "version": "0.1.4",
-    "description": "Turkey financial markets data library, BIST stocks, KAP, forex, crypto, investment funds, and more",
+    "version": "0.1.5",
+    "description": "Türkiye financial markets data library, BIST stocks, KAP,VIOP, forex, crypto, investment funds, and more",
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/test/demo.ts

@@ -10,6 +10,7 @@ import { Inflation } from '../src/inflation.js';
 import { Ticker } from '../src/ticker.js';
 import { symbols, searchSymbols, cryptoSymbols, fxSymbols, indexSymbols } from '../src/market.js';
 import { getKapProvider } from '../src/providers/kap.js';
+import { VIOP } from '../src/viop.js';
 
 async function testCrypto() {
     console.log('\n🪙 CRYPTO (BtcTurk)');
@@ -152,6 +153,35 @@ async function testKap() {
     } catch (error) { console.error('Error:', error); }
 }
 
+async function testViop() {
+    console.log('\n📊 VIOP (Derivatives Market)');
+    console.log('─'.repeat(60));
+    try {
+        const viop = new VIOP();
+
+        // Test stock futures
+        const stockFutures = await viop.getStockFutures();
+        console.log(`Stock Futures: ${stockFutures.length} contracts`);
+        if (stockFutures.length > 0) {
+            console.log('Sample:', JSON.stringify(stockFutures.slice(0, 2), null, 2));
+        }
+
+        // Test index futures
+        const indexFutures = await viop.getIndexFutures();
+        console.log(`\nIndex Futures: ${indexFutures.length} contracts`);
+        if (indexFutures.length > 0) {
+            console.log('Sample:', JSON.stringify(indexFutures.slice(0, 2), null, 2));
+        }
+
+        // Test by symbol
+        const thyaoContracts = await viop.getBySymbol('THYAO');
+        console.log(`\nTHYAO Contracts: ${thyaoContracts.length}`);
+        if (thyaoContracts.length > 0) {
+            console.log('First:', JSON.stringify(thyaoContracts[0], null, 2));
+        }
+    } catch (error) { console.error('Error:', error); }
+}
+
 async function main() {
     console.log('🚀 borsajs API Test');
     console.log('═'.repeat(60));
@@ -164,6 +194,7 @@ async function main() {
     await testInflation();
     await testSymbols();
     await testKap();
+    await testViop();
 
     console.log('\n' + '═'.repeat(60));
     console.log('✅ All tests completed!');