@stacksjs/defaults 0.75.84 → 0.75.86

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

@@ -12,12 +12,13 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 
 ## Payment Drivers (provider-neutral)
 
-`paymentDriver()` (also `Payment.driver()`) returns the driver `config.payment.driver` selects: `stripe` (default) or `adyen`, or one added with `registerPaymentDriver(name, factory)`. Source: `storage/framework/core/payments/src/driver/`.
+`paymentDriver()` (also `Payment.driver()`) returns the driver `config.payment.driver` selects: `stripe` (default), `adyen` or `paddle`, or one added with `registerPaymentDriver(name, factory)`. Source: `storage/framework/core/payments/src/driver/`.
 
 - Money is `{ amount, currency }` in minor units; `assertMoney` refuses floats before a request leaves.
 - 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()`.
 - `checkout` copies `reference` and `metadata` onto the payment / subscription / setup intent it creates (Stripe: `payment_intent_data`, `subscription_data`, `setup_intent_data`), so their webhooks can be attributed. `allowPromotionCodes` and `automaticTax` are Stripe only; Adyen refuses them.
-- Unsupported operations throw `PaymentUnsupportedError` (driver + operation). Adyen has no catalog, subscriptions, invoices, coupons or portal.
+- Unsupported operations throw `PaymentUnsupportedError` (driver + operation). Adyen has no catalog, subscriptions, invoices, coupons or portal; Paddle has no server-side charge, server-side subscribe, setup checkout, promotion-code or trial option on a checkout, or separate cancel URL.
+- Paddle (`driver: 'paddle'`, Billing API v1, merchant of record): customers found or created by email; every payment is a transaction completed in Paddle.js (`clientConfirmation: { provider: 'paddle', transactionId, successUrl? }`), so `charge` and `subscribe` are unsupported and subscriptions start at `checkout` in `subscription` mode with catalog prices; refunds are adjustments Paddle reviews (`pending`, settled by `adjustment.updated`; a refund's event id is the adjustment's, so a created-and-updated approval counts once); webhooks `Paddle-Signature` = HMAC-SHA256 hex of `<ts>:<raw body>` under the secret, 5 s tolerance. Paddle has no hosted page: `GET /payments/checkout` (mounted while the driver is `paddle`) is the default payment link page, reading `stacks_success_url` from the transaction for Paddle.js. Env: `PADDLE_API_KEY`, `PADDLE_ENVIRONMENT`, `PADDLE_CLIENT_TOKEN`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TAX_CATEGORY`.
 - 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.

package/bootstrap.ts

@@ -21,7 +21,7 @@
  * @see storage/framework/core/router/src/route-loader.ts:loadFrameworkRoutes
  */
 
-import { feature } from '@stacksjs/config'
+import { config, feature } from '@stacksjs/config'
 import { frameworkPath } from '@stacksjs/path'
 import { bundleMounts, DEFAULT_ROUTE_BUNDLE_FEATURES, route } from '@stacksjs/router'
 import MaintenanceMiddleware from './app/Middleware/Maintenance'
@@ -160,6 +160,15 @@ if (mounts('payments')) {
   await route.register(frameworkPath('defaults/routes/payments.ts'))
 }
 
+// The page a Paddle payment link opens: Paddle has no hosted checkout, so
+// its default payment link has to point at a page of the app's that loads
+// Paddle.js. Mounted while the app pays through Paddle, as part of the
+// `payments` bundle when the app names its bundles.
+const paymentDriverName = (config as { payment?: { driver?: string } }).payment?.driver
+if (paymentDriverName === 'paddle' && (selection?.explicit ? selection.bundles.has('payments') : true)) {
+  await route.register(frameworkPath('defaults/routes/paddle.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.84",
+  "version": "0.75.86",
   "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.84",
+  "version": "0.75.86",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,8 +55,8 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "^0.75.84",
-    "@stacksjs/sanitizer": "^0.2.378",
+    "@stacksjs/mobile": "^0.75.86",
+    "@stacksjs/sanitizer": "^0.2.384",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "ts-qr-codes": "^0.1.8"

package/resources/components/NativeComponents.test.ts

@@ -20,6 +20,12 @@ describe('Native components', () => {
     expect(item).toContain('draggable="false"')
   })
 
+  it('switches tabs instantly: prefetched, and without the cross-fade', () => {
+    const item = read('NativeTabItem')
+    expect(item).toContain('data-stx-prefetch="eager"')
+    expect(item).toContain('data-stx-transition="none"')
+  })
+
   it('centres each tab in the bar rather than against its top border', () => {
     // stx wraps each NativeTabItem in a scope box; the box stretched while
     // the link inside kept its own height, so icons sat on the border.

package/resources/components/NativeTabItem.stx

@@ -22,7 +22,9 @@ const hasBadge = badge !== '' && badge !== 0 && badge !== '0'
      long press, and a draggable link starts a native drag instead of
      navigating. `data-stx-prefetch="eager"`: every tab's page is fetched once
      the current one is idle, so switching tabs is served from the router's
-     cache, as instant as a native tab bar. -->
+     cache, as instant as a native tab bar. `data-stx-transition="none"`: and
+     swapped without the router's cross-fade, which iOS never draws between
+     tabs (it read as a quarter-second lag on every tap). -->
 <StxLink
   to="{{ href }}"
   aria-label="{{ label }}"
@@ -31,6 +33,7 @@ const hasBadge = badge !== '' && badge !== 0 && badge !== '0'
   class="native-tab-item"
   draggable="false"
   data-stx-prefetch="eager"
+  data-stx-transition="none"
 >
   <span class="native-tab-glyph">
     <i aria-hidden="true" class="{{ icon }} native-tab-icon"></i>

package/resources/emails/notification.stx

@@ -0,0 +1,44 @@
+<script server>
+// What notify() sends by email: the notification's subject as the heading,
+// its plain-text body as paragraphs (blank lines between them, single line
+// breaks kept, addresses as links) and, when the notification names one, a
+// button to where it happened. Same <EmailLayout> as the other prebaked
+// mailers (stacksjs/stacks#1901); an app's own resources/emails/notification
+// wins over this one.
+const appName = props.appName || 'Stacks'
+const primaryColor = props.primaryColor || '#3451b2'
+const subject = props.subject || appName
+const paragraphs = Array.isArray(props.paragraphs) ? props.paragraphs : []
+const actionUrl = props.actionUrl || ''
+const actionLabel = props.actionLabel || 'Open'
+const preheader = props.preheader || ''
+const year = props.year || new Date().getFullYear()
+</script>
+
+<EmailLayout title="{{ subject }}" preheader="{{ preheader }}">
+  <template #header>
+    <tr>
+      <td style="background-color:{{ primaryColor }};padding:30px 40px;text-align:center;">
+        <h1 style="margin:0;color:#ffffff;font-size:24px;font-weight:600;">{{ appName }}</h1>
+      </td>
+    </tr>
+  </template>
+
+  <EmailText size="heading">{{ subject }}</EmailText>
+  @foreach(paragraphs as parts)
+    <EmailText>@foreach(parts as part)@if(part.br)<br>@elseif(part.url)<a href="{{ part.url }}" style="color:{{ primaryColor }};text-decoration:underline;word-break:break-all;">{{ part.url }}</a>@else{{ part.text }}@endif@endforeach</EmailText>
+  @endforeach
+
+  @if(actionUrl)
+    <EmailButton href="{{ actionUrl }}" bg="{{ primaryColor }}">{{ actionLabel }}</EmailButton>
+  @endif
+
+  <template #footer>
+    <tr>
+      <td style="padding:20px 40px;background-color:#f9fafb;border-top:1px solid #e5e7eb;">
+        <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">This is an automated message from {{ appName }}. Please do not reply to this email.</p>
+        <p style="margin:10px 0 0 0;color:#9ca3af;font-size:11px;text-align:center;">&copy; {{ year }} {{ appName }}. All rights reserved.</p>
+      </td>
+    </tr>
+  </template>
+</EmailLayout>

package/routes/paddle.ts

@@ -0,0 +1,21 @@
+import { route } from '@stacksjs/router'
+
+/**
+ * The page a Paddle payment link opens (stacksjs/stacks#665). Set Paddle's
+ * default payment link (Checkout > Checkout settings) to
+ * `https://<your app>/payments/checkout`: Paddle appends the transaction as
+ * `?_ptxn=`, and this page opens Paddle.js on it with the success page
+ * `Payment.checkout()` stored on the transaction.
+ *
+ * Mounted while `config.payment.driver` is `paddle`. An app route at the same
+ * path registers first and wins.
+ */
+route.get('/payments/checkout', async (request) => {
+  const { servePaddleCheckout } = await import('@stacksjs/payments')
+  return servePaddleCheckout(request)
+})
+
+route.get('/payments/checkout.js', async () => {
+  const { servePaddleCheckoutScript } = await import('@stacksjs/payments')
+  return servePaddleCheckoutScript()
+})

package/routes/payments.ts

@@ -6,7 +6,9 @@ import { route } from '@stacksjs/router'
  *
  * 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.
+ * its HMAC key in `ADYEN_HMAC_KEY`, or a Paddle notification destination with
+ * its secret key in `PADDLE_WEBHOOK_SECRET`, 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.
  *