@siglume/direct-request-payment 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.4.9 - 2026-06-19
+
+Classifier consistency patch release.
+
+- Required Micro / Nano settlement batch confirmations to carry aggregated
+  on-chain finality, a valid Micro/Nano pricing band, and the expected weekly or
+  monthly settlement cadence before returning `metered_batch_settled`.
+- Added TypeScript and Python tests for missing finality, wrong finality,
+  missing pricing band, and Micro/Nano cadence mismatches.
+
+## 0.4.8 - 2026-06-19
+
+Webhook sample hardening release.
+
+- Added TypeScript and Python confirmation classifiers for Standard settled
+  payments, Micro / Nano accepted usage, and Micro / Nano settled batches.
+- Updated public webhook samples to require finality, settlement status, and
+  non-empty settlement identifiers before fulfilling or reconciling.
+- Routed unknown Micro / Nano challenge hashes and malformed settlement batch
+  confirmations to manual review in copy-paste samples.
+
 ## 0.4.7 - 2026-06-19
 
 Documentation-only patch release.

package/README.md

@@ -103,10 +103,10 @@ const session = await merchant.createCheckoutSession({
 });
 redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
-// 3. Handle the signed direct_payment.confirmed webhook. Fulfill Standard only
-//    when pricing_band=standard, finality=per_payment_onchain, and
-//    settlement_status=settled. Treat Micro / Nano as accepted but unsettled
-//    until the later metered settlement batch is settled.
+// 3. Handle the signed direct_payment.confirmed webhook. Use
+//    classifyDirectPaymentConfirmation(event). Fulfill Standard only for
+//    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
+//    until the later metered_batch_settled event arrives.
 //    Poll merchant.getCheckoutSession(session.session_id) if you also want to
 //    show status in your own UI.
 ```
@@ -138,10 +138,10 @@ session = merchant.create_checkout_session(
 )
 redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
-# 3. Handle the signed direct_payment.confirmed webhook. Fulfill Standard only
-#    when pricing_band=standard, finality=per_payment_onchain, and
-#    settlement_status=settled. Treat Micro / Nano as accepted but unsettled
-#    until the later metered settlement batch is settled.
+# 3. Handle the signed direct_payment.confirmed webhook. Use
+#    classify_direct_payment_confirmation(event). Fulfill Standard only for
+#    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
+#    until the later metered_batch_settled event arrives.
 #    Poll merchant.get_checkout_session(session["session_id"]) if you also want
 #    to show status in your own UI.
 ```
@@ -525,7 +525,10 @@ the payload. Create a marketplace webhook subscription with
 signing secret once.
 
 ```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!,
@@ -534,18 +537,16 @@ const { event } = await verifyDirectRequestPaymentWebhook(
 );
 
 if (event.type === "direct_payment.confirmed") {
-  if (event.data.mode === "metered_settlement_batch") {
+  const confirmation = classifyDirectPaymentConfirmation(event);
+  if (confirmation.kind === "metered_batch_settled") {
     // Reconcile settled Micro / Nano batches by settlement_batch_id /
     // usage_event_digest; these events do not carry an order challenge hash.
-  } else if (
-    event.data.pricing_band === "standard" &&
-    event.data.finality === "per_payment_onchain" &&
-    event.data.settlement_status === "settled"
-  ) {
+  } else if (confirmation.kind === "standard_settled") {
     // Mark the order paid once if event.data.challenge_hash/order mapping matches.
-  } else if (event.data.pricing_band === "micro" || event.data.pricing_band === "nano") {
-    // Mark fulfilled-but-unsettled only if your business allows fulfillment
-    // before the aggregated Micro / Nano settlement succeeds.
+  } else if (confirmation.kind === "metered_usage_accepted") {
+    // Mark fulfilled-but-unsettled after matching confirmation.challenge_hash.
+  } else {
+    // Route confirmation.reason to manual review. Do not mark paid or fulfilled.
   }
 }
 ```
@@ -553,7 +554,10 @@ if (event.type === "direct_payment.confirmed") {
 ```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"],
@@ -562,30 +566,30 @@ verified = verify_direct_request_payment_webhook(
 )
 
 if verified["event"]["type"] == "direct_payment.confirmed":
-    data = verified["event"]["data"]
-    if data.get("mode") == "metered_settlement_batch":
+    confirmation = classify_direct_payment_confirmation(verified["event"])
+    if confirmation["kind"] == "metered_batch_settled":
         # Reconcile settled Micro / Nano batches by settlement_batch_id /
         # usage_event_digest; these events do not carry an order challenge hash.
         pass
-    elif (
-        data.get("pricing_band") == "standard"
-        and data.get("finality") == "per_payment_onchain"
-        and data.get("settlement_status") == "settled"
-    ):
+    elif confirmation["kind"] == "standard_settled":
         # Mark the order paid once if event.data.challenge_hash/order mapping matches.
         pass
-    elif data.get("pricing_band") in ("micro", "nano"):
-        # Mark fulfilled-but-unsettled only if your business allows fulfillment
-        # before the aggregated Micro / Nano settlement succeeds.
+    elif confirmation["kind"] == "metered_usage_accepted":
+        # Mark fulfilled-but-unsettled after matching confirmation["challenge_hash"].
+        pass
+    else:
+        # Route confirmation["reason"] to manual review. Do not mark paid or fulfilled.
         pass
 ```
 
 New `direct_payment.confirmed` payloads include `pricing_band`,
 `settlement_cadence`, `finality`, `protocol_fee_minor`, `settlement_status`,
 `settlement_batch_id`, `chain_receipt_id`, `usage_event_digest`, `settled_at`,
-and when available `request_hash_v2`. Use these machine fields instead of
-inferring settlement semantics from the event name alone. Do not mark an order
-paid from the event type alone.
+and when available `request_hash_v2`. Use
+`classifyDirectPaymentConfirmation(event)` /
+`classify_direct_payment_confirmation(event)` or the same machine-field checks
+instead of inferring settlement semantics from the event name alone. Do not mark
+an order paid from the event type alone.
 
 ## Security Rules
 

package/dist/index.cjs

@@ -34,11 +34,15 @@ __export(src_exports, {
   DEFAULT_WEBHOOK_TOLERANCE_SECONDS: () => DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
   DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND: () => DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME: () => DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME,
+  DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS: () => DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS,
+  DIRECT_REQUEST_PAYMENT_METERED_FINALITY: () => DIRECT_REQUEST_PAYMENT_METERED_FINALITY,
   DIRECT_REQUEST_PAYMENT_MODE: () => DIRECT_REQUEST_PAYMENT_MODE,
   DIRECT_REQUEST_PAYMENT_RECEIPT_KIND: () => DIRECT_REQUEST_PAYMENT_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME: () => DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME,
   DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE: () => DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE,
   DIRECT_REQUEST_PAYMENT_SDK_VERSION: () => DIRECT_REQUEST_PAYMENT_SDK_VERSION,
+  DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY: () => DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY,
+  DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS: () => DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS,
   DirectRequestPaymentClient: () => DirectRequestPaymentClient,
   DirectRequestPaymentMerchantClient: () => DirectRequestPaymentMerchantClient,
   HostedCheckoutNotAvailableError: () => HostedCheckoutNotAvailableError,
@@ -50,6 +54,7 @@ __export(src_exports, {
   buildPaymentExecutionPayload: () => buildPaymentExecutionPayload,
   buildPreparedTransactionExecutionPayload: () => buildPreparedTransactionExecutionPayload,
   buildWebhookSignatureHeader: () => buildWebhookSignatureHeader,
+  classifyDirectPaymentConfirmation: () => classifyDirectPaymentConfirmation,
   computeWebhookSignature: () => computeWebhookSignature,
   createDirectRequestPaymentChallenge: () => createDirectRequestPaymentChallenge,
   createDirectRequestPaymentChallengeSignature: () => createDirectRequestPaymentChallengeSignature,
@@ -78,7 +83,11 @@ var DIRECT_REQUEST_PAYMENT_RECEIPT_KIND = "sdrp_direct_payment";
 var DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND = "sdrp_direct_payment_allowance";
 var DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE = "sdrp_direct_payment_requirement";
 var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
-var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.7";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.9";
+var DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS = "settled";
+var DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS = "pending_settlement";
+var DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY = "per_payment_onchain";
+var DIRECT_REQUEST_PAYMENT_METERED_FINALITY = "aggregated_onchain_settlement";
 var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {
@@ -671,6 +680,120 @@ function parseDirectRequestPaymentWebhookEvent(payload) {
   }
   return parsed;
 }
+function classifyDirectPaymentConfirmation(event) {
+  const data = event.data;
+  const requirementId = stringOrNull(data.requirement_id) ?? stringOrNull(data.direct_payment_requirement_id);
+  const challengeHash = stringOrNull(data.challenge_hash);
+  const pricingBand = stringOrNull(data.pricing_band);
+  const settlementCadence = stringOrNull(data.settlement_cadence);
+  const finality = stringOrNull(data.finality);
+  const settlementStatus = stringOrNull(data.settlement_status);
+  if (event.type !== "direct_payment.confirmed") {
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "not_direct_payment_confirmed",
+      requirement_id: requirementId,
+      settlement_batch_id: stringOrNull(data.settlement_batch_id),
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (data.mode === "metered_settlement_batch") {
+    const settlementBatchId = stringOrNull(data.settlement_batch_id);
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    const usageEventDigest = stringOrNull(data.usage_event_digest);
+    if (settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && finality === DIRECT_REQUEST_PAYMENT_METERED_FINALITY && (pricingBand === "micro" || pricingBand === "nano") && settlementCadence === (pricingBand === "micro" ? "weekly" : "monthly") && settlementBatchId && chainReceiptId && usageEventDigest) {
+      return {
+        kind: "metered_batch_settled",
+        event,
+        data,
+        pricing_band: pricingBand,
+        settlement_cadence: pricingBand === "micro" ? "weekly" : "monthly",
+        settlement_batch_id: settlementBatchId,
+        chain_receipt_id: chainReceiptId,
+        usage_event_digest: usageEventDigest,
+        settled_at: stringOrNull(data.settled_at)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "invalid_metered_settlement_confirmation",
+      requirement_id: requirementId,
+      settlement_batch_id: settlementBatchId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "standard") {
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    if (finality === DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && requirementId && challengeHash && chainReceiptId) {
+      return {
+        kind: "standard_settled",
+        event,
+        data,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        chain_receipt_id: chainReceiptId,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_standard_settlement_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "micro" || pricingBand === "nano") {
+    if (finality === DIRECT_REQUEST_PAYMENT_METERED_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS && requirementId && challengeHash) {
+      return {
+        kind: "metered_usage_accepted",
+        event,
+        data,
+        pricing_band: pricingBand,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_metered_usage_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  return {
+    kind: "unknown",
+    event,
+    data,
+    reason: "unknown_confirmation_shape",
+    requirement_id: requirementId,
+    settlement_batch_id: stringOrNull(data.settlement_batch_id),
+    pricing_band: pricingBand,
+    settlement_cadence: settlementCadence,
+    settlement_status: settlementStatus,
+    finality
+  };
+}
 async function verifyDirectRequestPaymentWebhook(signing_secret, body, signature_header, options = {}) {
   const verification = await verifyWebhookSignature(signing_secret, body, signature_header, options);
   const text = new TextDecoder().decode(bodyBytes(body));