@stacksjs/defaults 0.75.76 → 0.75.77

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 657 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 658 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -66,7 +66,7 @@ globalThis.toggleDark = toggleDark
 - **Custom Functions**: From `resources/functions/` (counter, dark mode, GPX, geo utilities)
 
 ### Server Auto-Imports (100+)
-- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (104 models)
+- **All ORM Models**: User, Post, Author, Product, Order, Payment, Customer, etc. (105 models)
 - **Request Models**: UserRequest, PostRequest, OrderRequest, etc.
 - **Actions**: Action types and helpers
 - **Schema**: validation schema builder

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

@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Commerce
 
-Comprehensive e-commerce module with 15 sub-modules and 36 models.
+Comprehensive e-commerce module with 15 sub-modules and 37 models.
 
 ## Key Paths
 - Core package: `storage/framework/core/commerce/src/`

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

@@ -12,7 +12,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 - Database package: `storage/framework/core/database/src/`
 - Configuration: `config/database.ts`
 - QB config: `config/query-builder.ts`
-- Migrations: `database/migrations/` (233 migration files, `.sql` format)
+- Migrations: `database/migrations/` (235 migration files, `.sql` format)
 - QB state: `.qb/`
 - ORM: `storage/framework/orm/`
 

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-migrations
-description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 233 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
+description: Use when working with database migrations in a Stacks application - creating migration files, running migrations, fresh migration (drop + recreate), seeding after migration, migration file naming conventions, or the 235 built-in migration files. For the database API itself (queries, connections, SQL helpers), see stacks-database.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -119,6 +119,6 @@ The framework includes migrations for all built-in models:
 - Do not commit a second snapshot under `.qb/`; that indicates a missing `snapshotDir` configuration
 - If a generated SQLite migration rebuilds tables, test it against a copy of the current database and run `PRAGMA integrity_check` plus `PRAGMA foreign_key_check`
 - `--seed` flag after `migrate:fresh` seeds the database with factory data
-- 233 migration files exist by default for all framework models
+- 235 migration files exist by default for all framework models
 - SQLite >= 3.47.2 is required (system requirement)
 - For the database API (queries, connections), see the `stacks-database` skill

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-models
-description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 104 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
+description: Use when working with data models in Stacks - the defineModel() API, model attributes with validation and factories, relationships (hasOne/hasMany/belongsTo/belongsToMany), traits (useAuth, useUuid, useTimestamps, useSearch, useApi, billable, taggable, categorizable, commentable, likeable, observe), computed properties (get/set), model generation, and the 105 built-in framework models. Covers model definitions and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -304,7 +304,7 @@ honoured: fewer rows are seeded rather than a duplicate combination.
 ## Built-in models by category
 
 The ones below are worth knowing by name. They are a selection, not the set:
-`storage/framework/defaults/app/Models/` holds 104, and that directory is the
+`storage/framework/defaults/app/Models/` holds 105, and that directory is the
 authority. This section said "All 62 built-in models by category" while
 listing fewer than that against 102 on disk, so an agent reading to the end
 had no way to tell it was short.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-orm
-description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 104 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
+description: Use when working with the Stacks ORM - defining models with defineModel(), model relationships (hasOne, hasMany, belongsTo, belongsToMany, morphOne, hasManyThrough), attributes, traits, factories, computed properties, query building, transactions, or the 105 built-in models. Covers @stacksjs/orm, storage/framework/orm/, and storage/framework/defaults/app/Models/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, SQLite >= 3.47.2
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -11,7 +11,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ## Key Paths
 - Core ORM package: `storage/framework/core/orm/src/`
 - ORM implementation: `storage/framework/orm/`
-- Model definitions: `storage/framework/defaults/app/Models/` (104 models)
+- Model definitions: `storage/framework/defaults/app/Models/` (105 models)
 - Application models: `app/Models/`
 - Default model templates: `storage/framework/defaults/app/Models/`
 - ORM type globals: `storage/framework/types/orm-globals.d.ts`
@@ -239,16 +239,11 @@ Table defaults to `{tableName}_likes`, FK defaults to `{singular}_id`.
 - `Model._likeable.unlike(id, userId): Promise<void>`
 - `Model._likeable.isLiked(id, userId): Promise<boolean>`
 
-### Billable (when `traits.billable: true`) -- Stripe integration
-All methods lazy-import `@stacksjs/payments`.
-- `createStripeUser(model, options)`, `updateStripeUser(model, options)`, `deleteStripeUser(model)`
-- `createOrGetStripeUser(model, options)`, `retrieveStripeUser(model)`
-- `defaultPaymentMethod(model)`, `setDefaultPaymentMethod(model, pmId)`, `addPaymentMethod(model, paymentMethodId)`, `paymentMethods(model, cardType?)`
-- `newSubscription(model, type, lookupKey, options)` -- returns `{ subscription, paymentIntent }`
-- `updateSubscription(model, type, lookupKey, options)`, `cancelSubscription(model, providerId, options)`
-- `activeSubscription(model)` -- queries `subscriptions` table for `provider_status = 'active'`, then retrieves from Stripe
-- `checkout(model, priceIds[], options)` -- supports `enableTax`, `allowPromotions` options
-- `createSetupIntent(model, options)`, `subscriptionHistory(model)`, `transactionHistory(model)`
+### Billable (when `traits.billable: true`) -- the configured payment driver
+All methods lazy-import `@stacksjs/payments`. Full reference: `stacks-payments`.
+- Provider-neutral (`config.payment.driver`): `paymentCustomer(model)`, `charge(model, money, paymentMethodId, options)`, `createPayment(model, money, options)`, `checkout(model, { mode, lines, successUrl, cancelUrl })`, `paymentMethods(model)`, `removePaymentMethod(model, providerId)`, `newSubscription(model, type, price)` -> `SubscriptionSummary`, `cancelSubscription(model, providerId, { atPeriodEnd })` (ownership-checked), `activeSubscription(model)` -> `{ subscription, providerSubscription }`
+- Stripe only (throw `PaymentUnsupportedError` under another driver): `createStripeUser`, `updateStripeUser`, `deleteStripeUser`, `createOrGetStripeUser`, `retrieveStripeUser`, `syncStripeCustomerDetails`, `setDefaultPaymentMethod`, `addPaymentMethod`, `updateSubscription`, `createSetupIntent`, `subscriptionHistory`, Connect methods
+- Local: `defaultPaymentMethod(model)`, `storeTransaction(model, productId, options)`, `transactionHistory(model)`
 
 ### Two-Factor Auth (when `traits.useAuth.useTwoFactor: true`)
 - `Model._twoFactor.generateTwoFactorForModel(model)` -- generates secret, calls `model.update()`

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

@@ -18,7 +18,9 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 - Methods: `customer`, `charge(payer, money, paymentMethodId)`, `createPayment` (browser completes: `clientConfirmation` is a Stripe client secret or an Adyen session), `refund`, `checkout(payer, { mode, lines, successUrl, ... })`, `paymentMethods`, `removePaymentMethod`, `subscribe`, `cancelSubscription`, `subscriptions`, `verifyWebhook({ payload, headers })` -> `PaymentEvent[]`, `acknowledgeWebhook()`.
 - Unsupported operations throw `PaymentUnsupportedError` (driver + operation). Adyen has no catalog, subscriptions, invoices, coupons or portal.
 - 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.
+- 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.
 
 ## Key Paths
@@ -487,6 +489,7 @@ for the plans it is meant for.
 - `payment_methods` -- columns: `id`, `type`, `last_four`, `brand`, `exp_year`, `exp_month`, `user_id`, `provider_id`, `is_default`
 - `payment_products` -- columns: `id`, `name`, `unit_price`
 - `payment_transactions` -- columns: `id`, `name`, `description`, `amount`, `brand`, `type`, `provider_id`, `user_id`
+- `payment_webhook_events` -- columns: `provider`, `event_id` (unique together), `processed_at`; commerce's webhook dedup
 
 ## User Model Requirements
 The `UserModel` must have:
@@ -521,12 +524,24 @@ const customer = await user.retrieveStripeUser()
 ```
 
 The instance methods are exactly the keys of `createBillableMethods` in
-`core/orm/src/traits/billable.ts`. Among them: `retrieveStripeUser()`,
-`createPayment(amount, options)`, `setDefaultPaymentMethod(id)` (a number is the
-local row, a string is Stripe's `pm_...` id), `deletePaymentMethod(id)`,
-`syncStripeCustomerDetails(options)`, `storeTransaction(productId, options)`,
-`newSubscription(type, lookupKey, options)`. Anything else is not a function at
-runtime.
+`core/orm/src/traits/billable.ts`. Anything else is not a function at runtime.
+
+- Provider-neutral, through the configured driver: `paymentCustomer()`,
+  `charge(money, paymentMethodId, options)`, `createPayment(money, options)`,
+  `checkout({ mode, lines, successUrl, cancelUrl })`, `paymentMethods()`,
+  `removePaymentMethod(providerId)`, `newSubscription(type, price)`,
+  `cancelSubscription(providerId, { atPeriodEnd })` (refuses a subscription the
+  record does not own), `activeSubscription()`. Money is `{ amount, currency }`
+  in minor units; results are the driver's shapes, with `raw` holding the
+  provider's object (strip it before sending to a browser).
+- Stripe only, throwing `PaymentUnsupportedError` under another driver:
+  `createStripeUser`, `updateStripeUser`, `deleteStripeUser`,
+  `createOrGetStripeUser`, `retrieveStripeUser`, `syncStripeCustomerDetails`,
+  `setDefaultPaymentMethod(id)` (a number is the local row, a string Stripe's
+  `pm_...` id), `addPaymentMethod`, `updateSubscription`, `createSetupIntent`,
+  `subscriptionHistory`, and the Connect methods.
+- Local only: `defaultPaymentMethod()`, `storeTransaction(productId, options)`,
+  `transactionHistory()`.
 
 ## Gotchas
 - Stripe API keys MUST be in `.env` as `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY` -- never hardcode them in config files
@@ -534,7 +549,7 @@ runtime.
 - 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
-- `removePaymentMethod()` takes a database record ID (number), not a Stripe PM ID (string)
+- The facade's `Payment.removePaymentMethod()` takes a database record ID (number); the billable instance method `removePaymentMethod()` takes the provider's id (string)
 - `setDefaultPaymentMethod` has two variants: one takes a Stripe PM ID string (`setUserDefaultPayment`), the other takes a database ID number
 - `getOrCreateCustomer()` handles deleted Stripe customers by recreating them
 - Subscription status checks query the local database, not Stripe directly

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

@@ -86,7 +86,7 @@ All model CRUD events: `model:created`, `model:updated`, `model:deleted`
 
 - **Content**: author, post, page
 - **Core**: user, activity, campaign, comment, email-list, notification, social-post, subscription, tag
-- **Commerce (36 models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
+- **Commerce (37 models)**: cart, cart-item, category, coupon, customer, order, order-item, payment, product, product-variant, review, shipping-method, shipping-rate, tax-rate, transaction, gift-card, license-key, and more
 
 All payloads are `Record<string, any>`.
 

package/app/Actions/Dashboard/Settings/BillingShowAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions/runtime'
 import { PaymentTransaction, User } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { forBrowser } from '../../Payment/payment-response'
 
 interface SettledBillingRead {
   label: string
@@ -82,9 +83,12 @@ export default new Action({
       { label: 'Default payment method', result: defaultPaymentMethod },
     ]
 
+    // The provider's own objects stay on the server; the page reads the
+    // provider-neutral fields beside them.
+    const active = subscription.status === 'fulfilled' ? subscription.value as { subscription?: unknown, providerSubscription?: unknown } | undefined : undefined
     return {
-      subscription: subscription.status === 'fulfilled' ? subscription.value : null,
-      paymentMethods: paymentMethods.status === 'fulfilled' ? paymentMethods.value : [],
+      subscription: active ? { subscription: active.subscription, providerSubscription: forBrowser(active.providerSubscription) } : null,
+      paymentMethods: paymentMethods.status === 'fulfilled' ? forBrowser(paymentMethods.value as unknown[]) : [],
       defaultPaymentMethod: defaultPaymentMethod.status === 'fulfilled' ? defaultPaymentMethod.value : null,
       transactions: transactions.map(serializeBillingTransaction),
       unavailable: billingReadFailures(providerReads),

package/app/Actions/Payment/CancelSubscriptionAction.ts

@@ -2,10 +2,11 @@ import { Action } from '@stacksjs/actions/runtime'
 import { isBillable, SubscriptionNotOwnedError } from '@stacksjs/orm'
 import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
+import { forBrowser, paymentFailure } from './payment-response'
 
 export default new Action({
   name: 'CancelSubscriptionAction',
-  description: 'Cancel Subscription for stripe',
+  description: 'Cancel the caller\'s subscription, now or at the end of its period',
   method: 'POST',
   async handle(request: RequestInstance) {
     const providerId = request.get<unknown>('providerId')
@@ -24,15 +25,13 @@ export default new Action({
     // Only the caller's own subscription: the trait checks ownership, and one
     // 404 covers both "no such subscription" and "someone else's".
     try {
-      // `cancelSubscription` answers `{ subscription }` and nothing else. This
-      // returned `.paymentIntent` off it, which is always undefined.
-      const { subscription } = await user.cancelSubscription(providerId)
-      return response.json(subscription)
+      const subscription = await user.cancelSubscription(providerId, { atPeriodEnd: request.get('atPeriodEnd') === true })
+      return response.json(forBrowser(subscription))
     }
     catch (error) {
       if (error instanceof SubscriptionNotOwnedError)
         return response.json({ error: 'Subscription not found' }, 404)
-      throw error
+      return paymentFailure(error)
     }
   },
 })

package/app/Actions/Payment/CreateCheckoutAction.ts

@@ -2,10 +2,19 @@ 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'
 
+/**
+ * A hosted checkout for a price, answered with the page to send the payer to.
+ *
+ * It used to check out a hard-coded Stripe price id from someone's account
+ * and return the payer to https://google.com, which the same-origin check on
+ * checkout redirects refused anyway. The price and the return pages come from
+ * the request now, and the return pages must be on this app's origin.
+ */
 export default new Action({
   name: 'CreateCheckoutAction',
-  description: 'Create Checkout link for stripe',
+  description: 'Create a hosted checkout page for a price',
   method: 'POST',
   async handle(request: RequestInstance) {
     const user = await request.user()
@@ -16,18 +25,30 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const checkout = await user.checkout([
-      {
-        priceId: 'price_1QBEfsBv6MhUdo23avVV0kqx',
-        quantity: 1,
-      },
-    ], {
-      enableTax: true,
-      allowPromotions: true,
-      cancel_url: 'https://google.com',
-      success_url: 'https://google.com',
-    })
+    const price = request.get('price')
+    const successUrl = request.get('successUrl')
+    const cancelUrl = request.get('cancelUrl')
+    const mode = request.get('mode') === 'subscription' ? 'subscription' : 'payment'
+    const quantity = Number(request.get('quantity') ?? 1)
 
-    return response.json(checkout)
+    if (typeof price !== 'string' || !price)
+      return response.json({ message: 'A `price` is required.' }, 422)
+    if (typeof successUrl !== 'string' || !successUrl)
+      return response.json({ message: 'A `successUrl` is required.' }, 422)
+    if (!Number.isInteger(quantity) || quantity < 1)
+      return response.json({ message: '`quantity` is a whole number of at least 1.' }, 422)
+
+    try {
+      const session = await user.checkout({
+        mode,
+        lines: [{ price, quantity }],
+        successUrl,
+        ...(typeof cancelUrl === 'string' && cancelUrl ? { cancelUrl } : {}),
+      })
+      return response.json(forBrowser(session))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/CreateInvoiceSubscription.ts

@@ -1,7 +1,10 @@
+import type { UserModel } from '@stacksjs/orm'
 import { Action } from '@stacksjs/actions/runtime'
+import { config } from '@stacksjs/config'
 import { isBillable } from '@stacksjs/orm'
-import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
+import { BILLING_NOT_ENABLED, manageSubscription, PaymentUnsupportedError, summarizeSubscription } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
+import { forBrowser, paymentFailure } from './payment-response'
 
 export default new Action({
   name: 'CreateInvoiceSubscription',
@@ -16,14 +19,29 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    // There is no `newSubscriptionInvoice` on a billable user, and never was, so
-    // this threw "is not a function". An invoiced subscription is an ordinary
-    // one that Stripe bills by emailing an invoice instead of charging a card.
-    const subscription = await user.newSubscription('pro', 'stacks_pro_monthly', {
-      collection_method: 'send_invoice',
-      days_until_due: 30,
-    })
+    const type = request.get('type')
+    const plan = request.get('plan')
+    if (typeof type !== 'string' || !type || typeof plan !== 'string' || !plan)
+      return response.json({ message: 'An invoiced subscription needs a `plan` (its name) and a `type` (the price lookup key).' }, 422)
 
-    return response.json(subscription)
+    // An invoiced subscription is an ordinary one that Stripe bills by emailing
+    // an invoice instead of charging a card - a Stripe Billing feature. It used
+    // to subscribe everyone to a hard-coded 'pro' / 'stacks_pro_monthly'.
+    try {
+      const driver = String((config as { payment?: { driver?: string } }).payment?.driver ?? 'stripe')
+      if (driver !== 'stripe')
+        throw new PaymentUnsupportedError(driver, 'invoiced subscriptions', 'they are a Stripe Billing feature')
+
+      // `request.user()` is the User model instance, which is what the
+      // billable modules take; its request-facing type omits the model's own methods.
+      const subscription = await manageSubscription.create(user as unknown as UserModel, plan, type, {
+        collection_method: 'send_invoice',
+        days_until_due: 30,
+      })
+      return response.json(forBrowser(summarizeSubscription(subscription)))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/CreatePaymentIntentAction.ts

@@ -1,12 +1,19 @@
 import { Action } from '@stacksjs/actions/runtime'
+import { config } from '@stacksjs/config'
 import { HttpError } from '@stacksjs/error-handling'
 import { isBillable } from '@stacksjs/orm'
 import { BILLING_NOT_ENABLED } from '@stacksjs/payments'
 import { response } from '@stacksjs/router'
+import { forBrowser, paymentFailure } from './payment-response'
 
+/**
+ * Start a payment for a product, completed in the browser on the provider's
+ * SDK. Answers the payment with its `clientConfirmation`: a Stripe client
+ * secret, or an Adyen session (which also needs `returnUrl`).
+ */
 export default new Action({
   name: 'CreatePaymentIntentAction',
-  description: 'Create Payment Intent for stripe',
+  description: 'Start a payment for a product, completed in the browser',
   method: 'POST',
   async handle(request: RequestInstance) {
     const productId = Number(request.get('productId'))
@@ -25,14 +32,20 @@ export default new Action({
       throw new HttpError(422, 'Product not found!')
     }
 
-    // The Product model's column is `price`; `unit_price` has never been one,
-    // so that read was undefined and the intent was created for NaN. And the
-    // method is `createPayment`: `user.paymentIntent()` never existed.
-    const paymentIntent = await user.createPayment(Number(product.get('price')), {
-      currency: 'usd',
-      allowed_payment_method_types: ['card'],
-    })
-
-    return response.json(paymentIntent)
+    // The currency the app configures, not a hard-coded USD; the product's
+    // price is already in minor units.
+    const currency = String((config as { payment?: { currency?: string } }).payment?.currency || 'usd')
+    const returnUrl = request.get('returnUrl')
+
+    try {
+      const payment = await user.createPayment(
+        { amount: Number(product.get('price')), currency },
+        { reference: `product-${productId}`, ...(typeof returnUrl === 'string' && returnUrl ? { returnUrl } : {}) },
+      )
+      return response.json(forBrowser(payment))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/CreateSetupIntentAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'CreateSetupIntentAction',
@@ -16,10 +17,13 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const setupIntent = await user.createSetupIntent({
-      allowed_payment_method_types: ['card', 'link', 'us_bank_account'],
-    })
-
-    return response.json(setupIntent)
+    // `allowed_payment_method_types` was passed here, which is not a Stripe
+    // parameter; Stripe chooses the methods from the dashboard settings.
+    try {
+      return response.json(await user.createSetupIntent())
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/CreateSubscriptionAction.ts

@@ -2,16 +2,17 @@ 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'
 
 export default new Action({
   name: 'CreateSubscriptionAction',
   description: 'Create Subscription for stripe',
   method: 'POST',
   async handle(request: RequestInstance) {
-    const type = request.get('type') as string
-    const plan = request.get('plan') as string
-    const period = request.get('period') as string
-    const description = request.get('description') as string
+    const type = request.get('type')
+    const plan = request.get('plan')
+    if (typeof type !== 'string' || !type || typeof plan !== 'string' || !plan)
+      return response.json({ message: 'A subscription needs a `plan` (its name) and a `type` (the price lookup key).' }, 422)
 
     const user = await request.user()
 
@@ -23,8 +24,13 @@ export default new Action({
 
     // `plan` is the subscription's name ('pro') and `type` the price lookup key
     // ('stacks_pro_monthly'), which is the order `newSubscription` takes them in.
-    const { paymentIntent } = await user.newSubscription(plan, type, { description, metadata: { period } })
-
-    return response.json(paymentIntent)
+    // An incomplete subscription carries a `clientConfirmation` for its first
+    // payment, which the browser confirms.
+    try {
+      return response.json(forBrowser(await user.newSubscription(plan, type)))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/DeleteDefaultPaymentAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'DeleteDefaultPaymentAction',
@@ -16,8 +17,17 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const paymentMethod = Number(request.get('paymentMethod'))
+    // The provider's id for the method, as `paymentMethods` lists it.
+    const paymentMethod = request.get('paymentMethod')
+    if (typeof paymentMethod !== 'string' || !paymentMethod)
+      return response.json({ message: 'A `paymentMethod` id is required.' }, 422)
 
-    await user.deletePaymentMethod(paymentMethod)
+    try {
+      await user.removePaymentMethod(paymentMethod)
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/FetchActiveSubscriptionAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'FetchActiveSubscriptionAction',
@@ -16,8 +17,12 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const subscription = await user.activeSubscription()
-
-    return response.json(subscription)
+    try {
+      const active = await user.activeSubscription()
+      return response.json(active ? { subscription: active.subscription, providerSubscription: forBrowser(active.providerSubscription) } : null)
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/FetchPaymentCustomerAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'FetchPaymentCustomerAction',
@@ -16,10 +17,13 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    // `asStripeUser()` does not exist; `retrieveStripeUser()` is the lookup,
-    // and answers undefined for a user with no Stripe customer yet.
-    const customer = await user.retrieveStripeUser()
-
-    return response.json(customer)
+    // The provider's customer for this user - created on first use - in our
+    // terms, whichever provider is configured.
+    try {
+      return response.json(await user.paymentCustomer())
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/FetchPaymentMethodsAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'FetchPaymentMethodsAction',
@@ -16,8 +17,11 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const paymentMethods = await user.paymentMethods()
-
-    return response.json(paymentMethods)
+    try {
+      return response.json(forBrowser(await user.paymentMethods()))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/SetDefaultPaymentAction.ts

@@ -2,6 +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 { paymentFailure, paymentMethodReference } from './payment-response'
 
 export default new Action({
   name: 'SetDefaultPaymentAction',
@@ -16,13 +17,19 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    // The payment store posts `{ paymentId }`; this read only `setupIntent`, so
-    // it saw undefined and asked for payment method NaN. `setupIntent` is still
-    // read for any client written against the old name.
-    const paymentId = Number(request.get('paymentId') ?? request.get('setupIntent'))
+    // The payment store posts `{ paymentId }`; `setupIntent` is still read for
+    // a client written against the old name. Either a local row id or the
+    // provider's own `pm_...` id.
+    const paymentMethod = paymentMethodReference(request.get('paymentId') ?? request.get('setupIntent'))
+    if (paymentMethod === null)
+      return response.json({ message: 'A `paymentId` is required.' }, 422)
 
-    const paymentMethod = await user.setDefaultPaymentMethod(paymentId)
-
-    return response.json(paymentMethod)
+    try {
+      await user.setDefaultPaymentMethod(paymentMethod)
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/SetUserDefaultPaymentAction.ts

@@ -2,6 +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 { paymentFailure, paymentMethodReference } from './payment-response'
 
 export default new Action({
   name: 'SetUserDefaultPaymentAction',
@@ -16,12 +17,19 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const paymentId = String(request.get('setupIntent'))
+    // The payment store posts `{ paymentId }`; `setupIntent` is still read for
+    // a client written against the old name. Either a local row id or the
+    // provider's own `pm_...` id.
+    const paymentMethod = paymentMethodReference(request.get('setupIntent') ?? request.get('paymentId'))
+    if (paymentMethod === null)
+      return response.json({ message: 'A `paymentId` is required.' }, 422)
 
-    // A string id is Stripe's own `pm_...`, which `setDefaultPaymentMethod`
-    // resolves on Stripe's side. `setUserDefaultPaymentMethod()` never existed.
-    const paymentMethod = await user.setDefaultPaymentMethod(paymentId)
-
-    return response.json(paymentMethod)
+    try {
+      await user.setDefaultPaymentMethod(paymentMethod)
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/StorePaymentMethodAction.ts

@@ -2,6 +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'
 
 export default new Action({
   name: 'StorePaymentMethodAction',
@@ -18,8 +19,11 @@ export default new Action({
 
     const paymentIntent = request.get('setupIntent') as string
 
-    const paymentMethod = await user.addPaymentMethod(paymentIntent)
-
-    return response.json(paymentMethod)
+    try {
+      return response.json(forBrowser(await user.addPaymentMethod(paymentIntent)))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/UpdateDefaultPaymentMethodAction.ts

@@ -2,6 +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 { paymentFailure, paymentMethodReference } from './payment-response'
 
 export default new Action({
   name: 'UpdateDefaultPaymentMethodAction',
@@ -16,8 +17,18 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const paymentMethod = Number(request.get('paymentMethod'))
+    // A local row id or the provider's own id. This answered nothing at all,
+    // so the client waited on an empty response.
+    const paymentMethod = paymentMethodReference(request.get('paymentMethod'))
+    if (paymentMethod === null)
+      return response.json({ message: 'A `paymentMethod` is required.' }, 422)
 
-    await user.setDefaultPaymentMethod(paymentMethod)
+    try {
+      await user.setDefaultPaymentMethod(paymentMethod)
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/UpdateSubscriptionAction.ts

@@ -2,15 +2,17 @@ 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'
 
 export default new Action({
   name: 'UpdateSubscriptionAction',
   description: 'Update Subscription for stripe',
   method: 'POST',
   async handle(request: RequestInstance) {
-    const type = request.get('type') as string
-    const plan = request.get('plan') as string
-    const description = request.get('description') as string
+    const type = request.get('type')
+    const plan = request.get('plan')
+    if (typeof type !== 'string' || !type || typeof plan !== 'string' || !plan)
+      return response.json({ message: 'A subscription change needs a `plan` and a `type` (the new price lookup key).' }, 422)
 
     const user = await request.user()
 
@@ -20,8 +22,11 @@ export default new Action({
     if (!isBillable(user))
       return response.error(BILLING_NOT_ENABLED, 503)
 
-    const { paymentIntent } = await user.updateSubscription(plan, type, { description })
-
-    return response.json(paymentIntent)
+    try {
+      return response.json(forBrowser(await user.updateSubscription(plan, type)))
+    }
+    catch (error) {
+      return paymentFailure(error)
+    }
   },
 })

package/app/Actions/Payment/payment-response.ts

@@ -0,0 +1,50 @@
+import { PaymentProviderError, PaymentUnsupportedError } from '@stacksjs/payments'
+import { response } from '@stacksjs/router'
+
+/**
+ * What the billing endpoints answer when a payment call fails in a way the
+ * caller can act on, so every endpoint reports it the same way:
+ *
+ * - the configured provider cannot do it: 501, naming the provider;
+ * - the provider refused it: 502, with the provider's message and code;
+ * - the request itself was wrong (a float amount, a URL off this origin): 422.
+ *
+ * Anything else is a bug and is rethrown to the error handler.
+ */
+export function paymentFailure(error: unknown): Response {
+  if (error instanceof PaymentUnsupportedError)
+    return response.json({ message: error.message, driver: error.driver, operation: error.operation }, 501)
+  if (error instanceof PaymentProviderError)
+    return response.json({ message: error.message, driver: error.driver, code: error.code }, 502)
+  if (error instanceof TypeError)
+    return response.json({ message: error.message }, 422)
+  throw error
+}
+
+/**
+ * A driver result as the browser should see it: without `raw`, the provider's
+ * own object, which carries far more than the page needs - customer ids,
+ * metadata, other parties' references.
+ */
+export function forBrowser<T>(value: T): T {
+  if (Array.isArray(value))
+    return value.map(entry => forBrowser(entry)) as T
+  if (value && typeof value === 'object' && 'raw' in value) {
+    const { raw: _raw, ...rest } = value as Record<string, unknown>
+    return rest as T
+  }
+  return value
+}
+
+/**
+ * A payment method reference from a request: a local `payment_methods` row id
+ * (a number, or digits) or the provider's own id (`pm_...`). Converting every
+ * value with `Number()` turned a provider id into NaN.
+ */
+export function paymentMethodReference(value: unknown): number | string | null {
+  if (typeof value === 'number' && Number.isInteger(value))
+    return value
+  if (typeof value !== 'string' || !value)
+    return null
+  return /^\d+$/.test(value) ? Number(value) : value
+}

package/app/Models/commerce/Payment.ts

@@ -184,6 +184,16 @@ export default defineModel({
       },
       factory: faker => faker.helpers.maybe(() => faker.lorem.sentence(), { probability: 0.3 }),
     },
+
+    // Why the provider declined it, in the provider's words. Written by the
+    // payment webhook (`handleCommercePaymentEvent`) for ops triage.
+    failureReason: {
+      order: 16,
+      fillable: true,
+      validation: {
+        rule: schema.string().max(1000),
+      },
+    },
   },
 
   dashboard: {

package/app/Models/commerce/PaymentWebhookEvent.ts

@@ -0,0 +1,56 @@
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation/runtime'
+
+/**
+ * A payment webhook delivery already applied. Providers retry until they are
+ * answered, so commerce records each event here in the same transaction as the
+ * order update it makes, and a retry finds its row and does nothing.
+ */
+export default defineModel({
+  name: 'PaymentWebhookEvent',
+  table: 'payment_webhook_events',
+  primaryKey: 'id',
+  autoIncrement: true,
+
+  indexes: [
+    {
+      name: 'payment_webhook_events_provider_event_unique',
+      columns: ['provider', 'event_id'],
+      unique: true,
+    },
+  ],
+
+  // Written by the system on a provider's behalf, never for a caller.
+  ownership: false,
+
+  traits: {
+    useTimestamps: true,
+  },
+
+  attributes: {
+    /** The payment driver that verified it: `stripe`, `adyen`, or one you registered. */
+    provider: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().required().max(64),
+      },
+    },
+    eventId: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.string().required().max(512),
+      },
+    },
+    processedAt: {
+      required: true,
+      fillable: true,
+      validation: {
+        rule: schema.timestamp().required(),
+      },
+    },
+  },
+
+  dashboard: { enabled: false },
+} as const)

package/functions/billing/dashboard.ts

@@ -79,17 +79,21 @@ function normalizeSubscription(value: unknown): BillingSubscription | null {
   if (Object.keys(stored).length === 0)
     return null
 
-  const price = record(records(record(provider.items).data)[0]?.price)
+  // The provider subscription in the payment driver's terms: `price` carries
+  // its name and amount, the period end is a date. It used to be Stripe's own
+  // object, read through `items.data[0].price`.
+  const price = record(provider.price)
+  const priceAmount = record(price.amount)
 
   return {
     id: text(stored.id, stored.uuid, stored.provider_id, stored.providerId),
-    plan: text(stored.plan, stored.type, price.nickname, price.lookup_key),
+    plan: text(stored.plan, stored.type, price.name),
     type: text(stored.type, stored.plan),
     status: text(stored.provider_status, stored.providerStatus, provider.status),
-    amount: number(stored.unit_price ?? stored.unitPrice ?? price.unit_amount),
-    currency: text(price.currency, provider.currency),
-    periodEnd: timestamp(provider.current_period_end ?? stored.ends_at ?? stored.endsAt),
-    cancelAtPeriodEnd: Boolean(provider.cancel_at_period_end),
+    amount: number(stored.unit_price ?? stored.unitPrice ?? priceAmount.amount),
+    currency: text(priceAmount.currency),
+    periodEnd: timestamp(provider.currentPeriodEnd ?? stored.ends_at ?? stored.endsAt),
+    cancelAtPeriodEnd: Boolean(provider.cancelAtPeriodEnd),
   }
 }
 
@@ -101,7 +105,7 @@ function normalizePaymentMethod(value: unknown, defaultId: string): BillingPayme
   return {
     id,
     brand: text(card.brand, method.brand, method.type),
-    lastFour: text(card.last4, method.last_four, method.lastFour),
+    lastFour: text(method.last4, card.last4, method.last_four, method.lastFour),
     expMonth: number(card.exp_month ?? method.exp_month ?? method.expMonth),
     expYear: number(card.exp_year ?? method.exp_year ?? method.expYear),
     isDefault: Boolean(method.is_default ?? method.isDefault) || Boolean(id && id === defaultId),

package/functions/remote-terminal-element.ts

@@ -1,3 +1,6 @@
+// The stylesheet's text-import declaration travels with this module, so an app
+// typechecking it gets the declaration whatever its tsconfig includes.
+/// <reference path="./xterm-styles.d.ts" />
 import type { FitAddon } from '@xterm/addon-fit'
 import type { Terminal } from '@xterm/xterm'
 import { DashboardApiError } from './dashboard-api'

package/functions/text-import-declarations.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * A defaults module that imports a stylesheet (or any non-code file) as text
+ * needs a `declare module` for that specifier, and an app has to SEE it. The
+ * declaration used to sit beside the module unreferenced: this repo's tsconfig
+ * happened to include it, an app's does not, so every app's `buddy typecheck`
+ * failed on stacks 0.75.75 (`Cannot find module '@xterm/xterm/css/xterm.css'`).
+ *
+ * The rule this holds: such a module references its declaration with
+ * `/// <reference path>`, so it reaches any program that typechecks the module.
+ */
+
+const defaultsRoot = resolve(import.meta.dir, '..')
+const TEXT_IMPORT = /import\(\s*'([^']+)'\s*,\s*\{\s*with:\s*\{\s*type:\s*'text'\s*\}\s*\}\s*\)|from\s+'([^']+)'\s+with\s+\{\s*type:\s*'text'\s*\}/g
+const REFERENCE = /^\/\/\/\s*<reference\s+path="([^"]+)"\s*\/>/gm
+
+function textImports(source: string): string[] {
+  return [...source.matchAll(TEXT_IMPORT)].map(match => (match[1] ?? match[2])!).filter(spec => !spec.startsWith('.'))
+}
+
+function declaredByReferences(file: string, source: string): string {
+  return [...source.matchAll(REFERENCE)].map(match => readFileSync(join(dirname(file), match[1]!), 'utf8')).join('\n')
+}
+
+const modules = [...new Bun.Glob('**/*.ts').scanSync({ cwd: defaultsRoot, absolute: true })]
+  .filter(file => !file.includes('/node_modules/') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts'))
+  .map(file => ({ file, source: readFileSync(file, 'utf8') }))
+  .filter(({ source }) => textImports(source).length > 0)
+
+describe('text imports in the defaults', () => {
+  it('finds the ones there are', () => {
+    // The scan is only worth something while it sees the case that broke.
+    expect(modules.map(({ file }) => file.slice(defaultsRoot.length + 1))).toContain('functions/remote-terminal-element.ts')
+  })
+
+  it('reference a declaration for each specifier, so an app typechecking the module sees it', () => {
+    const missing = modules.flatMap(({ file, source }) => {
+      const declared = declaredByReferences(file, source)
+      return textImports(source)
+        .filter(spec => !declared.includes(`declare module '${spec}'`))
+        .map(spec => `${file.slice(defaultsRoot.length + 1)}: ${spec}`)
+    })
+    expect(missing).toEqual([])
+  })
+})

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.76",
+  "version": "0.75.77",
   "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.76",
+  "version": "0.75.77",
   "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.76",
+    "@stacksjs/mobile": "^0.75.77",
     "@stacksjs/sanitizer": "^0.2.378",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/stores/payment.ts

@@ -28,6 +28,21 @@ function requestHeaders(write = false): Record<string, string> {
   return write ? withCsrfHeader(headers) : headers
 }
 
+/**
+ * The Stripe client secret in a payment endpoint's answer. The endpoints
+ * answer in the payment driver's terms - `clientConfirmation` - and this
+ * store confirms with Stripe.js, so a session for another provider (Adyen's
+ * Drop-in) is refused by name rather than handed to Stripe.
+ */
+function stripeClientSecret(result: { clientConfirmation?: { provider: string, clientSecret?: string } }): string {
+  const confirmation = result.clientConfirmation
+  if (!confirmation)
+    throw new Error('The payment needs nothing confirmed in the browser.')
+  if (confirmation.provider !== 'stripe' || !confirmation.clientSecret)
+    throw new Error(`This store confirms Stripe payments; the configured provider is ${confirmation.provider}.`)
+  return confirmation.clientSecret
+}
+
 const paymentStore = defineStore('payment', () => {
   // TODO: update the any types
   const loadingStates = ref<Record<string, boolean>>({})
@@ -69,10 +84,7 @@ const paymentStore = defineStore('payment', () => {
       throw new Error(`Failed to fetch setup intent: ${response.status}`)
     }
 
-    const client: any = await response.json()
-    const clientSecret = client.client_secret
-
-    return clientSecret
+    return stripeClientSecret(await response.json())
   }
 
   async function fetchPaymentIntent(id: number, productId: number): Promise<string> {
@@ -90,13 +102,10 @@ const paymentStore = defineStore('payment', () => {
       throw new Error(`Failed to create payment intent: ${response.status}`)
     }
 
-    const client: any = await response.json()
-    const clientSecret = client.client_secret
-
-    return clientSecret
+    return stripeClientSecret(await response.json())
   }
 
-  async function storeTransaction(id: number, productId: number): Promise<string> {
+  async function storeTransaction(id: number, productId: number): Promise<TransactionHistory> {
     const body = { productId }
 
     const url = `${apiUrl}/payments/store-transaction/${id}`
@@ -111,10 +120,9 @@ const paymentStore = defineStore('payment', () => {
       throw new Error(`Failed to store transaction: ${response.status}`)
     }
 
-    const client: any = await response.json()
-    const clientSecret = client.client_secret
-
-    return clientSecret
+    // The stored transaction. This read `client_secret` off it, which a
+    // transaction never has, so callers always got undefined.
+    return await response.json()
   }
 
   async function subscribeToPlan(body: { type: string, plan: string, description: string }): Promise<string> {
@@ -264,13 +272,15 @@ const paymentStore = defineStore('payment', () => {
     if (response.status !== 204) {
       const res = await response.json()
 
-      transactionHistory.value = res.data
+      // The endpoint answers the rows themselves; `.data` was always undefined.
+      transactionHistory.value = Array.isArray(res) ? res : (res?.data ?? [])
     }
 
     removeLoadingState('fetchTransactionHistory')
   }
 
-  async function deletePaymentMethod(paymentMethod: number): Promise<void> {
+  /** `paymentMethod` is the provider's id, as `paymentMethods` lists it. */
+  async function deletePaymentMethod(paymentMethod: string): Promise<void> {
     setLoadingState('deletePaymentMethod')
     const url = `${apiUrl}/payments/delete-payment-method/${authenticatedUserId()}`