Metadata-Version: 2.4
Name: israeli-bank-scrapers-python
Version: 0.1.15
Summary: Python migration slice for Leumi and Isracard scrapers
Author-email: Meir Finkelstine <mfinkelstine@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/mfinkelstine/israeli-bank-scrapers
Project-URL: Repository, https://github.com/mfinkelstine/israeli-bank-scrapers
Project-URL: Issues, https://github.com/mfinkelstine/israeli-bank-scrapers/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Framework :: FastAPI
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright<2,>=1.50
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: tzdata>=2024.1
Provides-Extra: test
Requires-Dist: httpx<1,>=0.27; extra == "test"
Requires-Dist: pytest<9,>=8; extra == "test"
Requires-Dist: pytest-asyncio<1,>=0.24; extra == "test"
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

<a id="readme-top"></a>

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![MIT License][license-shield]][license-url]
[![PyPI][pypi-shield]][pypi-url]

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://github.com/mfinkelstine/israeli-bank-scrapers">
    <img src="logo.png" alt="Logo" width="80" height="80">
  </a>

  <h3 align="center">israeli-bank-scrapers-python</h3>

  <p align="center">
    Leumi bank + Isracard credit-card scraping, as a FastAPI service
    <br />
    <a href="docs/api.md"><strong>Explore the API docs »</strong></a>
    <br />
    <br />
    <a href="CURL_COMMANDS.md">curl examples</a>
    &middot;
    <a href="https://github.com/mfinkelstine/israeli-bank-scrapers/issues/new">Report Bug</a>
    &middot;
    <a href="https://github.com/mfinkelstine/israeli-bank-scrapers/issues/new">Request Feature</a>
  </p>
</div>

<!-- TABLE OF CONTENTS -->
<details>
  <summary>Table of Contents</summary>
  <ol>
    <li>
      <a href="#about-the-project">About The Project</a>
      <ul>
        <li><a href="#built-with">Built With</a></li>
        <li><a href="#scope">Scope</a></li>
      </ul>
    </li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites</a></li>
        <li><a href="#installation">Installation</a></li>
        <li><a href="#configuration">Configuration</a></li>
      </ul>
    </li>
    <li>
      <a href="#usage">Usage</a>
      <ul>
        <li><a href="#run-the-service">Run the service</a></li>
        <li><a href="#call-the-api">Call the API</a></li>
        <li><a href="#use-as-a-library">Use as a library</a></li>
      </ul>
    </li>
    <li><a href="#roadmap">Roadmap</a></li>
    <li><a href="#contributing">Contributing</a></li>
    <li><a href="#license">License</a></li>
    <li><a href="#contact">Contact</a></li>
    <li><a href="#acknowledgments">Acknowledgments</a></li>
  </ol>
</details>

<!-- ABOUT THE PROJECT -->
## About The Project

Python port of the [`israeli-bank-scrapers`](https://github.com/mfinkelstine/israeli-bank-scrapers)
TypeScript library's Leumi and Isracard scrapers, packaged as a standalone
FastAPI service rather than a Node.js library. Playwright drives a real
Chromium browser to log in and pull transactions, balances, standing
orders, loans, deposits, and mortgages (Leumi); the service preserves the
HTTP contract of the original TypeScript/Express service it replaces, so
existing callers don't need to change anything besides where they point.

**Before using this against real credentials**, read
[`docs/api.md`](docs/api.md) — what each provider needs, what every
endpoint returns, error types, and the config env vars.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Built With

* [![Python][Python.org]][Python-url]
* [![FastAPI][FastAPI.com]][FastAPI-url]
* [![Pydantic][Pydantic.dev]][Pydantic-url]
* [![Playwright][Playwright.dev]][Playwright-url]
* [![Docker][Docker.com]][Docker-url]

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Scope

Ported so far: **Leumi** (bank) and **Isracard** (credit card). The
TypeScript reference this project is porting from (`ts/`, still live in
this repo) supports many more Israeli banks and card issuers — see
[Roadmap](#roadmap). See `PROGRESS.md` for the full migration status,
architecture notes, and release process.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->
## Getting Started

### Prerequisites

* Python 3.11+
* A Chromium-capable environment — Playwright downloads its own Chromium
  build, so you just need the OS-level dependencies its installer pulls in:
  ```sh
  python -m playwright install --with-deps chromium
  ```

### Installation

To use the published package (as a service or a library):

```sh
pip install israeli-bank-scrapers-python
python -m playwright install --with-deps chromium
```

To work on the project itself (contributing, running the test suite):

```sh
git clone https://github.com/mfinkelstine/israeli-bank-scrapers.git
cd israeli-bank-scrapers
pip install -e ".[dev,test]"
python -m playwright install --with-deps chromium
```

Run the test suite:

```sh
pytest
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

### Configuration

To run real scrapes locally — either through the test suite's live tests
or the `scripts/curl-api.sh` helper behind [`CURL_COMMANDS.md`](CURL_COMMANDS.md)
— copy `.env.example` to `.env` and fill in test credentials:

```sh
cp .env.example .env
```

```env
LEUMI_USERNAME=
LEUMI_PASSWORD=
ISRACARD_ID=
ISRACARD_PASSWORD=
ISRACARD_CARD6DIGITS=
```

**This `.env` file is a local dev/test convenience only** — the deployed
service itself never reads credentials from the environment; it takes them
per-request in the request body (see [`docs/api.md`](docs/api.md)). The one
exception is `GET /healthz`'s optional deep-check config
(`HEALTHZ_COMPANY`/`HEALTHZ_USERNAME`/`HEALTHZ_ID`/`HEALTHZ_PASSWORD`/`HEALTHZ_CARD6`),
also documented there. Never commit `.env` or paste real credentials into
an issue, PR, or log.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- USAGE EXAMPLES -->
## Usage

### Run the service

```sh
uvicorn israeli_bank_scrapers.api.app:app --host 0.0.0.0 --port 3002
```

Or via Docker (installs the published PyPI package, not local source):

```sh
docker build -t israeli-bank-scrapers .
docker run -p 3002:3002 israeli-bank-scrapers
```

Endpoints: `GET /health`, `GET|POST /healthz`, `POST /scrape`,
`POST /standing-orders`, `POST /cards`, `POST /balance`, `POST /portfolio`,
`GET /openapi.json`, `GET /docs`.

### Call the API

```sh
curl -sS -X POST http://127.0.0.1:3002/scrape \
  -H "Content-Type: application/json" \
  -d '{"company": "leumi", "credentials": {"username": "...", "password": "..."}, "months": 1}'
```

_For what credentials each provider needs and what every endpoint returns,
see [`docs/api.md`](docs/api.md). For more copy-paste examples (every
endpoint, both providers), see [`CURL_COMMANDS.md`](CURL_COMMANDS.md)._

### Use as a library

```python
from israeli_bank_scrapers.browser import BrowserSession
from israeli_bank_scrapers.providers.leumi import LeumiProvider

async with BrowserSession() as page:
    provider = LeumiProvider()
    result = await provider.scrape_transactions(page, username, password, start_date=...)
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- ROADMAP -->
## Roadmap

- [x] Leumi (bank)
- [x] Isracard (credit card)
- [ ] Additional banks/card issuers from the TypeScript reference
      (`ts/src/definitions.ts`), not yet ported: Hapoalim, Beinleumi, Union,
      Amex, Visa Cal, Max, Otsar Hahayal, Discount, Mercantile, Mizrahi,
      Massad, Yahav, Behatsdaa, Beyahad Bishvilha, OneZero, Pagi

See the [open issues](https://github.com/mfinkelstine/israeli-bank-scrapers/issues)
for a full list of proposed features and known issues, and `PROGRESS.md`
for the detailed migration log.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTRIBUTING -->
## Contributing

Contributions are welcome. If you have a suggestion that would make this
better, fork the repo and open a pull request, or open an issue with the
"enhancement" tag.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- LICENSE -->
## License

Distributed under the MIT License. See `LICENSE` for more information.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTACT -->
## Contact

Meir Finkelstine - mfinkelstine@gmail.com

Project Link: [https://github.com/mfinkelstine/israeli-bank-scrapers](https://github.com/mfinkelstine/israeli-bank-scrapers)

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- ACKNOWLEDGMENTS -->
## Acknowledgments

* [israeli-bank-scrapers](https://github.com/mfinkelstine/israeli-bank-scrapers/tree/main/ts) —
  the original TypeScript library this project ports, created by Elad Shaham
  and its contributors
* [Playwright](https://playwright.dev) and [FastAPI](https://fastapi.tiangolo.com)
* [Best-README-Template](https://github.com/othneildrew/Best-README-Template) —
  this file's structure

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES -->
[contributors-shield]: https://img.shields.io/github/contributors/mfinkelstine/israeli-bank-scrapers.svg?style=for-the-badge
[contributors-url]: https://github.com/mfinkelstine/israeli-bank-scrapers/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/mfinkelstine/israeli-bank-scrapers.svg?style=for-the-badge
[forks-url]: https://github.com/mfinkelstine/israeli-bank-scrapers/network/members
[stars-shield]: https://img.shields.io/github/stars/mfinkelstine/israeli-bank-scrapers.svg?style=for-the-badge
[stars-url]: https://github.com/mfinkelstine/israeli-bank-scrapers/stargazers
[issues-shield]: https://img.shields.io/github/issues/mfinkelstine/israeli-bank-scrapers.svg?style=for-the-badge
[issues-url]: https://github.com/mfinkelstine/israeli-bank-scrapers/issues
[license-shield]: https://img.shields.io/github/license/mfinkelstine/israeli-bank-scrapers.svg?style=for-the-badge
[license-url]: https://github.com/mfinkelstine/israeli-bank-scrapers/blob/main/LICENSE
[pypi-shield]: https://img.shields.io/pypi/v/israeli-bank-scrapers-python.svg?style=for-the-badge
[pypi-url]: https://pypi.org/project/israeli-bank-scrapers-python/
[Python.org]: https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54
[Python-url]: https://www.python.org/
[FastAPI.com]: https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white
[FastAPI-url]: https://fastapi.tiangolo.com/
[Pydantic.dev]: https://img.shields.io/badge/Pydantic-E92063?style=for-the-badge&logo=pydantic&logoColor=white
[Pydantic-url]: https://docs.pydantic.dev/
[Playwright.dev]: https://img.shields.io/badge/Playwright-2EAD33?style=for-the-badge&logo=playwright&logoColor=white
[Playwright-url]: https://playwright.dev/python/
[Docker.com]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white
[Docker-url]: https://www.docker.com/
