@siglume/direct-request-payment 0.4.18 → 0.4.19

package/docs/quickstart-10-minutes.md

@@ -1,176 +1,145 @@
-# 10-Minute First Test Payment
+# 10-Minute Product Integration
 
-This guide is the shortest supported path to one **Standard Payment** test
-through Siglume wallet Hosted Checkout. It is not a full production launch.
+This guide is the supported 10-minute path for adding SDRP Hosted Checkout to
+an existing product. The goal is to
+add two routes to your own server:
 
-## What the 10 minutes cover
+- `POST /payments/checkout/siglume/start`
+- `POST /payments/webhooks/siglume`
 
-You can count the 10 minutes only after the prerequisites below are already
-ready. The target outcome is:
+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.
 
-- one Standard-band order,
-- one Hosted Checkout session,
-- one signed `direct_payment.confirmed` webhook,
-- one idempotent local fulfillment decision.
+## 0. Readiness first
 
-This guide does **not** cover production monitoring, refunds, subscriptions,
-scheduled autopay, game entitlement recovery, or Micro / Nano accounting.
+Install the SDK in your product.
 
-## Prerequisites
+Node / Express:
 
-Before starting, confirm:
+```bash
+npm install @siglume/direct-request-payment
+```
+
+Python / FastAPI:
+
+```bash
+pip install siglume-direct-request-payment
+```
 
-- You have a Siglume merchant account and merchant Siglume bearer token.
-- Hosted Checkout is enabled for that merchant account.
-- The merchant billing mandate is active, including any required wallet
-  approval.
-- You have a public HTTPS webhook URL that can receive the raw request body.
-- Your checkout return URL origin is known and can be registered.
-- The buyer has a Siglume wallet funded in the settlement token for the test
-  market: JPYC for JPY, USDC for USD.
-- Your order amount is in the Standard band: JPY 501+ or USD 3.01+.
+Set these environment variables in your app or `.env`:
 
-If Hosted Checkout is not enabled, stop here. The SDK raises
-`HostedCheckoutNotAvailableError` for rollout 404/409 responses; contact
-Siglume support or your Siglume account contact to enable the account before
-continuing with a human web checkout.
+```bash
+SIGLUME_MERCHANT_AUTH_TOKEN=<merchant Siglume bearer token>
+SIGLUME_DIRECT_PAYMENT_MERCHANT=<merchant key>
+SHOP_PUBLIC_ORIGIN=https://www.your-product.example
+SHOP_WEBHOOK_URL=https://api.your-product.example/payments/webhooks/siglume
+```
 
-## 1. Install
+Then run:
 
-Runnable starter directories are available if you want a small server to edit:
+```bash
+npx siglume-check readiness
+```
 
-- [TypeScript Express starter](../examples/hosted-checkout-typescript)
-- [Python Flask starter](../examples/hosted-checkout-python)
+The readiness check fails before you write checkout code if any required item is
+missing. It checks local config, reads the merchant account, and creates one
+unpaid expiring Hosted Checkout probe session to prove the account is enabled
+and the return origin is accepted. No buyer is charged.
 
-For an existing app, install the SDK directly:
+For CI or a preflight script:
 
 ```bash
-npm install @siglume/direct-request-payment
+npx siglume-check readiness --json
 ```
 
-or:
+If this command fails, fix the reported item first. Do not build a human web
+checkout path until readiness passes.
+
+## 1. Copy integration files into your product
+
+For Express:
 
 ```bash
-pip install siglume-direct-request-payment
+npx siglume-sdrp init express --target src/siglume
 ```
 
-## 2. Set environment variables
+For FastAPI:
 
 ```bash
-SIGLUME_MERCHANT_AUTH_TOKEN=<merchant Siglume bearer token>
-SIGLUME_DIRECT_PAYMENT_MERCHANT=example_merchant
-SHOP_PUBLIC_ORIGIN=https://www.example.com
-SHOP_WEBHOOK_URL=https://api.example.com/siglume/webhook
+siglume-sdrp init fastapi --target app/siglume
 ```
 
-Do not use a Developer Portal `cli_` API key. Merchant setup requires the
-merchant's Siglume bearer token.
+These commands copy framework-specific route files into your codebase. The
+generated files are intentionally small and are meant to be edited.
 
-## 3. Register merchant settings
+## 2. Mount the routes
 
-Run setup once from your server, CI, or integration machine:
+Express:
 
 ```ts
-import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
 
-const merchant = new DirectRequestPaymentMerchantClient({
-  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
-});
-
-const setup = await merchant.setupCheckout({
+app.use("/payments", createSiglumeSdrpRouter({
   merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
-  display_name: "Example Merchant",
-  billing_plan: "launch",
-  billing_currency: "JPY",
-  webhook_callback_url: process.env.SHOP_WEBHOOK_URL!,
-  checkout_allowed_origins: [process.env.SHOP_PUBLIC_ORIGIN!],
-});
-
-console.log(setup.env.SIGLUME_DIRECT_PAYMENT_MERCHANT);
+  merchant_auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+  webhook_secret: process.env.SIGLUME_WEBHOOK_SECRET!,
+  shop_public_origin: process.env.SHOP_PUBLIC_ORIGIN!,
+  order_store: siglumeOrderStore,
+}));
 ```
 
-Store the returned `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` and
-`SIGLUME_WEBHOOK_SECRET` in a server-side secret store. Secret values are
-returned only when created or rotated.
-
-## 4. Create a Standard checkout session
+FastAPI:
 
-For each order, create the order on your server first. Then create a Hosted
-Checkout session:
+```py
+from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
+from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
 
-```ts
-const session = await merchant.createCheckoutSession({
-  merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
-  amount_minor: 1200,
-  currency: "JPY",
-  nonce: "order_123-attempt_1",
-  success_url: `${process.env.SHOP_PUBLIC_ORIGIN}/thanks`,
-  cancel_url: `${process.env.SHOP_PUBLIC_ORIGIN}/cart`,
-  metadata: { order_id: "order_123" },
-});
-
-await orders.update("order_123", {
-  siglume_challenge_hash: session.challenge_hash,
-  siglume_checkout_session_id: session.session_id,
-  siglume_payment_status: "pending",
-});
-
-redirect(session.checkout_url);
+app.include_router(
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    prefix="/payments",
+)
 ```
 
-The browser must never choose the amount, currency, nonce, or return URL. The
-session is single-use and expires.
+## 3. Replace the order-store example
 
-## 5. Fulfill from the signed webhook
+Replace the example store with your product's order database. The adapter must:
 
-The browser return path is not the source of truth. Use the signed webhook and
-classify the confirmation:
+- load the order by your `order_id`,
+- verify the current user is allowed to pay for that order,
+- return the server-authored `amount_minor` and `currency`,
+- persist `challenge_hash` and `checkout_session_id` before redirecting,
+- record webhook event ids durably,
+- mark Standard orders paid exactly once,
+- mark Micro / Nano orders as fulfilled but unsettled exactly once,
+- route unknown classifications to manual review.
 
-```ts
-import {
-  classifyDirectPaymentConfirmation,
-  verifyDirectRequestPaymentWebhook,
-} from "@siglume/direct-request-payment";
-
-const { event } = await verifyDirectRequestPaymentWebhook(
-  process.env.SIGLUME_WEBHOOK_SECRET!,
-  rawRequestBody,
-  siglumeSignatureHeader,
-);
-
-if (event.type === "direct_payment.confirmed") {
-  const confirmation = classifyDirectPaymentConfirmation(event);
-
-  if (confirmation.kind === "standard_settled") {
-    await orders.markPaidOnceByChallengeHash(confirmation.challenge_hash, {
-      requirement_id: confirmation.requirement_id,
-      chain_receipt_id: confirmation.chain_receipt_id,
-    });
-  } else if (confirmation.kind === "metered_usage_accepted") {
-    await orders.markFulfilledButUnsettledOnceByChallengeHash(
-      confirmation.challenge_hash,
-      { requirement_id: confirmation.requirement_id },
-    );
-  } else {
-    await orders.flagForPaymentStateReview(confirmation);
-  }
-}
+Do not calculate the amount from browser input.
+
+## 4. Start checkout from your frontend
+
+Call your own server route:
+
+```bash
+curl -X POST https://api.your-product.example/payments/checkout/siglume/start \
+  -H "content-type: application/json" \
+  -d "{\"order_id\":\"order_123\"}"
 ```
 
-For this 10-minute guide, keep the test order in the Standard band so the
-expected successful branch is `standard_settled`.
+Redirect the shopper to the returned `checkout_url`.
 
-## Done means
+## 5. Done means
 
-You are done with the quickstart when:
+Your product is integrated when:
 
-- the checkout session is created,
-- the buyer reaches the Siglume wallet hosted checkout page,
+- `npx siglume-check readiness` passes,
+- your product has mounted checkout and webhook routes,
+- your order database stores `challenge_hash` for the order,
 - the signed webhook verifies against the raw body,
-- `classifyDirectPaymentConfirmation(event)` returns `standard_settled`,
-- your order is marked paid once, keyed by the stored `challenge_hash`.
+- `standard_settled` marks the order paid once,
+- `metered_usage_accepted` uses a separate fulfilled-but-unsettled state.
 
-Before production, complete the full checklist in
-[Merchant Quickstart](./merchant-quickstart.md#go-live-checklist), read
-[Payment lifecycle](./payment-lifecycle.md), and prepare the failure handling in
-[Troubleshooting](./troubleshooting.md).
+For Micro / Nano revenue reconciliation, read
+[Payment lifecycle](./payment-lifecycle.md) and
+[Micro / Nano Statements and Notices](./metered-statements.md).

package/docs/troubleshooting.md

@@ -10,6 +10,14 @@ Siglume account contact.
 Hosted Checkout is enabled account by account during beta. Check this before
 building a human web checkout:
 
+```bash
+npx siglume-check readiness
+```
+
+The command validates local configuration, reads the merchant account, and
+creates one unpaid expiring checkout session to prove Hosted Checkout is
+available for this merchant account.
+
 - The merchant account exists.
 - The merchant billing mandate is active.
 - The webhook callback URL is HTTPS and reachable.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.18",
+  "version": "0.4.19",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",
@@ -33,6 +33,10 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "siglume-sdrp": "./bin/siglume-sdrp.mjs",
+    "siglume-check": "./bin/siglume-sdrp.mjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -52,11 +56,15 @@
   },
   "files": [
     "dist",
+    "bin",
     "docs",
     "examples",
+    "templates",
     "!examples/**/node_modules",
     "!examples/**/__pycache__",
     "!examples/**/*.pyc",
+    "!templates/**/__pycache__",
+    "!templates/**/*.pyc",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/templates/express/README.md

@@ -0,0 +1,22 @@
+# Express Integration Files
+
+Mount the router in your existing app:
+
+```ts
+import { createSiglumeSdrpRouter } from "./siglume/siglume-sdrp-routes.js";
+import { siglumeOrderStore } from "./siglume/siglume-order-store.example.js";
+
+app.use("/payments", createSiglumeSdrpRouter({
+  merchant: process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT!,
+  merchant_auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN!,
+  webhook_secret: process.env.SIGLUME_WEBHOOK_SECRET!,
+  shop_public_origin: process.env.SHOP_PUBLIC_ORIGIN!,
+  order_store: siglumeOrderStore,
+}));
+```
+
+Replace `siglume-order-store.example.ts` with your real order database adapter.
+The route paths become:
+
+- `POST /payments/checkout/siglume/start`
+- `POST /payments/webhooks/siglume`

package/templates/express/siglume-order-store.example.ts

@@ -0,0 +1,53 @@
+import type { Request } from "express";
+
+import type { SiglumeCheckoutOrder, SiglumeSdrpOrderStore } from "./siglume-sdrp-routes.js";
+
+type Order = SiglumeCheckoutOrder & {
+  status: "created" | "pending" | "paid" | "fulfilled_unsettled" | "review_required";
+  challenge_hash?: string;
+  checkout_session_id?: string;
+  requirement_id?: string;
+  chain_receipt_id?: string;
+};
+
+const orders = new Map<string, Order>([
+  ["order_123", { id: "order_123", amount_minor: 1200, currency: "JPY", status: "created" }],
+]);
+const processedEvents = new Set<string>();
+
+export const siglumeOrderStore: SiglumeSdrpOrderStore = {
+  async getOrderForCheckout(orderId: string, _req: Request) {
+    return orders.get(orderId) || null;
+  },
+  async markCheckoutPending(input) {
+    const order = orders.get(input.order_id);
+    if (!order) return;
+    order.status = "pending";
+    order.challenge_hash = input.challenge_hash;
+    order.checkout_session_id = input.checkout_session_id;
+  },
+  async recordWebhookEventOnce(eventId) {
+    if (processedEvents.has(eventId)) return false;
+    processedEvents.add(eventId);
+    return true;
+  },
+  async findOrderByChallengeHash(challengeHash) {
+    return [...orders.values()].find((order) => order.challenge_hash === challengeHash) || null;
+  },
+  async markOrderPaidOnce(input) {
+    const order = orders.get(input.order_id);
+    if (!order || order.status === "paid") return;
+    order.status = "paid";
+    order.requirement_id = input.requirement_id;
+    order.chain_receipt_id = input.chain_receipt_id;
+  },
+  async markOrderFulfilledUnsettledOnce(input) {
+    const order = orders.get(input.order_id);
+    if (!order || order.status === "fulfilled_unsettled") return;
+    order.status = "fulfilled_unsettled";
+    order.requirement_id = input.requirement_id;
+  },
+  async flagPaymentReview(input) {
+    console.warn("payment review required", input);
+  },
+};

package/templates/express/siglume-sdrp-routes.ts

@@ -0,0 +1,157 @@
+import express from "express";
+import {
+  classifyDirectPaymentConfirmation,
+  DirectRequestPaymentMerchantClient,
+  HostedCheckoutNotAvailableError,
+  verifyDirectRequestPaymentWebhook,
+  type DirectRequestPaymentCurrency,
+} from "@siglume/direct-request-payment";
+
+export interface SiglumeCheckoutOrder {
+  id: string;
+  amount_minor: number;
+  currency: DirectRequestPaymentCurrency | string;
+}
+
+export interface SiglumeSdrpOrderStore {
+  getOrderForCheckout(orderId: string, req: express.Request): Promise<SiglumeCheckoutOrder | null>;
+  markCheckoutPending(input: {
+    order_id: string;
+    challenge_hash: string;
+    checkout_session_id: string;
+  }): Promise<void>;
+  recordWebhookEventOnce(eventId: string): Promise<boolean>;
+  findOrderByChallengeHash(challengeHash: string): Promise<{ id: string } | null>;
+  markOrderPaidOnce(input: {
+    order_id: string;
+    requirement_id: string;
+    chain_receipt_id: string;
+  }): Promise<void>;
+  markOrderFulfilledUnsettledOnce(input: {
+    order_id: string;
+    requirement_id: string;
+    pricing_band: string;
+  }): Promise<void>;
+  flagPaymentReview(input: Record<string, unknown>): Promise<void>;
+}
+
+export interface SiglumeSdrpRouterOptions {
+  merchant: string;
+  merchant_auth_token: string;
+  webhook_secret: string;
+  shop_public_origin: string;
+  order_store: SiglumeSdrpOrderStore;
+}
+
+export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): express.Router {
+  const router = express.Router();
+  const merchant = new DirectRequestPaymentMerchantClient({
+    auth_token: options.merchant_auth_token,
+  });
+
+  router.post("/checkout/siglume/start", express.json(), async (req, res, next) => {
+    try {
+      const orderId = String(req.body?.order_id || "");
+      const order = await options.order_store.getOrderForCheckout(orderId, req);
+      if (!order) {
+        res.status(404).json({ error: "order_not_found" });
+        return;
+      }
+
+      const session = await merchant.createCheckoutSession({
+        merchant: options.merchant,
+        amount_minor: order.amount_minor,
+        currency: order.currency,
+        nonce: `${order.id}-attempt_${Date.now()}`,
+        success_url: `${options.shop_public_origin}/checkout/siglume/success`,
+        cancel_url: `${options.shop_public_origin}/checkout/siglume/cancel`,
+        metadata: { order_id: order.id },
+      });
+
+      await options.order_store.markCheckoutPending({
+        order_id: order.id,
+        challenge_hash: session.challenge_hash,
+        checkout_session_id: session.session_id,
+      });
+
+      res.json({ checkout_url: session.checkout_url, session_id: session.session_id });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post("/webhooks/siglume", express.raw({ type: "application/json" }), async (req, res, next) => {
+    try {
+      const { event } = await verifyDirectRequestPaymentWebhook(
+        options.webhook_secret,
+        req.body,
+        req.header("siglume-signature") || "",
+      );
+
+      if (!(await options.order_store.recordWebhookEventOnce(event.id))) {
+        res.status(204).send();
+        return;
+      }
+
+      if (event.type === "direct_payment.confirmed") {
+        const confirmation = classifyDirectPaymentConfirmation(event);
+
+        if (confirmation.kind === "standard_settled") {
+          const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
+          if (order) {
+            await options.order_store.markOrderPaidOnce({
+              order_id: order.id,
+              requirement_id: confirmation.requirement_id,
+              chain_receipt_id: confirmation.chain_receipt_id,
+            });
+          } else {
+            await options.order_store.flagPaymentReview({
+              reason: "unknown_challenge_hash",
+              requirement_id: confirmation.requirement_id,
+            });
+          }
+        } else if (confirmation.kind === "metered_usage_accepted") {
+          const order = await options.order_store.findOrderByChallengeHash(confirmation.challenge_hash);
+          if (order) {
+            await options.order_store.markOrderFulfilledUnsettledOnce({
+              order_id: order.id,
+              requirement_id: confirmation.requirement_id,
+              pricing_band: confirmation.pricing_band,
+            });
+          } else {
+            await options.order_store.flagPaymentReview({
+              reason: "unknown_metered_challenge_hash",
+              requirement_id: confirmation.requirement_id,
+            });
+          }
+        } else if (confirmation.kind === "metered_batch_settled") {
+          await options.order_store.flagPaymentReview({
+            reason: "metered_batch_settled_reconcile_statement_api",
+            settlement_batch_id: confirmation.settlement_batch_id,
+            chain_receipt_id: confirmation.chain_receipt_id,
+          });
+        } else {
+          await options.order_store.flagPaymentReview({
+            reason: confirmation.reason,
+            requirement_id: confirmation.requirement_id,
+            settlement_batch_id: confirmation.settlement_batch_id,
+          });
+        }
+      }
+
+      res.status(204).send();
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.use((error: unknown, _req: express.Request, res: express.Response, next: express.NextFunction) => {
+    if (error instanceof HostedCheckoutNotAvailableError) {
+      res.status(409).json({ error: "hosted_checkout_not_enabled" });
+      return;
+    }
+    next(error);
+  });
+
+  return router;
+}

package/templates/fastapi/README.md

@@ -0,0 +1,22 @@
+# FastAPI Integration Files
+
+Mount the router in your existing app:
+
+```py
+from fastapi import FastAPI
+
+from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
+from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
+
+app = FastAPI()
+app.include_router(
+    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    prefix="/payments",
+)
+```
+
+Replace `siglume_order_store_example.py` with your real order database adapter.
+The route paths become:
+
+- `POST /payments/checkout/siglume/start`
+- `POST /payments/webhooks/siglume`

package/templates/fastapi/siglume_order_store_example.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import Request
+
+_orders: dict[str, dict[str, Any]] = {
+    "order_123": {"id": "order_123", "amount_minor": 1200, "currency": "JPY", "status": "created"}
+}
+_processed_events: set[str] = set()
+
+
+class ExampleSiglumeOrderStore:
+    async def get_order_for_checkout(self, order_id: str, request: Request) -> dict[str, Any] | None:
+        return _orders.get(order_id)
+
+    async def mark_checkout_pending(self, *, order_id: str, challenge_hash: str, checkout_session_id: str) -> None:
+        order = _orders.get(order_id)
+        if not order:
+            return
+        order["status"] = "pending"
+        order["challenge_hash"] = challenge_hash
+        order["checkout_session_id"] = checkout_session_id
+
+    async def record_webhook_event_once(self, event_id: str) -> bool:
+        if event_id in _processed_events:
+            return False
+        _processed_events.add(event_id)
+        return True
+
+    async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None:
+        for order in _orders.values():
+            if order.get("challenge_hash") == challenge_hash:
+                return order
+        return None
+
+    async def mark_order_paid_once(self, *, order_id: str, requirement_id: str, chain_receipt_id: str) -> None:
+        order = _orders.get(order_id)
+        if not order or order.get("status") == "paid":
+            return
+        order["status"] = "paid"
+        order["requirement_id"] = requirement_id
+        order["chain_receipt_id"] = chain_receipt_id
+
+    async def mark_order_fulfilled_unsettled_once(self, *, order_id: str, requirement_id: str, pricing_band: str) -> None:
+        order = _orders.get(order_id)
+        if not order or order.get("status") == "fulfilled_unsettled":
+            return
+        order["status"] = "fulfilled_unsettled"
+        order["requirement_id"] = requirement_id
+        order["pricing_band"] = pricing_band
+
+    async def flag_payment_review(self, data: dict[str, Any]) -> None:
+        print("payment review required", data)