@siglume/direct-request-payment 0.4.7 → 0.4.9

package/docs/merchant-quickstart.md

@@ -392,7 +392,10 @@ signer and verifier only.
 Use the webhook as the durable signal, not just the browser return path.
 
 ```ts
-import { verifyDirectRequestPaymentWebhook } from "@siglume/direct-request-payment";
+import {
+  classifyDirectPaymentConfirmation,
+  verifyDirectRequestPaymentWebhook,
+} from "@siglume/direct-request-payment";
 
 const { event } = await verifyDirectRequestPaymentWebhook(
   process.env.SIGLUME_WEBHOOK_SECRET!,
@@ -404,57 +407,57 @@ if (event.type !== "direct_payment.confirmed") {
   return new Response(null, { status: 204 });
 }
 
-const data = event.data;
+const confirmation = classifyDirectPaymentConfirmation(event);
 
-if (data.mode === "metered_settlement_batch") {
+if (confirmation.kind === "metered_batch_settled") {
   // Aggregated Micro/Nano settlement events do not carry an order challenge.
-  if (data.settlement_status === "settled") {
-    await orders.reconcileMeteredSettlementOnce({
-      settlement_batch_id: String(data.settlement_batch_id ?? ""),
-      chain_receipt_id: String(data.chain_receipt_id ?? ""),
-      usage_event_digest: String(data.usage_event_digest ?? ""),
-      settled_at: String(data.settled_at ?? ""),
-    });
-  }
+  await orders.reconcileMeteredSettlementOnce({
+    settlement_batch_id: confirmation.settlement_batch_id,
+    chain_receipt_id: confirmation.chain_receipt_id,
+    usage_event_digest: confirmation.usage_event_digest,
+    settled_at: confirmation.settled_at ?? null,
+  });
   return new Response(null, { status: 204 });
 }
 
-if (
-  data.pricing_band === "standard" &&
-  data.finality === "per_payment_onchain" &&
-  data.settlement_status === "settled"
-) {
-  const order = await orders.findByChallengeHash(String(data.challenge_hash ?? ""));
+if (confirmation.kind === "standard_settled") {
+  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
   if (!order) {
     await orders.flagForPaymentStateReview({
       reason: "unknown_challenge_hash",
-      requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+      requirement_id: confirmation.requirement_id,
     });
     return new Response(null, { status: 204 });
   }
   await orders.markPaidOnce(order.id, {
-    siglume_requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
-    chain_receipt_id: String(data.chain_receipt_id ?? ""),
+    siglume_requirement_id: confirmation.requirement_id,
+    chain_receipt_id: confirmation.chain_receipt_id,
   });
   return new Response(null, { status: 204 });
 }
 
-if (data.pricing_band === "micro" || data.pricing_band === "nano") {
-  const order = await orders.findByChallengeHash(String(data.challenge_hash ?? ""));
-  if (order) {
-    await orders.markFulfilledButUnsettledOnce(order.id, {
-      siglume_requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
-      pricing_band: String(data.pricing_band),
+if (confirmation.kind === "metered_usage_accepted") {
+  const order = await orders.findByChallengeHash(confirmation.challenge_hash);
+  if (!order) {
+    await orders.flagForPaymentStateReview({
+      reason: "unknown_metered_challenge_hash",
+      requirement_id: confirmation.requirement_id,
     });
+    return new Response(null, { status: 204 });
   }
+  await orders.markFulfilledButUnsettledOnce(order.id, {
+    siglume_requirement_id: confirmation.requirement_id,
+    pricing_band: confirmation.pricing_band,
+  });
   return new Response(null, { status: 204 });
 }
 
 // Missing or unknown machine fields: do not mark the order paid from the event
 // name alone. Fetch the requirement or route it to manual review.
 await orders.flagForPaymentStateReview({
-  reason: "missing_settlement_machine_fields",
-  requirement_id: String(data.requirement_id ?? data.direct_payment_requirement_id ?? ""),
+  reason: confirmation.reason,
+  requirement_id: confirmation.requirement_id ?? "",
+  settlement_batch_id: confirmation.settlement_batch_id ?? null,
 });
 return new Response(null, { status: 204 });
 ```
@@ -464,7 +467,10 @@ Python:
 ```py
 import os
 
-from siglume_direct_request_payment import verify_direct_request_payment_webhook
+from siglume_direct_request_payment import (
+    classify_direct_payment_confirmation,
+    verify_direct_request_payment_webhook,
+)
 
 verified = verify_direct_request_payment_webhook(
     os.environ["SIGLUME_WEBHOOK_SECRET"],
@@ -475,53 +481,54 @@ verified = verify_direct_request_payment_webhook(
 if verified["event"]["type"] != "direct_payment.confirmed":
     return "", 204
 
-data = verified["event"]["data"]
+confirmation = classify_direct_payment_confirmation(verified["event"])
 
-if data.get("mode") == "metered_settlement_batch":
+if confirmation["kind"] == "metered_batch_settled":
     # Aggregated Micro/Nano settlement events do not carry an order challenge.
-    if data.get("settlement_status") == "settled":
-        orders.reconcile_metered_settlement_once(
-            settlement_batch_id=str(data.get("settlement_batch_id") or ""),
-            chain_receipt_id=str(data.get("chain_receipt_id") or ""),
-            usage_event_digest=str(data.get("usage_event_digest") or ""),
-            settled_at=str(data.get("settled_at") or ""),
-        )
+    orders.reconcile_metered_settlement_once(
+        settlement_batch_id=confirmation["settlement_batch_id"],
+        chain_receipt_id=confirmation["chain_receipt_id"],
+        usage_event_digest=confirmation["usage_event_digest"],
+        settled_at=confirmation.get("settled_at"),
+    )
     return "", 204
 
-if (
-    data.get("pricing_band") == "standard"
-    and data.get("finality") == "per_payment_onchain"
-    and data.get("settlement_status") == "settled"
-):
-    order = orders.find_by_challenge_hash(str(data.get("challenge_hash") or ""))
+if confirmation["kind"] == "standard_settled":
+    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
     if not order:
         orders.flag_for_payment_state_review(
             reason="unknown_challenge_hash",
-            requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+            requirement_id=confirmation["requirement_id"],
         )
         return "", 204
     orders.mark_paid_once(
         order["id"],
-        siglume_requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
-        chain_receipt_id=str(data.get("chain_receipt_id") or ""),
+        siglume_requirement_id=confirmation["requirement_id"],
+        chain_receipt_id=confirmation["chain_receipt_id"],
     )
     return "", 204
 
-if data.get("pricing_band") in ("micro", "nano"):
-    order = orders.find_by_challenge_hash(str(data.get("challenge_hash") or ""))
-    if order:
-        orders.mark_fulfilled_but_unsettled_once(
-            order["id"],
-            siglume_requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
-            pricing_band=str(data.get("pricing_band") or ""),
+if confirmation["kind"] == "metered_usage_accepted":
+    order = orders.find_by_challenge_hash(confirmation["challenge_hash"])
+    if not order:
+        orders.flag_for_payment_state_review(
+            reason="unknown_metered_challenge_hash",
+            requirement_id=confirmation["requirement_id"],
         )
+        return "", 204
+    orders.mark_fulfilled_but_unsettled_once(
+        order["id"],
+        siglume_requirement_id=confirmation["requirement_id"],
+        pricing_band=confirmation["pricing_band"],
+    )
     return "", 204
 
 # Missing or unknown machine fields: do not mark the order paid from the event
 # name alone. Fetch the requirement or route it to manual review.
 orders.flag_for_payment_state_review(
-    reason="missing_settlement_machine_fields",
-    requirement_id=str(data.get("requirement_id") or data.get("direct_payment_requirement_id") or ""),
+    reason=confirmation["reason"],
+    requirement_id=confirmation.get("requirement_id") or "",
+    settlement_batch_id=confirmation.get("settlement_batch_id"),
 )
 return "", 204
 ```
@@ -529,11 +536,12 @@ return "", 204
 ## Reconcile Micro / Nano Statements
 
 Standard Payment can be marked paid from the verified `direct_payment.confirmed`
-webhook only when `pricing_band === "standard"`,
-`finality === "per_payment_onchain"`, and `settlement_status === "settled"`.
-Micro Payment and Nano Payment are different: they are automatic amount bands
-and are settled later in aggregated on-chain batches. Use the statement APIs to
-answer:
+webhook only when `classifyDirectPaymentConfirmation(event)` returns
+`standard_settled`, which requires Standard pricing, per-payment on-chain
+finality, settled status, a challenge hash, a requirement id, and a chain
+receipt id. Micro Payment and Nano Payment are different: they are automatic
+amount bands and are settled later in aggregated on-chain batches. Use the
+statement APIs to answer:
 
 - how much Micro / Nano usage is open this week or month,
 - when the buyer's assigned period closes,

package/examples/express-checkout.ts

@@ -1,5 +1,6 @@
 import express from "express";
 import {
+  classifyDirectPaymentConfirmation,
   DirectRequestPaymentMerchantClient,
   verifyDirectRequestPaymentWebhook,
 } from "@siglume/direct-request-payment";
@@ -22,45 +23,54 @@ app.use((req, res, next) => {
 
 const orders = new Map<string, any>();
 
-async function handleDirectPaymentConfirmed(data: Record<string, any>): Promise<void> {
-  if (data.mode === "metered_settlement_batch") {
+async function flagForPaymentStateReview(payload: Record<string, any>): Promise<void> {
+  console.warn("payment state review required", payload);
+}
+
+async function handleDirectPaymentConfirmed(event: any): Promise<void> {
+  const classification = classifyDirectPaymentConfirmation(event);
+
+  if (classification.kind === "metered_batch_settled") {
     // Aggregated Micro/Nano settlement events do not carry an order challenge.
     // Reconcile them against statement / settlement batch data instead.
-    if (data.settlement_status === "settled") {
-      console.log("settled metered batch", data.settlement_batch_id || data.usage_event_digest);
-    }
+    console.log("settled metered batch", classification.settlement_batch_id, classification.chain_receipt_id);
     return;
   }
 
-  if (
-    data.pricing_band === "standard" &&
-    data.finality === "per_payment_onchain" &&
-    data.settlement_status === "settled"
-  ) {
-    const challengeHash = String(data.challenge_hash || "");
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+  if (classification.kind === "standard_settled") {
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
     if (order) {
       order.siglume_payment_status = "paid";
-      order.siglume_requirement_id = data.requirement_id || data.direct_payment_requirement_id;
-      order.siglume_chain_receipt_id = data.chain_receipt_id || null;
+      order.siglume_requirement_id = classification.requirement_id;
+      order.siglume_chain_receipt_id = classification.chain_receipt_id;
+    } else {
+      await flagForPaymentStateReview({
+        reason: "unknown_challenge_hash",
+        requirement_id: classification.requirement_id,
+      });
     }
     return;
   }
 
-  if (data.pricing_band === "micro" || data.pricing_band === "nano") {
-    const challengeHash = String(data.challenge_hash || "");
-    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === challengeHash);
+  if (classification.kind === "metered_usage_accepted") {
+    const order = [...orders.values()].find((item) => item.siglume_challenge_hash === classification.challenge_hash);
     if (order) {
       order.siglume_payment_status = "fulfilled_unsettled";
-      order.siglume_requirement_id = data.requirement_id || data.direct_payment_requirement_id;
+      order.siglume_requirement_id = classification.requirement_id;
+    } else {
+      await flagForPaymentStateReview({
+        reason: "unknown_metered_challenge_hash",
+        requirement_id: classification.requirement_id,
+      });
     }
     return;
   }
 
   // Unknown or older payload shape: do not mark paid from the event name alone.
-  console.warn("direct_payment.confirmed missing settlement machine fields", {
-    id: data.id,
-    requirement_id: data.requirement_id || data.direct_payment_requirement_id,
+  await flagForPaymentStateReview({
+    reason: classification.reason,
+    requirement_id: classification.requirement_id,
+    settlement_batch_id: classification.settlement_batch_id,
   });
 }
 
@@ -111,7 +121,7 @@ app.post("/siglume/webhook", express.raw({ type: "application/json" }), asyncRou
   );
 
   if (event.type === "direct_payment.confirmed") {
-    await handleDirectPaymentConfirmed(event.data);
+    await handleDirectPaymentConfirmed(event);
   }
 
   res.status(204).send();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",