onemax 0.1.0__tar.gz

onemax-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest --cov --cov-report=term-missing

onemax-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - name: Check the tag matches the package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          declared="$(uv run python -c 'from importlib.metadata import version; print(version("onemax"))')"
+          imported="$(uv run python -c 'import onemax; print(onemax.__version__)')"
+          echo "tag $tag, pyproject $declared, module $imported"
+          test "$tag" = "$declared"
+          test "$tag" = "$imported"
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - name: Take the notes from the changelog
+        run: |
+          awk -v version="${GITHUB_REF_NAME#v}" '
+            /^## / { found = ($2 == version); next }
+            found { print }
+          ' CHANGELOG.md > notes.md
+          test -s notes.md
+      - name: Publish the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file notes.md

onemax-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+dist/
+build/
+*.egg-info/
+.env

onemax-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Check a member by the code on their card and record the usage: `verify_code`, `confirm_usage`,
+  `void_usage`, `usage`.
+- Account linking with PKCE: `generate_pkce`, `authorize_url`, `exchange_code`, `link_status`,
+  `verify_link`, `revoke_link`.
+- `context` to check a key and list the venue's offers.
+- Sync `OneMaxClient` and async `AsyncOneMaxClient` with the same methods.
+- Typed results and one error class per kind of failure.

onemax-0.1.0/LICENSE

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

onemax-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: onemax
+Version: 0.1.0
+Summary: Python client for the OneMax partner API
+Project-URL: Homepage, https://onemax.az
+Project-URL: Repository, https://github.com/onemax-az/onemax-python
+Project-URL: Changelog, https://github.com/onemax-az/onemax-python/blob/main/CHANGELOG.md
+Author: OneMax
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,azerbaijan,membership,onemax,partner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# onemax
+
+Python client for the [OneMax](https://onemax.az) partner API.
+
+OneMax is a 1+1 membership club in Baku. Members pay for a plan and show a code at the counter to
+use a partner's offer. This library lets a partner's own system do what the counter does: check
+that someone is a member and record that they used the offer.
+
+Sync and async, fully typed, one dependency.
+
+```bash
+pip install onemax
+```
+
+## Getting a key
+
+1. OneMax switches API access on for your business.
+2. The owner opens the partner panel, goes to API and creates a key.
+3. The key is shown once. It belongs to one venue and acts there like a cashier.
+
+Keep the key on your server. It must never reach a browser or a mobile app.
+
+## Quick start: a member's code
+
+A member opens their OneMax card and reads you the six digit code.
+
+```python
+from onemax import OneMaxClient
+
+client = OneMaxClient("omx_live_...")
+
+check = client.verify_code("482915")
+if not check.usable:
+    print("No discount:", check.reason)
+else:
+    order = place_order(discounted=True)
+    client.confirm_usage(check.usage_id, reference=order.id)
+```
+
+`verify_code` only answers the question. Nothing counts against the member until you call
+`confirm_usage`. If the order falls through, call `void_usage(check.usage_id)` instead.
+
+Pass your own order id as `reference`. Confirming again with the same reference returns the same
+usage, so a retried request is safe.
+
+## Account linking
+
+A member links their OneMax account to your app once. After that you check them without a code.
+Linking is the OAuth 2.0 authorization code flow with PKCE, so the same steps work for a website
+and a mobile app.
+
+Register the addresses your app may return to in the partner panel, under API, Account linking.
+Your client id is shown there.
+
+**1. Send the member to the permission page.**
+
+```python
+from onemax import generate_pkce
+
+pkce = generate_pkce()
+session["onemax_verifier"] = pkce.verifier
+
+url = client.authorize_url(
+    client_id="omx_client_...",
+    redirect_uri="https://example.az/onemax/return",
+    code_challenge=pkce.challenge,
+    state=session_id,
+)
+```
+
+In a mobile app, open `url` in the system browser and use your app link as the `redirect_uri`,
+for example `taksi://onemax/return`.
+
+**2. The member returns to your address** with `code` and `state`, or with `error=access_denied`
+if they declined. Check that `state` is the one you sent.
+
+**3. Exchange the code on your server and store the token.**
+
+```python
+link = client.exchange_code(
+    code,
+    code_verifier=session["onemax_verifier"],
+    redirect_uri="https://example.az/onemax/return",
+)
+save(user_id, link.link_token)
+```
+
+The code works once and for five minutes.
+
+**4. Check the member whenever you need to.**
+
+```python
+status = client.link_status(link_token)
+if not status.linked:
+    forget(user_id)
+
+check = client.verify_link(link_token)
+if check.usable:
+    client.confirm_usage(check.usage_id, reference=order.id)
+```
+
+A member can unlink at any time in their OneMax profile. From then on `link_status` answers
+`linked=False` and `verify_link` answers `reason="not_linked"`. Neither raises.
+
+You learn only whether the subscription is active. The member's name, email, phone and photo are
+never shared.
+
+## Async
+
+`AsyncOneMaxClient` has the same methods, awaited:
+
+```python
+from onemax import AsyncOneMaxClient
+
+async with AsyncOneMaxClient("omx_live_...") as client:
+    check = await client.verify_code("482915")
+```
+
+## Results
+
+`verify_code` and `verify_link` return a `Verification`:
+
+| Field | Meaning |
+| --- | --- |
+| `active` | The member has a subscription that works today |
+| `usable` | They may use the offer right now |
+| `reason` | Why, as a `Reason` |
+| `usage_id` | Set when `usable` is true. Confirm it or void it |
+| `daily_limit` | How many times a day a member may use this venue |
+
+| `Reason` | Meaning |
+| --- | --- |
+| `OK` | Go ahead |
+| `NOT_SUBSCRIBED` | No subscription, or it has ended |
+| `LIMIT_REACHED` | The member already used today's allowance at this venue |
+| `OFFER_UNAVAILABLE` | The venue or the offer is not open right now |
+| `INVALID_CODE` | The code is wrong, expired or already used |
+| `NOT_LINKED` | The link token no longer works |
+
+`Reason` and `UsageStatus` are string enums, so `check.reason == "ok"` works as well. A value this
+version does not know is returned as a plain string.
+
+If a venue has several offers open, pass `offer_id`. `client.context()` lists them.
+
+## Errors
+
+Everything the library raises is a `OneMaxError`.
+
+| Class | When |
+| --- | --- |
+| `TransportError` | No usable answer: a connection failure, a timeout, or a body that is not JSON |
+| `ApiError` | The API answered with an error. Has `status`, `code`, `message`, `details`, `request_id` |
+| `AuthenticationError` | 401. The key is missing, wrong or switched off |
+| `AccessDisabledError` | 403. API access is switched off for the partner |
+| `NotFoundError` | 404. No such usage for this key |
+| `ConflictError` | 409. For example `usage_limit_reached`, `already_applied`, `reference_used` |
+| `InvalidRequestError` | 400 or 422. For example `offer_required`, `link_code_invalid` |
+| `RateLimitError` | 429. Has `retry_after` in seconds |
+| `ServerError` | 500 and above |
+
+```python
+from onemax import ConflictError, OneMaxError
+
+try:
+    client.confirm_usage(usage_id, reference=order.id)
+except ConflictError as error:
+    if error.code == "usage_limit_reached":
+        charge_full_price(order)
+    else:
+        raise
+except OneMaxError:
+    retry_later(order)
+```
+
+`message` is in Azerbaijani and meant for your logs. Decide on `code`.
+
+## Limits
+
+- The member's daily limit applies exactly as it does at a counter.
+- 120 requests a minute per key.
+- The library never retries by itself. `confirm_usage` with a `reference` is safe to retry.
+
+## Development
+
+```bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+## Releasing
+
+Set the version in `src/onemax/_version.py`, add a `## x.y.z` section to `CHANGELOG.md`, commit, then push a tag
+`vx.y.z`. The `Publish` workflow checks that the tag equals the package version, runs the checks,
+publishes to PyPI and creates the GitHub release from the changelog section. A tag that does not match the
+version publishes nothing.
+
+## License
+
+MIT

onemax-0.1.0/README.md

@@ -0,0 +1,202 @@
+# onemax
+
+Python client for the [OneMax](https://onemax.az) partner API.
+
+OneMax is a 1+1 membership club in Baku. Members pay for a plan and show a code at the counter to
+use a partner's offer. This library lets a partner's own system do what the counter does: check
+that someone is a member and record that they used the offer.
+
+Sync and async, fully typed, one dependency.
+
+```bash
+pip install onemax
+```
+
+## Getting a key
+
+1. OneMax switches API access on for your business.
+2. The owner opens the partner panel, goes to API and creates a key.
+3. The key is shown once. It belongs to one venue and acts there like a cashier.
+
+Keep the key on your server. It must never reach a browser or a mobile app.
+
+## Quick start: a member's code
+
+A member opens their OneMax card and reads you the six digit code.
+
+```python
+from onemax import OneMaxClient
+
+client = OneMaxClient("omx_live_...")
+
+check = client.verify_code("482915")
+if not check.usable:
+    print("No discount:", check.reason)
+else:
+    order = place_order(discounted=True)
+    client.confirm_usage(check.usage_id, reference=order.id)
+```
+
+`verify_code` only answers the question. Nothing counts against the member until you call
+`confirm_usage`. If the order falls through, call `void_usage(check.usage_id)` instead.
+
+Pass your own order id as `reference`. Confirming again with the same reference returns the same
+usage, so a retried request is safe.
+
+## Account linking
+
+A member links their OneMax account to your app once. After that you check them without a code.
+Linking is the OAuth 2.0 authorization code flow with PKCE, so the same steps work for a website
+and a mobile app.
+
+Register the addresses your app may return to in the partner panel, under API, Account linking.
+Your client id is shown there.
+
+**1. Send the member to the permission page.**
+
+```python
+from onemax import generate_pkce
+
+pkce = generate_pkce()
+session["onemax_verifier"] = pkce.verifier
+
+url = client.authorize_url(
+    client_id="omx_client_...",
+    redirect_uri="https://example.az/onemax/return",
+    code_challenge=pkce.challenge,
+    state=session_id,
+)
+```
+
+In a mobile app, open `url` in the system browser and use your app link as the `redirect_uri`,
+for example `taksi://onemax/return`.
+
+**2. The member returns to your address** with `code` and `state`, or with `error=access_denied`
+if they declined. Check that `state` is the one you sent.
+
+**3. Exchange the code on your server and store the token.**
+
+```python
+link = client.exchange_code(
+    code,
+    code_verifier=session["onemax_verifier"],
+    redirect_uri="https://example.az/onemax/return",
+)
+save(user_id, link.link_token)
+```
+
+The code works once and for five minutes.
+
+**4. Check the member whenever you need to.**
+
+```python
+status = client.link_status(link_token)
+if not status.linked:
+    forget(user_id)
+
+check = client.verify_link(link_token)
+if check.usable:
+    client.confirm_usage(check.usage_id, reference=order.id)
+```
+
+A member can unlink at any time in their OneMax profile. From then on `link_status` answers
+`linked=False` and `verify_link` answers `reason="not_linked"`. Neither raises.
+
+You learn only whether the subscription is active. The member's name, email, phone and photo are
+never shared.
+
+## Async
+
+`AsyncOneMaxClient` has the same methods, awaited:
+
+```python
+from onemax import AsyncOneMaxClient
+
+async with AsyncOneMaxClient("omx_live_...") as client:
+    check = await client.verify_code("482915")
+```
+
+## Results
+
+`verify_code` and `verify_link` return a `Verification`:
+
+| Field | Meaning |
+| --- | --- |
+| `active` | The member has a subscription that works today |
+| `usable` | They may use the offer right now |
+| `reason` | Why, as a `Reason` |
+| `usage_id` | Set when `usable` is true. Confirm it or void it |
+| `daily_limit` | How many times a day a member may use this venue |
+
+| `Reason` | Meaning |
+| --- | --- |
+| `OK` | Go ahead |
+| `NOT_SUBSCRIBED` | No subscription, or it has ended |
+| `LIMIT_REACHED` | The member already used today's allowance at this venue |
+| `OFFER_UNAVAILABLE` | The venue or the offer is not open right now |
+| `INVALID_CODE` | The code is wrong, expired or already used |
+| `NOT_LINKED` | The link token no longer works |
+
+`Reason` and `UsageStatus` are string enums, so `check.reason == "ok"` works as well. A value this
+version does not know is returned as a plain string.
+
+If a venue has several offers open, pass `offer_id`. `client.context()` lists them.
+
+## Errors
+
+Everything the library raises is a `OneMaxError`.
+
+| Class | When |
+| --- | --- |
+| `TransportError` | No usable answer: a connection failure, a timeout, or a body that is not JSON |
+| `ApiError` | The API answered with an error. Has `status`, `code`, `message`, `details`, `request_id` |
+| `AuthenticationError` | 401. The key is missing, wrong or switched off |
+| `AccessDisabledError` | 403. API access is switched off for the partner |
+| `NotFoundError` | 404. No such usage for this key |
+| `ConflictError` | 409. For example `usage_limit_reached`, `already_applied`, `reference_used` |
+| `InvalidRequestError` | 400 or 422. For example `offer_required`, `link_code_invalid` |
+| `RateLimitError` | 429. Has `retry_after` in seconds |
+| `ServerError` | 500 and above |
+
+```python
+from onemax import ConflictError, OneMaxError
+
+try:
+    client.confirm_usage(usage_id, reference=order.id)
+except ConflictError as error:
+    if error.code == "usage_limit_reached":
+        charge_full_price(order)
+    else:
+        raise
+except OneMaxError:
+    retry_later(order)
+```
+
+`message` is in Azerbaijani and meant for your logs. Decide on `code`.
+
+## Limits
+
+- The member's daily limit applies exactly as it does at a counter.
+- 120 requests a minute per key.
+- The library never retries by itself. `confirm_usage` with a `reference` is safe to retry.
+
+## Development
+
+```bash
+uv sync
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+## Releasing
+
+Set the version in `src/onemax/_version.py`, add a `## x.y.z` section to `CHANGELOG.md`, commit, then push a tag
+`vx.y.z`. The `Publish` workflow checks that the tag equals the package version, runs the checks,
+publishes to PyPI and creates the GitHub release from the changelog section. A tag that does not match the
+version publishes nothing.
+
+## License
+
+MIT

onemax-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "onemax"
+dynamic = ["version"]
+description = "Python client for the OneMax partner API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "OneMax" }]
+keywords = ["onemax", "membership", "partner", "api", "azerbaijan"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://onemax.az"
+Repository = "https://github.com/onemax-az/onemax-python"
+Changelog = "https://github.com/onemax-az/onemax-python/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.15.0",
+    "mypy>=1.19.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/onemax/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/onemax"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "UP", "B", "A", "C4", "SIM", "RUF", "PT", "TID"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

onemax-0.1.0/src/onemax/__init__.py

@@ -0,0 +1,44 @@
+from ._version import __version__
+from .aio import AsyncOneMaxClient
+from .client import OneMaxClient
+from .errors import (
+    AccessDisabledError,
+    ApiError,
+    AuthenticationError,
+    ConflictError,
+    InvalidRequestError,
+    NotFoundError,
+    OneMaxError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+)
+from .models import Context, LinkStatus, LinkToken, Offer, Reason, Usage, UsageStatus, Verification
+from .pkce import Pkce, challenge_for, generate_pkce
+
+__all__ = [
+    "AccessDisabledError",
+    "ApiError",
+    "AsyncOneMaxClient",
+    "AuthenticationError",
+    "ConflictError",
+    "Context",
+    "InvalidRequestError",
+    "LinkStatus",
+    "LinkToken",
+    "NotFoundError",
+    "Offer",
+    "OneMaxClient",
+    "OneMaxError",
+    "Pkce",
+    "RateLimitError",
+    "Reason",
+    "ServerError",
+    "TransportError",
+    "Usage",
+    "UsageStatus",
+    "Verification",
+    "__version__",
+    "challenge_for",
+    "generate_pkce",
+]