@stacksjs/defaults 0.70.57 → 0.70.59

package/app/Jobs/PruneModelsJob.ts

@@ -0,0 +1,61 @@
+import { log } from '@stacksjs/logging'
+
+interface PrunableModelConfig {
+  table: string
+  olderThanDays?: number
+  column?: string
+  query?: (qb: any) => any
+}
+
+export default class PruneModelsJob {
+  public static config = {
+    schedule: '0 0 * * *', // Daily at midnight
+    withoutOverlapping: true,
+    timeout: 5 * 60,
+    retries: 3,
+    retryAfter: [60, 120, 300],
+  }
+
+  /**
+   * The models to prune and their configurations.
+   * Add entries here to register prunable models.
+   */
+  private static prunableModels: PrunableModelConfig[] = []
+
+  /**
+   * Register a model for pruning.
+   */
+  public static register(table: string, options: Omit<PrunableModelConfig, 'table'> = {}): void {
+    PruneModelsJob.prunableModels.push({ table, ...options })
+  }
+
+  public static async handle(): Promise<{ total: number, results: Array<{ table: string, pruned: number }> }> {
+    try {
+      log.info('Running model pruning job')
+
+      const { prunable } = await import('../../orm/src/utils/prunable')
+
+      const results: Array<{ table: string, pruned: number }> = []
+      let total = 0
+
+      for (const model of PruneModelsJob.prunableModels) {
+        const pruned = await prunable(model.table, {
+          olderThanDays: model.olderThanDays,
+          column: model.column,
+          query: model.query,
+        })
+
+        results.push({ table: model.table, pruned })
+        total += pruned
+      }
+
+      log.info(`Model pruning complete: ${total} records pruned across ${results.length} models`)
+
+      return { total, results }
+    }
+    catch (error) {
+      log.error('Failed to prune models:', error)
+      throw error
+    }
+  }
+}

package/app/Jobs/PruneQueryLogsJob.ts

@@ -0,0 +1,51 @@
+import { config } from '@stacksjs/config'
+import { log } from '@stacksjs/logging'
+import QueryController from '../Controllers/QueryController'
+
+export default class PruneQueryLogsJob {
+  /**
+   * Job configuration
+   */
+  public static config = {
+    // Run the job based on the configured frequency, defaulting to daily
+    schedule: config.database?.queryLogging?.pruneFrequency
+      ? `0 */${config.database.queryLogging.pruneFrequency} * * *` // Every X hours
+      : '0 0 * * *', // Daily at midnight
+
+    // Prevent overlapping job executions
+    withoutOverlapping: true,
+
+    // Timeout after 5 minutes
+    timeout: 5 * 60,
+
+    // Retry up to 3 times with exponential backoff
+    retries: 3,
+    retryAfter: [60, 120, 300], // seconds
+  }
+
+  /**
+   * Execute the job
+   */
+  public static async handle() {
+    try {
+      log.info('Running query logs pruning job')
+
+      // Skip if query logging is disabled
+      if (!config.database?.queryLogging?.enabled) {
+        log.info('Query logging is disabled, skipping pruning job')
+        return
+      }
+
+      // Prune old query logs
+      const result = await QueryController.pruneQueryLogs()
+
+      log.info(`Successfully pruned ${result.pruned} query logs older than ${result.retentionDays} days`)
+
+      return result
+    }
+    catch (error) {
+      log.error('Failed to prune query logs:', error)
+      throw error
+    }
+  }
+}

package/app/Jobs/README.md

@@ -0,0 +1,79 @@
+# What are Jobs
+
+Jobs are a way to define a task that should be executed at a specific time. They are a Stacks primitive that may be called from anywhere in your application.
+
+> [!TIP]
+> Jobs can also be executed on a schedule, using cron syntax. Simply define the `rate` at which the job should run, and Stacks will take care of the rest.
+
+## Get Started
+
+The following command will bootstrap a new job file in the `app/Jobs` directory.
+
+```sh
+buddy make:job ExampleJob
+```
+
+```sh
+
+### Example
+
+A simple example of a job that logs a message. _For a closer look, take a peak at the [ExampleJob.ts](./ExampleJob.ts)._
+
+```ts
+
+export interface JobOptions {
+  /**
+
+   _ The name of the job.
+
+   _/
+  name?: string
+  description?: string
+  handle?: string | Function
+  action?: string // the ActionName. Typed support incoming
+  timezone?: string
+  /**
+
+   _ Number of tries. Must be between 0 and 185.
+
+   _/
+  tries?: IntRange<0, 185>
+  backoff?: number | number[]
+  rate?: string | Every
+  enabled?: boolean
+}
+
+const options: JobOptions = {
+  name: 'Example Job', // optional, defaults to the file name
+  description: 'A demo (cron) job that runs every minute', // optional, used in the dashboard for context
+  tries: 3, // optional, defaults to 3 retries (in case of failures)
+  backoff: 3, // optional, defaults to 3-second delays between retries
+  rate: Every.Minute, // optional, '_ _ _ _ *' in cron syntax
+  handle: () => { // action: 'SendWelcomeEmail', // instead of handle, you may target an action or `action: () => {`
+    log.info('This message logs every minute') // unless triggered via a route.job() call, in which case it logs once
+  },
+}
+
+export default new Job(options)
+
+```
+
+## 🚜 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/Jobs/SendCampaignJob.ts

@@ -0,0 +1,201 @@
+import { config } from '@stacksjs/config'
+import { mail, template } from '@stacksjs/email'
+import { log } from '@stacksjs/logging'
+import { buildUnsubscribeHeaders } from '@stacksjs/newsletter'
+import { Campaign, CampaignSend, EmailList, EmailListSubscriber, Subscriber } from '@stacksjs/orm'
+import { Job } from '@stacksjs/queue'
+import { url } from '@stacksjs/router'
+
+/**
+ * Newsletter campaign dispatcher.
+ *
+ * Loads the campaign + its target list, walks every active pivot row,
+ * renders the template, attaches per-recipient `List-Unsubscribe`
+ * headers (RFC 8058), and hands each envelope to `@stacksjs/email`.
+ *
+ * Why per-recipient sends instead of one fan-out send?  The pivot
+ * UUID is the unsubscribe token — embedding it means we can't share
+ * a single envelope across recipients without leaking everyone else's
+ * unsubscribe URL via Bcc round-tripping. Per-recipient also lets us
+ * record granular CampaignSend status rows for retries and analytics.
+ *
+ * Failures from a single recipient don't poison the chunk — we record
+ * the error on the `CampaignSend` row and keep going. Whole-job
+ * failures (e.g. "campaign not found") throw so the queue retries.
+ */
+interface SendCampaignPayload {
+  campaignId: number
+  chunkSize?: number
+  dryRun?: boolean
+}
+
+export default new Job({
+  name: 'SendCampaign',
+  description: 'Fan a campaign out to its target list (background)',
+  queue: 'campaigns',
+  // Whole-campaign failures are rare; we don't want a flaky DB to
+  // double-send a marketing blast. One automatic retry, then surface.
+  tries: 2,
+  backoff: [60],
+
+  async handle(payload: SendCampaignPayload) {
+    if (!payload?.campaignId)
+      throw new Error('[SendCampaign] payload.campaignId is required')
+
+    const campaign = await (Campaign as any).find(payload.campaignId)
+    if (!campaign)
+      throw new Error(`[SendCampaign] Campaign ${payload.campaignId} not found`)
+
+    if (campaign.status === 'sent' || campaign.status === 'cancelled') {
+      log.warn(`[SendCampaign] Skipping campaign ${campaign.id} in status '${campaign.status}'`)
+      return { sent: 0, skipped: true }
+    }
+
+    if (!campaign.email_list_id)
+      throw new Error(`[SendCampaign] Campaign ${campaign.id} has no email_list_id`)
+
+    const list = await (EmailList as any).find(campaign.email_list_id)
+    if (!list)
+      throw new Error(`[SendCampaign] EmailList ${campaign.email_list_id} not found`)
+
+    await campaign.update({ status: 'sending' })
+
+    const appName = config.app.name || 'Stacks'
+    const fromAddress = {
+      name: campaign.from_name || config.email.from?.name || appName,
+      address: campaign.from_address || config.email.from?.address || 'no-reply@stacksjs.com',
+    }
+    const unsubscribeMailbox = (config as any)?.email?.unsubscribeMailbox
+
+    const chunkSize = payload.chunkSize ?? 50
+    const dryRun = payload.dryRun ?? false
+
+    let sent = 0
+    let failed = 0
+    let offset = 0
+
+    // Walk active pivots in chunks. We never load the full list into
+    // memory — large lists (100k+) would OOM the worker, and we want
+    // crash safety: if the worker dies mid-send we can resume from the
+    // first subscriber without a CampaignSend row for this campaign.
+    while (true) {
+      const pivots = await (EmailListSubscriber as any)
+        .where('email_list_id', campaign.email_list_id)
+        .where('status', 'subscribed')
+        .limit(chunkSize)
+        .offset(offset)
+        .get()
+
+      if (!pivots || pivots.length === 0)
+        break
+
+      for (const pivot of pivots) {
+        // Skip if we've already sent for this (campaign, subscriber).
+        // The unique index protects us, but checking up front avoids a
+        // try/catch round-trip per existing row when we resume.
+        const existing = await (CampaignSend as any)
+          .where('campaign_id', campaign.id)
+          .where('subscriber_id', pivot.subscriber_id)
+          .first()
+        if (existing && existing.status === 'sent')
+          continue
+
+        const subscriber = await (Subscriber as any).find(pivot.subscriber_id)
+        if (!subscriber || !subscriber.email)
+          continue
+
+        // The pivot UUID is the per-list unsubscribe token. Both the
+        // header and the in-body link point to the same handler so
+        // RFC 8058 one-click and "click the link" land in the same
+        // place.
+        const unsubscribeUrl = url('email.unsubscribe', { token: pivot.uuid })
+        const headers = buildUnsubscribeHeaders({
+          url: unsubscribeUrl,
+          mailto: unsubscribeMailbox,
+        })
+
+        let html: string
+        let text: string | undefined
+        try {
+          const rendered = await template(campaign.template, {
+            variables: {
+              email: subscriber.email,
+              unsubscribeUrl,
+              listName: list.name,
+              campaignName: campaign.name,
+            },
+            subject: campaign.subject,
+          })
+          html = rendered.html
+          text = rendered.text
+        }
+        catch {
+          // Template name didn't resolve to a file — fall back to
+          // treating campaign.template as raw HTML. Saves you from
+          // having to scaffold a .stx file for one-off blasts.
+          html = campaign.template
+          text = campaign.text || undefined
+        }
+
+        const sendRow = existing
+          ?? (await (CampaignSend as any).create({
+            campaign_id: campaign.id,
+            subscriber_id: pivot.subscriber_id,
+            email_list_id: campaign.email_list_id,
+            status: 'queued',
+          }))
+
+        if (dryRun) {
+          await sendRow.update({ status: 'sent', sent_at: new Date().toISOString(), provider_message_id: 'dry-run' })
+          sent++
+          continue
+        }
+
+        try {
+          const result = await mail.send({
+            to: [subscriber.email],
+            from: fromAddress,
+            subject: campaign.subject,
+            html,
+            text,
+            // `headers` is optional on EmailMessage — drivers that
+            // already propagate raw headers pick this up; ones that
+            // don't yet will silently drop and we lose only the
+            // RFC 8058 one-click affordance. The in-body link still
+            // works in every case.
+            headers,
+          } as any)
+
+          if (result?.success === false) {
+            await sendRow.update({ status: 'failed', error: result?.message ?? 'driver returned failure' })
+            failed++
+            continue
+          }
+
+          await sendRow.update({
+            status: 'sent',
+            sent_at: new Date().toISOString(),
+            provider_message_id: result?.messageId ?? null,
+          })
+          sent++
+        }
+        catch (err: unknown) {
+          const message = err instanceof Error ? err.message : String(err)
+          await sendRow.update({ status: 'failed', error: message })
+          failed++
+        }
+      }
+
+      offset += pivots.length
+    }
+
+    await campaign.update({
+      status: 'sent',
+      sent_at: new Date().toISOString(),
+      sent_count: sent,
+    })
+
+    log.debug(`[SendCampaign] campaign=${campaign.id} sent=${sent} failed=${failed}`)
+    return { sent, failed }
+  },
+})

package/app/Jobs/SendEmailJob.ts

@@ -0,0 +1,52 @@
+import type { EmailMessage } from '@stacksjs/types'
+import { mail } from '@stacksjs/email'
+import { log } from '@stacksjs/logging'
+import { Job } from '@stacksjs/queue'
+
+/**
+ * Background email-send job.
+ *
+ * `mail.queue(message)` (and `.later(seconds, message)` / `.queueOn(queue, message)`)
+ * dispatch to a job named `SendEmail` — this is its handler. Without this
+ * file the queued envelope just sat in the `jobs` table forever (the
+ * framework had no shipped handler), so any caller using `mail.queue()`
+ * silently dropped the email.
+ *
+ * Uses `mail.use(driver)` so the same payload can be sent through any
+ * registered transport — preserves the driver the producer chose at
+ * dispatch time even if the worker process inherits a different default.
+ */
+interface SendEmailPayload {
+  message: EmailMessage
+  driver?: string
+}
+
+export default new Job({
+  name: 'SendEmail',
+  description: 'Send an email via the configured transport (background)',
+  queue: 'emails',
+  tries: 3,
+  backoff: [10, 30, 60], // 10s → 30s → 60s
+
+  async handle(payload: SendEmailPayload) {
+    if (!payload?.message) {
+      throw new Error('[SendEmail] payload.message is required')
+    }
+
+    const transport = payload.driver
+      ? mail.use(payload.driver)
+      : mail
+
+    const result = await transport.send(payload.message)
+
+    if (!result?.success) {
+      // Re-throw so the worker counts this as a failed attempt (and the
+      // queue retries with the configured backoff). Without throwing,
+      // failed sends would silently drop on the floor.
+      throw new Error(`[SendEmail] driver '${result?.provider ?? payload.driver ?? 'default'}' returned failure: ${result?.message ?? 'unknown error'}`)
+    }
+
+    log.debug(`[SendEmail] sent via ${result.provider} (messageId=${result.messageId ?? 'n/a'})`)
+    return { messageId: result.messageId, provider: result.provider }
+  },
+})

package/app/Jobs/SendPasswordResetEmailJob.ts

@@ -0,0 +1,44 @@
+import { Job } from '@stacksjs/queue'
+import { passwordResets } from '@stacksjs/auth'
+
+interface PasswordResetPayload {
+  email: string
+}
+
+console.log('[SendPasswordResetEmailJob] Job file loaded')
+
+export default new Job({
+  name: 'SendPasswordResetEmail',
+  description: 'Sends a password reset email to the user',
+  queue: 'emails',
+  tries: 3,
+  backoff: [10, 30, 60], // Retry after 10s, 30s, 60s
+
+  async handle(payload: PasswordResetPayload) {
+    console.log('[Job.handle] SendPasswordResetEmailJob.handle() called')
+    console.log('[Job.handle] Received payload:', payload)
+
+    const { email } = payload
+
+    if (!email) {
+      console.error('[Job.handle] No email in payload!')
+      throw new Error('Email is required to send password reset')
+    }
+
+    console.log(`[Job.handle] Processing password reset for: ${email}`)
+
+    try {
+      console.log('[Job.handle] Calling passwordResets().sendEmail()...')
+      const resetInstance = passwordResets(email)
+      console.log('[Job.handle] Password reset instance created')
+
+      await resetInstance.sendEmail()
+      console.log(`[Job.handle] Email sent successfully to ${email}`)
+    }
+    catch (error) {
+      console.error(`[Job.handle] Failed to send email to ${email}`)
+      console.error('[Job.handle] Error:', error)
+      throw error // Re-throw to trigger retry
+    }
+  },
+})

package/app/Jobs/SyncSearchIndexJob.ts

@@ -0,0 +1,64 @@
+import { log } from '@stacksjs/logging'
+import { Job } from '@stacksjs/queue'
+import { useSearchEngine } from '@stacksjs/search-engine'
+
+/**
+ * Background search-index sync job (stacksjs/stacks#1891).
+ *
+ * Models declaring `traits.useSearch: { queueable: true }` dispatch
+ * to this job from their `afterCreate` / `afterUpdate` / `afterDelete`
+ * hooks instead of calling the search-engine driver inline. That
+ * keeps the request path off the network round-trip when the search
+ * backend is on a different host — slow upserts or transient
+ * Meilisearch failures don't block the user write.
+ *
+ * Payload shape (dispatched by `define-model.ts:buildSearchHooks`):
+ *   - `{ op: 'upsert', index, doc }` — create or update a document
+ *   - `{ op: 'delete', index, id }`  — remove a document by id
+ *
+ * Failures throw so the queue counts them as failed attempts and
+ * the configured backoff retries. With `tries: 5` and the default
+ * backoff, a five-minute Meilisearch outage doesn't lose writes.
+ */
+interface SyncSearchIndexPayload {
+  index: string
+  op: 'upsert' | 'delete'
+  doc?: Record<string, unknown>
+  id?: number
+}
+
+export default new Job({
+  name: 'SyncSearchIndex',
+  description: 'Sync a model write to the search engine (background)',
+  queue: 'search',
+  tries: 5,
+  backoff: [5, 15, 30, 60, 120],
+
+  async handle(payload: SyncSearchIndexPayload) {
+    if (!payload?.index || !payload?.op) {
+      throw new Error('[SyncSearchIndex] payload.index and payload.op are required')
+    }
+
+    const engine = useSearchEngine()
+
+    if (payload.op === 'upsert') {
+      if (!payload.doc) {
+        throw new Error('[SyncSearchIndex] upsert requires payload.doc')
+      }
+      await engine.addDocument(payload.index, payload.doc)
+      log.debug(`[SyncSearchIndex] upserted into ${payload.index}`)
+      return { ok: true, op: 'upsert', index: payload.index }
+    }
+
+    if (payload.op === 'delete') {
+      if (payload.id == null) {
+        throw new Error('[SyncSearchIndex] delete requires payload.id')
+      }
+      await engine.deleteDocument(payload.index, Number(payload.id))
+      log.debug(`[SyncSearchIndex] deleted ${payload.id} from ${payload.index}`)
+      return { ok: true, op: 'delete', index: payload.index, id: payload.id }
+    }
+
+    throw new Error(`[SyncSearchIndex] unknown op '${(payload as { op?: string }).op}'`)
+  },
+})

package/app/Listener.ts

@@ -0,0 +1,84 @@
+import type { StacksEvents, WildcardHandler } from '@stacksjs/events'
+import { handleError } from '@stacksjs/error-handling'
+import { emitter } from '@stacksjs/events'
+import { path as p } from '@stacksjs/path'
+import events from './Events'
+
+// Cache resolved action modules to avoid repeated dynamic imports
+const actionCache = new Map<string, { handle: (event: any) => Promise<any> | any }>()
+
+// Deduplicate in-flight imports to prevent concurrent import races
+const pendingImports = new Map<string, Promise<{ handle: (event: any) => Promise<any> | any } | null>>()
+
+// Pre-compute which event types have listeners for O(1) lookup
+const eventTypes = new Set(Object.keys(events))
+
+export async function handleEvents() {
+  emitter.on('*', listenEvents as WildcardHandler<StacksEvents>)
+}
+
+function listenEvents(type: keyof typeof events, event: any) {
+  // Fast path: skip events with no registered listeners
+  if (!eventTypes.has(type as string))
+    return
+
+  const eventListeners = events[type]
+  if (!eventListeners || eventListeners.length === 0)
+    return
+
+  // Fire-and-forget with error handling — mitt doesn't await wildcard handlers
+  processListeners(type as string, eventListeners, event)
+}
+
+async function resolveAction(listener: string): Promise<{ handle: (event: any) => Promise<any> | any } | null> {
+  // Check cache first
+  const cached = actionCache.get(listener)
+  if (cached) return cached
+
+  // Check if an import is already in-flight
+  let pending = pendingImports.get(listener)
+  if (pending) return pending
+
+  // Start the import and cache the promise to deduplicate concurrent calls
+  pending = (async () => {
+    try {
+      const imported = await import(p.appPath(`Actions/${listener}.ts`))
+      const actionModule = imported.default
+      if (actionModule && typeof actionModule.handle === 'function') {
+        actionCache.set(listener, actionModule)
+        return actionModule
+      }
+      handleError(`Action "${listener}" does not export a handle method`)
+      return null
+    }
+    catch (error) {
+      handleError(`Failed to import action "${listener}"`, error)
+      return null
+    }
+    finally {
+      pendingImports.delete(listener)
+    }
+  })()
+
+  pendingImports.set(listener, pending)
+  return pending
+}
+
+async function processListeners(type: string, listeners: string[], event: any) {
+  for (const listener of listeners) {
+    try {
+      if (typeof listener === 'function') {
+        await (listener as any)(event)
+        continue
+      }
+
+      const action = await resolveAction(listener)
+      if (action) {
+        await action.handle(event)
+      }
+    }
+    catch (error) {
+      handleError(`Failed to execute listener "${listener}" for event "${type}"`, error)
+    }
+  }
+}

package/app/Listeners/Console.ts

@@ -0,0 +1,22 @@
+import type { CLI } from '@stacksjs/types'
+import process from 'node:process'
+
+export default function (cli: CLI) {
+  // Listen to the `inspire:three` command
+  cli.on('inspire:three', () => {
+    // eslint-disable-next-line no-console
+    console.log('inspiring with three quotes')
+    // Do something
+  })
+
+  // 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)
+  })
+}