@stacksjs/defaults 0.75.81 → 0.75.83

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

@@ -230,11 +230,12 @@ straight-line distance by a detour factor and returns `null` for a stationary
 courier rather than `Infinity`.
 
 ## Integration with Payments
-Commerce works with `@stacksjs/payments` for Stripe integration:
+Commerce takes payments through `@stacksjs/payments`, on whichever provider `config.payment.driver` names:
 ```typescript
 import { Payment } from '@stacksjs/payments'
-await Payment.charge(customer, order.totalAmount, paymentMethodId)
+await Payment.charge(customer, { amount: order.totalAmount, currency: 'usd' }, paymentMethodId, { reference: `order-${order.id}` })
 ```
+The provider's webhook reaches orders through `POST /webhooks/payments` (see `stacks-payments`).
 
 ## Dashboard Routes
 All commerce models have dashboard views at `/dashboard/commerce/*`.

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

@@ -23,7 +23,7 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 - 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.
+- The Payment facade's neutral functions go through this driver; its Stripe-only functions and everything Stripe-level below return Stripe objects.
 
 ## Key Paths
 - Core package: `storage/framework/core/payments/src/`
@@ -44,87 +44,91 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 
 ## Payment Facade
 
-The `Payment` object aggregates all payment operations. Every method is also available as a standalone export.
+The `Payment` object aggregates the payment operations; every function is also a standalone export. It has two halves (`storage/framework/core/payments/src/payment.ts`):
+
+- **Provider-neutral** - through `paymentDriver()`, so they work on Stripe and Adyen alike. Money is `{ amount, currency }` in minor units; results are the driver's shapes.
+- **Stripe only** - Stripe's parameters and types, and `PaymentUnsupportedError` (naming the operation) under any other driver: `changeSubscription`, `updateCustomer`, `deleteCustomer`, `addPaymentMethod`, `setDefaultPaymentMethod`, `createSetupIntent`, `getInvoices`, `createInvoice`, `payInvoice`, `createProduct`, `getPrice`, `listProducts`, `createCoupon`, `createPromoCode`, `validatePromoCode`, `billingPortal`. The check is `assertStripeDriver(operation)`, shared with the billable trait.
+
+Something Stripe-specific the neutral half cannot express (a Connect destination charge's `payment_intent_data.transfer_data`, `prorate`/`invoice_now` on a cancellation, customer create params) goes through the `manage*` modules or the raw `stripe` client.
 
 ### Charges
 
 ```typescript
 import { Payment } from '@stacksjs/payments'
 
-// Create and confirm a charge (creates PaymentIntent with confirm: true)
-const intent = await Payment.charge(user, 2999, 'pm_xxx', { currency: 'usd' })
+// Charge a stored payment method, server side
+const result = await Payment.charge(user, { amount: 2999, currency: 'usd' }, 'pm_xxx', { reference: 'order-1' })
 
-// Create PaymentIntent without confirming (for client-side confirmation)
-const intent = await Payment.createPayment(user, 2999, { currency: 'usd' })
+// A payment the browser completes: result.clientConfirmation is a Stripe client secret or an Adyen session
+const pending = await Payment.createPayment(user, { amount: 2999, currency: 'usd' })
 
-// Refund -- partial
-const refund = await Payment.refund('pi_xxx', 1000)
-
-// Refund -- full (omit amount)
-const refund = await Payment.refund('pi_xxx')
+// Refund -- partial, or full when the amount is left out
+const partial = await Payment.refund('pi_xxx', { amount: { amount: 1000, currency: 'usd' } })
+const full = await Payment.refund('pi_xxx')
 ```
 
-`charge()` sets `confirmation_method: 'automatic'`, `confirm: true`, attaches the payment method, and delegates to `createPayment()`. If the user has a `stripe_id`, it is set as the customer on the PaymentIntent. Default currency is `'usd'`.
-
-The `manageCharge` module also exposes `findPayment(id)` which retrieves a PaymentIntent by ID, returning `null` on failure.
+`PaymentResult` has `id`, `status` (`succeeded`, `processing`, `requires_action`, `requires_payment_method`, `failed`, `canceled`), `amount`, `clientConfirmation`, `redirectUrl` and `raw` (the provider's object; strip it before a browser sees it). The `manageCharge` module is the Stripe-level API (`findPayment(id)` and the PaymentIntent params).
 
 ### Checkout Sessions
 
 ```typescript
-// One-time payment checkout
-const session = await Payment.checkout(user, [
-  { price: 'price_xxx', quantity: 1 }
-], { success_url: '/success', cancel_url: '/cancel' })
-
-// Subscription checkout
-const subSession = await Payment.subscriptionCheckout(user, 'price_xxx', {
-  success_url: '/success', cancel_url: '/cancel'
+const session = await Payment.checkout(user, {
+  mode: 'payment',
+  lines: [{ price: 'price_xxx', quantity: 1 }],
+  successUrl: 'https://app.example.com/success',
+  cancelUrl: 'https://app.example.com/cancel',
+})
+
+// One price in subscription mode
+const upgrade = await Payment.subscriptionCheckout(user, 'price_xxx', {
+  successUrl: 'https://app.example.com/welcome',
+  cancelUrl: 'https://app.example.com/pricing',
+  metadata: { user_id: String(user.id) },
 })
 ```
 
-Both methods require the user to have a `stripe_id` (throws if missing). `checkout()` sets `mode: 'payment'`, `subscriptionCheckout()` sets `mode: 'subscription'`.
+Send the payer to `session.url`. `trialDays` starts a subscription checkout with a trial. `reference` and `metadata` are copied onto the payment or subscription the checkout creates. Return URLs must be on the app's origin.
 
 ### Subscriptions
 
 ```typescript
-// Create -- uses lookup_key to resolve the Stripe Price
+// Subscribe to a price (a Stripe lookup key); `type` names it locally, `default` unless given
 const sub = await Payment.subscribe(user, 'premium-monthly')
 
-// Cancel at period end (prorate: true)
-const cancelled = await Payment.cancelSubscription('sub_xxx')
+// Cancel now
+await Payment.cancelSubscription('sub_xxx')
 
-// Cancel immediately (invoice_now: true, prorate: false)
-const cancelled = await Payment.cancelSubscription('sub_xxx', true)
+// Stop renewing: entitled until the period ends, recorded in the row's ends_at
+await Payment.cancelSubscription('sub_xxx', { atPeriodEnd: true })
 
-// Check active subscription
+// The provider's subscriptions, every status
+const all = await Payment.subscriptions(user)
+
+// Entitlement, from the local subscriptions table
 const hasActive = await Payment.hasActiveSubscription(user, 'default')
 
-// Change plan -- swaps the subscription item's price
+// Stripe only: swap the subscription item's price
 const changed = await Payment.changeSubscription(user, 'enterprise-monthly')
 ```
 
-`subscribe()` calls `managePrice.retrieveByLookupKey(lookupKey)` to find the price, then creates the subscription with `payment_behavior: 'allow_incomplete'` and `expand: ['latest_invoice.payment_intent']`. It stores the subscription in the `subscriptions` database table.
+`subscribe()` resolves the price by lookup key, creates the subscription with `payment_behavior: 'allow_incomplete'` and `expand: ['latest_invoice.confirmation_secret']` (an incomplete subscription's summary carries that as `clientConfirmation`), and stores it in `subscriptions`. Dates are stored as timestamps from the subscription item's `current_period_end`, where Stripe keeps it since API 2025-03-31.basil.
 
 `isValid()` returns `true` if the subscription status is `'active'` or `'trialing'`. `isIncomplete()` checks for `'incomplete'` status.
 
-`cancel()` calls `stripe.subscriptions.cancel()` and updates `provider_status` to `'canceled'` in the database.
-
-`update()` retrieves the active subscription via `user.activeSubscription()`, finds the new price by lookup key, updates the subscription item, and stores the updated price in the database.
+`cancelSubscription(id, immediately)` is gone: its `false` also cancelled at once, only with a proration. For Stripe's `prorate` / `invoice_now`, call `manageSubscription.cancel(id, params)`.
 
 ### Customers
 
 ```typescript
-// Get existing or create new Stripe customer
-const customer = await Payment.getOrCreateCustomer(user, { name: 'John' })
+// The provider's customer, created on first use: { id, email, name }
+const customer = await Payment.getOrCreateCustomer(user)
 
-// Update customer details in Stripe
+// Stripe only
 const updated = await Payment.updateCustomer(user, { name: 'Jane' })
-
-// Delete from Stripe and clear stripe_id on user model
 const deleted = await Payment.deleteCustomer(user)
 ```
 
-`createOrGetStripeUser()` checks `user.stripe_id` first. If the user has one, it retrieves the customer from Stripe. If the customer was deleted (404 or `deleted: true`), it creates a new one. On creation, it auto-fills `name` and `email` from the user model and calls `user.update({ stripe_id: customer.id })`.
+`createOrGetStripeUser()` (what the Stripe driver uses) checks `user.stripe_id` first. If the user has one, it retrieves the customer from Stripe. If the customer was deleted (404 or `deleted: true`), it creates a new one. On creation, it auto-fills `name` and `email` from the user model and calls `user.update({ stripe_id: customer.id })`. Pass Stripe customer create params through `manageCustomer.createOrGetStripeUser(user, params)`.
 
 Additional methods on `manageCustomer`:
 - `stripeId(user)` -- returns `user.stripe_id`
@@ -137,19 +141,20 @@ Additional methods on `manageCustomer`:
 ### Payment Methods
 
 ```typescript
-// Add a payment method to the customer
-const pm = await Payment.addPaymentMethod(user, 'pm_xxx')
-
-// Set as default (by Stripe payment method ID string)
-const customer = await Payment.setDefaultPaymentMethod(user, 'pm_xxx')
+// The provider's stored methods, default marked: { id, type, brand, last4, expMonth, expYear, isDefault }
+const methods = await Payment.paymentMethods(user)
 
-// Remove a payment method (by database record ID number)
-const removed = await Payment.removePaymentMethod(user, paymentMethodDbId)
+// Detach one, by the provider's id
+await Payment.removePaymentMethod(user, 'pm_xxx')
 
-// Create a setup intent for collecting payment methods
+// Stripe only
+const pm = await Payment.addPaymentMethod(user, 'pm_xxx')
+const customer = await Payment.setDefaultPaymentMethod(user, 'pm_xxx')
 const intent = await Payment.createSetupIntent(user, { payment_method_types: ['card'] })
 ```
 
+`removePaymentMethod()` used to take the local `payment_methods` row id as well; `managePaymentMethod.deletePaymentMethod(user, id)` still does.
+
 `addPaymentMethod()` accepts a string (Stripe PM ID) or Stripe.PaymentMethod object. It attaches the PM to the customer if not already attached, then stores it in the `payment_methods` table with `type`, `last_four`, `brand`, `exp_year`, `exp_month`, `user_id`, `provider_id`.
 
 `setUserDefaultPayment()` accepts a Stripe PM ID string, clears existing `is_default` flags, sets the new default in the database, and updates `invoice_settings.default_payment_method` on the Stripe customer.
@@ -549,9 +554,9 @@ The instance methods are exactly the keys of `createBillableMethods` in
 - Stripe API keys MUST be in `.env` as `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY` -- never hardcode them in config files
 - 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
+- `Payment.charge()` (Stripe driver) creates AND confirms the PaymentIntent in one step
 - `subscribe()` resolves the price via `lookup_key`, not a direct Stripe price ID
-- The facade's `Payment.removePaymentMethod()` takes a database record ID (number); the billable instance method `removePaymentMethod()` takes the provider's id (string)
+- `Payment.removePaymentMethod()` and the billable instance method `removePaymentMethod()` both take the provider's id (string); `managePaymentMethod.deletePaymentMethod()` takes the local row id (number)
 - `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/ide/vscode/package.json

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

package/project/bun-version

@@ -0,0 +1 @@
+1.4.2

package/resources/components/NativeComponents.test.ts

@@ -57,7 +57,7 @@ describe('Native components', () => {
   it('names the screen the back button returns to, and gives way to the title', () => {
     const bar = read('NativeNavBar')
     expect(bar).toContain('enterNavTrail(navTrail(), window.location.pathname + window.location.search)')
-    expect(bar).toContain('@container (max-width: 4.5rem)')
+    expect(bar).toContain('@container (max-width: 6.5rem)')
     expect(bar).toContain("useReactiveProp<boolean>('titleOnScroll', false)")
   })
 

package/resources/components/NativeNavBar.stx

@@ -171,7 +171,10 @@ function tapBack(event: MouseEvent): void {
   .native-nav-back:active { opacity: 0.55; }
   .native-nav-back-icon { flex-shrink: 0; width: 1.6rem; height: 1.6rem; }
   .native-nav-back-label { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-  @container (max-width: 4.5rem) {
+  /* Where the centred title leaves too little room for a word, the chevron
+     alone, as on iOS: at 4.5rem a long title still left "Wo…" for "Workout"
+     on a 402pt phone. 6.5rem fits a one-word name beside the chevron. */
+  @container (max-width: 6.5rem) {
     .native-nav-back-label { display: none; }
   }
 

package/resources/layouts/404.stx

@@ -26,9 +26,9 @@ const backgroundImage = props.backgroundImage || '/svgs/404.svg'
         Sorry, we couldn't find the page you're looking for.
       </p>
 
-      <!-- Same ember as the illustration beside it. White on #c14a15 is
-        4.93:1 and on the #9c3510 hover 7.17:1, so both states clear AA. -->
-      <a href="/" class="inline-block mt-10 px-4 py-2 text-white bg-[#c14a15] hover:bg-[#9c3510] rounded">
+      <!-- The Stacks cobalt, from the logo's plate. White on #1747c9 is
+        7.55:1 and on the #0f359d hover 10.41:1, so both states clear AA. -->
+      <a href="/" class="inline-block mt-10 px-4 py-2 text-white bg-[#1747c9] hover:bg-[#0f359d] rounded">
         Go back home
       </a>
     </main>

package/resources/views/errors/404.stx

@@ -24,7 +24,7 @@
       framework accent: it sits inches from the artwork, and a blue mark
       against a warm dusk scene reads as a mistake in any app's brand. The
       dark value is the same ramp's coral, from the scene's night variant. -->
-    <div class="my-6 h-1 w-14 bg-[#c14a15] dark:bg-[#ff8a4c] rounded-full"></div>
+    <div class="my-6 h-1 w-14 bg-[#1747c9] dark:bg-[#7ea3ff] rounded-full"></div>
 
     <h1 class="mb-2 font-semibold text-2xl text-neutral-950 dark:text-white">Page not found</h1>