@siglume/direct-request-payment 0.4.20 → 0.4.22

package/docs/quickstart-10-minutes.md

@@ -11,7 +11,43 @@ 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. Readiness first
+## 0. Run the sandbox first
+
+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.
 
@@ -64,7 +100,7 @@ npx siglume-check readiness --no-api --json
 human web checkout path, run readiness without `--no-api` and fix every FAIL
 item.
 
-## 1. Copy integration files into your product
+## 2. Copy integration files into your product
 
 For Express:
 
@@ -81,7 +117,7 @@ siglume-sdrp init fastapi --target app/siglume
 These commands copy framework-specific route files into your codebase. The
 generated files are intentionally small and are meant to be edited.
 
-## 2. Mount the routes
+## 3. Mount the routes
 
 Express:
 
@@ -125,7 +161,7 @@ app.include_router(
 )
 ```
 
-## 3. Replace the order-store example
+## 4. Adapter responsibilities
 
 Replace the example store with your product's order database. The adapter must:
 
@@ -146,7 +182,51 @@ Micro / Nano, checkout returns `METERED_INTEGRATION_REQUIRED` until you set
 fulfilled-but-unsettled state, settlement reconciliation, past-due handling, and
 terminal write-off handling.
 
-## 4. Start checkout from your frontend
+## 5. Use a real database adapter
+
+The copied files include durable database adapters. Use these before opening
+checkout to users; the `*.example.*` stores are only for reading the interface.
+
+Express:
+
+```ts
+import {
+  createPrismaSiglumeOrderStore,
+  createTypeOrmSiglumeOrderStore,
+  createSequelizeSiglumeOrderStore,
+  createDrizzleSiglumeOrderStore,
+} from "./siglume/siglume-order-store.sql.js";
+
+const order_store = createPrismaSiglumeOrderStore(prisma, {
+  dialect: "postgres",
+  orders_table: "orders",
+  order_id_column: "id",
+  amount_minor_column: "amount_minor",
+  currency_column: "currency",
+});
+```
+
+FastAPI:
+
+```py
+from sqlalchemy.orm import sessionmaker
+from .siglume.siglume_order_store_sqlalchemy import (
+    SQLAlchemySiglumeOrderStore,
+    create_sqlalchemy_engine,
+    create_sqlalchemy_siglume_schema,
+)
+
+engine = create_sqlalchemy_engine(os.environ["DATABASE_URL"])
+create_sqlalchemy_siglume_schema(engine)
+SessionLocal = sessionmaker(engine, future=True)
+order_store = SQLAlchemySiglumeOrderStore(SessionLocal)
+```
+
+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.
+
+## 6. Start checkout from your frontend
 
 Call your own server route:
 
@@ -158,16 +238,17 @@ curl -X POST https://api.your-product.example/payments/checkout/siglume/start \
 
 Redirect the shopper to the returned `checkout_url`.
 
-## 5. Done means
+## 7. Done means
 
 Your product is integrated when:
 
-- `npx siglume-check readiness` passes,
+- `npx siglume-check readiness --sandbox` passes against your local product,
+- `npx siglume-check readiness` passes against live Siglume credentials,
 - your product has mounted checkout and webhook routes,
-- your order database stores one active checkout attempt and `challenge_hash` for the order,
+- your order database uses the SQL/ORM adapter or an equivalent transactional store,
 - the signed webhook verifies against the raw body,
 - `standard_settled` marks the order paid once,
-- duplicate webhook deliveries do not double-fulfill the order.
+- a failed webhook handler is retried and duplicate webhook deliveries do not double-fulfill the order.
 
 For Micro / Nano revenue reconciliation, read
 [Payment lifecycle](./payment-lifecycle.md) and

package/docs/sandbox.md

@@ -0,0 +1,60 @@
+# SDRP Sandbox
+
+Use the SDK sandbox 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.
+
+Start your product locally first, then run:
+
+```bash
+npx siglume-sdrp sandbox \
+  --origin http://localhost:3000 \
+  --webhook-url http://localhost:3000/payments/webhooks/siglume
+```
+
+Set the printed environment variables in your product:
+
+```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 verify the integration:
+
+```bash
+npx siglume-check readiness --sandbox
+```
+
+Create a checkout through your own product route:
+
+```bash
+curl -X POST http://localhost:3000/payments/checkout/siglume/start \
+  -H "content-type: application/json" \
+  -d "{\"order_id\":\"order_123\"}"
+```
+
+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.
+
+Sandbox Micro / Nano behavior follows the same public classifications:
+
+- JPY 501+ / USD 3.01+ returns `standard_settled`.
+- 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.
+
+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 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`,
+- confirm the live webhook subscription and signing secret are for the live product URL.

package/docs/troubleshooting.md

@@ -11,12 +11,15 @@ Hosted Checkout is enabled account by account during beta. Check this before
 building a human web checkout:
 
 ```bash
+npx siglume-check readiness --sandbox
 npx siglume-check readiness
 ```
 
-The command 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.
+Run `--sandbox` against the local SDK sandbox first. Then run the same command
+without `--sandbox` against live credentials. The command 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.
 
 - The merchant account exists.
 - The merchant billing mandate is active.
@@ -31,6 +34,11 @@ unpaid expiring checkout session, and queues a signed webhook test delivery.
 `--no-api` is only for local config smoke tests. `--no-probe` is a partial API
 check and does not report readiness as ready.
 
+If sandbox readiness fails, make sure `SIGLUME_ENV=sandbox`,
+`SIGLUME_API_BASE=http://127.0.0.1:8787/v1`, `SHOP_PUBLIC_ORIGIN`, and
+`SHOP_WEBHOOK_URL` all point to your local product, and that
+`siglume-sdrp sandbox --webhook-url ...` is still running.
+
 If `createCheckoutSession(...)` or `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError`, do not show the raw 404/409 to the buyer.
 Stop the human checkout flow and contact Siglume support or your Siglume account

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.20,<0.5",
+  "siglume-direct-request-payment>=0.4.22,<0.5",
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
@@ -79,9 +79,17 @@
     "pack:check": "npm pack --json"
   },
   "devDependencies": {
+    "@types/express": "^5.0.6",
     "@types/node": "^20.16.5",
+    "@types/sql.js": "^1.4.11",
+    "esbuild": "^0.28.1",
+    "express": "^5.2.1",
+    "sql.js": "^1.14.1",
     "tsup": "^8.3.0",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.9"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

package/templates/express/README.md

@@ -10,7 +10,16 @@ import {
   createSiglumeSdrpWebhookHandler,
   type SiglumeSdrpRouterOptions,
 } from "./siglume/siglume-sdrp-routes.js";
-import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
+import { createPrismaSiglumeOrderStore } from "./siglume/siglume-order-store.sql.js";
+import { prisma } from "../db/prisma.js";
+
+const siglumeOrderStore = createPrismaSiglumeOrderStore(prisma, {
+  dialect: "postgres",
+  orders_table: "orders",
+  order_id_column: "id",
+  amount_minor_column: "amount_minor",
+  currency_column: "currency",
+});
 
 const siglumeOptions: SiglumeSdrpRouterOptions = {
   merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
@@ -31,7 +40,12 @@ app.use(express.json());
 app.use("/payments", createSiglumeSdrpCheckoutRouter(siglumeOptions));
 ```
 
-Replace `siglume-order-store.example.ts` with your real order database adapter.
+Use `siglume-order-store.sql.ts` for a durable database-backed adapter. It
+supports Prisma, TypeORM, Sequelize, Drizzle, and any driver that can implement
+the small `SiglumeSqlExecutor` interface. Run
+`createSiglumeSdrpSqlSchema({ dialect: "postgres" })` once in a migration or
+translate the returned SQL into your migration tool.
+
 Keep `processWebhookEventOnce()` transactional: record the webhook event as
 processed only after the order update or review write succeeds. The generated
 route defaults to Standard-only. Enable `allow_metered_payments` only after you