tuppence 0.1.0__tar.gz

tuppence-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+node_modules/
+dist/
+# The booking origin's quality gates build here (apps/web/playwright.book.config.ts).
+dist-book/
+dist-store/
+# …and the browser POS's acceptance test here (apps/web/playwright.pos.config.ts).
+dist-pos/
+# …and M32's quality gate for it here (apps/web/playwright.pos-gate.config.ts).
+dist-pos-gate/
+coverage/
+*.tsbuildinfo
+.DS_Store
+
+# env and secrets — never commit
+.env
+.env.*
+!.env.example
+infra/gcp/*.env
+!infra/gcp/*.env.example
+*-key.json
+*.pem
+
+# local tooling
+.firebase/
+.vite/
+.worktrees/
+worktrees/
+playwright-report/
+# The press pack's renders (plan/102): published to R2 by press-publish, never committed.
+apps/press/out/
+# The assistant eval's reports (apps/api: pnpm assistant:eval)
+eval-reports/
+test-results/
+/tmp/
+
+# python (packages/python)
+.venv
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# The iOS release build's output: archives and .ipa files, hundreds of MB apiece.
+apps/mobile/build/
+
+# Swift Package Manager (packages/ios): the build and Xcode's package state.
+.build/
+.swiftpm/
+
+# Wrangler's local state (infra/cloudflare: the edge Worker's deploy).
+.wrangler/
+
+# 81-26: sandbox refresh tokens for the live accounting suites (accounting:consent)
+.accounting-sandbox/
+
+# CI: the inputs each workspace package was built from (scripts/package-builds.mjs)
+.ci-builds/

tuppence-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: tuppence
+Version: 0.1.0
+Summary: The Tuppence API for Python — payments for developers and AI agents.
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: black==26.10.1; extra == 'dev'
+Requires-Dist: cryptography>=42; extra == 'dev'
+Requires-Dist: datamodel-code-generator==0.34.0; extra == 'dev'
+Requires-Dist: isort==6.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
+Provides-Extra: http402
+Requires-Dist: cryptography>=42; extra == 'http402'
+Description-Content-Type: text/markdown
+
+# tuppence
+
+The Tuppence API for Python — payments for developers and AI agents.
+
+```bash
+pip install tuppence
+```
+
+```python
+import os
+from tuppence import Tuppence
+
+tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])
+
+link = tuppence.payment_links.create(name="Research report", amount=2000, currency="gbp")
+print(link.url)  # send it to whoever should pay
+
+for payment in tuppence.payments.list_all(status="succeeded"):
+    print(payment.id, payment.amount, payment.fee, payment.net)  # integer pence
+```
+
+Python 3.10+. Money is always an integer number of minor units (pence).
+
+## Async
+
+```python
+from tuppence import AsyncTuppence
+
+async with AsyncTuppence(os.environ["TUPPENCE_SECRET_KEY"]) as tuppence:
+    payment = await tuppence.payments.create(amount=2000, currency="gbp")
+    async for refund in tuppence.refunds.list_all(payment=payment.id):
+        ...
+```
+
+## Retries and idempotency
+
+Every POST carries an `Idempotency-Key`: yours, or a fresh one reused by every retry of that
+call — so retrying after a timeout never charges twice. Network errors, timeouts, `5xx`, `429`
+(honouring `Retry-After`) and an idempotent request still in flight are retried twice by default,
+with jittered backoff. Nothing else is.
+
+```python
+tuppence.refunds.create(payment="pay_…", amount=500, idempotency_key="order-42-refund")
+tuppence = Tuppence(key, max_retries=4, timeout=10)  # client-wide
+tuppence.balance.retrieve(max_retries=0, timeout=2)  # per request
+```
+
+## Another API address
+
+The SDK calls `https://api.tuppence.ai`. To use another Tuppence environment you have been given,
+set `TUPPENCE_API_URL`, or pass `base_url`:
+
+```python
+tuppence = Tuppence(key, base_url="https://…")
+```
+
+## Errors
+
+```python
+from tuppence import CardError, InvalidRequestError
+
+try:
+    tuppence.refunds.create(payment="pay_…", amount=10_000)
+except InvalidRequestError as e:
+    print(e.code, e.param, e.request_id)  # branch on `code`; quote `request_id` to support
+```
+
+`CardError`, `InvalidRequestError`, `AuthenticationError`, `PermissionError`, `RateLimitError`,
+`IdempotencyError`, `APIError` and `ConnectionError` all derive from `TuppenceError`.
+
+## Webhooks
+
+```python
+event = tuppence.webhooks.construct_event(
+    request.body,  # the RAW body, exactly as received
+    request.headers["Tuppence-Signature"],
+    os.environ["TUPPENCE_WEBHOOK_SECRET"],
+)
+```
+
+A wrong secret, a tampered body or a timestamp more than five minutes old raises
+`SignatureVerificationError` — never act on that payload.
+
+## Tuppence Connect: acting as your connected accounts
+
+A platform's connected accounts are full Tuppence accounts. Make one, send its owner onboarding,
+then act as it with your own key — per call, or through a client bound to it:
+
+```python
+bella = tuppence.accounts.create(email="bella@example.com", business_type="individual")
+link = tuppence.account_links.create(
+    account=bella.id,
+    type="account_onboarding",
+    refresh_url="https://groomly.example/onboarding/refresh",
+    return_url="https://groomly.example/onboarding/done",
+)
+
+# One call as Bella: the `Tuppence-Account` header, never part of the path.
+tuppence.payments.create(
+    amount=4500, currency="gbp", application_fee_amount=100, tuppence_account=bella.id
+)
+
+# Or a client bound to her — a new one, on the same connections: `tuppence` is unchanged.
+as_bella = tuppence.as_account(bella.id)
+as_bella.bookings.list()
+```
+
+`accounts.persons`, `.external_accounts` and `.capabilities`, and `files.create(purpose=…,
+file=open("passport.png", "rb"))` are the rest of onboarding through your own forms.
+`application_fees` (and `.refunds`) and `transfers` (and `.reversals`) are the money, and
+`balance.list_transactions(balance="connect")` lists your Connect balance's every movement. The
+async client has the same, method for method. A Connect webhook's event says which account it happened
+on: `event["account"]`.
+
+## HTTP 402: put a price on a route
+
+```python
+from tuppence.http402 import Http402Middleware, PayWall
+
+app.add_middleware(  # FastAPI, Starlette, any ASGI app
+    Http402Middleware,
+    routes={"GET /v1/report": PayWall(AsyncTuppence(key), price=50, currency="gbp")},
+)
+```
+
+`pip install "tuppence[http402]"`. Unpaid requests get `402 Payment Required` with where to pay;
+the caller pays and retries with `Authorization: Tuppence-Receipt <token>` — verified offline
+against Tuppence's published keys, and accepted once. Agents with prepaid credit pay with
+`Authorization: Tuppence-Credits <token>` (`credits_meter=`). `paid_tool` does the same for a
+tool on a Python MCP server.
+
+## Payouts and prices
+
+`tuppence.payouts.settings()` says when money is paid out and what could change it;
+`.instant_quote()` and `.create(method="instant")` move pending money now, and
+`.set_next_day(enabled=True)` switches next-day payouts (UK) on or off once `next_day.available`
+says so. `tuppence.account.retrieve_pricing()` is every price the account pays — the list's, or
+one agreed with Tuppence, with its dates.
+
+## Models
+
+Responses are pydantic models generated from the API's OpenAPI contract
+(`apps/api/openapi.public.json`). Fields the API adds later are kept (`model_extra`), so an older
+SDK still sees everything the server sent. Anything without a method yet:
+`tuppence.request("GET", "/v1/…")` — same auth, retries and idempotency.

tuppence-0.1.0/README.md

@@ -0,0 +1,145 @@
+# tuppence
+
+The Tuppence API for Python — payments for developers and AI agents.
+
+```bash
+pip install tuppence
+```
+
+```python
+import os
+from tuppence import Tuppence
+
+tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])
+
+link = tuppence.payment_links.create(name="Research report", amount=2000, currency="gbp")
+print(link.url)  # send it to whoever should pay
+
+for payment in tuppence.payments.list_all(status="succeeded"):
+    print(payment.id, payment.amount, payment.fee, payment.net)  # integer pence
+```
+
+Python 3.10+. Money is always an integer number of minor units (pence).
+
+## Async
+
+```python
+from tuppence import AsyncTuppence
+
+async with AsyncTuppence(os.environ["TUPPENCE_SECRET_KEY"]) as tuppence:
+    payment = await tuppence.payments.create(amount=2000, currency="gbp")
+    async for refund in tuppence.refunds.list_all(payment=payment.id):
+        ...
+```
+
+## Retries and idempotency
+
+Every POST carries an `Idempotency-Key`: yours, or a fresh one reused by every retry of that
+call — so retrying after a timeout never charges twice. Network errors, timeouts, `5xx`, `429`
+(honouring `Retry-After`) and an idempotent request still in flight are retried twice by default,
+with jittered backoff. Nothing else is.
+
+```python
+tuppence.refunds.create(payment="pay_…", amount=500, idempotency_key="order-42-refund")
+tuppence = Tuppence(key, max_retries=4, timeout=10)  # client-wide
+tuppence.balance.retrieve(max_retries=0, timeout=2)  # per request
+```
+
+## Another API address
+
+The SDK calls `https://api.tuppence.ai`. To use another Tuppence environment you have been given,
+set `TUPPENCE_API_URL`, or pass `base_url`:
+
+```python
+tuppence = Tuppence(key, base_url="https://…")
+```
+
+## Errors
+
+```python
+from tuppence import CardError, InvalidRequestError
+
+try:
+    tuppence.refunds.create(payment="pay_…", amount=10_000)
+except InvalidRequestError as e:
+    print(e.code, e.param, e.request_id)  # branch on `code`; quote `request_id` to support
+```
+
+`CardError`, `InvalidRequestError`, `AuthenticationError`, `PermissionError`, `RateLimitError`,
+`IdempotencyError`, `APIError` and `ConnectionError` all derive from `TuppenceError`.
+
+## Webhooks
+
+```python
+event = tuppence.webhooks.construct_event(
+    request.body,  # the RAW body, exactly as received
+    request.headers["Tuppence-Signature"],
+    os.environ["TUPPENCE_WEBHOOK_SECRET"],
+)
+```
+
+A wrong secret, a tampered body or a timestamp more than five minutes old raises
+`SignatureVerificationError` — never act on that payload.
+
+## Tuppence Connect: acting as your connected accounts
+
+A platform's connected accounts are full Tuppence accounts. Make one, send its owner onboarding,
+then act as it with your own key — per call, or through a client bound to it:
+
+```python
+bella = tuppence.accounts.create(email="bella@example.com", business_type="individual")
+link = tuppence.account_links.create(
+    account=bella.id,
+    type="account_onboarding",
+    refresh_url="https://groomly.example/onboarding/refresh",
+    return_url="https://groomly.example/onboarding/done",
+)
+
+# One call as Bella: the `Tuppence-Account` header, never part of the path.
+tuppence.payments.create(
+    amount=4500, currency="gbp", application_fee_amount=100, tuppence_account=bella.id
+)
+
+# Or a client bound to her — a new one, on the same connections: `tuppence` is unchanged.
+as_bella = tuppence.as_account(bella.id)
+as_bella.bookings.list()
+```
+
+`accounts.persons`, `.external_accounts` and `.capabilities`, and `files.create(purpose=…,
+file=open("passport.png", "rb"))` are the rest of onboarding through your own forms.
+`application_fees` (and `.refunds`) and `transfers` (and `.reversals`) are the money, and
+`balance.list_transactions(balance="connect")` lists your Connect balance's every movement. The
+async client has the same, method for method. A Connect webhook's event says which account it happened
+on: `event["account"]`.
+
+## HTTP 402: put a price on a route
+
+```python
+from tuppence.http402 import Http402Middleware, PayWall
+
+app.add_middleware(  # FastAPI, Starlette, any ASGI app
+    Http402Middleware,
+    routes={"GET /v1/report": PayWall(AsyncTuppence(key), price=50, currency="gbp")},
+)
+```
+
+`pip install "tuppence[http402]"`. Unpaid requests get `402 Payment Required` with where to pay;
+the caller pays and retries with `Authorization: Tuppence-Receipt <token>` — verified offline
+against Tuppence's published keys, and accepted once. Agents with prepaid credit pay with
+`Authorization: Tuppence-Credits <token>` (`credits_meter=`). `paid_tool` does the same for a
+tool on a Python MCP server.
+
+## Payouts and prices
+
+`tuppence.payouts.settings()` says when money is paid out and what could change it;
+`.instant_quote()` and `.create(method="instant")` move pending money now, and
+`.set_next_day(enabled=True)` switches next-day payouts (UK) on or off once `next_day.available`
+says so. `tuppence.account.retrieve_pricing()` is every price the account pays — the list's, or
+one agreed with Tuppence, with its dates.
+
+## Models
+
+Responses are pydantic models generated from the API's OpenAPI contract
+(`apps/api/openapi.public.json`). Fields the API adds later are kept (`model_extra`), so an older
+SDK still sees everything the server sent. Anything without a method yet:
+`tuppence.request("GET", "/v1/…")` — same auth, retries and idempotency.

tuppence-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tuppence"
+version = "0.1.0"
+description = "The Tuppence API for Python — payments for developers and AI agents."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "pydantic>=2.7,<3"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+# HTTP 402 for Python (tuppence.http402): receipts are Ed25519-signed, verified offline.
+http402 = ["cryptography>=42"]
+dev = [
+  "cryptography>=42",
+  "starlette>=0.37",
+  "pytest>=8",
+  "ruff>=0.6",
+  "mypy>=1.10",
+  # Pinned, with the formatters it runs: the generated models are committed, and a new version
+  # of any of the three reformats them (scripts/generate.py --check would then fail).
+  "datamodel-code-generator==0.34.0",
+  "black==26.10.1",
+  "isort==6.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tuppence"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# Generated (scripts/generate.py). Their sources are linted; mypy still checks both.
+extend-exclude = ["src/tuppence/models.py", "src/tuppence/_sync_resources.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+files = ["src/tuppence"]
+plugins = ["pydantic.mypy"]

tuppence-0.1.0/scripts/generate.py

@@ -0,0 +1,142 @@
+"""Generates what the SDK does not write by hand (plan 11-03), and checks it is current.
+
+    python scripts/generate.py           # write
+    python scripts/generate.py --check   # fail if anything is stale (CI)
+
+1. ``src/tuppence/models.py`` — pydantic models from ``apps/api/openapi.public.json``. The
+   server validates what it is SENT; the SDK only reads what comes back, so length, pattern and
+   range constraints are dropped before generating — an answer is never refused for being, say,
+   an empty string the spec calls ``minLength: 1`` — and so are enums: a status the API adds next
+   year must not break parsing in an SDK installed today.
+2. ``src/tuppence/_sync_resources.py`` — the synchronous resources, from the async ones
+   (``_async_resources.py`` is the source of truth), the way ``unasync`` keeps httpcore's two
+   halves identical: one set of methods, two clients that cannot drift.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SPEC = ROOT.parent.parent / "apps" / "api" / "openapi.public.json"
+MODELS = ROOT / "src" / "tuppence" / "models.py"
+ASYNC = ROOT / "src" / "tuppence" / "_async_resources.py"
+SYNC = ROOT / "src" / "tuppence" / "_sync_resources.py"
+
+DROPPED = {
+    "minLength",
+    "maxLength",
+    "pattern",
+    "minimum",
+    "maximum",
+    "minItems",
+    "maxItems",
+    "multipleOf",
+    "enum",
+}
+
+
+def _loosen(node: object) -> object:
+    if isinstance(node, list):
+        return [_loosen(item) for item in node]
+    if isinstance(node, dict):
+        return {k: _loosen(v) for k, v in node.items() if k not in DROPPED}
+    return node
+
+
+def _keep_store_event_types(raw: dict, spec: dict) -> dict:
+    """Each store event's ``type`` stays its one value (94-06): ``StoreEvent`` is a union
+    discriminated by it, so ``event.type == "order.created"`` narrows ``event.data.object``. A
+    new event type is a new schema, never a new value of an old one, so nothing breaks."""
+    schemas = raw["components"]["schemas"]
+    for item in schemas.get("StoreEvent", {}).get("oneOf", []):
+        name = item["$ref"].rsplit("/", 1)[-1]
+        spec["components"]["schemas"][name]["properties"]["type"] = schemas[name]["properties"][
+            "type"
+        ]
+    return spec
+
+
+def models() -> str:
+    from datamodel_code_generator import DataModelType, InputFileType, LiteralType, generate
+    from datamodel_code_generator.format import PythonVersion
+
+    raw = json.loads(SPEC.read_text())
+    spec = _keep_store_event_types(raw, _loosen(raw))
+    with tempfile.TemporaryDirectory() as tmp:
+        source = Path(tmp) / "openapi.public.json"
+        source.write_text(json.dumps(spec))
+        target = Path(tmp) / "models.py"
+        generate(
+            source,
+            input_file_type=InputFileType.OpenAPI,
+            output=target,
+            output_model_type=DataModelType.PydanticV2BaseModel,
+            target_python_version=PythonVersion.PY_310,
+            base_class="tuppence._model.TuppenceModel",
+            use_standard_collections=True,
+            use_union_operator=True,
+            use_schema_description=True,
+            use_field_description=True,
+            strict_nullable=True,
+            # Only the store events' one-value `type`s keep an enum (see above): a Literal each.
+            enum_field_as_literal=LiteralType.One,
+            disable_timestamp=True,
+            custom_file_header=(
+                "# GENERATED from apps/api/openapi.public.json by scripts/generate.py.\n"
+                "# Do not edit: regenerate whenever the API contract changes."
+            ),
+        )
+        return target.read_text()
+
+
+# async → sync, token by token. Order matters: the longer patterns first.
+UNASYNC = [
+    (r"AsyncIterator", "Iterator"),
+    (r"AsyncHttpClient", "SyncHttpClient"),
+    (r"async def ", "def "),
+    (r"async for ", "for "),
+    (r"await ", ""),
+    (r"\bAsync([A-Z]\w*)", r"\1"),
+    (r"_async_resources", "_sync_resources"),
+]
+
+
+def sync_resources() -> str:
+    text = ASYNC.read_text()
+    for pattern, replacement in UNASYNC:
+        text = re.sub(pattern, replacement, text)
+    header = (
+        "# GENERATED from _async_resources.py by scripts/generate.py — do not edit.\n"
+        "# Change the async resources and regenerate: the two clients cannot drift.\n"
+    )
+    return header + text
+
+
+def main() -> int:
+    check = "--check" in sys.argv
+    stale = []
+    for path, text in ((MODELS, models()), (SYNC, sync_resources())):
+        if check:
+            if not path.exists() or path.read_text() != text:
+                stale.append(path.relative_to(ROOT))
+        else:
+            path.write_text(text)
+            print(f"wrote {path.relative_to(ROOT)}")
+    if stale:
+        print(
+            f"stale: {', '.join(map(str, stale))} — run `python scripts/generate.py` and commit",
+            file=sys.stderr,
+        )
+        return 1
+    if check:
+        print("generated files are current")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tuppence-0.1.0/src/tuppence/__init__.py

@@ -0,0 +1,111 @@
+"""The Tuppence API for Python — payments for developers and AI agents.
+
+from tuppence import Tuppence
+tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])
+payment = tuppence.payments.create(amount=2000, currency="gbp")
+"""
+
+from . import models
+from ._client import AsyncTuppence, Tuppence
+from ._errors import (
+    APIError,
+    AuthenticationError,
+    CardError,
+    ConnectionError,
+    IdempotencyError,
+    InvalidRequestError,
+    PermissionError,
+    RateLimitError,
+    SignatureVerificationError,
+    TuppenceError,
+)
+from ._http import DEFAULT_API_VERSION, VERSION
+from ._model import Page, TuppenceModel
+from ._webhooks import (
+    DEFAULT_TOLERANCE_SECONDS,
+    SIGNATURE_HEADER,
+    construct_event,
+    construct_store_event,
+    generate_test_header,
+)
+
+# The objects by the names a developer uses.
+Account = models.AccountModel
+#: Every price the account pays now — the list's, or one agreed with Tuppence.
+AccountPricing = models.AccountPricingModel
+Payment = models.PaymentModel
+Refund = models.RefundModel
+Customer = models.CustomerModel
+PaymentLink = models.PaymentLinkModel
+Balance = models.BalanceModel
+BalanceTransaction = models.BalanceTransactionModel
+Payout = models.PayoutModel
+#: What an instant move would cost, to the bank or the card balance — or why it can't be made.
+InstantPayoutQuote = models.InstantPayoutQuoteModel
+PayoutSettings = models.PayoutSettingsModel
+Dispute = models.DisputeModel
+Event = models.EventModel
+# Any of the store's webhook events (94-06): `.root` narrows on `type`.
+StoreEvent = models.StoreEvent
+WebhookEndpoint = models.WebhookEndpointModel
+Meter = models.MeterModel
+CreditBalance = models.CreditBalanceModel
+# Tuppence Connect: a platform's connected accounts, and onboarding them.
+ConnectedAccount = models.ConnectAccountModel
+AccountLink = models.AccountLinkModel
+Person = models.PersonModel
+ExternalAccount = models.ExternalAccountModel
+Capability = models.CapabilityModel
+ApplicationFee = models.ApplicationFeeModel
+Transfer = models.TransferModel
+
+__version__ = VERSION
+
+__all__ = [
+    "APIError",
+    "Account",
+    "AccountLink",
+    "AccountPricing",
+    "ApplicationFee",
+    "AsyncTuppence",
+    "AuthenticationError",
+    "Balance",
+    "BalanceTransaction",
+    "Capability",
+    "CardError",
+    "ConnectedAccount",
+    "ConnectionError",
+    "CreditBalance",
+    "Customer",
+    "DEFAULT_API_VERSION",
+    "DEFAULT_TOLERANCE_SECONDS",
+    "Dispute",
+    "Event",
+    "ExternalAccount",
+    "IdempotencyError",
+    "InstantPayoutQuote",
+    "InvalidRequestError",
+    "Meter",
+    "Page",
+    "Payment",
+    "PaymentLink",
+    "Payout",
+    "PayoutSettings",
+    "PermissionError",
+    "Person",
+    "RateLimitError",
+    "Refund",
+    "SIGNATURE_HEADER",
+    "SignatureVerificationError",
+    "StoreEvent",
+    "Transfer",
+    "Tuppence",
+    "TuppenceError",
+    "TuppenceModel",
+    "VERSION",
+    "WebhookEndpoint",
+    "construct_event",
+    "construct_store_event",
+    "generate_test_header",
+    "models",
+]