@writeshh/nepse-sdk/README.md

Node.js wrapper around NepseUnofficialApi (Python)

## NEPSE SDK

Node.js wrapper around the Python library NepseUnofficialApi. It invokes a small Python bridge to access the underlying functionality.

Upstream library: https://github.com/basic-bgnr/NepseUnofficialApi

### Install

```
npm i @writeshh/nepse-sdk
```

- Requires Python >= 3.11.
- On install, this package will try to create a local virtual environment at `.venv` and install the upstream Python lib into it. If that fails (e.g., macOS PEP 668 externally managed Python), it falls back to user/pipx installs and will show guidance.

Manual alternative if needed:

```
pipx install git+https://github.com/basic-bgnr/NepseUnofficialApi
# or
pip3 install --user git+https://github.com/basic-bgnr/NepseUnofficialApi
```

### Configuration

- The bridge prefers `.venv/bin/python` (or Windows `Scripts/python.exe`) recorded in `bridge/.python_path`.
- Override Python path with env: `NEPSE_NODE_PYTHON=/path/to/python node ...`

### Usage (Node API)

```js
const { NepseNode } = require('@writeshh/nepse-sdk');

(async () => {
  const nepse = new NepseNode();

  // Basic
  const companies = await nepse.getCompanyList();
  const summary = await nepse.getSummary();

  // With args
  const details = await nepse.getCompanyDetails('NABIL');
  const floors = await nepse.getFloorSheetOf('NABIL', '2024-12-11');

  console.log(companies.length, summary.length, details?.symbol, floors.length);
})();
```

TypeScript usage:

```ts
import { NepseNode, CompanyBasicInfo } from '@writeshh/nepse-sdk';

const nepse = new NepseNode();

async function main() {
  const companies: CompanyBasicInfo[] = await nepse.getCompanyList();
  console.log(companies[0].symbol);
}

main();
```

Available methods (mirrors upstream):

- No-arg: `getCompanyList`, `getSecurityList`, `getSectorScrips`, `getLiveMarket`, `getPriceVolume`, `getSummary`, `getTopTenTradeScrips`, `getTopTenTransactionScrips`, `getTopTenTurnoverScrips`, `getSupplyDemand`, `getTopGainers`, `getTopLosers`, `isNepseOpen`, `getNepseIndex`, `getNepseSubIndices`, `getDailyNepseIndexGraph`, `getDailySensitiveIndexGraph`, `getDailyFloatIndexGraph`, `getDailySensitiveFloatIndexGraph`, `getDailyBankSubindexGraph`, `getDailyDevelopmentBankSubindexGraph`, `getDailyFinanceSubindexGraph`, `getDailyHotelTourismSubindexGraph`, `getDailyHydroSubindexGraph`, `getDailyInvestmentSubindexGraph`, `getDailyLifeInsuranceSubindexGraph`, `getDailyManufacturingSubindexGraph`, `getDailyMicrofinanceSubindexGraph`, `getDailyMutualfundSubindexGraph`, `getDailyNonLifeInsuranceSubindexGraph`, `getDailyOthersSubindexGraph`, `getDailyTradingSubindexGraph`.
- With args: `getFloorSheetOf(symbol, businessDate)`, `getCompanyDetails(symbol)`, `getDailyScripPriceGraph(symbol)`, `getCompanyPriceVolumeHistory(symbol, startDate, endDate)`, `getSymbolMarketDepth(symbol)`.

Upstream example routes that inspired this mapping: https://github.com/basic-bgnr/NepseUnofficialApi/blob/master/example/NepseServer.py

### CLI

```
nepse-node companies
nepse-node floorsheet
nepse-node summary
nepse-node live
nepse-node depth NABIL
nepse-node company NABIL
```

### Troubleshooting

- SSL certificate errors: upstream suggests temporarily disabling TLS verification or installing missing CA certs. See their README: https://github.com/basic-bgnr/NepseUnofficialApi
- macOS PEP 668 (externally managed Python): prefer the built-in `.venv`, or use `pipx` as shown above.