@siglume/direct-request-payment 0.4.15 → 0.4.17

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.4.17 - 2026-06-19
+
+Public-surface cleanup for the v0.4.15 external review.
+
+- Classified signed `direct_payment.confirmed` webhooks with unsupported
+  `data.mode` as `unknown` with `unsupported_confirmation_mode`, instead of
+  failing raw webhook parsing.
+- Added stricter TypeScript settlement/open-period summary types and public
+  webhook amount/threshold fields.
+- Rejected unsafe API base URLs and webhook callback URLs in both TypeScript
+  and Python helpers.
+- Added release workflow checks that tag names match package versions before
+  publishing.
+- Aligned README and docs wording around the buyer / provider / token / pricing
+  band exposure scope and fixed JPY / USD threshold wording.
+
+## 0.4.16 - 2026-06-19
+
+SDRP Micro / Nano terminal-risk and idempotency hardening release.
+
+- Added public settlement batch fields for terminal provider accounting:
+  `terminal_provider_receivable_minor`,
+  `uncollectible_provider_receivable_minor`,
+  `written_off_provider_receivable_minor`, `terminal_status`,
+  `terminal_marked_at`, and `terminal_reason_code`.
+- Documented operator terminal states `uncollectible` and `written_off` after
+  past-due manual review. These amounts are not settled, unsettled, or past-due
+  receivable.
+- Documented merchant setup risk acceptance receipt
+  `merchant_account.metadata_jsonb.metered_risk_acceptance`.
+- Documented fail-closed idempotency behavior:
+  `IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD` for reused keys with a
+  different metered input payload.
+
 ## 0.4.15 - 2026-06-19
 
 Corrective SDRP Micro / Nano public-surface release.

package/README.md

@@ -24,7 +24,7 @@ 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
-payments; it does not hold customer funds or wallets.
+payment authorizations; it does not hold customer funds or wallets.
 
 **Current public beta scope.** SDRP currently settles JPYC / USDC on **Polygon
 PoS only**. The public SDK does not expose chain selection, cross-chain payment,
@@ -199,11 +199,11 @@ 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-SDRP-Tx protocol fee, settled weekly or earlier when the buyer/payee
-  batch reaches JPY 10,000 / USD 100.00.
+  per-SDRP-Tx protocol fee, settled weekly or earlier when the same buyer /
+  provider / token / pricing band reaches JPY 10,000 / USD 100.00.
 - **Nano Payment** — very small payments, applied automatically by amount. A
-  flat per-SDRP-Tx protocol fee, settled monthly or earlier when the buyer/payee
-  batch reaches JPY 10,000 / USD 100.00.
+  flat per-SDRP-Tx protocol fee, settled monthly or earlier when the same buyer
+  / provider / token / pricing band 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
@@ -223,6 +223,10 @@ aggregated settlement model whenever they offer amounts in these bands. If a
 product cannot fulfill before provider revenue is settled, keep the price in the
 Standard band; in practice, do not offer JPY 500-and-under or USD 3-and-under
 items for that product.
+Self-service setup records this acceptance in
+`merchant_account.metadata_jsonb.metered_risk_acceptance`, including
+`terms_version`, `accepted_at`, `principal_user_id`, `receipt_id`, and fixed
+market thresholds `JPY: 10000` / `USD: 10000`.
 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, but they are
@@ -273,10 +277,11 @@ Pricing has one structure: choose a Standard Payment plan, then Siglume applies
 the fee for each payment by amount. Micro / Nano are automatic amount bands, not
 extra setup choices.
 
-Both launch settlement currencies are first-class: JPY settled in JPYC, and USD
-settled in USDC. A merchant settles in one currency, chosen at onboarding. The
-settlement fee percentage is identical in both currencies; only the flat
-amounts differ.
+Both launch settlement currencies are first-class where enabled: JPY settled in
+JPYC, and USD settled in USDC. Some accounts may require agreed USD/USDC terms
+before USD is enabled. A merchant settles in one currency, chosen at
+onboarding. The settlement fee percentage is identical in both currencies; only
+the flat amounts differ.
 
 | Public one-time payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |

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.15";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.17";
 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";
@@ -126,7 +126,7 @@ var SiglumeWebhookPayloadError = class extends SiglumeDirectRequestPaymentError
   }
 };
 var DirectRequestPaymentClient = class {
-  auth_token;
+  #authToken;
   base_url;
   timeout_ms;
   user_agent;
@@ -142,8 +142,8 @@ var DirectRequestPaymentClient = class {
     if (!fetchImpl) {
       throw new SiglumeDirectRequestPaymentError("A fetch implementation is required in this runtime.");
     }
-    this.auth_token = authToken;
-    this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
+    this.#authToken = authToken;
+    this.base_url = normalizeApiBaseUrl(options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE);
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
     this.user_agent = options.user_agent ?? `@siglume/direct-request-payment/${DIRECT_REQUEST_PAYMENT_SDK_VERSION}`;
     this.fetch_impl = fetchImpl;
@@ -246,7 +246,7 @@ var DirectRequestPaymentClient = class {
     try {
       const headers = {
         "Accept": "application/json",
-        "Authorization": `Bearer ${this.auth_token}`,
+        "Authorization": `Bearer ${this.#authToken}`,
         "User-Agent": this.user_agent
       };
       let body;
@@ -278,7 +278,7 @@ var DirectRequestPaymentClient = class {
   }
 };
 var DirectRequestPaymentMerchantClient = class {
-  auth_token;
+  #authToken;
   base_url;
   timeout_ms;
   user_agent;
@@ -294,8 +294,8 @@ var DirectRequestPaymentMerchantClient = class {
     if (!fetchImpl) {
       throw new SiglumeDirectRequestPaymentError("A fetch implementation is required in this runtime.");
     }
-    this.auth_token = authToken;
-    this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
+    this.#authToken = authToken;
+    this.base_url = normalizeApiBaseUrl(options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE);
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
     this.user_agent = options.user_agent ?? `@siglume/direct-request-payment/${DIRECT_REQUEST_PAYMENT_SDK_VERSION}`;
     this.fetch_impl = fetchImpl;
@@ -313,7 +313,7 @@ var DirectRequestPaymentMerchantClient = class {
       payload.allowed_currencies = normalizeAllowedCurrencies(input.allowed_currencies);
     }
     if (input.webhook_callback_url !== void 0) {
-      payload.webhook_callback_url = requireNonEmpty(input.webhook_callback_url, "webhook_callback_url");
+      payload.webhook_callback_url = normalizeHttpsUrl(input.webhook_callback_url, "webhook_callback_url");
     }
     if (input.billing_mandate_cap_minor !== void 0) {
       payload.billing_mandate_cap_minor = positiveInteger(input.billing_mandate_cap_minor, "billing_mandate_cap_minor");
@@ -393,7 +393,7 @@ var DirectRequestPaymentMerchantClient = class {
   }
   async createWebhookSubscription(input) {
     const payload = {
-      callback_url: requireNonEmpty(input.callback_url, "callback_url"),
+      callback_url: normalizeHttpsUrl(input.callback_url, "callback_url"),
       event_types: input.event_types?.length ? input.event_types.map((eventType) => requireNonEmpty(eventType, "event_type")) : ["direct_payment.confirmed", "direct_payment.spent"]
     };
     if (input.description !== void 0) {
@@ -436,7 +436,7 @@ var DirectRequestPaymentMerchantClient = class {
     try {
       const headers = {
         "Accept": "application/json",
-        "Authorization": `Bearer ${this.auth_token}`,
+        "Authorization": `Bearer ${this.#authToken}`,
         "User-Agent": this.user_agent
       };
       let body;
@@ -674,11 +674,6 @@ function parseDirectRequestPaymentWebhookEvent(payload) {
     occurred_at: requireNonEmpty(stringOrNull(event.occurred_at) ?? "", "webhook occurred_at"),
     data: { ...data }
   };
-  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;
 }
 function classifyDirectPaymentConfirmation(event) {
@@ -689,6 +684,7 @@ function classifyDirectPaymentConfirmation(event) {
   const settlementCadence = stringOrNull(data.settlement_cadence);
   const finality = stringOrNull(data.finality);
   const settlementStatus = stringOrNull(data.settlement_status);
+  const mode = stringOrNull(data.mode);
   if (event.type !== "direct_payment.confirmed") {
     return {
       kind: "unknown",
@@ -703,7 +699,21 @@ function classifyDirectPaymentConfirmation(event) {
       finality
     };
   }
-  if (data.mode === "metered_settlement_batch") {
+  if (!DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES.has(mode ?? "")) {
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "unsupported_confirmation_mode",
+      requirement_id: requirementId,
+      settlement_batch_id: stringOrNull(data.settlement_batch_id),
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (mode === "metered_settlement_batch") {
     const settlementBatchId = stringOrNull(data.settlement_batch_id);
     const chainReceiptId = stringOrNull(data.chain_receipt_id);
     const usageEventDigest = stringOrNull(data.usage_event_digest);
@@ -875,6 +885,38 @@ function normalizeAllowedCurrencies(value) {
 function defaultTokenForCurrency(currency) {
   return currency === "JPY" ? "JPYC" : "USDC";
 }
+function normalizeApiBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(requireNonEmpty(value, "base_url"));
+  } catch {
+    throw new SiglumeDirectRequestPaymentError("base_url must be an absolute URL such as https://siglume.com/v1.");
+  }
+  if (url.username || url.password) {
+    throw new SiglumeDirectRequestPaymentError("base_url must not include userinfo.");
+  }
+  if (!isAllowedCheckoutOriginScheme(url)) {
+    throw new SiglumeDirectRequestPaymentError(
+      "base_url must use https, except http is allowed for localhost, 127.0.0.1, or [::1]."
+    );
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+function normalizeHttpsUrl(value, name) {
+  let url;
+  try {
+    url = new URL(requireNonEmpty(value, name));
+  } catch {
+    throw new SiglumeDirectRequestPaymentError(`${name} must be an absolute https URL.`);
+  }
+  if (url.username || url.password) {
+    throw new SiglumeDirectRequestPaymentError(`${name} must not include userinfo.`);
+  }
+  if (url.protocol !== "https:" || !url.hostname) {
+    throw new SiglumeDirectRequestPaymentError(`${name} must use https.`);
+  }
+  return url.toString();
+}
 function normalizeOriginList(value) {
   if (!Array.isArray(value)) {
     throw new SiglumeDirectRequestPaymentError("checkout_allowed_origins must be an array of origin URLs.");