keble-payment 2.4.1__tar.gz

keble_payment-2.4.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

keble_payment-2.4.1/.gitignore

@@ -0,0 +1,163 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintainted in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+.vscode/
+.cursor/
+.idea/
+.lprof/
+.ruff_cache/
+
+# Local payment-provider test keys belong outside git.
+tests/**/*.pem
+
+run_copy_readme.sh
+.claude

keble_payment-2.4.1/.python-version

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

keble_payment-2.4.1/AGENTS.md

@@ -0,0 +1,24 @@
+# keble-payment Agent Notes
+
+## Testing Guideline
+
+- Follow root `../../TESTING_GUIDELINE.md` for all payment test work.
+- The Keble development default is local-full and runs Mongo/Redis integration tests while excluding hosted providers:
+  `RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 uv run pytest -q -m "not live and not container"`.
+- Keep the portable-offline fallback for machines without local DBs:
+  `uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"`.
+- Real Stripe, Alipay, PayPal, container, live, and eval tests must be explicitly marked and env-gated.
+- Prefer shared `keble_db.testing` helpers for new DB tests instead of ad hoc database cleanup.
+- Payment integration tests must use per-test Mongo databases and Redis namespaces from `keble_db.testing`; do not add broad collection deletes against shared databases.
+- Keep payment-specific reusable test settings and asset helpers in `keble_payment.testing`; do not recreate root `tests/config.py`, root `tests/helpers.py`, or `tests/support`.
+- If payment or DB test data is missing, enrich `keble_payment.testing` or `keble_db.testing` first instead of creating another downstream-only fixture.
+- Keep executable tests only under canonical layer roots: `tests/unit`, `tests/integration`, `tests/live`, `tests/contract`, `tests/evals`, and `tests/db_stack`.
+- Put pure schema/client-shape tests in the `unit` layer and real Mongo/Redis behavior in the `integration db` layer that runs in local-full with `RUN_INTEGRATION=1 RUN_REAL_DB=1`.
+- Do not add provider-specific pytest markers such as Stripe, Alipay, or PayPal. Use canonical `live` plus provider env guards, paths, or `-k` selection for provider slices.
+- Once a provider live slice is explicitly enabled and credentials are present, provider request/schema errors must fail the test; do not catch provider exceptions and convert them to skips.
+- Do not cache successful provider responses to skip real Stripe, Alipay, PayPal, Keepa, LLM, or embedding checks. Keep live tests tiny and explicit.
+- Future payment quality or provider-contract regression datasets belong under `tests/evals` with `eval`; selecting `-m eval` is enough, so do not add a generic `RUN_EVALS` gate.
+- Update `README.md`, `docs/testing.md`, `AGENTS.md`/`CLAUDE.md`, and `AiAgentChangesLogs.md` when test infrastructure changes.
+- Update `docs/testing.md` timing tables whenever test counts, speed, or layer gates change.
+- After Python test or fixture changes, run local-full, portable-offline, unit, eval, relevant integration/live selectors, `npx --yes pyright .`, and `uv build` from this repo root.
+- `pyrightconfig.json` currently keeps payment pyright as a Python 3.13 syntax/import sanity gate, not a strict full-repo type gate; do not claim strict type cleanliness until that config is intentionally tightened and still passes.

keble_payment-2.4.1/AiAgentChangesLogs.md

@@ -0,0 +1,160 @@
+# Ai Agent Changes Logs
+
+Historical entries before 2026-06-30 23:13 were moved to `logs/AiAgentChangesLogs.20260630.md`.
+
+## 2026-07-03 03:37 CST
+State: branch `refactor/local-db-evals-keble-payment`; local-full DB default and eval-selector alignment.
+
+zma:
+- Follow `prompts/20260702/1.8-pytests-heavy.md` repo by repo.
+- Make local DB-heavy tests run in the default local-full development selector.
+- Keep eval-quality tests under `tests/evals` with `eval` marks and run the eval selector too.
+
+Ai:
+- Tightened payment integration gating to the shared `RUN_INTEGRATION=1 RUN_REAL_DB=1` local-full shape while keeping Stripe/Alipay/PayPal live providers behind separate live env gates.
+- Updated README, AGENTS, CLAUDE, and `docs/testing.md` so local-full is the development default, portable-offline is the no-DB fallback, and future payment quality/provider-contract datasets belong under `tests/evals` with `eval` marks and no generic `RUN_EVALS` gate.
+- Refreshed the timing table and `uv.lock` to the current local `keble-helpers 1.46.0` path dependency exposed by the proof run.
+- Proof: local-full `RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 uv run pytest -q -m "not live and not container"` `344 passed, 6 deselected` in 29.79s; portable-offline `279 passed, 71 deselected` in 3.46s; unit `279 passed, 71 deselected` in 3.41s; eval selector `350 deselected` in 2.12s; contract selector `350 deselected` in 2.11s; db_stack selector `350 deselected` in 2.12s; integration `65 passed, 285 deselected` in 4.05s; Stripe live `1 passed, 3 skipped` in 3.65s; Alipay live `2 skipped` in 1.46s with `RUN_ALIPAY_TRANSFER_LIVE` intentionally not enabled; `npx --yes pyright .` `0 errors` in 3.58s; `uv lock --check` passed; `uv build` produced sdist and wheel.
+
+## 2026-07-02 15:32 CST
+State: branch `feature/service-pricing-policies`; package version `2.3.2`.
+
+zma:
+- Persist service pricing policy facts on orders so users and callbacks know the purchase used a limited-time deal or other pricing policy.
+
+Ai:
+- Added `OrderPricingPolicySnapshot` and optional `pricing_policy_snapshot` on orders without changing amount math.
+- Threaded the snapshot through `OrderClient.acreate_order` so backend checkout can store policy/tag/original/base/deal price and linked-claim facts.
+- Added focused order schema coverage proving the snapshot is stored separately from the charged amount.
+
+## 2026-07-02 13:49 CST
+State: branch `refactor/harden-pytests-keble-payment`; payment tests now use per-test DB/Redis isolation and backend-env-aware live config.
+
+zma:
+- Continue the cross-repo pytest hardening follow-up.
+- Reconsider over-trimmed real tests, remove weak skip/pass patterns, use shared backend env credentials, and keep canonical marks aligned.
+
+Ai:
+- Bumped `keble-payment` to `2.3.1`, required `keble-db>=1.8.1`, and added `httpx[socks]` so provider clients work under SOCKS proxy environments.
+- Routed payment test settings through `keble_db.testing.resolve_test_env`, including backend `.env` aliases for Mongo, Redis, Stripe, Alipay, and PayPal.
+- Replaced broad Mongo cleanup with per-test Mongo databases and Redis namespaces from `keble_db.testing.create_test_namespace`.
+- Kept ordinary integration tests offline by patching only Alipay payment-url construction outside live tests, while preserving real Alipay/Stripe behavior in guarded live slices.
+- Strengthened coupon/order/webhook tests by replacing manual try/except, placeholder skips, and weak concurrency checks with specific assertions.
+- Updated README, docs/testing.md, AGENTS.md, and CLAUDE.md with namespace isolation, env resolution, no provider-success caching, and current timing proof.
+- Proof: default offline pytest `278 passed, 71 deselected` in `1.61s`; unit `278 passed, 71 deselected` in `1.61s`; integration `65 passed, 284 deselected` in `1.74s`; Stripe live `1 passed, 3 skipped` in `2.07s`; Alipay live `2 skipped`; `npx --yes pyright .` `0 errors`.
+
+## 2026-07-01 17:22 CST
+State: branch `refactor/testing-quality-audit-payment-live`; live Stripe checkout-session tests strengthened.
+
+zma:
+- Continue the cross-repo testing follow-up audit from `prompts/202060701/1.1-tests-enrich-and-run.md`.
+- Ensure real/live tests are useful and not weakened into skip-on-failure behavior.
+
+Ai:
+- Removed broad exception-to-skip handling from Stripe checkout-session live tests so explicitly enabled live provider request/schema failures fail the test instead of being reported as skips.
+- Kept skips only for missing live preconditions such as `STRIPE_TEST_API_KEY`, `STRIPE_TEST_PRICE_ID`, or missing dependent session state.
+- Strengthened the checkout-session list assertion to validate returned item shape instead of asserting a non-negative list length.
+- Updated README, docs/testing.md, AGENTS.md, and CLAUDE.md with the provider-live failure contract.
+
+## 2026-07-01 15:49 CST
+State: branch `refactor/testing-quality-audit-keble-payment`; follow-up audit for skipped Stripe payment-intent tests.
+
+zma:
+- Continue the cross-repo testing follow-up audit from `prompts/202060701/1.1-tests-enrich-and-run.md`.
+- Replace skipped or placeholder tests with meaningful behavior assertions instead of weakening coverage.
+
+Ai:
+- Replaced two permanently skipped tests for removed `OrderClient._acreate_stripe_payment_intent` with current `_aget_payment_by_stripe_payment_intent` webhook-path assertions.
+- Covered missing webhook intent persistence, typed `DataIntegrityCompromised` wrapping for failed payload persistence, and subscription-style payment intents that intentionally return `None` when no payment is linked.
+- Proof: focused `tests/unit/stripe_api/test_order_apis.py` `53 passed`; default offline pytest `276 passed, 2 skipped, 71 deselected`; unit pytest `276 passed, 2 skipped, 71 deselected`; unconditional-skip scan clean for the repaired file; `npx --yes pyright .` `0 errors`.
+
+## 2026-07-01 12:06 CST
+State: branch `refactor/testing-quality-audit-keble-payment-skips`; follow-up audit for unconditional live-test skips.
+
+zma:
+- Continue the cross-repo testing follow-up audit from `prompts/202060701/1.1-tests-enrich-and-run.md`.
+- Remove placeholder or permanent skips while keeping live provider tests explicitly gated and offline by default.
+
+Ai:
+- Replaced the permanent Alipay transfer skip with an explicit slow live gate requiring `RUN_ALIPAY_TRANSFER_LIVE=1` in addition to the repo live-test controls.
+- Replaced manual try/except assertions in the Alipay live test with `pytest.raises` so expected provider validation failures are asserted directly.
+- Proof: focused transfer test is skipped by the opt-in gate; default offline pytest `273 passed, 4 skipped, 71 deselected`; unit pytest `273 passed, 4 skipped, 71 deselected`; hard-skip scan clean; `uv run npx --yes pyright .` `0 errors`; `uv build` succeeded.
+
+## 2026-07-01 11:33 CST
+State: branch `refactor/testing-quality-audit-keble-payment`; follow-up audit for placeholder tests and payment order-state coverage.
+
+zma:
+- Continue the cross-repo testing follow-up audit from `prompts/202060701/1.1-tests-enrich-and-run.md`.
+- Replace useless placeholder tests with real assertions, keep default tests offline, and run pytest plus `npx --yes pyright .`.
+
+Ai:
+- Replaced the two placeholder order paid-check tests with integration assertions for unpaid, paid, and missing order IDs.
+- Covered Redis paid-cache behavior through the offline admin-simulated payment success path and covered stored paid-state behavior through the bank-prepaid order path.
+- Refreshed `uv.lock` for the actual local path-source `keble-exceptions 0.1.1` resolution used by `uv run`.
+- Proof: focused payment checks `2 passed`; default offline pytest `273 passed, 4 skipped, 71 deselected`; unit pytest `273 passed, 4 skipped, 71 deselected`; placeholder scan clean; `npx --yes pyright .` `0 errors`.
+
+## 2026-07-01 07:18 CST
+State: Strict test-support root cleanup for `keble-payment`.
+
+zma:
+- Continue the strict cross-repo testing cleanup.
+- Remove final root `tests/` support blockers while preserving payment test docs and local key ignores.
+
+Ai:
+- Moved root `tests/README.md` to `docs/testing.md` and linked it from README.
+- Moved the local PEM key ignore behavior from `tests/.gitignore` into the repo root `.gitignore`.
+- Added repo-local `uv` sources for `keble-db`, `keble-exceptions`, and `keble-helpers` so proof commands use the current local Keble dependency line instead of stale published helper metadata.
+- Updated AGENTS/CLAUDE so future workers update `docs/testing.md` instead of recreating root test docs.
+
+## 2026-07-01 03:28 CST
+State: Strict folder follow-up for `keble-payment`; package runtime behavior and dependency versions were not changed.
+
+zma:
+- Continue the cross-repo testing cleanup with stricter folder and marker allowances.
+- Remove legacy `test_*` source-group folders, root test helper modules, and duplicate test configs while keeping default tests offline.
+
+Ai:
+- Moved offline payment tests into `tests/unit`, real Mongo/Redis tests into `tests/integration`, and live provider canaries into `tests/live`.
+- Moved reusable payment test settings and asset helpers into `keble_payment.testing`.
+- Moved pytest marker config from duplicate `tests/pytest.ini` into `pyproject.toml` and updated docs to the canonical folder structure.
+
+## 2026-06-30 23:13
+        State: Documentation-only README compaction and AI log archival; no runtime code, schemas, dependencies, or tests were changed.
+
+        zma:
+        - Auto compact and summarize README.md files across repos unless already small.
+- Cross-check retained README information for validity and keep only critical, necessary information.
+- Move lengthy AiAgentChangesLogs.md files into repo-local logs/AiAgentChangesLogs.2026****.md.
+- Merge the documentation changes to main repo by repo.
+
+        Ai:
+        - Archived the previous long agent change log into `logs/AiAgentChangesLogs.20260630.md`.
+- Compacted `README.md` to current purpose, validated wiring, install/test gates, and high-risk side effects.
+- Kept only critical current README facts cross-checked against manifests, config, source roots, compose scripts, or existing guideline files.
+## 2026-07-12 15:50 CST
+State: `feature/coupon-attribution-performance`; package 2.4.0 attribution and reporting contract implemented and under release verification.
+
+zma:
+- Add scalable AI/human coupon attribution support across Keble and Truth.
+- Preserve historical tag/contributor truth and answer monthly or arbitrary-range performance questions.
+
+Ai:
+- Added immutable coupon redemption snapshots for currency, marketplace, tags, contributors, and exact basis-point allocation.
+- Replaced fetch-all coupon reads with indexed `CouponListQuery`/`CouponPage`, assignment migration, text search, and explicit sort indexes.
+- Added indexed coupon/tag/contributor performance aggregation and explicit approved legacy-history backfill with optional Mongo session participation.
+- Added unit and real-Mongo coverage for allocation, history writes, indexes, pagination, reporting, and backfill.
+## 2026-07-18 04:47 CST
+State: `fix/review2-money-contract`; exact PayPal boundary migration for `keble-payment 2.4.1`.
+
+zma:
+- Continue the complete Data Infra REVIEW2 plan and close every transitive Money caller before backend integration.
+- Preserve strong typing, exact financial semantics, release proof, and comprehensive exponent edge tests.
+
+Ai:
+- Removed float parsing and hard-coded two-decimal formatting from `PayPalMoney`.
+- Added exact JPY/USD/BHD round trips, negative adjustments, and excess-precision rejection coverage.
+- Corrected three local-full Mongo tests to create UTC-aware expiry/refund timestamps, matching the canonical aware Motor client instead of failing during datetime subtraction.
+- Removed module-import Mongo writes from three order scenarios and made their coupon cases create real rows inside per-test async namespaces; portable collection is now offline and the formerly `None` coupon cases exercise discounts.
+- Raised the public `keble-helpers` floor to 1.54.0 and removed the local helper source override for registry-reproducible builds.
+- Repaired the pre-existing full-repository Ruff gate without changing public exports, so the release now has a clean static-quality baseline.
+- Proof: exact PayPal `5 passed`; portable `291 passed, 75 deselected`; isolated local-full `360 passed, 6 deselected`; isolated integration `69 passed, 297 deselected`; Pyright `0 errors`; Ruff clean; lock check and wheel/sdist build passed.

keble_payment-2.4.1/CLAUDE.md

@@ -0,0 +1,24 @@
+# keble-payment Agent Notes
+
+## Testing Guideline
+
+- Follow root `../../TESTING_GUIDELINE.md` for all payment test work.
+- The Keble development default is local-full and runs Mongo/Redis integration tests while excluding hosted providers:
+  `RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 uv run pytest -q -m "not live and not container"`.
+- Keep the portable-offline fallback for machines without local DBs:
+  `uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"`.
+- Real Stripe, Alipay, PayPal, container, live, and eval tests must be explicitly marked and env-gated.
+- Prefer shared `keble_db.testing` helpers for new DB tests instead of ad hoc database cleanup.
+- Payment integration tests must use per-test Mongo databases and Redis namespaces from `keble_db.testing`; do not add broad collection deletes against shared databases.
+- Keep payment-specific reusable test settings and asset helpers in `keble_payment.testing`; do not recreate root `tests/config.py`, root `tests/helpers.py`, or `tests/support`.
+- If payment or DB test data is missing, enrich `keble_payment.testing` or `keble_db.testing` first instead of creating another downstream-only fixture.
+- Keep executable tests only under canonical layer roots: `tests/unit`, `tests/integration`, `tests/live`, `tests/contract`, `tests/evals`, and `tests/db_stack`.
+- Put pure schema/client-shape tests in the `unit` layer and real Mongo/Redis behavior in the `integration db` layer that runs in local-full with `RUN_INTEGRATION=1 RUN_REAL_DB=1`.
+- Do not add provider-specific pytest markers such as Stripe, Alipay, or PayPal. Use canonical `live` plus provider env guards, paths, or `-k` selection for provider slices.
+- Once a provider live slice is explicitly enabled and credentials are present, provider request/schema errors must fail the test; do not catch provider exceptions and convert them to skips.
+- Do not cache successful provider responses to skip real Stripe, Alipay, PayPal, Keepa, LLM, or embedding checks. Keep live tests tiny and explicit.
+- Future payment quality or provider-contract regression datasets belong under `tests/evals` with `eval`; selecting `-m eval` is enough, so do not add a generic `RUN_EVALS` gate.
+- Update `README.md`, `docs/testing.md`, `AGENTS.md`/`CLAUDE.md`, and `AiAgentChangesLogs.md` when test infrastructure changes.
+- Update `docs/testing.md` timing tables whenever test counts, speed, or layer gates change.
+- After Python test or fixture changes, run local-full, portable-offline, unit, eval, relevant integration/live selectors, `npx --yes pyright .`, and `uv build` from this repo root.
+- `pyrightconfig.json` currently keeps payment pyright as a Python 3.13 syntax/import sanity gate, not a strict full-repo type gate; do not claim strict type cleanliness until that config is intentionally tightened and still passes.

keble_payment-2.4.1/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: keble-payment
+Version: 2.4.1
+Author-email: zhenhao-ma <bob0103779@gmail.com>
+Requires-Python: <3.14,>=3.13
+Requires-Dist: httpx[socks]<1.0.0,>=0
+Requires-Dist: keble-db<2.0.0,>=1.8.1
+Requires-Dist: keble-exceptions<1.0.0,>=0,>=0.0.9
+Requires-Dist: keble-helpers<2.0.0,>=1.54.0
+Requires-Dist: python-alipay-sdk==1.10.1
+Requires-Dist: stripe<15.0.0,>=14
+Description-Content-Type: text/markdown
+
+# keble-payment
+
+`keble-payment` owns payment provider integration schemas and helpers for
+Alipay, Stripe, and payment persistence used by Keble services.
+
+## Verified State
+
+Checked on 2026-07-12 against `pyproject.toml`, `keble_payment/`, and tests
+on `feature/coupon-attribution-performance`.
+
+- Package: `keble-payment 2.4.0`
+- Python: `>=3.13,<3.14`
+- Critical deps: `keble-helpers`, `keble-db`, `keble-exceptions`,
+  `python-alipay-sdk`, `stripe`, `httpx`
+- Source roots: `alipay/`, `stripe/`, `paypal/`, `schemas/`, `crud/`, `main/`
+- Public exports: provider modules, payment schemas, and main client/helpers.
+
+## Runtime Contract
+
+- `keble-payment 2.4.1` converts PayPal decimal strings through exact
+  `Money.from_major_units` / `Money.to_major_units` APIs. Provider output uses
+  each currency's audited scale (JPY 0, USD 2, BHD 3) instead of a hard-coded
+  two-decimal formatter; unrepresentable precision fails before payout.
+- Provider API details stay in provider modules. Backend checkout flows should
+  consume package schemas and helpers rather than embedding provider payloads.
+- Stripe stored models support optional `stripe_account` for multi-account
+  handling; preserve that field across schema changes.
+- Tests must not perform live payment requests in the local-full or
+  portable-offline suites. Provider
+  fixtures/assets belong under tests and must stay deterministic.
+- Enabled provider live tests fail on provider request/schema errors; skips are
+  only for missing live-test preconditions such as credentials or test price IDs.
+- Reusable test settings and asset helpers live in `keble_payment.testing`.
+- Payment tests resolve shared test env values through `keble_db.testing`, so
+  backend-level `.env` values can be reused without duplicating secrets in this
+  package.
+- `OrderPricingPolicySnapshot` is the immutable paid-order audit shape for
+  service pricing policies. The snapshot records the selected policy/tag,
+  original/base/deal prices, currency, validity window, and optional linked
+  claim clue so backend callbacks can consume limited deals only after success.
+- Coupon histories snapshot currency, marketplace, and normalized tag/contributor
+  attribution at payment success. Multiple tags split 10,000 basis points with
+  deterministic largest-remainder allocation, so coupon/tag/contributor totals
+  reconcile exactly.
+- `CouponListQuery`/`CouponPage` own server search, sort, and pagination. Coupon
+  search uses `coupon_search_text_idx`; attribution review uses
+  `attribution_status_created_desc_idx`; supported sort fields have explicit indexes.
+- `CouponPerformanceQuery` is the only reporting contract. It uses closed-open
+  time ranges, IANA timezones, DAY/MONTH/TOTAL buckets, and exact Decimal output
+  grouped separately by currency and marketplace.
+- Historical attribution changes are explicit human-approved backfills through
+  `abackfill_coupon_history_attribution`; never infer current tags during reports.
+- Mongo and Redis integration tests must use per-test namespaces/databases and
+  cleanup, not broad session-level deletes against shared databases.
+- Executable tests stay under canonical layer roots: `tests/unit`,
+  `tests/integration`, `tests/live`, `tests/contract`, `tests/evals`, and
+  `tests/db_stack`.
+
+## Testing
+
+Detailed test-layer notes live in `docs/testing.md`.
+
+Local-full development command:
+
+```bash
+uv sync --group test
+RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 \
+  uv run pytest -q -m "not live and not container"
+```
+
+Portable-offline command:
+
+```bash
+uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
+```
+
+Real Mongo/Redis integration tests:
+
+```bash
+RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 uv run pytest -q -m integration
+```
+
+Eval selector:
+
+```bash
+uv run pytest -q -m eval
+```
+
+Syntax/type gate:
+
+```bash
+npx --yes pyright .
+```
+
+Latest proof on 2026-07-18:
+
+- Local-full selector: `360 passed, 6 deselected` in `4.40s`.
+- Portable-offline selector: `291 passed, 75 deselected` in `1.60s`.
+- Unit selector: `291 passed, 75 deselected` in `1.55s`.
+- Eval selector: `366 deselected` in `0.07s` (no eval tests are registered).
+- Contract selector: `366 deselected` in `0.07s` (no contract tests are registered).
+- DB-stack selector: `366 deselected` (no DB-stack-only tests are registered).
+- Integration selector: `69 passed, 297 deselected` in `2.95s`.
+- Stripe live canary: `1 passed, 3 skipped` in `3.65s`; skipped cases lacked
+  `STRIPE_TEST_PRICE_ID`.
+- Alipay live canary: `2 skipped` in `1.46s`; local Alipay key material was unavailable.
+- `npx --yes pyright .`: `0 errors`.
+
+## Change Logs
+
+Historical release notes and long AI change history live under `logs/` when
+archived.
+
+## Side Effect If Changes
+
+- Backend checkout, membership upgrade, payment callback, and admin order
+  routes depend on these provider schemas.
+- Frontend purchase success tracking depends on backend payment state derived
+  from this package.

keble_payment-2.4.1/README.md

@@ -0,0 +1,119 @@
+# keble-payment
+
+`keble-payment` owns payment provider integration schemas and helpers for
+Alipay, Stripe, and payment persistence used by Keble services.
+
+## Verified State
+
+Checked on 2026-07-12 against `pyproject.toml`, `keble_payment/`, and tests
+on `feature/coupon-attribution-performance`.
+
+- Package: `keble-payment 2.4.0`
+- Python: `>=3.13,<3.14`
+- Critical deps: `keble-helpers`, `keble-db`, `keble-exceptions`,
+  `python-alipay-sdk`, `stripe`, `httpx`
+- Source roots: `alipay/`, `stripe/`, `paypal/`, `schemas/`, `crud/`, `main/`
+- Public exports: provider modules, payment schemas, and main client/helpers.
+
+## Runtime Contract
+
+- `keble-payment 2.4.1` converts PayPal decimal strings through exact
+  `Money.from_major_units` / `Money.to_major_units` APIs. Provider output uses
+  each currency's audited scale (JPY 0, USD 2, BHD 3) instead of a hard-coded
+  two-decimal formatter; unrepresentable precision fails before payout.
+- Provider API details stay in provider modules. Backend checkout flows should
+  consume package schemas and helpers rather than embedding provider payloads.
+- Stripe stored models support optional `stripe_account` for multi-account
+  handling; preserve that field across schema changes.
+- Tests must not perform live payment requests in the local-full or
+  portable-offline suites. Provider
+  fixtures/assets belong under tests and must stay deterministic.
+- Enabled provider live tests fail on provider request/schema errors; skips are
+  only for missing live-test preconditions such as credentials or test price IDs.
+- Reusable test settings and asset helpers live in `keble_payment.testing`.
+- Payment tests resolve shared test env values through `keble_db.testing`, so
+  backend-level `.env` values can be reused without duplicating secrets in this
+  package.
+- `OrderPricingPolicySnapshot` is the immutable paid-order audit shape for
+  service pricing policies. The snapshot records the selected policy/tag,
+  original/base/deal prices, currency, validity window, and optional linked
+  claim clue so backend callbacks can consume limited deals only after success.
+- Coupon histories snapshot currency, marketplace, and normalized tag/contributor
+  attribution at payment success. Multiple tags split 10,000 basis points with
+  deterministic largest-remainder allocation, so coupon/tag/contributor totals
+  reconcile exactly.
+- `CouponListQuery`/`CouponPage` own server search, sort, and pagination. Coupon
+  search uses `coupon_search_text_idx`; attribution review uses
+  `attribution_status_created_desc_idx`; supported sort fields have explicit indexes.
+- `CouponPerformanceQuery` is the only reporting contract. It uses closed-open
+  time ranges, IANA timezones, DAY/MONTH/TOTAL buckets, and exact Decimal output
+  grouped separately by currency and marketplace.
+- Historical attribution changes are explicit human-approved backfills through
+  `abackfill_coupon_history_attribution`; never infer current tags during reports.
+- Mongo and Redis integration tests must use per-test namespaces/databases and
+  cleanup, not broad session-level deletes against shared databases.
+- Executable tests stay under canonical layer roots: `tests/unit`,
+  `tests/integration`, `tests/live`, `tests/contract`, `tests/evals`, and
+  `tests/db_stack`.
+
+## Testing
+
+Detailed test-layer notes live in `docs/testing.md`.
+
+Local-full development command:
+
+```bash
+uv sync --group test
+RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 RUN_DB_STACK=1 \
+  uv run pytest -q -m "not live and not container"
+```
+
+Portable-offline command:
+
+```bash
+uv run pytest -q -m "not live and not slow and not eval and not local_stack and not db_stack and not container"
+```
+
+Real Mongo/Redis integration tests:
+
+```bash
+RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 uv run pytest -q -m integration
+```
+
+Eval selector:
+
+```bash
+uv run pytest -q -m eval
+```
+
+Syntax/type gate:
+
+```bash
+npx --yes pyright .
+```
+
+Latest proof on 2026-07-18:
+
+- Local-full selector: `360 passed, 6 deselected` in `4.40s`.
+- Portable-offline selector: `291 passed, 75 deselected` in `1.60s`.
+- Unit selector: `291 passed, 75 deselected` in `1.55s`.
+- Eval selector: `366 deselected` in `0.07s` (no eval tests are registered).
+- Contract selector: `366 deselected` in `0.07s` (no contract tests are registered).
+- DB-stack selector: `366 deselected` (no DB-stack-only tests are registered).
+- Integration selector: `69 passed, 297 deselected` in `2.95s`.
+- Stripe live canary: `1 passed, 3 skipped` in `3.65s`; skipped cases lacked
+  `STRIPE_TEST_PRICE_ID`.
+- Alipay live canary: `2 skipped` in `1.46s`; local Alipay key material was unavailable.
+- `npx --yes pyright .`: `0 errors`.
+
+## Change Logs
+
+Historical release notes and long AI change history live under `logs/` when
+archived.
+
+## Side Effect If Changes
+
+- Backend checkout, membership upgrade, payment callback, and admin order
+  routes depend on these provider schemas.
+- Frontend purchase success tracking depends on backend payment state derived
+  from this package.