@siglume/direct-request-payment 0.4.19 → 0.4.20

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.4.20 - 2026-06-20
+
+Close the v0.4.19 public onboarding safety review.
+
+- Fixed generated Express/FastAPI webhook handling so webhook event ids are
+  recorded as processed only after the order update or durable review write
+  succeeds. A retry after a mid-handler failure is no longer discarded as a
+  duplicate.
+- Added stable checkout attempts/nonces to generated routes and starters so a
+  retry or double click reuses the active attempt instead of creating a fresh
+  timestamp nonce.
+- Split Express checkout and webhook mounting helpers so production apps can
+  mount the raw-body webhook before global `express.json()`.
+- Strengthened `siglume-check readiness` to require `SIGLUME_WEBHOOK_SECRET`,
+  active billing, matching active webhook subscription, subscribed
+  `direct_payment.confirmed`, matching signing-secret hint, Hosted Checkout
+  probe, and signed webhook delivery probe.
+- Added webhook subscription/test-delivery/delivery-list client helpers in
+  TypeScript and Python.
+- Made generated 10-minute routes Standard-only by default; Micro / Nano now
+  require explicit delayed-settlement reconciliation before fulfillment.
+- Clarified Micro / Nano unsettled-exposure scope and terminal states across
+  pricing, announcement, lifecycle, troubleshooting, and API reference docs.
+- Added readiness negative tests and webhook API client tests.
+
 ## 0.4.19 - 2026-06-20
 
 Make the 10-minute integration path a real product-integration path instead of

package/README.md

@@ -98,7 +98,8 @@ siglume-sdrp init fastapi --target app/siglume
 ```
 
 The readiness command checks account, billing, origin, webhook, and Hosted
-Checkout availability before you write checkout code.
+Checkout availability before you write checkout code. It also confirms the
+webhook subscription and signed test delivery when API probes are enabled.
 
 Before implementation, confirm Hosted Checkout readiness in
 [Troubleshooting](./docs/troubleshooting.md#hosted-checkout-readiness). For
@@ -119,8 +120,8 @@ fulfilling orders.
 
 | 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 |
+| EC one-time Standard payment | Hosted Checkout | Yes, with `siglume-check readiness` and `siglume-sdrp init` | Product DB adapter, refund/support process, monitoring |
+| Game consumables | Hosted Checkout or agent/API | Conditional | Idempotent entitlement grants, disconnect recovery, Micro / Nano settlement reconciliation and past-due 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 |
@@ -171,8 +172,8 @@ redirect(session.checkout_url); // -> https://siglume.com/pay/<session_id>
 
 // 3. Handle the signed direct_payment.confirmed webhook. Use
 //    classifyDirectPaymentConfirmation(event). Fulfill Standard only for
-//    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
-//    until the later metered_batch_settled event arrives.
+//    standard_settled. Do not fulfill metered_usage_accepted unless you have
+//    explicitly enabled Micro / Nano settlement reconciliation.
 //    Poll merchant.getCheckoutSession(session.session_id) if you also want to
 //    show status in your own UI.
 ```
@@ -206,8 +207,8 @@ redirect(session["checkout_url"])  # -> https://siglume.com/pay/<session_id>
 
 # 3. Handle the signed direct_payment.confirmed webhook. Use
 #    classify_direct_payment_confirmation(event). Fulfill Standard only for
-#    standard_settled; treat metered_usage_accepted as fulfilled-unsettled
-#    until the later metered_batch_settled event arrives.
+#    standard_settled. Do not fulfill metered_usage_accepted unless you have
+#    explicitly enabled Micro / Nano settlement reconciliation.
 #    Poll merchant.get_checkout_session(session["session_id"]) if you also want
 #    to show status in your own UI.
 ```
@@ -631,7 +632,8 @@ if (event.type === "direct_payment.confirmed") {
   } else if (confirmation.kind === "standard_settled") {
     // Mark the order paid once if event.data.challenge_hash/order mapping matches.
   } else if (confirmation.kind === "metered_usage_accepted") {
-    // Mark fulfilled-but-unsettled after matching confirmation.challenge_hash.
+    // Default Standard-only integrations should not fulfill this.
+    // Enable Micro / Nano only with settlement reconciliation and past-due handling.
   } else {
     // Route confirmation.reason to manual review. Do not mark paid or fulfilled.
   }
@@ -662,7 +664,8 @@ if verified["event"]["type"] == "direct_payment.confirmed":
         # Mark the order paid once if event.data.challenge_hash/order mapping matches.
         pass
     elif confirmation["kind"] == "metered_usage_accepted":
-        # Mark fulfilled-but-unsettled after matching confirmation["challenge_hash"].
+        # Default Standard-only integrations should not fulfill this.
+        # Enable Micro / Nano only with settlement reconciliation and past-due handling.
         pass
     else:
         # Route confirmation["reason"] to manual review. Do not mark paid or fulfilled.

package/bin/siglume-sdrp.mjs

@@ -52,7 +52,7 @@ Readiness options:
   --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.
+  --no-probe                Partial API check only; readiness will not be reported as ready.
   --json                    Print machine-readable JSON.
 `);
 }
@@ -89,6 +89,7 @@ async function readiness(options) {
   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 webhookSecret = process.env.SIGLUME_WEBHOOK_SECRET || "";
   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));
@@ -97,6 +98,7 @@ async function readiness(options) {
   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, "webhook_secret_present", Boolean(webhookSecret) && webhookSecret.startsWith("whsec_"), "Set SIGLUME_WEBHOOK_SECRET to the webhook signing secret returned by setupCheckout/setup_checkout.");
   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)) {
@@ -104,17 +106,46 @@ async function readiness(options) {
       auth_token: token,
       base_url: options.baseUrl || process.env.SIGLUME_API_BASE,
     });
+    let matchingWebhookSubscription = null;
     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.");
+      check(checks, "billing_mandate", Boolean(account.billing_mandate_id), "Complete the merchant billing mandate wallet approval.");
+      check(checks, "billing_status_active", activeLike(account.billing_status), `Billing status is ${account.billing_status || "unknown"}; it must be active before accepting payments.`);
       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 (!hasFailures(checks)) {
+      try {
+        const subscriptions = await merchantClient.listWebhookSubscriptions();
+        const activeSubscriptions = subscriptions.filter((subscription) => activeLike(subscription.status));
+        matchingWebhookSubscription = activeSubscriptions.find((subscription) => urlsEqual(subscription.callback_url, webhookUrl)) || null;
+        check(checks, "webhook_subscription_exists", activeSubscriptions.length > 0, "Create an active webhook subscription before checkout.");
+        check(checks, "webhook_callback_matches", Boolean(matchingWebhookSubscription), `No active webhook subscription points at ${webhookUrl}.`);
+        check(
+          checks,
+          "direct_payment_confirmed_subscribed",
+          Boolean(matchingWebhookSubscription) && includesEventType(matchingWebhookSubscription.event_types, "direct_payment.confirmed"),
+          "The matching webhook subscription must include direct_payment.confirmed.",
+        );
+        check(
+          checks,
+          "webhook_secret_matches_subscription_hint",
+          Boolean(matchingWebhookSubscription?.signing_secret_hint) && webhookSecret.endsWith(String(matchingWebhookSubscription.signing_secret_hint)),
+          "SIGLUME_WEBHOOK_SECRET does not match the signing_secret_hint for the matching subscription. Rotate or re-save the webhook secret.",
+        );
+      } catch (error) {
+        check(checks, "webhook_subscription_api", false, apiErrorMessage(error, "Could not read webhook subscriptions."));
+      }
+    }
+
+    if (!options.probe && !hasFailures(checks)) {
+      check(checks, "hosted_checkout_probe", false, "--no-probe skips Hosted Checkout and webhook delivery probes. Remove --no-probe for readiness.");
+    }
+
     if (options.probe && !hasFailures(checks)) {
       try {
         const session = await merchantClient.createCheckoutSession({
@@ -134,6 +165,13 @@ async function readiness(options) {
         check(checks, "hosted_checkout", false, message);
       }
     }
+
+    if (options.probe && !hasFailures(checks)) {
+      await checkWebhookDeliveryProbe(checks, merchantClient, {
+        merchant,
+        subscription: matchingWebhookSubscription,
+      });
+    }
   }
 
   const ok = !hasFailures(checks);
@@ -144,7 +182,11 @@ async function readiness(options) {
       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 && !options.api) {
+      console.log("Local config checks passed. API, Hosted Checkout, and webhook delivery readiness were not verified.");
+    } else {
+      console.log(ok ? "Ready for 10-minute SDRP integration." : "Not ready. Fix the FAIL items before coding checkout.");
+    }
   }
   if (!ok) {
     process.exitCode = 1;
@@ -163,11 +205,32 @@ async function init(args) {
   }
   const from = join(rootDir, "templates", framework);
   const to = resolve(process.cwd(), target);
+  if (!Boolean(parsed.force)) {
+    const conflicts = await findCopyConflicts(from, to);
+    if (conflicts.length) {
+      throw new Error(`Refusing to overwrite existing files. Re-run with --force to overwrite:\n${conflicts.join("\n")}`);
+    }
+  }
   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 findCopyConflicts(from, to) {
+  const conflicts = [];
+  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()) {
+      conflicts.push(...await findCopyConflicts(src, dst));
+    } else if (await exists(dst)) {
+      conflicts.push(dst);
+    }
+  }
+  return conflicts;
+}
+
 async function copyDir(from, to, force) {
   await mkdir(to, { recursive: true });
   for (const entry of await readdir(from)) {
@@ -259,6 +322,74 @@ function activeLike(value) {
   return /^(active|ready|current|ok|enabled|paid|complete|completed)$/i.test(String(value || ""));
 }
 
+function includesEventType(eventTypes, eventType) {
+  if (!Array.isArray(eventTypes) || eventTypes.length === 0) return true;
+  return eventTypes.map((item) => String(item)).includes(eventType);
+}
+
+function urlsEqual(left, right) {
+  try {
+    const leftUrl = new URL(String(left || ""));
+    const rightUrl = new URL(String(right || ""));
+    return leftUrl.href === rightUrl.href;
+  } catch {
+    return false;
+  }
+}
+
+function subscriptionId(subscription) {
+  return String(subscription?.id || subscription?.webhook_subscription_id || subscription?.subscription_id || "");
+}
+
+async function checkWebhookDeliveryProbe(checks, merchantClient, { merchant, subscription }) {
+  const id = subscriptionId(subscription);
+  if (!id) {
+    check(checks, "webhook_delivery_probe_passed", false, "Cannot run webhook delivery probe without a matching subscription id.");
+    return;
+  }
+  try {
+    const queued = await merchantClient.queueWebhookTestDelivery({
+      event_type: "direct_payment.confirmed",
+      subscription_ids: [id],
+      data: {
+        mode: "readiness_probe",
+        merchant,
+        direct_payment_requirement_id: `dpr_readiness_${Date.now()}`,
+        requirement_id: `dpr_readiness_${Date.now()}`,
+        challenge_hash: "sha256:readiness_probe",
+        pricing_band: "standard",
+        settlement_status: "readiness_probe",
+      },
+    });
+    const eventId = String(queued?.event?.id || "");
+    const deadline = Date.now() + 10000;
+    while (eventId && Date.now() < deadline) {
+      const deliveries = await merchantClient.listWebhookDeliveries({
+        subscription_id: id,
+        event_type: "direct_payment.confirmed",
+        limit: 10,
+      });
+      const delivery = deliveries.find((item) => String(item.event_id || "") === eventId);
+      if (delivery?.delivery_status === "delivered") {
+        check(checks, "webhook_delivery_probe_passed", true, "ready");
+        return;
+      }
+      if (delivery?.delivery_status === "failed") {
+        check(checks, "webhook_delivery_probe_passed", false, `Webhook delivery failed with response_status=${delivery.response_status ?? "unknown"}.`);
+        return;
+      }
+      await sleep(1000);
+    }
+    check(checks, "webhook_delivery_probe_passed", false, "Webhook test delivery was queued but did not report delivered before timeout. Check callback reachability and delivery logs.");
+  } catch (error) {
+    check(checks, "webhook_delivery_probe_passed", false, apiErrorMessage(error, "Webhook delivery probe failed."));
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function apiErrorMessage(error, fallback) {
   if (error instanceof SiglumeApiError) {
     return `${fallback} ${error.code} (${error.status}).`;

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.19";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.20";
 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";
@@ -404,6 +404,30 @@ var DirectRequestPaymentMerchantClient = class {
     }
     return this.request("POST", "/market/webhooks/subscriptions", payload);
   }
+  async listWebhookSubscriptions() {
+    return this.request("GET", "/market/webhooks/subscriptions");
+  }
+  async queueWebhookTestDelivery(input) {
+    const payload = {
+      event_type: requireNonEmpty(input.event_type, "event_type")
+    };
+    if (input.data !== void 0) {
+      payload.data = cloneJsonObject(input.data, "data");
+    }
+    if (input.subscription_ids !== void 0) {
+      payload.subscription_ids = input.subscription_ids.map((subscriptionId) => requireNonEmpty(subscriptionId, "subscription_id"));
+    }
+    return this.request("POST", "/market/webhooks/test-deliveries", payload);
+  }
+  async listWebhookDeliveries(input = {}) {
+    const params = new URLSearchParams();
+    if (input.subscription_id !== void 0) params.set("subscription_id", requireNonEmpty(input.subscription_id, "subscription_id"));
+    if (input.event_type !== void 0) params.set("event_type", requireNonEmpty(input.event_type, "event_type"));
+    if (input.status !== void 0) params.set("status", requireNonEmpty(input.status, "status"));
+    if (input.limit !== void 0) params.set("limit", String(positiveInteger(input.limit, "limit")));
+    const query = params.toString();
+    return this.request("GET", `/market/webhooks/deliveries${query ? `?${query}` : ""}`);
+  }
   async setupCheckout(input) {
     const merchant = await this.setupMerchant(input);
     const merchantKey = merchant.merchant_account.merchant;