@stacksjs/commerce 0.70.88 → 0.70.90

package/dist/coupons/destroy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Delete a coupon by ID
+ * @param id The ID of the coupon to delete
+ * @returns A boolean indicating success
+ */
+export declare function deleteCoupon(id: number): Promise<boolean>;
+/**
+ * Delete multiple coupons by IDs
+ * @param ids Array of coupon IDs to delete
+ * @returns Number of deleted coupons
+ */
+export declare function deleteCoupons(ids: number[]): Promise<number>;
+/**
+ * Delete expired coupons
+ * @returns The number of deleted coupons
+ */
+export declare function deleteExpiredCoupons(): Promise<number>;

package/dist/coupons/fetch.d.ts

@@ -0,0 +1,59 @@
+import type { CouponCountStats, CouponRedemptionStats, CouponStats, CouponTimeStats } from '../types';
+/**
+ * Fetch all coupons from the database
+ */
+export declare function fetchAll(): Promise<CouponJsonResponse[]>;
+/**
+ * Fetch a coupon by ID
+ */
+export declare function fetchById(id: number): Promise<CouponJsonResponse | undefined>;
+/**
+ * Fetch a coupon by code
+ */
+export declare function fetchByCode(code: string): Promise<CouponJsonResponse | undefined>;
+/**
+ * Fetch active coupons (is_active = true and within date range)
+ */
+export declare function fetchActive(): Promise<CouponJsonResponse[]>;
+/**
+ * Get coupon statistics
+ */
+export declare function fetchStats(): Promise<CouponStats>;
+/**
+ * Get count of active and inactive coupons for different time periods
+ */
+export declare function fetchCouponCounts(): Promise<CouponTimeStats>;
+/**
+ * Get detailed breakdown of active/inactive coupons by discount type
+ */
+export declare function fetchCouponCountsByType(): Promise<Record<string, CouponCountStats>>;
+/**
+ * Fetch coupon redemption statistics based on usage_count
+ */
+export declare function fetchRedemptionStats(): Promise<CouponRedemptionStats>;
+/**
+ * Get top redeemed coupons
+ */
+export declare function fetchTopRedeemedCoupons(limit?: number): Promise<any[]>;
+/**
+ * Get redemption trend data in a simplified manner
+ */
+export declare function fetchRedemptionTrend(days?: number): Promise<any[]>;
+/**
+ * Get conversion rate (number of redemptions / number of active coupons)
+ */
+export declare function fetchConversionRate(): Promise<{
+  rate: number
+  total_active: number
+  total_redeemed: number
+}>;
+/**
+ * Calculate the month-over-month change in active coupons
+ */
+export declare function getActiveCouponsMoMChange(): Promise<{
+  current_month: number
+  previous_month: number
+  difference: number
+  percentage_change: number
+}>;
+declare type CouponJsonResponse = ModelRow<typeof Coupon>;

package/dist/coupons/index.d.ts

@@ -0,0 +1,27 @@
+export type { CouponRedemptionResult } from './update';
+export {
+  deleteCoupon,
+  deleteCoupons,
+  deleteExpiredCoupons,
+} from './destroy';
+export {
+  fetchActive,
+  fetchAll,
+  fetchByCode,
+  fetchById,
+  fetchConversionRate,
+  fetchCouponCounts,
+  fetchCouponCountsByType,
+  fetchRedemptionStats,
+  fetchRedemptionTrend,
+  fetchStats,
+  fetchTopRedeemedCoupons,
+  getActiveCouponsMoMChange,
+} from './fetch';
+export {
+  store,
+} from './store';
+export {
+  redeem,
+  update,
+} from './update';

package/dist/coupons/store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Create a new coupon
+ *
+ * @param data The coupon data to store
+ * @returns The newly created coupon record
+ */
+export declare function store(data: NewCoupon): Promise<CouponJsonResponse | undefined>;
+declare type CouponJsonResponse = ModelRow<typeof Coupon>;
+declare type NewCoupon = NewModelData<typeof Coupon>;

package/dist/coupons/update.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare function update(id: number, data: Omit<CouponUpdate, 'id'>): Promise<CouponJsonResponse | undefined>;
+/**
+ * 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 declare function redeem(id: number): Promise<CouponRedemptionResult>;
+declare type CouponJsonResponse = ModelRow<typeof Coupon>;
+declare type CouponUpdate = UpdateModelData<typeof Coupon>;
+/**
+ * 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' }

package/dist/customers/destroy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Delete a customer by ID
+ *
+ * @param id The ID of the customer to delete
+ * @returns True if the deletion was successful, false otherwise
+ */
+export declare function destroy(id: number): Promise<boolean>;
+/**
+ * Bulk delete multiple customers
+ *
+ * @param ids Array of customer IDs to delete
+ * @returns Number of customers successfully deleted
+ */
+export declare function bulkDestroy(ids: number[]): Promise<number>;

package/dist/customers/fetch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fetch a customer by ID
+ */
+export declare function fetchById(id: number): Promise<CustomerJsonResponse | undefined>;
+/**
+ * Fetch all customers
+ */
+export declare function fetchAll(): Promise<CustomerJsonResponse[]>;
+declare type CustomerJsonResponse = ModelRow<typeof Customer>;

package/dist/customers/index.d.ts

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

package/dist/customers/store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Create a new customer
+ *
+ * @param data The customer data to store
+ * @returns The newly created customer record
+ */
+export declare function store(data: NewCustomer): Promise<CustomerJsonResponse>;
+declare type CustomerJsonResponse = ModelRow<typeof Customer>;
+declare type NewCustomer = NewModelData<typeof Customer>;

package/dist/customers/update.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function update(id: number, data: Omit<CustomerUpdate, 'id'>): Promise<CustomerJsonResponse>;
+declare type CustomerJsonResponse = ModelRow<typeof Customer>;
+declare type CustomerUpdate = UpdateModelData<typeof Customer>;

package/dist/devices/destroy.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function destroy(id: number): Promise<boolean>;
+/**
+ * Delete multiple print devices by ID
+ *
+ * @param ids Array of print device IDs to delete
+ * @returns Number of print devices deleted
+ */
+export declare function bulkDestroy(ids: number[]): Promise<number>;

package/dist/devices/export.d.ts

@@ -0,0 +1,35 @@
+import type { SpreadsheetWrapper } from 'ts-spreadsheets';
+/**
+ * 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 declare function exportPrintDevices(format?: 'csv' | 'excel'): Promise<SpreadsheetWrapper>;
+/**
+ * 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 declare function downloadPrintDevices(format?: 'csv' | 'excel', filename?: string): Promise<Response>;
+/**
+ * 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 declare function storePrintDevicesExport(format?: 'csv' | 'excel', path?: string): Promise<void>;
+/**
+ * Represents the structure of an exported print device
+ */
+export declare interface ExportedPrintDevice {
+  'Device ID': number
+  'Name': string
+  'MAC Address': string
+  'Location': string
+  'Terminal': string
+  'Status': string
+  'Last Ping': string
+  'Print Count': number
+}
+declare type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>;

package/dist/devices/fetch.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fetch a print device by ID
+ */
+export declare function fetchById(id: number): Promise<PrintDeviceJsonResponse | undefined>;
+/**
+ * Fetch all print devices
+ */
+export declare function fetchAll(): Promise<PrintDeviceJsonResponse[]>;
+/**
+ * Count all print devices
+ */
+export declare function countAll(): Promise<number>;
+/**
+ * Count total prints across all print devices from receipts
+ */
+export declare function countTotalPrints(): Promise<number>;
+/**
+ * Count total prints for a specific print device from receipts
+ */
+export declare function countPrintsByDeviceId(printDeviceId: number): Promise<number>;
+/**
+ * Calculate error rate percentage based on receipts
+ */
+export declare function calculateErrorRate(): Promise<number>;
+/**
+ * Fetch all errors from receipts for a specific print device
+ */
+export declare function fetchErrorsByDeviceId(printDeviceId: number): Promise<ReceiptJsonResponse[]>;
+/**
+ * Calculate printer health percentage based on online status
+ */
+export declare function calculatePrinterHealth(): Promise<number>;
+/**
+ * Get printer counts by status for visualization
+ */
+export declare function getPrinterStatusCounts(): Promise<Record<string, number>>;
+declare type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>;
+declare type ReceiptJsonResponse = ModelRow<typeof Receipt>;

package/dist/devices/index.d.ts

@@ -0,0 +1,27 @@
+// 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';

package/dist/devices/store.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Create a new print device
+ *
+ * @param data Print device data to store
+ * @returns The newly created print device record
+ */
+export declare function store(data: NewPrintDevice): Promise<PrintDeviceJsonResponse | undefined>;
+/**
+ * Create multiple print devices at once
+ *
+ * @param data Array of print device data to store
+ * @returns Number of print devices created
+ */
+export declare function bulkStore(data: NewPrintDevice[]): Promise<number>;
+declare type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>;
+declare type NewPrintDevice = NewModelData<typeof PrintDevice>;

package/dist/devices/update.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Update a print device by ID
+ *
+ * @param id The ID of the print device to update
+ * @param data The updated print device data
+ * @returns The updated print device record
+ */
+export declare function update(id: number, data: Omit<PrintDeviceUpdate, 'id'>): Promise<PrintDeviceJsonResponse | undefined>;
+/**
+ * Update a print device's status
+ *
+ * @param id The ID of the print device
+ * @param status The new status
+ * @returns The updated print device with the new status
+ */
+export declare function updateStatus(id: number, status: 'online' | 'offline' | 'warning'): Promise<PrintDeviceJsonResponse | undefined>;
+/**
+ * Update print count for a print device
+ *
+ * @param id The ID of the print device
+ * @param printCount The updated print count value
+ * @returns The updated print device
+ */
+export declare function updatePrintCount(id: number, printCount?: number): Promise<PrintDeviceJsonResponse | undefined>;
+declare type PrintDeviceJsonResponse = ModelRow<typeof PrintDevice>;
+declare type PrintDeviceUpdate = UpdateModelData<typeof PrintDevice>;

package/dist/errors/destroy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Delete a single error by ID
+ */
+export declare function destroy(id: number): Promise<boolean>;
+/**
+ * Delete multiple errors by IDs
+ */
+export declare function bulkDestroy(ids: number[]): Promise<boolean>;
+/**
+ * Delete all errors in a group (by type and message)
+ */
+export declare function destroyGroup(type: string, message: string): Promise<boolean>;

package/dist/errors/fetch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Fetch a single error by ID
+ */
+export declare function fetchById(id: number): Promise<ErrorRecord | undefined>;
+/**
+ * Fetch all errors (raw, ungrouped)
+ */
+export declare function fetchAll(): Promise<ErrorRecord[]>;
+/**
+ * Fetch errors grouped by type and message (Sentry-like behavior)
+ * Same errors are aggregated instead of creating duplicate entries
+ */
+export declare function fetchGrouped(): Promise<GroupedError[]>;
+/**
+ * Fetch errors for a specific group (by type and message)
+ */
+export declare function fetchByGroup(type: string, message: string): Promise<ErrorRecord[]>;
+/**
+ * Fetch error statistics
+ */
+export declare function fetchStats(): Promise<ErrorStats>;
+/**
+ * Fetch error timeline (hourly counts for the last 24 hours)
+ */
+export declare function fetchTimeline(): Promise<{ hour: string, count: number }[]>;
+export declare interface ErrorRecord {
+  id: number
+  type: string
+  message: string
+  stack: string | null
+  status: number | null
+  additional_info: string | null
+  created_at: string
+  updated_at: string | null
+}
+export declare interface GroupedError {
+  id: number
+  type: string
+  message: string
+  stack: string | null
+  status: string
+  count: number
+  first_seen: string
+  last_seen: string
+  error_ids: number[]
+}
+export declare interface ErrorStats {
+  total: number
+  unresolved: number
+  resolved: number
+  ignored: number
+  last_24h: number
+  trend: number
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,25 @@
+export type {
+  ErrorRecord,
+  ErrorStats,
+  GroupedError,
+} from './fetch';
+export {
+  bulkDestroy,
+  destroy,
+  destroyGroup,
+} from './destroy';
+export {
+  fetchAll,
+  fetchByGroup,
+  fetchById,
+  fetchGrouped,
+  fetchStats,
+  fetchTimeline,
+} from './fetch';
+export {
+  bulkUpdateStatus,
+  ignoreGroup,
+  resolveGroup,
+  unresolveGroup,
+  update,
+} from './update';

package/dist/errors/update.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Update a single error by ID
+ */
+export declare function update(id: number, data: UpdateErrorData): Promise<boolean>;
+/**
+ * Update multiple errors by IDs (for bulk status updates on grouped errors)
+ */
+export declare function bulkUpdateStatus(ids: number[], status: number): Promise<boolean>;
+/**
+ * Resolve a grouped error (sets status = 1 for all errors in the group)
+ */
+export declare function resolveGroup(type: string, message: string): Promise<boolean>;
+/**
+ * Ignore a grouped error (sets status = 2 for all errors in the group)
+ */
+export declare function ignoreGroup(type: string, message: string): Promise<boolean>;
+/**
+ * Unresolve a grouped error (sets status = 0 for all errors in the group)
+ */
+export declare function unresolveGroup(type: string, message: string): Promise<boolean>;
+export declare interface UpdateErrorData {
+  status?: number
+  additional_info?: string
+}

package/dist/gift-cards/destroy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Delete a gift card by ID
+ * @param id The ID of the gift card to delete
+ * @returns A boolean indicating whether the deletion was successful
+ */
+export declare function destroy(id: number): Promise<boolean>;
+/**
+ * Bulk delete multiple gift cards
+ * @param ids Array of gift card IDs to delete
+ * @returns Number of gift cards successfully deleted
+ */
+export declare function bulkDestroy(ids: number[]): Promise<number>;
+/**
+ * Delete expired gift cards
+ * @returns Number of gift cards deleted
+ */
+export declare function destroyExpired(): Promise<number>;
+/**
+ * Deactivate a gift card (set is_active to false)
+ * @param id The ID of the gift card to deactivate
+ * @returns A boolean indicating whether the deactivation was successful
+ */
+export declare function deactivate(id: number): Promise<boolean>;

package/dist/gift-cards/fetch.d.ts

@@ -0,0 +1,88 @@
+import type { GiftCardStats } from '../types';
+/**
+ * Fetch all gift cards from the database
+ */
+export declare function fetchAll(): Promise<GiftCardJsonResponse[]>;
+/**
+ * Fetch a gift card by ID
+ */
+export declare function fetchById(id: number): Promise<GiftCardJsonResponse | undefined>;
+/**
+ * Fetch a gift card by code
+ */
+export declare function fetchByCode(code: string): Promise<GiftCardJsonResponse | undefined>;
+/**
+ * Fetch active gift cards (is_active = true and not expired)
+ */
+export declare function fetchActive(): Promise<GiftCardJsonResponse[]>;
+/**
+ * Get gift card statistics
+ */
+export declare function fetchStats(): Promise<GiftCardStats>;
+/**
+ * Check gift card balance by code
+ */
+export declare function checkBalance(code: string): Promise<{ valid: boolean, balance?: number, currency?: string, message?: string }>;
+/**
+ * Compare active gift cards between different time periods
+ * @param daysRange Number of days to look back (7, 30, 60, etc.)
+ */
+export declare function compareActiveGiftCards(_daysRange?: number): Promise<{
+  current_period: number
+  previous_period: number
+  difference: number
+  percentage_change: number
+  days_range: number
+}>;
+/**
+ * Calculate gift card balances and initial values for different time periods
+ * with clear increase/decrease indicators
+ * @param daysRange Number of days to look back (7, 30, 60, etc.)
+ */
+export declare function calculateGiftCardValues(_daysRange?: number): Promise<{
+  current_period: {
+    total_initial_value: number
+    total_remaining_balance: number
+    utilization_rate: number
+    card_count: number
+    average_initial_value: number
+    average_remaining_balance: number
+  }
+  previous_period: {
+    total_initial_value: number
+    total_remaining_balance: number
+    utilization_rate: number
+    card_count: number
+  }
+  comparison: {
+    initial_value: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    balance: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+    card_count: {
+      difference: number
+      percentage: number
+      is_increase: boolean
+    }
+  }
+  days_range: number
+}>;
+/**
+ * Get total value of all gift cards
+ */
+export declare function fetchTotalValue(): Promise<{
+  total_value: number
+}>;
+/**
+ * Get total current balance of all gift cards
+ */
+export declare function fetchTotalCurrentBalance(): Promise<{
+  total_balance: number
+}>;
+declare type GiftCardJsonResponse = ModelRow<typeof GiftCard>;

package/dist/gift-cards/index.d.ts

@@ -0,0 +1,23 @@
+export {
+  bulkDestroy,
+  destroy,
+} from './destroy';
+export {
+  calculateGiftCardValues,
+  checkBalance,
+  compareActiveGiftCards,
+  fetchActive,
+  fetchAll,
+  fetchByCode,
+  fetchById,
+  fetchStats,
+  fetchTotalCurrentBalance,
+  fetchTotalValue,
+} from './fetch';
+export {
+  store,
+} from './store';
+export {
+  update,
+  updateBalance,
+} from './update';

package/dist/gift-cards/store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Create a new gift card
+ *
+ * @param data The gift card data to store
+ * @returns The newly created gift card record
+ */
+export declare function store(data: NewGiftCard): Promise<GiftCardJsonResponse | undefined>;
+declare type GiftCardJsonResponse = ModelRow<typeof GiftCard>;
+declare type NewGiftCard = NewModelData<typeof GiftCard>;