@siglume/direct-request-payment 0.4.11 → 0.4.13

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.13 - 2026-06-19
+
+Seller-borne Micro / Nano protocol fee correction.
+
+- Added `provider_usage_amount_minor` to provider usage events so provider usage
+  amount and provider receivable can be reconciled separately.
+- Clarified that all SDRP payment fees are seller-borne: Micro / Nano protocol
+  fees are deducted from provider receivable and are not added to buyer debit.
+- Updated metered statement formulas, CSV documentation, and API reference amount
+  names to match the seller-borne settlement model.
+
+## 0.4.12 - 2026-06-19
+
+Documentation-only fee-unit correction.
+
+- Unified Micro and Nano protocol fee units as `/ SDRP Tx`.
+- Clarified that `Tx` means one accepted SDRP payment, not the later on-chain
+  settlement transaction.
+
 ## 0.4.11 - 2026-06-19
 
 Documentation-only pricing correction.
@@ -20,9 +39,9 @@ Public beta scope and metered usage hardening patch.
 - Clarified that the current public beta supports JPYC / USDC settlement on
   Polygon PoS only and does not support multi-chain, cross-chain, or
   multi-wallet settlement routing through the public SDK.
-- Clarified that Standard Payment fees are deducted from merchant settlement,
-  while Micro / Nano protocol fees are added to buyer debit and are not provider
-  revenue.
+- Clarified Standard Payment fee deduction and Micro / Nano fee reporting. The
+  Micro / Nano fee-burden wording from that release was superseded by the
+  seller-borne correction in 0.4.13.
 
 ## 0.4.9 - 2026-06-19
 
@@ -128,7 +147,7 @@ public capability is now documented and every signature verified against code.
   `buildPreparedTransactionExecutionPayload`, and `computeWebhookSignature` (plus
   full per-function webhook-verification entries with examples).
 - Added an **Exported Constants** table (all 8 importable constants with values)
-  and an **Aliases** table (the `external_402*` legacy aliases → preferred
+  and an **Aliases** table (the `external_402*` legacy aliases ↁEpreferred
   `DirectRequestPayment*` names).
 - Replaced the "Python uses snake_case" hand-wave with the **actual Python
   keyword-only signatures** for the challenge / webhook / signature verifiers.
@@ -167,7 +186,7 @@ and humans pay through a Siglume-hosted checkout page.
   challenge server-side and returns a `checkout_url`; redirect the shopper there.
   The shopper logs into Siglume, approves, and pays from their own Siglume wallet
   (JPYC / USDC), then returns to your `success_url`. Fulfill on the existing
-  `direct_payment.confirmed` webhook — the source of truth — exactly as with the
+  `direct_payment.confirmed` webhook  Ethe source of truth  Eexactly as with the
   agent flow. The merchant SDK still does not authenticate the buyer.
 - **`getCheckoutSession(session_id)`** (TS + Py): read a session's status
   (`open` / `authenticated` / `paid` / `expired` / `cancelled` / `failed`).
@@ -178,7 +197,7 @@ and humans pay through a Siglume-hosted checkout page.
 - Docs: documented the **two buyer systems** (human Web = Hosted Checkout; AI
   agent / AtoA = direct API / tools), the AtoA **prerequisite** that the buyer
   agent is pre-connected to Siglume (MCP/OAuth, or a custom app holding the
-  buyer's Siglume JWT), and the merchant / Siglume / buyer **boundaries** —
+  buyer's Siglume JWT), and the merchant / Siglume / buyer **boundaries**  E
   including that the buyer needs a Siglume wallet and this is **not** a card
   payment.
 
@@ -195,7 +214,7 @@ challenges and clients from 0.3.x interoperate unchanged.
   pricing guide: Micro settles weekly, Nano settles monthly, with the closing
   period, timezone, revenue-recognition point, retry / carry-over, and
   rejected / no-charge behavior spelled out. The exact close time, default
-  timezone, and settlement lag are marked platform-managed — the platform
+  timezone, and settlement lag are marked platform-managed  Ethe platform
   response is the source of truth.
 - Clarified that Micro / Nano provider revenue stays unsettled until the weekly /
   monthly on-chain settlement succeeds, that failed settlements are retried and
@@ -218,8 +237,8 @@ challenges and clients from 0.3.x interoperate unchanged.
 
 ## 0.3.4 - 2026-06-18
 
-- Docs: clarified the SDRP pricing structure — a Standard plan is selected, and
-  Micro / Nano are applied automatically by amount — across the README and
+- Docs: clarified the SDRP pricing structure  Ea Standard plan is selected, and
+  Micro / Nano are applied automatically by amount  Eacross the README and
   pricing guide.
 
 ## 0.3.3 - 2026-06-18
@@ -237,7 +256,7 @@ challenges and clients from 0.3.x interoperate unchanged.
   tag, not a once-per-day run limit. Siglume no longer caps scheduled autopay
   at one charge per day; occurrences are bounded by the buyer's per-run,
   daily, and monthly auto-pay budget plus the authorization's `max_runs` /
-  expiry. No code or wire-format changes — challenges signed by 0.3.0 verify
+  expiry. No code or wire-format changes  Echallenges signed by 0.3.0 verify
   unchanged.
 - Release automation now uses npm and PyPI Trusted Publishing from GitHub
   Actions, so normal releases do not require local npm OTP or PyPI credentials.
@@ -261,7 +280,7 @@ Recurring payment approval release.
 - Documented the recurring payment flow (subscription and scheduled autopay)
   in the README.
 - Updated pricing docs: the Launch plan's free monthly allowance of 100
-  payments is retired — Launch is now a flat 1.8% payment fee; the per-payment
+  payments is retired  ELaunch is now a flat 1.8% payment fee; the per-payment
   minimum fee is JPY 30 (USD merchants: USD 0.20); JPY/JPYC and USD/USDC
   settlement are both documented as first-class.
 

package/README.md

@@ -10,6 +10,17 @@ that want to accept Siglume wallet payments. The merchant fixes the order,
 amount, and currency on its server; the buyer pays with a Siglume wallet;
 Siglume applies the correct pricing and settlement path from the payment amount.
 
+**Relationship to HTTP 402.** SDRP is built around the HTTP **402 Payment
+Required** status: the Siglume platform returns **402 Payment Required** when a
+payment is required but not yet completed (for example, attempting to consume a
+payment requirement before it is confirmed). SDRP is **not wire-compatible with
+Coinbase's x402** — the challenge and payment-payload design is different. SDRP
+binds a signed `scheme:nonce:signature` challenge to the merchant, amount, and
+currency, settles through a Siglume wallet (JPYC / USDC), and confirms via a
+signed webhook; it does **not** use x402's HTTP-header payment payload or its
+single-request pay-and-retry handshake. The internal mode name `external_402`
+reflects this 402 lineage.
+
 Use this package when an external EC site, booking service, membership service,
 or paid API wants to accept Siglume wallet payments without taking custody of
 customer funds. The SDK creates and verifies one-time and recurring wallet
@@ -188,16 +199,23 @@ setup, and after that the applied fee and the settlement timing follow the
 - **Standard Payment** — most payments. Your selected plan's percentage fee,
   settled on-chain immediately after each payment confirms.
 - **Micro Payment** — small payments, applied automatically by amount. A flat
-  per-transaction protocol fee, **settled weekly**.
+  per-SDRP-Tx protocol fee, settled weekly or earlier when the buyer/payee
+  batch reaches JPY 10,000 / USD 100.00.
 - **Nano Payment** — very small payments, applied automatically by amount. A
-  flat per-usage protocol fee, **settled monthly**.
+  flat per-SDRP-Tx protocol fee, settled monthly or earlier when the buyer/payee
+  batch reaches JPY 10,000 / USD 100.00.
+
+Here, `Tx` means one accepted SDRP payment, not the later on-chain settlement
+transaction. Micro / Nano settlement batches are aggregated on-chain after the
+weekly or monthly close, or earlier when the fixed amount threshold is reached.
 
 Micro Payment and Nano Payment are not separate products you opt into; they are
 amount bands Siglume applies on your behalf. Your integration code is the same
 regardless of which band a payment falls into. The full fee table and the exact
-weekly / monthly settlement schedule are in [docs/pricing.md](./docs/pricing.md).
+weekly / monthly settlement schedule plus early threshold settlement rule are in
+[docs/pricing.md](./docs/pricing.md).
 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
+aggregated 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. Merchant setup and the
 billing mandate terms assume the merchant accepts this Micro / Nano delayed
@@ -211,10 +229,11 @@ 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.
+rounded debit per SDRP Tx higher than the decimal provider usage amount; the
+difference is reported as batch `rounding_delta_minor`. Micro / Nano protocol
+fees are provider-borne and are not added to the buyer debit. 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).
@@ -264,8 +283,11 @@ amounts differ.
 | Public one-time payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
 | JPY 501+ / USD 3.01+ | 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 / USD 0.31-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) |
-| JPY 1-49 / USD 0.01-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) |
+| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | USD 0.01 / SDRP Tx, about JPY 2 | Weekly settlement, or earlier at JPY 10,000 / USD 100.00 - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
+| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / SDRP Tx, about JPY 0.2 | Monthly settlement, or earlier at JPY 10,000 / USD 100.00 - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
+
+In this table, `Tx` means one accepted SDRP payment, not an on-chain settlement
+transaction.
 
 A merchant billing mandate is required before accepting payments, even on the
 Launch plan. The current public API chooses the payment band from
@@ -281,9 +303,12 @@ 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`.
-Standard Payment fees are deducted from the merchant settlement amount. Micro /
-Nano protocol fees are added to the buyer debit and are not provider revenue.
-The full fee table and the weekly / monthly settlement schedule live in
+All SDRP payment fees are seller-borne. Standard Payment fees are deducted from
+the merchant settlement amount. Micro / Nano protocol fees are deducted from
+provider receivable at aggregated settlement and are not added to the buyer
+debit.
+The full fee table, the weekly / monthly settlement schedule, and the JPY
+10,000 / USD 100.00 early settlement threshold 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).
@@ -630,11 +655,12 @@ Read [docs/security.md](./docs/security.md) before going live.
 
 - The Direct Request Payment HTTP endpoints live under
   `/v1/sdrp/direct-payments/...`; the SDK targets them for you.
-- For wire compatibility the platform still tags these payments with the legacy
-  mode value `external_402`, and the merchant registry may still expose the
-  legacy billing-plan key `free` for the Launch tier. The SDK sets and reads
-  these values for you — treat them as compatibility identifiers, not public
-  product names.
+- The platform tags these payments with the internal mode value `external_402`,
+  which reflects SDRP's HTTP 402 Payment Required lineage (it is **not**
+  x402-wire-compatible — see "Relationship to HTTP 402"). The merchant registry
+  may also still expose the legacy billing-plan key `free` for the Launch tier.
+  The SDK sets and reads these values for you; `external_402` is an internal
+  mode identifier, not a public product name.
 
 ## Documentation
 

package/dist/index.cjs

@@ -83,7 +83,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.10";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.13";
 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";