@stacksjs/defaults 0.70.355 → 0.70.357

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

@@ -14,6 +14,7 @@ Multi-driver email system with template rendering, S3-based inbox management, an
 - Core package: `storage/framework/core/email/src/`
 - Configuration: `config/email.ts`
 - Application mail: `app/Mail/`
+- Persistence models: `storage/framework/defaults/app/Models/EmailSuppression.ts`, `EmailIdempotency.ts`, `EmailWebhookEvent.ts`
 - Email layouts: `storage/framework/defaults/resources/emails/layouts/`
 - Email resources: `storage/framework/defaults/resources/emails/`
 
@@ -54,11 +55,30 @@ await mail.send({
   text: 'Hello!'
 })
 
+// Use this when later state depends on successful provider delivery.
+await mail.sendOrFail({
+  to: 'user@example.com',
+  subject: 'Your invitation',
+  text: 'Open the invitation link.'
+})
+
 // Switch driver
 const sendgridMail = mail.use('sendgrid')
 await sendgridMail.send(message)
 ```
 
+`mail.send()` always returns an `EmailResult`. Provider rejection is represented
+as `{ success: false, message, provider }`, which is useful for campaign jobs
+that aggregate individual outcomes. It may still throw for invalid framework
+configuration. `mail.sendOrFail()` returns the same successful result and throws
+`EmailDeliveryError` for a structured provider failure. Use `sendOrFail()` when
+an action reports that mail was sent, when a caller relies on `.catch()`, or when
+delivery status is persisted after the call.
+
+Keep template rendering fallback separate from provider delivery. Resolve HTML
+and text first, fall back to plain text only when rendering fails, then call
+`sendOrFail()` once outside the template `try` block.
+
 ## Email Class
 
 ```typescript
@@ -230,7 +250,7 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
     }
   })
 
-  await mail.send({
+  await mail.sendOrFail({
     from: { name: config.app.name, address: config.email.from.address },
     to,
     subject: 'Confirm your subscription',
@@ -240,6 +260,21 @@ export async function sendSubscriptionConfirmation({ to, subscriberUuid }: Optio
 }
 ```
 
+## Delivery persistence models
+
+Stacks ships three internal models and their generated migrations:
+
+- `EmailSuppression` uses `email_suppressions` and uniquely keys `email + type`.
+- `EmailIdempotency` uses `email_idempotency` and uniquely keys `idempotency_key`.
+- `EmailWebhookEvent` uses `email_webhook_events` and uniquely keys `provider + event_id`.
+
+Each model declares authenticated `useApi` index, show, and destroy routes, but
+sets `dashboard.enabled` to false so operational records do not clutter the
+generic model catalog. Sensitive idempotency keys, recipients, subjects, and
+provider event IDs are hidden from generated responses. Run `buddy migrate`
+after upgrading so suppression, send deduplication, and webhook deduplication
+are enforced rather than using their legacy warn-once compatibility path.
+
 ## Inbound MIME and attachment storage
 
 `parseInboundEmail()` parses RFC messages with bounded header, nesting, total-size, and attachment-count limits. It returns normalized sender and recipient data, text and HTML bodies, and binary-safe attachments. Attachment filenames are sanitized before they become S3 keys.
@@ -274,6 +309,8 @@ Reprocessing refreshes existing messages instead of skipping them, preserves the
 - The `mail` singleton auto-registers all 5 drivers on initialization
 - SMTP driver handles TLS handshake manually (not via node:tls)
 - SendGrid/Mailgun retry with exponential backoff on failure
+- `mail.send()` returns structured failures; use `mail.sendOrFail()` when success is required
+- Suppression, send idempotency, and webhook dedup are backed by built-in `useApi` models
 - Mailtrap requires `inboxId` for sandbox mode
 - EmailSDK reads inbox from S3 (bucket configured via env)
 - EmailSDK attachment downloads use binary-safe S3 reads and opaque IDs

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

@@ -196,6 +196,12 @@ await createUser('Alice', 'alice@example.com') // auto-wrapped
 
 Both `transaction()` and `savepoint()` delegate to `db.transaction()` and `db.savepoint()` from `@stacksjs/database`.
 
+### Transaction executor boundary
+
+Every query that must commit or roll back together must use the callback handle (`tx` or `sp`), including validation reads, pivot writes, and the final readback. Do not mix `Model.find()`, `Model.create()`, instance `update()` / `delete()`, or instance relation calls into a raw query-builder transaction. The model executor is a separate execution surface and is not rebound to the callback handle. On SQLite it may use a separate connection, so it cannot observe an uncommitted row written through `tx`.
+
+`runInTransactionScope()` buffers supported side effects until commit, but it does not rebind model queries. For a transaction-backed custom action, use the model definition as the schema and relationship source of truth, then execute the complete persistence workflow through `tx`. Read the created or updated row through `tx` before returning so a readback failure also rolls back the mutation.
+
 ## Trait Methods (traits/)
 
 ### Taggable (when `traits.taggable: true`)

package/app/Actions/ContactAction.ts

@@ -53,7 +53,7 @@ export default new Action({
     ].join('\n')
 
     try {
-      await mail.send({
+      await mail.sendOrFail({
         to: [toAddress],
         from: { name: appName, address: fromAddress },
         replyTo: email,
@@ -63,7 +63,7 @@ export default new Action({
     }
     catch (err) {
       const errMessage = err instanceof Error ? err.message : String(err)
-      console.error('[ContactAction] mail.send failed:', errMessage)
+      console.error('[ContactAction] mail.sendOrFail failed:', errMessage)
       return { success: false, message: 'We could not send your message. Try again in a moment.' }
     }
 

package/app/Actions/Dashboard/Analytics/EventAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { AnalyticsEvent } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -50,9 +51,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Event analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Event analytics records could not be read.', 'EventAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/MarketingAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Campaign } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -55,9 +56,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Campaign analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Campaign analytics records could not be read.', 'MarketingAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/SalesAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Category, Order, OrderItem, Payment, Product } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   analyticsCurrency,
   analyticsIdentifier,
@@ -93,9 +94,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Sales analytics records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Sales analytics records could not be read.', 'SalesAnalyticsAction')
     }
   },
 })

package/app/Actions/Dashboard/Analytics/WebAnalyticsAction.ts

@@ -2,6 +2,7 @@ import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Request } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   buildWebAnalytics,
   normalizeAnalyticsRange,
@@ -27,9 +28,14 @@ export default new Action({
         message: error instanceof Error ? error.message : 'The analytics query is invalid.',
       }, 422)
     }
-    const records = await Request.orderByDesc('id').limit(10_000).get()
-    const rows = records.map(requestAnalyticsRow)
+    try {
+      const records = await Request.orderByDesc('id').limit(10_000).get()
+      const rows = records.map(requestAnalyticsRow)
 
-    return buildWebAnalytics(rows, range, new Date(), scope)
+      return buildWebAnalytics(rows, range, new Date(), scope)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Web analytics records could not be read.', 'WebAnalyticsAction')
+    }
   },
 })

package/app/Actions/Dashboard/Auth/MeAction.ts

@@ -1,6 +1,7 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { getUserRoles } from '@stacksjs/auth'
+import { dashboardOperationalError } from '../dashboard-response'
 
 interface MeResponse {
   user: {
@@ -59,17 +60,13 @@ export default new Action({
 
     const userId = Number(user.id)
 
-    let roles: string[] = []
+    let roles: string[]
     try {
       const records = await getUserRoles(userId)
       roles = records.map(r => r.name)
     }
-    catch (err) {
-      // RBAC store not configured, migrations not run, or DB unreachable.
-      // Empty roles → useRole will fall back to its dev default. We don't
-      // want to 500 the dashboard just because the role tables haven't
-      // been migrated yet on a fresh project.
-      console.warn('[dashboard/auth/me] getUserRoles failed:', err instanceof Error ? err.message : err)
+    catch (error) {
+      return dashboardOperationalError(error, 'Dashboard identity could not be loaded.', 'MeAction')
     }
 
     const res: MeResponse = {

package/app/Actions/Dashboard/Buddy/BuddyChatAction.ts

@@ -4,6 +4,7 @@ import { Action } from '@stacksjs/actions'
 import { buddyState, createAIClient } from '@stacksjs/ai'
 import { config } from '@stacksjs/config'
 import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { buddySystemPrompt, isBuddyProviderConfigured, publicBuddyHistory, resolveBuddyProvider } from './buddy-chat'
 
 export default new Action({
@@ -49,9 +50,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Buddy could not answer the question.',
-      }, 502)
+      return dashboardOperationalError(error, 'Buddy could not answer the question.', 'BuddyChatAction', 502)
     }
   },
 })

package/app/Actions/Dashboard/Cloud/CloudIndexAction.ts

@@ -1,12 +1,19 @@
 import { Action } from '@stacksjs/actions'
 import { tsCloud } from '~/config/cloud'
+import { dashboardOperationalError } from '../dashboard-response'
 import { getDashboardCloudSnapshot } from './cloud-overview'
 
 export default new Action({
   name: 'CloudIndexAction',
   description: 'Returns configured cloud infrastructure and persisted deployment state.',
   method: 'GET',
+  apiResponse: true,
   async handle() {
-    return getDashboardCloudSnapshot(tsCloud)
+    try {
+      return await getDashboardCloudSnapshot(tsCloud)
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Cloud infrastructure could not be loaded.', 'CloudIndexAction')
+    }
   },
 })

package/app/Actions/Dashboard/Cloud/ServerlessIndexAction.ts

@@ -1,20 +1,27 @@
 import { Action } from '@stacksjs/actions'
 import { tsCloud } from '~/config/cloud'
+import { dashboardOperationalError } from '../dashboard-response'
 import { getDashboardCloudSnapshot } from './cloud-overview'
 
 export default new Action({
   name: 'ServerlessIndexAction',
   description: 'Returns serverless services derived from environment application manifests.',
   method: 'GET',
+  apiResponse: true,
   async handle() {
-    const snapshot = await getDashboardCloudSnapshot(tsCloud)
-    return {
-      project: snapshot.project,
-      environments: snapshot.environments.filter(environment => environment.serverless),
-      services: snapshot.serverlessServices,
-      links: snapshot.serverlessLinks,
-      events: snapshot.events.filter(event => event.service.toLowerCase().includes('serverless')),
-      generatedAt: snapshot.generatedAt,
+    try {
+      const snapshot = await getDashboardCloudSnapshot(tsCloud)
+      return {
+        project: snapshot.project,
+        environments: snapshot.environments.filter(environment => environment.serverless),
+        services: snapshot.serverlessServices,
+        links: snapshot.serverlessLinks,
+        events: snapshot.events.filter(event => event.service.toLowerCase().includes('serverless')),
+        generatedAt: snapshot.generatedAt,
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Serverless infrastructure could not be loaded.', 'ServerlessIndexAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceCategoriesAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { Category } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { normalizeCommerceCategoryRecord, summarizeCommerceCategories } from './commerce-category-records'
 
 export default new Action({
@@ -24,9 +24,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Category records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Category records could not be read.', 'CommerceCategoriesAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceCouponsAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { Coupon, Product } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { normalizeCouponRecord, summarizeCoupons } from './coupon-records'
 import { commerceIdentifier, commerceValue } from './commerce-record'
 
@@ -26,9 +26,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Coupon records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Coupon records could not be read.', 'CommerceCouponsAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceCustomersAction.ts

@@ -1,7 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { config } from '@stacksjs/config'
 import { Customer } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   normalizeCommerceCustomerCurrency,
   normalizeCommerceCustomerRecord,
@@ -25,9 +25,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Customer records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Customer records could not be read.', 'CommerceCustomersAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceDashboardAction.ts

@@ -1,7 +1,7 @@
 import type { RequestInstance } from '@stacksjs/types'
 import { Action } from '@stacksjs/actions'
 import { Customer, Order, OrderItem, Product } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   buildCommerceDashboard,
   commerceDashboardQueryStart,
@@ -56,9 +56,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Commerce overview records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Commerce overview records could not be read.', 'CommerceDashboardAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceDeliveryAction.ts

@@ -1,7 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { config } from '@stacksjs/config'
 import { DeliveryRoute, Driver, ShippingMethod, ShippingZone } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { buildDeliveryOverview } from './commerce-delivery'
 
 export default new Action({
@@ -28,9 +28,7 @@ export default new Action({
       )
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Delivery records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Delivery records could not be read.', 'CommerceDeliveryAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceGiftCardsAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { Customer, GiftCard } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { normalizeGiftCardRecord, summarizeGiftCards } from './gift-card-records'
 import { commerceIdentifier, commerceValue } from './commerce-record'
 
@@ -26,9 +26,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Gift card records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Gift card records could not be read.', 'CommerceGiftCardsAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommerceOrdersAction.ts

@@ -1,7 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { config } from '@stacksjs/config'
 import { Coupon, Customer, Order, OrderItem } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   addOrderItemQuantity,
   normalizeCommerceOrderRecord,
@@ -54,9 +54,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Order records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Order records could not be read.', 'CommerceOrdersAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommercePaymentsAction.ts

@@ -1,6 +1,6 @@
 import { Action } from '@stacksjs/actions'
 import { Customer, Order, Payment } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import { commerceIdentifier, commerceValue } from './commerce-record'
 import { normalizePaymentRecord, summarizePayments } from './payment-records'
 
@@ -32,9 +32,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Payment records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Payment records could not be read.', 'CommercePaymentsAction')
     }
   },
 })

package/app/Actions/Dashboard/Commerce/CommercePosAction.ts

@@ -1,7 +1,7 @@
 import { Action } from '@stacksjs/actions'
 import { config } from '@stacksjs/config'
 import { Category, Customer, Manufacturer, Product, TaxRate } from '@stacksjs/orm'
-import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
 import {
   isCommercePosCustomerActive,
   normalizeCommercePosCustomer,
@@ -63,9 +63,7 @@ export default new Action({
       }
     }
     catch (error) {
-      return response.json({
-        message: error instanceof Error ? error.message : 'Point of sale records could not be read.',
-      }, 503)
+      return dashboardOperationalError(error, 'Point of sale records could not be read.', 'CommercePosAction')
     }
   },
 })