@siglume/direct-request-payment 0.4.19 → 0.4.22

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.4.22 - 2026-06-20
+
+- Fixed clean-checkout TypeScript resolution for template imports so CI and npm
+  release typechecks do not depend on a prebuilt `dist/` directory.
+
+## 0.4.21 - 2026-06-20
+
+Complete the 10-minute integration path with durable adapters, sandbox, and E2E.
+
+- Added a local `siglume-sdrp sandbox` server that creates fake Hosted Checkout
+  sessions, sends signed `direct_payment.confirmed` webhooks, records delivery
+  status, and never charges a wallet.
+- Added `SIGLUME_ENV=sandbox`, `SIGLUME_SANDBOX_API_BASE`, and
+  `siglume-check readiness --sandbox` so sandbox and live checks are explicit.
+- Added durable Express SQL/ORM order-store adapters for Prisma, TypeORM,
+  Sequelize, Drizzle, and generic SQL executors.
+- Added a durable FastAPI SQLAlchemy order-store adapter and packaged it in the
+  Python templates.
+- Added Express and FastAPI E2E tests covering checkout start, checkout URL
+  reuse, signed webhook success, duplicate webhook suppression, retry after
+  handler failure, and Standard-only Micro/Nano blocking.
+- Updated the 10-minute guide, sandbox guide, template READMEs, API reference,
+  troubleshooting, and README so implementers can test locally before live
+  credentials.
+
+## 0.4.20 - 2026-06-20
+
+Close the v0.4.19 public onboarding safety review.
+
+- Fixed generated Express/FastAPI webhook handling so webhook event ids are
+  recorded as processed only after the order update or durable review write
+  succeeds. A retry after a mid-handler failure is no longer discarded as a
+  duplicate.
+- Added stable checkout attempts/nonces to generated routes and starters so a
+  retry or double click reuses the active attempt instead of creating a fresh
+  timestamp nonce.
+- Split Express checkout and webhook mounting helpers so production apps can
+  mount the raw-body webhook before global `express.json()`.
+- Strengthened `siglume-check readiness` to require `SIGLUME_WEBHOOK_SECRET`,
+  active billing, matching active webhook subscription, subscribed
+  `direct_payment.confirmed`, matching signing-secret hint, Hosted Checkout
+  probe, and signed webhook delivery probe.
+- Added webhook subscription/test-delivery/delivery-list client helpers in
+  TypeScript and Python.
+- Made generated 10-minute routes Standard-only by default; Micro / Nano now
+  require explicit delayed-settlement reconciliation before fulfillment.
+- Clarified Micro / Nano unsettled-exposure scope and terminal states across
+  pricing, announcement, lifecycle, troubleshooting, and API reference docs.
+- Added readiness negative tests and webhook API client tests.
+
 ## 0.4.19 - 2026-06-20
 
 Make the 10-minute integration path a real product-integration path instead of

package/README.md

@@ -86,6 +86,8 @@ CLI-first:
 
 ```bash
 npm install @siglume/direct-request-payment
+npx siglume-sdrp sandbox --webhook-url http://localhost:3000/payments/webhooks/siglume
+npx siglume-check readiness --sandbox
 npx siglume-check readiness
 npx siglume-sdrp init express --target src/siglume
 ```
@@ -97,8 +99,12 @@ pip install siglume-direct-request-payment
 siglume-sdrp init fastapi --target app/siglume
 ```
 
-The readiness command checks account, billing, origin, webhook, and Hosted
-Checkout availability before you write checkout code.
+The sandbox command starts a local Siglume-compatible API that creates fake
+checkout sessions and sends signed webhooks to your product. It never charges a
+wallet; see [SDRP Sandbox](./docs/sandbox.md). The readiness command checks
+account, billing, origin, webhook, and Hosted Checkout availability before you
+write checkout code. It also confirms the webhook subscription and signed test
+delivery when API probes are enabled.
 
 Before implementation, confirm Hosted Checkout readiness in
 [Troubleshooting](./docs/troubleshooting.md#hosted-checkout-readiness). For
@@ -119,8 +125,8 @@ fulfilling orders.
 
 | Use case | Recommended path | 10-minute integration path? | Production work still required |
 | --- | --- | --- | --- |
-| EC one-time Standard payment | Hosted Checkout | Yes, with `siglume-check readiness` and `siglume-sdrp init` | Refund/support process and monitoring |
-| Game consumables | Hosted Checkout or agent/API | Conditional | Idempotent entitlement grants, disconnect recovery, Micro / Nano unsettled-risk handling |
+| EC one-time Standard payment | Hosted Checkout | Yes, with `siglume-check readiness` and `siglume-sdrp init` | Product DB adapter, refund/support process, monitoring |
+| Game consumables | Hosted Checkout or agent/API | Conditional | Idempotent entitlement grants, disconnect recovery, Micro / Nano settlement reconciliation and past-due handling |
 | Paid API / AtoA | Direct API or Siglume marketplace tool | Conditional | Request idempotency, buyer auth context, reconciliation |
 | SaaS subscription | Recurring challenge plus raw API | No | Renewal, cancellation, failed renewal, plan-change lifecycle |
 | Scheduled autopay | Recurring challenge plus schedule token | No | Scheduler, token custody, budget failure handling |
@@ -171,8 +177,8 @@ redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
 // 3. Handle the signed direct_payment.confirmed webhook. Use
 //    classifyDirectPaymentConfirmation(event). Fulfill Standard only for
-//    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
-//    until the later metered_batch_settled event arrives.
+//    standard_settled. Do not fulfill metered_usage_accepted unless you have
+//    explicitly enabled Micro / Nano settlement reconciliation.
 //    Poll merchant.getCheckoutSession(session.session_id) if you also want to
 //    show status in your own UI.
 ```
@@ -206,8 +212,8 @@ redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
 # 3. Handle the signed direct_payment.confirmed webhook. Use
 #    classify_direct_payment_confirmation(event). Fulfill Standard only for
-#    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
-#    until the later metered_batch_settled event arrives.
+#    standard_settled. Do not fulfill metered_usage_accepted unless you have
+#    explicitly enabled Micro / Nano settlement reconciliation.
 #    Poll merchant.get_checkout_session(session["session_id"]) if you also want
 #    to show status in your own UI.
 ```
@@ -631,7 +637,8 @@ if (event.type === "direct_payment.confirmed") {
   } else if (confirmation.kind === "standard_settled") {
     // Mark the order paid once if event.data.challenge_hash/order mapping matches.
   } else if (confirmation.kind === "metered_usage_accepted") {
-    // Mark fulfilled-but-unsettled after matching confirmation.challenge_hash.
+    // Default Standard-only integrations should not fulfill this.
+    // Enable Micro / Nano only with settlement reconciliation and past-due handling.
   } else {
     // Route confirmation.reason to manual review. Do not mark paid or fulfilled.
   }
@@ -662,7 +669,8 @@ if verified["event"]["type"] == "direct_payment.confirmed":
         # Mark the order paid once if event.data.challenge_hash/order mapping matches.
         pass
     elif confirmation["kind"] == "metered_usage_accepted":
-        # Mark fulfilled-but-unsettled after matching confirmation["challenge_hash"].
+        # Default Standard-only integrations should not fulfill this.
+        # Enable Micro / Nano only with settlement reconciliation and past-due handling.
         pass
     else:
         # Route confirmation["reason"] to manual review. Do not mark paid or fulfilled.