myorlen-ebok-api 0.1.0__tar.gz

myorlen_ebok_api-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# credentials and personal downloads - never commit
+.env
+.env.*
+session.json
+*.pdf
+*.xlsx
+*.csv
+
+# python / tooling
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+.session/

myorlen_ebok_api-0.1.0/AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Guidance for coding agents working on this repository.
+
+## What this is
+
+`myorlen-ebok-api`: an unofficial Python SDK + CLI for the myORLEN gas eBOK
+(https://ebok.myorlen.pl; previously PGNiG eBOK at ebok.pgnig.pl). The portal is a React SPA over a JSON API
+on the same host; the SDK logs in with e-mail + password, keeps the returned token and calls
+the same endpoints. **API.md is the endpoint reference**: read it before touching the client,
+and update it whenever you learn something new about the site.
+
+## Layout
+
+```
+src/myorlen_ebok_api/
+  client.py      MyorlenClient: login, token handling, one method per feature (I/O only)
+  parsers.py     pure functions JSON -> models; all field names of the API live here
+  models.py      dataclasses (Decimal money, date dates), InvoiceFilter enum, to_jsonable()
+  exceptions.py  MyorlenError > AuthenticationError | ApiError | ParseError | NotFoundError
+  cli.py         `myorlen-ebok-api` argparse CLI, JSON on stdout
+tests/
+  fixtures/      ANONYMISED captures of real API responses
+  test_parsers.py  parsers against fixtures
+  test_client.py   client flows with HTTP mocked by `responses` (asserts request params too)
+  test_cli.py      CLI end to end with mocked HTTP
+  test_live.py     read-only checks against the real site, skipped unless MYORLEN_LIVE=1
+```
+
+## Commands
+
+```bash
+uv sync                                   # install (uses uv.lock)
+uv run pytest                             # offline test suite, must stay green
+uv run ruff check . && uv run ruff format --check .
+uv run mypy                               # strict mode on src/
+MYORLEN_LIVE=1 uv run pytest -m live        # needs MYORLEN_USER / MYORLEN_PASS (env or .env)
+uv run myorlen-ebok-api --help              # CLI
+```
+
+Add dependencies with `uv add` / `uv add --dev` so `uv.lock` stays in sync. CI runs ruff,
+mypy and pytest on Python 3.10–3.13 (`.github/workflows/ci.yml`).
+
+## How a feature works (pattern to follow)
+
+1. Find the route name in the web bundle (`https://ebok.myorlen.pl/static/js/main.js`): the
+   route table is `var H={auth:{…},crm:{…}}`, call sites look like
+   `Ct.getData("get_invoices_v2",{pageNumber:1,pageSize:12})` or `Ct.get("crm.get_ppg_list")`.
+2. Call it through `MyorlenClient._get()` (adds `api-version=3.0` and the `AuthToken` header,
+   re-logs in once on 401, raises `ApiError` on a non-zero `Code`) or `_download()` for files.
+3. Parse with a pure function in `parsers.py` into a dataclass from `models.py`.
+
+Keep I/O in `client.py` and parsing in `parsers.py`. New parsers get a fixture + test in
+`test_parsers.py`; new client methods get a `responses` test that also asserts the query sent
+(see existing tests).
+
+## Site quirks worth knowing
+
+- Every call needs `api-version=3.0`; the token goes in the `AuthToken` header, not a cookie.
+- Wrong credentials give `403` with an empty body, not a JSON error.
+- The token expires after about an hour (sliding, see `TokenExpireDateUtc` in every answer);
+  the SDK caches it in the session file with a stable `DeviceId`.
+- `get-user-data` may answer `Code: 1` on success.
+- `get-invoices-v2` rejects `type=` with 400; use the boolean filters (API.md).
+- `PdfExists` in invoice lists is always false; ask the PDF endpoint directly. Interest-note PDFs
+  often come back as `text/plain` "Brak podglądu PDF…" instead of a PDF.
+- `get-interest-note-details` uses different field names than invoices (`DocumentNumber`,
+  `DateCreated`, `DatePaymentDeadline`).
+
+## Releasing
+
+Releases go to PyPI from GitHub Actions (`.github/workflows/release.yml`) via trusted
+publishing; there is no token to manage.
+
+1. Bump the version: `uv version --bump patch` (or `minor` / `major`); this updates `pyproject.toml` and `uv.lock`.
+2. Commit, then tag and push: `git tag v$(uv version --short) && git push && git push --tags`.
+3. The workflow runs CI, checks the tag matches the version, builds and smoke-tests the wheel,
+   publishes to https://pypi.org/project/myorlen-ebok-api/ and creates a GitHub release with the files attached.
+
+PyPI versions can never be re-uploaded, so a broken release needs a new version number.
+
+## Safety rules
+
+- **Never commit personal data.** `.env` holds real credentials and is gitignored. Fixtures must
+  be anonymised: replace names, addresses, client / agreement / PPG / meter numbers, e-mails,
+  phone, PESEL, IBANs, document numbers, UUIDs and tokens before saving into `tests/fixtures/`.
+  Grep the fixtures for the real values before committing.
+- Live exploration is read-only. Do not call payment endpoints (`pay-for-*`), reading
+  submission (`add-ppg-reading*`, `cancel-reading`), contact forms, agreement changes, e-invoice
+  toggles or account settings. If the SDK ever exposes a write endpoint, test it with mocks only.
+- Keep request volume low when exploring (one login, reuse the token).

myorlen_ebok_api-0.1.0/API.md

@@ -0,0 +1,142 @@
+# myORLEN eBOK (ebok.myorlen.pl, formerly PGNiG eBOK): reverse-engineered API reference
+
+Mapped in November 2026 against a live household account (one gas agreement, tariff W-2.1)
+and the web app bundle (`/static/js/main.js?v=1.1646`). Unofficial: the operator can change
+any of this without notice. Implemented in `src/myorlen_ebok_api/client.py` (HTTP) and
+`src/myorlen_ebok_api/parsers.py` (JSON parsing). All example values below are fake.
+
+> **Host.** `https://ebok.pgnig.pl/` now redirects (301) to `https://ebok.myorlen.pl/`.
+> Only the new host is used.
+
+## Architecture
+
+- `ebok.myorlen.pl` serves a **React SPA**; its JSON API lives on the same origin under
+  `/auth/…`, `/crm/…`, `/notification/…`, `/contact/…`, `/agreements/…`, `/cms/…`.
+  The bundle has the full route table (`var H={auth:{login:"/auth/login",…},crm:{…}}`).
+- Every request carries the query parameter **`api-version=3.0`**.
+- Authenticated requests send the token in the **`AuthToken`** request header (no cookies needed).
+- JSON is PascalCase. Every answer has an envelope:
+  `Code` (0 = OK), `Message`, `DisplayToEndUser`, `EndUserMessage`, `TokenExpireDate`,
+  `TokenExpireDateUtc` (sliding token expiry), `ConfigUpdateDateUtc`.
+  `crm/get-user-data` can answer `Code: 1` on success (the web app treats it as 0).
+- Timestamps: `2026-10-27T00:00:00.000000Z`. Query dates are sent as `Date.toISOString()`,
+  e.g. `2025-01-01T00:00:00.000Z`. Amounts are JSON numbers (PLN), volumes in m³, energy in kWh.
+- Missing / invalid token → `401 {"Message": "Authorization has been denied for this request."}`.
+- Bad request parameters → `400` with `Code: 1`.
+
+## Authentication
+
+`POST /auth/login?api-version=3.0`, JSON body:
+
+```json
+{"Identificator": "you@example.com", "AccessPin": "password",
+ "DeviceType": "Web", "DeviceId": "<uuid>", "DeviceName": "…"}
+```
+
+Success → `200` with `Token`, `DateExpirationUtc` (≈1 h), `AutomaticLoginToken` (for
+`/auth/login-automatic-token`, "remember me"), flags (`NewUser`, `ForceChangePasswordByInvalidPolicy`, …).
+Wrong credentials → `403` with an empty body. Other failures carry `Code`: 1011 unauthorised
+device, 1015 user not found, 1018 not activated, 1025 temporarily blocked (5 minutes).
+No captcha on this endpoint (the site has a reCAPTCHA key, used by other forms).
+
+`DeviceId` shows up in the account's device list (`/auth/get-devices`); the SDK keeps it stable
+in the session file. Logout: `POST /auth/logout` with `{}` and the `AuthToken` header.
+
+The site also has an OpenID flow (`/auth/oid/init-login` → `RedirectUrl`), used for accounts
+migrated to the shared ORLEN identity; the SDK uses the classic login above.
+
+## Endpoints (all `GET`, all need `AuthToken`)
+
+### Account
+
+| Endpoint | Params | Response |
+|---|---|---|
+| `/crm/get-user-data` | – | `Email`, `FirstName`, `LastName`, `Pesel` (masked `800********`), `Nip`, `Saldo`, `AmountToPay`, `Billing`, `HasPrepaid`, `Acceptances[]` (consent texts), … |
+| `/auth/get-related-accounts` | – | `RelatedAccounts[]`: `PublicId`, `ClientNumber`, `Current`, `ClientName`, `Pesel` |
+| `/crm/get-other-accounts` | – | `Results[]`: other eBOK logins for the same PESEL (masked e-mail) |
+| `/crm/get-billing-summary` | – | `{Status: "Paid", Value: null}` (dashboard headline) |
+| `/crm/get-agreements` | – | `Agreements[]` (active) |
+| `/crm/get-all-agreements` | – | `Agreements[]` incl. inactive |
+| `/crm/get-agreement-details` | `agreementNumber`, `clientNumber` | `{Agreement: {...}}`, superset of the list item (+ `AddressForCorrespondence`, `FirstName`, `LastName`, `IsOwner`, `NotExpiredChanges`) |
+| `/crm/get-ppg-list` | – | `PpgList[]`: `IdPPG`, `MeterNumber`, `Address`, `ReadingDateUtc`, `ReadingValue`, `ContractNumber`, `ClientNumber`, `Tariff`, `IdLocal`, `HasHistory`, `AddReadingMode`, … |
+
+Agreement item: `Type` (`PPG` gas), `AgreementNumber`, `ClientNumber`, `PpNumber` (PPG
+number), `Address` / `ClientAddress` / `InvoiceAddress` (`Ulica`, `UlicaTyp`, `NrBudynku`,
+`NrLokalu`, `KodPocztowy`, `Miejscowosc`), `Active`, `StartDate`, `EndDate`, `ClientName`,
+`Iban` (individual account to pay into), `EcoInvoice`, `Saldo`, `Region`, `Tariff`,
+`AgreementName`, `Owner`, `CollectionPoints[]` (`NumberOSD`, `IdCRD`, `Address*`, `Billing`).
+
+### Invoices
+
+`/crm/get-invoices-v2`: `pageNumber`, `pageSize` (web app: 12; 200 for the payment dialog),
+optional filters:
+
+| Param | Meaning |
+|---|---|
+| `dateFrom`, `dateTo` | ISO timestamps, filter by issue date |
+| `agreementNumber`, `clientNumber` | restrict to an agreement / customer |
+| `paid=false` | unpaid only |
+| `afterDeadline=true` | overdue |
+| `loadAfter30Days=true` | forecast instalments due in more than 30 days |
+| `excludeAfterDeadline=true` | not overdue ("upcoming" tab, combined with `paid=false`) |
+| `beforeEndDate=true`, `forecastToPay=true`, `isHomeAssistant=true` | used by other screens |
+
+`type=…` answers 400. Response: `InvoicesList[]`, `HasMoreRecords`, `AllowLoadAfter30Days`,
+`AllowLoadAllInvoices`, `HasNonPaidForecast`. Item: `Number`, `Date`, `SellDate`,
+`StartDate`/`EndDate` (billing period), `PayingDeadlineDate`, `GrossAmount`, `AmountToPay`,
+`IsPaid`, `Status` (`Posted`), `Type`, `TempType` (`R` settlement, `P`/`B` forecast
+instalments, empty for notes), `IsInterestNote`, `IsCreditNote`, `Correction`,
+`AgreementNumber`, `IdPP`, `WearKWH`, `WearM3`, `Iban`, `PDFPrintAllowed`, `PdfExists`
+(always false in practice; use the PDF endpoint).
+
+| Endpoint | Params | Response |
+|---|---|---|
+| `/crm/get-invoice-details` | `invoiceNumber`, `excludePdfCheck=true` | `{Invoice: {...}}` + `Address`, `PdfVisibility`, `AutomaticPaymentDate`, `IsSubscribed` |
+| `/crm/get-interest-note-details` | `interestNoteNumber`, `excludePdfCheck=true` | `{InterestNote: {DocumentNumber, DateCreated, DatePaymentDeadline, DateSell, GrossAmount, AmountToPay, IsPaid, …}}` |
+| `/crm/get-invoice-pdf-visibility` | `invoiceNumber` | `{Visibility: "PdfVisible"}` |
+| `/crm/get-invoice-pdf` | `invoiceNumber`, `mode=partial` | `application/pdf`, `Content-Disposition: inline; filename="p/…pdf"` |
+| `/crm/get-interest-note-pdf` | `interestNoteNumber`, `mode=partial` | PDF, or `text/plain` "Brak podglądu PDF dla wybranej faktury." |
+
+### Payments & history
+
+| Endpoint | Params | Response |
+|---|---|---|
+| `/crm/get-client-payments` | – | `Payments[]`: `DocumentDate`, `DocumentNumber` (`KP/RAP/…`), `Value`, `PaymentType` (`P`), `Description`, `ClientNumber`, `Transfer` |
+| `/crm/get-compensations` | – | `Compensations[]` (empty on the test account) |
+| `/crm/get-refunds` | – | `Refunds[]` (empty on the test account) |
+| `/crm/get-account-history` | `pageNumber`, `pageSize` | `HistoryList[]`: `Date`, `Type` ("Zapłata za fakturę", …), `Description` |
+
+### Readings & consumption
+
+| Endpoint | Params | Response |
+|---|---|---|
+| `/crm/get-all-ppg-readings-for-meter` | `idPpg`, `pageNumber`, `pageSize`, `ignoreStartDate=true` or `dateFrom`+`dateTo`, optional `type` | `MeterReadings[]`, `HasMoreRecords` |
+| `/crm/get-ppg-readings-dates` | `idPpg` | `MeterReadingsDates[]` |
+| `/crm/get-ppgs-readings-file` | `ppgIds` | xlsx attachment `Readings_YYYY_MM_DD_HH_MM_SS.xlsx` |
+| `/crm/get-monthly-wear-chart-data` | `ppgIds`, `pageNumber`, `pageSize` | `ChartData: {"październik_2026": [{Label, Year, Value, Wear, Type, ReadingDateUtc, Period, ZoneLabel}]}` |
+| `/crm/get-yearly-wear-chart-data` | `ppgIds` | `ComparisonPercent`, `IsPlusSignForPercent`, `ThisYearData[]` / `PreviousYearData[]`: `{Year, WearByYear, ChartItems[]}` |
+| `/crm/get-wear-comparison-chart-data` | period params | not used |
+
+Reading: `ReadingDateUtc`, `Value` (meter, m³), `Wear` (consumption since previous), `Value2/3`,
+`Wear2/3` (multi-register meters), `Type` (`Real`, …), `Status` (`ROZL` settled,
+`ANUL_KLIENT` cancelled by customer), `MeterNumber`, `PpId`, `ClientNumber`, `CanBeCancelled`.
+The list only covers the current billing system's history (two readings on the test account).
+
+### Messages & settings
+
+| Endpoint | Params | Response |
+|---|---|---|
+| `/notification/get-notifications` | – | `Notifications[]`: `Id`, `Title`, `Body`, `DateCreatedUtc`, `Type` (`Invoices`, …), `ObjectId` (invoice number) |
+| `/notification/get-unreaded-count` | – | `{UnreadedCount}` |
+| `/notification/email-settings` | – | `{Settings: {System, Invoices}}` |
+| `/contact/get-contact-history-v2` | `pageIndex`, `pageSize` | `Contacts[]`, `AllowLoadMore` (item shape not observed: empty on the test account) |
+| `/contact/get-contact-message` | `PublicId` | `Answers`, `ContactMessage` (not used) |
+
+## Write endpoints (not used by the SDK)
+
+Mapped from the bundle only; never called while exploring:
+`POST /crm/add-ppg-reading-v2` (submit a reading), `/crm/cancel-reading`,
+`/crm/pay-for-invoice-v2` / `pay-for-multi-invoice-v2` (payments), `/notification/remove`,
+`/agreements/set-agreement-name`, `/agreements/set-agreement-color`, `/cms/order-einvoice`,
+`/crm/disable-eco-invoice`, `/contact/send-message-v2`, `/auth/change-password`,
+`/auth/change-email-v2`, `/agreements/change-tariff`, `/agreements/send-terminate-agreement`.

myorlen_ebok_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacek Grela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

myorlen_ebok_api-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: myorlen-ebok-api
+Version: 0.1.0
+Summary: Unofficial Python SDK and CLI for the myORLEN gas eBOK (ebok.myorlen.pl, formerly PGNiG eBOK): agreements, invoices, PDFs, payments, meter readings, consumption.
+Project-URL: Homepage, https://github.com/grelade/myorlen-ebok-api
+Project-URL: Issues, https://github.com/grelade/myorlen-ebok-api/issues
+Author-email: Jacek Grela <jacekgrela@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ebok,gas,invoices,myorlen,pgnig,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Polish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# myorlen-ebok-api
+
+Unofficial Python SDK and command-line client for the **myORLEN eBOK**
+([ebok.myorlen.pl](https://ebok.myorlen.pl)), the customer portal of the Polish gas retailer myORLEN.
+
+> **Previous name: PGNiG eBOK.** The portal used to be the eBOK of PGNiG Obrót Detaliczny at
+> `ebok.pgnig.pl`; after the rebranding to myORLEN that address redirects to `ebok.myorlen.pl`.
+> Existing PGNiG eBOK logins work unchanged.
+
+It logs in with your eBOK e-mail and password and gives typed access to what the portal shows:
+
+- user data, balance and amount to pay, linked customer accounts
+- supply agreements with tariff, address, IBAN, collection points; agreement details
+- invoices, forecast instalments and interest notes (filters, paging), invoice details, **PDF downloads**
+- payments booked on the account, eBOK action history
+- gas meter points (PPG) with the last reading; reading history, Excel export
+- consumption per settlement period and year-over-year comparison
+- notifications, contact-form history, e-mail notification settings
+
+> Not affiliated with PGNiG or ORLEN. The portal has no public API; this library calls the
+> same JSON endpoints the web app uses and can break when they change.
+> See [API.md](API.md) for the reverse-engineered endpoint reference.
+
+## Install
+
+```bash
+pip install myorlen-ebok-api        # or: uv add myorlen-ebok-api
+```
+
+Latest unreleased code: `pip install git+https://github.com/grelade/myorlen-ebok-api`.
+
+Requires Python 3.10+.
+
+## Command line
+
+```bash
+export MYORLEN_USER=you@example.com MYORLEN_PASS='…'     # or put them in ./.env (PGNIG_USER / PGNIG_PASS also work)
+uvx myorlen-ebok-api balance
+```
+
+| Command | Output |
+|---|---|
+| `user`, `balance`, `accounts` | user data, balance / amount to pay / payment status, linked accounts |
+| `agreements [--all]` / `agreement [NUMBER]` | supply agreements / details of one |
+| `meter-points` | meter points (PPG) with the last reading |
+| `invoices [--from D] [--to D] [--filter all\|unpaid\|overdue\|forecast] [--agreement N] [--limit N]` | invoices |
+| `invoice NUMBER` | invoice or interest-note details |
+| `pdf NUMBER [--out DIR_OR_FILE]` | save an invoice PDF |
+| `payments`, `history [--limit N]` | payments, eBOK action history |
+| `readings [--from D] [--to D] [--xlsx PATH]` | meter readings (m³) or the Excel export |
+| `monthly [--months N]`, `yearly` | consumption charts |
+| `notifications`, `contacts`, `email-settings` | messages and settings |
+
+Output is JSON (amounts are strings to keep `Decimal` precision). Global options: `--ppg ID`
+(needed only for accounts with several meter points) and `--session-file PATH` (default
+`~/.cache/myorlen-ebok-api/session.json`; the token is reused so repeated runs don't log in again).
+
+## Library
+
+```python
+from myorlen_ebok_api import MyorlenClient
+
+with MyorlenClient("you@example.com", "secret", session_file="~/.cache/myorlen-ebok-api/session.json") as c:
+    user = c.get_user()
+    print(user.balance, user.amount_to_pay)
+
+    for inv in c.iter_invoices(filter="unpaid"):
+        print(inv.number, inv.gross_amount, inv.due_date)
+
+    latest = next(c.iter_invoices())
+    pdf = c.download_invoice(latest)  # DownloadedFile(filename, content_type, content)
+    open(pdf.filename, "wb").write(pdf.content)
+
+    for r in c.iter_readings():
+        print(r.date, r.value, r.consumption, "m³")
+```
+
+All methods: `get_user`, `get_related_accounts`, `get_billing_summary`, `get_agreements`,
+`get_agreement`, `get_meter_points`, `get_meter_point`, `get_invoices`, `iter_invoices`,
+`get_invoice`, `download_invoice`, `get_payments`, `get_account_history`, `get_readings`,
+`iter_readings`, `get_reading_dates`, `export_readings`, `get_monthly_consumption`,
+`get_yearly_consumption`, `get_notifications`, `get_unread_count`, `get_email_settings`,
+`get_contact_history`, `iter_contact_history`; session: `login`, `logout`, `save_session`.
+
+Errors derive from `myorlen_ebok_api.MyorlenError` (`AuthenticationError`, `ApiError`, `ParseError`,
+`NotFoundError`).
+
+## Development
+
+```bash
+uv sync                          # creates .venv with dev tools
+uv run pytest                    # offline tests (HTTP mocked, anonymised fixtures)
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+MYORLEN_LIVE=1 uv run pytest -m live   # read-only smoke tests against the real site (.env credentials)
+```
+
+See [AGENTS.md](AGENTS.md) for the project layout and conventions.
+
+## License
+
+MIT

myorlen_ebok_api-0.1.0/README.md

@@ -0,0 +1,101 @@
+# myorlen-ebok-api
+
+Unofficial Python SDK and command-line client for the **myORLEN eBOK**
+([ebok.myorlen.pl](https://ebok.myorlen.pl)), the customer portal of the Polish gas retailer myORLEN.
+
+> **Previous name: PGNiG eBOK.** The portal used to be the eBOK of PGNiG Obrót Detaliczny at
+> `ebok.pgnig.pl`; after the rebranding to myORLEN that address redirects to `ebok.myorlen.pl`.
+> Existing PGNiG eBOK logins work unchanged.
+
+It logs in with your eBOK e-mail and password and gives typed access to what the portal shows:
+
+- user data, balance and amount to pay, linked customer accounts
+- supply agreements with tariff, address, IBAN, collection points; agreement details
+- invoices, forecast instalments and interest notes (filters, paging), invoice details, **PDF downloads**
+- payments booked on the account, eBOK action history
+- gas meter points (PPG) with the last reading; reading history, Excel export
+- consumption per settlement period and year-over-year comparison
+- notifications, contact-form history, e-mail notification settings
+
+> Not affiliated with PGNiG or ORLEN. The portal has no public API; this library calls the
+> same JSON endpoints the web app uses and can break when they change.
+> See [API.md](API.md) for the reverse-engineered endpoint reference.
+
+## Install
+
+```bash
+pip install myorlen-ebok-api        # or: uv add myorlen-ebok-api
+```
+
+Latest unreleased code: `pip install git+https://github.com/grelade/myorlen-ebok-api`.
+
+Requires Python 3.10+.
+
+## Command line
+
+```bash
+export MYORLEN_USER=you@example.com MYORLEN_PASS='…'     # or put them in ./.env (PGNIG_USER / PGNIG_PASS also work)
+uvx myorlen-ebok-api balance
+```
+
+| Command | Output |
+|---|---|
+| `user`, `balance`, `accounts` | user data, balance / amount to pay / payment status, linked accounts |
+| `agreements [--all]` / `agreement [NUMBER]` | supply agreements / details of one |
+| `meter-points` | meter points (PPG) with the last reading |
+| `invoices [--from D] [--to D] [--filter all\|unpaid\|overdue\|forecast] [--agreement N] [--limit N]` | invoices |
+| `invoice NUMBER` | invoice or interest-note details |
+| `pdf NUMBER [--out DIR_OR_FILE]` | save an invoice PDF |
+| `payments`, `history [--limit N]` | payments, eBOK action history |
+| `readings [--from D] [--to D] [--xlsx PATH]` | meter readings (m³) or the Excel export |
+| `monthly [--months N]`, `yearly` | consumption charts |
+| `notifications`, `contacts`, `email-settings` | messages and settings |
+
+Output is JSON (amounts are strings to keep `Decimal` precision). Global options: `--ppg ID`
+(needed only for accounts with several meter points) and `--session-file PATH` (default
+`~/.cache/myorlen-ebok-api/session.json`; the token is reused so repeated runs don't log in again).
+
+## Library
+
+```python
+from myorlen_ebok_api import MyorlenClient
+
+with MyorlenClient("you@example.com", "secret", session_file="~/.cache/myorlen-ebok-api/session.json") as c:
+    user = c.get_user()
+    print(user.balance, user.amount_to_pay)
+
+    for inv in c.iter_invoices(filter="unpaid"):
+        print(inv.number, inv.gross_amount, inv.due_date)
+
+    latest = next(c.iter_invoices())
+    pdf = c.download_invoice(latest)  # DownloadedFile(filename, content_type, content)
+    open(pdf.filename, "wb").write(pdf.content)
+
+    for r in c.iter_readings():
+        print(r.date, r.value, r.consumption, "m³")
+```
+
+All methods: `get_user`, `get_related_accounts`, `get_billing_summary`, `get_agreements`,
+`get_agreement`, `get_meter_points`, `get_meter_point`, `get_invoices`, `iter_invoices`,
+`get_invoice`, `download_invoice`, `get_payments`, `get_account_history`, `get_readings`,
+`iter_readings`, `get_reading_dates`, `export_readings`, `get_monthly_consumption`,
+`get_yearly_consumption`, `get_notifications`, `get_unread_count`, `get_email_settings`,
+`get_contact_history`, `iter_contact_history`; session: `login`, `logout`, `save_session`.
+
+Errors derive from `myorlen_ebok_api.MyorlenError` (`AuthenticationError`, `ApiError`, `ParseError`,
+`NotFoundError`).
+
+## Development
+
+```bash
+uv sync                          # creates .venv with dev tools
+uv run pytest                    # offline tests (HTTP mocked, anonymised fixtures)
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+MYORLEN_LIVE=1 uv run pytest -m live   # read-only smoke tests against the real site (.env credentials)
+```
+
+See [AGENTS.md](AGENTS.md) for the project layout and conventions.
+
+## License
+
+MIT

myorlen_ebok_api-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "myorlen-ebok-api"
+version = "0.1.0"
+description = "Unofficial Python SDK and CLI for the myORLEN gas eBOK (ebok.myorlen.pl, formerly PGNiG eBOK): agreements, invoices, PDFs, payments, meter readings, consumption."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jacek Grela", email = "jacekgrela@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["pgnig", "myorlen", "ebok", "gas", "invoices", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Natural Language :: Polish",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://github.com/grelade/myorlen-ebok-api"
+Issues = "https://github.com/grelade/myorlen-ebok-api/issues"
+
+[project.scripts]
+myorlen-ebok-api = "myorlen_ebok_api.cli:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "responses>=0.25",
+    "ruff>=0.6",
+    "types-requests>=2.31",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "API.md", "AGENTS.md", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003"]  # Polish text contains look-alike characters by design
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["responses.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = ["live: hits the real ebok.myorlen.pl (needs MYORLEN_USER/MYORLEN_PASS and MYORLEN_LIVE=1)"]

myorlen_ebok_api-0.1.0/src/myorlen_ebok_api/__init__.py

@@ -0,0 +1,66 @@
+"""Unofficial Python SDK for the myORLEN gas eBOK (ebok.myorlen.pl, formerly PGNiG eBOK)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import BASE_URL, MyorlenClient
+from .exceptions import ApiError, AuthenticationError, MyorlenError, NotFoundError, ParseError
+from .models import (
+    Address,
+    Agreement,
+    BillingSummary,
+    CollectionPoint,
+    ConsumptionEntry,
+    ContactMessage,
+    DownloadedFile,
+    EmailSettings,
+    HistoryEntry,
+    Invoice,
+    InvoiceFilter,
+    InvoicePage,
+    MeterPoint,
+    Notification,
+    Payment,
+    Reading,
+    ReadingPage,
+    RelatedAccount,
+    User,
+    YearConsumption,
+    YearlyConsumption,
+)
+
+try:
+    __version__ = version("myorlen-ebok-api")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "BASE_URL",
+    "Address",
+    "Agreement",
+    "ApiError",
+    "AuthenticationError",
+    "BillingSummary",
+    "CollectionPoint",
+    "ConsumptionEntry",
+    "ContactMessage",
+    "DownloadedFile",
+    "EmailSettings",
+    "HistoryEntry",
+    "Invoice",
+    "InvoiceFilter",
+    "InvoicePage",
+    "MeterPoint",
+    "MyorlenClient",
+    "MyorlenError",
+    "NotFoundError",
+    "Notification",
+    "ParseError",
+    "Payment",
+    "Reading",
+    "ReadingPage",
+    "RelatedAccount",
+    "User",
+    "YearConsumption",
+    "YearlyConsumption",
+    "__version__",
+]

myorlen_ebok_api-0.1.0/src/myorlen_ebok_api/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())