@siglume/direct-request-payment 0.4.2 → 0.4.4

package/docs/api-reference.md

@@ -267,7 +267,15 @@ Returns the `sha256:`-prefixed hash for an existing challenge string.
 ## `directRequestPaymentRequestHash(input)` / `direct_request_payment_request_hash(...)`
 
 Returns the SDK-side request hash material for merchant, amount, currency, and
-challenge. This is mostly useful for tests and internal assertions.
+challenge. This is the legacy v1 hash retained for wire compatibility and
+existing idempotency assertions.
+
+## `directRequestPaymentRequestHashV2(input)` / `direct_request_payment_request_hash_v2(...)`
+
+Returns the v2 request hash for the same fields using canonical JSON before
+hashing. New tests and server-side assertions should prefer this value when the
+API response includes `request_hash_v2`; keep accepting `request_hash` for older
+requirements and historical webhook payloads.
 
 ## `DirectRequestPaymentMerchantClient`
 
@@ -308,8 +316,10 @@ Input:
   Hosted Checkout (open-redirect defense). A Hosted Checkout `success_url` /
   `cancel_url` must be on a registered origin; the origin of
   `webhook_callback_url` is auto-allowed in addition. Each entry must be an
-  absolute origin such as `https://shop.example.com`; entries are normalized to
-  bare, lowercased origins and deduped.
+  absolute origin such as `https://shop.example.com`; production origins must
+  use `https`. Development `http` origins are accepted only for `localhost`,
+  `127.0.0.1`, or `[::1]`. Userinfo is rejected. Entries are normalized to bare,
+  lowercased origins and deduped.
 
 In addition to the `setupMerchant` inputs above, `setupCheckout` accepts these
 orchestration toggles:
@@ -371,7 +381,7 @@ POST /v1/sdrp/direct-payments/checkout-sessions
 ```ts
 const session = await merchant.createCheckoutSession({
   merchant: "example_merchant",
-  amount_minor: 500,
+  amount_minor: 1200,
   currency: "JPY",
   nonce: order.id,
   success_url: "https://www.your-shop.com/thanks",
@@ -383,7 +393,7 @@ const session = await merchant.createCheckoutSession({
 ```py
 session = merchant.create_checkout_session(
     merchant="example_merchant",
-    amount_minor=500,
+    amount_minor=1200,
     currency="JPY",
     nonce=order["id"],
     success_url="https://www.your-shop.com/thanks",
@@ -500,11 +510,15 @@ Use it with the authenticated buyer's Siglume bearer token. Developer Portal
 
 This client creates SDRP Standard Payment requirements for external merchant
 checkout flows. Micro Payment and Nano Payment are applied automatically by
-amount and settled on a weekly / monthly cadence; they are not created explicitly
-through this client.
+amount and settled on account-assigned weekly / monthly slots; they are not
+created explicitly through this client. Use the statement APIs below to see
+open-period usage, the close time, the final-notice schedule, and settled /
+unsettled / past-due revenue.
 
-Payment requirements include `fee_bps` from the Siglume platform. The SDK does
-not calculate merchant plan fees locally; see [Pricing](./pricing.md).
+Standard Payment requirements include `fee_bps` from the Siglume platform. The
+SDK does not calculate merchant plan fees locally. For Micro / Nano, use the
+statement API amount fields (`protocol_fee_minor`, `gross_buyer_debit_minor`,
+`buyer_debit_minor`, and `rounding_delta_minor`); see [Pricing](./pricing.md).
 
 ```ts
 const siglume = new DirectRequestPaymentClient({
@@ -542,6 +556,22 @@ Input:
 - `allowance_amount_minor`: optional positive integer
 - `metadata`: optional JSON object
 
+The returned requirement includes both compatibility and machine-readable
+settlement fields:
+
+- `request_hash`: legacy v1 request hash, retained for existing requirements
+  and integrations.
+- `request_hash_v2`: canonical-JSON v2 request hash when the server can compute
+  one for the challenge-backed request.
+- `pricing_band`: `standard`, `micro`, or `nano`.
+- `settlement_cadence`: `per_payment`, `weekly`, or `monthly`.
+- `finality`: machine-readable finality class such as
+  `per_payment_onchain` or `aggregated_onchain_settlement`.
+- `protocol_fee_minor`: Micro / Nano protocol fee when applicable; `null` for
+  Standard Payment.
+- `settlement_status`: `pending_payment`, `provisional`, `settled`,
+  `pending_settlement`, or another explicit operational state.
+
 ### `getPaymentRequirement(requirement_id)` / `get_payment_requirement(requirement_id)`
 
 Calls:
@@ -629,6 +659,191 @@ Input may include:
 - `await_timeout_seconds`
 - `await_poll_seconds`
 
+### `request<T>(method, path, json_body?)` (TypeScript only)
+
+Calls an authenticated Siglume JSON endpoint using the same bearer token and
+base URL configured on `DirectRequestPaymentClient`.
+
+`path` is the API path after `/v1`, for example
+`/sdrp/metered/my-summary`. The helper expects a JSON response. Use raw
+`fetch`, `curl`, or your HTTP client for CSV exports.
+
+Python does not expose a public generic request helper. Use the named Python
+methods documented below for Micro / Nano statements, and ordinary HTTPS
+requests for endpoints that do not yet have a named Python SDK method.
+
+## Metered Statement APIs
+
+Micro Payment and Nano Payment require operational reconciliation after usage is
+accepted. The immediate requirement response does not tell a merchant how much
+is settled, when the batch can first debit, or why a buyer is past due.
+
+See the full operating guide:
+[Micro / Nano Statements and Notices](./metered-statements.md).
+
+### Buyer summary
+
+```text
+GET /v1/sdrp/metered/my-summary
+```
+
+Common query parameters:
+
+- `plan_type`: `micro` or `nano`
+- `token_symbol`: `JPYC` or `USDC`
+
+TypeScript:
+
+```ts
+const summary = await siglume.getBuyerMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+summary = siglume.get_buyer_metered_summary(plan_type="micro", token_symbol="JPYC")
+```
+
+Use `open_periods` for current-period estimated debit,
+`settlement_batches` for closed / scheduled / settled periods, and
+`past_due_blocks` to explain `METERED_SETTLEMENT_PAST_DUE`.
+
+### Buyer usage and settlement lists
+
+```text
+GET /v1/sdrp/metered/my-usage-events
+GET /v1/sdrp/metered/my-settlement-batches
+```
+
+SDK methods:
+
+- TypeScript: `listBuyerUsageEvents(...)`, `listBuyerSettlementBatches(...)`
+- Python: `list_buyer_usage_events(...)`, `list_buyer_settlement_batches(...)`
+
+Each accepts `plan_type`, `token_symbol`, `status`, and `limit`, and returns
+`{items, next_cursor}`.
+
+Buyer-facing amount names are centered on the debit:
+
+- `estimated_buyer_debit_minor`
+- `provider_usage_amount_minor`
+- `gross_buyer_debit_minor`
+- `buyer_debit_minor`
+- `protocol_fee_minor`
+
+### Provider summary
+
+```text
+GET /v1/sdrp/metered/provider/summary
+```
+
+Common query parameters:
+
+- `plan_type`: `micro` or `nano`
+- `token_symbol`: `JPYC` or `USDC`
+- `listing_id`
+- `capability_key`
+
+TypeScript:
+
+```ts
+const providerSummary = await siglume.getProviderMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+```
+
+Python:
+
+```py
+provider_summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
+```
+
+Use `open_periods` for current-period expected revenue, `periods` for closed
+and historical batches, and `totals` to separate settled, unsettled, and
+past-due provider amounts. Do not recognize Micro / Nano revenue until the batch
+is `settled` and has an on-chain receipt.
+
+### Provider usage and settlement detail
+
+```text
+GET /v1/sdrp/metered/provider/usage-events
+GET /v1/sdrp/metered/provider/settlement-batches
+GET /v1/sdrp/metered/provider/settlement-batches/{settlement_batch_id}
+```
+
+SDK methods:
+
+- TypeScript: `listProviderUsageEvents(...)`,
+  `listProviderSettlementBatches(...)`, `getProviderSettlementBatch(...)`
+- Python: `list_provider_usage_events(...)`,
+  `list_provider_settlement_batches(...)`, `get_provider_settlement_batch(...)`
+
+Provider list methods accept `plan_type`, `token_symbol`, `status`,
+`listing_id`, `capability_key`, and `limit`. Detail accepts
+`settlement_batch_id`, plus optional `listing_id` and `capability_key`. List
+methods return `{items, next_cursor}`.
+
+Provider-facing amount names:
+
+- `provider_receivable_minor`
+- `gross_buyer_debit_minor`
+- `buyer_debit_minor`
+- `protocol_fee_minor`
+- `settled_provider_receivable_minor`
+- `unsettled_provider_receivable_minor`
+- `past_due_provider_receivable_minor`
+
+Schedule and execution fields:
+
+- `period_start`, `period_end`, `close_at`
+- `expected_scheduled_debit_at`
+- `scheduled_debit_at`
+- `not_before_attempt_at`
+- `execution_status`
+- `latest_execution_attempt_status`
+- `chain_receipt_id`
+- `usage_event_digest`
+- `attempt_count`
+- `next_attempt_at`
+
+Failure fields are sanitized for public display:
+
+- `failure_reason_code`
+- `failure_reason_label`
+- `failure_reason_help`
+- `support_reference`
+
+Provider APIs do not expose raw `buyer_user_id`, buyer email, buyer wallet
+address, relayer id, nonce, gas data, raw RPC errors, or raw
+`failure_message`. Use `buyer_period_ref` for provider-side reconciliation
+within a period.
+
+### Provider CSV export
+
+```text
+GET /v1/sdrp/metered/provider/settlement-batches/{settlement_batch_id}/usage-events.csv
+```
+
+The CSV is not JSON. Fetch it with raw `fetch`, `curl`, or your HTTP client:
+
+```bash
+curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/usage-events.csv \
+  -H "Authorization: Bearer <provider-siglume-bearer-token>" \
+  -o sdrp-metered.csv
+```
+
+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
+```
+
+The CSV uses `buyer_period_ref`, not raw buyer account identifiers.
+
 ## Payload Builders
 
 These pure functions build the `execute-prepared` payload from a payment
@@ -698,8 +913,17 @@ Returns `{ timestamp, signature }`.
 Validates and normalizes a parsed webhook event object (requires `id`, `type`,
 `api_version`, `occurred_at`, and an object `data`). Throws
 `SiglumeWebhookPayloadError` on a malformed event, or when a
-`direct_payment.confirmed` event does not carry `data.mode = "external_402"`. The
-`payload` argument is positional in both languages.
+`direct_payment.confirmed` event does not carry a supported Direct Request
+Payment mode (`external_402` or `metered_settlement_batch`). The `payload`
+argument is positional in both languages.
+
+For `direct_payment.confirmed`, inspect `event.data.pricing_band`,
+`event.data.settlement_cadence`, `event.data.finality`,
+`event.data.protocol_fee_minor`, and `event.data.settlement_status` instead of
+inferring whether the event means per-payment on-chain confirmation or an
+aggregated Micro / Nano settlement confirmation. `event.data.request_hash_v2`
+is present on new challenge-backed requirements; keep accepting
+`event.data.request_hash` for historical payloads.
 
 ### `verifyDirectRequestPaymentWebhook(secret, body, signature_header, options)` / `verify_direct_request_payment_webhook(secret, body, signature_header, *, tolerance_seconds=300, now=None)`
 
@@ -746,6 +970,7 @@ Both packages export these importable constants:
 | `DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND` | `sdrp_direct_payment_allowance` |
 | `DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE` | `sdrp_direct_payment_requirement` |
 | `DEFAULT_WEBHOOK_TOLERANCE_SECONDS` | `300` |
+| `DIRECT_REQUEST_PAYMENT_SDK_VERSION` | package version string |
 
 The `external_402` / `siglume-external-402-*` values are legacy wire-compat
 identifiers, not public product names (see the README "Compatibility Notes").

package/docs/merchant-quickstart.md

@@ -14,11 +14,13 @@ external merchant.
 The merchant server must not create charges with a customer wallet. It signs the
 order challenge; the buyer-facing Siglume payment flow pays it.
 
-This quickstart is for SDRP Standard Payment in an external merchant product.
-Micro Payment and Nano Payment are applied automatically by amount and settled on
-a weekly / monthly cadence (see [Pricing](./pricing.md#settlement-schedule)); they
-are not browser checkout requirements you create with this SDK. Their provider
-revenue remains unsettled until the later on-chain settlement succeeds.
+This quickstart uses Standard-band example amounts. Micro Payment and Nano
+Payment are applied automatically by amount through the same Hosted Checkout or
+agent/API flow; you do not create a separate Micro/Nano object or pass a
+"force Standard" flag. Micro/Nano are settled on account-assigned weekly /
+monthly slots after the final notice and close-plus-3-day window (see
+[Pricing](./pricing.md#settlement-schedule)), and provider revenue remains
+unsettled until the later on-chain settlement succeeds.
 
 ## Two Buyer Systems
 
@@ -73,7 +75,7 @@ await merchant.setupCheckout({
 // Per order: create a session and redirect the shopper to checkout_url.
 const session = await merchant.createCheckoutSession({
   merchant: "example_merchant",
-  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.example.com/thanks",
@@ -113,7 +115,7 @@ merchant.setup_checkout(
 # Per order: create a session and redirect the shopper to checkout_url.
 session = merchant.create_checkout_session(
     merchant="example_merchant",
-    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.example.com/thanks",
@@ -430,6 +432,59 @@ if verified["event"]["type"] == "direct_payment.confirmed":
     )
 ```
 
+## Reconcile Micro / Nano Statements
+
+Standard Payment can be fulfilled from the verified
+`direct_payment.confirmed` webhook. Micro Payment and Nano Payment are different:
+they are automatic amount bands and are settled later in aggregated on-chain
+batches. Use the statement APIs to answer:
+
+- how much Micro / Nano usage is open this week or month,
+- when the buyer's assigned period closes,
+- when Siglume may first attempt the debit (`not_before_attempt_at`),
+- how much provider revenue is settled, unsettled, retrying, or past due.
+
+Provider summary:
+
+```ts
+import { DirectRequestPaymentClient } from "@siglume/direct-request-payment";
+
+const siglume = new DirectRequestPaymentClient({
+  auth_token: providerSiglumeBearerToken,
+});
+
+const summary = await siglume.getProviderMeteredSummary({
+  plan_type: "micro",
+  token_symbol: "JPYC",
+});
+
+console.log(summary.totals.settled_provider_receivable_minor);
+console.log(summary.totals.unsettled_provider_receivable_minor);
+console.log(summary.totals.past_due_provider_receivable_minor);
+```
+
+Line-level CSV export:
+
+```bash
+curl https://siglume.com/v1/sdrp/metered/provider/settlement-batches/<batch-id>/usage-events.csv \
+  -H "Authorization: Bearer <provider-siglume-bearer-token>" \
+  -o sdrp-metered.csv
+```
+
+Python exposes the same named helper:
+
+```py
+from siglume_direct_request_payment import DirectRequestPaymentClient
+
+siglume = DirectRequestPaymentClient(auth_token=provider_siglume_bearer_token)
+summary = siglume.get_provider_metered_summary(plan_type="micro", token_symbol="JPYC")
+```
+
+Do not book Micro / Nano provider revenue as settled revenue until the batch is
+`settled` and `chain_receipt_id` is present. See
+[Micro / Nano Statements and Notices](./metered-statements.md) for the full
+manual, including buyer past-due blocks and public failure fields.
+
 ## Failure Handling
 
 - `EXTERNAL_402_CHALLENGE_REQUIRED`: the merchant server did not provide a
@@ -465,3 +520,6 @@ if verified["event"]["type"] == "direct_payment.confirmed":
 - Nonces cannot be reused for separate order attempts.
 - The order is fulfilled only after a verified webhook maps back to the stored
   `challenge_hash`.
+- Micro / Nano accounting reads statement APIs or CSV and keeps settled,
+  unsettled, and past-due revenue separate.
+- Micro / Nano provider revenue is not recognized before on-chain settlement.