@siglume/direct-request-payment 0.4.18 → 0.4.20

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

@@ -0,0 +1,231 @@
+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 SiglumeCheckoutAttempt extends SiglumeCheckoutOrder {
+  order_id: string;
+  attempt_id: string;
+  stable_nonce: string;
+  checkout_url?: string;
+  checkout_session_id?: string;
+}
+
+export interface SiglumeSdrpOrderStore {
+  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>;
+  processWebhookEventOnce(
+    eventId: string,
+    handler: () => Promise<void>,
+  ): Promise<"processed" | "duplicate">;
+  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;
+  allow_metered_payments?: boolean;
+}
+
+export function createSiglumeSdrpCheckoutRouter(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 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: 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: attempt.order_id, attempt_id: attempt.attempt_id },
+      });
+
+      await options.order_store.markCheckoutPending({
+        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 });
+    } 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;
+}
+
+export function createSiglumeSdrpWebhookHandler(options: SiglumeSdrpRouterOptions): express.RequestHandler {
+  return async (req, res, next) => {
+    try {
+      const { event } = await verifyDirectRequestPaymentWebhook(
+        options.webhook_secret,
+        req.body,
+        req.header("siglume-signature") || "",
+      );
+
+      const result = await options.order_store.processWebhookEventOnce(event.id, async () => {
+        await processSiglumeWebhookEvent(options, event);
+      });
+
+      if (result === "duplicate") {
+        res.status(204).send();
+        return;
+      }
+
+      res.status(204).send();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+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;
+    }
+    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,
+  });
+}
+
+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

@@ -0,0 +1,26 @@
+# 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(), allow_metered_payments=False),
+    prefix="/payments",
+)
+```
+
+Replace `siglume_order_store_example.py` with your real order database adapter.
+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`
+- `POST /payments/webhooks/siglume`

package/templates/fastapi/siglume_order_store_example.py

@@ -0,0 +1,77 @@
+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 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,
+        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 process_webhook_event_once(self, event_id: str, handler) -> str:
+        if event_id in _processed_events:
+            return "duplicate"
+        await handler()
+        _processed_events.add(event_id)
+        return "processed"
+
+    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)

package/templates/fastapi/siglume_sdrp_routes.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Awaitable, Callable, Literal, Protocol
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, Response
+from starlette.concurrency import run_in_threadpool
+from siglume_direct_request_payment import (
+    DirectRequestPaymentMerchantClient,
+    HostedCheckoutNotAvailableError,
+    classify_direct_payment_confirmation,
+    verify_direct_request_payment_webhook,
+)
+
+
+class SiglumeSdrpOrderStore(Protocol):
+    async def begin_checkout_attempt(self, order_id: str, request: Request) -> dict[str, Any] | 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: ...
+    async def process_webhook_event_once(
+        self,
+        event_id: str,
+        handler: Callable[[], Awaitable[None]],
+    ) -> Literal["processed", "duplicate"]: ...
+    async def find_order_by_challenge_hash(self, challenge_hash: str) -> dict[str, Any] | None: ...
+    async def mark_order_paid_once(self, *, order_id: str, requirement_id: str, chain_receipt_id: str) -> None: ...
+    async def mark_order_fulfilled_unsettled_once(self, *, order_id: str, requirement_id: str, pricing_band: str) -> None: ...
+    async def flag_payment_review(self, data: dict[str, Any]) -> None: ...
+
+
+def create_siglume_sdrp_router(
+    order_store: SiglumeSdrpOrderStore,
+    *,
+    allow_metered_payments: bool = False,
+) -> APIRouter:
+    router = APIRouter()
+    merchant_key = os.environ["SIGLUME_DIRECT_PAYMENT_MERCHANT"]
+    shop_origin = os.environ["SHOP_PUBLIC_ORIGIN"]
+    merchant = DirectRequestPaymentMerchantClient(
+        auth_token=os.environ["SIGLUME_MERCHANT_AUTH_TOKEN"],
+    )
+
+    @router.post("/checkout/siglume/start")
+    async def start_checkout(request: Request) -> JSONResponse:
+        body = await request.json()
+        order_id = str(body.get("order_id") or "")
+        attempt = await order_store.begin_checkout_attempt(order_id, request)
+        if not attempt:
+            return JSONResponse({"error": "order_not_found"}, status_code=404)
+
+        if not allow_metered_payments and not _is_standard_checkout_amount(str(attempt["currency"]), int(attempt["amount_minor"])):
+            return JSONResponse({"error": "METERED_INTEGRATION_REQUIRED"}, status_code=409)
+
+        if attempt.get("checkout_url") and attempt.get("checkout_session_id"):
+            return JSONResponse({
+                "checkout_url": attempt["checkout_url"],
+                "session_id": attempt["checkout_session_id"],
+            })
+
+        try:
+            session = await run_in_threadpool(
+                lambda: merchant.create_checkout_session(
+                    merchant=merchant_key,
+                    amount_minor=int(attempt["amount_minor"]),
+                    currency=str(attempt["currency"]),
+                    nonce=str(attempt["stable_nonce"]),
+                    success_url=f"{shop_origin}/checkout/siglume/success",
+                    cancel_url=f"{shop_origin}/checkout/siglume/cancel",
+                    metadata={"order_id": attempt["order_id"], "attempt_id": attempt["attempt_id"]},
+                )
+            )
+        except HostedCheckoutNotAvailableError:
+            return JSONResponse({"error": "hosted_checkout_not_enabled"}, status_code=409)
+
+        await order_store.mark_checkout_pending(
+            order_id=str(attempt["order_id"]),
+            attempt_id=str(attempt["attempt_id"]),
+            stable_nonce=str(attempt["stable_nonce"]),
+            challenge_hash=session["challenge_hash"],
+            checkout_session_id=session["session_id"],
+            checkout_url=session["checkout_url"],
+        )
+        return JSONResponse({"checkout_url": session["checkout_url"], "session_id": session["session_id"]})
+
+    @router.post("/webhooks/siglume")
+    async def siglume_webhook(request: Request) -> Response:
+        event = verify_direct_request_payment_webhook(
+            os.environ["SIGLUME_WEBHOOK_SECRET"],
+            await request.body(),
+            request.headers.get("Siglume-Signature", ""),
+        )["event"]
+
+        async def handler() -> None:
+            await _process_siglume_webhook_event(
+                order_store,
+                event,
+                allow_metered_payments=allow_metered_payments,
+            )
+
+        if await order_store.process_webhook_event_once(str(event["id"]), handler) == "duplicate":
+            return Response(status_code=204)
+
+        return Response(status_code=204)
+
+    return router
+
+
+async def _process_siglume_webhook_event(
+    order_store: SiglumeSdrpOrderStore,
+    event: dict[str, Any],
+    *,
+    allow_metered_payments: bool,
+) -> None:
+    if event["type"] != "direct_payment.confirmed":
+        return
+
+    confirmation = classify_direct_payment_confirmation(event)
+    if confirmation["kind"] == "standard_settled":
+        order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
+        if order:
+            await order_store.mark_order_paid_once(
+                order_id=str(order["id"]),
+                requirement_id=confirmation["requirement_id"],
+                chain_receipt_id=confirmation["chain_receipt_id"],
+            )
+        else:
+            await order_store.flag_payment_review({
+                "reason": "unknown_challenge_hash",
+                "requirement_id": confirmation["requirement_id"],
+            })
+    elif confirmation["kind"] == "metered_usage_accepted":
+        if not allow_metered_payments:
+            await order_store.flag_payment_review({
+                "reason": "metered_integration_required",
+                "requirement_id": confirmation["requirement_id"],
+                "pricing_band": confirmation["pricing_band"],
+            })
+            return
+        order = await order_store.find_order_by_challenge_hash(confirmation["challenge_hash"])
+        if order:
+            await order_store.mark_order_fulfilled_unsettled_once(
+                order_id=str(order["id"]),
+                requirement_id=confirmation["requirement_id"],
+                pricing_band=confirmation["pricing_band"],
+            )
+        else:
+            await order_store.flag_payment_review({
+                "reason": "unknown_metered_challenge_hash",
+                "requirement_id": confirmation["requirement_id"],
+            })
+    else:
+        await order_store.flag_payment_review(dict(confirmation))
+
+
+def _is_standard_checkout_amount(currency: str, amount_minor: int) -> bool:
+    normalized_currency = currency.upper()
+    if normalized_currency == "JPY":
+        return amount_minor >= 501
+    if normalized_currency == "USD":
+        return amount_minor >= 301
+    return False