@invezgo/sdk 1.0.1 → 1.3.0

package/README.md

@@ -1,350 +1,313 @@
-<div align="center">
-
-![Versi](https://img.shields.io/badge/versi-1.0.0-blue.svg)
-![Lisensi](https://img.shields.io/badge/lisensi-MIT-green.svg)
-![TypeScript](https://img.shields.io/badge/TypeScript-Siap-blue.svg)
-![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)
-
-# 📈 Invezgo SDK
-
-**SDK Resmi JavaScript/TypeScript untuk Invezgo API — Platform AI & Data Pasar Saham Indonesia**
-
-SDK ini menyediakan akses mudah ke **API Saham Indonesia** dari platform **Invezgo**, mencakup data **Bursa Efek Indonesia (BEI)**, **laporan keuangan emiten**, **Bandarmology**, **Foreign Flow**, **AI Insight**, dan banyak lagi.
-
-[✨ Fitur](#-fitur) • [⚙️ Instalasi](#-instalasi) • [🚀 Mulai Cepat](#-mulai-cepat) • [📚 Dokumentasi](#-dokumentasi) • [💡 Contoh](#-contoh) • [📖 API Reference](#-api-reference)
-
-</div>
-
----
-
-## 🇮🇩 Tentang Invezgo
-
-**Invezgo** adalah **platform analisis saham berbasis kecerdasan buatan (AI)** yang berfokus pada pasar modal Indonesia.  
-Misi kami adalah membantu investor ritel mendapatkan **akses setara terhadap data, wawasan, dan analisis pasar saham** melalui kombinasi teknologi data, AI, dan antarmuka yang mudah digunakan.
-
-Invezgo menyediakan:
-- 📊 **Data pasar saham Indonesia (BEI)** secara real-time  
-- 🧮 **Analisis otomatis** seperti Bandarmology, Foreign Flow, dan akumulasi investor  
-- 🤖 **AI Insight** yang menjelaskan pola perdagangan dan perilaku pasar  
-- 📈 **Laporan keuangan & indikator fundamental** yang terintegrasi  
-- 🧠 **Alat riset seperti screener, portofolio, watchlist, dan jurnal trading**  
-
-Dengan **Invezgo SDK**, Anda dapat mengintegrasikan seluruh fitur tersebut langsung ke aplikasi Anda — baik untuk **Fintech**, **dashboard analisis saham**, **screener otomatis**, atau **riset kuantitatif**.
-
----
-
-## ✨ Fitur Utama
-
-- 🔥 **Dukungan Penuh TypeScript** — Semua endpoint memiliki definisi tipe lengkap  
-- 📦 **Dual Module (CJS & ESM)** — Dapat digunakan di Node.js maupun browser modern  
-- 🎯 **Cakupan Lengkap** — Mencakup semua endpoint API Invezgo  
-- 🛡️ **Error Handling Terstruktur** — Menampilkan kode, pesan, dan detail error  
-- ⚡ **Async/Await Modern** — Memanfaatkan sintaks modern yang mudah dibaca  
-- 📚 **Dokumentasi Lengkap** — Mendukung IntelliSense & komentar JSDoc  
-- 🚀 **Tanpa Dependensi** — Ringan, cepat, dan efisien  
-- 🔐 **Keamanan Otomatis** — Autentikasi via Bearer Token  
-- 🌐 **Node.js & Browser** — Dapat digunakan di server maupun aplikasi web  
-
----
-
-## ⚙️ Instalasi
-
-Pasang SDK menggunakan npm, yarn, atau pnpm:
-
-```bash
-# Menggunakan npm
-npm install @invezgo/sdk
-
-# Menggunakan yarn
-yarn add @invezgo/sdk
-
-# Menggunakan pnpm
-pnpm add @invezgo/sdk
-```
-
----
-
-## 🚀 Mulai Cepat
-
-### 1️⃣ Dapatkan API Key Anda
-
-Untuk mulai menggunakan SDK, Anda membutuhkan API key dari Invezgo:
-
-- 🔑 [Pengaturan API Key](https://invezgo.com/id/setting/api)
-- 💳 [Paket Langganan](https://invezgo.com/subscription)
-
----
-
-### 2️⃣ Contoh JavaScript (CommonJS)
-
-```javascript
-const { Invezgo } = require('@invezgo/sdk');
-
-const client = new Invezgo({
-  apiKey: 'api-key-anda'
-});
-
-// Ambil daftar seluruh saham
-(async () => {
-  try {
-    const stocks = await client.analysis.getStockList();
-    console.log(`Ditemukan ${stocks.length} saham`);
-    console.log(stocks[0]); // { code: 'BBCA', name: 'Bank Central Asia', logo: '...' }
-  } catch (error) {
-    console.error('Terjadi kesalahan:', error.message);
-  }
-})();
-```
-
----
-
-### 3️⃣ Contoh TypeScript / ES Modules
-
-```typescript
-import Invezgo from '@invezgo/sdk';
-
-const client = new Invezgo({
-  apiKey: 'api-key-anda'
-});
-
-(async () => {
-  try {
-    const info = await client.analysis.getInformation('BBCA');
-    console.log(info.name);   // Bank Central Asia
-    console.log(info.sector); // Keuangan
-  } catch (error) {
-    console.error('Error:', error);
-  }
-})();
-```
-
----
-
-## 📚 Dokumentasi
-
-### Konfigurasi
-
-```typescript
-import Invezgo from '@invezgo/sdk';
-
-const client = new Invezgo({
-  apiKey: 'api-key-anda',              // Wajib
-  baseURL: 'https://api.invezgo.com',  // Opsional
-  timeout: 30000                       // Opsional (default 30 detik)
-});
-```
-
----
-
-### Kategori Endpoint
-
-| Kategori | Deskripsi | Jumlah Metode |
-|----------|------------|---------------|
-| **`analysis`** | Analisis saham, grafik, data keuangan | 30+ |
-| **`watchlists`** | Manajemen watchlist pribadi | 7 |
-| **`journals`** | Catatan transaksi/jurnal trading | 5 |
-| **`portfolios`** | Portofolio & ringkasan investasi | 2 |
-| **`ai`** | Analisis saham dengan AI | 10 |
-| **`search`** | Pencarian saham & pengguna | 3 |
-| **`profile`** | Profil pengguna & sosial | 8 |
-| **`membership`** | Langganan & transaksi paket | 5 |
-| **`posts`** | Konten komunitas & postingan | 8 |
-| **`trades`** | Data transaksi realisasi | 4 |
-| **`screener`** | Filter saham otomatis | 3 |
-| **`health`** | Status kesehatan API | 3 |
-
----
-
-## 💡 Contoh Penggunaan
-
-### 📊 Analisis Saham
-
-```typescript
-import Invezgo from '@invezgo/sdk';
-const client = new Invezgo({ apiKey: 'api-key-anda' });
-
-// Ambil seluruh daftar saham
-const stocks = await client.analysis.getStockList();
-console.log(`Total saham: ${stocks.length}`);
-
-// Ambil informasi perusahaan
-const info = await client.analysis.getInformation('BBCA');
-console.log(info.name); // Bank Central Asia
-console.log(info.sector); // Keuangan
-```
-
----
-
-### 💰 Laporan Keuangan Emiten
-
-```typescript
-// Ambil laporan Neraca (Balance Sheet)
-const balanceSheet = await client.analysis.getFinancialStatement('BBCA', {
-  statement: 'BS',
-  type: 'Q',
-  limit: 10
-});
-
-console.log(balanceSheet.rows);
-console.log(balanceSheet.columns);
-```
-
----
-
-### 🧭 Broker & Bandarmology
-
-```typescript
-// Ambil data ringkasan broker untuk saham tertentu
-const summary = await client.analysis.getBrokerSummaryStock('BBCA', {
-  from: '2024-12-01',
-  to: '2024-12-30',
-  investor: 'all',
-  market: 'RG'
-});
-console.log(summary);
-```
-
----
-
-### 🤖 Analisis AI
-
-```typescript
-// Analisis AI terhadap aktivitas broker
-const result = await client.ai.analyzeInventoryChart('BBCA', {
-  from: '2024-12-01',
-  to: '2024-12-30',
-  scope: 'vol',
-  investor: 'all',
-  limit: 5,
-  market: 'RG'
-});
-
-console.log(result.summary);
-```
-
----
-
-### 🔎 Screener Saham Otomatis
-
-```typescript
-const results = await client.screener.screen({
-  columns: ['volume', 'close', 'value'],
-  conditions: [
-    { ratio: 'BASIC', column: 'close', operator: '>=', value: '5000' },
-    { ratio: 'COMPARE', column: 'value', compare: 'volume', operator: '>', multiply: 'x', value: '1' }
-  ]
-});
-```
-
----
-
-## 📖 Referensi API
-
-Tersedia lebih dari **100 endpoint terstruktur** dalam kategori berikut:
-
-- `analysis.getStockList()`, `getBrokerList()`, `getInformation(code)`
-- `getChart(code, {from, to})`, `getOrderBook(code)`, `getIntraday(code)`
-- `getTopChange(date)`, `getTopForeign(date)`, `getTopAccumulation(date)`
-- `getFinancialStatement(code, {...})`
-- `getKeyStat(code, {...})`, `getKeyStatChart(...)`
-- `getShareholder(code)`, `getShareholderKSEI(...)`, `getInsider(...)`
-- `getBrokerSummaryStock(...)`, `getInventoryChartStock(...)`
-- `ai.analyzeInventoryChart(...)`, `ai.analyzeShareholderAbove(...)`
-- `watchlists.*`, `journals.*`, `portfolios.*`, `screener.*`, `health.*`
-
----
-
-## 🔐 Keamanan
-
-1. Jangan pernah commit **API key** ke repositori publik  
-2. Gunakan **environment variable** di server:
-   ```typescript
-   const client = new Invezgo({
-     apiKey: process.env.INVEZGO_API_KEY!
-   });
-   ```
-3. Gunakan kunci berbeda untuk *dev* dan *production*  
-4. Lakukan rotasi API key secara berkala  
-
----
-
-## 🌍 Kompatibilitas
-
-SDK ini menggunakan `fetch` API bawaan yang tersedia di:
-
-- ✅ Browser modern (Chrome, Edge, Safari, Firefox)
-- ✅ Node.js 18+
-- ⚠️ Node.js 14–17 → butuh `node-fetch`
-- ⚠️ Browser lama → butuh `whatwg-fetch`
-
----
-
-## ⚠️ Penanganan Error
-
-```typescript
-import { Invezgo, InvezgoError } from '@invezgo/sdk';
-
-try {
-  await client.analysis.getInformation('INVALID');
-} catch (err) {
-  if (err instanceof InvezgoError) {
-    console.error('Kode:', err.statusCode);
-    console.error('Pesan:', err.message);
-  }
-}
-```
-
----
-
-## 🧠 FAQ
-
-**Apakah data ini real-time?**  
-> Sebagian data seperti harga dan orderbook bersifat real-time (jika tersedia). Beberapa data seperti laporan keuangan bersifat periodik (EoD atau kuartalan).
-
-**Apakah aman digunakan di frontend?**  
-> Sebaiknya gunakan server (backend) untuk menyimpan API key, atau gunakan token scoped khusus frontend.
-
-**Apakah SDK ini gratis?**  
-> Beberapa endpoint memerlukan langganan. Lihat [Paket Langganan](https://invezgo.com/subscription).
-
----
-
-## 🤝 Kontribusi
-
-Kami sangat terbuka terhadap kontribusi komunitas.  
-Langkahnya:
-
-1. Fork repository ini  
-2. Buat branch baru: `git checkout -b fitur-baru`  
-3. Commit perubahan: `git commit -m "feat: tambah fitur baru"`  
-4. Push: `git push origin fitur-baru`  
-5. Buka Pull Request  
-
----
-
-## 📝 Lisensi
-
-Proyek ini dirilis di bawah **MIT License** — silakan lihat [LICENSE](LICENSE).
-
----
-
-## 🔗 Tautan Penting
-
-- 🌐 [Website Invezgo](https://invezgo.com)  
-- 📚 [Dokumentasi API](https://api.invezgo.com)  
-- 🔑 [Dapatkan API Key](https://invezgo.com/id/setting/api)  
-- 💳 [Langganan Paket](https://invezgo.com/subscription)  
-- 📋 [Syarat & Ketentuan](https://invezgo.com/terms)  
-- 🔒 [Kebijakan Privasi](https://invezgo.com/privacy-policy)  
-- 🐛 [Laporkan Bug](https://github.com/Invezgo/invezgo-js-sdk/issues)
-
----
-
-<div align="center">
-
-Made with ❤️ by the [Invezgo](https://invezgo.com) team  
-**Empowering Indonesian investors with better data, better insights, and better decisions**
-
-⭐ [Beri bintang di GitHub](https://github.com/Invezgo/invezgo-js-sdk)
-
-</div>
+<div align="center">
+
+# 📈 Invezgo SDK - API Saham Indonesia Resmi untuk JavaScript & TypeScript
+
+![API Saham Indonesia](https://img.shields.io/badge/API%20Saham%20Indonesia-Lengkap-blue)
+![Official SDK](https://img.shields.io/badge/SDK-Resmi-green)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6)
+![Node](https://img.shields.io/badge/Node-%3E%3D14-brightgreen)
+
+**SDK resmi untuk integrasi API Saham Indonesia yang lengkap, resmi, dan performance-oriented.**
+
+Dirancang untuk developer yang membangun aplikasi saham, dashboard analitik, screener, alert engine, watchlist, jurnal transaksi, dan backend service yang membutuhkan akses stabil ke **API Saham Indonesia** dari Invezgo.
+
+[🌐 Website Invezgo](https://invezgo.com) • [📚 Dokumentasi API](https://api.invezgo.com/documentation)
+
+</div>
+
+---
+
+## 🚀 Mengapa Invezgo untuk API Saham Indonesia
+
+Jika Anda mencari **API Saham Indonesia** yang siap dipakai untuk production, `@invezgo/sdk` memberikan surface integrasi yang lebih rapi dibanding request manual. SDK ini dibuat untuk mempermudah integrasi **API Saham Indonesia resmi** ke aplikasi JavaScript dan TypeScript dengan kontrak yang konsisten, typing yang jelas, dan footprint runtime yang ringan.
+
+Keunggulan utamanya:
+
+- ✅ **Resmi**: mengikuti surface API resmi Invezgo
+- ✅ **Lengkap**: mencakup data saham, broker, index, screener, alert, watchlist, jurnal, portofolio, post, dan recommendation
+- ✅ **Cepat dan ringan**: memakai `fetch` native tanpa dependency runtime tambahan
+- ✅ **Developer-first**: mendukung TypeScript, DTO terstruktur, `CJS`, `ESM`, dan error handling yang jelas
+- ✅ **Production-ready**: cocok untuk backend service, internal tools, fintech product, dan dashboard monitoring
+
+---
+
+## 🎯 Cocok untuk Use Case Berikut
+
+- 📊 Dashboard berbasis **API Saham Indonesia**
+- 🤖 Screener saham Indonesia dengan formula custom
+- 🔔 Alert saham dan monitoring market behavior
+- 🧾 Jurnal transaksi dan manajemen watchlist
+- 💼 Portofolio dan personal investment tools
+- 🏗️ Backend integration untuk aplikasi fintech dan wealth platform
+- 🧠 Research tooling untuk quant, trader, dan analis
+
+---
+
+## 📦 Instalasi
+
+```bash
+npm install @invezgo/sdk
+```
+
+---
+
+## 🛒 Cara Mulai dan Berlangganan
+
+Sebelum menggunakan SDK ini, Anda perlu memiliki akses aktif ke **API Saham Indonesia** dari Invezgo.
+
+### 1. Pilih paket langganan API
+
+Kunjungi halaman resmi API Saham Indonesia Invezgo untuk melihat paket yang tersedia dan memilih plan yang sesuai dengan kebutuhan aplikasi Anda:
+
+- Paket API Saham Indonesia: [https://invezgo.com/id/data-api-saham-indonesia](https://invezgo.com/id/data-api-saham-indonesia)
+
+### 2. Login ke akun Invezgo
+
+Setelah memilih paket, login ke akun Invezgo Anda melalui website utama:
+
+- Website Invezgo: [https://invezgo.com](https://invezgo.com)
+
+### 3. Generate API key
+
+Setelah langganan aktif, generate API key dari dashboard akun Invezgo Anda. API key inilah yang akan dipakai untuk autentikasi semua request ke **API Saham Indonesia**.
+
+### 4. Install SDK
+
+Install package JavaScript/TypeScript resmi:
+
+```bash
+npm install @invezgo/sdk
+```
+
+### 5. Simpan API key di environment variable
+
+Contoh yang direkomendasikan:
+
+```bash
+INVEZGO_API_KEY=your_api_key_here
+```
+
+### 6. Mulai integrasi
+
+Gunakan API key tersebut untuk mengakses endpoint Invezgo melalui SDK:
+
+```ts
+import Invezgo from '@invezgo/sdk';
+
+const client = new Invezgo({
+  apiKey: process.env.INVEZGO_API_KEY!,
+});
+```
+
+---
+
+## ⚡ Quick Start
+
+```ts
+import Invezgo from '@invezgo/sdk';
+
+const client = new Invezgo({
+  apiKey: process.env.INVEZGO_API_KEY!,
+});
+
+const stocks = await client.analysis.getStockList();
+const indexes = await client.analysis.getIndexList();
+const intraday = await client.analysis.getIntradayData('BBCA', 'RG');
+
+console.log(stocks[0]);
+console.log(indexes[0]);
+console.log(intraday.close);
+```
+
+---
+
+## 🧩 Fitur Utama API Saham Indonesia di SDK Ini
+
+### 📈 Data pasar dan analysis yang lengkap
+
+Modul `analysis` mencakup endpoint penting untuk **API Saham Indonesia**, termasuk:
+
+- daftar saham dan broker BEI
+- daftar index IDX
+- top gainer, top loser, top foreign, top accumulation, dan top retail flow
+- chart saham dan index
+- intraday chart, intraday summary, dan order book
+- broker summary, broker stalker, inventory chart, momentum chart
+- shareholder data, shareholder relation, insider activity, dan corporate action calendar
+- financial statement dan key statistics
+
+### 🛡️ SDK resmi yang lebih aman untuk production
+
+Menggunakan SDK resmi membantu mengurangi mismatch pada path, query params, payload, dan struktur response. Untuk tim yang membangun produk berbasis **API Saham Indonesia resmi**, pendekatan ini membuat proses development dan maintenance lebih efisien.
+
+### ⚙️ Ringan dan fokus pada performa
+
+`Invezgo SDK` tidak membawa dependency runtime tambahan. Ini relevan untuk aplikasi yang sensitif terhadap startup time, cold start, footprint container, atau deployment serverless.
+
+### 👨‍💻 Developer experience yang rapi
+
+- TypeScript-first
+- `InvezgoError` untuk error handling terstruktur
+- deklarasi tipe untuk DTO dan response utama
+- output build untuk `require` dan `import`
+
+---
+
+## 🗂️ Modul yang Tersedia
+
+- `alerts`
+- `analysis`
+- `watchlists`
+- `journals`
+- `portfolios`
+- `search`
+- `profile`
+- `membership`
+- `posts`
+- `recommendation`
+- `trades`
+- `screener`
+- `usage`
+
+---
+
+## 💡 Contoh Integrasi API Saham Indonesia
+
+### 🔔 Alert saham
+
+```ts
+await client.alerts.add({
+  name: 'Breakout volume',
+  formula: 'close > ema(20) and volume > sma(volume, 20)',
+  category: ['COMPOSITE'],
+  every: 'END_OF_DAY',
+  send: 'IN_OUT',
+});
+```
+
+### 📊 Analysis dan data intraday
+
+```ts
+const topRetail = await client.analysis.getTopRitel('2026-03-10');
+
+const intraday = await client.analysis.getIntradayData('BBCA', 'RG');
+
+const calendar = await client.analysis.getCalendar({
+  code: 'BBCA',
+  page: 1,
+  limit: 10,
+});
+```
+
+### 👀 Watchlist
+
+```ts
+await client.watchlists.add({
+  group: 'banking',
+  code: 'BBCA',
+  price: 9000,
+  scope: ['private'],
+  note: 'Area pantau',
+});
+
+await client.watchlists.updateGroup('group-id', {
+  name: 'Big Caps',
+});
+```
+
+### 🧾 Jurnal transaksi
+
+```ts
+await client.journals.add({
+  code: 'BBCA',
+  broker: 'AK',
+  date: '2026-03-10',
+  lot: 10,
+  fee: 15000,
+  price: 9050,
+  status: 'BUY',
+  scope: ['private'],
+  note: 'Entry bertahap',
+});
+```
+
+### 🔎 Screener saham Indonesia
+
+```ts
+const results = await client.screener.screen({
+  formula: 'close > ema(20)',
+  category: ['COMPOSITE', 'IDXFINANCE'],
+});
+```
+
+### 🤝 Recommendation
+
+```ts
+const recommendations = await client.recommendation.getUserRecommendations();
+```
+
+### 📊 API Usage Statistics
+
+```ts
+const usage = await client.usage.getApiUsage();
+console.log(`Remaining API calls: ${usage.remaining}/${usage.limit}`);
+```
+
+---
+
+## 🏗️ Keunggulan untuk Tim Developer
+
+Saat membangun aplikasi di atas **API Saham Indonesia**, tim engineering biasanya membutuhkan kontrak yang jelas, integrasi yang ringan, dan surface yang mudah dipelihara. `Invezgo SDK` membantu menyederhanakan proses tersebut sehingga tim dapat fokus pada logic produk, bukan pada detail HTTP request yang berulang.
+
+Secara praktis, manfaatnya:
+
+- mengurangi boilerplate request manual
+- mengurangi risiko typo pada endpoint dan payload
+- mempercepat onboarding engineer baru
+- mempermudah review, testing, dan maintenance
+
+---
+
+## 🔄 Catatan Migrasi Versi 1.2.0
+
+- ditambahkan `client.usage` untuk memantau limit dan kuota penggunaan API key
+- ditambahkan endpoint analysis baru: `getMultiTimeChart`, `getShareholderHigh`, `getShareholderClassification`, dan `getShareholderClassifyTable`
+- tipe data fully typed untuk seluruh endpoint yang baru ditambahkan
+
+## 🔄 Catatan Migrasi Versi 1.1.0
+
+- ditambahkan `client.alerts`
+- ditambahkan `client.recommendation`
+- ditambahkan endpoint analysis baru seperti index list, top retail flow, intraday summary, sector stalker, shareholder 1%, dan corporate action calendar
+- DTO `watchlists`, `journals`, `membership`, dan `screener` sudah mengikuti skema request terbaru
+- `client.ai` dan `client.health` dihapus karena tidak lagi tersedia pada kontrak API terbaru
+
+---
+
+## 🛠️ Build
+
+```bash
+npm run build
+```
+
+---
+
+## 🧠 Tipe yang Diekspor
+
+SDK ini mengekspor tipe inti seperti:
+
+- `InvezgoConfig`
+- `Stock`, `Broker`, `StockIndex`
+- `TopChangeResponse`, `TopRetailResponse`
+- `IntradayStockData`, `IntradayIndexData`
+- `ShareholderRelationResponse`
+- `FinancialStatementResponse`, `KeyStatResponse`
+- DTO endpoint seperti `AlertDto`, `CreateWatchlistDto`, `AddJournalTransactionDto`, `ScreenDto`
+
+---
+
+## 🔗 Referensi
+
+- 🌐 Website utama: [https://invezgo.com](https://invezgo.com)
+- 📚 Dokumentasi API: [https://api.invezgo.com/documentation](https://api.invezgo.com/documentation)
+- 🧪 Contoh tambahan: [`docs/EXAMPLES.md`](./docs/EXAMPLES.md)