@stacksjs/defaults 0.70.57 → 0.70.59

package/app/Listeners/README.md

@@ -0,0 +1,47 @@
+# What are Listeners
+
+Currently, only one specific kind of listener is allowed: `Console.ts`.
+
+## Get Started
+
+A simple example of how Console listeners work. _For a closer look, take a peak at the [Console.ts](./Console.ts) file._
+
+```ts
+export default function (cli: CLI) {
+  // Listen to the `inspire:three` command
+  cli.on('inspire:three', () => {
+    console.log('not yet implemented...')
+  })
+
+  // Listen to the default command
+  cli.on('inspire:!', () => {
+    // Do something
+  })
+
+  // Listen to unknown commands
+  cli.on('inspire:*', () => {
+    console.error('Invalid command: %s', cli.args.join(' '))
+    process.exit(1)
+  })
+}
+```
+
+## 🚜 Contributing
+
+Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](../../LICENSE.md) for more information.
+
+Made with 💙

package/app/Mail/OrderConfirmation.ts

@@ -0,0 +1,60 @@
+import { config } from '@stacksjs/config'
+import { mail, template } from '@stacksjs/email'
+
+export interface OrderConfirmationItem {
+  name: string
+  qty: number
+  lineTotal: number
+}
+
+export interface OrderConfirmationOptions {
+  to: string
+  orderId: number | string
+  customerName?: string
+  items: OrderConfirmationItem[]
+  subtotal: number
+  shipping: number
+  total: number
+  shippingAddress?: string
+  /** Absolute URL the receipt CTA should link to (e.g. `/orders/123`). */
+  orderUrl: string
+}
+
+/**
+ * Send the post-checkout receipt email.
+ *
+ * Uses `resources/emails/order-confirmation.stx` for the layout. The
+ * template renders the items table, totals, and a "View your order"
+ * CTA back to the storefront. Failures bubble up as rejected
+ * promises — the calling action should `.catch()` so a mailer
+ * outage doesn't fail the order.
+ */
+export async function sendOrderConfirmation(options: OrderConfirmationOptions): Promise<void> {
+  const appName = config.app.name || 'PetStore'
+  const fromAddress = config.email.from?.address || 'hello@stacksjs.com'
+
+  const { html, text } = await template('order-confirmation', {
+    variables: {
+      orderId: options.orderId,
+      orderUrl: options.orderUrl,
+      customerName: options.customerName || 'there',
+      items: options.items,
+      subtotal: options.subtotal,
+      shipping: options.shipping,
+      total: options.total,
+      shippingAddress: options.shippingAddress || '',
+      appName,
+    },
+    subject: `Your ${appName} order #${options.orderId} is confirmed`,
+  })
+
+  await mail.send({
+    to: [options.to],
+    from: { name: appName, address: fromAddress },
+    subject: `Your ${appName} order #${options.orderId} is confirmed`,
+    html,
+    text,
+  })
+}
+
+export default sendOrderConfirmation

package/app/Mail/SubscriptionConfirmation.ts

@@ -0,0 +1,41 @@
+import { config } from '@stacksjs/config'
+import { mail, template } from '@stacksjs/email'
+import { url } from '@stacksjs/router'
+
+export interface SubscriptionConfirmationOptions {
+  to: string
+  subscriberUuid: string
+}
+
+/**
+ * Send a subscription confirmation email with an unsubscribe link.
+ *
+ * Uses the `resources/emails/subscription-confirmation.stx` template.
+ */
+export async function sendSubscriptionConfirmation(options: SubscriptionConfirmationOptions): Promise<void> {
+  const { to, subscriberUuid } = options
+
+  const appName = config.app.name || 'Stacks'
+  const unsubscribeUrl = url('email.unsubscribe', { token: subscriberUuid })
+
+  const { html, text } = await template('subscription-confirmation', {
+    variables: {
+      email: to,
+      unsubscribeUrl,
+    },
+    subject: `Welcome to ${appName}!`,
+  })
+
+  await mail.send({
+    to: [to],
+    from: {
+      name: config.email.from?.name || appName,
+      address: config.email.from?.address || 'hello@stacksjs.com',
+    },
+    subject: `Welcome to ${appName}!`,
+    html,
+    text,
+  })
+}
+
+export default sendSubscriptionConfirmation

package/app/Middleware/Abilities.ts

@@ -0,0 +1,53 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Token Abilities Middleware
+ *
+ * This middleware checks if the current token has the required abilities/scopes.
+ * Must be used after the 'auth' middleware.
+ *
+ * Usage:
+ * - Add 'abilities:read,write' middleware to routes that require specific abilities
+ * - The abilities are passed as a comma-separated string after the colon
+ *
+ * Example:
+ * route.get('/admin', 'AdminAction').middleware('auth').middleware('abilities:admin')
+ * route.post('/posts', 'CreatePostAction').middleware('auth').middleware('abilities:posts:create')
+ */
+export default new Middleware({
+  name: 'abilities',
+  priority: 2, // Run after auth middleware
+
+  async handle(request) {
+    // Get the required abilities from middleware parameters
+    // This would be passed like 'abilities:read,write'
+    const requiredAbilities = request._middlewareParams?.abilities?.split(',') || []
+
+    if (requiredAbilities.length === 0) {
+      // No abilities required, pass through
+      return
+    }
+
+    // Get the current access token
+    const token = request._currentAccessToken
+
+    if (!token) {
+      throw new HttpError(401, 'Unauthenticated.')
+    }
+
+    const tokenAbilities: string[] = token.abilities || []
+
+    // Wildcard grants all permissions
+    if (tokenAbilities.includes('*')) {
+      return
+    }
+
+    // Check if token has ALL required abilities
+    for (const ability of requiredAbilities) {
+      if (!tokenAbilities.includes(ability.trim())) {
+        throw new HttpError(403, `Missing required ability: ${ability.trim()}`)
+      }
+    }
+  },
+})

package/app/Middleware/Api.ts

@@ -0,0 +1,26 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * API Middleware
+ *
+ * Validates that the request includes a valid API key or meets
+ * API-specific requirements (Accept header, rate limiting prefix, etc.).
+ *
+ * Usage:
+ * route.group({ middleware: 'api' }, () => {
+ *   route.get('/data', 'DataAction')
+ * })
+ */
+export default new Middleware({
+  name: 'api',
+  priority: 1,
+
+  async handle(request) {
+    // Ensure the request accepts JSON
+    const accept = request.headers.get('accept') || ''
+    if (!accept.includes('application/json') && !accept.includes('*/*')) {
+      throw new HttpError(406, 'This endpoint only serves JSON responses. Set Accept: application/json.')
+    }
+  },
+})

package/app/Middleware/Auth.ts

@@ -0,0 +1,59 @@
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Authentication Middleware
+ *
+ * Validates the bearer token from the request and ensures
+ * the user is authenticated before proceeding.
+ *
+ * Usage:
+ * route.get('/dashboard', 'DashboardAction').middleware('auth')
+ * route.group({ middleware: 'auth' }, () => { ... })
+ */
+function extractBearerToken(request: any): string | null {
+  if (typeof request.bearerToken === 'function') {
+    const t = request.bearerToken()
+    if (t)
+      return t
+  }
+  const authHeader
+    = (typeof request.header === 'function' && request.header('authorization'))
+    || request.headers?.get?.('authorization')
+    || request.headers?.get?.('Authorization')
+  if (typeof authHeader === 'string' && authHeader.startsWith('Bearer '))
+    return authHeader.substring(7)
+  return null
+}
+
+export default new Middleware({
+  name: 'Auth',
+  priority: 1,
+
+  async handle(request) {
+    const { Auth } = await import('@stacksjs/auth')
+
+    const bearerToken = extractBearerToken(request)
+
+    if (!bearerToken)
+      throw new HttpError(401, 'Unauthorized. No token provided.')
+
+    const isValid = await Auth.validateToken(bearerToken)
+    if (!isValid)
+      throw new HttpError(401, 'Unauthorized. Invalid token.')
+
+    const user = await Auth.getUserFromToken(bearerToken)
+    if (user) {
+      Auth.setUser(user)
+      ;request._authenticatedUser = user
+      // Do NOT overwrite `request.user` — `enhanceRequest` declared
+      // it as an async function (`user(): Promise<UserModel | undefined>`)
+      // and downstream action code reaches for `await request.user()`.
+      // Replacing the function with a User object made every caller
+      // throw "user is not a function" post-auth. Read from
+      // `_authenticatedUser` via `request.user()` instead — the helper
+      // prefers the stamped value before falling back to a token
+      // lookup. See stacksjs/stacks#1860 M-9.
+    }
+  },
+})

package/app/Middleware/Can.ts

@@ -0,0 +1,68 @@
+import { AuthorizationException, authorize } from '@stacksjs/auth'
+import { HttpError } from '@stacksjs/error-handling'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Authorization Gate Middleware
+ *
+ * This middleware checks if the current user is authorized to perform an action
+ * using the Gate system. Must be used after the 'auth' middleware.
+ *
+ * Usage:
+ * - Add 'can:ability' middleware to routes that require specific authorization
+ * - Add 'can:ability,modelParam' to authorize against a route model
+ *
+ * Examples:
+ * route.get('/settings', 'SettingsAction').middleware('auth').middleware('can:edit-settings')
+ * route.put('/posts/:post', 'UpdatePostAction').middleware('auth').middleware('can:update,post')
+ * route.delete('/posts/:post', 'DeletePostAction').middleware('auth').middleware('can:delete,post')
+ */
+export default new Middleware({
+  name: 'can',
+  priority: 3, // Run after auth and abilities middleware
+
+  async handle(request) {
+    // Get the ability and optional model parameter from middleware params
+    // Format: 'can:ability' or 'can:ability,modelParam'
+    const params = request._middlewareParams?.can?.split(',') || []
+
+    if (params.length === 0) {
+      // No ability specified, pass through (should this be an error?)
+      return
+    }
+
+    const ability = params[0]?.trim()
+    const modelParam = params[1]?.trim()
+
+    if (!ability) {
+      throw new HttpError(500, 'Authorization middleware requires an ability parameter')
+    }
+
+    // Get the authenticated user
+    const user = request.user || request._user || null
+
+    // Prepare arguments for the gate check
+    const args: any[] = []
+
+    // If a model parameter is specified, get it from route params
+    if (modelParam) {
+      const routeParams = request.params || {}
+      const model = routeParams[modelParam]
+
+      if (model) {
+        args.push(model)
+      }
+    }
+
+    // Perform the authorization check
+    try {
+      await authorize(ability, user, ...args)
+    }
+    catch (error) {
+      if (error instanceof AuthorizationException) {
+        throw new HttpError(error.status || 403, error.message)
+      }
+      throw error
+    }
+  },
+})

package/app/Middleware/Compress.ts

@@ -0,0 +1,213 @@
+import { brotliCompressSync, constants as zlibConstants } from 'node:zlib'
+import { Buffer } from 'node:buffer'
+import { Middleware } from '@stacksjs/router'
+
+/**
+ * Response Compression Middleware
+ *
+ * Compresses outgoing response bodies with brotli or gzip when the
+ * client advertises support via `Accept-Encoding`. The middleware
+ * runs at the *end* of the chain — by the time it executes, the
+ * action has already produced a response and stored it on the
+ * request via `_response`. (We intercept by patching the response
+ * after the chain ends — see implementation note below.)
+ *
+ * IMPORTANT — middleware shape mismatch:
+ *   The Stacks middleware runner only invokes `handle()` for
+ *   pre-action gating; it has no post-response hook. To compress
+ *   the *outgoing* response, this middleware therefore acts as a
+ *   marker — its real work is implemented as a *response wrapper*
+ *   that the router applies whenever the `compress` middleware is
+ *   attached (see Compress.applyToResponse below).
+ *
+ *   In practice, calling code uses the exported `applyCompression()`
+ *   helper directly:
+ *
+ * @example
+ * ```ts
+ * import { applyCompression } from '@stacksjs/middleware/Compress'
+ *
+ * const response = await action.handle(req)
+ * return applyCompression(req, response)
+ * ```
+ *
+ * Compression decisions:
+ *   - **Skip** if response already has `content-encoding` set.
+ *   - **Skip** if body smaller than 1 KB — overhead exceeds savings.
+ *   - **Skip** for already-compressed content types (image/*, video/*,
+ *     audio/*, application/zip, gzip, octet-stream).
+ *   - **Skip** SSE / WebSocket upgrades (`text/event-stream`).
+ *   - **Prefer brotli** when `br` is offered. Brotli typically
+ *     achieves ~20% better ratios than gzip on HTML/JSON/CSS/JS at
+ *     comparable CPU cost — well worth the swap when the client
+ *     supports it.
+ *   - **Fall back to gzip** for `gzip` clients (universal support).
+ *
+ * Headers always added when compressed:
+ *   - `Content-Encoding: br | gzip`
+ *   - `Vary: Accept-Encoding`  (so caches segment by encoding)
+ *
+ * `Content-Length` is rewritten to the compressed size.
+ */
+
+/** Body must exceed this threshold (bytes) to warrant compression. */
+const MIN_COMPRESS_BYTES = 1024
+
+/**
+ * Content-types that are already compressed (or untouchable). Re-running
+ * gzip/brotli over them gains nothing and wastes CPU.
+ *
+ * Pattern matched as `startsWith` against the lowercased content-type
+ * (sans parameters). Intentionally conservative — we'd rather miss a
+ * compression opportunity than corrupt a binary stream by double-encoding.
+ */
+const SKIP_CONTENT_TYPE_PREFIXES = [
+  'image/',
+  'video/',
+  'audio/',
+  'application/zip',
+  'application/gzip',
+  'application/x-gzip',
+  'application/x-bzip2',
+  'application/x-brotli',
+  'application/octet-stream',
+  // SSE / streaming pipelines must not be buffered for compression.
+  'text/event-stream',
+]
+
+/** Parse the q-weighted Accept-Encoding header into a preference set. */
+function pickEncoding(acceptEncoding: string | null): 'br' | 'gzip' | null {
+  if (!acceptEncoding) return null
+  // We don't fully implement q-value parsing — it's overkill for the
+  // brotli-vs-gzip choice. We just check for token presence.
+  const lc = acceptEncoding.toLowerCase()
+  // Brotli first because it ratios better on text — typical 20% smaller
+  // than gzip on HTML/JSON. CPU cost per byte is similar at default
+  // quality on Node's libbrotli.
+  if (lc.includes('br')) return 'br'
+  if (lc.includes('gzip')) return 'gzip'
+  return null
+}
+
+/** Heuristic: is this content type worth compressing? */
+function shouldCompressContentType(contentType: string | null): boolean {
+  if (!contentType) return true // unknown → assume text-like
+  const ct = (contentType.toLowerCase().split(';')[0] ?? '').trim()
+  for (const prefix of SKIP_CONTENT_TYPE_PREFIXES) {
+    if (ct.startsWith(prefix)) return false
+  }
+  return true
+}
+
+/**
+ * Compress a Response if (a) the client supports an encoding, (b) the
+ * body is large enough, and (c) the content type isn't already
+ * compressed. Returns the original Response unchanged when any of
+ * those conditions don't hold.
+ *
+ * Buffers the entire body in memory — appropriate for the typical
+ * JSON/HTML response sizes we're targeting (KB to single-digit MB).
+ * For multi-MB streamed responses, the middleware should be skipped
+ * (the SSE / event-stream check above handles the most common case).
+ *
+ * @example
+ * ```ts
+ * const response = Response.json({ users: [...] })
+ * return await applyCompression(request, response)
+ * // → response with `Content-Encoding: br` and a brotli-compressed body
+ * ```
+ */
+export async function applyCompression(request: Request, response: Response): Promise<Response> {
+  // Already encoded — leave it alone. Re-encoding would corrupt the
+  // body, and the client already knows what to expect.
+  if (response.headers.get('content-encoding')) return response
+
+  // No body or non-text content streams (SSE, etc.) — skip.
+  if (!response.body) return response
+
+  const contentType = response.headers.get('content-type')
+  if (!shouldCompressContentType(contentType)) return response
+
+  const encoding = pickEncoding(request.headers.get('accept-encoding'))
+  if (!encoding) return response
+
+  // Buffer the body. We need the full payload to compress synchronously
+  // (Bun.gzipSync / brotliCompressSync) AND to know the post-compression
+  // length for the Content-Length header.
+  const bodyBuf = Buffer.from(await response.arrayBuffer())
+  if (bodyBuf.byteLength < MIN_COMPRESS_BYTES) {
+    // Body too small — re-emit as a fresh Response since we already
+    // consumed `response.body` above.
+    return new Response(bodyBuf, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    })
+  }
+
+  let compressed: Buffer
+  if (encoding === 'br') {
+    // Brotli quality 5 is the sweet spot for dynamic responses:
+    // quality 11 (max) is ~10× slower for ~5% smaller output.
+    // 5 is also the Express compression-middleware default.
+    compressed = brotliCompressSync(bodyBuf, {
+      params: {
+        [zlibConstants.BROTLI_PARAM_QUALITY]: 5,
+      },
+    })
+  }
+  else {
+    // Bun.gzipSync is significantly faster than node:zlib.gzipSync
+    // for typical response sizes — used here in preference to
+    // node:zlib for the gzip path. Brotli has no Bun-native API yet
+    // (as of writing) so we use node:zlib for that branch.
+    compressed = Buffer.from(Bun.gzipSync(bodyBuf))
+  }
+
+  const newHeaders = new Headers(response.headers)
+  newHeaders.set('Content-Encoding', encoding)
+  newHeaders.set('Content-Length', String(compressed.byteLength))
+  // Caches MUST key on Accept-Encoding once we vary the body by it,
+  // otherwise a gzip-only proxy serves a brotli body to a gzip-only
+  // client and the response is undecodable.
+  const existingVary = newHeaders.get('Vary')
+  if (existingVary) {
+    if (!/\baccept-encoding\b/i.test(existingVary)) {
+      newHeaders.set('Vary', `${existingVary}, Accept-Encoding`)
+    }
+  }
+  else {
+    newHeaders.set('Vary', 'Accept-Encoding')
+  }
+
+  return new Response(compressed, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: newHeaders,
+  })
+}
+
+/**
+ * Marker middleware. The router inspects the route middleware list for
+ * `compress` and, when present, runs `applyCompression()` on the final
+ * response. The middleware's `handle` is intentionally a no-op:
+ * compression must run *after* the action, but the standard middleware
+ * pipeline runs *before* it.
+ *
+ * @example
+ * ```ts
+ * route.get('/api/large.json', 'Actions/LargePayload').middleware('compress')
+ * ```
+ */
+export default new Middleware({
+  name: 'compress',
+  // Run last in the pre-action chain so the marker stamp lands close
+  // to the action — the post-action wrapper picks it up by name.
+  priority: 100,
+
+  async handle(request) {
+    // Stamp the request so the post-response wrapper knows to compress.
+    // This is read by the router's response-finalization step.
+    ;request._compress = true
+  },
+})