mm-aggr-sdk 0.1.1__tar.gz

mm_aggr_sdk-0.1.1/.cursor/rules/api-source-of-truth.mdc

@@ -0,0 +1,13 @@
+---
+description: Merchant OpenAPI is the source of truth; do not invent endpoints
+alwaysApply: true
+---
+
+# API source of truth
+
+- Implement only operations in the contrib hub pin
+  `contract/openapi/merchants.openapi.yaml` (nested checkout:
+  `contrib/contract/` from `mm_aggregator`) and `/api/v1/schema/merchants/`.
+- Cross-check the live schema if the pin may be behind. Do not invent paths,
+  headers, or error codes.
+- Never put merchant API keys in frontend or plugin JavaScript.

mm_aggr_sdk-0.1.1/.cursor/rules/currency-safety.mdc

@@ -0,0 +1,10 @@
+---
+description: Never mix monetary amounts across currencies
+alwaysApply: true
+---
+
+# Currency safety
+
+- Never add, subtract, compare, or aggregate amounts across currencies.
+- Group values by currency code. Cross-currency math requires an explicit FX
+  context (rate source and applied rate).

mm_aggr_sdk-0.1.1/.cursor/rules/docs-audience.mdc

@@ -0,0 +1,13 @@
+---
+description: README is for installers; CONTRIBUTING is for people who change this repo
+alwaysApply: true
+---
+
+# Documentation audience
+
+- `README.md` is for application developers installing this package. Install,
+  requirements, quick start, credentials. No git branches, PR process, or
+  coding standards except a single link to `CONTRIBUTING.md`.
+- `CONTRIBUTING.md` is for contributors. Clone, toolchain, tests, CLA, commits.
+  Do not duplicate merchant install steps from README.
+- Never mix these audiences.

mm_aggr_sdk-0.1.1/.cursor/rules/license.mdc

@@ -0,0 +1,10 @@
+---
+description: MIT license and CLA for MainMoney SARL
+alwaysApply: true
+---
+
+# License
+
+- Copyright (c) MainMoney SARL. Outbound license: MIT.
+- Pull requests require `CLA.md` so contributions vest in MainMoney SARL.
+- Keep the license headers and manifest SPDX ids consistent with `LICENSE`.

mm_aggr_sdk-0.1.1/.cursor/rules/python.mdc

@@ -0,0 +1,10 @@
+---
+description: Python SDK coding standards
+globs: "**/*.py"
+alwaysApply: false
+---
+
+# Python
+
+- Type hints on public functions. pytest for tests. ruff for format and lint.
+- Prefer uv; keep Poetry lockfile in sync when dependencies change.

mm_aggr_sdk-0.1.1/.cursor/skills/add-python-api-resource/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: add-python-api-resource
+description: Add a merchant API resource to the MainMoney Python SDK from OpenAPI
+---
+
+# Add a Python API resource
+
+1. Read the pinned contract `contrib/contract/openapi/merchants.openapi.yaml`
+   (and `contrib/contract/resources.md`). Cross-check live
+   `/api/v1/schema/merchants/` if the pin may be behind. Do not invent endpoints.
+2. Add a typed method on the client with pytest coverage.
+3. Update README with the installer-facing call only.

mm_aggr_sdk-0.1.1/.env.example

@@ -0,0 +1,5 @@
+MM_CLIENT_ID=
+MM_API_SECRET=
+# Optional. Default production: https://aggregator.mainmoney.net/api/v1/
+# Test: https://testaggregator.mainmoney.net/api/v1/ (Client test=True)
+# MM_BASE_URI=

mm_aggr_sdk-0.1.1/.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# Copilot instructions
+
+Project: MainMoney Python SDK.
+
+- Follow CONVENTIONS.md and .cursor/rules.
+- README is for package users; CONTRIBUTING is for repo contributors.
+- Do not invent merchant API endpoints.

mm_aggr_sdk-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src
+      - run: uv run pytest

mm_aggr_sdk-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Tag matches package version
+        run: |
+          version="$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/mm_aggr/__init__.py)"
+          test "v${version}" = "${GITHUB_REF_NAME}" || { echo "Tag ${GITHUB_REF_NAME} != v${version}"; exit 1; }
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

mm_aggr_sdk-0.1.1/.gitignore

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

mm_aggr_sdk-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13

mm_aggr_sdk-0.1.1/AGENTS.md

@@ -0,0 +1,5 @@
+# MainMoney Python SDK — agent instructions
+
+Read `CONVENTIONS.md`, `CONTRIBUTING.md`, and `.cursor/rules/` before changing code.
+
+`README.md` is for installers only. Do not put contribution workflow there.

mm_aggr_sdk-0.1.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.1
+
+- Relicensed under the MIT License.
+- Distribution renamed to `mm-aggr-sdk` on PyPI (the import package is still `mm_aggr`).
+- First release published to PyPI.

mm_aggr_sdk-0.1.1/CLA.md

@@ -0,0 +1,24 @@
+# Contributor License Agreement
+
+Copyright owner: **MainMoney SARL**
+
+By submitting a contribution (including a pull request, patch, or issue
+attachment) to this repository, you agree that:
+
+1. You grant MainMoney SARL a perpetual, worldwide, irrevocable, royalty-free,
+   sublicensable copyright and patent license to use, reproduce, modify,
+   create derivative works of, publicly display, publicly perform, and
+   distribute your contribution, and to relicense it (including under a
+   commercial license).
+2. You assign to MainMoney SARL all right, title, and interest in the
+   contribution to the extent permitted by law. If assignment is not
+   effective, the license in (1) still applies.
+3. You represent that the contribution is your original work, or that you have
+   the right to grant these terms, and that the contribution does not
+   knowingly infringe third-party rights.
+4. You retain the right to be identified as the author of the contribution.
+
+MainMoney SARL may use contributions in proprietary products and distributes this
+repository under the MIT License.
+
+This is not legal advice. Individual and entity contributors are both covered.

mm_aggr_sdk-0.1.1/CLAUDE.md

@@ -0,0 +1,3 @@
+# MainMoney Python SDK
+
+Follow `CONVENTIONS.md` and `.cursor/rules/`. README = installers; CONTRIBUTING = contributors. License is MIT (MainMoney SARL).

mm_aggr_sdk-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+This document is for people who change **this repository**. To install the
+package into an application, see [README.md](README.md).
+
+## Legal
+
+Pull requests require agreement to [CLA.md](CLA.md). Contributions are owned
+by MainMoney SARL.
+
+## Clone
+
+```bash
+git clone git@github.com:MainMoney-Inc/mm_aggr_python_sdk.git
+```
+
+## Setup
+
+```bash
+uv sync --all-extras
+# or: poetry install
+uv run pytest
+uv run mypy src
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## PyPI
+
+The distribution name is `mm-aggr-sdk` (import package `mm_aggr`). Releases are
+automated: bump `__version__` in `src/mm_aggr/__init__.py`, update `CHANGELOG.md`, then
+push an annotated tag `vX.Y.Z`. The `Publish` workflow builds and uploads to
+[PyPI](https://pypi.org/project/mm-aggr-sdk/) through Trusted Publishing (workflow
+`publish.yml`, environment `pypi`). Do not commit PyPI tokens.
+
+## Branches and commits
+
+- `feature/<name>`, `bugfix/<name>`, `hotfix/<issue>`, `refactor/<description>`
+- Conventional commits: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## Pull requests
+
+- Include tests for behavior changes.
+- Do not invent merchant API endpoints. Implement from the pinned OpenAPI in
+  the contrib hub (`contract/openapi/merchants.openapi.yaml`, checkout path
+  `contrib/contract/` from `mm_aggregator`). Cross-check live
+  `/api/v1/schema/merchants/` if the pin may be behind.
+- Do not commit secrets.
+- Local demos live under `examples/`. Working SQLite (`db.sqlite3`) is gitignored;
+  commit `data/initial.sqlite3` only when the mini-shop schema or catalog changes.

mm_aggr_sdk-0.1.1/CONVENTIONS.md

@@ -0,0 +1,8 @@
+# Conventions
+
+- Python 3.11+ (develop on 3.13/3.14). Type hints and mypy-compatible code.
+- Package layout: `src/mm_aggr/`. uv is the primary toolchain; Poetry is supported.
+- pytest, ruff. No empty `except:` swallows.
+- HTTP via injectable `HttpClient` (default `RequestsHttpClient`, `requests` runtime dependency).
+- Currency: never mix amounts across currencies.
+- Do not call the aggregator from this SDK with invented paths.

mm_aggr_sdk-0.1.1/LICENSE

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

mm_aggr_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: mm-aggr-sdk
+Version: 0.1.1
+Summary: Python SDK for the MainMoney aggregator merchant API
+Project-URL: Homepage, https://github.com/MainMoney-Inc/mm_aggr_python_sdk
+Project-URL: Issues, https://github.com/MainMoney-Inc/mm_aggr_python_sdk/issues
+Project-URL: Changelog, https://github.com/MainMoney-Inc/mm_aggr_python_sdk/blob/main/CHANGELOG.md
+Project-URL: Source, https://github.com/MainMoney-Inc/mm_aggr_python_sdk
+Author: MainMoney SARL
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mainmoney,merchant,payments,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: types-requests>=2.32.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MainMoney Python SDK
+
+Python client for the MainMoney aggregator merchant API. Install this package
+in your Python application (Django, FastAPI, Flask, or scripts).
+
+The [JS/TS frontend SDK](https://github.com/MainMoney-Inc/mm_aggr_js_sdk) can
+be used in the browser only if this SDK (or the PHP or Node SDK) runs on your
+server. Never put merchant API keys in frontend code.
+
+## Requirements
+
+- Python 3.11 or later (3.13 or 3.14 recommended)
+- A merchant application on MM Aggregator
+
+## Install
+
+With uv (recommended):
+
+```bash
+uv add mm-aggr-sdk
+```
+
+With pip:
+
+```bash
+pip install mm-aggr-sdk
+```
+
+With Poetry:
+
+```bash
+poetry add mm-aggr-sdk
+```
+
+Until the package is on PyPI, install from GitHub:
+
+```bash
+pip install git+https://github.com/MainMoney-Inc/mm_aggr_python_sdk.git
+```
+
+## Quick start
+
+```python
+import os
+
+from mm_aggr import Client
+
+client = Client(
+    client_id=os.environ["MM_CLIENT_ID"],
+    secret=os.environ["MM_API_SECRET"],
+    test=True,  # https://testaggregator.mainmoney.net — omit for production
+)
+
+deposit = client.deposits.create(
+    {
+        "provider_code": "VODACOM_MPESA_COD",
+        "reference": "ORDER-123",
+        "amount": "100.00",
+        "currency": "USD",
+        "customer_phone": "243820000000",
+    },
+    idempotency_key="ORDER-123",
+)
+```
+
+Defaults: production `https://aggregator.mainmoney.net/api/v1/`, test
+`https://testaggregator.mainmoney.net/api/v1/`. Pass `base_uri` only to override.
+Configure credentials from your environment. Merchant API docs:
+`/api/v1/docs/merchants/` on the aggregator host.
+
+Exchange `client_id` and `secret` for a Bearer access token is handled by the
+SDK. There is no `X-API-KEY` header. Reuse the same `reference` and optional
+`Idempotency-Key` when retrying a create. Amounts are decimal strings; do not
+mix currencies.
+
+Verify inbound webhooks with
+`client.webhooks.verify(raw_body, signature, secret)`.
+
+Do not send merchant API keys to the browser.
+
+## License
+
+Copyright (c) 2026 MainMoney SARL. Licensed under the MIT License. See [LICENSE](LICENSE).
+
+## Examples
+
+Runnable mini-shops live in [examples/](examples/). Each folder has its own
+README (Django REST Framework, FastAPI, Flask). Pair them with a
+[JS/TS frontend example](https://github.com/MainMoney-Inc/mm_aggr_js_sdk/tree/main/examples).
+
+Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md).

mm_aggr_sdk-0.1.1/README.md

@@ -0,0 +1,91 @@
+# MainMoney Python SDK
+
+Python client for the MainMoney aggregator merchant API. Install this package
+in your Python application (Django, FastAPI, Flask, or scripts).
+
+The [JS/TS frontend SDK](https://github.com/MainMoney-Inc/mm_aggr_js_sdk) can
+be used in the browser only if this SDK (or the PHP or Node SDK) runs on your
+server. Never put merchant API keys in frontend code.
+
+## Requirements
+
+- Python 3.11 or later (3.13 or 3.14 recommended)
+- A merchant application on MM Aggregator
+
+## Install
+
+With uv (recommended):
+
+```bash
+uv add mm-aggr-sdk
+```
+
+With pip:
+
+```bash
+pip install mm-aggr-sdk
+```
+
+With Poetry:
+
+```bash
+poetry add mm-aggr-sdk
+```
+
+Until the package is on PyPI, install from GitHub:
+
+```bash
+pip install git+https://github.com/MainMoney-Inc/mm_aggr_python_sdk.git
+```
+
+## Quick start
+
+```python
+import os
+
+from mm_aggr import Client
+
+client = Client(
+    client_id=os.environ["MM_CLIENT_ID"],
+    secret=os.environ["MM_API_SECRET"],
+    test=True,  # https://testaggregator.mainmoney.net — omit for production
+)
+
+deposit = client.deposits.create(
+    {
+        "provider_code": "VODACOM_MPESA_COD",
+        "reference": "ORDER-123",
+        "amount": "100.00",
+        "currency": "USD",
+        "customer_phone": "243820000000",
+    },
+    idempotency_key="ORDER-123",
+)
+```
+
+Defaults: production `https://aggregator.mainmoney.net/api/v1/`, test
+`https://testaggregator.mainmoney.net/api/v1/`. Pass `base_uri` only to override.
+Configure credentials from your environment. Merchant API docs:
+`/api/v1/docs/merchants/` on the aggregator host.
+
+Exchange `client_id` and `secret` for a Bearer access token is handled by the
+SDK. There is no `X-API-KEY` header. Reuse the same `reference` and optional
+`Idempotency-Key` when retrying a create. Amounts are decimal strings; do not
+mix currencies.
+
+Verify inbound webhooks with
+`client.webhooks.verify(raw_body, signature, secret)`.
+
+Do not send merchant API keys to the browser.
+
+## License
+
+Copyright (c) 2026 MainMoney SARL. Licensed under the MIT License. See [LICENSE](LICENSE).
+
+## Examples
+
+Runnable mini-shops live in [examples/](examples/). Each folder has its own
+README (Django REST Framework, FastAPI, Flask). Pair them with a
+[JS/TS frontend example](https://github.com/MainMoney-Inc/mm_aggr_js_sdk/tree/main/examples).
+
+Want to contribute? See [CONTRIBUTING.md](CONTRIBUTING.md).

mm_aggr_sdk-0.1.1/docs/README.md

@@ -0,0 +1,4 @@
+# Python SDK docs
+
+User install guide: [../README.md](../README.md).
+Contributor setup: [../CONTRIBUTING.md](../CONTRIBUTING.md).

mm_aggr_sdk-0.1.1/examples/README.md

@@ -0,0 +1,14 @@
+# Python SDK examples
+
+Standalone mini-shops that use the `mm-aggr-sdk` package. Each folder is its own
+uv project. Start **one** backend, then point a
+[JS/TS frontend example](https://github.com/MainMoney-Inc/mm_aggr_js_sdk/tree/main/examples)
+at it with `VITE_MERCHANT_BACKEND_URL`.
+
+| Example | Port | Start |
+| --- | --- | --- |
+| [django-drf](django-drf/) | 8000 | See that folder’s README |
+| [fastapi](fastapi/) | 8001 | See that folder’s README |
+| [flask](flask/) | 8002 | See that folder’s README |
+
+Same app in every example: choose a product, pay (deposit), refund, transfer (payout).

mm_aggr_sdk-0.1.1/examples/django-drf/.env.example

@@ -0,0 +1,9 @@
+MM_CLIENT_ID=
+MM_API_SECRET=
+MM_TEST=true
+MM_WEBHOOK_SECRET=
+# Optional. Override aggregator host (local or custom).
+# MM_BASE_URI=https://testaggregator.mainmoney.net/api/v1/
+PORT=8000
+CORS_ORIGINS=http://127.0.0.1:5173,http://127.0.0.1:5174,http://127.0.0.1:5175,http://127.0.0.1:4200,http://localhost:5173,http://localhost:5174,http://localhost:5175,http://localhost:4200
+DJANGO_SECRET_KEY=django-drf-example-change-me

mm_aggr_sdk-0.1.1/examples/django-drf/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+db.sqlite3
+*.sqlite3-journal
+.env
+.env.*
+!.env.example

mm_aggr_sdk-0.1.1/examples/django-drf/README.md

@@ -0,0 +1,53 @@
+# Django REST Framework mini-shop
+
+Standalone example that installs [`mm-aggr-sdk`](https://github.com/MainMoney-Inc/mm_aggr_python_sdk)
+as a package and exposes the same shop API as the other SDK examples.
+
+Pages a frontend can drive: products, pay (deposit), refund, transfer (payout).
+
+Default port: **8000**.
+
+## Setup
+
+```bash
+cp .env.example .env
+# set MM_CLIENT_ID, MM_API_SECRET, and MM_WEBHOOK_SECRET
+uv sync
+./scripts/reset-db
+```
+
+Until PyPI lists `mm-aggr-sdk`, `uv sync` installs it from GitHub (see `pyproject.toml`).
+
+If `db.sqlite3` is missing, `./scripts/reset-db` copies the committed snapshot
+`data/initial.sqlite3`. To refill products after a migrate:
+
+```bash
+./scripts/seed
+```
+
+Update `data/initial.sqlite3` only when the schema or catalog changes:
+
+```bash
+uv run python manage.py migrate
+./scripts/seed
+./scripts/export-initial-db
+```
+
+Do not commit `db.sqlite3` (local orders and test refunds stay on your machine).
+
+## Run
+
+```bash
+uv run python manage.py runserver 8000
+```
+
+Then start a JS frontend example and set:
+
+```
+VITE_MERCHANT_BACKEND_URL=http://127.0.0.1:8000
+```
+
+Aggregator webhooks cannot reach `localhost`. Use a tunnel if you want
+`POST /webhooks` to fire. Status polling works without a public URL.
+
+Webhook URL (after a tunnel): `https://your-host.example/webhooks`

mm_aggr_sdk-0.1.1/examples/django-drf/catalog/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class CatalogConfig(AppConfig):
+    default_auto_field = "django.db.models.AutoField"
+    name = "catalog"

mm_aggr_sdk-0.1.1/examples/django-drf/catalog/client.py

@@ -0,0 +1,16 @@
+"""Build a MainMoney SDK client from Django settings."""
+
+from __future__ import annotations
+
+from django.conf import settings
+
+
+def get_client():
+    from mm_aggr import Client
+
+    return Client(
+        client_id=settings.MM_CLIENT_ID,
+        secret=settings.MM_API_SECRET,
+        base_uri=settings.MM_BASE_URI,
+        test=settings.MM_TEST,
+    )

mm_aggr_sdk-0.1.1/examples/django-drf/catalog/management/commands/seed.py

@@ -0,0 +1,16 @@
+from django.core.management.base import BaseCommand
+
+from catalog.models import Product
+from catalog.views import DEMO_PRODUCTS
+
+
+class Command(BaseCommand):
+    help = "Insert demo products if the catalog is empty."
+
+    def handle(self, *args: object, **options: object) -> None:
+        created = 0
+        for item in DEMO_PRODUCTS:
+            _, was_created = Product.objects.get_or_create(sku=item["sku"], defaults=item)
+            if was_created:
+                created += 1
+        self.stdout.write(f"Seeded {created} products ({Product.objects.count()} total).")