@siglume/direct-request-payment 0.4.17 → 0.4.19

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.4.19 - 2026-06-20
+
+Make the 10-minute integration path a real product-integration path instead of
+a separate demo.
+
+- Added npm and PyPI CLI bins `siglume-sdrp` and `siglume-check`.
+- Added `siglume-check readiness` to validate merchant token, merchant key,
+  HTTPS origin/webhook configuration, Standard-band probe amount, merchant
+  account/billing readiness, and Hosted Checkout availability through an unpaid
+  checkout-session probe.
+- Added `siglume-sdrp init express` for npm and `siglume-sdrp init fastapi` for
+  npm/PyPI to copy framework-specific checkout/webhook route files into an
+  existing product.
+- Added Express and FastAPI integration templates with order-store adapter
+  interfaces so teams can wire SDRP into their real order database instead of
+  starting from an isolated sample app.
+- Reframed the 10-minute guide around existing-product integration and moved
+  the readiness check before any coding.
+
+## 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.

package/README.md

@@ -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,53 @@ 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
+
+Use [10-Minute Product Integration](./docs/quickstart-10-minutes.md) to add
+Hosted Checkout routes to an existing Express or FastAPI product. The path is
+CLI-first:
+
+```bash
+npm install @siglume/direct-request-payment
+npx siglume-check readiness
+npx siglume-sdrp init express --target src/siglume
+```
+
+or:
+
+```bash
+pip install siglume-direct-request-payment
+siglume-sdrp init fastapi --target app/siglume
+```
+
+The readiness command checks account, billing, origin, webhook, and Hosted
+Checkout availability before you write checkout code.
+
+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 integration path? | Production work still required |
+| --- | --- | --- | --- |
+| EC one-time Standard payment | Hosted Checkout | Yes, with `siglume-check readiness` and `siglume-sdrp init` | Refund/support process and 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 +133,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
@@ -286,8 +335,8 @@ 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.
@@ -641,7 +690,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
 
@@ -670,12 +721,17 @@ Read [docs/security.md](./docs/security.md) before going live.
 ## Documentation
 
 - [Merchant quickstart](./docs/merchant-quickstart.md)
+- [10-minute product integration](./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/bin/siglume-sdrp.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  DirectRequestPaymentMerchantClient,
+  HostedCheckoutNotAvailableError,
+  SiglumeApiError,
+} from "../dist/index.js";
+
+const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+main().catch((error) => {
+  console.error(`siglume-sdrp: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});
+
+async function main() {
+  loadDotEnv();
+  const [command = "help", ...args] = process.argv.slice(2);
+  if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+  if (command === "readiness" || command === "doctor") {
+    await readiness(parseArgs(args));
+    return;
+  }
+  if (command === "init") {
+    await init(args);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+function printHelp() {
+  console.log(`Siglume SDRP integration CLI
+
+Usage:
+  siglume-check readiness --merchant <key> --origin <https://shop.example> --webhook-url <https://api.example/siglume/webhook>
+  siglume-sdrp init express --target src/siglume
+  siglume-sdrp init fastapi --target app/siglume
+
+Readiness options:
+  --merchant <key>          Merchant key. Defaults to SIGLUME_DIRECT_PAYMENT_MERCHANT.
+  --origin <origin>         Public shop origin. Defaults to SHOP_PUBLIC_ORIGIN.
+  --webhook-url <url>       Public webhook URL. Defaults to SHOP_WEBHOOK_URL.
+  --currency <JPY|USD>      Probe currency. Defaults to SIGLUME_DIRECT_PAYMENT_TEST_CURRENCY or JPY.
+  --amount-minor <amount>   Standard-band probe amount. Defaults to 501 for JPY, 301 for USD.
+  --base-url <url>          Siglume API base URL. Defaults to SIGLUME_API_BASE or production.
+  --no-api                  Validate local config only; do not call Siglume.
+  --no-probe                Call getMerchant only; do not create an unpaid checkout session.
+  --json                    Print machine-readable JSON.
+`);
+}
+
+function parseArgs(args) {
+  const out = { api: true, probe: true, json: false };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--no-api") {
+      out.api = false;
+    } else if (arg === "--no-probe") {
+      out.probe = false;
+    } else if (arg === "--json") {
+      out.json = true;
+    } else if (arg === "--force") {
+      out.force = true;
+    } else if (arg.startsWith("--")) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const value = args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error(`${arg} requires a value.`);
+      }
+      out[key] = value;
+      i += 1;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+  return out;
+}
+
+async function readiness(options) {
+  const checks = [];
+  const merchant = options.merchant || process.env.SIGLUME_DIRECT_PAYMENT_MERCHANT || "";
+  const origin = options.origin || process.env.SHOP_PUBLIC_ORIGIN || "";
+  const webhookUrl = options.webhookUrl || process.env.SHOP_WEBHOOK_URL || "";
+  const token = process.env.SIGLUME_MERCHANT_AUTH_TOKEN || process.env.SIGLUME_AUTH_TOKEN || "";
+  const currency = normalizeCurrency(options.currency || process.env.SIGLUME_DIRECT_PAYMENT_TEST_CURRENCY || "JPY");
+  const amountMinor = Number(options.amountMinor || process.env.SIGLUME_DIRECT_PAYMENT_TEST_AMOUNT_MINOR || (currency === "USD" ? 301 : 501));
+
+  check(checks, "merchant_key", Boolean(merchant), "Set SIGLUME_DIRECT_PAYMENT_MERCHANT or pass --merchant.");
+  check(checks, "merchant_token", Boolean(token) && !token.startsWith("cli_"), "Set SIGLUME_MERCHANT_AUTH_TOKEN to a merchant Siglume bearer token, not a cli_ key.");
+  check(checks, "shop_origin", isHttpsOrigin(origin), "Set SHOP_PUBLIC_ORIGIN to an https origin, for example https://www.example.com.");
+  check(checks, "webhook_url", isHttpsUrl(webhookUrl), "Set SHOP_WEBHOOK_URL to a public https webhook URL.");
+  check(checks, "standard_probe_amount", isStandardAmount(currency, amountMinor), "Use a Standard-band probe amount: JPY 501+ or USD 301+ minor units.");
+
+  if (options.api && !hasFailures(checks)) {
+    const merchantClient = new DirectRequestPaymentMerchantClient({
+      auth_token: token,
+      base_url: options.baseUrl || process.env.SIGLUME_API_BASE,
+    });
+    try {
+      const merchantResponse = await merchantClient.getMerchant(merchant);
+      const account = merchantResponse.merchant_account || {};
+      check(checks, "merchant_exists", Boolean(account.merchant), "Run merchant setup before checkout.");
+      check(checks, "billing_mandate", Boolean(account.billing_mandate_id) || activeLike(account.billing_status), "Complete the merchant billing mandate wallet approval.");
+      warnIf(checks, "merchant_status", account.status && !activeLike(account.status), `Merchant status is ${account.status}; confirm it is allowed to accept payments.`);
+      warnIf(checks, "billing_status", account.billing_status && !activeLike(account.billing_status), `Billing status is ${account.billing_status}; confirm it is active before accepting payments.`);
+    } catch (error) {
+      check(checks, "merchant_api", false, apiErrorMessage(error, "Could not read the merchant account."));
+    }
+
+    if (options.probe && !hasFailures(checks)) {
+      try {
+        const session = await merchantClient.createCheckoutSession({
+          merchant,
+          amount_minor: amountMinor,
+          currency,
+          nonce: `sdrp-readiness-${Date.now()}`,
+          success_url: `${origin}/siglume-readiness/success`,
+          cancel_url: `${origin}/siglume-readiness/cancel`,
+          metadata: { source: "siglume-sdrp-readiness" },
+        });
+        check(checks, "hosted_checkout", Boolean(session.checkout_url && session.challenge_hash), "Hosted Checkout did not return a checkout_url.");
+      } catch (error) {
+        const message = error instanceof HostedCheckoutNotAvailableError
+          ? "Hosted Checkout is not enabled for this merchant account. Ask Siglume to enable it before coding the human checkout path."
+          : apiErrorMessage(error, "Hosted Checkout probe failed. Check checkout_allowed_origins, currency, amount, and billing mandate.");
+        check(checks, "hosted_checkout", false, message);
+      }
+    }
+  }
+
+  const ok = !hasFailures(checks);
+  if (options.json) {
+    console.log(JSON.stringify({ ok, checks }, null, 2));
+  } else {
+    for (const item of checks) {
+      const mark = item.status === "pass" ? "OK" : item.status === "warn" ? "WARN" : "FAIL";
+      console.log(`${mark} ${item.name}: ${item.message}`);
+    }
+    console.log(ok ? "Ready for 10-minute SDRP integration." : "Not ready. Fix the FAIL items before coding checkout.");
+  }
+  if (!ok) {
+    process.exitCode = 1;
+  }
+}
+
+async function init(args) {
+  const framework = args[0];
+  const parsed = parseArgs(args.slice(1));
+  const target = parsed.target;
+  if (!["express", "fastapi"].includes(framework)) {
+    throw new Error("init requires framework: express or fastapi.");
+  }
+  if (!target) {
+    throw new Error("init requires --target <directory>.");
+  }
+  const from = join(rootDir, "templates", framework);
+  const to = resolve(process.cwd(), target);
+  await copyDir(from, to, Boolean(parsed.force));
+  console.log(`Copied ${framework} SDRP integration files to ${to}`);
+  console.log("Wire the exported router into your app, then run siglume-check readiness before opening checkout.");
+}
+
+async function copyDir(from, to, force) {
+  await mkdir(to, { recursive: true });
+  for (const entry of await readdir(from)) {
+    const src = join(from, entry);
+    const dst = join(to, entry);
+    const info = await stat(src);
+    if (info.isDirectory()) {
+      await copyDir(src, dst, force);
+    } else {
+      if (!force && await exists(dst)) {
+        throw new Error(`${dst} already exists. Re-run with --force to overwrite.`);
+      }
+      await mkdir(dirname(dst), { recursive: true });
+      await writeFile(dst, await readFile(src));
+    }
+  }
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function loadDotEnv() {
+  try {
+    const text = readFileSync(resolve(process.cwd(), ".env"), "utf8");
+    for (const line of text.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) continue;
+      const [key, ...rest] = trimmed.split("=");
+      if (key && !process.env[key]) {
+        process.env[key] = rest.join("=").replace(/^["']|["']$/g, "");
+      }
+    }
+  } catch {
+    // .env is optional.
+  }
+}
+
+function check(checks, name, passed, message) {
+  checks.push({ name, status: passed ? "pass" : "fail", message: passed ? "ready" : message });
+}
+
+function warnIf(checks, name, condition, message) {
+  if (condition) {
+    checks.push({ name, status: "warn", message });
+  }
+}
+
+function hasFailures(checks) {
+  return checks.some((item) => item.status === "fail");
+}
+
+function isHttpsOrigin(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.origin === value.replace(/\/$/, "");
+  } catch {
+    return false;
+  }
+}
+
+function isHttpsUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function normalizeCurrency(value) {
+  const currency = String(value || "").toUpperCase();
+  if (currency !== "JPY" && currency !== "USD") {
+    throw new Error("--currency must be JPY or USD.");
+  }
+  return currency;
+}
+
+function isStandardAmount(currency, amountMinor) {
+  return Number.isSafeInteger(amountMinor) && amountMinor >= (currency === "USD" ? 301 : 501);
+}
+
+function activeLike(value) {
+  return /^(active|ready|current|ok|enabled|paid|complete|completed)$/i.test(String(value || ""));
+}
+
+function apiErrorMessage(error, fallback) {
+  if (error instanceof SiglumeApiError) {
+    return `${fallback} ${error.code} (${error.status}).`;
+  }
+  return fallback;
+}

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.17";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.19";
 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";
@@ -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