unlyx 1.0.0__tar.gz

unlyx-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UNIVERSALHOMEANDTECH LTD (Unlyx)
+
+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.

unlyx-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: unlyx
+Version: 1.0.0
+Summary: Official Python SDK for the Unlyx REST API v1 (account, services, orders, webhooks, usage).
+Author: Unlyx
+License: MIT
+Project-URL: Homepage, https://unlyx.com/developers
+Project-URL: Source, https://github.com/AktherHossion/unlyx-python
+Project-URL: Issues, https://github.com/AktherHossion/unlyx-python/issues
+Keywords: unlyx,imei,unlock,reseller,gsm,api,sdk,webhooks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# unlyx (Python)
+
+Official Python SDK for the **Unlyx REST API v1** — balance, services, orders (single and bulk), cancel, webhooks and usage for any Unlyx shop.
+
+- Python 3.9+, standard library only. Fully typed (`py.typed`).
+- HTTPS only, TLS verified, redirects never followed.
+- Every POST carries an `Idempotency-Key`; retries re-send the same key, so a network hiccup can never charge an order twice.
+- One exception type: `unlyx.UnlyxError`.
+- `unlyx.verify_webhook()` checks signed webhook deliveries.
+
+## Install
+
+```bash
+pip install unlyx
+```
+
+Until the package is on PyPI, install it from a copy of this folder: `pip install ./sdks/python`.
+
+## Quick start
+
+```python
+import os
+import unlyx
+
+client = unlyx.Client("https://yourshop.com", os.environ["UNLYX_API_KEY"])
+
+account = client.account()
+print(account.balance, account.currency)
+
+for service in client.services("imei"):
+    print(service.id, service.name, service.price, service.currency)
+
+# Use your own order id as the idempotency key: running the same code twice
+# returns the first order, never a second charge.
+order = client.place_order(42, "356938035643809", idempotency_key="my-order-1001")
+print(order.reference, order.status)
+
+order = client.order(order.reference)
+if order.is_success:
+    print("Result:", order.reply)
+```
+
+Get a key in the shop: **Account → API**. Tick *Sandbox* to build without spending money — sandbox orders get a `SANDBOX-` reference and never reach a supplier.
+
+## All methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `account()` | `GET /account` | `Account` |
+| `usage(days=7)` | `GET /usage` | `Usage` |
+| `services(type=None)` | `GET /services` | `list[Service]` |
+| `service(id)` | `GET /services/{id}` | `Service` |
+| `place_order(service, imei=None, *, quantity, fields, note, file, idempotency_key)` | `POST /orders` | `Order` (`replayed`, `balance` set) |
+| `place_orders([...])` | `POST /orders/bulk` | `BulkResult` |
+| `orders(*, status, since, imei, page, per_page)` | `GET /orders` | `OrderPage` |
+| `order(reference)` | `GET /orders/{reference}` | `Order` |
+| `cancel_order(reference)` | `POST /orders/{reference}/cancel` | `Order` |
+| `webhooks()` | `GET /webhooks` | `list[WebhookEndpoint]` |
+| `create_webhook(url, events=None, name=None)` | `POST /webhooks` | `WebhookEndpoint` (`secret` set once) |
+| `delete_webhook(id)` | `DELETE /webhooks/{id}` | `bool` |
+| `request(method, path, query=None, body=None, headers=None)` | anything under `/api/v1` | decoded JSON envelope |
+
+Money (`balance`, `price`) is kept as an exact decimal string — use `decimal.Decimal(order.price)` for maths.
+
+Bulk: up to 100 lines; each succeeds or fails on its own. A line's `reference` is its idempotency key; lines without one get a random reference so the SDK's retries are safe.
+
+```python
+result = client.place_orders([
+    {"reference": "batch7-1", "service": 42, "imei": "356938035643809"},
+    {"reference": "batch7-2", "service": 42, "imei": "359070071234567"},
+])
+for line in result.failed:
+    print(line.reference, line.error_message)
+```
+
+## Options
+
+```python
+client = unlyx.Client(
+    "https://yourshop.com", key,
+    timeout=30, connect_timeout=10,
+    max_retries=2,          # 0 turns retries off
+    max_retry_wait=60,      # never sleep longer than this for a Retry-After
+    signing_key_id=None,    # optional request signing, see below
+    signing_secret=None,
+    ca_bundle=None,         # path to a CA bundle if the system has none
+    user_agent="my-panel/2.3",
+)
+```
+
+### When the SDK retries
+
+| Situation | GET | POST |
+|---|---|---|
+| Connection failed before anything was sent (DNS, refused, TLS) | retried | retried, same Idempotency-Key |
+| HTTP 429 with `Retry-After` (≤ `max_retry_wait`) | retried after that wait | retried after that wait, same key |
+| HTTP 5xx | retried with backoff | **not retried** (except below) |
+| HTTP 503 with error code `temporary` (shop database busy, nothing placed) | retried | retried, same key |
+| Timeout / connection lost after sending | retried | **not retried** — check the order, or repeat with the same key |
+
+### Request signing (optional)
+
+If the shop turned on signed requests for your key, pass `signing_key_id` and `signing_secret`. Every request then carries `X-Key-Id`, `X-Timestamp` (unix seconds) and `X-Signature` = hex HMAC-SHA256 of `"{METHOD}\n{path}\n{timestamp}\n{rawBody}"` (path without the query string, e.g. `/api/v1/orders`; empty body for GET).
+
+## Errors
+
+```python
+try:
+    client.place_order(42, "356938035643809", idempotency_key="my-order-1002")
+except unlyx.UnlyxError as e:
+    e.code          # "low_balance", "invalid_input", "not_found", "service_disabled", "rate_limited", "connection_error" …
+    e.http_status   # 402, 404, 409, 422, 429 … (0 = no response)
+    e.message       # readable text from the shop
+    e.reference     # short support reference — quote it to the shop
+    e.retry_after   # seconds, on 429
+    e.body          # decoded JSON body
+```
+
+## Webhooks
+
+```python
+# Flask
+import os
+from flask import Flask, request, abort
+import unlyx
+
+app = Flask(__name__)
+
+@app.post("/hooks/unlyx")
+def unlyx_hook():
+    try:
+        event = unlyx.verify_webhook(request.get_data(), request.headers, os.environ["UNLYX_WEBHOOK_SECRET"])
+    except unlyx.UnlyxError:
+        abort(400)
+    # event["event"] == "order.completed"; event["data"]["reference"], event["data"]["reply"] …
+    # Use the X-Unlyx-Delivery header to ignore a delivery you already handled.
+    return "", 200
+```
+
+Always pass the **raw** body bytes. `verify_webhook` checks `X-Unlyx-Signature` (`t=<unix>,v1=<hex HMAC-SHA256 of "<unix>.<body>">`), refuses timestamps more than 5 minutes off (`tolerance=`), and accepts a list of secrets while you rotate.
+
+## Tests
+
+```bash
+pip install pytest
+pytest            # or: python -m unittest discover -s tests
+```
+
+The suite uses a mocked transport and never calls a real shop. Plug in your own HTTP stack by passing any object with a `send(HttpRequest) -> HttpResponse` method as `transport=`.
+
+## License
+
+MIT

unlyx-1.0.0/README.md

@@ -0,0 +1,153 @@
+# unlyx (Python)
+
+Official Python SDK for the **Unlyx REST API v1** — balance, services, orders (single and bulk), cancel, webhooks and usage for any Unlyx shop.
+
+- Python 3.9+, standard library only. Fully typed (`py.typed`).
+- HTTPS only, TLS verified, redirects never followed.
+- Every POST carries an `Idempotency-Key`; retries re-send the same key, so a network hiccup can never charge an order twice.
+- One exception type: `unlyx.UnlyxError`.
+- `unlyx.verify_webhook()` checks signed webhook deliveries.
+
+## Install
+
+```bash
+pip install unlyx
+```
+
+Until the package is on PyPI, install it from a copy of this folder: `pip install ./sdks/python`.
+
+## Quick start
+
+```python
+import os
+import unlyx
+
+client = unlyx.Client("https://yourshop.com", os.environ["UNLYX_API_KEY"])
+
+account = client.account()
+print(account.balance, account.currency)
+
+for service in client.services("imei"):
+    print(service.id, service.name, service.price, service.currency)
+
+# Use your own order id as the idempotency key: running the same code twice
+# returns the first order, never a second charge.
+order = client.place_order(42, "356938035643809", idempotency_key="my-order-1001")
+print(order.reference, order.status)
+
+order = client.order(order.reference)
+if order.is_success:
+    print("Result:", order.reply)
+```
+
+Get a key in the shop: **Account → API**. Tick *Sandbox* to build without spending money — sandbox orders get a `SANDBOX-` reference and never reach a supplier.
+
+## All methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `account()` | `GET /account` | `Account` |
+| `usage(days=7)` | `GET /usage` | `Usage` |
+| `services(type=None)` | `GET /services` | `list[Service]` |
+| `service(id)` | `GET /services/{id}` | `Service` |
+| `place_order(service, imei=None, *, quantity, fields, note, file, idempotency_key)` | `POST /orders` | `Order` (`replayed`, `balance` set) |
+| `place_orders([...])` | `POST /orders/bulk` | `BulkResult` |
+| `orders(*, status, since, imei, page, per_page)` | `GET /orders` | `OrderPage` |
+| `order(reference)` | `GET /orders/{reference}` | `Order` |
+| `cancel_order(reference)` | `POST /orders/{reference}/cancel` | `Order` |
+| `webhooks()` | `GET /webhooks` | `list[WebhookEndpoint]` |
+| `create_webhook(url, events=None, name=None)` | `POST /webhooks` | `WebhookEndpoint` (`secret` set once) |
+| `delete_webhook(id)` | `DELETE /webhooks/{id}` | `bool` |
+| `request(method, path, query=None, body=None, headers=None)` | anything under `/api/v1` | decoded JSON envelope |
+
+Money (`balance`, `price`) is kept as an exact decimal string — use `decimal.Decimal(order.price)` for maths.
+
+Bulk: up to 100 lines; each succeeds or fails on its own. A line's `reference` is its idempotency key; lines without one get a random reference so the SDK's retries are safe.
+
+```python
+result = client.place_orders([
+    {"reference": "batch7-1", "service": 42, "imei": "356938035643809"},
+    {"reference": "batch7-2", "service": 42, "imei": "359070071234567"},
+])
+for line in result.failed:
+    print(line.reference, line.error_message)
+```
+
+## Options
+
+```python
+client = unlyx.Client(
+    "https://yourshop.com", key,
+    timeout=30, connect_timeout=10,
+    max_retries=2,          # 0 turns retries off
+    max_retry_wait=60,      # never sleep longer than this for a Retry-After
+    signing_key_id=None,    # optional request signing, see below
+    signing_secret=None,
+    ca_bundle=None,         # path to a CA bundle if the system has none
+    user_agent="my-panel/2.3",
+)
+```
+
+### When the SDK retries
+
+| Situation | GET | POST |
+|---|---|---|
+| Connection failed before anything was sent (DNS, refused, TLS) | retried | retried, same Idempotency-Key |
+| HTTP 429 with `Retry-After` (≤ `max_retry_wait`) | retried after that wait | retried after that wait, same key |
+| HTTP 5xx | retried with backoff | **not retried** (except below) |
+| HTTP 503 with error code `temporary` (shop database busy, nothing placed) | retried | retried, same key |
+| Timeout / connection lost after sending | retried | **not retried** — check the order, or repeat with the same key |
+
+### Request signing (optional)
+
+If the shop turned on signed requests for your key, pass `signing_key_id` and `signing_secret`. Every request then carries `X-Key-Id`, `X-Timestamp` (unix seconds) and `X-Signature` = hex HMAC-SHA256 of `"{METHOD}\n{path}\n{timestamp}\n{rawBody}"` (path without the query string, e.g. `/api/v1/orders`; empty body for GET).
+
+## Errors
+
+```python
+try:
+    client.place_order(42, "356938035643809", idempotency_key="my-order-1002")
+except unlyx.UnlyxError as e:
+    e.code          # "low_balance", "invalid_input", "not_found", "service_disabled", "rate_limited", "connection_error" …
+    e.http_status   # 402, 404, 409, 422, 429 … (0 = no response)
+    e.message       # readable text from the shop
+    e.reference     # short support reference — quote it to the shop
+    e.retry_after   # seconds, on 429
+    e.body          # decoded JSON body
+```
+
+## Webhooks
+
+```python
+# Flask
+import os
+from flask import Flask, request, abort
+import unlyx
+
+app = Flask(__name__)
+
+@app.post("/hooks/unlyx")
+def unlyx_hook():
+    try:
+        event = unlyx.verify_webhook(request.get_data(), request.headers, os.environ["UNLYX_WEBHOOK_SECRET"])
+    except unlyx.UnlyxError:
+        abort(400)
+    # event["event"] == "order.completed"; event["data"]["reference"], event["data"]["reply"] …
+    # Use the X-Unlyx-Delivery header to ignore a delivery you already handled.
+    return "", 200
+```
+
+Always pass the **raw** body bytes. `verify_webhook` checks `X-Unlyx-Signature` (`t=<unix>,v1=<hex HMAC-SHA256 of "<unix>.<body>">`), refuses timestamps more than 5 minutes off (`tolerance=`), and accepts a list of secrets while you rotate.
+
+## Tests
+
+```bash
+pip install pytest
+pytest            # or: python -m unittest discover -s tests
+```
+
+The suite uses a mocked transport and never calls a real shop. Plug in your own HTTP stack by passing any object with a `send(HttpRequest) -> HttpResponse` method as `transport=`.
+
+## License
+
+MIT

unlyx-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unlyx"
+version = "1.0.0"
+description = "Official Python SDK for the Unlyx REST API v1 (account, services, orders, webhooks, usage)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Unlyx" }]
+keywords = ["unlyx", "imei", "unlock", "reseller", "gsm", "api", "sdk", "webhooks"]
+dependencies = []
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "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",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["unlyx"]
+
+[tool.setuptools.package-data]
+unlyx = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://unlyx.com/developers"
+Source = "https://github.com/AktherHossion/unlyx-python"
+Issues = "https://github.com/AktherHossion/unlyx-python/issues"

unlyx-1.0.0/setup.cfg

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