@siglume/direct-request-payment 0.4.22 → 0.4.24

package/docs/pricing.md

@@ -1,7 +1,7 @@
 # Pricing
 
 This page documents the trial-phase merchant pricing for Siglume Direct Request
-Payment as of SDK v0.4.22. Pricing can change by agreement or future product
+Payment as of SDK v0.4.24. Pricing can change by agreement or future product
 release; the Siglume platform response is the source of truth for per-payment
 fee data returned at runtime.
 

package/docs/quickstart-10-minutes.md

@@ -11,45 +11,9 @@ The SDK supplies the readiness check, route files, webhook verification, payment
 classification, and the order-store adapter contract. Your app supplies the
 real order lookup and fulfillment writes.
 
-## 0. Run the sandbox first
+## 0. Install the SDK
 
-Do this before touching live Siglume credentials. The local sandbox is a tiny
-Siglume-compatible API server bundled with the SDK. It creates fake checkout
-sessions, signs webhooks with your sandbox secret, records delivery status, and
-never charges a wallet.
-
-In one terminal, point it at your product's local webhook route:
-
-```bash
-npx siglume-sdrp sandbox \
-  --origin http://localhost:3000 \
-  --webhook-url http://localhost:3000/payments/webhooks/siglume
-```
-
-Use the values it prints in your product `.env`:
-
-```bash
-SIGLUME_ENV=sandbox
-SIGLUME_API_BASE=http://127.0.0.1:8787/v1
-SIGLUME_MERCHANT_AUTH_TOKEN=sandbox_merchant_token
-SIGLUME_DIRECT_PAYMENT_MERCHANT=sandbox_merchant
-SHOP_PUBLIC_ORIGIN=http://localhost:3000
-SHOP_WEBHOOK_URL=http://localhost:3000/payments/webhooks/siglume
-SIGLUME_WEBHOOK_SECRET=whsec_sandbox_local
-```
-
-Then run:
-
-```bash
-npx siglume-check readiness --sandbox
-```
-
-The sandbox readiness check proves your local server can receive a signed
-`direct_payment.confirmed` delivery before you use live credentials.
-
-## 1. Live readiness
-
-Install the SDK in your product.
+Install the SDK in your existing product first.
 
 Node / Express:
 
@@ -63,6 +27,13 @@ Python / FastAPI:
 pip install siglume-direct-request-payment
 ```
 
+For FastAPI projects, the Python package supplies `init`, `preflight`, and
+`verify` commands. The local sandbox server is currently provided by the npm
+CLI, so install Node.js/npm as well when you want local sandbox checkout
+verification.
+
+## 1. Optional live preflight
+
 Set these environment variables in your app or `.env`:
 
 ```bash
@@ -73,32 +44,32 @@ SHOP_WEBHOOK_URL=https://api.your-product.example/payments/webhooks/siglume
 SIGLUME_WEBHOOK_SECRET=<webhook signing secret from setupCheckout/setup_checkout>
 ```
 
-Then run the matching CLI:
+Before mounting routes, you may run a preflight. It checks local config,
+merchant, billing, webhook subscription metadata, and Hosted Checkout access,
+but it intentionally does not send a webhook delivery because your webhook route
+does not exist yet.
 
 ```bash
 # Node / Express
-npx siglume-check readiness
+npx siglume-check preflight
 
 # Python / FastAPI
-siglume-check readiness
+siglume-check preflight
 ```
 
-The readiness check fails before you write checkout code if any required item is
-missing. It checks local config, reads the merchant account, requires active
-billing, confirms the webhook subscription points to `SHOP_WEBHOOK_URL`, checks
-that `direct_payment.confirmed` is subscribed, verifies the local webhook secret
-against the subscription hint, creates one unpaid expiring Hosted Checkout probe
-session, and queues a signed webhook test delivery. No buyer is charged.
+Use `readiness` or `verify` only after your webhook route is mounted and your
+app is running. Those commands also queue a signed webhook test delivery and
+require it to be delivered.
 
 For a CI local-config smoke test:
 
 ```bash
-npx siglume-check readiness --no-api --json
+npx siglume-check preflight --no-api --json
 ```
 
 `--no-api` does not prove Hosted Checkout or webhook delivery. Before opening a
-human web checkout path, run readiness without `--no-api` and fix every FAIL
-item.
+human web checkout path, run `siglume-check verify` without `--no-api` and fix
+every FAIL item.
 
 ## 2. Copy integration files into your product
 
@@ -219,14 +190,76 @@ from .siglume.siglume_order_store_sqlalchemy import (
 engine = create_sqlalchemy_engine(os.environ["DATABASE_URL"])
 create_sqlalchemy_siglume_schema(engine)
 SessionLocal = sessionmaker(engine, future=True)
-order_store = SQLAlchemySiglumeOrderStore(SessionLocal)
+order_store = SQLAlchemySiglumeOrderStore(
+    SessionLocal,
+    # Optional for existing products with different order table/column names:
+    # orders_table=product_orders,
+    # order_id_column="order_id",
+    # amount_minor_column="total_cents",
+    # currency_column="iso_currency",
+    # order_status_column="payment_status",
+)
+```
+
+If your FastAPI app already uses SQLAlchemy `AsyncSession`, use the async
+adapter instead:
+
+```py
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from .siglume.siglume_order_store_sqlalchemy_async import (
+    AsyncSQLAlchemySiglumeOrderStore,
+    create_async_sqlalchemy_engine,
+    create_async_sqlalchemy_siglume_schema,
+)
+
+engine = create_async_sqlalchemy_engine(os.environ["DATABASE_URL"])
+# Run this during your FastAPI startup/lifespan initialization.
+await create_async_sqlalchemy_siglume_schema(engine)
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+order_store = AsyncSQLAlchemySiglumeOrderStore(SessionLocal)
+```
+
+`create_sqlalchemy_siglume_schema(engine)` creates only SDRP-owned tables by
+default. Use `include_orders_table=True` only for the sample `orders` table.
+
+The adapters persist one active checkout attempt per order, reuse an unexpired
+checkout URL on network retries, create a new attempt after expiry/failure,
+record webhook event ids only after the order update/review write succeeds, and
+keep duplicate deliveries from double-fulfilling an order.
+
+## 6. Start your app and run sandbox verify
+
+Start your product locally with the mounted checkout and webhook routes. Then,
+in another terminal, start the sandbox and point it at your local webhook route:
+
+```bash
+npx siglume-sdrp sandbox \
+  --origin http://localhost:3000 \
+  --webhook-url http://localhost:3000/payments/webhooks/siglume
+```
+
+Use the values it prints in your product `.env`:
+
+```bash
+SIGLUME_ENV=sandbox
+SIGLUME_API_BASE=http://127.0.0.1:8787/v1
+SIGLUME_MERCHANT_AUTH_TOKEN=sandbox_merchant_token
+SIGLUME_DIRECT_PAYMENT_MERCHANT=sandbox_merchant
+SHOP_PUBLIC_ORIGIN=http://localhost:3000
+SHOP_WEBHOOK_URL=http://localhost:3000/payments/webhooks/siglume
+SIGLUME_WEBHOOK_SECRET=whsec_sandbox_local
+```
+
+Restart your product with those values, keep the sandbox running, then verify
+the local webhook delivery:
+
+```bash
+npx siglume-check verify --sandbox
 ```
 
-The adapters persist one checkout attempt per order, reuse the checkout URL on
-retries, record webhook event ids only after the order update/review write
-succeeds, and keep duplicate deliveries from double-fulfilling an order.
+`verify --sandbox` must pass before you switch to live credentials.
 
-## 6. Start checkout from your frontend
+## 7. Start checkout from your frontend
 
 Call your own server route:
 
@@ -238,12 +271,12 @@ curl -X POST https://api.your-product.example/payments/checkout/siglume/start \
 
 Redirect the shopper to the returned `checkout_url`.
 
-## 7. Done means
+## 8. Done means
 
 Your product is integrated when:
 
-- `npx siglume-check readiness --sandbox` passes against your local product,
-- `npx siglume-check readiness` passes against live Siglume credentials,
+- `npx siglume-check verify --sandbox` passes against your local product,
+- `npx siglume-check verify` passes against live Siglume credentials,
 - your product has mounted checkout and webhook routes,
 - your order database uses the SQL/ORM adapter or an equivalent transactional store,
 - the signed webhook verifies against the raw body,

package/docs/sandbox.md

@@ -1,6 +1,7 @@
 # SDRP Sandbox
 
-Use the SDK sandbox before live Siglume credentials. It is a local
+Use the SDK sandbox after your local checkout and webhook routes are mounted,
+and before live Siglume credentials. It is a local
 Siglume-compatible API server for product integration testing. It creates fake
 checkout sessions, signs `direct_payment.confirmed` webhooks, records delivery
 status, and never charges a wallet.
@@ -28,7 +29,7 @@ SIGLUME_WEBHOOK_SECRET=whsec_sandbox_local
 Then verify the integration:
 
 ```bash
-npx siglume-check readiness --sandbox
+npx siglume-check verify --sandbox
 ```
 
 Create a checkout through your own product route:
@@ -41,6 +42,14 @@ curl -X POST http://localhost:3000/payments/checkout/siglume/start \
 
 Open the returned `checkout_url` and click the sandbox confirm button. Your
 product should receive a signed webhook and mark the Standard order paid once.
+If the confirm button or confirm endpoint is called again for the same sandbox
+session, the sandbox returns the original confirmation result and does not send
+another webhook. The sandbox checkout page follows the returned `redirect_url`
+after a successful confirmation so your return page is exercised too.
+
+The sandbox rejects invalid checkout input early: `amount_minor` must be a
+positive integer, `currency` must be `JPY` or `USD`, and return URLs must be
+HTTPS or local HTTP URLs.
 
 Sandbox Micro / Nano behavior follows the same public classifications:
 
@@ -48,13 +57,29 @@ Sandbox Micro / Nano behavior follows the same public classifications:
 - JPY 50-500 / USD 0.31-3.00 returns `metered_usage_accepted` with weekly Micro settlement fields.
 - JPY 1-49 / USD 0.01-0.30 returns `metered_usage_accepted` with monthly Nano settlement fields.
 
+For Micro / Nano sandbox sessions, the signed webhook and metered summary
+endpoints include seller-borne accounting fields:
+
+- `buyer_debit_minor = provider_gross_amount_minor`
+- `protocol_fee_minor` is the Micro / Nano fixed protocol fee
+- `provider_receivable_minor = provider_gross_amount_minor - protocol_fee_minor`
+- `settlement_threshold_minor = 10000` for JPY 10,000 or USD 100.00 fixed-market thresholds
+
+You can inspect the sandbox statement shape through the same SDK clients or raw
+API paths:
+
+```bash
+curl "http://127.0.0.1:8787/v1/sdrp/metered/provider/summary?plan_type=micro&token_symbol=JPYC"
+curl "http://127.0.0.1:8787/v1/sdrp/metered/my-summary?plan_type=nano&token_symbol=USDC"
+```
+
 The generated route defaults to Standard-only, so Micro / Nano checkout returns
 `METERED_INTEGRATION_REQUIRED` until you explicitly enable metered handling.
 
 Before live launch:
 
-- run `npx siglume-check readiness --sandbox` against the local product,
+- run `npx siglume-check verify --sandbox` against the local product,
 - run the same checkout path and confirm a sandbox webhook,
 - switch to live `SIGLUME_MERCHANT_AUTH_TOKEN`, `SIGLUME_DIRECT_PAYMENT_MERCHANT`, `SHOP_PUBLIC_ORIGIN`, `SHOP_WEBHOOK_URL`, and `SIGLUME_WEBHOOK_SECRET`,
-- run `npx siglume-check readiness` without `--sandbox`,
+- run `npx siglume-check verify` without `--sandbox`,
 - confirm the live webhook subscription and signing secret are for the live product URL.

package/docs/troubleshooting.md

@@ -7,19 +7,22 @@ Siglume account contact.
 
 ## Hosted Checkout readiness
 
-Hosted Checkout is enabled account by account during beta. Check this before
-building a human web checkout:
+Hosted Checkout is enabled account by account during beta. Use `preflight`
+before route mounting, then use `verify` after the webhook route is mounted and
+your app is running:
 
 ```bash
-npx siglume-check readiness --sandbox
-npx siglume-check readiness
+npx siglume-check preflight
+npx siglume-check verify --sandbox
+npx siglume-check verify
 ```
 
-Run `--sandbox` against the local SDK sandbox first. Then run the same command
-without `--sandbox` against live credentials. The command validates local
+Run `verify --sandbox` against the local SDK sandbox first. Then run `verify`
+without `--sandbox` against live credentials. `verify` validates local
 configuration, reads the merchant account, checks the active billing mandate,
 confirms the webhook subscription, creates one unpaid expiring checkout session,
-and queues a signed webhook test delivery.
+and queues a signed webhook test delivery. `preflight` skips the delivery probe
+so it can run before your webhook endpoint exists.
 
 - The merchant account exists.
 - The merchant billing mandate is active.
@@ -32,7 +35,8 @@ and queues a signed webhook test delivery.
 - The signed webhook test delivery reaches the endpoint and returns success.
 
 `--no-api` is only for local config smoke tests. `--no-probe` is a partial API
-check and does not report readiness as ready.
+check and does not report readiness as ready. Prefer `preflight` for the
+intentional no-delivery phase.
 
 If sandbox readiness fails, make sure `SIGLUME_ENV=sandbox`,
 `SIGLUME_API_BASE=http://127.0.0.1:8787/v1`, `SHOP_PUBLIC_ORIGIN`, and

package/examples/hosted-checkout-python/pyproject.toml

@@ -5,5 +5,5 @@ requires-python = ">=3.11"
 dependencies = [
   "Flask>=3.0,<4",
   "python-dotenv>=1.0,<2",
-  "siglume-direct-request-payment>=0.4.22,<0.5",
+  "siglume-direct-request-payment>=0.4.24,<0.5",
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.22",
+  "version": "0.4.24",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
@@ -75,7 +75,7 @@
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "npm run build && vitest run",
     "pack:check": "npm pack --json"
   },
   "devDependencies": {