@siglume/direct-request-payment 0.4.19 → 0.4.22

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

@@ -13,14 +13,28 @@ export interface SiglumeCheckoutOrder {
   currency: DirectRequestPaymentCurrency | string;
 }
 
+export interface SiglumeCheckoutAttempt extends SiglumeCheckoutOrder {
+  order_id: string;
+  attempt_id: string;
+  stable_nonce: string;
+  checkout_url?: string;
+  checkout_session_id?: string;
+}
+
 export interface SiglumeSdrpOrderStore {
-  getOrderForCheckout(orderId: string, req: express.Request): Promise<SiglumeCheckoutOrder | null>;
+  beginCheckoutAttempt(orderId: string, req: express.Request): Promise<SiglumeCheckoutAttempt | null>;
   markCheckoutPending(input: {
     order_id: string;
+    attempt_id: string;
+    stable_nonce: string;
     challenge_hash: string;
     checkout_session_id: string;
+    checkout_url: string;
   }): Promise<void>;
-  recordWebhookEventOnce(eventId: string): Promise<boolean>;
+  processWebhookEventOnce(
+    eventId: string,
+    handler: () => Promise<void>,
+  ): Promise<"processed" | "duplicate">;
   findOrderByChallengeHash(challengeHash: string): Promise<{ id: string } | null>;
   markOrderPaidOnce(input: {
     order_id: string;
@@ -41,9 +55,10 @@ export interface SiglumeSdrpRouterOptions {
   webhook_secret: string;
   shop_public_origin: string;
   order_store: SiglumeSdrpOrderStore;
+  allow_metered_payments?: boolean;
 }
 
-export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): express.Router {
+export function createSiglumeSdrpCheckoutRouter(options: SiglumeSdrpRouterOptions): express.Router {
   const router = express.Router();
   const merchant = new DirectRequestPaymentMerchantClient({
     auth_token: options.merchant_auth_token,
@@ -52,26 +67,39 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
   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) {
+      const attempt = await options.order_store.beginCheckoutAttempt(orderId, req);
+      if (!attempt) {
         res.status(404).json({ error: "order_not_found" });
         return;
       }
 
+      if (!options.allow_metered_payments && !isStandardCheckoutAmount(attempt.currency, attempt.amount_minor)) {
+        res.status(409).json({ error: "METERED_INTEGRATION_REQUIRED" });
+        return;
+      }
+
+      if (attempt.checkout_url && attempt.checkout_session_id) {
+        res.json({ checkout_url: attempt.checkout_url, session_id: attempt.checkout_session_id });
+        return;
+      }
+
       const session = await merchant.createCheckoutSession({
         merchant: options.merchant,
-        amount_minor: order.amount_minor,
-        currency: order.currency,
-        nonce: `${order.id}-attempt_${Date.now()}`,
+        amount_minor: attempt.amount_minor,
+        currency: attempt.currency,
+        nonce: attempt.stable_nonce,
         success_url: `${options.shop_public_origin}/checkout/siglume/success`,
         cancel_url: `${options.shop_public_origin}/checkout/siglume/cancel`,
-        metadata: { order_id: order.id },
+        metadata: { order_id: attempt.order_id, attempt_id: attempt.attempt_id },
       });
 
       await options.order_store.markCheckoutPending({
-        order_id: order.id,
+        order_id: attempt.order_id,
+        attempt_id: attempt.attempt_id,
+        stable_nonce: attempt.stable_nonce,
         challenge_hash: session.challenge_hash,
         checkout_session_id: session.session_id,
+        checkout_url: session.checkout_url,
       });
 
       res.json({ checkout_url: session.checkout_url, session_id: session.session_id });
@@ -80,7 +108,19 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
     }
   });
 
-  router.post("/webhooks/siglume", express.raw({ type: "application/json" }), async (req, res, next) => {
+  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;
+}
+
+export function createSiglumeSdrpWebhookHandler(options: SiglumeSdrpRouterOptions): express.RequestHandler {
+  return async (req, res, next) => {
     try {
       const { event } = await verifyDirectRequestPaymentWebhook(
         options.webhook_secret,
@@ -88,70 +128,104 @@ export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): expr
         req.header("siglume-signature") || "",
       );
 
-      if (!(await options.order_store.recordWebhookEventOnce(event.id))) {
+      const result = await options.order_store.processWebhookEventOnce(event.id, async () => {
+        await processSiglumeWebhookEvent(options, event);
+      });
+
+      if (result === "duplicate") {
         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" });
+export function createSiglumeSdrpRouter(options: SiglumeSdrpRouterOptions): express.Router {
+  const router = createSiglumeSdrpCheckoutRouter(options);
+  router.post(
+    "/webhooks/siglume",
+    express.raw({ type: "application/json" }),
+    createSiglumeSdrpWebhookHandler(options),
+  );
+  return router;
+}
+
+async function processSiglumeWebhookEvent(
+  options: SiglumeSdrpRouterOptions,
+  event: Awaited<ReturnType<typeof verifyDirectRequestPaymentWebhook>>["event"],
+): Promise<void> {
+  if (event.type !== "direct_payment.confirmed") {
+    return;
+  }
+
+  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,
+      });
+    }
+    return;
+  }
+
+  if (confirmation.kind === "metered_usage_accepted") {
+    if (!options.allow_metered_payments) {
+      await options.order_store.flagPaymentReview({
+        reason: "metered_integration_required",
+        requirement_id: confirmation.requirement_id,
+        pricing_band: confirmation.pricing_band,
+      });
       return;
     }
-    next(error);
+    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,
+      });
+    }
+    return;
+  }
+
+  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,
+    });
+    return;
+  }
+
+  await options.order_store.flagPaymentReview({
+    reason: confirmation.reason,
+    requirement_id: confirmation.requirement_id,
+    settlement_batch_id: confirmation.settlement_batch_id,
   });
+}
 
-  return router;
+function isStandardCheckoutAmount(currency: string, amountMinor: number): boolean {
+  if (!Number.isSafeInteger(amountMinor)) return false;
+  const normalizedCurrency = String(currency || "").toUpperCase();
+  if (normalizedCurrency === "JPY") return amountMinor >= 501;
+  if (normalizedCurrency === "USD") return amountMinor >= 301;
+  return false;
 }

package/templates/fastapi/README.md

@@ -5,17 +5,36 @@ Mount the router in your existing app:
 ```py
 from fastapi import FastAPI
 
-from .siglume.siglume_order_store_example import ExampleSiglumeOrderStore
+import os
+from sqlalchemy.orm import sessionmaker
+
+from .siglume.siglume_order_store_sqlalchemy import (
+    SQLAlchemySiglumeOrderStore,
+    create_sqlalchemy_engine,
+    create_sqlalchemy_siglume_schema,
+)
 from .siglume.siglume_sdrp_routes import create_siglume_sdrp_router
 
 app = FastAPI()
+engine = create_sqlalchemy_engine(os.environ["DATABASE_URL"])
+create_sqlalchemy_siglume_schema(engine)
+SessionLocal = sessionmaker(engine, future=True)
+siglume_order_store = SQLAlchemySiglumeOrderStore(SessionLocal)
+
 app.include_router(
-    create_siglume_sdrp_router(ExampleSiglumeOrderStore()),
+    create_siglume_sdrp_router(siglume_order_store, allow_metered_payments=False),
     prefix="/payments",
 )
 ```
 
-Replace `siglume_order_store_example.py` with your real order database adapter.
+Use `siglume_order_store_sqlalchemy.py` for a durable SQLAlchemy adapter. It
+creates the required checkout attempt, webhook event, and payment review tables
+and keeps webhook processing transactional.
+
+Keep `process_webhook_event_once()` 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
+implement Micro / Nano settlement reconciliation and past-due handling.
 The route paths become:
 
 - `POST /payments/checkout/siglume/start`

package/templates/fastapi/siglume_order_store_example.py

@@ -11,22 +11,45 @@ _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 begin_checkout_attempt(self, order_id: str, request: Request) -> dict[str, Any] | None:
+        order = _orders.get(order_id)
+        if order is None:
+            return None
+        order.setdefault("attempt_id", f"{order['id']}_attempt_1")
+        order.setdefault("stable_nonce", f"{order['id']}-attempt_1")
+        return {
+            **order,
+            "order_id": order["id"],
+            "attempt_id": order["attempt_id"],
+            "stable_nonce": order["stable_nonce"],
+        }
 
-    async def mark_checkout_pending(self, *, order_id: str, challenge_hash: str, checkout_session_id: str) -> None:
+    async def mark_checkout_pending(
+        self,
+        *,
+        order_id: str,
+        attempt_id: str,
+        stable_nonce: str,
+        challenge_hash: str,
+        checkout_session_id: str,
+        checkout_url: str,
+    ) -> None:
         order = _orders.get(order_id)
         if not order:
             return
         order["status"] = "pending"
+        order["attempt_id"] = attempt_id
+        order["stable_nonce"] = stable_nonce
         order["challenge_hash"] = challenge_hash
         order["checkout_session_id"] = checkout_session_id
+        order["checkout_url"] = checkout_url
 
-    async def record_webhook_event_once(self, event_id: str) -> bool:
+    async def process_webhook_event_once(self, event_id: str, handler) -> str:
         if event_id in _processed_events:
-            return False
+            return "duplicate"
+        await handler()
         _processed_events.add(event_id)
-        return True
+        return "processed"
 
     async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None:
         for order in _orders.values():

package/templates/fastapi/siglume_order_store_sqlalchemy.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import contextvars
+import hashlib
+import json
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+from fastapi import Request
+from sqlalchemy import (
+    BigInteger,
+    Column,
+    DateTime,
+    MetaData,
+    String,
+    Table,
+    Text,
+    create_engine,
+    insert,
+    select,
+    update,
+)
+from sqlalchemy.engine import Engine
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.sql import func
+
+
+metadata = MetaData()
+
+orders = Table(
+    "orders",
+    metadata,
+    Column("id", String(255), primary_key=True),
+    Column("amount_minor", BigInteger, nullable=False),
+    Column("currency", String(8), nullable=False),
+    Column("status", String(32), nullable=False, default="created"),
+    Column("created_at", DateTime(timezone=True), server_default=func.now(), nullable=False),
+    Column("updated_at", DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False),
+)
+
+checkout_attempts = Table(
+    "siglume_checkout_attempts",
+    metadata,
+    Column("order_id", String(255), primary_key=True),
+    Column("attempt_id", String(255), nullable=False, unique=True),
+    Column("stable_nonce", String(255), nullable=False, unique=True),
+    Column("status", String(32), nullable=False, default="created"),
+    Column("challenge_hash", String(255), unique=True),
+    Column("checkout_session_id", String(255)),
+    Column("checkout_url", Text),
+    Column("requirement_id", String(255)),
+    Column("chain_receipt_id", String(255)),
+    Column("pricing_band", String(32)),
+    Column("paid_at", DateTime(timezone=True)),
+    Column("fulfilled_unsettled_at", DateTime(timezone=True)),
+    Column("created_at", DateTime(timezone=True), server_default=func.now(), nullable=False),
+    Column("updated_at", DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False),
+)
+
+webhook_events = Table(
+    "siglume_webhook_events",
+    metadata,
+    Column("event_id", String(255), primary_key=True),
+    Column("status", String(32), nullable=False),
+    Column("error_message", Text),
+    Column("created_at", DateTime(timezone=True), server_default=func.now(), nullable=False),
+    Column("processed_at", DateTime(timezone=True)),
+)
+
+payment_reviews = Table(
+    "siglume_payment_reviews",
+    metadata,
+    Column("review_id", String(255), primary_key=True),
+    Column("order_id", String(255)),
+    Column("reason", String(128), nullable=False),
+    Column("payload_json", Text, nullable=False),
+    Column("created_at", DateTime(timezone=True), server_default=func.now(), nullable=False),
+)
+
+_current_session: contextvars.ContextVar[Session | None] = contextvars.ContextVar(
+    "siglume_sdrp_sqlalchemy_session",
+    default=None,
+)
+
+
+def create_sqlalchemy_engine(database_url: str) -> Engine:
+    connect_args = {"check_same_thread": False} if database_url.startswith("sqlite") else {}
+    return create_engine(database_url, future=True, connect_args=connect_args)
+
+
+def create_sqlalchemy_siglume_schema(engine: Engine) -> None:
+    metadata.create_all(engine)
+
+
+def seed_sqlalchemy_order(
+    session: Session,
+    *,
+    order_id: str,
+    amount_minor: int,
+    currency: str,
+    status: str = "created",
+) -> None:
+    session.execute(
+        insert(orders).values(
+            id=order_id,
+            amount_minor=amount_minor,
+            currency=currency.upper(),
+            status=status,
+        )
+    )
+
+
+class SQLAlchemySiglumeOrderStore:
+    def __init__(
+        self,
+        session_factory: sessionmaker[Session],
+        *,
+        authorize_order: Callable[[dict[str, Any], Request], bool] | None = None,
+    ) -> None:
+        self._session_factory = session_factory
+        self._authorize_order = authorize_order
+
+    async def begin_checkout_attempt(self, order_id: str, request: Request) -> dict[str, Any] | None:
+        clean_order_id = _require_text(order_id, "order_id")
+        with self._session_factory.begin() as session:
+            order = session.execute(select(orders).where(orders.c.id == clean_order_id)).mappings().first()
+            if order is None:
+                return None
+            order_dict = dict(order)
+            if self._authorize_order and not self._authorize_order(order_dict, request):
+                return None
+
+            attempt_id, stable_nonce = _stable_attempt(clean_order_id)
+            existing = session.execute(
+                select(checkout_attempts).where(checkout_attempts.c.order_id == clean_order_id)
+            ).mappings().first()
+            if existing is None:
+                session.execute(
+                    insert(checkout_attempts).values(
+                        order_id=clean_order_id,
+                        attempt_id=attempt_id,
+                        stable_nonce=stable_nonce,
+                        status="created",
+                    )
+                )
+                existing = session.execute(
+                    select(checkout_attempts).where(checkout_attempts.c.order_id == clean_order_id)
+                ).mappings().first()
+            state = dict(existing or {})
+            return {
+                "id": clean_order_id,
+                "order_id": clean_order_id,
+                "amount_minor": int(order_dict["amount_minor"]),
+                "currency": str(order_dict["currency"]),
+                "attempt_id": str(state.get("attempt_id") or attempt_id),
+                "stable_nonce": str(state.get("stable_nonce") or stable_nonce),
+                "checkout_session_id": state.get("checkout_session_id"),
+                "checkout_url": state.get("checkout_url"),
+            }
+
+    async def mark_checkout_pending(
+        self,
+        *,
+        order_id: str,
+        attempt_id: str,
+        stable_nonce: str,
+        challenge_hash: str,
+        checkout_session_id: str,
+        checkout_url: str,
+    ) -> None:
+        session = self._session()
+        session.execute(
+            update(checkout_attempts)
+            .where(checkout_attempts.c.order_id == order_id)
+            .values(
+                status="pending",
+                attempt_id=attempt_id,
+                stable_nonce=stable_nonce,
+                challenge_hash=challenge_hash,
+                checkout_session_id=checkout_session_id,
+                checkout_url=checkout_url,
+                updated_at=func.now(),
+            )
+        )
+        self._commit_if_own_session(session)
+
+    async def process_webhook_event_once(
+        self,
+        event_id: str,
+        handler: Callable[[], Awaitable[None]],
+    ) -> Literal["processed", "duplicate"]:
+        clean_event_id = _require_text(event_id, "event_id")
+        with self._session_factory.begin() as session:
+            existing = session.execute(
+                select(webhook_events.c.event_id).where(webhook_events.c.event_id == clean_event_id)
+            ).first()
+            if existing is not None:
+                return "duplicate"
+            try:
+                session.execute(insert(webhook_events).values(event_id=clean_event_id, status="processing"))
+            except IntegrityError:
+                return "duplicate"
+            token = _current_session.set(session)
+            try:
+                await handler()
+                session.execute(
+                    update(webhook_events)
+                    .where(webhook_events.c.event_id == clean_event_id)
+                    .values(status="processed", processed_at=func.now())
+                )
+                return "processed"
+            finally:
+                _current_session.reset(token)
+
+    async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None:
+        session = self._session()
+        row = session.execute(
+            select(checkout_attempts.c.order_id).where(checkout_attempts.c.challenge_hash == challenge_hash)
+        ).first()
+        self._close_if_own_session(session)
+        return {"id": row[0]} if row else None
+
+    async def mark_order_paid_once(self, *, order_id: str, requirement_id: str, chain_receipt_id: str) -> None:
+        session = self._session()
+        result = session.execute(
+            update(checkout_attempts)
+            .where(checkout_attempts.c.order_id == order_id)
+            .where(checkout_attempts.c.status != "paid")
+            .values(
+                status="paid",
+                requirement_id=requirement_id,
+                chain_receipt_id=chain_receipt_id,
+                paid_at=func.now(),
+                updated_at=func.now(),
+            )
+        )
+        if result.rowcount:
+            session.execute(
+                update(orders)
+                .where(orders.c.id == order_id)
+                .values(status="paid", updated_at=func.now())
+            )
+        self._commit_if_own_session(session)
+
+    async def mark_order_fulfilled_unsettled_once(self, *, order_id: str, requirement_id: str, pricing_band: str) -> None:
+        session = self._session()
+        result = session.execute(
+            update(checkout_attempts)
+            .where(checkout_attempts.c.order_id == order_id)
+            .where(checkout_attempts.c.status.notin_(["fulfilled_unsettled", "paid"]))
+            .values(
+                status="fulfilled_unsettled",
+                requirement_id=requirement_id,
+                pricing_band=pricing_band,
+                fulfilled_unsettled_at=func.now(),
+                updated_at=func.now(),
+            )
+        )
+        if result.rowcount:
+            session.execute(
+                update(orders)
+                .where(orders.c.id == order_id)
+                .values(status="fulfilled_unsettled", updated_at=func.now())
+            )
+        self._commit_if_own_session(session)
+
+    async def flag_payment_review(self, data: dict[str, Any]) -> None:
+        session = self._session()
+        payload = json.dumps(data, separators=(",", ":"), sort_keys=True)
+        session.execute(
+            insert(payment_reviews).values(
+                review_id=f"sdrp_review_{_sha256(f'{time.time()}:{payload}')[:24]}",
+                order_id=data.get("order_id") if isinstance(data.get("order_id"), str) else None,
+                reason=str(data.get("reason") or "manual_review_required"),
+                payload_json=payload,
+            )
+        )
+        self._commit_if_own_session(session)
+
+    def _session(self) -> Session:
+        current = _current_session.get()
+        if current is not None:
+            return current
+        return self._session_factory()
+
+    def _commit_if_own_session(self, session: Session) -> None:
+        if _current_session.get() is not session:
+            try:
+                session.commit()
+            finally:
+                session.close()
+
+    def _close_if_own_session(self, session: Session) -> None:
+        if _current_session.get() is not session:
+            session.close()
+
+
+def _stable_attempt(order_id: str) -> tuple[str, str]:
+    digest = _sha256(order_id)[:32]
+    return f"sdrp_attempt_{digest}", f"sdrp-{digest}"
+
+
+def _sha256(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def _require_text(value: str, name: str) -> str:
+    text = str(value or "").strip()
+    if not text:
+        raise ValueError(f"{name} is required")
+    return text