@siglume/direct-request-payment 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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
+SDK manual and public helpers.
+
+- Clarified that Standard / Micro / Nano are selected by amount, removed the
+  unsupported "force Standard for immediate finality" implication, and changed
+  Hosted Checkout Standard examples to Standard-band amounts.
+- Removed the Express sample route that accepted a buyer `Authorization` header
+  on the merchant server; human web checkout now redirects through Hosted
+  Checkout, while agent payment remains buyer-side direct API/tool work.
+- Documented Micro / Nano decimal fee rounding, `rounding_delta_minor`, budget
+  reservation versus token locking, no guaranteed `past_due` collection, HTTP
+  result accounting, and operational status handling.
+- Added typed TypeScript and named Python helpers for Micro / Nano statement
+  APIs.
+- Added `request_hash_v2` helpers/docs and documented the new
+  requirement/webhook machine fields for pricing band, settlement cadence,
+  finality, protocol fee, and settlement status.
+- Hardened TS/Python integer and `checkout_allowed_origins` validation.
+
 ## 0.4.3 - 2026-06-19
 
 Documentation-only release for SDRP Micro / Nano operations.

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
 
@@ -89,7 +90,7 @@ await merchant.setupMerchant({
 // 2. Per order: create a session and redirect the shopper to checkout_url.
 const session = await merchant.createCheckoutSession({
   merchant: "your_merchant_key",
-  amount_minor: 500,            // server-fixed; the browser cannot change it
+  amount_minor: 1200,           // server-fixed; the browser cannot change it
   currency: "JPY",
   nonce: order.id,              // unique per order
   success_url: "https://www.your-shop.com/thanks",
@@ -121,7 +122,7 @@ merchant.setup_merchant(
 # 2. Per order: create a session and redirect the shopper to checkout_url.
 session = merchant.create_checkout_session(
     merchant="your_merchant_key",
-    amount_minor=500,            # server-fixed; the browser cannot change it
+    amount_minor=1200,           # server-fixed; the browser cannot change it
     currency="JPY",
     nonce=order["id"],           # unique per order
     success_url="https://www.your-shop.com/thanks",
@@ -183,6 +184,16 @@ 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.
+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).
@@ -230,14 +241,20 @@ amounts differ.
 
 | Payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
-| Over JPY 500 / over USD 3.00, or whenever immediate finality is required | Standard Payment | Select one Standard plan: Launch, Starter, Growth, or Pro | Launch: JPY 0 / USD 0 monthly, 1.8%; Starter: JPY 980 / USD 6 monthly, 1.0%; Growth: JPY 2,980 / USD 18 monthly, 0.7%; Pro: JPY 9,800 / USD 60 monthly, 0.5%. Minimum JPY 30 / USD 0.20 per payment. | Settled on-chain immediately after the payment confirms |
+| Over JPY 500 / over USD 3.00 | Standard Payment | Select one Standard plan: Launch, Starter, Growth, or Pro | Launch: JPY 0 / USD 0 monthly, 1.8%; Starter: JPY 980 / USD 6 monthly, 1.0%; Growth: JPY 2,980 / USD 18 monthly, 0.7%; Pro: JPY 9,800 / USD 60 monthly, 0.5%. Minimum JPY 30 / USD 0.20 per payment. | Settled on-chain immediately after the payment confirms |
 | JPY 50-500 / over USD 0.30 and up to USD 3.00 | Micro Payment | Applied automatically by amount | USD 0.01 / Tx, about JPY 2 | Weekly settlement - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
 | Under JPY 50 / up to USD 0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / usage, about JPY 0.2 | Monthly settlement - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
 
 A merchant billing mandate is required before accepting payments, even on the
-Launch plan. `fee_bps` returned on a payment requirement is the authoritative
-fee rate for that payment in the merchant's settlement currency. The full fee
-table and the weekly / monthly settlement schedule live in
+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`,
+`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,
 when will it close, when can it debit, and what is settled" are documented in
 [docs/metered-statements.md](./docs/metered-statements.md).
@@ -347,7 +364,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.
 
@@ -516,6 +533,11 @@ if verified["event"]["type"] == "direct_payment.confirmed":
     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.
+
 ## Security Rules
 
 - Keep the challenge secret on the merchant server only.
@@ -538,7 +560,8 @@ Read [docs/security.md](./docs/security.md) before going live.
 - 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.
-- Treat `fee_bps` returned by Siglume as the runtime fee source of truth.
+- Treat `fee_bps` returned by Siglume as the Standard Payment runtime fee source
+  of truth; use statement API amount fields for Micro / Nano.
 
 ## Compatibility Notes
 

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(src_exports, {
   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,
   DirectRequestPaymentClient: () => DirectRequestPaymentClient,
   DirectRequestPaymentMerchantClient: () => DirectRequestPaymentMerchantClient,
   HostedCheckoutNotAvailableError: () => HostedCheckoutNotAvailableError,
@@ -58,6 +59,7 @@ __export(src_exports, {
   createExternal402RecurringChallenge: () => createExternal402RecurringChallenge,
   directRequestPaymentChallengeHash: () => directRequestPaymentChallengeHash,
   directRequestPaymentRequestHash: () => directRequestPaymentRequestHash,
+  directRequestPaymentRequestHashV2: () => directRequestPaymentRequestHashV2,
   parseDirectRequestPaymentChallenge: () => parseDirectRequestPaymentChallenge,
   parseDirectRequestPaymentWebhookEvent: () => parseDirectRequestPaymentWebhookEvent,
   verifyDirectRequestPaymentChallenge: () => verifyDirectRequestPaymentChallenge,
@@ -76,6 +78,8 @@ 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.5";
+var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {
     super(message);
@@ -122,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;
@@ -132,7 +136,7 @@ var DirectRequestPaymentClient = class {
     this.auth_token = authToken;
     this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
-    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.4.3";
+    this.user_agent = options.user_agent ?? `@siglume/direct-request-payment/${DIRECT_REQUEST_PAYMENT_SDK_VERSION}`;
     this.fetch_impl = fetchImpl;
   }
   async createPaymentRequirement(input) {
@@ -180,6 +184,53 @@ var DirectRequestPaymentClient = class {
   async executeAllowanceTransaction(requirement, options = {}) {
     return this.executePreparedTransaction(buildAllowanceExecutionPayload(requirement, options));
   }
+  async getBuyerMeteredSummary(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/my-summary", input)
+    );
+  }
+  async listBuyerUsageEvents(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/my-usage-events", input)
+    );
+  }
+  async listBuyerSettlementBatches(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/my-settlement-batches", input)
+    );
+  }
+  async getProviderMeteredSummary(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/provider/summary", input)
+    );
+  }
+  async listProviderUsageEvents(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/provider/usage-events", input)
+    );
+  }
+  async listProviderSettlementBatches(input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath("/sdrp/metered/provider/settlement-batches", input)
+    );
+  }
+  async getProviderSettlementBatch(settlement_batch_id, input = {}) {
+    return this.request(
+      "GET",
+      meteredQueryPath(
+        `/sdrp/metered/provider/settlement-batches/${encodeURIComponent(
+          requireNonEmpty(settlement_batch_id, "settlement_batch_id")
+        )}`,
+        input
+      )
+    );
+  }
   async request(method, path, json_body) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeout_ms);
@@ -237,7 +288,7 @@ var DirectRequestPaymentMerchantClient = class {
     this.auth_token = authToken;
     this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
-    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.4.3";
+    this.user_agent = options.user_agent ?? `@siglume/direct-request-payment/${DIRECT_REQUEST_PAYMENT_SDK_VERSION}`;
     this.fetch_impl = fetchImpl;
   }
   async setupMerchant(input) {
@@ -530,6 +581,16 @@ async function directRequestPaymentRequestHash(input) {
   const material = `${normalizeMerchant(input.merchant)}${positiveInteger(input.amount_minor, "amount_minor")}${normalizeCurrency(input.currency)}${requireNonEmpty(input.challenge, "challenge")}`;
   return sha256Prefixed(material);
 }
+async function directRequestPaymentRequestHashV2(input) {
+  const material = JSON.stringify({
+    amount_minor: positiveInteger(input.amount_minor, "amount_minor"),
+    challenge: requireNonEmpty(input.challenge, "challenge"),
+    currency: normalizeCurrency(input.currency),
+    merchant: normalizeMerchant(input.merchant),
+    version: 2
+  });
+  return sha256Prefixed(material);
+}
 function buildPaymentExecutionPayload(requirement, options = {}) {
   return buildPreparedTransactionExecutionPayload(requirement, requirement.transaction_request, {
     receipt_kind: DIRECT_REQUEST_PAYMENT_RECEIPT_KIND,
@@ -603,8 +664,10 @@ function parseDirectRequestPaymentWebhookEvent(payload) {
     occurred_at: requireNonEmpty(stringOrNull(event.occurred_at) ?? "", "webhook occurred_at"),
     data: { ...data }
   };
-  if (parsed.type === "direct_payment.confirmed" && parsed.data.mode !== DIRECT_REQUEST_PAYMENT_MODE) {
-    throw new SiglumeWebhookPayloadError("direct_payment.confirmed webhook must carry data.mode='external_402'.");
+  if (parsed.type === "direct_payment.confirmed" && !DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES.has(String(parsed.data.mode ?? ""))) {
+    throw new SiglumeWebhookPayloadError(
+      "direct_payment.confirmed webhook must carry a supported Direct Request Payment mode."
+    );
   }
   return parsed;
 }
@@ -658,6 +721,13 @@ function normalizeToken(value) {
   }
   return token;
 }
+function normalizeMeteredPlanType(value) {
+  const planType = requireNonEmpty(value, "plan_type").toLowerCase();
+  if (planType === "micro" || planType === "nano") {
+    return planType;
+  }
+  throw new SiglumeDirectRequestPaymentError("plan_type must be micro or nano.");
+}
 function normalizeAllowedCurrencies(value) {
   const normalized = {};
   if (Array.isArray(value)) {
@@ -695,7 +765,15 @@ function normalizeOriginList(value) {
         "each checkout_allowed_origins entry must be an absolute origin such as https://shop.example.com."
       );
     }
-    const origin = `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}`;
+    if (url.username || url.password) {
+      throw new SiglumeDirectRequestPaymentError("checkout_allowed_origins entries must not include userinfo.");
+    }
+    if (!isAllowedCheckoutOriginScheme(url)) {
+      throw new SiglumeDirectRequestPaymentError(
+        "checkout_allowed_origins entries must use https, except http is allowed for localhost, 127.0.0.1, or [::1]."
+      );
+    }
+    const origin = url.origin.toLowerCase();
     if (!seen.has(origin)) {
       seen.add(origin);
       origins.push(origin);
@@ -703,8 +781,47 @@ function normalizeOriginList(value) {
   }
   return origins;
 }
+function isAllowedCheckoutOriginScheme(url) {
+  if (url.protocol === "https:") {
+    return Boolean(url.hostname);
+  }
+  if (url.protocol !== "http:") {
+    return false;
+  }
+  const hostname = url.hostname.toLowerCase();
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+}
+function meteredQueryPath(path, input) {
+  const params = new URLSearchParams();
+  if (input.plan_type !== void 0) {
+    params.set("plan_type", normalizeMeteredPlanType(input.plan_type));
+  }
+  if (input.token_symbol !== void 0) {
+    params.set("token_symbol", normalizeToken(input.token_symbol));
+  }
+  if ("status" in input && input.status !== void 0) {
+    params.set("status", requireNonEmpty(input.status, "status"));
+  }
+  if ("listing_id" in input && input.listing_id !== void 0) {
+    params.set("listing_id", requireNonEmpty(input.listing_id, "listing_id"));
+  }
+  if ("capability_key" in input && input.capability_key !== void 0) {
+    params.set("capability_key", requireNonEmpty(input.capability_key, "capability_key"));
+  }
+  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;
+}
 function positiveInteger(value, name) {
-  const parsed = Number(value);
+  if (typeof value !== "number") {
+    throw new SiglumeDirectRequestPaymentError(`${name} must be a positive safe integer.`);
+  }
+  const parsed = value;
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
     throw new SiglumeDirectRequestPaymentError(`${name} must be a positive safe integer.`);
   }