@siglume/direct-request-payment 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 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.
+
+- Added the Micro / Nano Statements and Notices manual, covering buyer and
+  provider statement APIs, CSV export, final debit notices, the close-plus-3-day
+  debit site, past-due blocks, sanitized failure fields, and support references.
+- Expanded API reference, merchant quickstart, security, pricing, and Japanese
+  announcement docs so integrators can reconcile settled, unsettled, retrying,
+  and past-due Micro / Nano revenue without relying on private platform fields.
+- No wire-format or runtime behavior changes.
+
 ## 0.4.2 - 2026-06-19
 
 Documentation completeness release. No wire-format or API changes; 0.4.x clients

package/README.md

@@ -89,7 +89,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 +121,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 +183,14 @@ 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 operational reconciliation, expected revenue, settled revenue, retry state,
+and CSV exports, see
+[docs/metered-statements.md](./docs/metered-statements.md).
 
 ## What This SDK Covers
 
@@ -194,6 +202,7 @@ guarantee provider revenue before settlement succeeds.
 - buyer-authenticated payment requirement creation
 - prepared wallet transaction execution payloads
 - payment requirement verification
+- authenticated TypeScript JSON requests to Micro / Nano statement APIs
 - signed webhook verification
 
 It does not custody funds or manage customer wallets. Merchant setup runs through
@@ -226,15 +235,23 @@ 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 |
-| JPY 50-500 / about USD 0.30-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 1 to JPY 49 / under USD 0.01 to about 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) |
+| 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
-[docs/pricing.md](./docs/pricing.md).
+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).
 
 ## Merchant Setup: One SDK Call
 
@@ -510,6 +527,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.
@@ -532,7 +554,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
 
@@ -549,6 +572,7 @@ Read [docs/security.md](./docs/security.md) before going live.
 - [Merchant quickstart](./docs/merchant-quickstart.md)
 - [API reference](./docs/api-reference.md)
 - [Pricing](./docs/pricing.md)
+- [Micro / Nano statements and notices](./docs/metered-statements.md)
 - [Security guide](./docs/security.md)
 - [Merchant setup example](./examples/setup-merchant.ts)
 - [Express checkout example](./examples/express-checkout.ts)

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.4";
+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);
@@ -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.2";
+    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.2";
+    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,44 @@ 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")));
+  }
+  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.`);
   }