@stacksjs/defaults 0.75.79 → 0.75.81

package/ai/skills/stacks-payments/SKILL.md

@@ -21,6 +21,7 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 - Adyen: Checkout API v72, `X-API-Key`; shopper reference `user-<id>` (no PII); full refunds go to `/reversals`; webhooks verified per item with HMAC-SHA256 over 8 colon-joined fields under the hex key, acknowledged with 202.
 - `PaymentEvent` carries `provider` and `id` (together, the retry key), `reference` (the payment; for a refund, the payment refunded), `amount` (for a refund, that one refund - Stripe's cumulative `amount_refunded` is turned into a delta from `previous_attributes`) and `reason`. Adyen's id is `eventCode:pspReference:success`, since Adyen may resend a pair with the outcome changed.
 - The Stripe driver delegates to the existing billable modules, so idempotency keys and `stripe_id` handling are unchanged.
+- Webhook route: the `payments` default route bundle (mounted with the `commerce` feature) serves `POST /webhooks/payments` through `orders.receivePaymentWebhook(request)`: 401 `missing-config` while the driver's secret is unset (`WebhookNotConfiguredError`), 400 `invalid-signature` (`WebhookSignatureError`), otherwise applies the events and answers with `acknowledgeWebhook()`.
 - Commerce: `orders.handleCommercePaymentEvent(event)` from `@stacksjs/commerce` applies `payment.succeeded` / `payment.failed` (reason into `payments.failure_reason`) / `refund.succeeded` (added to `refund_amount`; `refunded` + order REFUNDED only when it covers the payment, else `partiallyRefunded`) to the order, deduplicated in `payment_webhook_events` (the `PaymentWebhookEvent` model) in the same transaction.
 - Everything below this section is Stripe's own API and returns Stripe objects.
 
@@ -546,7 +547,7 @@ The instance methods are exactly the keys of `createBillableMethods` in
 
 ## Gotchas
 - Stripe API keys MUST be in `.env` as `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY` -- never hardcode them in config files
-- The Stripe SDK is initialized eagerly -- if `STRIPE_SECRET_KEY` is missing, the module throws on import
+- The Stripe client is created lazily, on first use: importing `@stacksjs/payments` without `STRIPE_SECRET_KEY` (or without the opt-in `stripe` package) is fine, and the first Stripe call throws naming what is missing
 - All amounts are in cents -- use `toCents()` and `toDollars()` for conversion
 - `charge()` creates AND confirms the PaymentIntent in one step
 - `subscribe()` resolves the price via `lookup_key`, not a direct Stripe price ID

package/app/Actions/Payment/CreateSetupIntentAction.ts

@@ -2,7 +2,7 @@ import { Action } from '@stacksjs/actions/runtime'
 import { isBillable } from '@stacksjs/orm'
 import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
-import { forBrowser, paymentFailure } from './payment-response'
+import { paymentFailure } from './payment-response'
 
 export default new Action({
   name: 'CreateSetupIntentAction',

package/app/Actions/Payment/DeleteDefaultPaymentAction.ts

@@ -2,7 +2,7 @@ import { Action } from '@stacksjs/actions/runtime'
 import { isBillable } from '@stacksjs/orm'
 import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
-import { forBrowser, paymentFailure } from './payment-response'
+import { paymentFailure } from './payment-response'
 
 export default new Action({
   name: 'DeleteDefaultPaymentAction',

package/app/Actions/Payment/FetchPaymentCustomerAction.ts

@@ -2,7 +2,7 @@ import { Action } from '@stacksjs/actions/runtime'
 import { isBillable } from '@stacksjs/orm'
 import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
-import { forBrowser, paymentFailure } from './payment-response'
+import { paymentFailure } from './payment-response'
 
 export default new Action({
   name: 'FetchPaymentCustomerAction',

package/bootstrap.ts

@@ -153,6 +153,13 @@ if (mounts('delivery')) {
   await route.register(frameworkPath('defaults/routes/delivery.ts'))
 }
 
+// The payment provider's webhook, which applies payments and refunds to
+// orders. Gated with the commerce surface; it answers 401 until the driver's
+// webhook secret is configured.
+if (mounts('payments')) {
+  await route.register(frameworkPath('defaults/routes/payments.ts'))
+}
+
 // Social sign-in: `/auth/{provider}` + `/auth/{provider}/callback`
 // (stacksjs/stacks#2276). An opt-in bundle, NOT part of the implicit default
 // set or `all` — OAuth callback URLs in an app that configured no provider

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.79",
+  "version": "0.75.81",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.79",
+  "version": "0.75.81",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "^0.75.79",
+    "@stacksjs/mobile": "^0.75.81",
     "@stacksjs/sanitizer": "^0.2.378",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/routes/payments.ts

@@ -0,0 +1,17 @@
+import { orders } from '@stacksjs/commerce'
+import { route } from '@stacksjs/router'
+
+/**
+ * The payment provider's webhook (stacksjs/stacks#665, #1879 Co-17).
+ *
+ * Point the provider at `POST /webhooks/payments`: Stripe's endpoint with its
+ * signing secret in `STRIPE_WEBHOOK_SECRET`, or Adyen's standard webhook with
+ * its HMAC key in `ADYEN_HMAC_KEY`, whichever `config.payment.driver` names.
+ * Payments and refunds then reach their orders without app code; orders used
+ * to sit at PENDING whenever the webhook was the only news of a payment.
+ *
+ * Unconfigured, it answers 401 and applies nothing. CSRF-exempt, since the
+ * provider calls it; the signature is what authenticates it. An app route at
+ * the same path registers first and wins.
+ */
+route.post('/webhooks/payments', request => orders.receivePaymentWebhook(request)).skipCsrf()