Metadata-Version: 2.4
Name: ayush-ipo
Version: 0.1.4
Summary: CLI app to apply for IPOs and manage MeroShare accounts across multiple users!
Project-URL: Repository, https://github.com/ayush57joshi/NEPSE-IPO
Author-email: Ayush Joshi <ayush57.joshi@gmail.com>
License-File: LICENSE
Keywords: ipo,meroshare,nepse,tms
Requires-Python: <3.13,>=3.9
Requires-Dist: cryptography>=41.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tenacity>=8.2.2
Description-Content-Type: text/markdown

<div align="center">

# NEPSE IPO

![Release Pipeline](https://github.com/ayush57joshi/NEPSE-IPO/actions/workflows/release.yml/badge.svg)
![PyPI - Version](https://img.shields.io/pypi/v/ayush-ipo)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ayush-ipo)

A CLI application written in Python to manage MeroShare accounts — apply for IPOs, track portfolios, and check allotment results across multiple accounts simultaneously.

</div>

---

## Features

- Apply for IPOs across multiple MeroShare accounts in one command
- Track portfolio value and performance per account or combined
- Check live IPO application status and allotment results
- Auto-sync account data once per day on first login
- Export portfolio, application history, and transactions to CSV
- Tag and filter accounts for selective operations
- Telegram notifications for IPO applications
- Encrypted local storage for all account credentials

---

## Installation

Install Python 3.9 or later, then install via pipx (recommended):

```
pipx install ayush-ipo
```

Or using pip:

```
pip install ayush-ipo
```

Launch from the command line:

```
ipo
```

---

## First Launch

On the first launch, the application will ask you to set a master password. This password encrypts your stored account credentials locally — it is not your MeroShare password. You will be asked for it every time you launch the application.

Up to 3 password attempts are allowed before the application exits.

---

## Commands

| Command               | Description                                                        |
| --------------------- | ------------------------------------------------------------------ |
| `add`                 | Add a MeroShare account                                            |
| `remove`              | Remove an account                                                  |
| `apply`               | Apply for an open IPO across all accounts                          |
| `status`              | Check live IPO application status and allotment result             |
| `status all`          | Show full application history instead of the 5 most recent        |
| `portfolio`           | Show portfolio for a specific account                              |
| `portfolio all`       | Show combined portfolio across all accounts                        |
| `stats`               | Show IPO application statistics for all accounts                   |
| `stats {id}`          | Show detailed allotment history for a specific account             |
| `sync`                | Manually sync all account data from MeroShare                      |
| `diagnose`            | Run API checks on default account (login → details → portfolio...) |
| `diagnose all`        | Run API checks for all accounts                                    |
| `diagnose {id}`       | Run API checks for one account                                     |
| `export portfolio`    | Export portfolio holdings to CSV                                   |
| `export applications` | Export IPO application history to CSV                              |
| `export transactions {id}` | Export live transaction CSV for a specific account          |
| `transactions {id} {script}` | Show transaction history for one script (e.g. NRN)       |
| `transactions {id} all` | Show full transaction history for one account                    |
| `tag`                 | Assign a tag to an account for grouping                            |
| `select {tag}`        | Filter active accounts by tag for subsequent commands              |
| `select all`          | Clear tag filter and use all accounts                              |
| `list account(s)`     | Show all accounts                                                  |
| `list account(s) full`| Show all accounts including passwords and PINs                     |
| `list capital(s)`     | Show capital/broker list                                           |
| `change lock`         | Change the master password                                         |
| `change password`     | Change a MeroShare account password                                |
| `change export`       | Change the CSV export directory                                    |
| `loglevel {critical|error|warning|info|debug|all}` | Set logging verbosity              |
| `telegram enable`     | Enable Telegram notifications                                      |
| `telegram disable`    | Disable Telegram notifications                                     |
| `clear`               | Clear terminal screen                                              |
| `help`                | Show available commands                                            |
| `help {command}`      | Show detailed help for a specific command                          |
| `exit`                | Exit the application                                               |

**Aliases:** `result` / `results` → `status` · `stat` → `stats` · `transaction` → `transactions` · `cls` / `c` → `clear` · `q` / `x` → `exit`

---

## Usage

### Adding an account

```
IPO > add
Enter DMAT (16 digits): 1234567891234567
Enter Meroshare Password: ********
Enter CRN Number: 02-R00222224
Enter Meroshare PIN: ****
```

You can also pass all arguments inline:

```
IPO > add 1234567891234567 myp@ssw0rd 02-R00222224 1234
```

Press **ESC** at any field to cancel. All fields are validated immediately — DMAT must be exactly 16 digits and PIN must be numeric.

---

### Applying for an IPO

```
IPO > apply
```

A table of open issues will be displayed. Enter the Share ID and the number of units to apply. The application will apply across all active accounts and display a per-account result table.

---

### Checking IPO status and results

```
IPO > status
```

Displays the 5 most recent applications. Enter a Share ID to fetch live status and allotment result for all accounts. You can enter multiple Share IDs in one session — press **ESC** to exit, or type any valid command to switch directly to it.

To view the full application history:

```
IPO > status all
```

Allotted column values:

| Value           | Meaning                                      |
| --------------- | -------------------------------------------- |
| `Yes`           | Allotted — result has been published         |
| `No`            | Not allotted — result has been published     |
| `Not Published` | Result has not been published yet            |
| `N/A`           | This account did not apply for this offering |

---

### Viewing portfolio

```
IPO > portfolio
```

Select an account by ID. You can view multiple accounts without re-entering the command — press **ESC** to exit.

To view a combined portfolio across all accounts:

```
IPO > portfolio all
```

---

### Statistics

```
IPO > stats
```

Shows a per-account breakdown of total applied, rejected, un-allotted, allotted, and pending IPOs along with the allotment success rate.

To view the full allotment history for a specific account including invested amount and current portfolio value:

```
IPO > stats 1
```

---

### Exporting data

On first export, the application will ask you to choose a directory. This is saved for future exports. To change it later:

```
IPO > change export
```

Export portfolio:

```
IPO > export portfolio
```

Export application history:

```
IPO > export applications
```

Export live transaction CSV for account 2:

```
IPO > export transactions 2
```

CSV files are saved as:

- `ipo_export_portfolio_{date}.csv`
- `ipo_export_applications_{date}.csv`
- `ipo_export_transactions_{account_name}_{date}.csv`

If the export directory is missing, you'll be prompted to set it again.

---

### Transaction history

Show one script's history for account 2:

```
IPO > transactions 2 NRN
```

Show all scripts for account 2:

```
IPO > transactions 2 all
```

---

### Diagnostics

Run endpoint checks in sequence and stop at the first failing step:

```
IPO > diagnose
IPO > diagnose all
IPO > diagnose 2
```

Checks include: login, account details, portfolio, applicable issues, and logout.

---

### Tagging and filtering accounts

Assign a tag to group accounts:

```
IPO > tag
```

Filter all subsequent commands to only operate on tagged accounts:

```
IPO > select family
```

Return to using all accounts:

```
IPO > select all
```

The active tag filter is shown in the prompt:

```
IPO (family) >
```

---

### Auto-sync

The application automatically syncs portfolio and application data from MeroShare on the first login of each day. Subsequent logins the same day skip the sync to avoid unnecessary API calls. To force a sync at any time:

```
IPO > sync
```

---

## Data & Privacy

All account credentials are encrypted using Fernet symmetric encryption and stored locally. No data is sent anywhere except to the official MeroShare API. A local sync file is created alongside the data file to track sync state and export preferences — this file is not encrypted and should not be committed to version control.

---

## Requirements

- Python >= 3.9
- Active MeroShare account(s)
- CRN number for each account

---

## Credits

Originally developed by [Arpan Koirala](https://github.com/arpandaze).
Extended and redesigned by [Ayush Joshi](https://github.com/ayush57joshi) (2026).

---

## License

MIT License — see [LICENSE](LICENSE) for details.