v1.0.0-dev: slim to the real product — merchant state machine only

cardano_checkout/__init__.py

@@ -1,68 +1,71 @@
-"""cardano_checkout — Python SDK for merchant-side Cardano payments + NFT cert minting.
+"""cardano-checkout — merchant-side Cardano payment lifecycle in Python.
 
-Zero-custody by design: consumers provide a wallet xpub (account-level
-extended public key). The SDK derives unique receive addresses per
-invoice, polls the chain for payment, and (optionally) mints a CIP-25
-NFT certificate of authenticity on confirmation.
+Zero-custody by design: the merchant brings a wallet xpub and an
+:class:`~cardano_checkout.store.InvoiceStore` implementation. The SDK
+owns the payment lifecycle — per-invoice receive-address bookkeeping,
+Koios UTxO polling, confirm / underpay / overpay classification, and
+time-windowed repricing against a consumer-supplied oracle.
+
+**The SDK deliberately does NOT ship Cardano primitives.** Address
+derivation, transaction building, chain context, and native-script
+minting all live in `pycardano <https://github.com/Python-Cardano/pycardano>`_
+and are consumer concerns. See the README for the pairing pattern and
+for the CIP-25 v2 metadata-builder snippet (a 60-line helper that fits
+anywhere in your own code without needing a separate dep).
 
 Quick start::
 
-    from cardano_checkout import addresses, oracles
+    from cardano_checkout import Invoice, InvoiceStatus, InMemoryStore, InvoiceScheduler
 
-    addr = addresses.derive_address(xpub_hex, index=42, network="mainnet")
-    price = await oracles.get_ada_usd_price()
-    lovelace = await oracles.convert_usd_to_lovelace(99.00)
+    store = InMemoryStore()  # or your SQLAlchemy / asyncpg / sqlite adapter
 
-For full invoice lifecycle see :mod:`cardano_checkout.invoice` +
-:mod:`cardano_checkout.store` (Protocol-based persistence).
+    async def my_price_fn(usd: float) -> int:
+        # your oracle — CoinGecko / Koios ticker / fixed rate in tests
+        rate = await fetch_ada_usd_rate()
+        return int(round(usd / rate * 1_000_000))
 
-For NFT minting see :mod:`cardano_checkout.mint`.
+    scheduler = InvoiceScheduler(store=store, price_fn=my_price_fn)
+    await scheduler.start()
 """
 
 from __future__ import annotations
 
-__version__ = "0.2.0-dev"
+__version__ = "1.0.0-dev"
 
-# Pure modules — stable API from extraction
-from cardano_checkout import addresses, oracles  # noqa: F401
-
-# Payment lifecycle
 from cardano_checkout.invoice import Invoice, InvoiceStatus  # noqa: F401
 from cardano_checkout.store import InMemoryStore, InvoiceStore  # noqa: F401
-
-# Monitoring + scheduling
 from cardano_checkout.monitor import (  # noqa: F401
+    CONFIRM_TOLERANCE,
+    DEFAULT_MAX_REPRICINGS,
+    DEFAULT_PAYMENT_WINDOW_MINUTES,
+    KOIOS_URL,
+    OVERPAY_THRESHOLD,
+    PriceFn,
+    check_address_utxos,
     check_pending_invoices,
+    evaluate_utxos,
     reprice_expired_invoices,
 )
 from cardano_checkout.scheduler import InvoiceScheduler  # noqa: F401
 
-# NFT + IPFS
-from cardano_checkout.mint import (  # noqa: F401
-    MintPolicy,
-    UnsignedMint,
-    build_cip25_metadata,
-    mint_nft_cert,
-    submit_signed_tx,
-)
-from cardano_checkout.ipfs import IPFSClient, pin_bytes  # noqa: F401
-
 __all__ = [
     "__version__",
-    "addresses",
-    "oracles",
+    # Invoice lifecycle
     "Invoice",
     "InvoiceStatus",
+    # Persistence
     "InvoiceStore",
     "InMemoryStore",
+    # Monitor + scheduler
+    "PriceFn",
     "InvoiceScheduler",
+    "check_address_utxos",
     "check_pending_invoices",
+    "evaluate_utxos",
     "reprice_expired_invoices",
-    "MintPolicy",
-    "UnsignedMint",
-    "mint_nft_cert",
-    "submit_signed_tx",
-    "build_cip25_metadata",
-    "IPFSClient",
-    "pin_bytes",
+    "KOIOS_URL",
+    "CONFIRM_TOLERANCE",
+    "OVERPAY_THRESHOLD",
+    "DEFAULT_MAX_REPRICINGS",
+    "DEFAULT_PAYMENT_WINDOW_MINUTES",
 ]