openreceive 0.4.4__tar.gz

openreceive-0.4.4/.gitignore

@@ -0,0 +1,82 @@
+/building/*
+
+# Local environment and deployment secrets.
+.env
+.env.*
+!.env.example
+.openreceive/
+
+private_private_infra_details.txt
+
+# Local planning files and the private scratch directory. Never committed;
+# these names have existed locally and must not reach the public repo.
+or-master-plan.txt
+or-to-do.txt
+/private/
+
+.DS_Store
+
+# Local Claude Code project memory (path-leaking, machine-specific).
+.claude/projects/
+
+# Tooling output.
+*.gem
+packages/ruby/*/Gemfile.lock
+node_modules/
+coverage/
+dist/
+.turbo/
+.vite/
+.next/
+.cache/
+.release/
+*.tsbuildinfo
+
+# PHP and Python engine toolchain output (packages/php, packages/python, the
+# Laravel/Django/FastAPI demos). Composer's vendor/ and uv's .venv/ are
+# rebuilt from composer.lock / uv.lock; never committed.
+vendor/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.phpunit.cache/
+.phpunit.result.cache
+tmp/*
+
+/logs/
+# The demos' file logger writes cwd-relative when enabled.
+examples/*/server/*/logs/
+
+# Local audit scratch lists and working files (any extension: .txt lists, the
+# .mts/.xt one-off harnesses used while chasing a bug). Never committed.
+zz-*
+**/zz*.test.mjs
+
+# Local live-test override; expected_capabilities.example.json is the tracked template.
+tools/live-nwc-test/expected_capabilities.json
+
+# Playwright artifacts
+tests/e2e/test-results/
+
+# Prisma client for the test:orms lane; `npm run test:orms` regenerates it.
+tests/orms/generated/
+
+# The Node stacks' SQLite databases and cookie secrets. The shop SURVIVES a
+# restart, so unlike a disposable checkout demo these are real local state.
+examples/buttons/.data/
+
+# .NET build output (BTCPay plugin workspace)
+packages/dotnet/**/bin/
+packages/dotnet/**/obj/
+packages/dotnet/**/bin-docker/
+packages/dotnet/**/obj-docker/
+packages/dotnet/**/TestResults/
+packages/dotnet/docker/.state/
+tests/e2e-btcpay/test-results/
+
+# The standalone checkout build copied in by hatch_build.py at wheel/sdist build time.
+packages/python/openreceive/src/openreceive/django/static/

openreceive-0.4.4/LICENSE

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

openreceive-0.4.4/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: openreceive
+Version: 0.4.4
+Summary: Receive-only Lightning checkout for Python hosts: NWC wallet kernel, settlement engine, framework-free HTTP handler, Django and FastAPI adapters.
+Project-URL: Homepage, https://openreceive.org
+Project-URL: Documentation, https://openreceive.org/guides
+Project-URL: Source, https://github.com/OpenReceive/openreceive
+Project-URL: Changelog, https://github.com/OpenReceive/openreceive/blob/master/CHANGELOG.md
+Author-email: OpenReceive <info@openreceive.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bitcoin,django,fastapi,lightning,nostr,nwc,payments
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: coincurve>=20
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets<16,>=13
+Provides-Extra: django
+Requires-Dist: django>=5.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Requires-Dist: sqlalchemy>=2; extra == 'fastapi'
+Requires-Dist: starlette>=0.40; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=3; extra == 'flask'
+Requires-Dist: sqlalchemy>=2; extra == 'flask'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# openreceive
+
+Receive-only Lightning checkout for Python hosts, over Nostr Wallet Connect.
+One distribution with framework extras:
+
+```sh
+pip install "openreceive[django]"    # Django >= 5.2
+pip install "openreceive[fastapi]"   # FastAPI >= 0.115 (sync SQLAlchemy engine for the two tables)
+pip install "openreceive[sqlalchemy]"  # plain hosts: the handler + the SQL repository
+```
+
+The package is engine #5 of the OpenReceive monorepo and reproduces the shared
+money, settlement, NIP-47 paging, swap-provider and HTTP behavior pinned by
+`spec/test-vectors/` (`tools/conformance/python-crosslang.py`). The host owns
+orders, prices and fulfillment; OpenReceive owns the `openreceive_payments` /
+`openreceive_meta` rows inside the host's database, the per-reference lock,
+write-once settlement and the reconciliation state machine.
+
+Layout:
+
+- `openreceive` — kernel: `money`, `settlement`, `nwc` (URI, info, requests,
+  errors, the `ReceiveNwcClient` protocol and the production client),
+  `payments` (wallet walk, closure decision), `swap`, `rates`.
+- `openreceive.storage` — the `PaymentRepository` protocol, the SQLAlchemy
+  Core repository (`SqlPaymentRepository`, `payments_schema_sql(dialect)`).
+- `openreceive.server` — `Service`, the framework-free `RequestHandler`
+  (request → status/body/headers), `OpenReceiveApp` (handler + repository +
+  the gated opportunistic reconcile), notifications worker, doctor, `Host`.
+- `openreceive.testing` — `FakeWallet`, `FakeSwapProvider` and the testkit
+  fixtures every engine shares (`docs/internal/testkit-contract.md`).
+
+Documentation: https://openreceive.org/guides — quickstarts for Django and
+FastAPI, the storage guide, and the host testing guide.
+
+Receive-only NWC codes must never reach browsers, logs or tests. `NWC_URI`,
+`LSC_URI_PRIMARY` and `LSC_URI_BACKUP` are read from the process environment.

openreceive-0.4.4/README.md

@@ -0,0 +1,36 @@
+# openreceive
+
+Receive-only Lightning checkout for Python hosts, over Nostr Wallet Connect.
+One distribution with framework extras:
+
+```sh
+pip install "openreceive[django]"    # Django >= 5.2
+pip install "openreceive[fastapi]"   # FastAPI >= 0.115 (sync SQLAlchemy engine for the two tables)
+pip install "openreceive[sqlalchemy]"  # plain hosts: the handler + the SQL repository
+```
+
+The package is engine #5 of the OpenReceive monorepo and reproduces the shared
+money, settlement, NIP-47 paging, swap-provider and HTTP behavior pinned by
+`spec/test-vectors/` (`tools/conformance/python-crosslang.py`). The host owns
+orders, prices and fulfillment; OpenReceive owns the `openreceive_payments` /
+`openreceive_meta` rows inside the host's database, the per-reference lock,
+write-once settlement and the reconciliation state machine.
+
+Layout:
+
+- `openreceive` — kernel: `money`, `settlement`, `nwc` (URI, info, requests,
+  errors, the `ReceiveNwcClient` protocol and the production client),
+  `payments` (wallet walk, closure decision), `swap`, `rates`.
+- `openreceive.storage` — the `PaymentRepository` protocol, the SQLAlchemy
+  Core repository (`SqlPaymentRepository`, `payments_schema_sql(dialect)`).
+- `openreceive.server` — `Service`, the framework-free `RequestHandler`
+  (request → status/body/headers), `OpenReceiveApp` (handler + repository +
+  the gated opportunistic reconcile), notifications worker, doctor, `Host`.
+- `openreceive.testing` — `FakeWallet`, `FakeSwapProvider` and the testkit
+  fixtures every engine shares (`docs/internal/testkit-contract.md`).
+
+Documentation: https://openreceive.org/guides — quickstarts for Django and
+FastAPI, the storage guide, and the host testing guide.
+
+Receive-only NWC codes must never reach browsers, logs or tests. `NWC_URI`,
+`LSC_URI_PRIMARY` and `LSC_URI_BACKUP` are read from the process environment.

openreceive-0.4.4/hatch_build.py

@@ -0,0 +1,46 @@
+"""Hatchling build hook: carry the standalone checkout build into the wheel.
+
+`openreceive.django` templates load `{% static "openreceive/openreceive-checkout.js" %}`
+and its stylesheet; those files are the output of `npm run build:packages`
+(tools/package/build-standalone-elements.mjs → packages/js/elements/dist/standalone/),
+not Python source, so they are NOT committed under src/. This hook copies that
+tree into `src/openreceive/django/static/openreceive/` whenever it exists next
+to this package in the monorepo — for `uv build` (sdist and wheel) and for the
+editable install `uv sync` performs — so the wheel carries the assets and their
+MANIFEST.json. Outside the monorepo (a wheel built from the sdist) the copy is
+already inside the sdist and nothing happens. With neither present the build
+still succeeds and warns: the engine works without the static files; only the
+packaged-static render path in the quickstart needs them.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+STANDALONE_SOURCE = Path("..", "..", "js", "elements", "dist", "standalone")
+STATIC_TARGET = Path("src", "openreceive", "django", "static", "openreceive")
+
+
+class StandaloneCheckoutHook(BuildHookInterface):  # type: ignore[type-arg]
+    PLUGIN_NAME = "standalone-checkout"
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        root = Path(self.root)
+        source = (root / STANDALONE_SOURCE).resolve()
+        target = root / STATIC_TARGET
+        if (source / "MANIFEST.json").is_file():
+            if target.exists():
+                shutil.rmtree(target)
+            shutil.copytree(source, target)
+            return
+        if (target / "MANIFEST.json").is_file():
+            return
+        self.app.display_warning(
+            f"openreceive: {STATIC_TARGET} is empty — the standalone checkout build was not found at "
+            f"{STANDALONE_SOURCE} (run `npm run build:packages` in the monorepo first). The wheel "
+            "will ship without the packaged static checkout files."
+        )

openreceive-0.4.4/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openreceive"
+dynamic = ["version"]
+description = "Receive-only Lightning checkout for Python hosts: NWC wallet kernel, settlement engine, framework-free HTTP handler, Django and FastAPI adapters."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "OpenReceive", email = "info@openreceive.org" }]
+keywords = ["lightning", "bitcoin", "nwc", "nostr", "payments", "django", "fastapi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: Django",
+  "Framework :: FastAPI",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = [
+  "coincurve>=20",
+  "cryptography>=42",
+  "websockets>=13,<16",
+  "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+django = ["Django>=5.2"]
+fastapi = ["fastapi>=0.115", "starlette>=0.40", "sqlalchemy>=2"]
+flask = ["flask>=3", "sqlalchemy>=2"]
+sqlalchemy = ["sqlalchemy>=2"]
+
+[project.urls]
+Homepage = "https://openreceive.org"
+Documentation = "https://openreceive.org/guides"
+Source = "https://github.com/OpenReceive/openreceive"
+Changelog = "https://github.com/OpenReceive/openreceive/blob/master/CHANGELOG.md"
+
+[project.scripts]
+openreceive = "openreceive.cli:main"
+
+[dependency-groups]
+dev = [
+  "pytest>=8",
+  "pytest-django>=4.9",
+  "ruff>=0.6",
+  "mypy>=1.11",
+  "sqlalchemy>=2",
+  "alembic>=1.13",
+  "fastapi>=0.115",
+  "starlette>=0.40",
+  "psycopg[binary]>=3.2",
+  "pymysql>=1.1",
+  "Django>=5.2",
+  "django-stubs>=5.2",
+]
+
+[tool.hatch.version]
+path = "src/openreceive/_version.py"
+
+# Copies packages/js/elements/dist/standalone into django/static/openreceive at
+# build time (hatch_build.py); the copy is gitignored, the wheel carries it.
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openreceive"]
+# The Django app's static checkout assets and migrations are package data
+# (hatchling needs the explicit include; verify with `unzip -l` in CI).
+include = [
+  "src/openreceive/**/*.py",
+  "src/openreceive/django/static/**",
+  "src/openreceive/django/migrations/**",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/openreceive", "README.md", "pyproject.toml", "hatch_build.py"]
+exclude = ["tests/fixtures/**"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+addopts = "-q -p no:cacheprovider"
+# The Django adapter's tests (tests/django) run through pytest-django against
+# the package's own sqlite test settings; the rest of the suite ignores them.
+DJANGO_SETTINGS_MODULE = "tests.django.settings"
+filterwarnings = ["error::DeprecationWarning:openreceive.*"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+# Generated renderings are never hand-edited (npm run generate:models owns them).
+extend-exclude = ["src/openreceive/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+ignore = ["B904", "E501"]
+
+[tool.ruff.lint.isort]
+# tests/fastapi and tests/django sit under a `src` root, so isort would
+# otherwise file the frameworks themselves as first-party.
+known-third-party = ["fastapi", "starlette", "django"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+mypy_path = "src"
+packages = ["openreceive"]
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = ["coincurve", "coincurve.*"]
+ignore_missing_imports = true

openreceive-0.4.4/src/openreceive/__init__.py

@@ -0,0 +1,27 @@
+"""OpenReceive for Python: receive-only Lightning checkout over NWC.
+
+The kernel (money, settlement, NIP-47 normalization, the wallet walk, the
+closure decision, swaps) is pure functions over dicts; the server
+(`openreceive.server`) binds it to a wallet client, a price feed and a payment
+repository, and `openreceive.django` / `openreceive.fastapi` mount the
+framework-free handler. This module re-exports only the kernel entry points
+hosts reach for directly.
+"""
+
+from openreceive._version import __version__
+from openreceive.money import quote_fiat_to_msats
+from openreceive.nwc.uri import NWC_CODE_HELP_URL, NwcUriParseError, parse_uri, redact_uri
+from openreceive.settlement import is_settled
+
+parse_nwc_uri = parse_uri
+redact_nwc_uri = redact_uri
+
+__all__ = [
+    "NWC_CODE_HELP_URL",
+    "NwcUriParseError",
+    "__version__",
+    "is_settled",
+    "parse_nwc_uri",
+    "quote_fiat_to_msats",
+    "redact_nwc_uri",
+]

openreceive-0.4.4/src/openreceive/_generated/fulfillment_note.py

@@ -0,0 +1,59 @@
+"""GENERATED FILE — DO NOT EDIT.
+
+Source: spec/data/fulfillment-note.txt (npm run generate:models).
+Twins: packages/js/core/src/generated/fulfillment-note-text.ts, packages/ruby/openreceive-rails/lib/openreceive/generated/fulfillment_note.rb,
+packages/php/openreceive/src/Generated/FulfillmentNote.php; all render the same text, so no host scaffold can
+give different advice.
+"""
+
+from typing import Final
+
+# The note's lines, with "{{table}}" awaiting the caller's table name.
+FULFILLMENT_NOTE_TEMPLATE: Final = (
+    "Fulfilling exactly once",
+    "",
+    "WHAT OPENRECEIVE GUARANTEES",
+    "",
+    "Across every settlement path OpenReceive itself owns (wallet notifications,",
+    "the opportunistic reconcile pass, an explicit reconcile job), the settlement",
+    "hook runs AT MOST ONCE per reference. The library serializes on its own",
+    "`{{table}}` rows, decides the winner there, and runs your hook",
+    "inside that same transaction. A second payment to a second invoice for the",
+    "same order is still recorded - with `status_reason = 'duplicate_settlement'`",
+    "- but never fulfills a second time. You do not need to add a lock for this.",
+    "",
+    "That makes the reference the unit of fulfillment: give every payable order",
+    "its own reference, created before checkout, kept across retries, and never",
+    "reused. A new checkout under a reference that has already settled is refused",
+    "with a 409 rather than fulfilled again; a fresh reference per page load",
+    "leaves one order payable twice.",
+    "",
+    "WHAT YOU MUST GUARANTEE",
+    "",
+    "OpenReceive cannot see fulfillment that happens outside it. If ANY other",
+    "path can also mark this order fulfilled - an admin action, a second payment",
+    "processor, a support tool, a replayed webhook, a retried background job -",
+    "then those paths race each other, not OpenReceive, and you must make",
+    "fulfillment idempotent yourself.",
+    "",
+    "The usual way is to make the transition itself the lock: guard it with a",
+    "conditional write that only one transaction can win.",
+    "",
+    "  -- Idempotent by construction: the WHERE clause is the guard. Whoever",
+    "  -- flips 'awaiting_payment' -> 'paid' first is the only one who fulfills;",
+    "  -- every later attempt updates 0 rows and must do nothing.",
+    "  UPDATE orders",
+    "     SET state = 'paid', paid_at = :paid_at",
+    "   WHERE id = :reference",
+    "     AND state = 'awaiting_payment';",
+    "  -- then: if 0 rows were affected, return without shipping anything.",
+    "",
+    "If your fulfillment is a read-modify-write that cannot be expressed as one",
+    "conditional UPDATE, take a row lock for the duration instead:",
+    "",
+    "  SELECT * FROM orders WHERE id = :reference FOR UPDATE;  -- postgres/mysql",
+    "  -- ...check state, ship, write the new state, all before COMMIT.",
+    "",
+    "Run either one inside the transaction OpenReceive hands your settlement",
+    "hook, so the order transition and the payment record commit together.",
+)