keble-payment 2.4.1

No project description provided

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:

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:

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:

RUN_INTEGRATION=1 RUN_REAL_DB=1 RUN_LOCAL_STACK=1 uv run pytest -q -m integration

Eval selector:

uv run pytest -q -m eval

Syntax/type gate:

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.