Metadata-Version: 2.4
Name: oma-helen-cli
Version: 1.7.0
Summary: Oma Helen API library and CLI
Project-URL: Homepage, https://github.com/carohauta/oma-helen-cli
Project-URL: Repository, https://github.com/carohauta/oma-helen-cli
Project-URL: Issues, https://github.com/carohauta/oma-helen-cli/issues
Author-email: carohauta <carosoft.dev@gmail.com>
License: MIT
License-File: LICENSE
Keywords: api,cli,electricity,finland,helen
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4==4.12.3
Requires-Dist: cachetools>=5.3.3
Requires-Dist: requests>=2.28.1
Requires-Dist: soupsieve==2.5
Requires-Dist: urllib3>=1.26.5
Provides-Extra: test
Requires-Dist: pytest-mock>=3.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Oma Helen CLI

[![Tests](https://github.com/carohauta/oma-helen-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/carohauta/oma-helen-cli/actions/workflows/tests.yml)

An interactive CLI to use [Oma Helen](https://www.helen.fi/kirjautuminen) from your command line. Offers an API client to get contract data and electricity measurements in JSON format.

### What is Oma Helen?

Oma Helen is the user portal for a Finnish electricity company, Helen Oy.

### How to install and use

Install from [pypi](https://pypi.org/project/oma-helen-cli/) and run:

```sh
pip install oma-helen-cli
oma-helen-cli
```

Then just enter you Oma Helen credentials and start entering commands.

Tip: in order to list all the commands within the CLI, enter `?`

### Available functions

| Function name                                    | What it does                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get_api_access_token                             | Get the access token to the Oma Helen API. With the token, you can make manual curl requests to the API                                                                                                                                                                                                                                                                          |
| refresh_token                                    | Re-authenticate the session. Tries to refresh the access token, but if that fails, logs in again with username and password                                                                                                                                                                                                                                                      |
| get_contract_base_price                          | Get the monthly base price of your current electricity contract                                                                                                                                                                                                                                                                                                                  |
| get_contract_data_json                           | Returns the whole contract data as JSON. Will return all active contracts you have with Helen                                                                                                                                                                                                                                                                                    |
| get_daily_measurements_json                      | Returns your daily energy consumption for the on-going month of the on-going year as JSON                                                                                                                                                                                                                                                                                        |
| get_market_prices_json                           | Returns the prices for the Market Price Electricity contract as JSON. The JSON includes the price for last month, the current month and next month if available                                                                                                                                                                                                                  |
| get_monthly_measurements_json                    | Returns your monthly energy consumption for the on-going year as JSON                                                                                                                                                                                                                                                                                                            |
| calculate_the_impact_of_usage_between_dates      | Calculates your impact of usage (in c/kwh) between given dates for the Helen Smart Electricity Guarantee                                                                                                                                                                                                                                                                         |
| calculate_spot_cost_between_dates                | Calculates the total costs (eur) between given dates of a spot price contract in an hourly precision                                                                                                                                                                                                                                                                             |
| get_exchange_margin_price_json                   | Get the margin price of the Exchange Electricity contract                                                                                                                                                                                                                                                                                                                        |
| get_contract_energy_unit_price                   | Get the energy unit price (c/kwh) from your contract data. Note that this only works for fixed price contracts. For spot electricity contract, this returns 0.0                                                                                                                                                                                                                  |
| get_contract_transfer_fee                        | Get the transfer fees (c/kwh) from your contract. Note that if Helen is not your transfer company, this returns 0.0                                                                                                                                                                                                                                                              |
| calculate_transfer_fees_between_dates            | Calculates total transfer fees (eur) based on your consumption between dates                                                                                                                                                                                                                                                                                                     |
| get_contract_transfer_base_price                 | Get the monthly transfer base price (eur) from your contract. Note that if Helen is not your transfer company, this returns 0.0                                                                                                                                                                                                                                                  |
| get_all_delivery_sites                           | Get all delivery sites across your active contracts                                                                                                                                                                                                                                                                                                                              |
| get_all_gsrn_ids                                 | Get all GSRN ids across your active contracts                                                                                                                                                                                                                                                                                                                                    |
| select_delivery_site                             | Select a delivery site by id for the CLI to use. Accepts both GSRN ids and delivery site ids as input. Useful if you have multiple contracts with Helen. Use `get_all_delivery_sites` or `get_all_gsrn_ids` to find out all your delivery sites / GSRN ids. After selecting a delivery site, all measurements and other requested data will be about the selected delivery site. |
| get_contract_type                                | Get the contract type (e.g., exchange electricity, market price) from your contract data                                                                                                                                                                                                                                                                                         |
| get_spot_prices_chart_data                       | Get spot prices from chart data API for a single day, including 15-minute intervals                                                                                                                                                                                                                                                                                              |
| get_hourly_measurements_with_spot_prices_json    | Get the measurements with spot prices for each hour between given dates                                                                                                                                                                                                                                                                                                          |
| get_quarterly_measurements_with_spot_prices_json | Get the measurements with spot prices for each quarter between given dates                                                                                                                                                                                                                                                                                                       |
| exit                                             | Exit the CLI application                                                                                                                                                                                                                                                                                                                                                         |

### Installing from sources and running the project for local development

First clone this repo.

This project uses [uv](https://docs.astral.sh/uv/) for fast dependency management. Make sure you have uv installed.

1. In the project root folder run `uv sync` to install dependencies
2. Launch the CLI with `uv run oma-helen-cli`
3. Enter your username and password as they are prompted
4. Type `?` into the CLI prompt to see all available functions

For development with test dependencies: `uv sync --extra test`

### Testing

Install test dependencies
`uv sync --extra test`

Run tests
`uv run pytest tests/test_api_client.py`

Run with verbose output
`uv run pytest tests/test_api_client.py -v`
