@stacksjs/defaults 0.70.57 → 0.70.59

package/app/Actions/Storefront/UpdateCartItemAction.ts

@@ -0,0 +1,83 @@
+import { Action } from '@stacksjs/actions'
+import { db } from '@stacksjs/database'
+import { response } from '@stacksjs/router'
+import { readCartCookie } from '../../Storefront/CartCookie'
+
+const CART_COOKIE = 'stacks_cart'
+
+/**
+ * Change the quantity of a cart line, or remove it (quantity=0).
+ * Scoped by the caller's cart cookie so one shopper can't poke at
+ * another's cart by guessing item ids.
+ */
+export default new Action({
+  name: 'UpdateCartItemAction',
+  description: 'Update or remove a cart item by id, scoped to caller cookie.',
+  method: 'POST',
+
+  async handle(request: any) {
+    const itemId = Number(request.get('item_id') ?? 0)
+    const quantity = Math.max(0, Math.min(99, Number(request.get('quantity') ?? 1)))
+
+    // HMAC-verified cookie. Tampered tokens look like "no cookie" so
+    // an attacker can't probe for the existence of arbitrary carts.
+    const token = readCartCookie(request, CART_COOKIE)
+    if (!token)
+      return response.json({ error: 'No active cart' }, { status: 400 })
+
+    const cart = await (db as any)
+      .selectFrom('carts')
+      .where('session_token', '=', token)
+      .selectAll()
+      .executeTakeFirst()
+
+    if (!cart)
+      return response.json({ error: 'Cart not found' }, { status: 404 })
+
+    const item = await (db as any)
+      .selectFrom('cart_items')
+      .where('id', '=', itemId)
+      .where('cart_id', '=', cart.id)
+      .selectAll()
+      .executeTakeFirst()
+
+    if (!item)
+      return response.json({ error: 'Item not in your cart' }, { status: 404 })
+
+    if (quantity === 0) {
+      await (db as any).deleteFrom('cart_items').where('id', '=', item.id).execute()
+    }
+    else {
+      await (db as any)
+        .updateTable('cart_items')
+        .set({
+          quantity,
+          total_price: quantity * Number(item.unit_price),
+        })
+        .where('id', '=', item.id)
+        .execute()
+    }
+
+    const items = await (db as any)
+      .selectFrom('cart_items')
+      .where('cart_id', '=', cart.id)
+      .selectAll()
+      .execute()
+
+    const totalItems = items.reduce((s: number, i: any) => s + Number(i.quantity), 0)
+    const subtotal = items.reduce((s: number, i: any) => s + Number(i.total_price || 0), 0)
+
+    await (db as any)
+      .updateTable('carts')
+      .set({ total_items: totalItems, subtotal, total: subtotal })
+      .where('id', '=', cart.id)
+      .execute()
+
+    const wantsHtml = (request.headers?.get?.('accept') || '').includes('text/html')
+    const xhr = request.headers?.get?.('x-requested-with') === 'XMLHttpRequest'
+    if (wantsHtml && !xhr)
+      return response.redirect('/cart')
+
+    return response.json({ ok: true, total_items: totalItems, subtotal })
+  },
+})

package/app/Actions/Storefront/_shipping.ts

@@ -0,0 +1,64 @@
+/**
+ * Shipping rules used by both the cart view and the place-order action.
+ *
+ * Centralized so a copy in cart.stx and another in PlaceOrderAction.ts
+ * can't drift — when finance changes "free shipping over $40" to
+ * "free over $50" you don't want one of the two surfaces (the price
+ * the shopper sees vs. the total they're charged) to lag the other.
+ *
+ * Override per-app by setting `STOREFRONT_FREE_SHIPPING_THRESHOLD` and
+ * `STOREFRONT_FLAT_SHIPPING` in the environment, or by editing this
+ * file in the application's own `app/Actions/Storefront/_shipping.ts`
+ * if the rule needs more logic than two numbers (per-region, weight-
+ * based, etc.).
+ */
+
+const DEFAULT_FREE_SHIPPING_THRESHOLD = 40
+const DEFAULT_FLAT_SHIPPING = 5
+
+export const FREE_SHIPPING_THRESHOLD = numFromEnv(
+  'STOREFRONT_FREE_SHIPPING_THRESHOLD',
+  DEFAULT_FREE_SHIPPING_THRESHOLD,
+)
+
+export const FLAT_SHIPPING = numFromEnv(
+  'STOREFRONT_FLAT_SHIPPING',
+  DEFAULT_FLAT_SHIPPING,
+)
+
+/**
+ * Compute the shipping fee for a given subtotal. Empty cart → 0,
+ * otherwise free at/above the threshold, otherwise the flat rate.
+ */
+export function shippingFor(subtotal: number): number {
+  if (!Number.isFinite(subtotal) || subtotal <= 0)
+    return 0
+  if (subtotal >= FREE_SHIPPING_THRESHOLD)
+    return 0
+  return FLAT_SHIPPING
+}
+
+/**
+ * Return `{ subtotal, shipping, total }` for a given subtotal — the
+ * shape both the cart view and the place-order action want, with the
+ * shipping rule applied consistently.
+ */
+export function totalsFor(subtotal: number): {
+  subtotal: number
+  shipping: number
+  total: number
+} {
+  const sub = Number.isFinite(subtotal) ? subtotal : 0
+  const shipping = shippingFor(sub)
+  return { subtotal: sub, shipping, total: sub + shipping }
+}
+
+function numFromEnv(name: string, fallback: number): number {
+  const raw = (typeof process !== 'undefined' && process.env)
+    ? process.env[name]
+    : undefined
+  if (raw === undefined || raw === '')
+    return fallback
+  const parsed = Number(raw)
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback
+}

package/app/Actions/SubscriberEmailAction.ts

@@ -0,0 +1,60 @@
+import { Action } from '@stacksjs/actions'
+import { isUniqueViolation, Subscriber, SubscriberEmail } from '@stacksjs/orm'
+import { rateLimit } from '@stacksjs/router'
+import { sendSubscriptionConfirmation } from '../Mail/SubscriptionConfirmation'
+
+export default new Action({
+  name: 'SubscriberEmailAction',
+  description: 'Save emails from subscribe page and send confirmation email',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    // Per-IP throttle. The endpoint is unauthenticated and skipCsrf'd so
+    // bots will find it; without this they can flood the subscribers
+    // table within minutes and burn through SES/SendGrid quota. 10/min
+    // is generous for a real human filling the same form repeatedly.
+    await rateLimit('email-subscribe', 10).per('minute')
+
+    const email = request.get('email')
+    const source = request.get('source') || 'homepage'
+
+    if (!email || !email.includes('@')) {
+      return { success: false, message: 'A valid email is required' }
+    }
+
+    // Check if subscriber already exists
+    const existingSubscriber = await Subscriber.where('email', email).first()
+    if (existingSubscriber) {
+      return { success: true, message: 'Already subscribed' }
+    }
+
+    // Create subscriber record. The check above is a fast path; two requests
+    // for the same email can still both pass it and race into the
+    // subscribers.email unique index (#1957). Treat the loser's unique
+    // violation as the same "already subscribed" success — the response
+    // contract (and its enumeration semantics) is unchanged.
+    let subscriber: any
+    try {
+      subscriber = await Subscriber.create({ email, status: 'subscribed', source })
+    }
+    catch (err) {
+      if (isUniqueViolation(err))
+        return { success: true, message: 'Already subscribed' }
+      throw err
+    }
+
+    // Log the email event
+    await SubscriberEmail.create({ email, source })
+
+    // Send subscription confirmation email asynchronously (do not block the response)
+    sendSubscriptionConfirmation({
+      to: email,
+      subscriberUuid: subscriber.uuid,
+    }).catch((err: unknown) => {
+      const message = err instanceof Error ? err.message : String(err)
+      console.error(`Failed to send confirmation email to ${email}:`, message)
+    })
+
+    return { success: true, subscriber }
+  },
+})

package/app/Actions/TestErrorAction.ts

@@ -0,0 +1,163 @@
+/**
+ * Test Error Action
+ *
+ * Browse /test-error for a visual index of every error scenario.
+ * Append ?type=<scenario> to trigger a specific exception.
+ */
+
+import type { EnhancedRequest } from 'bun-router'
+import { dirname, join } from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+class DatabaseError extends Error {
+  constructor(message: string, public query?: string) {
+    super(message)
+    this.name = 'DatabaseError'
+  }
+}
+
+class ValidationError extends Error {
+  constructor(message: string, public field?: string) {
+    super(message)
+    this.name = 'ValidationError'
+  }
+}
+
+const ERROR_SCENARIOS = [
+  {
+    type: 'database',
+    title: 'DatabaseError',
+    description: 'Deep call stack with a missing-table SQL error — shows code snippets and collapsed framework frames.',
+    status: 500,
+  },
+  {
+    type: 'validation',
+    title: 'ValidationError',
+    description: '422-style validation failure with a field hint.',
+    status: 422,
+  },
+  {
+    type: 'auth',
+    title: 'AuthenticationError',
+    description: 'Unauthorized access with an expired token message.',
+    status: 401,
+  },
+  {
+    type: 'notfound',
+    title: 'NotFoundError',
+    description: 'Missing resource — useful for testing 404-style traces.',
+    status: 404,
+  },
+  {
+    type: 'generic',
+    title: 'Error',
+    description: 'Plain unhandled exception with a minimal stack.',
+    status: 500,
+  },
+] as const
+
+function innerDatabaseCall(): never {
+  throw new DatabaseError(
+    `SQLSTATE[42S02]: Base table or view not found: 1146 Table 'app.nonexistent_table' doesn't exist`,
+    `SELECT * FROM nonexistent_table WHERE id = 1`,
+  )
+}
+
+function queryBuilder() {
+  return innerDatabaseCall()
+}
+
+function repository() {
+  return queryBuilder()
+}
+
+function service() {
+  return repository()
+}
+
+async function renderPreviewIndex(requestUrl: string): Promise<Response> {
+  const base = new URL(requestUrl)
+  base.search = ''
+
+  const scenarios = ERROR_SCENARIOS.map(s => ({
+    ...s,
+    href: `${base.pathname}?type=${s.type}`,
+  }))
+
+  const viewsRoot = join(dirname(fileURLToPath(import.meta.url)), '../../resources/views/errors')
+  const { renderTemplate } = await import('@stacksjs/stx')
+  const body = await renderTemplate(join(viewsRoot, 'tester.stx'), {
+    context: { scenarios },
+    injectCSS: true,
+    templateOnly: true,
+    processClientScripts: false,
+  })
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Error Page Tester — Stacks</title>
+</head>
+<body class="min-h-dvh antialiased font-sans dark:text-white bg-neutral-50 dark:bg-neutral-900 scheme-light-dark">
+  ${body}
+</body>
+</html>`
+
+  return new Response(html, {
+    status: 200,
+    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+  })
+}
+
+export default {
+  name: 'Test Error Action',
+  description: 'Demonstrates the Laravel-style error page',
+
+  async handle(request: EnhancedRequest): Promise<Response> {
+    // Production short-circuits to 404 so even an accidental or userland
+    // re-registration can't expose the exception generator in prod —
+    // mirrors the mailable-preview guard in defaults/routes/core.ts
+    // (stacksjs/stacks#1900 A3; added for #1955). Production-only (not
+    // the registration gate's local-env allowlist) so a deliberate
+    // re-registration in staging still works.
+    const env = (process.env.APP_ENV ?? process.env.NODE_ENV ?? '').toLowerCase()
+    if (env === 'production')
+      return new Response('Not Found', { status: 404 })
+
+    const url = new URL(request.url)
+    const errorType = url.searchParams.get('type')
+
+    if (!errorType) {
+      return await renderPreviewIndex(request.url)
+    }
+
+    switch (errorType) {
+      case 'validation':
+        throw new ValidationError('The email field must be a valid email address.', 'email')
+
+      case 'auth': {
+        const authError = new Error('Unauthorized: Invalid or expired authentication token.')
+        authError.name = 'AuthenticationError'
+        throw authError
+      }
+
+      case 'notfound': {
+        const notFoundError = new Error('Resource not found: User with ID 42 does not exist.')
+        notFoundError.name = 'NotFoundError'
+        throw notFoundError
+      }
+
+      case 'generic':
+        throw new Error('Something went wrong while processing your request.')
+
+      case 'database':
+      default:
+        service()
+    }
+
+    return Response.json({ message: 'No error occurred' })
+  },
+}

package/app/Actions/UnsubscribeAction.ts

@@ -0,0 +1,107 @@
+import { Action } from '@stacksjs/actions'
+import { EmailList, EmailListSubscriber, Subscriber } from '@stacksjs/orm'
+
+export default new Action({
+  name: 'UnsubscribeAction',
+  description: 'Handle email unsubscription via token (subscriber UUID or per-list pivot UUID)',
+  method: 'GET',
+
+  async handle(request: RequestInstance) {
+    const token = request.get('token')
+
+    if (!token) {
+      return new Response(unsubscribePage('Missing token', 'The unsubscribe link is invalid.', false), {
+        headers: { 'Content-Type': 'text/html' },
+      })
+    }
+
+    // Two flavors of token can land here:
+    //   1. EmailListSubscriber.uuid → per-list (newsletter) unsubscribe.
+    //      We only flip this one row; other lists + transactional mail
+    //      keep flowing.
+    //   2. Subscriber.uuid → legacy global unsubscribe (drops every list).
+    //
+    // We try the per-list pivot first because it's the safer scope —
+    // if a recipient kept an old link around, we'd rather honor it as
+    // a single-list unsubscribe than nuke their entire subscription.
+    // UUIDs are universally unique so the lookups never collide.
+    try {
+      const pivot = await EmailListSubscriber.where('uuid', token).first()
+
+      if (pivot) {
+        const subscriber = await Subscriber.find(pivot.subscriber_id)
+        const list = await EmailList.find(pivot.email_list_id)
+        const listName = list?.name ?? 'this list'
+
+        if (pivot.status === 'unsubscribed') {
+          return new Response(unsubscribePage('Already unsubscribed', `${subscriber?.email ?? 'You'} has already been unsubscribed from ${listName}.`, true), {
+            headers: { 'Content-Type': 'text/html' },
+          })
+        }
+
+        await pivot.update({
+          status: 'unsubscribed',
+          unsubscribed_at: new Date().toISOString(),
+        })
+
+        return new Response(unsubscribePage('Unsubscribed', `${subscriber?.email ?? 'You'} has been successfully unsubscribed from ${listName}. You will no longer receive emails from this list.`, true), {
+          headers: { 'Content-Type': 'text/html' },
+        })
+      }
+
+      const subscriber = await Subscriber.where('uuid', token).first()
+
+      if (!subscriber) {
+        return new Response(unsubscribePage('Invalid link', 'This unsubscribe link is invalid or has already been used.', false), {
+          headers: { 'Content-Type': 'text/html' },
+        })
+      }
+
+      if (subscriber.status === 'unsubscribed') {
+        return new Response(unsubscribePage('Already unsubscribed', `${subscriber.email} has already been unsubscribed.`, true), {
+          headers: { 'Content-Type': 'text/html' },
+        })
+      }
+
+      await subscriber.update({
+        status: 'unsubscribed',
+        unsubscribed_at: new Date().toISOString(),
+      })
+
+      return new Response(unsubscribePage('Unsubscribed', `${subscriber.email} has been successfully unsubscribed. You will no longer receive emails from us.`, true), {
+        headers: { 'Content-Type': 'text/html' },
+      })
+    }
+    catch (error: unknown) {
+      const message = error instanceof Error ? error.message : String(error)
+      console.error('Unsubscribe error:', message)
+      return new Response(unsubscribePage('Error', 'Something went wrong. Please try again later.', false), {
+        headers: { 'Content-Type': 'text/html' },
+      })
+    }
+  },
+})
+
+function unsubscribePage(title: string, message: string, success: boolean): string {
+  const icon = success ? '✓' : '✗'
+  const iconColor = success ? '#22c55e' : '#ef4444'
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background-color: #0e0e0e; color: #d4d4d4; display: flex; align-items: center; justify-content: center; min-height: 100vh;">
+  <div style="max-width: 480px; margin: 0 auto; padding: 40px 20px; text-align: center;">
+    <div style="width: 64px; height: 64px; border-radius: 50%; background-color: ${iconColor}20; display: inline-flex; align-items: center; justify-content: center; margin-bottom: 24px;">
+      <span style="font-size: 28px; color: ${iconColor};">${icon}</span>
+    </div>
+    <h1 style="color: #ececec; font-size: 24px; font-weight: 600; margin: 0 0 12px;">${title}</h1>
+    <p style="color: #a0a0a0; font-size: 16px; line-height: 1.6; margin: 0 0 32px;">${message}</p>
+    <a href="https://stacksjs.com" style="color: #888; font-size: 13px; text-decoration: none;">stacksjs.com</a>
+  </div>
+</body>
+</html>`
+}

package/app/Actions/UploadTestAction.ts

@@ -0,0 +1,57 @@
+import { Action } from '@stacksjs/actions'
+import { Storage } from '@stacksjs/storage'
+
+interface Request {
+  file: (key: string) => any
+  hasFile: (key: string) => boolean
+  get: (key: string, defaultValue?: any) => any
+}
+
+export default new Action({
+  name: 'Upload Test',
+  description: 'Test file upload to public directory',
+
+  async handle(request?: Request) {
+    if (!request) {
+      return { success: false, message: 'No request provided' }
+    }
+
+    // Check if file was uploaded
+    if (!request.hasFile('file')) {
+      return { success: false, message: 'No file uploaded' }
+    }
+
+    const file = request.file('file')
+    if (!file) {
+      return { success: false, message: 'File is empty' }
+    }
+
+    // Get optional directory from request
+    const directory = request.get('directory', 'uploads')
+
+    try {
+      // Store to public directory using UploadedFile methods
+      const path = await file.storePublicly(directory)
+
+      return {
+        success: true,
+        message: 'File uploaded successfully',
+        data: {
+          path,
+          name: file.name,
+          size: file.getSize(),
+          mimeType: file.mimeType,
+          extension: file.extension,
+          isImage: file.isImage(),
+          url: `/storage/${path}`,
+        },
+      }
+    }
+    catch (error) {
+      return {
+        success: false,
+        message: error instanceof Error ? error.message : 'Upload failed',
+      }
+    }
+  },
+})

package/app/Broadcasts/OrderShipped.ts

@@ -0,0 +1,57 @@
+import type { RealtimeInstance } from '@stacksjs/types'
+import { channel } from '@stacksjs/realtime'
+
+interface OrderData {
+  orderId: string
+  userId: string
+  products: Array<{
+    id: string
+    name: string
+    quantity: number
+  }>
+  totalAmount: number
+  shippingAddress: {
+    street: string
+    city: string
+    country: string
+    postalCode: string
+  }
+  shippedAt?: string
+}
+
+export default {
+  /**
+   * The event name.
+   */
+  event: 'OrderShipped',
+
+  /**
+   * Handle the broadcast event.
+   * This method is called when the event is triggered.
+   */
+  async handle(data: OrderData): Promise<void> {
+    await channel(`orders.${data.orderId}`).private(this.event, data)
+  },
+} satisfies RealtimeInstance
+
+// Usage example:
+/*
+const orderData = {
+  orderId: '12345',
+  userId: 'user_123',
+  products: [
+    { id: 'prod_1', name: 'Widget', quantity: 2 },
+    { id: 'prod_2', name: 'Gadget', quantity: 1 },
+  ],
+  totalAmount: 99.99,
+  shippingAddress: {
+    street: '123 Main St',
+    city: 'Anytown',
+    country: 'USA',
+    postalCode: '12345',
+  },
+}
+
+// Trigger the broadcast
+await broadcast('OrderShipped', orderData)
+*/

package/app/Commands/Inspire.ts

@@ -0,0 +1,57 @@
+import type { CLI } from '@stacksjs/types'
+// triggered via `$your-cli inspire` and `buddy inspire`
+import process from 'node:process'
+import { log, quotes } from '@stacksjs/cli'
+import { ExitCode } from '@stacksjs/types'
+
+// for enhanced type-safety & autocompletion,
+// you may want to define the options' interface
+interface InspireOptions {
+  two: boolean
+}
+
+export default function (cli: CLI) {
+  cli
+    .command('inspire', 'Inspire yourself with a random quote')
+    .option('--two, -t', 'Inspire yourself with two random quotes', {
+      default: false,
+    })
+    .alias('insp')
+    .action((options: InspireOptions) => {
+      try {
+        if (options.two) {
+          const randomQuotes = quotes.random(2)
+          randomQuotes.toArray().forEach((quote: string, index: number) => {
+            console.log(`${index + 1}. ${quote}`)
+          })
+        }
+        else {
+          const quote = quotes.random(1).first()
+          console.log(`\n"${quote}"\n`)
+        }
+
+        console.log('✓ Have a great day!')
+      }
+      catch (error) {
+        console.error('Error:', error)
+      }
+      process.exit(ExitCode.Success)
+    })
+
+  cli.command('inspire:two', 'Inspire yourself with two random quotes').action(() => {
+    console.log('')
+    quotes.random(2).toArray().forEach((quote: string, index: number) => {
+      console.log(`${index + 1}. "${quote}"`)
+    })
+    console.log('')
+    console.log('✓ Have a great day!')
+    process.exit(ExitCode.Success)
+  })
+
+  cli.on('inspire:*', () => {
+    log.error('Invalid command: %s\nSee --help for a list of available commands.', cli.args.join(' '))
+    process.exit(1)
+  })
+
+  return cli // TODO: this may not be needed
+}