@stacksjs/commerce 0.70.53 → 0.70.55

package/src/utils/typed-stats.ts

@@ -0,0 +1,67 @@
+/**
+ * Typed helpers for the aggregate-stats queries the commerce package uses
+ * heavily. The bun-query-builder `eb` expression-builder callback is
+ * effectively `any` from the consumer side (its return type is the
+ * builder's internal `SelectExpressionList`, not exported), so without a
+ * thin wrapper every call site has to `as any` both the callback param
+ * and the awaited result. That dropped *all* type safety for column
+ * names, bindings, and result shapes — fields like `averageSize` could
+ * be renamed in one place and silently break another.
+ *
+ * These helpers give us a typed result shape (caller declares the keys)
+ * and a single localized `as any` at the bun-query-builder boundary.
+ */
+
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+
+/**
+ * Stats descriptors map: each key is the result-row alias; each value is
+ * a `{ kind, column, where? }` triple describing the aggregate to emit.
+ */
+export type StatsDescriptor =
+  | { kind: 'count', column?: string, filter?: { column: string, op: string, value: unknown } }
+  | { kind: 'sum', column: string, filter?: { column: string, op: string, value: unknown } }
+  | { kind: 'avg', column: string, filter?: { column: string, op: string, value: unknown } }
+  | { kind: 'min', column: string, filter?: { column: string, op: string, value: unknown } }
+  | { kind: 'max', column: string, filter?: { column: string, op: string, value: unknown } }
+
+/**
+ * Run a typed aggregate query against a table.
+ *
+ * @example
+ * ```ts
+ * const stats = await aggregateStats('receipts', {
+ *   total: { kind: 'count' },
+ *   success: { kind: 'count', filter: { column: 'status', op: '=', value: 'success' } },
+ *   averageSize: { kind: 'avg', column: 'size' },
+ * }, qb => qb.where('timestamp', '>=', start).where('timestamp', '<=', end))
+ * // typeof stats: { total: number; success: number; averageSize: number }
+ * ```
+ */
+export async function aggregateStats<TKeys extends string>(
+  table: string,
+  descriptors: Record<TKeys, StatsDescriptor>,
+  applyWhere?: (qb: any) => any,
+): Promise<Record<TKeys, number>> {
+  let query: any = (db as any).selectFrom(table)
+  if (applyWhere) query = applyWhere(query)
+
+  query = query.select((eb: StacksExpressionBuilder) => Object.entries(descriptors).map(([alias, d]) => {
+    const col = (d as { column?: string }).column ?? 'id'
+    let expr = eb.fn[(d as StatsDescriptor).kind](col)
+    if ((d as { filter?: unknown }).filter) {
+      const f = (d as StatsDescriptor & { filter: NonNullable<StatsDescriptor['filter']> }).filter
+      expr = expr.filterWhere(f.column, f.op, f.value)
+    }
+    return expr.as(alias)
+  }))
+
+  const row = await query.executeTakeFirst()
+  const out = {} as Record<TKeys, number>
+  for (const alias of Object.keys(descriptors) as TKeys[]) {
+    const v = row?.[alias]
+    out[alias] = typeof v === 'number' ? v : Number(v ?? 0) || 0
+  }
+  return out
+}

package/src/waitlists/index.ts

@@ -0,0 +1,19 @@
+import * as products from './products'
+import * as restaurant from './restaurant'
+
+export {
+  products,
+  restaurant,
+}
+
+interface WaitlistsNamespace {
+  products: typeof products
+  restaurant: typeof restaurant
+}
+
+const waitlists: WaitlistsNamespace = {
+  products,
+  restaurant,
+}
+
+export default waitlists

package/src/waitlists/products/destroy.ts

@@ -0,0 +1,65 @@
+type WaitlistProductJsonResponse = ModelRow<typeof WaitlistProduct>
+import { db } from '@stacksjs/database'
+
+/**
+ * Delete a waitlist product entry by ID
+ *
+ * @param id The ID of the waitlist product to delete
+ * @returns The deleted waitlist product record
+ */
+export async function destroy(id: number): Promise<WaitlistProductJsonResponse | undefined> {
+  try {
+    // First get the waitlist product to return it after deletion
+    const waitlistProduct = await db
+      .selectFrom('waitlist_products')
+      .where('id', '=', id)
+      .selectAll()
+      .executeTakeFirst()
+
+    if (!waitlistProduct)
+      return undefined
+
+    // Delete the waitlist product
+    await db
+      .deleteFrom('waitlist_products')
+      .where('id', '=', id)
+      .execute()
+
+    return waitlistProduct as WaitlistProductJsonResponse
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete waitlist product: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Delete multiple waitlist product entries by their IDs
+ *
+ * @param ids Array of waitlist product IDs to delete
+ * @returns Number of waitlist products deleted
+ */
+export async function bulkDestroy(ids: number[]): Promise<number> {
+  if (!ids.length)
+    return 0
+
+  try {
+    // Delete all waitlist products with the given IDs
+    const result = await db
+      .deleteFrom('waitlist_products')
+      .where('id', 'in', ids)
+      .execute()
+
+    return (result as any).length || 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete waitlist products in bulk: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/waitlists/products/export.ts

@@ -0,0 +1,113 @@
+type WaitlistProductJsonResponse = ModelRow<typeof WaitlistProduct>
+import type { SpreadsheetWrapper } from 'ts-spreadsheets'
+import { createSpreadsheet } from 'ts-spreadsheets'
+import { fetchAll } from './fetch'
+
+/**
+ * Represents the structure of an exported waitlist product
+ */
+export interface ExportedWaitlistProduct {
+  'ID': number
+  'Name': string
+  'Email': string
+  'Phone': string
+  'Party Size': number
+  'Notification Preference': string
+  'Source': string
+  'Status': string
+  'Created At': string
+  'Notified At': string
+  'Purchased At': string
+  'Cancelled At': string
+  'Notes': string
+}
+
+/**
+ * Export waitlist products to a spreadsheet
+ * @param format The format of the spreadsheet (default is CSV)
+ * @returns Spreadsheet object ready for download or storage
+ */
+export async function exportWaitlist(format: 'csv' | 'excel' = 'csv'): Promise<SpreadsheetWrapper> {
+  // Fetch all waitlist products
+  const waitlistProducts = await fetchAll()
+
+  // Prepare data for spreadsheet
+  const spreadsheetData = prepareWaitlistForExport(waitlistProducts)
+
+  // Create and return spreadsheet
+  return createSpreadsheet(spreadsheetData, { type: format })
+}
+
+/**
+ * Prepare waitlist data for spreadsheet export
+ * @param waitlistProducts Array of waitlist product objects
+ * @returns Spreadsheet data structure
+ */
+function prepareWaitlistForExport(waitlistProducts: WaitlistProductJsonResponse[]) {
+  // Define headings
+  const headings: (keyof ExportedWaitlistProduct)[] = [
+    'ID',
+    'Name',
+    'Email',
+    'Phone',
+    'Party Size',
+    'Notification Preference',
+    'Source',
+    'Status',
+    'Created At',
+    'Notified At',
+    'Purchased At',
+    'Cancelled At',
+    'Notes',
+  ]
+
+  // Transform waitlist products into export format
+  const data = waitlistProducts.map((product) => {
+    return [
+      product.id,
+      product.name,
+      product.email,
+      product.phone || 'N/A',
+      (product as any).party_size,
+      product.notificationPreference,
+      product.source,
+      product.status,
+      product.created_at,
+      product.notifiedAt || 'N/A',
+      product.purchasedAt || 'N/A',
+      product.cancelledAt || 'N/A',
+      product.notes || 'N/A',
+    ]
+  })
+
+  return { headings, data }
+}
+
+/**
+ * Export waitlist products and automatically download
+ * @param format The format of the spreadsheet (default is CSV)
+ * @param filename Optional filename for the download
+ * @returns Download response
+ */
+export async function downloadWaitlist(format: 'csv' | 'excel' = 'csv', filename?: string): Promise<Response> {
+  const spreadsheet = await exportWaitlist(format)
+
+  // Use default filename if not provided
+  const defaultFilename = `waitlist_export_${new Date().toISOString().split('T')[0]}.${format}`
+  return spreadsheet.download(filename || defaultFilename)
+}
+
+/**
+ * Store waitlist export to disk
+ * @param format The format of the spreadsheet (default is CSV)
+ * @param path Optional path to store the file
+ * @returns Path where the file is stored
+ */
+export async function storeWaitlistExport(format: 'csv' | 'excel' = 'csv', path?: string): Promise<void> {
+  const spreadsheet = await exportWaitlist(format)
+
+  // Use default path and filename if not provided
+  const defaultPath = `waitlist_export_${new Date().toISOString().split('T')[0]}.${format}`
+
+  spreadsheet.store(path || defaultPath)
+}

package/src/waitlists/products/fetch.ts

@@ -0,0 +1,362 @@
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+import { formatDate } from '@stacksjs/orm'
+type WaitlistProductJsonResponse = ModelRow<typeof WaitlistProduct>
+
+/**
+ * Fetch a waitlist product by ID
+ */
+export async function fetchById(id: number): Promise<WaitlistProductJsonResponse | undefined> {
+  return await db
+    .selectFrom('waitlist_products')
+    .where('id', '=', id)
+    .selectAll()
+    .executeTakeFirst() as WaitlistProductJsonResponse | undefined
+}
+
+/**
+ * Fetch all waitlist products
+ */
+export async function fetchAll(): Promise<WaitlistProductJsonResponse[]> {
+  return await db.selectFrom('waitlist_products').selectAll().execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch the count of waitlist products grouped by source
+ * @param startDate Optional start date to filter by
+ * @param endDate Optional end date to filter by
+ * @returns An object containing the count for each source
+ */
+export async function fetchCountBySource(
+  startDate?: Date,
+  _endDate?: Date,
+): Promise<Record<string, number>> {
+  let query = db
+    .selectFrom('waitlist_products')
+    .select(['source', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('source') as any
+
+  if (startDate && _endDate) {
+    const startDateStr = formatDate(startDate)
+    const endDateStr = formatDate(_endDate)
+    query = query
+      .where('created_at', '>=', startDateStr)
+      .where('created_at', '<=', endDateStr)
+  }
+
+  const results = await query.execute()
+
+  return results.reduce((acc: any, { source, count }: any) => {
+    acc[source] = count
+    return acc
+  }, {} as Record<string, number>)
+}
+
+/**
+ * Fetch the count of waitlist products for a specific date
+ * @param date The date to count entries for (defaults to today)
+ * @returns The count of entries for the specified date
+ */
+export async function fetchCountByDate(date: Date = new Date()): Promise<number> {
+  const startOfDay = new Date(date)
+  startOfDay.setHours(0, 0, 0, 0)
+
+  const endOfDay = new Date(date)
+  endOfDay.setHours(23, 59, 59, 999)
+
+  const startDateStr = formatDate(startOfDay)
+  const endDateStr = formatDate(endOfDay)
+
+  const result = await db
+    .selectFrom('waitlist_products')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('created_at', '>=', startDateStr)
+    .where('created_at', '<=', endDateStr)
+    .executeTakeFirst() as { count: number } | undefined
+
+  return result?.count ?? 0
+}
+
+/**
+ * Fetch the count of waitlist products with a specific quantity
+ * @param quantity The quantity to count orders for
+ * @returns The count of orders with the specified quantity
+ */
+export async function fetchCountByQuantity(quantity: number): Promise<number> {
+  const result = await db
+    .selectFrom('waitlist_products')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('quantity', '=', quantity)
+    .executeTakeFirst() as { count: number } | undefined
+
+  return result?.count ?? 0
+}
+
+/**
+ * Fetch the count of waitlist products grouped by quantity
+ * @param startDate Optional start date to filter by
+ * @param endDate Optional end date to filter by
+ * @returns An object containing the count for each quantity
+ */
+export async function fetchCountByAllQuantities(
+  startDate?: Date,
+  _endDate?: Date,
+): Promise<Record<number, number>> {
+  let query = db
+    .selectFrom('waitlist_products')
+    .select(['quantity', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('quantity') as any
+
+  if (startDate && _endDate) {
+    const startDateStr = formatDate(startDate)
+    const endDateStr = formatDate(_endDate)
+    query = query
+      .where('created_at', '>=', startDateStr)
+      .where('created_at', '<=', endDateStr)
+  }
+
+  const results = await query.execute()
+
+  return results.reduce((acc: any, { quantity, count }: any) => {
+    acc[quantity] = count
+    return acc
+  }, {} as Record<number, number>)
+}
+
+/**
+ * Fetch waitlist products between two dates
+ * @param startDate The start date of the range
+ * @param endDate The end date of the range
+ * @returns Array of waitlist products within the date range
+ */
+export async function fetchBetweenDates(
+  startDate: Date,
+  endDate: Date,
+): Promise<WaitlistProductJsonResponse[]> {
+  const startDateStr = formatDate(startDate)
+  const endDateStr = formatDate(endDate)
+
+  return await db
+    .selectFrom('waitlist_products')
+    .selectAll()
+    .where('created_at', '>=', startDateStr)
+    .where('created_at', '<=', endDateStr)
+    .execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch waitlist products that were notified between two dates
+ * @param startDate The start date of the range
+ * @param endDate The end date of the range
+ * @returns Array of waitlist products that were notified within the date range
+ */
+export async function fetchNotifiedBetweenDates(
+  startDate: Date,
+  endDate: Date,
+): Promise<WaitlistProductJsonResponse[]> {
+  const startDateStr = formatDate(startDate)
+  const endDateStr = formatDate(endDate)
+
+  return await db
+    .selectFrom('waitlist_products')
+    .selectAll()
+    .where('notified_at', '>=', startDateStr)
+    .where('notified_at', '<=', endDateStr)
+    .where('notified_at', 'is not', null)
+    .execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch waitlist products that were purchased between two dates
+ * @param startDate The start date of the range
+ * @param endDate The end date of the range
+ * @returns Array of waitlist products that were purchased within the date range
+ */
+export async function fetchPurchasedBetweenDates(
+  startDate: Date,
+  endDate: Date,
+): Promise<WaitlistProductJsonResponse[]> {
+  const startDateStr = formatDate(startDate)
+  const endDateStr = formatDate(endDate)
+
+  return await db
+    .selectFrom('waitlist_products')
+    .selectAll()
+    .where('purchased_at', '>=', startDateStr)
+    .where('purchased_at', '<=', endDateStr)
+    .where('purchased_at', 'is not', null)
+    .execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch waitlist products that were cancelled between two dates
+ * @param startDate The start date of the range
+ * @param endDate The end date of the range
+ * @returns Array of waitlist products that were cancelled within the date range
+ */
+export async function fetchCancelledBetweenDates(
+  startDate: Date,
+  endDate: Date,
+): Promise<WaitlistProductJsonResponse[]> {
+  const startDateStr = formatDate(startDate)
+  const endDateStr = formatDate(endDate)
+
+  return await db
+    .selectFrom('waitlist_products')
+    .selectAll()
+    .where('cancelled_at', '>=', startDateStr)
+    .where('cancelled_at', '<=', endDateStr)
+    .where('cancelled_at', 'is not', null)
+    .execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch all waitlist products with waiting status
+ * @returns Array of waitlist products with waiting status
+ */
+export async function fetchWaiting(): Promise<WaitlistProductJsonResponse[]> {
+  return await db
+    .selectFrom('waitlist_products')
+    .selectAll()
+    .where('status', '=', 'waiting')
+    .execute() as WaitlistProductJsonResponse[]
+}
+
+/**
+ * Fetch the count of waitlist products by status
+ * @param status The status to filter by
+ * @param startDate Optional start date to filter by
+ * @param endDate Optional end date to filter by
+ * @returns The count of waitlist products with the specified status
+ */
+export async function fetchCountByStatus(
+  status: string,
+  startDate?: Date,
+  _endDate?: Date,
+): Promise<number> {
+  let query = db
+    .selectFrom('waitlist_products')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('status', '=', status) as any
+
+  if (startDate && _endDate) {
+    const startDateStr = formatDate(startDate)
+    const endDateStr = formatDate(_endDate)
+    query = query
+      .where('created_at', '>=', startDateStr)
+      .where('created_at', '<=', endDateStr)
+  }
+
+  const result = await query.executeTakeFirst() as { count: number } | undefined
+  return result?.count ?? 0
+}
+
+/**
+ * Fetch conversion rates for waitlist products
+ * @param startDate Optional start date to filter by
+ * @param endDate Optional end date to filter by
+ * @returns Object containing total conversion rate and breakdown by status
+ */
+export async function fetchConversionRates(
+  _startDate?: Date,
+  _endDate?: Date,
+): Promise<{
+    totalConversionRate: number
+    statusBreakdown: Record<string, { count: number, percentage: number }>
+  }> {
+  let query = db
+    .selectFrom('waitlist_products')
+    .select(['status', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('status') as any
+
+  if (_startDate && _endDate) {
+    const startDateStr = formatDate(_startDate)
+    const endDateStr = formatDate(_endDate)
+    query = query
+      .where('created_at', '>=', startDateStr)
+      .where('created_at', '<=', endDateStr)
+  }
+
+  const results = await query.execute()
+
+  // Calculate total count and purchased count
+  const totalCount = results.reduce((sum: any, { count }: any) => sum + count, 0)
+  const purchasedCount = results.find((r: any) => r.status === 'purchased')?.count ?? 0
+
+  // Calculate conversion rate
+  const totalConversionRate = totalCount > 0 ? (purchasedCount / totalCount) * 100 : 0
+
+  // Create status breakdown with percentages
+  const statusBreakdown = results.reduce((acc: any, { status, count }: any) => {
+    acc[status as string] = {
+      count,
+      percentage: totalCount > 0 ? (count / totalCount) * 100 : 0,
+    }
+    return acc
+  }, {} as Record<string, { count: number, percentage: number }>)
+
+  return {
+    totalConversionRate,
+    statusBreakdown,
+  }
+}
+
+/**
+ * Fetch the count of waitlist products between two dates
+ * @param startDate The start date of the range
+ * @param endDate The end date of the range
+ * @returns The count of waitlist products within the date range
+ */
+export async function fetchCountBetweenDates(
+  startDate: Date,
+  endDate: Date,
+): Promise<number> {
+  const startDateStr = formatDate(startDate)
+  const endDateStr = formatDate(endDate)
+
+  const result = await db
+    .selectFrom('waitlist_products')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('created_at', '>=', startDateStr)
+    .where('created_at', '<=', endDateStr)
+    .executeTakeFirst() as { count: number } | undefined
+
+  return result?.count ?? 0
+}
+
+/**
+ * Fetch the count of waitlist products grouped by date
+ * @param startDate Optional start date to filter by
+ * @param endDate Optional end date to filter by
+ * @returns An array of objects containing date and count
+ */
+export async function fetchCountByDateGrouped(
+  startDate?: Date,
+  _endDate?: Date,
+): Promise<{ date: string, count: number }[]> {
+  let query = db
+    .selectFrom('waitlist_products')
+    .select(['created_at'])
+
+  if (startDate && _endDate) {
+    const startDateStr = formatDate(startDate)
+    const endDateStr = formatDate(_endDate)
+    query = query
+      .where('created_at', '>=', startDateStr)
+      .where('created_at', '<=', endDateStr)
+  }
+
+  const results = await query.execute()
+
+  // Group by date and count
+  const dateCounts = results.reduce((acc: any, { created_at }: any) => {
+    const date = (created_at || '').split('T')[0] || 'unknown' // Get YYYY-MM-DD
+    acc[date] = (acc[date] || 0) + 1
+    return acc
+  }, {} as Record<string, number>)
+
+  // Convert to array and sort by date
+  return Object.entries(dateCounts)
+    .map(([date, count]) => ({ date, count: count as number }))
+    .sort((a, b) => a.date.localeCompare(b.date))
+}

package/src/waitlists/products/index.ts

@@ -0,0 +1,33 @@
+// Functions from destroy.ts
+export {
+  bulkDestroy,
+  destroy,
+} from './destroy'
+
+export {
+  fetchAll,
+  fetchById,
+  fetchCancelledBetweenDates,
+  fetchConversionRates,
+  fetchCountBetweenDates,
+  fetchCountByAllQuantities,
+  fetchCountByDate,
+  fetchCountByDateGrouped,
+  fetchCountByQuantity,
+  fetchCountBySource,
+  fetchCountByStatus,
+  fetchNotifiedBetweenDates,
+  fetchPurchasedBetweenDates,
+  fetchWaiting,
+} from './fetch'
+
+export {
+  bulkStore,
+  store,
+} from './store'
+
+export {
+  update,
+  updatePartySize,
+  updateStatus,
+} from './update'