@siglume/direct-request-payment 0.4.11 → 0.4.13

package/docs/metered-statements.md

@@ -19,12 +19,13 @@ Siglume applies the settlement band from the amount.
 
 | Band | Cadence | Period close | First debit attempt | Revenue recognition |
 | --- | --- | --- | --- | --- |
-| Micro Payment | Weekly | Account-assigned fixed weekly slot in the buyer settlement timezone | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
-| Nano Payment | Monthly | Account-assigned fixed monthly slot in the buyer settlement timezone | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; can close early once the buyer/payee/token batch reaches JPY 10,000 or USD 100.00 | After final debit notice delivery and the fixed close-plus-3-day window | Only after the aggregated settlement confirms on-chain |
 
-The schedule is platform-managed. Buyers and providers can see the assigned
-period and scheduled attempt times through the statement APIs, but cannot choose
-a custom close day.
+The schedule is platform-managed. Buyers and providers can see the resulting
+batch period and scheduled attempt times through the statement APIs, but cannot
+choose a custom close day. Early threshold settlement can create a batch before
+the account-assigned weekly or monthly close.
 
 The important timestamp is `not_before_attempt_at`. Siglume does not execute the
 debit before this timestamp. It is always after the final debit notice is
@@ -93,30 +94,33 @@ guarantee.
 ## Amount Rounding
 
 Micro / Nano usage rows keep provider price and protocol fee values as decimal
-minor-unit amounts. This allows Nano fees such as about JPY 0.2 per usage to be
-accounted without rounding every event.
+minor-unit amounts. This allows Nano fees such as about JPY 0.2 per SDRP Tx to
+be accounted without rounding every accepted payment.
 
 Rounding happens once when a settlement batch is created:
 
 ```text
-provider_usage_amount_minor = sum(provider price minor units for accepted usage)
-protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted usage)
-gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+provider_usage_amount_minor = sum(provider price minor units for accepted metered rows)
+protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
+provider_receivable_minor = max(provider_usage_amount_minor - protocol_fee_minor, 0)
+gross_buyer_debit_minor = provider_usage_amount_minor
 buyer_debit_minor = ceil(gross_buyer_debit_minor)
 rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
 ```
 
-For low-count Nano batches, the ceiling can make the effective buyer burden per
-usage higher than the headline "USD 0.001 / usage" protocol fee. The protocol
-fee remains the decimal statement amount; the extra integer-minor-unit
-adjustment is recorded as `rounding_delta_minor` on the settlement batch. Each
-settlement batch can add a positive rounding adjustment of less than 1 token
-minor unit; if a buyer uses many providers / payees in one period, that
-adjustment can occur once per settlement batch.
+For low-count Nano batches, the ceiling can make the effective rounded debit per
+SDRP Tx higher than the decimal provider usage amount. Here, `Tx` means one
+accepted SDRP payment, not an on-chain settlement transaction. The protocol fee
+remains the decimal statement amount and is deducted from provider receivable;
+the extra integer-minor-unit adjustment is recorded as `rounding_delta_minor` on
+the settlement batch. Each settlement batch can add a positive rounding
+adjustment of less than 1 token minor unit; if a buyer uses many providers /
+payees in one period, that adjustment can occur once per settlement batch.
 
 `rounding_delta_minor` belongs to the buyer debit and Siglume's rounding
-adjustment accounting for that batch. It is not provider revenue. Provider
-reports should use `provider_receivable_minor`,
+adjustment accounting for that batch. It is not provider revenue.
+`protocol_fee_minor` is provider-borne and is not added to the buyer debit.
+Provider reports should use `provider_receivable_minor`,
 `settled_provider_receivable_minor`, `unsettled_provider_receivable_minor`, and
 `past_due_provider_receivable_minor`.
 
@@ -144,8 +148,8 @@ They return `{items, next_cursor}`.
 Buyer usage event amount fields:
 
 - `provider_usage_amount_minor`: provider price for the usage event
-- `protocol_fee_minor`: metered protocol fee
-- `gross_buyer_debit_minor`: expected buyer debit for the event
+- `protocol_fee_minor`: provider-borne metered protocol fee
+- `gross_buyer_debit_minor`: provider usage amount before integer-token rounding
 - `expected_scheduled_debit_at`: derived schedule for an open period before a
   settlement batch exists
 
@@ -171,7 +175,7 @@ Buyer batch amount fields:
 
 - `estimated_buyer_debit_minor`: total buyer debit for the batch
 - `provider_usage_amount_minor`: provider usage amount before protocol fee
-- `gross_buyer_debit_minor`: provider usage amount plus protocol fee
+- `gross_buyer_debit_minor`: provider usage amount before integer-token rounding
 - `buyer_debit_minor`: amount scheduled for the debit transaction
 
 Past-due batches include:
@@ -304,12 +308,13 @@ Important batch fields:
 | `latest_execution_attempt_status` | Latest non-sensitive execution attempt status |
 | `chain_receipt_id` | On-chain receipt id when available |
 | `usage_event_digest` | Digest of usage rows included in the batch |
-| `provider_receivable_minor` | Provider amount for the batch |
-| `settled_provider_receivable_minor` | Provider amount that is settled on-chain |
-| `unsettled_provider_receivable_minor` | Provider amount not yet settled |
-| `past_due_provider_receivable_minor` | Provider amount blocked on past-due settlement |
-| `gross_buyer_debit_minor` | Provider amount plus protocol fee |
-| `protocol_fee_minor` | Micro / Nano protocol fee |
+| `provider_usage_amount_minor` | Provider usage amount before protocol fee |
+| `provider_receivable_minor` | Provider amount for the batch after provider-borne protocol fee |
+| `settled_provider_receivable_minor` | Provider receivable that is settled on-chain |
+| `unsettled_provider_receivable_minor` | Provider receivable not yet settled |
+| `past_due_provider_receivable_minor` | Provider receivable blocked on past-due settlement |
+| `gross_buyer_debit_minor` | Provider usage amount before integer-token rounding |
+| `protocol_fee_minor` | Micro / Nano protocol fee deducted from provider receivable |
 | `buyer_debit_minor` | Amount scheduled for the buyer debit |
 | `attempt_count`, `next_attempt_at` | Retry state |
 | `failure_reason_code`, `failure_reason_label`, `failure_reason_help` | Sanitized public failure reason |
@@ -329,7 +334,7 @@ curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/
 The CSV contains exactly these columns:
 
 ```text
-metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
+metered_usage_id,created_at,plan_type,settlement_cadence,period_start,period_end,listing_id,capability_key,operation_key,currency,token_symbol,provider_usage_amount_minor,provider_receivable_minor,protocol_fee_minor,gross_buyer_debit_minor,rounding_delta_minor,buyer_debit_minor,status,settlement_batch_id,buyer_period_ref
 ```
 
 The CSV uses `buyer_period_ref`, not `buyer_user_id`.

package/docs/pricing.md

@@ -34,14 +34,19 @@ charging.
 | 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 | Aggregated and settled **weekly** (see [Settlement schedule](#settlement-schedule)) |
-| JPY 1-49 / USD 0.01-0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / usage, about JPY 0.2 | Aggregated and settled **monthly** (see [Settlement schedule](#settlement-schedule)) |
+| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | USD 0.01 / SDRP Tx, about JPY 2 | Aggregated and settled **weekly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#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 | Aggregated and settled **monthly**, or earlier once the buyer/payee batch reaches JPY 10,000 / USD 100.00 (see [Settlement schedule](#settlement-schedule)) |
+
+In this table, `Tx` means one accepted SDRP payment, not an 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.
 
 Standard Payment settles per payment. Micro Payment and Nano Payment are
-aggregated and settled in account-assigned weekly / monthly slots - see
-[Settlement schedule](#settlement-schedule) for how each band closes, when the
-pre-debit notice window elapses, when revenue becomes settled, and how rejected
-requests behave.
+aggregated and settled in account-assigned weekly / monthly slots, with early
+settlement when the same buyer/payee/token/period batch reaches JPY 10,000 or
+USD 100.00. See [Settlement schedule](#settlement-schedule) for how each band
+closes, when the pre-debit notice window elapses, when revenue becomes settled,
+and how rejected requests behave.
 
 The current public API chooses the band from `amount_minor`; JPY 500-and-under /
 USD 3-and-under payments are routed to Micro / Nano delayed aggregated
@@ -67,11 +72,12 @@ If no paid plan is selected during merchant setup, the merchant account uses the
 Launch plan. A merchant billing mandate is still required before accepting
 payments so Siglume can collect the monthly base fee automatically.
 
-Standard Payment fees are deducted at settlement, so the merchant receives the
-net amount for each Standard payment. Micro / Nano protocol fees are different:
-they are added to the buyer debit, are reported as `protocol_fee_minor`, and are
-not provider revenue. Monthly base fees are collected separately through the
-merchant billing mandate.
+All SDRP payment fees are seller-borne. Standard Payment fees are deducted at
+settlement, so the merchant receives the net amount for each Standard payment.
+Micro / Nano protocol fees are deducted from provider receivable at aggregated
+settlement, are reported as `protocol_fee_minor`, and are not added to the buyer
+debit. Monthly base fees are collected separately through the merchant billing
+mandate.
 
 The same Standard Payment percentage schedule applies in JPY and USD. For
 Standard Payment, the Siglume platform returns `fee_bps` in the merchant's
@@ -89,23 +95,27 @@ confirmed payment turns into money in your settlement wallet.
 | Band | Cadence | Period | You are paid |
 | --- | --- | --- | --- |
 | Standard Payment | Per payment | n/a | On-chain, immediately after each payment confirms |
-| Micro Payment | Weekly | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
-| Nano Payment | Monthly | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs | After the period closes and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Micro Payment | Weekly, with early threshold settlement | Account-assigned fixed weekly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
+| Nano Payment | Monthly, with early threshold settlement | Account-assigned fixed monthly slot in the buyer settlement timezone; the assigned close time is visible through the statement APIs. If a buyer/payee/token/period batch reaches JPY 10,000 or USD 100.00 first, Siglume can close that batch early. | After the period closes or the fixed amount threshold is reached, and the roughly 3-day pre-debit notice window has elapsed, in aggregated on-chain settlement(s) grouped per buyer, payee, token, and period |
 
 ### Micro weekly settlement
 
 - **Closing period.** Micro-band payments accrue across one weekly period. The
   specific closing weekday and time are assigned as a fixed slot per account to
   spread settlement load.
+- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
+  10,000 or USD 100.00 before the weekly close, Siglume can close that batch
+  early and start the same final-notice and settlement flow.
 - **Timezone.** Period boundaries are evaluated in the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
-- **Settlement.** After the week closes, Siglume aggregates that week's Micro
+- **Settlement.** After the week closes or the early threshold is reached,
+  Siglume aggregates the Micro
   payments — grouped per buyer, payee, token, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
-- **Revenue recognition.** A Micro payment is final only once its weekly
+- **Revenue recognition.** A Micro payment is final only once its aggregated
   settlement confirms on-chain. Until then it is accrued, not settled.
 
 ### Nano monthly settlement
@@ -113,15 +123,19 @@ confirmed payment turns into money in your settlement wallet.
 - **Closing period.** Nano-band payments accrue across one monthly period. The
   specific closing day and time are assigned as a fixed slot per account to
   spread settlement load.
+- **Early threshold settlement.** If a buyer/payee/token batch reaches JPY
+  10,000 or USD 100.00 before the monthly close, Siglume can close that batch
+  early and start the same final-notice and settlement flow.
 - **Timezone.** As with Micro, period boundaries use the buyer's configured
   settlement timezone, defaulting to UTC. Assigned slots are persisted and are
   not recalculated on the fly.
-- **Settlement.** After the month closes, Siglume aggregates that month's Nano
+- **Settlement.** After the month closes or the early threshold is reached,
+  Siglume aggregates the Nano
   payments — grouped per buyer, payee, token, and period — into on-chain
   settlement(s). Siglume sends the final debit notice first; the on-chain debit
   is not attempted until the scheduled attempt time after an approximately
   3-day pre-debit notice window (`not_before_attempt_at`).
-- **Revenue recognition.** A Nano payment is final only once its monthly
+- **Revenue recognition.** A Nano payment is final only once its aggregated
   settlement confirms on-chain.
 
 ### Failures, retries, and carry-over
@@ -146,8 +160,9 @@ confirmed payment turns into money in your settlement wallet.
 
 Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 
-- A buyer's wallet budget reservation is consumed at the **gross amount** (your
-  price plus the protocol fee) from acceptance until settlement confirms. This
+- A buyer's wallet budget reservation is consumed at the **gross buyer debit
+  amount** (your usage price, before any provider-borne protocol fee) from
+  acceptance until settlement confirms. This
   is a reservation against Siglume spending limits; it does not lock, escrow,
   preserve, or guarantee the buyer's token balance, allowance, BudgetVault
   authorization, or payment source.
@@ -162,48 +177,54 @@ Micro and Nano run a budget check before the buyer's paid request is fulfilled:
 
 ### What is fixed vs platform-managed
 
-The cadence is fixed: **Micro settles weekly, Nano settles monthly**, and a
-payment is final only after its on-chain settlement confirms. Micro and Nano are
-automatic amount bands, not customer-selected options. The account-assigned
-period boundaries, roughly 3-day pre-debit notice window, and current retry policy
-above are the public behavior as of 2026-06-18. Treat the platform's statement
-status, `not_before_attempt_at`, Standard `fee_bps`, and Micro / Nano statement
-amount fields as authoritative rather than hard-coding local revenue
-recognition.
+The cadence fields are fixed: **Micro is weekly, Nano is monthly**. In both
+bands, Siglume can close a buyer/payee/token batch early once it reaches JPY
+10,000 or USD 100.00. A payment is final only after its on-chain settlement
+confirms. Micro and Nano are automatic amount bands, not customer-selected
+options. The account-assigned period boundaries, roughly 3-day pre-debit notice
+window, early settlement threshold, and current retry policy above are the
+public behavior as of 2026-06-19. Treat the platform's statement status,
+`not_before_attempt_at`, Standard `fee_bps`, and Micro / Nano statement amount
+fields as authoritative rather than hard-coding local revenue recognition.
 
 ## Micro / Nano Amount Rounding
 
 Micro / Nano fees are stored internally as decimal minor-unit values so
-sub-yen and sub-cent Nano fees are not silently rounded per usage event. The
+sub-yen and sub-cent Nano fees are not silently rounded per accepted SDRP Tx. The
 current settlement rule is:
 
 ```text
-provider_usage_amount_minor = sum(provider price minor units for accepted usage)
-protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted usage)
-gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+provider_usage_amount_minor = sum(provider price minor units for accepted metered rows)
+protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
+provider_receivable_minor = max(provider_usage_amount_minor - protocol_fee_minor, 0)
+gross_buyer_debit_minor = provider_usage_amount_minor
 buyer_debit_minor = ceil(gross_buyer_debit_minor)
 rounding_delta_minor = buyer_debit_minor - gross_buyer_debit_minor
 ```
 
-Rounding happens once when the settlement batch is created, not per usage event.
+Rounding happens once when the settlement batch is created, not per accepted
+SDRP Tx.
 The rounding mode is ceiling to the next integer token minor unit because
 on-chain settlement cannot debit fractional JPYC/USDC minor units. The positive
 `rounding_delta_minor` is part of the buyer debit for that batch and is retained
 as a rounding adjustment in Siglume's settlement accounting; it is not provider
-revenue. Providers should reconcile their revenue with
+revenue. `protocol_fee_minor` is provider-borne and is deducted from provider
+receivable, not added to the buyer debit. Providers should reconcile their
+revenue with
 `provider_receivable_minor`, `settled_provider_receivable_minor`,
 `unsettled_provider_receivable_minor`, and
 `past_due_provider_receivable_minor`, not with `buyer_debit_minor`.
 
 For low-count Nano batches, the integer ceiling can make the effective buyer
-burden per usage higher than the headline USD 0.001 / usage protocol fee. The
-decimal protocol fee remains visible as `protocol_fee_minor`; the difference
-created by integer-token settlement is visible as `rounding_delta_minor` on the
-batch. Each settlement batch can add a positive rounding adjustment of less than
-1 token minor unit. If a buyer uses many providers / payees in one period, that
-adjustment can occur once per settlement batch. JavaScript integrations should
-not sum Micro / Nano minor amounts with `number`; use a decimal library. Python
-integrations should use `Decimal`.
+rounded debit per SDRP Tx higher than the decimal provider usage amount. The
+decimal protocol fee remains visible as `protocol_fee_minor` and is deducted
+from provider receivable; the difference created by integer-token settlement is
+visible as `rounding_delta_minor` on the batch. Each settlement batch can add a
+positive rounding adjustment of less than 1 token minor unit. If a buyer uses
+many providers / payees in one period, that adjustment can occur once per
+settlement batch. JavaScript integrations should not sum Micro / Nano minor
+amounts with `number`; use a decimal library. Python integrations should use
+`Decimal`.
 
 ## Statement APIs and Notices
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siglume/direct-request-payment",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",