heytelecom 0.1.0__tar.gz

heytelecom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mauro Druwel
+
+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.

heytelecom-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: heytelecom
+Version: 0.1.0
+Summary: A Python library for interacting with Hey Telecom accounts
+Author-email: CoderMauro <mauro.druwel@gmail.com>
+Project-URL: Homepage, https://github.com/maurodruwel/heytelecom
+Project-URL: Repository, https://github.com/maurodruwel/heytelecom
+Keywords: hey,telecom,hey!,belgium,mobile,internet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: playwright
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# HeyTelecom Python Library
+
+<img width="1280" height="668" alt="HeyTelecom Banner" src="https://github.com/user-attachments/assets/d141fb44-e5c3-48af-a2b0-42ba4d2c510f" />
+
+<p align="center">
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/heytelecom"/>
+  <img alt="Python Version" src="https://img.shields.io/pypi/pyversions/heytelecom"/>
+  <img alt="License" src="https://img.shields.io/github/license/MauroDruwel/HeyTelecom"/>
+  <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/MauroDruwel/HeyTelecom"/>
+  <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/MauroDruwel/HeyTelecom"/>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> -
+  <a href="#quick-start">Quick Start</a> -
+  <a href="#features">Features</a> -
+  <a href="#api-reference">API Reference</a> -
+  <a href="https://github.com/MauroDruwel/HeyTelecom/issues">Bug Reports</a>
+</p>
+
+A Python library for interacting with [Hey Telecom](https://ecare.heytelecom.be) (hey!) accounts using Playwright for web automation. Automatically extract your mobile/internet usage, invoices, and account information.
+
+## Features
+
+- 🔐 Automatic login with session persistence
+- 📱 Retrieve mobile and internet product information
+- 📊 Get usage data (data, calls, SMS/MMS)
+- 💰 Fetch invoice information
+- 🎭 Built on Playwright for reliable web automation (headless only)
+- 🔧 Object-oriented API for easy integration
+- 🚀 Chromium browser with automatic dependency installation
+
+## Installation
+
+```bash
+pip install heytelecom
+```
+
+## Quick Start
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient(email="your@email.com", password="your_password") as client:
+    client.login()
+    account_data = client.get_account_data()
+    
+    import json
+    print(json.dumps(account_data.to_dict(), indent=2))
+```
+
+## API Reference
+
+### HeyTelecomClient
+
+Main client class for interacting with Hey Telecom.
+
+#### Constructor
+
+```python
+HeyTelecomClient(
+    email: Optional[str] = None,
+    password: Optional[str] = None,
+    user_data_dir: str = "hey_browser_data",
+    auto_install: bool = True
+)
+```
+
+**Parameters:**
+- `email`: Email address for login (optional if using saved session)
+- `password`: Password for login (optional if using saved session)
+- `user_data_dir`: Directory to store browser session data (default: "hey_browser_data")
+- `auto_install`: Automatically install Playwright chromium if not found (default: True)
+
+**Note:** Browser always runs in headless mode (no GUI) for reliable automation.
+
+**Auto-Installation:**
+When `auto_install=True` (default), the client automatically checks if Playwright chromium is installed when connecting. The check works by attempting to launch chromium - if it fails, the installer runs `playwright install chromium --with-deps --only-shell`. Set `auto_install=False` to disable this behavior and handle installation manually.
+
+#### Methods
+
+- `login()`: Login to Hey Telecom account
+- `get_products()`: Get list of all products (mobile and internet)
+- `get_latest_invoice()`: Get the latest invoice
+- `get_account_data()`: Get complete account data including products and invoice
+
+### Data Models
+
+#### Product
+- `product_id`: Unique product identifier
+- `product_type`: Type of product ("mobile" or "internet")
+- `phone_number`: Phone number (for mobile products)
+- `easy_switch_number`: Easy Switch number (for internet products)
+- `tariff`: Tariff/plan name
+- `contract`: Contract information (Contract object)
+- `usage`: Usage data (UsageData object)
+
+#### Contract
+- `start_date`: Contract start date (ISO format)
+- `price_per_month_eur`: Monthly price in EUR
+
+#### UsageData
+- `period`: Billing period with start and end dates
+- `data`: Data usage information (used, limit, unlimited)
+- `calls`: Call usage information (used, unlimited)
+- `sms_mms`: SMS/MMS usage information (used, unlimited)
+
+#### Invoice
+- `invoice_id`: Invoice identifier
+- `amount_eur`: Invoice amount in EUR
+- `status`: Invoice status
+- `paid`: Whether invoice is paid (boolean)
+- `date`: Invoice date (ISO format)
+- `due_date`: Invoice due date (ISO format)
+
+#### AccountData
+- `provider`: Provider name (always "hey!")
+- `last_sync`: Last synchronization timestamp
+- `products`: List of Product objects
+- `latest_invoice`: Latest Invoice object
+
+## Example Output
+
+```json
+{
+  "provider": "hey!",
+  "account": {
+    "last_sync": "2025-11-09T15:30:00"
+  },
+  "products": [
+    {
+      "id": "mobile_0412345678",
+      "type": "mobile",
+      "phone_number": "0412 34 56 78",
+      "tariff": "Hey! Mobile Plus",
+      "contract": {
+        "start_date": "2024-01-15",
+        "price_per_month_eur": 15.0
+      },
+      "usage": {
+        "period": {
+          "start": "2025-10-11",
+          "end": "2025-11-11"
+        },
+        "data": {
+          "used": 2.5,
+          "limit": 10.0,
+          "unlimited": false,
+          "last_update": "2025-11-09T14:30:00"
+        },
+        "calls": {
+          "used": 45.0,
+          "unlimited": true,
+          "last_update": "2025-11-09T14:30:00"
+        },
+        "sms_mms": {
+          "used": 12,
+          "unlimited": true,
+          "last_update": "2025-11-09T14:30:00"
+        }
+      }
+    }
+  ],
+  "billing": {
+    "latest_invoice": {
+      "invoice_id": "INV-20251101",
+      "amount_eur": 15.0,
+      "status": "betaald",
+      "paid": true,
+      "date": "2025-11-01",
+      "due_date": "2025-11-15"
+    }
+  }
+}
+```
+
+## Project Structure
+
+```
+heytestdev/
+├── src/
+│   └── heytelecom/
+│       ├── __init__.py          # Package initialization and exports
+│       ├── client.py            # Main HeyTelecomClient class
+│       ├── models.py            # Data models (Product, Invoice, etc.)
+│       ├── parsers.py           # Parsing utilities
+│       └── installer.py         # Playwright installation utilities
+├── README.md                    # This file
+├── pyproject.toml              # Package configuration
+└── .gitignore                  # Git ignore rules
+```
+
+## Requirements
+
+- Python 3.8+
+- playwright
+
+## Advanced Usage
+
+### Using Saved Sessions
+
+After the first login, the browser session is saved. You can use the library without credentials:
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient() as client:
+    account_data = client.get_account_data()
+    print(f"Found {len(account_data.products)} products")
+```
+
+### Getting Specific Data
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient() as client:
+    # Get only products
+    products = client.get_products()
+    for product in products:
+        print(f"Product: {product.tariff}")
+        print(f"Type: {product.product_type}")
+        if product.usage:
+            print(f"Usage: {product.usage.to_dict()}")
+    
+    # Get only latest invoice
+    invoice = client.get_latest_invoice()
+    if invoice:
+        print(f"Invoice: {invoice.amount_eur} EUR")
+        print(f"Status: {invoice.status}")
+        print(f"Paid: {invoice.paid}")
+```
+
+### Manual Playwright Installation
+
+Playwright chromium is automatically installed on first use. If you prefer manual installation:
+
+```bash
+# Manual installation (optional)
+playwright install chromium --with-deps --only-shell
+```
+
+Or use the built-in installer:
+
+```python
+from heytelecom import ensure_playwright_installed
+ensure_playwright_installed()
+```
+
+### Disabling Auto-Installation
+
+If you prefer to handle Playwright installation manually:
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient(auto_install=False) as client:
+    account_data = client.get_account_data()
+    print(account_data.to_dict())
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.

heytelecom-0.1.0/README.md

@@ -0,0 +1,272 @@
+# HeyTelecom Python Library
+
+<img width="1280" height="668" alt="HeyTelecom Banner" src="https://github.com/user-attachments/assets/d141fb44-e5c3-48af-a2b0-42ba4d2c510f" />
+
+<p align="center">
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/heytelecom"/>
+  <img alt="Python Version" src="https://img.shields.io/pypi/pyversions/heytelecom"/>
+  <img alt="License" src="https://img.shields.io/github/license/MauroDruwel/HeyTelecom"/>
+  <img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/MauroDruwel/HeyTelecom"/>
+  <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/MauroDruwel/HeyTelecom"/>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> -
+  <a href="#quick-start">Quick Start</a> -
+  <a href="#features">Features</a> -
+  <a href="#api-reference">API Reference</a> -
+  <a href="https://github.com/MauroDruwel/HeyTelecom/issues">Bug Reports</a>
+</p>
+
+A Python library for interacting with [Hey Telecom](https://ecare.heytelecom.be) (hey!) accounts using Playwright for web automation. Automatically extract your mobile/internet usage, invoices, and account information.
+
+## Features
+
+- 🔐 Automatic login with session persistence
+- 📱 Retrieve mobile and internet product information
+- 📊 Get usage data (data, calls, SMS/MMS)
+- 💰 Fetch invoice information
+- 🎭 Built on Playwright for reliable web automation (headless only)
+- 🔧 Object-oriented API for easy integration
+- 🚀 Chromium browser with automatic dependency installation
+
+## Installation
+
+```bash
+pip install heytelecom
+```
+
+## Quick Start
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient(email="your@email.com", password="your_password") as client:
+    client.login()
+    account_data = client.get_account_data()
+    
+    import json
+    print(json.dumps(account_data.to_dict(), indent=2))
+```
+
+## API Reference
+
+### HeyTelecomClient
+
+Main client class for interacting with Hey Telecom.
+
+#### Constructor
+
+```python
+HeyTelecomClient(
+    email: Optional[str] = None,
+    password: Optional[str] = None,
+    user_data_dir: str = "hey_browser_data",
+    auto_install: bool = True
+)
+```
+
+**Parameters:**
+- `email`: Email address for login (optional if using saved session)
+- `password`: Password for login (optional if using saved session)
+- `user_data_dir`: Directory to store browser session data (default: "hey_browser_data")
+- `auto_install`: Automatically install Playwright chromium if not found (default: True)
+
+**Note:** Browser always runs in headless mode (no GUI) for reliable automation.
+
+**Auto-Installation:**
+When `auto_install=True` (default), the client automatically checks if Playwright chromium is installed when connecting. The check works by attempting to launch chromium - if it fails, the installer runs `playwright install chromium --with-deps --only-shell`. Set `auto_install=False` to disable this behavior and handle installation manually.
+
+#### Methods
+
+- `login()`: Login to Hey Telecom account
+- `get_products()`: Get list of all products (mobile and internet)
+- `get_latest_invoice()`: Get the latest invoice
+- `get_account_data()`: Get complete account data including products and invoice
+
+### Data Models
+
+#### Product
+- `product_id`: Unique product identifier
+- `product_type`: Type of product ("mobile" or "internet")
+- `phone_number`: Phone number (for mobile products)
+- `easy_switch_number`: Easy Switch number (for internet products)
+- `tariff`: Tariff/plan name
+- `contract`: Contract information (Contract object)
+- `usage`: Usage data (UsageData object)
+
+#### Contract
+- `start_date`: Contract start date (ISO format)
+- `price_per_month_eur`: Monthly price in EUR
+
+#### UsageData
+- `period`: Billing period with start and end dates
+- `data`: Data usage information (used, limit, unlimited)
+- `calls`: Call usage information (used, unlimited)
+- `sms_mms`: SMS/MMS usage information (used, unlimited)
+
+#### Invoice
+- `invoice_id`: Invoice identifier
+- `amount_eur`: Invoice amount in EUR
+- `status`: Invoice status
+- `paid`: Whether invoice is paid (boolean)
+- `date`: Invoice date (ISO format)
+- `due_date`: Invoice due date (ISO format)
+
+#### AccountData
+- `provider`: Provider name (always "hey!")
+- `last_sync`: Last synchronization timestamp
+- `products`: List of Product objects
+- `latest_invoice`: Latest Invoice object
+
+## Example Output
+
+```json
+{
+  "provider": "hey!",
+  "account": {
+    "last_sync": "2025-11-09T15:30:00"
+  },
+  "products": [
+    {
+      "id": "mobile_0412345678",
+      "type": "mobile",
+      "phone_number": "0412 34 56 78",
+      "tariff": "Hey! Mobile Plus",
+      "contract": {
+        "start_date": "2024-01-15",
+        "price_per_month_eur": 15.0
+      },
+      "usage": {
+        "period": {
+          "start": "2025-10-11",
+          "end": "2025-11-11"
+        },
+        "data": {
+          "used": 2.5,
+          "limit": 10.0,
+          "unlimited": false,
+          "last_update": "2025-11-09T14:30:00"
+        },
+        "calls": {
+          "used": 45.0,
+          "unlimited": true,
+          "last_update": "2025-11-09T14:30:00"
+        },
+        "sms_mms": {
+          "used": 12,
+          "unlimited": true,
+          "last_update": "2025-11-09T14:30:00"
+        }
+      }
+    }
+  ],
+  "billing": {
+    "latest_invoice": {
+      "invoice_id": "INV-20251101",
+      "amount_eur": 15.0,
+      "status": "betaald",
+      "paid": true,
+      "date": "2025-11-01",
+      "due_date": "2025-11-15"
+    }
+  }
+}
+```
+
+## Project Structure
+
+```
+heytestdev/
+├── src/
+│   └── heytelecom/
+│       ├── __init__.py          # Package initialization and exports
+│       ├── client.py            # Main HeyTelecomClient class
+│       ├── models.py            # Data models (Product, Invoice, etc.)
+│       ├── parsers.py           # Parsing utilities
+│       └── installer.py         # Playwright installation utilities
+├── README.md                    # This file
+├── pyproject.toml              # Package configuration
+└── .gitignore                  # Git ignore rules
+```
+
+## Requirements
+
+- Python 3.8+
+- playwright
+
+## Advanced Usage
+
+### Using Saved Sessions
+
+After the first login, the browser session is saved. You can use the library without credentials:
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient() as client:
+    account_data = client.get_account_data()
+    print(f"Found {len(account_data.products)} products")
+```
+
+### Getting Specific Data
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient() as client:
+    # Get only products
+    products = client.get_products()
+    for product in products:
+        print(f"Product: {product.tariff}")
+        print(f"Type: {product.product_type}")
+        if product.usage:
+            print(f"Usage: {product.usage.to_dict()}")
+    
+    # Get only latest invoice
+    invoice = client.get_latest_invoice()
+    if invoice:
+        print(f"Invoice: {invoice.amount_eur} EUR")
+        print(f"Status: {invoice.status}")
+        print(f"Paid: {invoice.paid}")
+```
+
+### Manual Playwright Installation
+
+Playwright chromium is automatically installed on first use. If you prefer manual installation:
+
+```bash
+# Manual installation (optional)
+playwright install chromium --with-deps --only-shell
+```
+
+Or use the built-in installer:
+
+```python
+from heytelecom import ensure_playwright_installed
+ensure_playwright_installed()
+```
+
+### Disabling Auto-Installation
+
+If you prefer to handle Playwright installation manually:
+
+```python
+from heytelecom import HeyTelecomClient
+
+with HeyTelecomClient(auto_install=False) as client:
+    account_data = client.get_account_data()
+    print(account_data.to_dict())
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.

heytelecom-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heytelecom"
+version = "0.1.0"
+description = "A Python library for interacting with Hey Telecom accounts"
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.8"
+authors = [
+    {name = "CoderMauro", email = "mauro.druwel@gmail.com"}
+]
+keywords = ["hey", "telecom", "hey!", "belgium", "mobile", "internet"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "playwright",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-cov",
+]
+
+[project.urls]
+Homepage = "https://github.com/maurodruwel/heytelecom"
+Repository = "https://github.com/maurodruwel/heytelecom"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+heytelecom-install = "heytelecom.installer:main"

heytelecom-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heytelecom-0.1.0/src/heytelecom/__init__.py

@@ -0,0 +1,22 @@
+"""
+Hey Telecom Python Library
+
+A Python library for interacting with Hey Telecom accounts using Playwright.
+"""
+
+__version__ = "0.1.0"
+
+from .client import HeyTelecomClient
+from .models import Product, Contract, UsageData, Invoice, AccountData
+from .installer import install_playwright, ensure_playwright_installed
+
+__all__ = [
+    "HeyTelecomClient",
+    "Product",
+    "Contract",
+    "UsageData",
+    "Invoice",
+    "AccountData",
+    "install_playwright",
+    "ensure_playwright_installed",
+]