@stacksjs/commerce 0.70.53 → 0.70.55

package/src/coupons/update.ts

@@ -0,0 +1,147 @@
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+import { HttpError } from '@stacksjs/error-handling'
+import { formatDate, isUniqueViolation } from '@stacksjs/orm'
+type CouponJsonResponse = ModelRow<typeof Coupon>
+type CouponUpdate = UpdateModelData<typeof Coupon>
+import { fetchById } from './fetch'
+
+/**
+ * Discriminated result for `redeem` — `ok: true` on a successful
+ * atomic redemption (the row's `usage_count` was bumped and the
+ * limit wasn't already hit); `ok: false` with a `reason` when the
+ * redemption failed (out of uses, expired, inactive, missing).
+ * Callers branch on `reason` to surface a useful error to the user.
+ */
+export type CouponRedemptionResult =
+  | { ok: true, coupon: CouponJsonResponse }
+  | { ok: false, reason: 'not-found' | 'inactive' | 'expired' | 'limit-reached' }
+
+/**
+ * Update a coupon by ID
+ *
+ * @param id The ID of the coupon to update
+ * @param data The updated coupon data
+ * @returns The updated coupon record
+ */
+export async function update(id: number, data: Omit<CouponUpdate, 'id'>): Promise<CouponJsonResponse | undefined> {
+  // Check if coupon exists
+  const existingCoupon = await fetchById(id)
+  if (!existingCoupon) {
+    throw new Error(`Coupon with ID ${id} not found`)
+  }
+
+  try {
+    // Update the coupon
+    await db
+      .updateTable('coupons')
+      .set({
+        ...data,
+        updated_at: formatDate(new Date()),
+      })
+      .where('id', '=', id)
+      .execute()
+
+    // Fetch and return the updated coupon
+    const updatedCoupon = await fetchById(id)
+
+    if (updatedCoupon) {
+      // Convert SQLite integer boolean to actual boolean
+      const c = updatedCoupon as Record<string, unknown>
+      c.is_active = Boolean(c.is_active)
+    }
+
+    return updatedCoupon
+  }
+  catch (error) {
+    if (error instanceof HttpError)
+      throw error
+    // Cross-dialect duplicate detection (#1957).
+    if (isUniqueViolation(error))
+      throw new HttpError(409, 'A coupon with this code already exists')
+    if (error instanceof Error)
+      throw new Error(`Failed to update coupon: ${error.message}`)
+    throw error
+  }
+}
+
+/**
+ * Atomically redeem a coupon (stacksjs/stacks#1879 Co-5).
+ *
+ * Pre-fix: callers fetched the coupon, checked `usage_count <
+ * max_uses`, then bumped `usage_count` via `update()`. Two concurrent
+ * redemption requests against a coupon with `max_uses=1` both saw
+ * `usage_count=0`, both incremented, both succeeded. The coupon
+ * was redeemed twice — direct revenue loss equal to `discount_value`
+ * times the over-redemption count.
+ *
+ * Post-fix: single conditional UPDATE that bumps `usage_count` and
+ * enforces `max_uses` / `is_active` / expiry in the WHERE clause.
+ * The database guarantees only one writer wins the race. Returns a
+ * discriminated result so callers can surface a useful reason
+ * ("limit reached" vs "expired" vs "inactive") instead of a generic
+ * failure.
+ *
+ * @example
+ * ```ts
+ * const result = await redeem(couponId)
+ * if (!result.ok) {
+ *   throw new HttpError(400, `Coupon cannot be redeemed: ${result.reason}`)
+ * }
+ * // Use result.coupon — it reflects the post-redemption state.
+ * ```
+ */
+export async function redeem(id: number): Promise<CouponRedemptionResult> {
+  // Single atomic UPDATE — increment usage_count and enforce every
+  // redemption precondition in the WHERE clause. `max_uses IS NULL`
+  // means "unlimited" so coupons without an explicit cap aren't
+  // accidentally rejected.
+  const now = formatDate(new Date())
+  const result = await db
+    .updateTable('coupons')
+    .set({
+      usage_count: (db as any).raw(`COALESCE(usage_count, 0) + 1`),
+      updated_at: now,
+    })
+    .where('id', '=', id)
+    .where((eb: StacksExpressionBuilder) => eb.or([
+      eb('max_uses', 'is', null),
+      eb.cmpr('usage_count', '<', eb.ref('max_uses')),
+    ]))
+    .where('is_active', '=', 1)
+    .where((eb: StacksExpressionBuilder) => eb.or([
+      eb('start_date', 'is', null),
+      eb.cmpr('start_date', '<=', now),
+    ]))
+    .where((eb: StacksExpressionBuilder) => eb.or([
+      eb('end_date', 'is', null),
+      eb.cmpr('end_date', '>=', now),
+    ]))
+    .executeTakeFirst()
+
+  // bun-query-builder's executeTakeFirst returns metadata describing
+  // affected rows. If the UPDATE matched zero rows, the redemption
+  // failed (precondition mismatch); diagnose which one to give the
+  // caller a useful reason.
+  const affected = Number((result as any)?.numUpdatedRows ?? (result as any)?.affectedRows ?? 0)
+  if (affected > 0) {
+    const refreshed = await fetchById(id)
+    if (refreshed) {
+      // Convert SQLite integer boolean to actual boolean.
+      const c = refreshed as Record<string, unknown>
+      c.is_active = Boolean(c.is_active)
+      return { ok: true, coupon: refreshed }
+    }
+    return { ok: false, reason: 'not-found' }
+  }
+
+  // UPDATE matched zero rows — figure out which precondition failed.
+  const existing = await fetchById(id)
+  if (!existing) return { ok: false, reason: 'not-found' }
+  if (!existing.is_active) return { ok: false, reason: 'inactive' }
+  const startOk = !existing.start_date || existing.start_date <= now
+  const endOk = !existing.end_date || existing.end_date >= now
+  if (!startOk || !endOk) return { ok: false, reason: 'expired' }
+  // Fell through every other check → limit must have been reached.
+  return { ok: false, reason: 'limit-reached' }
+}

package/src/customers/destroy.ts

@@ -0,0 +1,62 @@
+import { db } from '@stacksjs/database'
+import { fetchById } from './fetch'
+
+/**
+ * Delete a customer by ID
+ *
+ * @param id The ID of the customer to delete
+ * @returns True if the deletion was successful, false otherwise
+ */
+export async function destroy(id: number): Promise<boolean> {
+  try {
+    // First check if the customer exists
+    const customer = await fetchById(id)
+
+    if (!customer) {
+      throw new Error(`Customer with ID ${id} not found`)
+    }
+
+    // Delete the customer
+    const result = await db
+      .deleteFrom('customers')
+      .where('id', '=', id)
+      .executeTakeFirst()
+
+    return result.numDeletedRows > 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete customer: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Bulk delete multiple customers
+ *
+ * @param ids Array of customer IDs to delete
+ * @returns Number of customers successfully deleted
+ */
+export async function bulkDestroy(ids: number[]): Promise<number> {
+  if (!ids.length)
+    return 0
+
+  try {
+    // Delete all customers in the array
+    const result = await db
+      .deleteFrom('customers')
+      .where('id', 'in', ids)
+      .executeTakeFirst()
+
+    return Number(result.numDeletedRows) || 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete customers in bulk: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/customers/fetch.ts

@@ -0,0 +1,20 @@
+type CustomerJsonResponse = ModelRow<typeof Customer>
+import { db } from '@stacksjs/database'
+
+/**
+ * Fetch a customer by ID
+ */
+export async function fetchById(id: number): Promise<CustomerJsonResponse | undefined> {
+  return await db
+    .selectFrom('customers')
+    .where('id', '=', id)
+    .selectAll()
+    .executeTakeFirst() as CustomerJsonResponse | undefined
+}
+
+/**
+ * Fetch all customers
+ */
+export async function fetchAll(): Promise<CustomerJsonResponse[]> {
+  return await db.selectFrom('customers').selectAll().execute() as CustomerJsonResponse[]
+}

package/src/customers/index.ts

@@ -0,0 +1,17 @@
+export {
+  bulkDestroy,
+  destroy,
+} from './destroy'
+
+export {
+  fetchAll,
+  fetchById,
+} from './fetch'
+
+export {
+  store,
+} from './store'
+
+export {
+  update,
+} from './update'

package/src/customers/store.ts

@@ -0,0 +1,45 @@
+type CustomerJsonResponse = ModelRow<typeof Customer>
+type NewCustomer = NewModelData<typeof Customer>
+import { db } from '@stacksjs/database'
+import { HttpError } from '@stacksjs/error-handling'
+import { isUniqueViolation } from '@stacksjs/orm'
+import { fetchById } from './fetch'
+
+/**
+ * Create a new customer
+ *
+ * @param data The customer data to store
+ * @returns The newly created customer record
+ */
+export async function store(data: NewCustomer): Promise<CustomerJsonResponse> {
+  try {
+    const customerData = {
+      ...data,
+      avatar: data.avatar ?? 'https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=400&fit=crop&q=60',
+    }
+
+    const result = await db
+      .insertInto('customers')
+      .values(customerData)
+      .executeTakeFirst()
+
+    if (!result)
+      throw new Error('Failed to create customer')
+
+    const insertId = result.insertId || Number(result.numInsertedOrUpdatedRows)
+
+    const customerResult = await fetchById(Number(insertId)) as CustomerJsonResponse
+
+    return customerResult
+  }
+  catch (error) {
+    if (error instanceof HttpError)
+      throw error
+    // Cross-dialect duplicate detection (#1957).
+    if (isUniqueViolation(error))
+      throw new HttpError(409, 'A customer with this email already exists')
+    if (error instanceof Error)
+      throw new Error(`Failed to create customer: ${error.message}`)
+    throw error
+  }
+}

package/src/customers/update.ts

@@ -0,0 +1,44 @@
+import { db } from '@stacksjs/database'
+import { HttpError } from '@stacksjs/error-handling'
+import { formatDate, isUniqueViolation } from '@stacksjs/orm'
+type CustomerJsonResponse = ModelRow<typeof Customer>
+type CustomerUpdate = UpdateModelData<typeof Customer>
+
+/**
+ * Update a customer
+ *
+ * @param id The ID of the customer to update
+ * @param data The customer data to update
+ * @returns The updated customer record
+ */
+export async function update(id: number, data: Omit<CustomerUpdate, 'id'>): Promise<CustomerJsonResponse> {
+  try {
+    if (!id)
+      throw new Error('Customer ID is required for update')
+
+    const result = await db
+      .updateTable('customers')
+      .set({
+        ...data,
+        updated_at: formatDate(new Date()),
+      })
+      .where('id', '=', id)
+      .returningAll()
+      .executeTakeFirst()
+
+    if (!result)
+      throw new Error('Failed to update customer')
+
+    return result as CustomerJsonResponse
+  }
+  catch (error) {
+    if (error instanceof HttpError)
+      throw error
+    // Cross-dialect duplicate detection (#1957).
+    if (isUniqueViolation(error))
+      throw new HttpError(409, 'A customer with this email already exists')
+    if (error instanceof Error)
+      throw new Error(`Failed to update customer: ${error.message}`)
+    throw error
+  }
+}

package/src/devices/destroy.ts

@@ -0,0 +1,54 @@
+import { db } from '@stacksjs/database'
+
+/**
+ * Delete a print device by ID
+ *
+ * @param id The ID of the print device to delete
+ * @returns True if the print device was deleted, false otherwise
+ */
+export async function destroy(id: number): Promise<boolean> {
+  try {
+    const result = await db
+      .deleteFrom('print_devices')
+      .where('id', '=', id)
+      .executeTakeFirst()
+
+    return Number(result.numDeletedRows) > 0
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete print device: ${error.message}`)
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Delete multiple print devices by ID
+ *
+ * @param ids Array of print device IDs to delete
+ * @returns Number of print devices deleted
+ */
+export async function bulkDestroy(ids: number[]): Promise<number> {
+  if (!ids.length)
+    return 0
+
+  try {
+    // Perform the delete operation
+    const result = await db
+      .deleteFrom('print_devices')
+      .where('id', 'in', ids)
+      .executeTakeFirst()
+
+    // Return the number of deleted rows
+    return Number(result.numDeletedRows)
+  }
+  catch (error) {
+    if (error instanceof Error) {
+      throw new TypeError(`Failed to delete print devices: ${error.message}`)
+    }
+
+    throw error
+  }
+}

package/src/devices/export.ts

@@ -0,0 +1,98 @@
+type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>
+import type { SpreadsheetWrapper } from 'ts-spreadsheets'
+import { createSpreadsheet } from 'ts-spreadsheets'
+import { fetchAll } from './fetch'
+
+/**
+ * Represents the structure of an exported print device
+ */
+export interface ExportedPrintDevice {
+  'Device ID': number
+  'Name': string
+  'MAC Address': string
+  'Location': string
+  'Terminal': string
+  'Status': string
+  'Last Ping': string
+  'Print Count': number
+}
+
+/**
+ * Export print devices to a spreadsheet
+ * @param format The format of the spreadsheet (default is CSV)
+ * @returns Spreadsheet object ready for download or storage
+ */
+export async function exportPrintDevices(format: 'csv' | 'excel' = 'csv'): Promise<SpreadsheetWrapper> {
+  // Fetch all print devices
+  const devices = await fetchAll()
+
+  // Prepare data for spreadsheet
+  const spreadsheetData = prepareDevicesForExport(devices)
+
+  // Create and return spreadsheet
+  return createSpreadsheet(spreadsheetData, { type: format })
+}
+
+/**
+ * Prepare print devices data for spreadsheet export
+ * @param devices Array of print device objects
+ * @returns Spreadsheet data structure
+ */
+function prepareDevicesForExport(devices: PrintDeviceJsonResponse[]) {
+  // Define headings
+  const headings: (keyof ExportedPrintDevice)[] = [
+    'Device ID',
+    'Name',
+    'MAC Address',
+    'Location',
+    'Terminal',
+    'Status',
+    'Last Ping',
+    'Print Count',
+  ]
+
+  // Transform devices into export format
+  const data = devices.map((device) => {
+    return [
+      device.id,
+      device.name,
+      device.macAddress,
+      device.location,
+      device.terminal,
+      device.status,
+      new Date(device.lastPing).toLocaleString(),
+      device.printCount,
+    ]
+  })
+
+  return { headings, data }
+}
+
+/**
+ * Export print devices 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 downloadPrintDevices(format: 'csv' | 'excel' = 'csv', filename?: string): Promise<Response> {
+  const spreadsheet = await exportPrintDevices(format)
+
+  // Use default filename if not provided
+  const defaultFilename = `print_devices_export_${new Date().toISOString().split('T')[0]}.${format}`
+  return spreadsheet.download(filename || defaultFilename)
+}
+
+/**
+ * Store print devices 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 storePrintDevicesExport(format: 'csv' | 'excel' = 'csv', path?: string): Promise<void> {
+  const spreadsheet = await exportPrintDevices(format)
+
+  // Use default path and filename if not provided
+  const defaultPath = `print_devices_export_${new Date().toISOString().split('T')[0]}.${format}`
+
+  spreadsheet.store(path || defaultPath)
+}

package/src/devices/fetch.ts

@@ -0,0 +1,125 @@
+type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>
+type ReceiptJsonResponse = ModelRow<typeof Receipt>
+import type { StacksExpressionBuilder } from '@stacksjs/database'
+import { db } from '@stacksjs/database'
+
+/**
+ * Fetch a print device by ID
+ */
+export async function fetchById(id: number): Promise<PrintDeviceJsonResponse | undefined> {
+  return await db
+    .selectFrom('print_devices')
+    .where('id', '=', id)
+    .selectAll()
+    .executeTakeFirst() as PrintDeviceJsonResponse | undefined
+}
+
+/**
+ * Fetch all print devices
+ */
+export async function fetchAll(): Promise<PrintDeviceJsonResponse[]> {
+  return await db.selectFrom('print_devices').selectAll().execute() as PrintDeviceJsonResponse[]
+}
+
+/**
+ * Count all print devices
+ */
+export async function countAll(): Promise<number> {
+  const result = await db
+    .selectFrom('print_devices')
+    .select(((eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')) as any)
+    .executeTakeFirst() as { count: number } | undefined
+  return result?.count ?? 0
+}
+
+/**
+ * Count total prints across all print devices from receipts
+ */
+export async function countTotalPrints(): Promise<number> {
+  const result = await db
+    .selectFrom('print_devices')
+    .select('print_count' as any)
+    .executeTakeFirst()
+
+  return (result as any)?.print_count ?? 0
+}
+
+/**
+ * Count total prints for a specific print device from receipts
+ */
+export async function countPrintsByDeviceId(printDeviceId: number): Promise<number> {
+  const result = await db
+    .selectFrom('print_devices')
+    .select('print_count' as any)
+    .where('id', '=', printDeviceId)
+    .executeTakeFirst()
+
+  return (result as any)?.print_count ?? 0
+}
+
+/**
+ * Calculate error rate percentage based on receipts
+ */
+export async function calculateErrorRate(): Promise<number> {
+  const result = await db
+    .selectFrom('receipts')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('total'),
+      eb.fn.count('id').filterWhere('status', '=', 'error').as('error_count'),
+    ]) as any)
+    .executeTakeFirst()
+
+  if (!(result as any)?.total || (result as any).total === 0) {
+    return 0
+  }
+
+  return Number((((result as any).error_count ?? 0) / (result as any).total) * 100)
+}
+
+/**
+ * Fetch all errors from receipts for a specific print device
+ */
+export async function fetchErrorsByDeviceId(printDeviceId: number): Promise<ReceiptJsonResponse[]> {
+  return await db
+    .selectFrom('receipts')
+    .where('print_device_id', '=', printDeviceId)
+    .where('status', '=', 'error')
+    .selectAll()
+    .execute() as ReceiptJsonResponse[]
+}
+
+/**
+ * Calculate printer health percentage based on online status
+ */
+export async function calculatePrinterHealth(): Promise<number> {
+  const result = await db
+    .selectFrom('print_devices')
+    .select(((eb: StacksExpressionBuilder) => [
+      eb.fn.count('id').as('total'),
+      eb.fn.count('id').filterWhere('status', '=', 'online').as('online_count'),
+    ]) as any)
+    .executeTakeFirst()
+
+  if (!(result as any)?.total || (result as any).total === 0) {
+    return 0
+  }
+
+  return Number((((result as any).online_count ?? 0) / (result as any).total) * 100)
+}
+
+/**
+ * Get printer counts by status for visualization
+ */
+export async function getPrinterStatusCounts(): Promise<Record<string, number>> {
+  const result = await db
+    .selectFrom('print_devices')
+    .select(['status', (eb: StacksExpressionBuilder) => eb.fn.count('id').as('count')] as any)
+    .groupBy('status')
+    .execute() as { status: string, count: number }[]
+
+  // Convert array to object with status as key and count as value
+  return result.reduce((acc: any, curr: any) => {
+    acc[curr.status as string] = curr.count
+    return acc
+  }, {} as Record<string, number>)
+}

package/src/devices/index.ts

@@ -0,0 +1,31 @@
+// Functions from destroy.ts
+export {
+  bulkDestroy,
+  destroy,
+} from './destroy'
+
+// Functions from export.ts
+export {
+  downloadPrintDevices,
+  exportPrintDevices,
+  storePrintDevicesExport,
+} from './export'
+
+// Functions from fetch.ts
+export {
+  fetchAll,
+  fetchById,
+} from './fetch'
+
+// Functions from store.ts
+export {
+  bulkStore,
+  store,
+} from './store'
+
+// Functions from update.ts
+export {
+  update,
+  updatePrintCount,
+  updateStatus,
+} from './update'