@stacksjs/defaults 0.70.229 → 0.70.231

package/app/Actions/Dashboard/Analytics/request-analytics.ts

@@ -0,0 +1,286 @@
+export type AnalyticsRange = 'day' | 'week' | 'month' | 'year'
+export type AnalyticsScope = 'all' | 'blog' | 'commerce'
+
+export interface RequestAnalyticsRow {
+  method: string
+  path: string
+  statusCode: number
+  durationMs: number
+  ipAddress: string
+  userAgent: string
+  createdAt: string
+}
+
+export interface AnalyticsModelRecord {
+  get: (key: string) => unknown
+}
+
+interface TrafficBucket {
+  date: string
+  pageViews: number
+  visitors: number
+}
+
+const RANGE_DAYS: Record<AnalyticsRange, number> = {
+  day: 1,
+  week: 7,
+  month: 30,
+  year: 365,
+}
+
+const SCOPE_PREFIXES: Record<Exclude<AnalyticsScope, 'all'>, string[]> = {
+  blog: ['/blog'],
+  commerce: ['/commerce', '/products', '/product', '/cart', '/checkout', '/orders'],
+}
+
+export function normalizeAnalyticsRange(value: unknown): AnalyticsRange {
+  if (value === null || value === undefined || value === '')
+    return 'month'
+  if (typeof value !== 'string')
+    throw new TypeError('Analytics range must be a string.')
+
+  const range = value.trim().toLowerCase()
+  if (!['day', 'week', 'month', 'year'].includes(range))
+    throw new RangeError('Analytics range must be day, week, month, or year.')
+  return range as AnalyticsRange
+}
+
+export function normalizeAnalyticsScope(value: unknown): AnalyticsScope {
+  if (value === null || value === undefined || value === '')
+    return 'all'
+  if (typeof value !== 'string')
+    throw new TypeError('Analytics scope must be a string.')
+
+  const scope = value.trim().toLowerCase()
+  if (!['all', 'blog', 'commerce'].includes(scope))
+    throw new RangeError('Analytics scope must be all, blog, or commerce.')
+  return scope as AnalyticsScope
+}
+
+function timestamp(value: string): number {
+  if (!value)
+    return Number.NaN
+  const normalized = /^\d{4}-\d{2}-\d{2} \d/.test(value)
+    ? `${value.replace(' ', 'T')}Z`
+    : value
+  return new Date(normalized).getTime()
+}
+
+function requiredRecordString(record: AnalyticsModelRecord, key: string): string {
+  const value = record.get(key)
+  if (typeof value !== 'string' || !value.trim())
+    throw new TypeError(`Request.${key} must be a non-empty string.`)
+  return value
+}
+
+function optionalRecordString(record: AnalyticsModelRecord, key: string): string {
+  const value = record.get(key)
+  if (value === null || value === undefined)
+    return ''
+  if (typeof value !== 'string')
+    throw new TypeError(`Request.${key} must be a string or null.`)
+  return value
+}
+
+function recordNumber(record: AnalyticsModelRecord, key: string): number {
+  const value = record.get(key)
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string' && value.trim() ? Number(value) : Number.NaN
+  if (!Number.isFinite(parsed))
+    throw new TypeError(`Request.${key} must be a finite number.`)
+  return parsed
+}
+
+export function requestAnalyticsRow(record: AnalyticsModelRecord): RequestAnalyticsRow {
+  const method = requiredRecordString(record, 'method').toUpperCase()
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD'].includes(method))
+    throw new TypeError('Request.method contains an unsupported HTTP method.')
+
+  const statusCode = recordNumber(record, 'status_code')
+  if (!Number.isInteger(statusCode) || statusCode < 100 || statusCode > 599)
+    throw new TypeError('Request.status_code must be an integer from 100 to 599.')
+
+  const durationMs = recordNumber(record, 'duration_ms')
+  if (durationMs < 0)
+    throw new TypeError('Request.duration_ms cannot be negative.')
+
+  const createdAt = requiredRecordString(record, 'created_at')
+  if (!Number.isFinite(timestamp(createdAt)))
+    throw new TypeError('Request.created_at must be a valid timestamp.')
+
+  return {
+    method,
+    path: requiredRecordString(record, 'path'),
+    statusCode,
+    durationMs,
+    ipAddress: optionalRecordString(record, 'ip_address'),
+    userAgent: optionalRecordString(record, 'user_agent'),
+    createdAt,
+  }
+}
+
+function pagePath(value: string): string {
+  try {
+    return new URL(value, 'http://stacks.local').pathname || '/'
+  }
+  catch {
+    return value.startsWith('/') ? value : `/${value}`
+  }
+}
+
+function isPageRequest(row: RequestAnalyticsRow): boolean {
+  const path = pagePath(row.path)
+  return row.method.toUpperCase() === 'GET'
+    && row.statusCode < 400
+    && !path.startsWith('/api/')
+    && !path.startsWith('/__')
+    && !/\.(?:css|js|map|png|jpe?g|gif|svg|ico|woff2?|ttf)$/i.test(path)
+}
+
+function matchesScope(row: RequestAnalyticsRow, scope: AnalyticsScope): boolean {
+  if (scope === 'all')
+    return true
+  const path = pagePath(row.path)
+  return SCOPE_PREFIXES[scope].some(prefix => path === prefix || path.startsWith(`${prefix}/`))
+}
+
+function browserName(userAgent: string): string {
+  if (/Edg\//i.test(userAgent)) return 'Edge'
+  if (/Firefox\//i.test(userAgent)) return 'Firefox'
+  if (/Chrome\//i.test(userAgent)) return 'Chrome'
+  if (/Safari\//i.test(userAgent)) return 'Safari'
+  return userAgent ? 'Other' : 'Unknown'
+}
+
+function deviceName(userAgent: string): string {
+  if (/iPad|Tablet/i.test(userAgent)) return 'Tablet'
+  if (/Mobile|Android|iPhone/i.test(userAgent)) return 'Phone'
+  return userAgent ? 'Desktop' : 'Unknown'
+}
+
+function percentage(value: number, total: number): number {
+  return total > 0 ? Math.round((value / total) * 1000) / 10 : 0
+}
+
+function dateKey(time: number, range: AnalyticsRange): string {
+  const date = new Date(time)
+  if (range === 'day')
+    return `${String(date.getUTCHours()).padStart(2, '0')}:00`
+  if (range === 'year')
+    return date.toISOString().slice(0, 7)
+  return date.toISOString().slice(0, 10)
+}
+
+function trafficSeries(rows: RequestAnalyticsRow[], range: AnalyticsRange): TrafficBucket[] {
+  const buckets = new Map<string, { pageViews: number, visitors: Set<string> }>()
+  for (const row of rows) {
+    const key = dateKey(timestamp(row.createdAt), range)
+    const bucket = buckets.get(key) || { pageViews: 0, visitors: new Set<string>() }
+    bucket.pageViews++
+    if (row.ipAddress)
+      bucket.visitors.add(row.ipAddress)
+    buckets.set(key, bucket)
+  }
+
+  return [...buckets.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([date, bucket]) => ({
+      date,
+      pageViews: bucket.pageViews,
+      visitors: bucket.visitors.size,
+    }))
+}
+
+function groupedBreakdown(
+  rows: RequestAnalyticsRow[],
+  keyFor: (row: RequestAnalyticsRow) => string,
+): Array<{ name: string, visitors: number, percentage: number }> {
+  const groups = new Map<string, Set<string>>()
+  for (const row of rows) {
+    const key = keyFor(row)
+    const visitors = groups.get(key) || new Set<string>()
+    if (row.ipAddress)
+      visitors.add(row.ipAddress)
+    groups.set(key, visitors)
+  }
+  const total = [...groups.values()].reduce((sum, visitors) => sum + visitors.size, 0)
+
+  return [...groups.entries()]
+    .map(([name, visitors]) => ({
+      name,
+      visitors: visitors.size,
+      percentage: percentage(visitors.size, total),
+    }))
+    .sort((left, right) => right.visitors - left.visitors)
+}
+
+export function buildWebAnalytics(
+  allRows: RequestAnalyticsRow[],
+  range: AnalyticsRange,
+  now = new Date(),
+  scope: AnalyticsScope = 'all',
+) {
+  const start = new Date(now.getTime() - RANGE_DAYS[range] * 24 * 60 * 60 * 1000)
+  const rows = allRows.filter(row =>
+    timestamp(row.createdAt) >= start.getTime()
+    && timestamp(row.createdAt) <= now.getTime()
+    && matchesScope(row, scope),
+  )
+  const pages = rows.filter(isPageRequest)
+  const visitors = new Set(pages.map(row => row.ipAddress).filter(Boolean))
+  const errors = rows.filter(row => row.statusCode >= 400).length
+  const successful = rows.filter(row => row.statusCode > 0 && row.statusCode < 400).length
+  const durationSamples = rows.map(row => row.durationMs).filter(value => value > 0)
+  const averageDuration = durationSamples.length > 0
+    ? Math.round(durationSamples.reduce((sum, value) => sum + value, 0) / durationSamples.length)
+    : 0
+
+  const pageGroups = new Map<string, { views: number, visitors: Set<string> }>()
+  for (const row of pages) {
+    const path = pagePath(row.path)
+    const page = pageGroups.get(path) || { views: 0, visitors: new Set<string>() }
+    page.views++
+    if (row.ipAddress)
+      page.visitors.add(row.ipAddress)
+    pageGroups.set(path, page)
+  }
+
+  const pageData = [...pageGroups.entries()]
+    .map(([path, page]) => ({
+      path,
+      entries: page.views,
+      visitors: page.visitors.size,
+      views: page.views,
+      percentage: percentage(page.views, pages.length),
+    }))
+    .sort((left, right) => right.views - left.views)
+    .slice(0, 10)
+
+  const realtimeStart = now.getTime() - 5 * 60 * 1000
+  const realtime = new Set(pages.filter(row => timestamp(row.createdAt) >= realtimeStart).map(row => row.ipAddress).filter(Boolean)).size
+
+  return {
+    source: 'requests',
+    range,
+    scope,
+    dateRange: {
+      start: start.toISOString(),
+      end: now.toISOString(),
+    },
+    overview: {
+      realtimeVisitors: realtime,
+      uniqueVisitors: visitors.size,
+      pageViews: pages.length,
+      averageResponseTime: averageDuration > 0 ? `${averageDuration} ms` : '-',
+      errorRate: rows.length > 0 ? `${percentage(errors, rows.length)}%` : 'N/A',
+      successfulRequests: successful,
+    },
+    traffic: trafficSeries(pages, range),
+    pages: pageData,
+    referrers: [],
+    devices: groupedBreakdown(pages, row => deviceName(row.userAgent)),
+    browsers: groupedBreakdown(pages, row => browserName(row.userAgent)),
+    countries: [],
+  }
+}

package/app/Actions/Dashboard/Analytics/sales-analytics.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test'
+import { buildSalesAnalytics } from './sales-analytics'
+
+const now = new Date('2026-07-29T12:00:00.000Z')
+
+describe('sales analytics', () => {
+  test('keeps currencies separate and uses recorded payment methods', () => {
+    const result = buildSalesAnalytics(
+      [
+        { id: '1', status: 'DELIVERED', totalAmount: 120, currency: 'USD', createdAt: '2026-07-29T10:00:00.000Z' },
+        { id: '2', status: 'CANCELED', totalAmount: 50, currency: 'USD', createdAt: '2026-07-29T10:30:00.000Z' },
+        { id: '3', status: 'DELIVERED', totalAmount: 80, currency: 'EUR', createdAt: '2026-07-29T11:00:00.000Z' },
+      ],
+      [
+        { method: 'creditCard', status: 'completed', amount: 120, refundAmount: 0, currency: 'USD', createdAt: '2026-07-29T10:00:00.000Z' },
+        { method: 'paypal', status: 'refunded', amount: 50, refundAmount: 0, currency: 'USD', createdAt: '2026-07-29T10:30:00.000Z' },
+        { method: 'creditCard', status: 'completed', amount: 80, refundAmount: 0, currency: 'EUR', createdAt: '2026-07-29T11:00:00.000Z' },
+      ],
+      [],
+      [],
+      [],
+      'day',
+      now,
+    )
+
+    expect(result.currencyTotals).toEqual([
+      { currency: 'USD', orders: 2, gross: 170, cancelled: 50, net: 120, average: 85 },
+      { currency: 'EUR', orders: 1, gross: 80, cancelled: 0, net: 80, average: 80 },
+    ])
+    expect(result.paymentMethods.map(method => `${method.method}:${method.currency}`)).toEqual(['Credit Card:EUR', 'Credit Card:USD', 'Paypal:USD'])
+    expect(result.paymentMethods.find(method => method.method === 'Paypal')?.refunds).toBe(50)
+  })
+
+  test('aggregates recorded order items by product and category', () => {
+    const result = buildSalesAnalytics(
+      [{ id: '1', status: 'DELIVERED', totalAmount: 75, currency: 'USD', createdAt: '2026-07-29T10:00:00.000Z' }],
+      [],
+      [
+        { orderId: '1', productId: '10', quantity: 2, price: 25 },
+        { orderId: '1', productId: '10', quantity: 1, price: 25 },
+      ],
+      [{ id: '10', name: 'Native Kit', categoryId: '4' }],
+      [{ id: '4', name: 'Tools' }],
+      'month',
+      now,
+    )
+
+    expect(result.topProducts).toEqual([{
+      id: '10:USD',
+      productId: '10',
+      name: 'Native Kit',
+      categoryId: '4',
+      quantity: 3,
+      revenue: 75,
+      currency: 'USD',
+    }])
+    expect(result.categories).toEqual([{
+      id: '4:USD',
+      categoryId: '4',
+      name: 'Tools',
+      quantity: 3,
+      revenue: 75,
+      currency: 'USD',
+    }])
+  })
+})

package/app/Actions/Dashboard/Analytics/sales-analytics.ts

@@ -0,0 +1,226 @@
+import type { AnalyticsRange } from './request-analytics'
+
+export interface SalesOrderRow {
+  id: string
+  status: string
+  totalAmount: number
+  currency: string
+  createdAt: string
+}
+
+export interface SalesPaymentRow {
+  method: string
+  status: string
+  amount: number
+  refundAmount: number
+  currency: string
+  createdAt: string
+}
+
+export interface SalesOrderItemRow {
+  orderId: string
+  productId: string
+  quantity: number
+  price: number
+}
+
+export interface SalesProductRow {
+  id: string
+  name: string
+  categoryId: string
+}
+
+export interface SalesCategoryRow {
+  id: string
+  name: string
+}
+
+const RANGE_DAYS: Record<AnalyticsRange, number> = {
+  day: 1,
+  week: 7,
+  month: 30,
+  year: 365,
+}
+
+function timestamp(value: string): number {
+  if (!value)
+    return Number.NaN
+  const normalized = /^\d{4}-\d{2}-\d{2} \d/.test(value)
+    ? `${value.replace(' ', 'T')}Z`
+    : value
+  return new Date(normalized).getTime()
+}
+
+function normalizeCurrency(value: string): string {
+  return value.trim().toUpperCase() || 'USD'
+}
+
+function isCancelled(status: string): boolean {
+  return ['canceled', 'cancelled'].includes(status.toLowerCase())
+}
+
+function paymentRefund(payment: SalesPaymentRow): number {
+  const status = payment.status.toLowerCase()
+  if (status === 'refunded')
+    return payment.refundAmount > 0 ? payment.refundAmount : payment.amount
+  if (status === 'partiallyrefunded' || status === 'partially_refunded')
+    return payment.refundAmount
+  return 0
+}
+
+function percentage(value: number, total: number): number {
+  return total > 0 ? Math.round((value / total) * 1000) / 10 : 0
+}
+
+function titleCase(value: string): string {
+  return value
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .replace(/\b\w/g, letter => letter.toUpperCase())
+}
+
+export function buildSalesAnalytics(
+  allOrders: SalesOrderRow[],
+  allPayments: SalesPaymentRow[],
+  orderItems: SalesOrderItemRow[],
+  products: SalesProductRow[],
+  categories: SalesCategoryRow[],
+  range: AnalyticsRange,
+  now = new Date(),
+) {
+  const start = new Date(now.getTime() - RANGE_DAYS[range] * 24 * 60 * 60 * 1000)
+  const inRange = (createdAt: string) => timestamp(createdAt) >= start.getTime() && timestamp(createdAt) <= now.getTime()
+  const orders = allOrders.filter(order => inRange(order.createdAt))
+  const payments = allPayments.filter(payment => inRange(payment.createdAt))
+
+  const currencyMap = new Map<string, { gross: number, cancelled: number, orders: number }>()
+  for (const order of orders) {
+    const currency = normalizeCurrency(order.currency)
+    const total = currencyMap.get(currency) || { gross: 0, cancelled: 0, orders: 0 }
+    total.gross += order.totalAmount
+    total.orders++
+    if (isCancelled(order.status))
+      total.cancelled += order.totalAmount
+    currencyMap.set(currency, total)
+  }
+
+  const currencyTotals = [...currencyMap.entries()]
+    .map(([currency, total]) => ({
+      currency,
+      orders: total.orders,
+      gross: total.gross,
+      cancelled: total.cancelled,
+      net: total.gross - total.cancelled,
+      average: total.orders > 0 ? Math.round((total.gross / total.orders) * 100) / 100 : 0,
+    }))
+    .sort((left, right) => right.net - left.net)
+
+  const paymentMap = new Map<string, { method: string, currency: string, amount: number, refunds: number, transactions: number }>()
+  for (const payment of payments) {
+    const currency = normalizeCurrency(payment.currency)
+    const key = `${payment.method}:${currency}`
+    const total = paymentMap.get(key) || {
+      method: titleCase(payment.method || 'unknown'),
+      currency,
+      amount: 0,
+      refunds: 0,
+      transactions: 0,
+    }
+    total.amount += payment.amount
+    total.refunds += paymentRefund(payment)
+    total.transactions++
+    paymentMap.set(key, total)
+  }
+  const totalPaymentTransactions = payments.length
+  const paymentMethods = [...paymentMap.values()]
+    .map(method => ({
+      ...method,
+      net: method.amount - method.refunds,
+      percentage: percentage(method.transactions, totalPaymentTransactions),
+    }))
+    .sort((left, right) =>
+      right.transactions - left.transactions
+      || left.method.localeCompare(right.method)
+      || left.currency.localeCompare(right.currency),
+    )
+
+  const dailyMap = new Map<string, { date: string, currency: string, value: number, orders: number }>()
+  for (const order of orders) {
+    const date = new Date(timestamp(order.createdAt)).toISOString().slice(0, 10)
+    const currency = normalizeCurrency(order.currency)
+    const key = `${date}:${currency}`
+    const total = dailyMap.get(key) || { date, currency, value: 0, orders: 0 }
+    total.value += order.totalAmount
+    total.orders++
+    dailyMap.set(key, total)
+  }
+  const dailyOrders = [...dailyMap.values()]
+    .sort((left, right) => right.date.localeCompare(left.date))
+    .slice(0, 30)
+
+  const productMap = new Map(products.map(product => [product.id, product]))
+  const categoryMap = new Map(categories.map(category => [category.id, category]))
+  const ordersById = new Map(orders.map(order => [order.id, order]))
+  const productTotals = new Map<string, { productId: string, name: string, quantity: number, revenue: number, categoryId: string, currency: string }>()
+  for (const item of orderItems) {
+    const order = ordersById.get(item.orderId)
+    if (!order)
+      continue
+    const product = productMap.get(item.productId)
+    const currency = normalizeCurrency(order.currency)
+    const key = `${item.productId}:${currency}`
+    const current = productTotals.get(key) || {
+      productId: item.productId,
+      name: product?.name || `Product ${item.productId}`,
+      quantity: 0,
+      revenue: 0,
+      categoryId: product?.categoryId || '',
+      currency,
+    }
+    current.quantity += item.quantity
+    current.revenue += item.quantity * item.price
+    productTotals.set(key, current)
+  }
+  const topProducts = [...productTotals.entries()]
+    .map(([id, product]) => ({ id, ...product }))
+    .sort((left, right) => right.revenue - left.revenue)
+    .slice(0, 10)
+
+  const categoryTotals = new Map<string, { categoryId: string, name: string, quantity: number, revenue: number, currency: string }>()
+  for (const product of topProducts) {
+    const categoryId = product.categoryId || 'uncategorized'
+    const id = `${categoryId}:${product.currency}`
+    const current = categoryTotals.get(id) || {
+      categoryId,
+      name: categoryMap.get(categoryId)?.name || 'Uncategorized',
+      quantity: 0,
+      revenue: 0,
+      currency: product.currency,
+    }
+    current.quantity += product.quantity
+    current.revenue += product.revenue
+    categoryTotals.set(id, current)
+  }
+
+  return {
+    source: 'models' as const,
+    range,
+    dateRange: {
+      start: start.toISOString(),
+      end: now.toISOString(),
+    },
+    overview: {
+      orders: orders.length,
+      payments: payments.length,
+      refunds: payments.filter(payment => paymentRefund(payment) > 0).length,
+      currencies: new Set([...orders.map(order => normalizeCurrency(order.currency)), ...payments.map(payment => normalizeCurrency(payment.currency))]).size,
+    },
+    currencyTotals,
+    paymentMethods,
+    dailyOrders,
+    topProducts,
+    categories: [...categoryTotals.entries()]
+      .map(([id, category]) => ({ id, ...category }))
+      .sort((left, right) => right.revenue - left.revenue),
+  }
+}

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

@@ -0,0 +1,57 @@
+import type { ConfiguredAIOptions } from '@stacksjs/ai'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { buddyState, createAIClient } from '@stacksjs/ai'
+import { config } from '@stacksjs/config'
+import { response } from '@stacksjs/router'
+import { buddySystemPrompt, isBuddyProviderConfigured, publicBuddyHistory, resolveBuddyProvider } from './buddy-chat'
+
+export default new Action({
+  name: 'BuddyChatAction',
+  description: 'Answers a framework question with the configured AI provider without modifying files.',
+  method: 'POST',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    const message = String(request.get('message') || '').trim()
+    if (message.length < 3)
+      return response.json({ message: 'Question must be at least 3 characters.' }, 422)
+    if (message.length > 4_000)
+      return response.json({ message: 'Question must be 4,000 characters or fewer.' }, 422)
+
+    const aiConfig = (config.ai || {}) as ConfiguredAIOptions
+    const provider = resolveBuddyProvider(aiConfig)
+    if (!isBuddyProviderConfigured(provider, aiConfig, process.env)) {
+      return response.json({
+        message: `${provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY'} is not configured.`,
+      }, 503)
+    }
+
+    try {
+      const history = publicBuddyHistory(buddyState.getState().conversationHistory, 20)
+      const result = await createAIClient(aiConfig, provider).generate(
+        [...history, { role: 'user', content: message }],
+        {
+          system: buddySystemPrompt(),
+          maxTokens: 1_200,
+          temperature: 0.2,
+        },
+      )
+
+      buddyState.addToHistory({ role: 'user', content: message })
+      buddyState.addToHistory({ role: 'assistant', content: result.content })
+
+      return {
+        content: result.content,
+        provider,
+        model: result.model,
+        usage: result.usage || null,
+      }
+    }
+    catch (error) {
+      return response.json({
+        message: error instanceof Error ? error.message : 'Buddy could not answer the question.',
+      }, 502)
+    }
+  },
+})

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

@@ -0,0 +1,14 @@
+import { Action } from '@stacksjs/actions'
+import { buddyState } from '@stacksjs/ai'
+
+export default new Action({
+  name: 'BuddyChatClearAction',
+  description: 'Clears the in-process Buddy chat history.',
+  method: 'POST',
+  apiResponse: true,
+
+  async handle() {
+    buddyState.clearHistory()
+    return { success: true }
+  },
+})

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

@@ -0,0 +1,31 @@
+import type { ConfiguredAIOptions } from '@stacksjs/ai'
+import { Action } from '@stacksjs/actions'
+import { buddyState } from '@stacksjs/ai'
+import { config } from '@stacksjs/config'
+import { publicBuddyHistory, isBuddyProviderConfigured, resolveBuddyProvider } from './buddy-chat'
+
+export default new Action({
+  name: 'BuddyChatStateAction',
+  description: 'Returns the provider readiness and in-process Buddy chat history.',
+  method: 'GET',
+  apiResponse: true,
+
+  async handle() {
+    const aiConfig = (config.ai || {}) as ConfiguredAIOptions
+    const provider = resolveBuddyProvider(aiConfig)
+    const state = buddyState.getState()
+
+    return {
+      provider,
+      configured: isBuddyProviderConfigured(provider, aiConfig, process.env),
+      history: publicBuddyHistory(state.conversationHistory),
+      repository: state.repo
+        ? {
+            name: state.repo.name,
+            branch: state.repo.branch,
+            path: state.repo.path,
+          }
+        : null,
+    }
+  },
+})