@siglume/direct-request-payment 0.4.16 → 0.4.18

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.4.18 - 2026-06-19
+
+Developer-onboarding cleanup for the v0.4.17 public review.
+
+- Added a scoped 10-minute first-test guide for one Standard Payment Hosted
+  Checkout flow, with explicit prerequisites and non-goals.
+- Added payment lifecycle and troubleshooting docs covering Hosted Checkout
+  readiness, webhook failure handling, retries, support references, and refund
+  escalation boundaries.
+- Added README glossary and use-case fit tables so merchant / provider /
+  publisher / payee wording and 10-minute claims are less ambiguous.
+- Added minimal Hosted Checkout TypeScript and Python starter directories with
+  `.env.example`, seeded test order, checkout start route, and webhook handler.
+- Replaced "Stripe Checkout equivalent" wording with Siglume wallet hosted
+  checkout wording in public docs and SDK comments.
+- Exported Python `TypedDict` response names for Hosted Checkout, Micro / Nano
+  summaries, settlement batches, webhook verification, and confirmation
+  classification.
+- Marked the existing Express checkout example as demo-only and not
+  production-safe.
+
+## 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.

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,
@@ -56,7 +56,7 @@ buyer**.
    redirect them to the returned `checkout_url`. They sign into Siglume (passkey
    or email code — the login *is* the wallet), review the amount, approve once,
    and pay from their own wallet, then return to your `success_url`. This is the
-   Stripe-Checkout-equivalent path.
+   Siglume wallet hosted checkout path.
 
 2. **AI agent / agent-to-agent (AtoA) → direct API / tools.** An autonomous
    buyer agent pays through `DirectRequestPaymentClient` (your app holds the
@@ -78,6 +78,39 @@ Honest framing: the part that integrates quickly is the **merchant plumbing**
 shopper to have — or create — a Siglume wallet and pay from it; it is not a
 card-style "instant" checkout for first-time buyers.
 
+## Fast Path
+
+If your merchant account, Hosted Checkout enablement, billing mandate, HTTPS
+webhook URL, and buyer test wallet are already ready, use
+[10-Minute First Test Payment](./docs/quickstart-10-minutes.md) to connect one
+Standard Payment test. That page is intentionally scoped to a first test
+payment, not a production launch.
+
+Before implementation, confirm Hosted Checkout readiness in
+[Troubleshooting](./docs/troubleshooting.md#hosted-checkout-readiness). For
+state handling, read [Payment lifecycle](./docs/payment-lifecycle.md) before
+fulfilling orders.
+
+## Who Is Who
+
+| Term | Meaning for public integrations |
+| --- | --- |
+| Buyer | The Siglume wallet user who pays. The merchant SDK does not log this user in. |
+| Merchant | The external product or store that starts checkout, owns the order, and verifies webhooks. |
+| Provider | The revenue recipient in Micro / Nano statements. In a simple EC integration this is usually the same business as the merchant. |
+| Publisher / listing owner | Marketplace-facing owner of a listing or capability. Most Hosted Checkout merchants do not need to handle this term directly. |
+| Payee | Internal settlement-grouping language. Public integration guides avoid this term unless a statement API field includes it. |
+
+## Use-Case Fit
+
+| Use case | Recommended path | 10-minute demo? | Production work still required |
+| --- | --- | --- | --- |
+| EC one-time Standard payment | Hosted Checkout | Yes, if prerequisites are ready | Durable order DB, webhook dedupe, refund/support process, monitoring |
+| Game consumables | Hosted Checkout or agent/API | Conditional | Idempotent entitlement grants, disconnect recovery, Micro / Nano unsettled-risk handling |
+| Paid API / AtoA | Direct API or Siglume marketplace tool | Conditional | Request idempotency, buyer auth context, reconciliation |
+| SaaS subscription | Recurring challenge plus raw API | No | Renewal, cancellation, failed renewal, plan-change lifecycle |
+| Scheduled autopay | Recurring challenge plus schedule token | No | Scheduler, token custody, budget failure handling |
+
 ## Hosted Checkout (Human Web Shoppers)
 
 **Beta / server rollout:** Hosted Checkout is rolling out account by account.
@@ -86,6 +119,8 @@ case `createCheckoutSession(...)` / `getCheckoutSession(...)` raises
 `HostedCheckoutNotAvailableError` instead of exposing the raw rollout 404/409.
 Keep the signed `direct_payment.confirmed` webhook as the durable signal, and
 inspect its settlement machine fields before marking any order paid.
+Check readiness before you build the flow; see
+[Hosted Checkout readiness](./docs/troubleshooting.md#hosted-checkout-readiness).
 
 Hosted Checkout is a Siglume-hosted page that turns a "Pay with Siglume" button
 into a completed wallet payment, then returns the shopper to your store. It
@@ -199,11 +234,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
@@ -277,16 +312,17 @@ 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 |
 | --- | --- | --- | --- | --- |
 | 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 | JPY 2 / USD 0.01 per SDRP Tx | 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 | JPY 0.2 / USD 0.001 per SDRP Tx | Monthly settlement, or earlier at JPY 10,000 / USD 100.00 - see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
+| JPY 50-500 / USD 0.31-3.00 | Micro Payment | Applied automatically by amount | JPY 2 / USD 0.01 per SDRP Tx | Closes weekly, or earlier when provider gross reaches 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 | JPY 0.2 / USD 0.001 per SDRP Tx | Closes monthly, or earlier when provider gross reaches 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.
@@ -640,7 +676,9 @@ an order paid from the event type alone.
 - Do not treat Direct Request Payment as stored value, prepaid points, escrow, or
   a platform balance.
 
-Read [docs/security.md](./docs/security.md) before going live.
+Read [docs/security.md](./docs/security.md) before going live. Use
+[docs/troubleshooting.md](./docs/troubleshooting.md) for operational error
+handling and support escalation.
 
 ## Go-Live Checklist
 
@@ -669,12 +707,17 @@ Read [docs/security.md](./docs/security.md) before going live.
 ## Documentation
 
 - [Merchant quickstart](./docs/merchant-quickstart.md)
+- [10-minute first test payment](./docs/quickstart-10-minutes.md)
+- [Payment lifecycle](./docs/payment-lifecycle.md)
+- [Troubleshooting](./docs/troubleshooting.md)
 - [API reference](./docs/api-reference.md)
 - [Pricing](./docs/pricing.md)
 - [Micro / Nano statements and notices](./docs/metered-statements.md)
 - [Security guide](./docs/security.md)
 - [Merchant setup example](./examples/setup-merchant.ts)
 - [Express checkout example](./examples/express-checkout.ts)
+- [Hosted Checkout TypeScript starter](./examples/hosted-checkout-typescript)
+- [Hosted Checkout Python starter](./examples/hosted-checkout-python)
 - [Japanese launch announcement draft](./docs/announcement-ja.md)
 - [Changelog](./CHANGELOG.md)
 

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.16";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.18";
 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");
@@ -327,8 +327,8 @@ var DirectRequestPaymentMerchantClient = class {
     return this.request("POST", "/sdrp/direct-payments/merchants", payload);
   }
   /**
-   * Create a Hosted Checkout session (Stripe-Checkout-equivalent for human web
-   * shoppers). Siglume authors the challenge server-side, persists a single-use
+   * Create a Hosted Checkout session for human web shoppers. Siglume authors
+   * the challenge server-side, persists a single-use
    * expiring session, and returns a `checkout_url`. Redirect the shopper there;
    * they log into Siglume, approve, and pay from their own wallet, then return
    * to your `success_url`. Fulfill on the `direct_payment.confirmed` webhook
@@ -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.");