@stacksjs/defaults 0.70.228 → 0.70.230

package/app/Actions/Dashboard/Email/InboxActivityAction.ts

@@ -0,0 +1,250 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { db } from '@stacksjs/database'
+import { emailSDK } from '@stacksjs/email'
+import { request as routerRequest, response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
+
+const RANGES = ['day', 'week', 'month', 'year'] as const
+type ActivityRange = typeof RANGES[number]
+
+interface DeliveryRow {
+  id: number
+  recipient: string
+  subject: string | null
+  status: string
+  sent_at: string | null
+  created_at: string | null
+}
+
+interface ActivityItem {
+  id: string
+  direction: 'received' | 'sent'
+  subject: string
+  correspondent: string
+  occurred_at: string
+  status: string
+}
+
+interface Bucket {
+  key: string
+  label: string
+  start: Date
+  end: Date
+}
+
+function queryValue(request: RequestInstance, key: string): string {
+  const query = ((routerRequest as any).query || {}) as Record<string, string | string[] | undefined>
+  const value = query[key]
+  return String((Array.isArray(value) ? value[0] : value) || request.get(key) || '').trim()
+}
+
+function startOfHour(date: Date): Date {
+  const result = new Date(date)
+  result.setMinutes(0, 0, 0)
+  return result
+}
+
+function startOfDay(date: Date): Date {
+  const result = new Date(date)
+  result.setHours(0, 0, 0, 0)
+  return result
+}
+
+function startOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), 1)
+}
+
+function addHours(date: Date, amount: number): Date {
+  const result = new Date(date)
+  result.setHours(result.getHours() + amount)
+  return result
+}
+
+function addDays(date: Date, amount: number): Date {
+  const result = new Date(date)
+  result.setDate(result.getDate() + amount)
+  return result
+}
+
+function addMonths(date: Date, amount: number): Date {
+  return new Date(date.getFullYear(), date.getMonth() + amount, 1)
+}
+
+function buildBuckets(range: ActivityRange, now: Date): Bucket[] {
+  if (range === 'day') {
+    const end = addHours(startOfHour(now), 1)
+    const start = addHours(end, -24)
+    return Array.from({ length: 24 }, (_, index) => {
+      const bucketStart = addHours(start, index)
+      return {
+        key: bucketStart.toISOString(),
+        label: bucketStart.toLocaleTimeString([], { hour: 'numeric' }),
+        start: bucketStart,
+        end: addHours(bucketStart, 1),
+      }
+    })
+  }
+
+  if (range === 'year') {
+    const end = addMonths(startOfMonth(now), 1)
+    const start = addMonths(end, -12)
+    return Array.from({ length: 12 }, (_, index) => {
+      const bucketStart = addMonths(start, index)
+      return {
+        key: bucketStart.toISOString(),
+        label: bucketStart.toLocaleDateString([], { month: 'short' }),
+        start: bucketStart,
+        end: addMonths(bucketStart, 1),
+      }
+    })
+  }
+
+  const days = range === 'week' ? 7 : 30
+  const end = addDays(startOfDay(now), 1)
+  const start = addDays(end, -days)
+  return Array.from({ length: days }, (_, index) => {
+    const bucketStart = addDays(start, index)
+    return {
+      key: bucketStart.toISOString(),
+      label: bucketStart.toLocaleDateString([], range === 'week'
+        ? { weekday: 'short' }
+        : { month: 'short', day: 'numeric' }),
+      start: bucketStart,
+      end: addDays(bucketStart, 1),
+    }
+  })
+}
+
+function timestamp(value: string | null | undefined): number {
+  if (!value)
+    return Number.NaN
+  return new Date(value).getTime()
+}
+
+function inPeriod(value: string | null | undefined, start: Date, end: Date): boolean {
+  const time = timestamp(value)
+  return Number.isFinite(time) && time >= start.getTime() && time < end.getTime()
+}
+
+function percentChange(current: number, previous: number): number | null {
+  if (previous === 0)
+    return current === 0 ? 0 : null
+  return Number((((current - previous) / previous) * 100).toFixed(1))
+}
+
+export default new Action({
+  name: 'InboxActivityAction',
+  description: 'Returns deterministic inbound and outbound mail activity for the dashboard.',
+  method: 'GET',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const requestedRange = queryValue(request, 'range').toLowerCase()
+    const range = RANGES.includes(requestedRange as ActivityRange)
+      ? requestedRange as ActivityRange
+      : 'week'
+    const mailbox = queryValue(request, 'mailbox') || defaultMailbox()
+    const buckets = buildBuckets(range, new Date())
+    const periodStart = buckets[0]!.start
+    const periodEnd = buckets.at(-1)!.end
+    const periodLength = periodEnd.getTime() - periodStart.getTime()
+    const previousStart = new Date(periodStart.getTime() - periodLength)
+
+    const [inbox, deliveryRows] = await Promise.all([
+      emailSDK.getInbox(mailbox, { limit: 1000 }),
+      db
+        .selectFrom('notification_deliveries')
+        .select(['id', 'recipient', 'subject', 'status', 'sent_at', 'created_at'])
+        .where('channel', '=', 'email')
+        .where('created_at', '>=', previousStart.toISOString())
+        .orderBy('created_at', 'desc')
+        .execute() as Promise<DeliveryRow[]>,
+    ])
+
+    const currentInbound = inbox.filter(email => inPeriod(email.date, periodStart, periodEnd))
+    const previousInbound = inbox.filter(email => inPeriod(email.date, previousStart, periodStart))
+    const currentOutbound = deliveryRows.filter(delivery => inPeriod(delivery.sent_at || delivery.created_at, periodStart, periodEnd))
+    const previousOutbound = deliveryRows.filter(delivery => inPeriod(delivery.sent_at || delivery.created_at, previousStart, periodStart))
+
+    const series = buckets.map(bucket => ({
+      key: bucket.key,
+      label: bucket.label,
+      received: currentInbound.filter(email => inPeriod(email.date, bucket.start, bucket.end)).length,
+      sent: currentOutbound.filter(delivery => inPeriod(delivery.sent_at || delivery.created_at, bucket.start, bucket.end)).length,
+      failed: currentOutbound.filter(delivery =>
+        delivery.status === 'failed'
+        && inPeriod(delivery.sent_at || delivery.created_at, bucket.start, bucket.end),
+      ).length,
+    }))
+
+    const currentMessages = currentInbound.length + currentOutbound.length
+    const previousMessages = previousInbound.length + previousOutbound.length
+    const unread = currentInbound.filter(email => !email.read).length
+    const attachments = currentInbound.filter(email => email.hasAttachments).length
+    const failed = currentOutbound.filter(delivery => delivery.status === 'failed').length
+
+    const deliveryStatuses = {
+      sent: currentOutbound.filter(delivery => delivery.status === 'sent').length,
+      delivered: currentOutbound.filter(delivery => delivery.status === 'delivered').length,
+      failed,
+      pending: currentOutbound.filter(delivery => delivery.status === 'pending').length,
+    }
+
+    const recentInbound: ActivityItem[] = currentInbound.map(email => ({
+      id: `inbound:${email.messageId}`,
+      direction: 'received',
+      subject: email.subject || '(no subject)',
+      correspondent: email.fromName || email.from,
+      occurred_at: email.date,
+      status: email.read ? 'read' : 'unread',
+    }))
+    const recentOutbound: ActivityItem[] = currentOutbound.map(delivery => ({
+      id: `outbound:${delivery.id}`,
+      direction: 'sent',
+      subject: delivery.subject || '(no subject)',
+      correspondent: delivery.recipient,
+      occurred_at: delivery.sent_at || delivery.created_at || '',
+      status: delivery.status,
+    }))
+
+    const recent = [...recentInbound, ...recentOutbound]
+      .sort((a, b) => timestamp(b.occurred_at) - timestamp(a.occurred_at))
+      .slice(0, 12)
+
+    return response.json({
+      mailbox,
+      range,
+      period: {
+        start: periodStart.toISOString(),
+        end: periodEnd.toISOString(),
+      },
+      stats: {
+        messages: currentMessages,
+        unread,
+        failed,
+        attachments,
+        message_change: percentChange(currentMessages, previousMessages),
+        unread_rate: currentInbound.length > 0
+          ? Number(((unread / currentInbound.length) * 100).toFixed(1))
+          : 0,
+      },
+      folder_counts: {
+        inbox: inbox.filter(email => !email.read).length,
+        starred: 0,
+        sent: 0,
+        drafts: 0,
+        archive: 0,
+        spam: 0,
+        trash: 0,
+      },
+      mailbox_state: {
+        read: currentInbound.length - unread,
+        unread,
+      },
+      delivery_statuses: deliveryStatuses,
+      series,
+      recent,
+    })
+  },
+})

package/app/Actions/Dashboard/Email/InboxDeleteAction.ts

@@ -0,0 +1,26 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { emailSDK } from '@stacksjs/email'
+import { response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
+
+export default new Action({
+  name: 'InboxDeleteAction',
+  description: 'Permanently deletes a single inbound email and its stored message files.',
+  method: 'DELETE',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const mailbox = String(request.get('mailbox') || defaultMailbox())
+    const messageId = String(request.getParam('id') || '')
+
+    if (!messageId)
+      return response.json({ message: 'A message ID is required.' }, 422)
+
+    const success = await emailSDK.delete(mailbox, messageId)
+    if (!success)
+      return response.json({ message: 'Email not found or it could not be deleted.' }, 404)
+
+    return response.json({ success: true, mailbox, messageId })
+  },
+})

package/app/Actions/Dashboard/Email/InboxIndexAction.ts

@@ -1,6 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { emailSDK } from '@stacksjs/email'
-import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
 
 export interface InboxItem {
   messageId: string
@@ -15,11 +16,6 @@ export interface InboxItem {
   path: string
 }
 
-function defaultMailbox(): string {
-  const domain = (config as any)?.email?.domain || 'stacksjs.com'
-  return `chris@${domain}`
-}
-
 export default new Action({
   name: 'InboxIndexAction',
   description: 'Returns real inbound emails for a mailbox from S3.',
@@ -38,12 +34,9 @@ export default new Action({
       }
     }
     catch (err) {
-      return {
-        mailbox: request?.query?.mailbox || defaultMailbox(),
-        total: 0,
-        emails: [],
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
+      return response.json({
+        message: err instanceof Error ? err.message : 'Inbox messages could not be loaded.',
+      }, 503)
     }
   },
 })

package/app/Actions/Dashboard/Email/InboxMarkReadAction.ts

@@ -1,11 +1,8 @@
+import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { emailSDK } from '@stacksjs/email'
-import { config } from '@stacksjs/config'
-
-function defaultMailbox(): string {
-  const domain = (config as any)?.email?.domain || 'stacksjs.com'
-  return `chris@${domain}`
-}
+import { response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
 
 export default new Action({
   name: 'InboxMarkReadAction',
@@ -13,24 +10,17 @@ export default new Action({
   method: 'POST',
   apiResponse: true,
 
-  async handle(request: any) {
-    try {
-      const body = request?.body || {}
-      const mailbox = body.mailbox || defaultMailbox()
-      const messageId = body.messageId
+  async handle(request: RequestInstance) {
+    const mailbox = String(request.get('mailbox') || defaultMailbox())
+    const messageId = String(request.get('messageId') || '')
+
+    if (!messageId)
+      return response.json({ message: 'messageId is required.' }, 422)
 
-      if (!messageId) {
-        return { ok: false, error: 'messageId is required' }
-      }
+    const success = await emailSDK.markAsRead(mailbox, messageId)
+    if (!success)
+      return response.json({ message: 'Email not found or its read state could not be updated.' }, 404)
 
-      const ok = await emailSDK.markAsRead(mailbox, messageId)
-      return { ok, mailbox, messageId }
-    }
-    catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
-    }
+    return response.json({ success: true, mailbox, messageId })
   },
 })

package/app/Actions/Dashboard/Email/InboxMarkUnreadAction.ts

@@ -0,0 +1,26 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { emailSDK } from '@stacksjs/email'
+import { response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
+
+export default new Action({
+  name: 'InboxMarkUnreadAction',
+  description: 'Marks a single inbound email as unread.',
+  method: 'POST',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const mailbox = String(request.get('mailbox') || defaultMailbox())
+    const messageId = String(request.get('messageId') || '')
+
+    if (!messageId)
+      return response.json({ message: 'messageId is required.' }, 422)
+
+    const success = await emailSDK.markAsUnread(mailbox, messageId)
+    if (!success)
+      return response.json({ message: 'Email not found or its read state could not be updated.' }, 404)
+
+    return response.json({ success: true, mailbox, messageId })
+  },
+})

package/app/Actions/Dashboard/Email/InboxPreferenceShowAction.ts

@@ -0,0 +1,18 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { MailPreference } from '@stacksjs/orm'
+import { response } from '@stacksjs/router'
+import { defaultMailbox, serializeMailPreference } from './mail-preference'
+
+export default new Action({
+  name: 'InboxPreferenceShowAction',
+  description: 'Returns the persisted settings for the configured dashboard mailbox.',
+  method: 'GET',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const mailbox = String(request.get('mailbox') || defaultMailbox()).trim().toLowerCase()
+    const record = await MailPreference.where('mailbox', '=', mailbox).first()
+    return response.json({ preference: serializeMailPreference(record, mailbox) })
+  },
+})

package/app/Actions/Dashboard/Email/InboxPreferenceUpdateAction.ts

@@ -0,0 +1,163 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { MailPreference } from '@stacksjs/orm'
+import { response } from '@stacksjs/router'
+import {
+  defaultMailbox,
+  type MailPreferenceInput,
+  mailPreferenceAttributes,
+  normalizeStringList,
+  serializeMailPreference,
+} from './mail-preference'
+
+const DENSITIES = new Set(['comfortable', 'default', 'compact'])
+const THEMES = new Set(['light', 'dark', 'system'])
+const LANGUAGES = new Set(['en', 'fr', 'de', 'es', 'ja'])
+const REPLY_BEHAVIORS = new Set(['reply', 'replyAll'])
+const AUTO_ADVANCE_OPTIONS = new Set(['newer', 'older', 'back'])
+const SOUNDS = new Set(['default', 'subtle', 'none'])
+
+function stringInput(
+  request: RequestInstance,
+  key: string,
+  fields: Record<string, string>,
+  fallback = '',
+): string {
+  const value = request.get(key)
+  if (value === null || value === undefined)
+    return fallback
+  if (typeof value !== 'string') {
+    fields[key] = 'This field must be a string.'
+    return fallback
+  }
+  return value
+}
+
+function booleanInput(
+  request: RequestInstance,
+  key: string,
+  fields: Record<string, string>,
+  fallback: boolean,
+): boolean {
+  const value = request.get(key)
+  if (value === null || value === undefined)
+    return fallback
+  if (typeof value !== 'boolean') {
+    fields[key] = 'This field must be a boolean.'
+    return fallback
+  }
+  return value
+}
+
+function enumInput<T extends string>(
+  request: RequestInstance,
+  key: string,
+  allowed: Set<string>,
+  fields: Record<string, string>,
+  fallback: T,
+): T {
+  const value = stringInput(request, key, fields, fallback)
+  if (!allowed.has(value)) {
+    fields[key] = `Choose one of: ${[...allowed].join(', ')}.`
+    return fallback
+  }
+  return value as T
+}
+
+function inputFromRequest(
+  request: RequestInstance,
+  mailbox: string,
+): { fields: Record<string, string>, input: MailPreferenceInput } {
+  const fields: Record<string, string> = {}
+  const accountName = stringInput(request, 'accountName', fields, 'Stacks').trim()
+  const signature = stringInput(request, 'signature', fields)
+  const vacationSubject = stringInput(request, 'vacationSubject', fields)
+  const vacationMessage = stringInput(request, 'vacationMessage', fields)
+
+  if (!accountName)
+    fields.accountName = 'Account name is required.'
+  else if (accountName.length > 255)
+    fields.accountName = 'Account name must be 255 characters or fewer.'
+  if (signature.length > 20_000)
+    fields.signature = 'Signature must be 20,000 characters or fewer.'
+  if (vacationSubject.length > 255)
+    fields.vacationSubject = 'Vacation subject must be 255 characters or fewer.'
+  if (vacationMessage.length > 20_000)
+    fields.vacationMessage = 'Vacation message must be 20,000 characters or fewer.'
+
+  const listInput = (key: 'filters' | 'blockedSenders' | 'labels'): string => {
+    const value = stringInput(request, key, fields, '[]')
+    try {
+      return normalizeStringList(value, key)
+    }
+    catch (error) {
+      fields[key] = error instanceof Error ? error.message : `${key} is invalid.`
+      return '[]'
+    }
+  }
+
+  return {
+    fields,
+    input: {
+      mailbox,
+      accountName,
+      signature,
+      displayDensity: enumInput(request, 'displayDensity', DENSITIES, fields, 'default'),
+      theme: enumInput(request, 'theme', THEMES, fields, 'system'),
+      language: enumInput(request, 'language', LANGUAGES, fields, 'en'),
+      defaultReplyBehavior: enumInput(request, 'defaultReplyBehavior', REPLY_BEHAVIORS, fields, 'replyAll'),
+      sendAndArchive: booleanInput(request, 'sendAndArchive', fields, true),
+      autoAdvance: enumInput(request, 'autoAdvance', AUTO_ADVANCE_OPTIONS, fields, 'newer'),
+      desktopNotifications: booleanInput(request, 'desktopNotifications', fields, true),
+      notificationSound: enumInput(request, 'notificationSound', SOUNDS, fields, 'default'),
+      notificationPreview: booleanInput(request, 'notificationPreview', fields, true),
+      filters: listInput('filters'),
+      blockedSenders: listInput('blockedSenders'),
+      labels: listInput('labels'),
+      loadRemoteImages: booleanInput(request, 'loadRemoteImages', fields, false),
+      showExternalContent: booleanInput(request, 'showExternalContent', fields, false),
+      vacationEnabled: booleanInput(request, 'vacationEnabled', fields, false),
+      vacationStartDate: stringInput(request, 'vacationStartDate', fields),
+      vacationEndDate: stringInput(request, 'vacationEndDate', fields),
+      vacationSubject,
+      vacationMessage,
+    },
+  }
+}
+
+export default new Action({
+  name: 'InboxPreferenceUpdateAction',
+  description: 'Creates or updates settings for the configured dashboard mailbox.',
+  method: 'PUT',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const mailboxValue = request.get('mailbox')
+    const mailbox = (mailboxValue === null || mailboxValue === undefined
+      ? defaultMailbox()
+      : typeof mailboxValue === 'string' ? mailboxValue : '')
+      .trim()
+      .toLowerCase()
+    if (!/^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/.test(mailbox) || mailbox.length > 320)
+      return response.json({ message: 'The mail settings are invalid.', fields: { mailbox: 'Enter a valid mailbox.' } }, 422)
+
+    const { fields, input } = inputFromRequest(request, mailbox)
+    if (Object.keys(fields).length)
+      return response.json({ message: 'The mail settings are invalid.', fields }, 422)
+
+    const record = await MailPreference.where('mailbox', '=', mailbox).first()
+    const attributes = mailPreferenceAttributes(input)
+    if (record)
+      await record.update(attributes)
+    else
+      await MailPreference.create(attributes)
+
+    return response.json({
+      success: true,
+      preference: serializeMailPreference(
+        await MailPreference.where('mailbox', '=', mailbox).first(),
+        mailbox,
+      ),
+    })
+  },
+})

package/app/Actions/Dashboard/Email/InboxSendAction.ts

@@ -0,0 +1,44 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { notify } from '@stacksjs/notifications'
+import { response } from '@stacksjs/router'
+import { schema } from '@stacksjs/validation'
+
+export default new Action({
+  name: 'InboxSendAction',
+  description: 'Sends a composed dashboard email and records its delivery attempt.',
+  method: 'POST',
+  apiResponse: true,
+  validations: {
+    to: {
+      rule: schema.string().email().max(320).required(),
+      message: 'Enter a valid recipient email address.',
+    },
+    subject: {
+      rule: schema.string().max(255).required(),
+      message: 'A subject is required and may not exceed 255 characters.',
+    },
+    body: {
+      rule: schema.string().max(100_000).required(),
+      message: 'A message body is required.',
+    },
+  },
+
+  async handle(request: RequestInstance) {
+    const to = String(request.get('to') || '').trim()
+    const subject = String(request.get('subject') || '').trim()
+    const body = String(request.get('body') || '').trim()
+
+    const [result] = await notify(
+      { email: to },
+      { subject, body, data: { source: 'dashboard-inbox' } },
+      ['email'],
+      { ignorePreferences: true },
+    )
+
+    if (!result?.success)
+      return response.json({ message: result?.error?.message || 'The email could not be sent.' }, 502)
+
+    return response.json({ success: true })
+  },
+})

package/app/Actions/Dashboard/Email/InboxShowAction.ts

@@ -1,11 +1,8 @@
 import { Action } from '@stacksjs/actions'
 import { emailSDK } from '@stacksjs/email'
-import { config } from '@stacksjs/config'
-
-function defaultMailbox(): string {
-  const domain = (config as any)?.email?.domain || 'stacksjs.com'
-  return `chris@${domain}`
-}
+import { response } from '@stacksjs/router'
+import { defaultMailbox } from './mail-preference'
+import { sanitizeInboxHtml } from './sanitize-inbox-html'
 
 export default new Action({
   name: 'InboxShowAction',
@@ -18,27 +15,25 @@ export default new Action({
       const mailbox = request?.query?.mailbox || defaultMailbox()
       const messageId = request?.params?.id
 
-      if (!messageId) {
-        return { error: 'messageId is required' }
-      }
+      if (!messageId)
+        return response.json({ message: 'A message ID is required.' }, 422)
 
       const email = await emailSDK.getEmail(mailbox, messageId)
-      if (!email) {
-        return { error: 'Email not found' }
-      }
+      if (!email)
+        return response.json({ message: 'Email not found.' }, 404)
 
       return {
         mailbox,
         messageId,
-        html: email.html ?? '',
+        html: sanitizeInboxHtml(email.html ?? ''),
         text: email.text ?? '',
         metadata: email.metadata,
       }
     }
     catch (err) {
-      return {
-        error: err instanceof Error ? err.message : 'unknown error',
-      }
+      return response.json({
+        message: err instanceof Error ? err.message : 'Email content could not be loaded.',
+      }, 503)
     }
   },
 })