@siglume/direct-request-payment 0.4.17 → 0.4.19

package/examples/hosted-checkout-typescript/src/order-store.ts

@@ -0,0 +1,52 @@
+export type OrderStatus = "created" | "pending" | "paid" | "fulfilled_unsettled" | "review_required";
+
+export interface Order {
+  id: string;
+  amount_minor: number;
+  currency: "JPY" | "USD";
+  payment_attempt: number;
+  siglume_challenge_hash?: string;
+  siglume_checkout_session_id?: string;
+  siglume_requirement_id?: string;
+  siglume_chain_receipt_id?: string;
+  siglume_payment_status: OrderStatus;
+}
+
+const orders = new Map<string, Order>([
+  [
+    "order_123",
+    {
+      id: "order_123",
+      amount_minor: 1200,
+      currency: "JPY",
+      payment_attempt: 0,
+      siglume_payment_status: "created",
+    },
+  ],
+]);
+
+const processedWebhookEvents = new Set<string>();
+
+export function getOrder(orderId: string): Order | undefined {
+  return orders.get(orderId);
+}
+
+export function allOrders(): Order[] {
+  return [...orders.values()];
+}
+
+export function saveOrder(order: Order): void {
+  orders.set(order.id, order);
+}
+
+export function findOrderByChallengeHash(challengeHash: string): Order | undefined {
+  return [...orders.values()].find((order) => order.siglume_challenge_hash === challengeHash);
+}
+
+export function markWebhookEventProcessedOnce(eventId: string): boolean {
+  if (processedWebhookEvents.has(eventId)) {
+    return false;
+  }
+  processedWebhookEvents.add(eventId);
+  return true;
+}

package/examples/hosted-checkout-typescript/src/server.ts

@@ -0,0 +1,139 @@
+import "dotenv/config";
+
+import express from "express";
+import {
+  classifyDirectPaymentConfirmation,
+  DirectRequestPaymentMerchantClient,
+  HostedCheckoutNotAvailableError,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
+
+import {
+  allOrders,
+  findOrderByChallengeHash,
+  getOrder,
+  markWebhookEventProcessedOnce,
+  saveOrder,
+} from "./order-store.js";
+
+const app = express();
+const port = Number(process.env.PORT || 3000);
+const merchantKey = process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "example_merchant";
+const shopOrigin = process.env.SHOP_PUBLIC_ORIGIN || "https://www.example.com";
+
+const siglumeMerchant = new DirectRequestPaymentMerchantClient({
+  auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN,
+});
+
+const asyncRoute =
+  (handler: express.RequestHandler): express.RequestHandler =>
+  (req, res, next) => {
+    Promise.resolve(handler(req, res, next)).catch(next);
+  };
+
+app.get("/orders", (_req, res) => {
+  res.json({ orders: allOrders() });
+});
+
+app.post(
+  "/checkout/siglume/start",
+  express.json(),
+  asyncRoute(async (req, res) => {
+    const orderId = String(req.body?.order_id || "");
+    const order = getOrder(orderId);
+    if (!order) {
+      res.status(404).json({ error: "order_not_found" });
+      return;
+    }
+
+    order.payment_attempt += 1;
+    const session = await siglumeMerchant.createCheckoutSession({
+      merchant: merchantKey,
+      amount_minor: order.amount_minor,
+      currency: order.currency,
+      nonce: `${order.id}-attempt_${order.payment_attempt}`,
+      success_url: `${shopOrigin}/thanks`,
+      cancel_url: `${shopOrigin}/cart`,
+      metadata: { order_id: order.id },
+    });
+
+    order.siglume_challenge_hash = session.challenge_hash;
+    order.siglume_checkout_session_id = session.session_id;
+    order.siglume_payment_status = "pending";
+    saveOrder(order);
+
+    res.json({
+      order_id: order.id,
+      amount_minor: order.amount_minor,
+      currency: order.currency,
+      checkout_url: session.checkout_url,
+      session_id: session.session_id,
+    });
+  }),
+);
+
+app.post(
+  "/siglume/webhook",
+  express.raw({ type: "application/json" }),
+  asyncRoute(async (req, res) => {
+    const { event } = await verifyDirectRequestPaymentWebhook(
+      process.env.SIGLUME_WEBHOOK_SECRET || "",
+      req.body,
+      req.header("siglume-signature") || "",
+    );
+
+    if (!markWebhookEventProcessedOnce(event.id)) {
+      res.status(204).send();
+      return;
+    }
+
+    if (event.type === "direct_payment.confirmed") {
+      const confirmation = classifyDirectPaymentConfirmation(event);
+
+      if (confirmation.kind === "standard_settled") {
+        const order = findOrderByChallengeHash(confirmation.challenge_hash);
+        if (order) {
+          order.siglume_payment_status = "paid";
+          order.siglume_requirement_id = confirmation.requirement_id;
+          order.siglume_chain_receipt_id = confirmation.chain_receipt_id;
+          saveOrder(order);
+        }
+      } else if (confirmation.kind === "metered_usage_accepted") {
+        const order = findOrderByChallengeHash(confirmation.challenge_hash);
+        if (order) {
+          order.siglume_payment_status = "fulfilled_unsettled";
+          order.siglume_requirement_id = confirmation.requirement_id;
+          saveOrder(order);
+        }
+      } else if (confirmation.kind === "metered_batch_settled") {
+        console.info("metered batch settled", {
+          settlement_batch_id: confirmation.settlement_batch_id,
+          chain_receipt_id: confirmation.chain_receipt_id,
+        });
+      } else {
+        console.warn("manual payment review required", {
+          event_id: event.id,
+          reason: confirmation.reason,
+          requirement_id: confirmation.requirement_id,
+        });
+      }
+    }
+
+    res.status(204).send();
+  }),
+);
+
+app.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;
+  }
+  console.error("checkout starter error:", {
+    name: error instanceof Error ? error.name : "Error",
+  });
+  res.status(500).json({ error: "internal_error" });
+});
+
+app.listen(port, () => {
+  console.log(`Siglume Hosted Checkout starter listening on http://localhost:${port}`);
+});

package/examples/hosted-checkout-typescript/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.17",
+  "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,8 +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)

package/templates/fastapi/siglume_sdrp_routes.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Protocol
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, Response
+from siglume_direct_request_payment import (
+    DirectRequestPaymentMerchantClient,
+    HostedCheckoutNotAvailableError,
+    classify_direct_payment_confirmation,
+    verify_direct_request_payment_webhook,
+)
+
+
+class SiglumeSdrpOrderStore(Protocol):
+    async def get_order_for_checkout(self, order_id: str, request: Request) -> dict[str, Any] | None: ...
+    async def mark_checkout_pending(self, *, order_id: str, challenge_hash: str, checkout_session_id: str) -> None: ...
+    async def record_webhook_event_once(self, event_id: str) -> bool: ...
+    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) -> 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 "")
+        order = await order_store.get_order_for_checkout(order_id, request)
+        if not order:
+            return JSONResponse({"error": "order_not_found"}, status_code=404)
+
+        try:
+            session = merchant.create_checkout_session(
+                merchant=merchant_key,
+                amount_minor=int(order["amount_minor"]),
+                currency=str(order["currency"]),
+                nonce=f"{order['id']}-attempt_{int(time.time() * 1000)}",
+                success_url=f"{shop_origin}/checkout/siglume/success",
+                cancel_url=f"{shop_origin}/checkout/siglume/cancel",
+                metadata={"order_id": order["id"]},
+            )
+        except HostedCheckoutNotAvailableError:
+            return JSONResponse({"error": "hosted_checkout_not_enabled"}, status_code=409)
+
+        await order_store.mark_checkout_pending(
+            order_id=str(order["id"]),
+            challenge_hash=session["challenge_hash"],
+            checkout_session_id=session["session_id"],
+        )
+        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"]
+
+        if not await order_store.record_webhook_event_once(str(event["id"])):
+            return Response(status_code=204)
+
+        if event["type"] == "direct_payment.confirmed":
+            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":
+                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))
+
+        return Response(status_code=204)
+
+    return router