@siglume/direct-request-payment 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.4.6 - 2026-06-19
+
+Patch release for the external webhook-state re-review.
+
+- Changed webhook examples to branch Standard settled payments, Micro / Nano
+  accepted-but-unsettled usage, and metered settlement batches separately.
+- Added Hosted Checkout settlement machine fields and metered settlement batch
+  webhook fields to TypeScript types and API docs.
+- Clarified public Nano one-time amount limits, Micro / Nano idempotency key
+  placement, and per-batch rounding adjustment behavior.
+- Added `pytest python_tests` to the PyPI Trusted Publishing release workflow.
+
+## 0.4.5 - 2026-06-19
+
+Patch release for the public beta re-review.
+
+- Added `cursor` support to TypeScript and Python metered statement list
+  helpers, with tests that fetch a second page.
+- Added missing TypeScript settlement batch retry fields
+  (`attempt_count`, `next_attempt_at`) and narrowed metered minor amount fields
+  to decimal strings.
+- Clarified the public idempotency contract: one-time requirement creation uses
+  the challenge nonce / `challenge_hash` / `request_hash_v2`; the SDK does not
+  expose an unsupported requirement `idempotency_key`.
+- Clarified Micro / Nano rounding, usage CSV `rounding_delta_minor`, provider
+  statement auth roles, and Standard vs aggregated on-chain receipt wording.
+
 ## 0.4.4 - 2026-06-19
 
 Correctness and security hardening release for the SDRP Direct Request Payment

package/README.md

@@ -22,8 +22,9 @@ buyer-facing Siglume payment flow creates and pays the requirement.
 
 `DirectRequestPaymentMerchantClient` requires the merchant's Siglume bearer
 token for setup. `DirectRequestPaymentClient` requires the buyer's Siglume
-bearer token for payment requirements. Do not use a Developer Portal `cli_` API
-key with this package.
+bearer token for payment requirements and buyer statements, or the provider /
+merchant user's Siglume bearer token for provider statements. Do not use a
+Developer Portal `cli_` API key with this package.
 
 ## Two Kinds of Buyer
 
@@ -66,12 +67,16 @@ card-style "instant" checkout for first-time buyers.
 Some merchant accounts may not have the server endpoint enabled yet. In that
 case `createCheckoutSession(...)` / `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError` instead of exposing the raw rollout 404/409.
-Keep fulfilling only from the signed `direct_payment.confirmed` webhook.
+Keep the signed `direct_payment.confirmed` webhook as the durable signal, and
+inspect its settlement machine fields before marking any order paid.
 
 Hosted Checkout is a Siglume-hosted page that turns a "Pay with Siglume" button
 into a completed wallet payment, then returns the shopper to your store. It
-orchestrates the same rails as the agent flow — there is no new money movement
-and the merchant fulfills on the same `direct_payment.confirmed` webhook.
+orchestrates the same rails as the agent flow — there is no new money movement.
+Fulfillment still starts from the signed `direct_payment.confirmed` webhook, but
+you must inspect the settlement machine fields before deciding whether the event
+means Standard settled payment, Micro / Nano accepted usage, or aggregated
+Micro / Nano settlement.
 
 ```ts
 import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
@@ -98,9 +103,12 @@ const session = await merchant.createCheckoutSession({
 });
 redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
-// 3. Fulfill when the signed direct_payment.confirmed webhook arrives (the
-//    source of truth). Poll merchant.getCheckoutSession(session.session_id) if
-//    you also want to show status in your own UI.
+// 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.
+//    Poll merchant.getCheckoutSession(session.session_id) if you also want to
+//    show status in your own UI.
 ```
 
 ```py
@@ -130,9 +138,12 @@ session = merchant.create_checkout_session(
 )
 redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
-# 3. Fulfill when the signed direct_payment.confirmed webhook arrives (the
-#    source of truth). Poll merchant.get_checkout_session(session["session_id"])
-#    if you also want to show status in your own UI.
+# 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.
+#    Poll merchant.get_checkout_session(session["session_id"]) if you also want
+#    to show status in your own UI.
 ```
 
 Siglume fixes the amount, currency, challenge, and return URLs **server-side** at
@@ -183,11 +194,19 @@ Provider revenue in the Micro and Nano bands is not settled revenue until the
 weekly or monthly on-chain settlement succeeds. Siglume keeps outstanding failed
 settlements for retry under the published policy, but does not advance or
 guarantee provider revenue before settlement succeeds.
+If your product cannot fulfill before provider revenue is settled, keep the
+price in the Standard band or agree a merchant-specific contract with Siglume
+before launch.
 Micro / Nano budget checks reserve spending capacity only; they do not lock,
 escrow, or guarantee the buyer's wallet balance, allowance, or settlement funds.
 Sub-minor-unit Nano fees are accumulated with decimal precision and rounded only
 when a settlement batch is created; see [Pricing](./docs/pricing.md) for the
 rounding formula and `rounding_delta_minor` semantics.
+For low-count Nano batches, integer-token settlement can make the effective
+buyer burden per usage higher than the headline USD 0.001 protocol fee; the
+difference is reported as batch `rounding_delta_minor`. Treat Micro / Nano
+minor amounts as decimal strings and use a decimal library or `Decimal` for
+accounting.
 For operational reconciliation, expected revenue, settled revenue, retry state,
 and CSV exports, see
 [docs/metered-statements.md](./docs/metered-statements.md).
@@ -202,7 +221,8 @@ and CSV exports, see
 - buyer-authenticated payment requirement creation
 - prepared wallet transaction execution payloads
 - payment requirement verification
-- authenticated TypeScript JSON requests to Micro / Nano statement APIs
+- authenticated TypeScript JSON requests and named Python helpers for Micro /
+  Nano statement APIs
 - signed webhook verification
 
 It does not custody funds or manage customer wallets. Merchant setup runs through
@@ -244,9 +264,11 @@ Launch plan. The current public API does not expose a flag that forces a
 JPY 500-and-under / USD 3-and-under payment into Standard immediate settlement.
 If immediate on-chain settlement is a hard requirement, price the item in the
 Standard band or confirm a merchant-specific contract with Siglume before
-launch. For Standard Payment, `fee_bps` returned on a payment requirement is the
-authoritative fee rate for that payment in the merchant's settlement currency.
-For Micro / Nano, the statement APIs expose `protocol_fee_minor`,
+launch. Public Direct Payment / Hosted Checkout `amount_minor` is a positive
+integer in minor currency units, so public one-time Nano amounts start at JPY 1
+or USD 0.01. For Standard Payment, `fee_bps` returned on a payment requirement
+is the authoritative fee rate for that payment in the merchant's settlement
+currency. For Micro / Nano, the statement APIs expose `protocol_fee_minor`,
 `gross_buyer_debit_minor`, `buyer_debit_minor`, and `rounding_delta_minor`.
 The full fee table and the weekly / monthly settlement schedule live in
 [docs/pricing.md](./docs/pricing.md). Statement APIs for "how much was used,
@@ -358,7 +380,7 @@ The nonce must not contain `:` because the current platform challenge format is
 
 ## Buyer Payment Flow
 
-Use `DirectRequestPaymentClient` only with the authenticated buyer's Siglume
+Use `DirectRequestPaymentClient` here with the authenticated buyer's Siglume
 bearer token. `SIGLUME_AUTH_TOKEN` may be used in server-side payment-confirmation
 helpers; `SIGLUME_API_KEY` and Developer Portal `cli_` keys are not accepted.
 
@@ -507,7 +529,19 @@ const { event } = await verifyDirectRequestPaymentWebhook(
 );
 
 if (event.type === "direct_payment.confirmed") {
-  // Mark the order paid if event.data.challenge_hash/order mapping matches.
+  if (event.data.mode === "metered_settlement_batch") {
+    // 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"
+  ) {
+    // 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.
+  }
 }
 ```
 
@@ -523,14 +557,30 @@ verified = verify_direct_request_payment_webhook(
 )
 
 if verified["event"]["type"] == "direct_payment.confirmed":
-    # Mark the order paid if event.data.challenge_hash/order mapping matches.
-    pass
+    data = verified["event"]["data"]
+    if data.get("mode") == "metered_settlement_batch":
+        # 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"
+    ):
+        # 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.
+        pass
 ```
 
 New `direct_payment.confirmed` payloads include `pricing_band`,
-`settlement_cadence`, `finality`, `protocol_fee_minor`, `settlement_status`, and
-when available `request_hash_v2`. Use these machine fields instead of inferring
-settlement semantics from the event name alone.
+`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.
 
 ## Security Rules
 
@@ -553,7 +603,8 @@ Read [docs/security.md](./docs/security.md) before going live.
 - Store `SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET` only on the merchant server.
 - Store the returned `SIGLUME_WEBHOOK_SECRET` only on the merchant server.
 - Persist `challenge_hash`, `requirement_id`, and fulfillment state per order.
-- Fulfill orders only from verified webhook data, with idempotency.
+- Fulfill orders only from verified webhook data, with idempotency, after
+  checking `pricing_band`, `finality`, and `settlement_status`.
 - Treat `fee_bps` returned by Siglume as the Standard Payment runtime fee source
   of truth; use statement API amount fields for Micro / Nano.
 

package/dist/index.cjs

@@ -78,7 +78,7 @@ 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.4";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.6";
 var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {
@@ -126,7 +126,7 @@ var DirectRequestPaymentClient = class {
     const authToken = options.auth_token ?? envValue("SIGLUME_AUTH_TOKEN");
     if (!authToken) {
       throw new SiglumeDirectRequestPaymentError(
-        "A buyer Siglume bearer token is required for Direct Request Payment API calls. Developer Portal API keys are not accepted."
+        "A buyer or provider Siglume user bearer token is required for Direct Request Payment API calls. Developer Portal API keys are not accepted."
       );
     }
     const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -811,6 +811,9 @@ function meteredQueryPath(path, input) {
   if ("limit" in input && input.limit !== void 0) {
     params.set("limit", String(positiveInteger(input.limit, "limit")));
   }
+  if ("cursor" in input && input.cursor !== void 0) {
+    params.set("cursor", requireNonEmpty(input.cursor, "cursor"));
+  }
   const query = params.toString();
   return query ? `${path}?${query}` : path;
 }