@siglume/direct-request-payment 0.4.12 → 0.4.14

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,31 +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 SDRP Tx to
-be accounted without rounding every accepted payment.
+minor-unit amounts. This allows Nano fees such as 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 metered rows)
 protocol_fee_minor = sum(Micro/Nano fixed protocol fee minor units for accepted metered rows)
-gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+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
-SDRP Tx higher than the headline "USD 0.001 / SDRP Tx" protocol fee. Here,
-`Tx` means one accepted SDRP payment, not an on-chain settlement transaction.
-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`.
 
@@ -145,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
 
@@ -172,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:
@@ -187,6 +190,18 @@ Buyer-triggered requeue is not part of the MVP. The buyer-facing UI should show
 the block reason, tell the buyer to repair balance / allowance / BudgetVault /
 caps, and point them to support with `support_reference`.
 
+Threshold-control fields:
+
+- `settlement_trigger`: `amount_threshold` or `scheduled_close`
+- `settlement_threshold_minor`: JPY `10000` or USD `10000` minor units
+- `threshold_reached_at`: set when the fixed amount threshold closed the batch
+- `total_unsettled_exposure_minor`: open plus `notice_pending`, `ready`,
+  `submitted`, retrying, and `past_due` provider gross exposure for the same
+  buyer / provider / token
+
+JPY 10,000 and USD 100.00 are market-specific fixed thresholds, not FX
+conversions of one another.
+
 ## Provider Statement APIs
 
 ### Summary
@@ -298,6 +313,10 @@ Important batch fields:
 | `status` | Batch lifecycle state such as `notice_pending`, `ready`, `submitted`, `settled`, `failed`, `past_due`, or `notice_delivery_failed` |
 | `notice_status` | Final debit notice delivery status |
 | `period_start`, `period_end`, `close_at` | Statement period boundaries |
+| `settlement_trigger` | `amount_threshold` for early threshold close, or `scheduled_close` for weekly/monthly close |
+| `settlement_threshold_minor` | Fixed market threshold for early settlement: JPY `10000` or USD `10000` minor units |
+| `threshold_reached_at` | Timestamp when the fixed threshold closed the batch, otherwise null |
+| `total_unsettled_exposure_minor` | Current open plus notice/ready/submitted/retrying/past-due provider gross exposure for the same buyer / provider / token |
 | `expected_scheduled_debit_at` | Expected debit time for an open period before a batch exists |
 | `scheduled_debit_at` | Scheduled debit time after batch creation |
 | `not_before_attempt_at` | Earliest allowed debit attempt; this is the close-plus-3-day gate |
@@ -305,12 +324,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 |
@@ -330,7 +350,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`.
@@ -371,9 +391,10 @@ Siglume retries failed Micro / Nano settlement every 6 hours for up to 28
 automatic attempts. After that the batch remains `past_due` until operator
 requeue.
 
-New Micro / Nano usage for the same buyer, plan type, and token is paused while
-the past-due block remains. The provider API is not called for the rejected
-request, and the request is not charged.
+New Micro / Nano usage for the same buyer / provider / token is paused while
+the total unsettled exposure is at or above the fixed threshold, and while a
+failed or past-due block remains. The provider API is not called for the
+rejected request, and the request is not charged.
 
 Public failure fields are sanitized. Show `failure_reason_code`,
 `failure_reason_label`, `failure_reason_help`, and `support_reference` to users

package/docs/pricing.md

@@ -34,18 +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 / SDRP 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 / SDRP Tx, 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 | JPY 2 / USD 0.01 per SDRP Tx | 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 | JPY 0.2 / USD 0.001 per SDRP Tx | 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.
+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
@@ -71,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
@@ -93,23 +95,29 @@ 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. JPY 10,000 and USD
+  100.00 are market-specific fixed thresholds, not FX conversions of one
+  another.
 - **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
@@ -117,15 +125,21 @@ 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. JPY 10,000 and USD
+  100.00 are market-specific fixed thresholds, not FX conversions of one
+  another.
 - **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
@@ -137,9 +151,12 @@ confirmed payment turns into money in your settlement wallet.
   the affected batch is treated as past due. Siglume currently retries every 6
   hours for up to 28 automatic attempts. After that, the batch remains past due
   and requires manual resolution before another attempt.
-- While a buyer has an unresolved failed Micro/Nano settlement for the same
-  payment band and token, new Micro/Nano usage is paused with the machine-readable
-  error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not called.
+- While the same buyer / provider / token has total unsettled exposure at or
+  above the fixed threshold, new Micro/Nano usage is paused with the
+  machine-readable error `METERED_SETTLEMENT_PAST_DUE`; the provider API is not
+  called. Exposure includes open usage plus `notice_pending`, `ready`,
+  `submitted`, retrying, and `past_due` batches, and remains paused while
+  settlement failure or `past_due` is unresolved.
 - Outstanding amounts remain attached to the failed settlement and are retried
   under this policy. They are not settled revenue, and Siglume does not advance,
   guarantee, or insure provider revenue before on-chain settlement succeeds.
@@ -150,8 +167,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.
@@ -166,14 +184,15 @@ 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
 
@@ -184,7 +203,8 @@ current settlement rule is:
 ```text
 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)
-gross_buyer_debit_minor = provider_usage_amount_minor + protocol_fee_minor
+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
 ```
@@ -195,20 +215,23 @@ 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 SDRP Tx higher than the headline USD 0.001 / SDRP Tx 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.12",
+  "version": "0.4.14",
   "description": "SDK for the Siglume Direct Request Payment SDRP payment protocol",
   "keywords": [
     "siglume",