@stacksjs/commerce 0.70.53 → 0.70.55

package/src/payments/fetch.ts

@@ -0,0 +1,288 @@
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+import { formatDate } from '@stacksjs/orm'
+type PaymentJsonResponse = ModelRow<typeof Payment>
+
+/**
+ * Payment statistics response interface
+ */
+export interface PaymentStats {
+  total_transactions: number
+  total_revenue: number
+  average_transaction: number
+  successful_rate: number
+  comparison: {
+    transactions: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    revenue: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    average: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+  }
+}
+
+export async function fetchAll(): Promise<PaymentJsonResponse[]> {
+  return await db
+    .selectFrom('payments')
+    .selectAll()
+    .execute() as PaymentJsonResponse[]
+}
+
+export async function fetchById(id: number): Promise<PaymentJsonResponse | undefined> {
+  return await db
+    .selectFrom('payments')
+    .selectAll()
+    .where('id', '=', id)
+    .executeTakeFirst() as PaymentJsonResponse | undefined
+}
+
+/**
+ * Fetch payment statistics for a specific time period
+ *
+ * @param daysRange Number of days to look back (7, 30, 60, etc.)
+ */
+export async function fetchPaymentStats(daysRange: number = 30): Promise<PaymentStats> {
+  const today = new Date()
+
+  // Current period (last N days)
+  const currentPeriodStart = new Date(today)
+  currentPeriodStart.setDate(today.getDate() - daysRange)
+
+  // Previous period (N days before the current period)
+  const previousPeriodEnd = new Date(currentPeriodStart)
+  previousPeriodEnd.setDate(previousPeriodEnd.getDate() - 1)
+
+  const previousPeriodStart = new Date(previousPeriodEnd)
+  previousPeriodStart.setDate(previousPeriodEnd.getDate() - daysRange)
+
+  // Get current period stats for completed payments
+  const currentStats = await db
+    .selectFrom('payments')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('transaction_count'),
+      eb.fn.sum('amount').as('total_revenue'),
+    ]) as any)
+    .where('created_at', '>=', formatDate(currentPeriodStart))
+    .where('created_at', '<=', formatDate(today))
+    .where('status', '=', 'completed')
+    .executeTakeFirst() as { transaction_count: number, total_revenue: number } | undefined
+
+  // Get previous period stats for completed payments
+  const previousStats = await db
+    .selectFrom('payments')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('transaction_count'),
+      eb.fn.sum('amount').as('total_revenue'),
+    ]) as any)
+    .where('created_at', '>=', formatDate(previousPeriodStart))
+    .where('created_at', '<=', formatDate(previousPeriodEnd))
+    .where('status', '=', 'completed')
+    .executeTakeFirst() as { transaction_count: number, total_revenue: number } | undefined
+
+  // Get total transactions count (including non-completed ones) for calculating success rate
+  const totalTransactions = await db
+    .selectFrom('payments')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .where('created_at', '>=', formatDate(currentPeriodStart))
+    .where('created_at', '<=', formatDate(today))
+    .executeTakeFirst() as { count: number } | undefined
+
+  // Calculate current period stats
+  const currentTransactions = Number(currentStats?.transaction_count || 0)
+  const currentRevenue = Number(currentStats?.total_revenue || 0)
+  const currentAverage = currentTransactions > 0 ? currentRevenue / currentTransactions : 0
+
+  // Calculate previous period stats
+  const previousTransactions = Number(previousStats?.transaction_count || 0)
+  const previousRevenue = Number(previousStats?.total_revenue || 0)
+  const previousAverage = previousTransactions > 0 ? previousRevenue / previousTransactions : 0
+
+  // Calculate differences
+  const transactionDifference = currentTransactions - previousTransactions
+  const revenueDifference = currentRevenue - previousRevenue
+  const averageDifference = currentAverage - previousAverage
+
+  // Calculate percentage changes
+  const transactionPercentage = previousTransactions > 0
+    ? (transactionDifference / previousTransactions) * 100
+    : (currentTransactions > 0 ? 100 : 0)
+
+  const revenuePercentage = previousRevenue > 0
+    ? (revenueDifference / previousRevenue) * 100
+    : (currentRevenue > 0 ? 100 : 0)
+
+  const averagePercentage = previousAverage > 0
+    ? (averageDifference / previousAverage) * 100
+    : (currentAverage > 0 ? 100 : 0)
+
+  // Calculate success rate
+  const allTransactions = Number(totalTransactions?.count || 0)
+  const successRate = allTransactions > 0
+    ? (currentTransactions / allTransactions) * 100
+    : 0
+
+  return {
+    total_transactions: currentTransactions,
+    total_revenue: currentRevenue,
+    average_transaction: currentAverage,
+    successful_rate: successRate,
+    comparison: {
+      transactions: {
+        difference: transactionDifference,
+        percentage: Math.abs(transactionPercentage),
+        is_increase: transactionDifference >= 0,
+      },
+      revenue: {
+        difference: revenueDifference,
+        percentage: Math.abs(revenuePercentage),
+        is_increase: revenueDifference >= 0,
+      },
+      average: {
+        difference: averageDifference,
+        percentage: Math.abs(averagePercentage),
+        is_increase: averageDifference >= 0,
+      },
+    },
+  }
+}
+
+/**
+ * Fetch payment statistics by payment method
+ *
+ * @param daysRange Number of days to look back
+ */
+export async function fetchPaymentStatsByMethod(_daysRange: number = 30): Promise<Record<string, {
+  count: number
+  revenue: number
+  percentage_of_total: number
+}>> {
+  const today = new Date()
+
+  const startDate = new Date(today)
+  startDate.setDate(today.getDate() - _daysRange)
+
+  // Get total stats for the period
+  const totalStats = await db
+    .selectFrom('payments')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('total_count'),
+      eb.fn.sum('amount').as('total_revenue'),
+    ]) as any)
+    .where('created_at', '>=', formatDate(startDate))
+    .where('created_at', '<=', formatDate(today))
+    .where('status', '=', 'completed')
+    .executeTakeFirst() as { total_count: number, total_revenue: number } | undefined
+
+  const totalCount = Number(totalStats?.total_count || 0)
+
+  // Get stats grouped by payment method
+  const methodStats = await db
+    .selectFrom('payments')
+    .select([
+      'method',
+      (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count'),
+      (eb: StacksExpressionBuilder) => eb.fn.sum('amount').as('revenue'),
+    ] as any)
+    .where('created_at', '>=', formatDate(startDate))
+    .where('created_at', '<=', formatDate(today))
+    .where('status', '=', 'completed')
+    .groupBy('method')
+    .execute() as { method: string, count: number, revenue: number }[]
+
+  // Format the results
+  const result: Record<string, {
+    count: number
+    revenue: number
+    percentage_of_total: number
+  }> = {}
+
+  methodStats.forEach((item: any) => {
+    const count = Number(item.count || 0)
+    const revenue = Number(item.revenue || 0)
+    const percentageOfTotal = totalCount > 0 ? (count / totalCount) * 100 : 0
+
+    result[item.method] = {
+      count,
+      revenue,
+      percentage_of_total: percentageOfTotal,
+    }
+  })
+
+  return result
+}
+
+/**
+ * Fetch monthly payment trends for the last 12 months
+ */
+export async function fetchMonthlyPaymentTrends(): Promise<Array<{
+  month: string
+  year: number
+  transactions: number
+  revenue: number
+  average: number
+}>> {
+  // Calculate date 12 months ago
+  const today = new Date()
+
+  const twelveMonthsAgo = new Date(today)
+  twelveMonthsAgo.setMonth(today.getMonth() - 11)
+
+  // Set to first day of that month
+  twelveMonthsAgo.setDate(1)
+
+  // Fetch all completed payments within the date range
+  const payments = await db
+    .selectFrom('payments')
+    .selectAll()
+    .where('created_at', '>=', formatDate(twelveMonthsAgo))
+    .where('status', '=', 'completed')
+    .execute() as any[]
+
+  // Group by year-month in JavaScript
+  const monthlyMap: Record<string, { year: number, month: number, transactions: number, revenue: number }> = {}
+
+  for (const payment of payments) {
+    const createdAt = payment.created_at ? new Date(payment.created_at) : new Date()
+    const year = createdAt.getFullYear()
+    const month = createdAt.getMonth() + 1 // 1-indexed
+    const key = `${year}-${String(month).padStart(2, '0')}`
+
+    if (!monthlyMap[key]) {
+      monthlyMap[key] = { year, month, transactions: 0, revenue: 0 }
+    }
+
+    monthlyMap[key].transactions++
+    monthlyMap[key].revenue += Number(payment.amount || 0)
+  }
+
+  // Convert to array and sort by year-month
+  const sortedKeys = Object.keys(monthlyMap).sort()
+
+  return sortedKeys.map((key) => {
+    const item = monthlyMap[key]!
+    const transactions = item.transactions
+    const revenue = item.revenue
+    const average = transactions > 0 ? revenue / transactions : 0
+
+    // Format month name
+    const monthDate = new Date(item.year, item.month - 1, 1)
+    const monthName = monthDate.toLocaleString('default', { month: 'short' })
+
+    return {
+      month: monthName,
+      year: item.year,
+      transactions,
+      revenue,
+      average,
+    }
+  })
+}

package/src/payments/index.ts

@@ -0,0 +1,16 @@
+export { bulkDestroy, destroy } from './destroy'
+
+// Fetch operations - from fetch.ts
+export {
+  fetchAll,
+  fetchById,
+  fetchMonthlyPaymentTrends,
+  fetchPaymentStats,
+  fetchPaymentStatsByMethod,
+} from './fetch'
+
+// Store operations - from store.ts
+export { store } from './store'
+
+// Update operations - from update.ts
+export { update } from './update'

package/src/payments/store.ts

@@ -0,0 +1,63 @@
+type PaymentJsonResponse = ModelRow<typeof Payment>
+type NewPayment = NewModelData<typeof Payment>
+import { randomUUIDv7 } from 'bun'
+import { db } from '@stacksjs/database'
+import { HttpError } from '@stacksjs/error-handling'
+import { isUniqueViolation } from '@stacksjs/orm'
+
+/**
+ * Create a new payment
+ *
+ * @param data The payment data to store
+ * @returns The newly created payment record
+ */
+export async function store(data: NewPayment): Promise<PaymentJsonResponse | undefined> {
+  const paymentData = {
+    ...data,
+    status: data.status || 'PENDING',
+    currency: data.currency || 'USD',
+    uuid: randomUUIDv7(),
+  }
+
+  try {
+    // Insert the payment record
+    const createdPayment = await db
+      .insertInto('payments')
+      .values(paymentData as NewPayment)
+      .executeTakeFirst()
+
+    const insertId = Number(createdPayment.insertId) || Number(createdPayment.numInsertedOrUpdatedRows)
+
+    // If insert was successful, retrieve the newly created payment
+    if (insertId) {
+      const payment = await db
+        .selectFrom('payments')
+        .where('id', '=', insertId)
+        .selectAll()
+        .executeTakeFirst()
+
+      return payment as PaymentJsonResponse | undefined
+    }
+
+    return undefined
+  }
+  catch (error) {
+    if (error instanceof HttpError)
+      throw error
+    // Cross-dialect duplicate detection (#1957) — checked before the
+    // insufficient-funds sniff (a duplicate is never an insufficient-funds
+    // error, and vice versa, so order is safe).
+    if (isUniqueViolation(error))
+      throw new HttpError(409, 'A payment with this transaction ID already exists')
+    if (error instanceof Error) {
+      // Check for insufficient amount errors or other payment-specific validations
+      if (error.message.includes('Insufficient funds')) {
+        throw new Error('Insufficient funds for this payment')
+      }
+
+      throw new Error(`Failed to create payment: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/payments/update.ts

@@ -0,0 +1,52 @@
+import { db } from '@stacksjs/database'
+import { formatDate } from '@stacksjs/orm'
+import { fetchById } from './fetch'
+
+type PaymentJsonResponse = ModelRow<typeof Payment>
+type PaymentUpdate = UpdateModelData<typeof Payment>
+
+/**
+ * Update a payment by ID.
+ *
+ * Supports the lifecycle a payment row goes through after creation —
+ * status transitions (pending → completed/failed/refunded), refund
+ * amount tracking, processor metadata (transaction ID, card brand),
+ * and operator notes. The original `amount` is intentionally fillable
+ * via this path because partial captures and adjustments can rewrite
+ * it before settlement; if your processor never adjusts captured
+ * amounts, just don't pass `amount` in `data`.
+ *
+ * @param id The ID of the payment to update
+ * @param data The updated payment data (omit `id`)
+ * @returns The updated payment record
+ */
+export async function update(id: number, data: Omit<PaymentUpdate, 'id'>): Promise<PaymentJsonResponse | undefined> {
+  const existing = await fetchById(id)
+  if (!existing) {
+    throw new Error(`Payment with ID ${id} not found`)
+  }
+
+  try {
+    await db
+      .updateTable('payments')
+      .set({
+        ...data,
+        updated_at: formatDate(new Date()),
+      })
+      .where('id', '=', id)
+      .execute()
+
+    return await fetchById(id)
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      // Same uniqueness collision the store path can hit — surface it
+      // with the same wording so callers can pattern-match.
+      if (error.message.includes('Duplicate entry') && error.message.includes('transaction_id')) {
+        throw new Error('A payment with this transaction ID already exists')
+      }
+      throw new Error(`Failed to update payment: ${error.message}`)
+    }
+    throw error
+  }
+}

package/src/products/categories/destroy.ts

@@ -0,0 +1,103 @@
+import { db } from '@stacksjs/database'
+import { fetchById } from './fetch'
+
+/**
+ * Delete a category by ID
+ * @param id The ID of the category to delete
+ * @returns A boolean indicating whether the deletion was successful
+ */
+export async function remove(id: number): Promise<boolean> {
+  // First check if the category exists
+  const category = await fetchById(id)
+
+  if (!category) {
+    throw new Error(`Category with ID ${id} not found`)
+  }
+
+  // Delete the category
+  const result = await db
+    .deleteFrom('categories')
+    .where('id', '=', id)
+    .executeTakeFirst()
+
+  return !!result
+}
+
+/**
+ * Bulk delete multiple categories
+ * @param ids Array of category IDs to delete
+ * @returns Number of categories successfully deleted
+ */
+export async function bulkRemove(ids: number[]): Promise<number> {
+  if (!ids.length) {
+    return 0
+  }
+
+  // Delete all categories in the array
+  const result = await db
+    .deleteFrom('categories')
+    .where('id', 'in', ids)
+    .executeTakeFirst()
+
+  return Number(result?.numDeletedRows) || 0
+}
+
+/**
+ * Delete child categories of a parent category
+ * @param parentId The ID of the parent category
+ * @returns Number of categories deleted
+ */
+export async function removeChildCategories(parentId: string): Promise<number> {
+  // Delete categories with the specified parent_category_id
+  const result = await db
+    .deleteFrom('categories')
+    .where('parent_category_id', '=', parentId)
+    .executeTakeFirst()
+
+  return Number(result?.numDeletedRows) || 0
+}
+
+/**
+ * Deactivate a category (set is_active to false)
+ * @param id The ID of the category to deactivate
+ * @returns A boolean indicating whether the deactivation was successful
+ */
+export async function deactivate(id: number): Promise<boolean> {
+  // First check if the category exists
+  const category = await fetchById(id)
+
+  if (!category) {
+    throw new Error(`Category with ID ${id} not found`)
+  }
+
+  // Update the category status
+  const result = await db
+    .updateTable('categories')
+    .set({
+      is_active: false,
+      updated_at: new Date().toISOString(),
+    })
+    .where('id', '=', id)
+    .executeTakeFirst()
+
+  return !!result
+}
+
+/**
+ * Deactivate all child categories of a parent category
+ * @param parentId The ID of the parent category
+ * @returns Number of categories deactivated
+ */
+export async function deactivateChildCategories(parentId: string): Promise<number> {
+  // Update categories with the specified parent_category_id
+  const result = await db
+    .updateTable('categories')
+    .set({
+      is_active: false,
+      updated_at: new Date().toISOString(),
+    })
+    .where('parent_category_id', '=', parentId)
+    .execute()
+
+  return Number((result as any).length) || 0
+}