@siglume/direct-request-payment 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## 0.4.0 - 2026-06-18
+
+Hosted Checkout for human web shoppers ("Pay with Siglume"). The two buyer
+systems are now both first-class: AI agents pay through the API/tools (unchanged)
+and humans pay through a Siglume-hosted checkout page.
+
+- **`DirectRequestPaymentMerchantClient.createCheckoutSession(...)`** (TS + Py):
+  create a single-use, expiring Hosted Checkout session. Siglume authors the
+  challenge server-side and returns a `checkout_url`; redirect the shopper there.
+  The shopper logs into Siglume, approves, and pays from their own Siglume wallet
+  (JPYC / USDC), then returns to your `success_url`. Fulfill on the existing
+  `direct_payment.confirmed` webhook — the source of truth — exactly as with the
+  agent flow. The merchant SDK still does not authenticate the buyer.
+- **`getCheckoutSession(session_id)`** (TS + Py): read a session's status
+  (`open` / `authenticated` / `paid` / `expired` / `cancelled` / `failed`).
+- **`checkout_allowed_origins`** added to `setupMerchant` / `setupCheckout`: a
+  return-URL origin allowlist (open-redirect defense). `success_url` /
+  `cancel_url` must be on a registered origin; the `webhook_callback_url` origin
+  is auto-allowed.
+- Docs: documented the **two buyer systems** (human Web = Hosted Checkout; AI
+  agent / AtoA = direct API / tools), the AtoA **prerequisite** that the buyer
+  agent is pre-connected to Siglume (MCP/OAuth, or a custom app holding the
+  buyer's Siglume JWT), and the merchant / Siglume / buyer **boundaries** —
+  including that the buyer needs a Siglume wallet and this is **not** a card
+  payment.
+
+No wire-format changes to existing challenges, requirements, or webhooks; 0.3.x
+clients interoperate unchanged. Hosted Checkout is gated server-side and is a
+purely additive surface.
+
+## 0.3.6 - 2026-06-18
+
+Documentation and public-surface cleanup release. No wire-format or API changes;
+challenges and clients from 0.3.x interoperate unchanged.
+
+- Documented the Micro / Nano **settlement schedule** in the README and the
+  pricing guide: Micro settles weekly, Nano settles monthly, with the closing
+  period, timezone, revenue-recognition point, retry / carry-over, and
+  rejected / no-charge behavior spelled out. The exact close time, default
+  timezone, and settlement lag are marked platform-managed — the platform
+  response is the source of truth.
+- Clarified that Micro / Nano provider revenue stays unsettled until the weekly /
+  monthly on-chain settlement succeeds, that failed settlements are retried and
+  may go past due, and that Siglume does not advance, guarantee, or insure unpaid
+  amounts.
+- Reframed the docs as a standalone SDRP payment SDK. Internal implementation
+  language was removed from the public surface: the legacy `external_402` mode
+  value and the `free` Launch-tier key are now isolated in a single
+  "Compatibility Notes" section, and internal batch / ledger terms were dropped.
+- Hardened the examples: they no longer print returned secrets (`setup.env`) and
+  no longer return raw `error.message` to the client.
+- Removed `external-402` from the npm / PyPI keywords; added `sdrp`,
+  `direct-request-payment`, `micropayments`, `metered-billing`, `jpyc`, `usdc`.
+- Hardened `.gitignore` (`.env`, `.env.*`, `.npmrc`, `.pypirc`, `.venv/`,
+  `coverage/`) and removed a developer-specific path from `RELEASING.md`.
+
+## 0.3.5 - 2026-06-18
+
+- Docs: protocol-first README framing for the SDRP Direct Request Payment SDK.
+
+## 0.3.4 - 2026-06-18
+
+- Docs: clarified the SDRP pricing structure — a Standard plan is selected, and
+  Micro / Nano are applied automatically by amount — across the README and
+  pricing guide.
+
+## 0.3.3 - 2026-06-18
+
+- Docs: SDRP direct-payment framing across the README, API reference, merchant
+  quickstart, pricing, and security guides.
+
+## 0.3.2 - 2026-06-18
+
+- Docs: documented the SDRP Micro / Nano amount-band boundaries.
+
 ## 0.3.1 - 2026-06-12
 
 - Docs: scheduled autopay (`cadence: "daily"`) is documented as an approval

package/README.md

@@ -5,24 +5,15 @@
 
 ## Protocol Overview
 
-Siglume Direct Request Payment is an SDRP payment protocol for products that
-want to accept Siglume wallet payments. The merchant fixes the order, amount,
-and currency on its server; the buyer pays with a Siglume wallet; Siglume
-applies the correct pricing and settlement path from the payment amount and
-execution conditions.
-
-During merchant setup, only the **Standard Payment plan** is selected. Micro
-Payment and Nano Payment are not separate choices for the merchant or buyer.
-They are applied automatically by amount.
+Siglume Direct Request Payment (SDRP) is a wallet payment protocol for products
+that want to accept Siglume wallet payments. The merchant fixes the order,
+amount, and currency on its server; the buyer pays with a Siglume wallet;
+Siglume applies the correct pricing and settlement path from the payment amount.
 
 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. This SDK is for external merchants integrating Siglume Direct
-Request Payment into their own checkout. It is not the server contract for SDRP
-Micro Payment or Nano Payment.
-
-The current platform payload still uses the internal mode name `external_402`;
-this SDK sets that value for you when creating a payment requirement.
+customer funds. The SDK creates and verifies one-time and recurring wallet
+payments; it does not hold customer funds or wallets.
 
 Payment requirement creation must run in the authenticated buyer's Siglume
 context. Your merchant server must not use a merchant secret or API key to
@@ -34,7 +25,114 @@ token for setup. `DirectRequestPaymentClient` requires the buyer's Siglume
 bearer token for payment requirements. Do not use a Developer Portal `cli_` API
 key with this package.
 
-The canonical HTTP endpoints live under `/v1/sdrp/direct-payments/...`.
+## Two Kinds of Buyer
+
+SDRP serves two kinds of buyer, and you integrate each differently. In both
+cases the buyer pays from a **Siglume wallet** (JPYC for JPY, USDC for USD) — it
+is **not** a card payment — and your **merchant SDK never authenticates the
+buyer**.
+
+1. **Human web shopper → Hosted Checkout.** When a person clicks "Pay with
+   Siglume" on your site, call
+   [`createCheckoutSession(...)`](#hosted-checkout-human-web-shoppers) and
+   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.
+
+2. **AI agent / agent-to-agent (AtoA) → direct API / tools.** An autonomous
+   buyer agent pays through `DirectRequestPaymentClient` (your app holds the
+   buyer's Siglume JWT) or through the Siglume marketplace tool
+   `market_confirm_direct_payment_and_execute` (MCP).
+
+   **Prerequisite (important):** agent payment assumes the buyer agent is
+   **already connected to Siglume before the payment**. An AI client
+   (Claude / ChatGPT / Cursor, …) connects through the **Siglume MCP server
+   (OAuth authorization, with a consent screen)**; a custom app holds the
+   buyer's **Siglume bearer token (JWT)**. Either way a Siglume authentication
+   context must be established before paying — the merchant SDK does not log the
+   buyer in. Unattended runs are bounded by Siglume's **approval gates / spending
+   budgets** (per-run / daily / monthly auto-pay budgets, or Works approval), not
+   by the merchant.
+
+Honest framing: the part that integrates quickly is the **merchant plumbing**
+(challenge or checkout session + webhook). Human web payment still requires the
+shopper to have — or create — a Siglume wallet and pay from it; it is not a
+card-style "instant" checkout for first-time buyers.
+
+## Hosted Checkout (Human Web Shoppers)
+
+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
+orchestrates the same rails as the agent flow — there is no new money movement
+and the merchant fulfills on the same `direct_payment.confirmed` webhook.
+
+```ts
+import { DirectRequestPaymentMerchantClient } from "@siglume/direct-request-payment";
+
+const merchant = new DirectRequestPaymentMerchantClient({ auth_token: process.env.SIGLUME_MERCHANT_AUTH_TOKEN });
+
+// 1. Register the return-URL origins once (open-redirect defense). The origin of
+//    your webhook_callback_url is auto-allowed in addition to these.
+await merchant.setupMerchant({
+  merchant: "your_merchant_key",
+  webhook_callback_url: "https://api.your-shop.com/webhooks/siglume",
+  checkout_allowed_origins: ["https://www.your-shop.com"],
+});
+
+// 2. Per order: create a session and redirect the shopper to checkout_url.
+const session = await merchant.createCheckoutSession({
+  merchant: "your_merchant_key",
+  amount_minor: 500,            // server-fixed; the browser cannot change it
+  currency: "JPY",
+  nonce: order.id,              // unique per order
+  success_url: "https://www.your-shop.com/thanks",
+  cancel_url: "https://www.your-shop.com/cart",
+  metadata: { order_id: order.id },
+});
+redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
+
+// 3. Fulfill when the signed direct_payment.confirmed webhook arrives (the
+//    source of truth). Poll merchant.getCheckoutSession(session.session_id) if
+//    you also want to show status in your own UI.
+```
+
+Siglume fixes the amount, currency, challenge, and return URLs **server-side** at
+session creation, so the browser cannot tamper with the price or the redirect
+target. The shopper's Siglume credentials are never shared with your store.
+
+**Who does what.**
+
+- **Merchant** — confirms the order; signs the challenge (agent flow) or creates
+  a checkout session (web flow); verifies the webhook signature; fulfills
+  idempotently. Never sees the buyer's Siglume credentials.
+- **Siglume** — provides the wallet and login, executes the wallet payment,
+  applies the fee, settles on-chain, and routes Micro / Nano automatically by
+  amount band.
+- **Buyer** — needs a Siglume wallet funded in **JPYC / USDC**. **Not a card
+  payment.**
+
+## Amount-Based Pricing and Settlement
+
+Pricing has one structure: you choose a **Standard Payment** plan once during
+setup, and after that the applied fee and the settlement timing follow the
+**payment amount** automatically. There is nothing else to choose.
+
+- **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-transaction protocol fee, **settled weekly**.
+- **Nano Payment** — very small payments, applied automatically by amount. A
+  flat per-usage protocol fee, **settled monthly**.
+
+Micro Payment and Nano Payment are not separate products you opt into; they are
+amount bands Siglume applies on your behalf. Your integration code is the same
+regardless of which band a payment falls into. The full fee table and the exact
+weekly / monthly settlement schedule are in [docs/pricing.md](./docs/pricing.md).
+Provider revenue in the Micro and Nano bands is not settled revenue until the
+weekly or monthly on-chain settlement succeeds. Siglume keeps outstanding failed
+settlements for retry under the published policy, but does not advance or
+guarantee provider revenue before settlement succeeds.
 
 ## What This SDK Covers
 
@@ -78,15 +176,15 @@ amounts differ.
 
 | Payment amount | Applied automatically | What you select | Fee | Settlement |
 | --- | --- | --- | --- | --- |
-| Over JPY 500 / over USD 3.00, or whenever immediate finality is required | 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. | Immediate on-chain split through DirectPaymentHub after payment confirmation |
-| JPY 50-500 / about USD 0.30-3.00 | Micro Payment | No selection. Applied automatically by amount. | USD 0.01 / Tx, about JPY 2 | Meter gate before provider execution; weekly delayed settlement |
-| Under JPY 1 to JPY 49 / under USD 0.01 to about USD 0.30 | Nano Payment | No selection. Applied automatically by amount. | USD 0.001 / usage, about JPY 0.2 | Meter gate before provider execution; monthly delayed settlement |
+| Over JPY 500 / over USD 3.00, or whenever immediate finality is required | 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 / about USD 0.30-3.00 | Micro Payment | Applied automatically by amount | USD 0.01 / Tx, about JPY 2 | Weekly settlement — see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
+| Under JPY 1 to JPY 49 / under USD 0.01 to about USD 0.30 | Nano Payment | Applied automatically by amount | USD 0.001 / usage, about JPY 0.2 | Monthly settlement — see [Settlement schedule](./docs/pricing.md#settlement-schedule) |
 
 A merchant billing mandate is required before accepting payments, even on the
-Launch plan. The API and merchant registry may still expose the internal plan key
-`free` for the Launch tier; treat it as a compatibility key, not a public plan
-name. `fee_bps` returned on a payment requirement is the authoritative fee rate
-for that payment in the merchant's settlement currency.
+Launch plan. `fee_bps` returned on a payment requirement is the authoritative
+fee rate for that payment in the merchant's settlement currency. The full fee
+table and the weekly / monthly settlement schedule live in
+[docs/pricing.md](./docs/pricing.md).
 
 ## Merchant Setup: One SDK Call
 
@@ -110,12 +208,12 @@ const setup = await merchant.setupCheckout({
   max_amount_minor: 100000,
 });
 
-console.log(setup.env);
-// {
-//   SIGLUME_DIRECT_PAYMENT_MERCHANT: "example_merchant",
-//   SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET: "edrp_...",
-//   SIGLUME_WEBHOOK_SECRET: "whsec_..."
-// }
+// setup.env holds the merchant key plus the challenge and webhook secrets:
+//   SIGLUME_DIRECT_PAYMENT_MERCHANT       (not secret)
+//   SIGLUME_DIRECT_PAYMENT_CHALLENGE_SECRET  (secret)
+//   SIGLUME_WEBHOOK_SECRET                   (secret)
+// Write these to your server-side secret store. Do NOT log the secret values.
+console.log(`Configured merchant: ${setup.env.SIGLUME_DIRECT_PAYMENT_MERCHANT}`);
 ```
 
 ```py
@@ -136,7 +234,9 @@ setup = merchant.setup_checkout(
     max_amount_minor=100000,
 )
 
-print(setup["env"])
+# setup["env"] holds the merchant key plus the challenge and webhook secrets.
+# Persist them to your server-side secret store; do not log the secret values.
+print("Configured merchant:", setup["env"]["SIGLUME_DIRECT_PAYMENT_MERCHANT"])
 ```
 
 Store returned secrets on the merchant server. `challenge_secret` and
@@ -289,7 +389,8 @@ const recurring = await createDirectRequestPaymentRecurringChallenge({
 //   POST /v1/sdrp/direct-payments/subscriptions
 //   { merchant, amount_minor, currency, cadence: "monthly", challenge }
 // For scheduled autopay, the buyer instead creates a scheduled auto-pay
-// authorization (mode: "external_402") and gives you the schedule_token.
+// authorization and hands you the schedule_token; your scheduler triggers
+// each occurrence with that token.
 ```
 
 ```py
@@ -383,6 +484,16 @@ Read [docs/security.md](./docs/security.md) before going live.
 - Fulfill orders only from verified webhook data, with idempotency.
 - Treat `fee_bps` returned by Siglume as the runtime fee source of truth.
 
+## Compatibility Notes
+
+- The Direct Request Payment HTTP endpoints live under
+  `/v1/sdrp/direct-payments/...`; the SDK targets them for you.
+- For wire compatibility the platform still tags these payments with the legacy
+  mode value `external_402`, and the merchant registry may still expose the
+  legacy billing-plan key `free` for the Launch tier. The SDK sets and reads
+  these values for you — treat them as compatibility identifiers, not public
+  product names.
+
 ## Documentation
 
 - [Merchant quickstart](./docs/merchant-quickstart.md)

package/dist/index.cjs

@@ -125,7 +125,7 @@ var DirectRequestPaymentClient = class {
     this.auth_token = authToken;
     this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
-    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.3.5";
+    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.4.0";
     this.fetch_impl = fetchImpl;
   }
   async createPaymentRequirement(input) {
@@ -230,7 +230,7 @@ var DirectRequestPaymentMerchantClient = class {
     this.auth_token = authToken;
     this.base_url = (options.base_url ?? envValue("SIGLUME_API_BASE") ?? DEFAULT_SIGLUME_API_BASE).replace(/\/+$/, "");
     this.timeout_ms = Math.max(1, Math.trunc(options.timeout_ms ?? 15e3));
-    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.3.5";
+    this.user_agent = options.user_agent ?? "@siglume/direct-request-payment/0.4.0";
     this.fetch_impl = fetchImpl;
   }
   async setupMerchant(input) {
@@ -254,8 +254,47 @@ var DirectRequestPaymentMerchantClient = class {
     if (input.max_amount_minor !== void 0) {
       payload.max_amount_minor = positiveInteger(input.max_amount_minor, "max_amount_minor");
     }
+    if (input.checkout_allowed_origins !== void 0) {
+      payload.checkout_allowed_origins = normalizeOriginList(input.checkout_allowed_origins);
+    }
     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
+   * 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
+   * (the source of truth), exactly as with the agent flow.
+   *
+   * `success_url`/`cancel_url` must be on an origin you registered via
+   * `checkout_allowed_origins` (or your `webhook_callback_url` origin).
+   */
+  async createCheckoutSession(input) {
+    const payload = {
+      merchant: normalizeSelfServiceMerchant(input.merchant),
+      amount_minor: positiveInteger(input.amount_minor, "amount_minor"),
+      currency: normalizeCurrency(input.currency),
+      nonce: requireNonEmpty(input.nonce, "nonce"),
+      success_url: requireNonEmpty(input.success_url, "success_url"),
+      cancel_url: requireNonEmpty(input.cancel_url, "cancel_url")
+    };
+    if (input.metadata !== void 0) {
+      payload.metadata = cloneJsonObject(input.metadata, "metadata");
+    }
+    return this.request(
+      "POST",
+      "/sdrp/direct-payments/checkout-sessions",
+      payload
+    );
+  }
+  /** Read a Hosted Checkout session's status (open / authenticated / paid / expired / cancelled / failed). */
+  async getCheckoutSession(session_id) {
+    return this.request(
+      "GET",
+      `/sdrp/direct-payments/checkout-sessions/${encodeURIComponent(requireNonEmpty(session_id, "session_id"))}`
+    );
+  }
   async getMerchant(merchant) {
     return this.request(
       "GET",
@@ -624,6 +663,29 @@ function normalizeAllowedCurrencies(value) {
 function defaultTokenForCurrency(currency) {
   return currency === "JPY" ? "JPYC" : "USDC";
 }
+function normalizeOriginList(value) {
+  if (!Array.isArray(value)) {
+    throw new SiglumeDirectRequestPaymentError("checkout_allowed_origins must be an array of origin URLs.");
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const origins = [];
+  for (const item of value) {
+    let url;
+    try {
+      url = new URL(requireNonEmpty(String(item), "checkout_allowed_origins entry"));
+    } catch {
+      throw new SiglumeDirectRequestPaymentError(
+        "each checkout_allowed_origins entry must be an absolute origin such as https://shop.example.com."
+      );
+    }
+    const origin = `${url.protocol.toLowerCase()}//${url.host.toLowerCase()}`;
+    if (!seen.has(origin)) {
+      seen.add(origin);
+      origins.push(origin);
+    }
+  }
+  return origins;
+}
 function positiveInteger(value, name) {
   const parsed = Number(value);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {