# 🇻🇳 vn-stock-sdk

**Thư viện TypeScript/Node.js toàn diện để lấy dữ liệu chứng khoán Việt Nam (HOSE, HNX, UPCOM).**

[![npm version](https://img.shields.io/npm/v/vn-stock-sdk.svg)](https://www.npmjs.com/package/vn-stock-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

Hỗ trợ lấy dữ liệu từ nhiều nguồn (TCBS, VNDirect, DNSE, SSI, Vietcombank...) với cơ chế **tự động retry**, **xoay vòng nguồn dữ liệu** và **Type-safe** hoàn toàn.

## 🚀 Tính năng nổi bật

*   **Đa nguồn dữ liệu:** Tự động tích hợp dữ liệu từ TCBS, VNDirect, DNSE, SSI.
*   **Dữ liệu phong phú:**
    *   Lịch sử giá (OHLCV) theo Ngày, Phút (1m, 5m, 15m...).
    *   Báo cáo tài chính (Cân đối kế toán, KQKD, Lưu chuyển tiền tệ).
    *   Thông tin doanh nghiệp, Cổ đông, Sự kiện quyền.
    *   Khớp lệnh Intraday, Phân tích dòng tiền Cá mập/Sói/Cừu.
    *   Chỉ số thị trường (VNIndex, VN30...), Phái sinh (VN30F).
    *   Ngoại hối (Vietcombank), Giá vàng (SJC), Quỹ mở, Trái phiếu.
*   **TypeScript:** Định nghĩa kiểu dữ liệu (Interface/Enum) đầy đủ, hỗ trợ IDE gợi ý code.
*   **Hiệu năng cao:** Tích hợp sẵn cơ chế Retry thông minh, Timeout và Headers giả lập trình duyệt.
*   **Không cần API Key:** Sử dụng các API public miễn phí.

## 📦 Cài đặt

```bash
npm install vn-stock-sdk
```
hoặc
```bash
yarn add vn-stock-sdk
```

## 📖 Hướng dẫn nhanh

```typescript
import { VnStockClient, Interval, DataSource } from 'vn-stock-sdk';

const client = new VnStockClient({ debug: false });

async function main() {
    // 1. Lấy lịch sử giá (OHLCV)
    // Mặc định dùng TCBS (Daily)
    const history = await client.quote("VCB").history({
        start: "2024-01-01",
        end: "2024-03-01",
        interval: Interval.D1
    });

    // 2. Lấy chart phút từ VNDirect (hoặc DNSE)
    const minuteChart = await client.quote("HPG").history({
        start: "2024-02-28",
        end: "2024-02-29",
        interval: Interval.M15, // 15 phút
        source: DataSource.VNDIRECT
    });

    // 3. Thông tin công ty & Cổ đông
    const company = await client.company("FPT").overview();
    const shareholders = await client.company("FPT").shareholders();

    console.log(`Công ty: ${company.name}, Vốn hoá: ${company.marketCap}`);
}

main();
```

## 📚 API Chi tiết

Client được chia thành các module chức năng để dễ sử dụng:

### 1. Quote (Dữ liệu giá & Khớp lệnh)
Truy cập qua: `client.quote(symbol)`

| Phương thức | Mô tả |
|Data Source|
|---|---|---|
| `.history({ start, end, interval, source })` | Lấy dữ liệu nến OHLCV. Hỗ trợ khung ngày (TCBS) và phút (VNDirect, DNSE). |
| `.intraday(page)` | Lấy dữ liệu khớp lệnh từng tick trong phiên (Intraday). |
| `.activeBuySellSummary()` | Thống kê khối lượng mua/bán chủ động. |
| `.investorTypeStats()` | Phân tích dòng tiền theo loại NĐT (Cá mập, Sói, Cừu). |
| `.news()` | Tin tức liên quan đến mã chứng khoán. |

### 2. Finance (Báo cáo tài chính)
Truy cập qua: `client.finance(symbol)`

| Phương thức | Mô tả |
|---|---|
| `.balanceSheet(period, limit)` | Bảng cân đối kế toán (Năm/Quý). |
| `.incomeStatement(period, limit)` | Báo cáo kết quả hoạt động kinh doanh. |
| `.cashFlow(period, limit)` | Báo cáo lưu chuyển tiền tệ. |
| `.ratio(period, limit)` | Các chỉ số tài chính (P/E, ROE, ROA, Margin...). |
| `.all(period, limit)` | Lấy tất cả các báo cáo trên cùng lúc. |

### 3. Company (Thông tin doanh nghiệp)
Truy cập qua: `client.company(symbol)`

| Phương thức | Mô tả |
|---|---|
| `.overview()` | Hồ sơ công ty, ngành nghề, vốn hoá, số lượng CP. |
| `.shareholders()` | Danh sách cổ đông lớn. |
| `.officers()` | Ban lãnh đạo & HĐQT. |
| `.events()` | Lịch sự kiện (Cổ tức, họp ĐHCĐ, phát hành thêm...). |
| `.insiderTrading()` | Giao dịch nội bộ (Ban lãnh đạo mua/bán). |
| `.foreignTrading(start, end)` | Lịch sử giao dịch khối ngoại. |

### 4. Market (Thị trường chung)
Truy cập qua: `client.market()`

| Phương thức | Mô tả |
|---|---|
| `.index(indexName, start, end)` | Lịch sử chỉ số (VNINDEX, VN30, HNX30...). |
| `.screener(filter)` | Bộ lọc cổ phiếu (theo P/E, ROE, Vốn hoá...). |
| `.derivativeHistory(symbol)` | Lịch sử giá phái sinh (VN30F1M...). |

### 5. Listing (Danh sách niêm yết)
Truy cập qua: `client.listing()`

| Phương thức | Mô tả |
|---|---|
| `.all(source)` | Danh sách toàn bộ mã chứng khoán trên 3 sàn. |
| `.indexGroup(groupName)` | Danh sách mã trong rổ chỉ số (VN30, VN100...). |
| `.sectors()` | Danh sách phân ngành ICB. |

### 6. Misc (Tiện ích khác)
Truy cập qua: `client.misc()`

| Phương thức | Mô tả |
|---|---|
| `.exchangeRates()` | Tỷ giá ngoại tệ (Nguồn: Vietcombank). |
| `.goldPrice()` | Giá vàng SJC (Nguồn: SJC). |
| `.bonds()` | Danh sách trái phiếu doanh nghiệp (iBond TCBS). |
| `.coveredWarrants()` | Danh sách chứng quyền (CW). |

---

## ⚙️ Cấu hình (Configuration)

Bạn có thể tuỳ chỉnh `VnStockClient` khi khởi tạo:

```typescript
const client = new VnStockClient({
    // Timeout cho mỗi request (ms)
    timeout: 10000, 
    
    // Số lần thử lại nếu request lỗi
    retries: 3, 
    
    // In log ra console để debug
    debug: true, 
    
    // (Tuỳ chọn) User-Agent tuỳ chỉnh
    userAgent: "MyTradingBot/1.0" 
});
```

## ⚠️ Disclaimer (Miễn trừ trách nhiệm)

*   **Không phải lời khuyên đầu tư:** Thư viện này chỉ phục vụ mục đích học tập, nghiên cứu và lấy dữ liệu.
*   **Nguồn dữ liệu:** Dữ liệu được lấy từ các nguồn công khai (Public APIs) của các công ty chứng khoán. Thư viện không chịu trách nhiệm về tính chính xác, kịp thời hoặc tính sẵn sàng của dữ liệu.
*   **Sử dụng hợp lý:** Vui lòng không spam request quá mức gây ảnh hưởng đến server của các nhà cung cấp dữ liệu.

## 🤝 Đóng góp (Contributing)

Mọi đóng góp (Pull Request, Issue) đều được hoan nghênh!

1.  Fork dự án.
2.  Tạo branch tính năng (`git checkout -b feature/AmazingFeature`).
3.  Commit thay đổi (`git commit -m 'Add some AmazingFeature'`).
4.  Push lên branch (`git push origin feature/AmazingFeature`).
5.  Mở Pull Request.

## 📄 License

Dự án được phân phối dưới giấy phép **MIT**. Xem file `LICENSE` để biết thêm chi tiết.