@stacksjs/defaults 0.74.2 → 0.74.4

package/app/Actions/Dashboard/Infrastructure/LogIndexAction.ts

@@ -1,16 +1,35 @@
 import type { RequestInstance } from '@stacksjs/types'
+import type { DashboardLogQuery, DashboardLogRange } from './log-provider'
 import { Action } from '@stacksjs/actions'
-import { db } from '@stacksjs/database'
 import { dashboardRequestValue } from '../dashboard-request'
 import { dashboardOperationalError } from '../dashboard-response'
-import { DASHBOARD_LOG_TYPES, normalizeDashboardLog, summarizeDashboardLogTypes } from './log-dashboard'
-
-const RANGES = ['1', '7', '30', '90', 'all'] as const
+import { DASHBOARD_LOG_TYPES } from './log-dashboard'
+import { DASHBOARD_LOG_RANGES, readDashboardLogs } from './log-provider'
 
 function queryValue(request: RequestInstance, key: string): string {
   return dashboardRequestValue(request, key)
 }
 
+/** Reads the filters off the request. Unknown values fall back rather than fail. */
+function logQuery(request: RequestInstance): DashboardLogQuery {
+  const requestedType = queryValue(request, 'type').toLowerCase()
+  const requestedRange = queryValue(request, 'range').toLowerCase()
+
+  return {
+    page: Math.max(1, Number.parseInt(queryValue(request, 'page') || '1', 10) || 1),
+    perPage: Math.min(100, Math.max(10, Number.parseInt(queryValue(request, 'per_page') || '25', 10) || 25)),
+    search: queryValue(request, 'search'),
+    type: DASHBOARD_LOG_TYPES.includes(requestedType as typeof DASHBOARD_LOG_TYPES[number])
+      ? requestedType
+      : '',
+    source: queryValue(request, 'source').toLowerCase(),
+    project: queryValue(request, 'project'),
+    range: DASHBOARD_LOG_RANGES.includes(requestedRange as DashboardLogRange)
+      ? requestedRange as DashboardLogRange
+      : '30',
+  }
+}
+
 export default new Action({
   name: 'LogIndexAction',
   description: 'Returns filtered, paginated Log model records for the dashboard.',
@@ -19,86 +38,7 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     try {
-      const requestedPage = Math.max(1, Number.parseInt(queryValue(request, 'page') || '1', 10) || 1)
-      const perPage = Math.min(100, Math.max(10, Number.parseInt(queryValue(request, 'per_page') || '25', 10) || 25))
-      const search = queryValue(request, 'search')
-      const requestedType = queryValue(request, 'type').toLowerCase()
-      const type = DASHBOARD_LOG_TYPES.includes(requestedType as typeof DASHBOARD_LOG_TYPES[number])
-        ? requestedType
-        : ''
-      const source = queryValue(request, 'source').toLowerCase()
-      const project = queryValue(request, 'project')
-      const requestedRange = queryValue(request, 'range').toLowerCase()
-      const range = RANGES.includes(requestedRange as typeof RANGES[number]) ? requestedRange : '30'
-      const cutoff = range === 'all' ? 0 : Date.now() - Number(range) * 86400000
-      const searchPattern = `%${search}%`
-
-      const applyFilters = <T extends {
-        where: (...args: any[]) => T
-        whereAny: (columns: string[], operator: string, value: unknown) => T
-      }>(query: T): T => {
-        let filtered = query
-        if (cutoff)
-          filtered = filtered.where('timestamp', '>=', cutoff)
-        if (type)
-          filtered = filtered.where('type', '=', type)
-        if (source)
-          filtered = filtered.where('source', '=', source)
-        if (project)
-          filtered = filtered.where('project', '=', project)
-        if (search)
-          filtered = filtered.whereAny(['message', 'project', 'file', 'stacktrace'], 'like', searchPattern)
-        return filtered
-      }
-
-      const [countRow, typeRows, sourceRows, projectRows] = await Promise.all([
-        applyFilters(db.selectFrom('logs').select(db.fn.count('id').as('count')))
-          .executeTakeFirst() as Promise<{ count: number | string } | undefined>,
-        applyFilters(db.selectFrom('logs').select(['type', db.fn.count('id').as('count')]))
-          .groupBy('type')
-          .execute() as Promise<Array<{ type: string, count: number | string }>>,
-        db.selectFrom('logs').select('source').distinct().orderBy('source', 'asc').limit(100).execute() as Promise<Array<{ source: string }>>,
-        db.selectFrom('logs').select('project').distinct().orderBy('project', 'asc').limit(500).execute() as Promise<Array<{ project: string }>>,
-      ])
-
-      const total = Number(countRow?.count || 0)
-      const totalPages = Math.max(1, Math.ceil(total / perPage))
-      const page = Math.min(requestedPage, totalPages)
-      const rows = await applyFilters(db.selectFrom('logs').select([
-        'id',
-        'timestamp',
-        'type',
-        'source',
-        'message',
-        'project',
-        'stacktrace',
-        'file',
-        'created_at',
-        'updated_at',
-      ]))
-        .orderBy('timestamp', 'desc')
-        .orderBy('id', 'desc')
-        .limit(perPage)
-        .offset((page - 1) * perPage)
-        .execute()
-
-      return {
-        logs: rows.map(normalizeDashboardLog),
-        summary: summarizeDashboardLogTypes(typeRows, total),
-        pagination: {
-          page,
-          perPage,
-          total,
-          totalPages,
-        },
-        options: {
-          sources: sourceRows.map(row => row.source).filter(Boolean),
-          projects: projectRows.map(row => row.project).filter(Boolean),
-          types: [...DASHBOARD_LOG_TYPES],
-          ranges: [...RANGES],
-        },
-        generatedAt: new Date().toISOString(),
-      }
+      return await readDashboardLogs(logQuery(request))
     }
     catch (error) {
       return dashboardOperationalError(error, 'Logs could not be loaded.', 'LogIndexAction')

package/app/Actions/Dashboard/Infrastructure/log-provider.ts

@@ -0,0 +1,189 @@
+import type { DashboardProviderUnavailable } from '../dashboard-provider'
+import type { DashboardLogRecord, DashboardLogSummary } from './log-dashboard'
+import { db } from '@stacksjs/database'
+import { HQ_READ_UNAVAILABLE, readThroughProvider, resolveDashboardDriver } from '../dashboard-provider'
+import { DASHBOARD_LOG_TYPES, normalizeDashboardLog, summarizeDashboardLogTypes } from './log-dashboard'
+
+/**
+ * Where the Logs section reads from.
+ *
+ * The local provider is the query that used to sit inside `LogIndexAction`,
+ * moved without changing a line of its logic: the same five statements against
+ * the `logs` table, the same filters, the same ordering, and the same clamp of
+ * a requested page down to the last page that exists.
+ *
+ * The payload deliberately reuses `DashboardLogRecord` and
+ * `DashboardLogSummary` from `log-dashboard.ts`. Three stx components import
+ * those same types, so a provider that returns the wrong shape is a compile
+ * error against the declaration the components themselves consume rather than
+ * a surprise at runtime.
+ */
+
+export const DASHBOARD_LOG_RANGES = ['1', '7', '30', '90', 'all'] as const
+
+export type DashboardLogRange = typeof DASHBOARD_LOG_RANGES[number]
+
+export interface DashboardLogQuery {
+  page: number
+  perPage: number
+  search: string
+  /** One of {@link DASHBOARD_LOG_TYPES}, or empty for every level. */
+  type: string
+  source: string
+  project: string
+  range: DashboardLogRange
+}
+
+export interface DashboardLogPagination {
+  page: number
+  perPage: number
+  total: number
+  totalPages: number
+}
+
+export interface DashboardLogOptions {
+  sources: string[]
+  projects: string[]
+  types: string[]
+  ranges: string[]
+}
+
+export interface DashboardLogPayload extends Partial<DashboardProviderUnavailable> {
+  logs: DashboardLogRecord[]
+  summary: DashboardLogSummary
+  pagination: DashboardLogPagination
+  options: DashboardLogOptions
+  generatedAt: string
+}
+
+export interface DashboardLogsProvider {
+  logs: (query: DashboardLogQuery) => Promise<DashboardLogPayload>
+}
+
+/** An empty page of logs, carrying the reason there is nothing to show. */
+export function emptyLogPayload(reason: string, query?: DashboardLogQuery): DashboardLogPayload {
+  return {
+    logs: [],
+    summary: { total: 0, error: 0, warning: 0, info: 0, success: 0 },
+    pagination: {
+      page: 1,
+      perPage: query?.perPage ?? 25,
+      total: 0,
+      totalPages: 1,
+    },
+    options: {
+      sources: [],
+      projects: [],
+      types: [...DASHBOARD_LOG_TYPES],
+      ranges: [...DASHBOARD_LOG_RANGES],
+    },
+    generatedAt: new Date().toISOString(),
+    unavailable: reason,
+  }
+}
+
+function isLogPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object')
+    return false
+  const candidate = payload as Partial<DashboardLogPayload>
+  return Array.isArray(candidate.logs)
+    && Boolean(candidate.summary)
+    && Boolean(candidate.pagination)
+    && Boolean(candidate.options)
+}
+
+/**
+ * This application's own `logs` table.
+ *
+ * Not wrapped in a catch. A failure here is a local database failure, and the
+ * action has always answered that with its operational error, which is the
+ * behaviour every existing caller and test expects.
+ */
+export const localLogsProvider: DashboardLogsProvider = {
+  async logs(query: DashboardLogQuery): Promise<DashboardLogPayload> {
+    const cutoff = query.range === 'all' ? 0 : Date.now() - Number(query.range) * 86400000
+    const searchPattern = `%${query.search}%`
+
+    const applyFilters = <T extends {
+      where: (...args: any[]) => T
+      whereAny: (columns: string[], operator: string, value: unknown) => T
+    }>(builder: T): T => {
+      let filtered = builder
+      if (cutoff)
+        filtered = filtered.where('timestamp', '>=', cutoff)
+      if (query.type)
+        filtered = filtered.where('type', '=', query.type)
+      if (query.source)
+        filtered = filtered.where('source', '=', query.source)
+      if (query.project)
+        filtered = filtered.where('project', '=', query.project)
+      if (query.search)
+        filtered = filtered.whereAny(['message', 'project', 'file', 'stacktrace'], 'like', searchPattern)
+      return filtered
+    }
+
+    const [countRow, typeRows, sourceRows, projectRows] = await Promise.all([
+      applyFilters(db.selectFrom('logs').select(db.fn.count('id').as('count')))
+        .executeTakeFirst() as Promise<{ count: number | string } | undefined>,
+      applyFilters(db.selectFrom('logs').select(['type', db.fn.count('id').as('count')]))
+        .groupBy('type')
+        .execute() as Promise<Array<{ type: string, count: number | string }>>,
+      db.selectFrom('logs').select('source').distinct().orderBy('source', 'asc').limit(100).execute() as Promise<Array<{ source: string }>>,
+      db.selectFrom('logs').select('project').distinct().orderBy('project', 'asc').limit(500).execute() as Promise<Array<{ project: string }>>,
+    ])
+
+    const total = Number(countRow?.count || 0)
+    const totalPages = Math.max(1, Math.ceil(total / query.perPage))
+    const page = Math.min(query.page, totalPages)
+    const rows = await applyFilters(db.selectFrom('logs').select([
+      'id',
+      'timestamp',
+      'type',
+      'source',
+      'message',
+      'project',
+      'stacktrace',
+      'file',
+      'created_at',
+      'updated_at',
+    ]))
+      .orderBy('timestamp', 'desc')
+      .orderBy('id', 'desc')
+      .limit(query.perPage)
+      .offset((page - 1) * query.perPage)
+      .execute()
+
+    return {
+      logs: rows.map(normalizeDashboardLog),
+      summary: summarizeDashboardLogTypes(typeRows, total),
+      pagination: {
+        page,
+        perPage: query.perPage,
+        total,
+        totalPages,
+      },
+      options: {
+        sources: sourceRows.map(row => row.source).filter(Boolean),
+        projects: projectRows.map(row => row.project).filter(Boolean),
+        types: [...DASHBOARD_LOG_TYPES],
+        ranges: [...DASHBOARD_LOG_RANGES],
+      },
+      generatedAt: new Date().toISOString(),
+    }
+  },
+}
+
+/** Reads the Logs section through whichever provider config selects. */
+export async function readDashboardLogs(query: DashboardLogQuery): Promise<DashboardLogPayload> {
+  const driver = await resolveDashboardDriver('logs')
+
+  if (driver.name === 'local')
+    return localLogsProvider.logs(query)
+
+  return readThroughProvider(
+    'logs',
+    reason => emptyLogPayload(reason, query),
+    async () => emptyLogPayload(HQ_READ_UNAVAILABLE, query),
+    isLogPayload,
+  )
+}

package/app/Actions/Dashboard/Marketing/AbandonedCartCampaignAction.ts

@@ -0,0 +1,51 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { config } from '@stacksjs/config'
+import { Campaign } from '@stacksjs/orm'
+import { response } from '@stacksjs/router'
+import { recoveryCampaignWriteData, validateRecoveryCampaign } from './abandoned-cart-records'
+import { marketingModelError } from './marketing-response'
+
+/**
+ * Write the campaign that goes after the cold carts.
+ *
+ * It is an ordinary Campaign row - the send pipeline, the delivery reporting
+ * and the campaigns screen all work on it unchanged. What makes it a recovery
+ * campaign is the segment stored on it, which names the trigger and the rules
+ * it was written with, so the campaign still says who it was for long after
+ * those carts have converted or been swept.
+ *
+ * Created as a draft, or scheduled if a time was given. Nothing sends from
+ * here: delivery goes through `CampaignSendAction` like every other campaign,
+ * so there is one place where mail actually leaves.
+ */
+export default new Action({
+  name: 'AbandonedCartCampaignAction',
+  description: 'Creates a cart-recovery campaign aimed at customers who left a cart behind.',
+  method: 'POST',
+  model: Campaign,
+
+  async handle(request: RequestInstance) {
+    const data = recoveryCampaignWriteData(
+      await request.all(),
+      String(config.commerce?.currency || 'USD').toUpperCase(),
+    )
+
+    const validationError = validateRecoveryCampaign(data)
+    if (validationError)
+      return response.json({ message: validationError }, 422)
+
+    try {
+      const campaign = await Campaign.create({
+        ...data,
+        audience_size: 0,
+        sent_count: 0,
+      })
+
+      return response.json({ id: campaign.get('id') }, 201)
+    }
+    catch (error) {
+      return marketingModelError(error, 'Recovery campaign could not be created.', 'AbandonedCartCampaignAction')
+    }
+  },
+})

package/app/Actions/Dashboard/Marketing/AbandonedCartIndexAction.ts

@@ -0,0 +1,85 @@
+import { Action } from '@stacksjs/actions'
+import { config } from '@stacksjs/config'
+import { db } from '@stacksjs/database'
+import { dashboardOperationalError } from '../dashboard-response'
+import { normalizeAbandonedCarts } from './abandoned-cart-records'
+
+/**
+ * Every cart that was filled and then left, and whatever has been done about it.
+ *
+ * Read straight from `carts` rather than from a rollup: the number a shop acts
+ * on has to be the number in the table, and a cached one drifts the moment
+ * somebody checks out.
+ *
+ * `converted` carts are fetched alongside the cold ones because recovery is
+ * only measurable as the difference between them - a dashboard that shows
+ * only what is still abandoned can say how much money is sitting there and
+ * never how much of it came back.
+ */
+export default new Action({
+  name: 'AbandonedCartIndexAction',
+  description: 'Returns abandoned carts, their recovery campaigns, and what those campaigns brought back.',
+  method: 'GET',
+  apiResponse: true,
+
+  async handle() {
+    try {
+      const carts = await db
+        .selectFrom('carts')
+        .selectAll()
+        .where('status', 'in', ['abandoned', 'expired', 'converted'])
+        .orderBy('updated_at', 'desc')
+        .limit(500)
+        .execute()
+
+      const cartIds = carts.map(cart => Number(cart.id)).filter(Number.isFinite)
+      const customerIds = [...new Set(
+        carts.map(cart => Number(cart.customer_id)).filter(id => Number.isFinite(id) && id > 0),
+      )]
+
+      /*
+       * Both of these are `in` lookups on the carts already fetched, so an
+       * empty page asks nothing rather than selecting every row in the table
+       * behind an `in ()` that some drivers read as "no filter".
+       */
+      const [items, customers, campaigns] = await Promise.all([
+        cartIds.length > 0
+          ? db.selectFrom('cart_items')
+              .select(['cart_id', 'quantity', 'product_name'])
+              .where('cart_id', 'in', cartIds)
+              .execute()
+          : Promise.resolve([]),
+        customerIds.length > 0
+          ? db.selectFrom('customers')
+              .select(['id', 'name', 'email'])
+              .where('id', 'in', customerIds)
+              .execute()
+          : Promise.resolve([]),
+        db.selectFrom('campaigns')
+          .selectAll()
+          .whereNotNull('segment_definition')
+          .orderBy('id', 'desc')
+          .limit(200)
+          .execute(),
+      ])
+
+      // Only the sends belonging to those campaigns matter, and there is no
+      // point reading a newsletter's hundred thousand rows to find out.
+      const campaignIds = campaigns.map(campaign => Number(campaign.id)).filter(Number.isFinite)
+      const sends = campaignIds.length > 0
+        ? await db.selectFrom('campaign_sends')
+            .select(['campaign_id', 'recipient', 'sent_at', 'created_at'])
+            .where('campaign_id', 'in', campaignIds)
+            .where('status', 'in', ['sent', 'delivered'])
+            .execute()
+        : []
+
+      return normalizeAbandonedCarts(carts, items, customers, campaigns, sends, {
+        defaultCurrency: String(config.commerce?.currency || 'USD').toUpperCase(),
+      })
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Abandoned carts could not be loaded.', 'AbandonedCartIndexAction')
+    }
+  },
+})