@stacksjs/defaults 0.70.229 → 0.70.231

package/app/Actions/Dashboard/Commerce/commerce-product-records.ts

@@ -0,0 +1,298 @@
+export interface CommerceProductRecord {
+  id: string
+  name: string
+  description: string
+  price: number
+  imageUrl: string
+  isAvailable: boolean
+  inventoryCount: number
+  preparationTime: number
+  allergens: string[]
+  nutritionalInfo: Record<string, string>
+  nutritionalInfoRaw: string
+  categoryId: string
+  categoryName: string
+  manufacturerId: string
+  manufacturerName: string
+  variantCount: number
+  unitCount: number
+  reviewCount: number
+  createdAt: string
+}
+
+export interface CommerceProductSummary {
+  total: number
+  available: number
+  unavailable: number
+  outOfStock: number
+  totalInventory: number
+}
+
+export interface ProductOption {
+  id: string
+  label: string
+}
+
+export interface ProductVariantDetail {
+  id: string
+  name: string
+  type: string
+  description: string
+  options: string[]
+  status: string
+}
+
+export interface ProductUnitDetail {
+  id: string
+  name: string
+  abbreviation: string
+  type: string
+  description: string
+  isDefault: boolean
+}
+
+export interface ProductReviewSummary {
+  total: number
+  approved: number
+  pending: number
+  averageRating: number
+}
+
+function value(record: any, ...keys: string[]): unknown {
+  for (const key of keys) {
+    const result = typeof record?.get === 'function' ? record.get(key) : record?.[key]
+    if (result !== null && result !== undefined)
+      return result
+  }
+  return undefined
+}
+
+function recordError(source: string, field: string, expectation: string): TypeError {
+  return new TypeError(`${source}.${field} must be ${expectation}.`)
+}
+
+function optionalText(input: unknown, source: string, field: string): string {
+  if (input === null || input === undefined || input === '')
+    return ''
+  if (typeof input !== 'string')
+    throw recordError(source, field, 'a string or null')
+  return input.trim()
+}
+
+function requiredText(input: unknown, source: string, field: string): string {
+  const result = optionalText(input, source, field)
+  if (!result)
+    throw recordError(source, field, 'a non-empty string')
+  return result
+}
+
+function identifier(input: unknown, source: string, field = 'id'): string {
+  if (typeof input === 'string' && input.trim())
+    return input.trim()
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input > 0)
+    return String(input)
+  if (typeof input === 'bigint' && input > 0)
+    return String(input)
+  throw recordError(source, field, 'a positive integer or non-empty string')
+}
+
+function number(input: unknown, source: string, field: string, options: { min?: number, max?: number } = {}): number {
+  const result = typeof input === 'number'
+    ? input
+    : typeof input === 'string' && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(input.trim())
+      ? Number(input)
+      : Number.NaN
+  if (!Number.isFinite(result))
+    throw recordError(source, field, 'a finite number')
+  if (options.min !== undefined && result < options.min)
+    throw recordError(source, field, `at least ${options.min}`)
+  if (options.max !== undefined && result > options.max)
+    throw recordError(source, field, `at most ${options.max}`)
+  return result
+}
+
+function boolean(input: unknown, source: string, field: string): boolean {
+  if (input === true || input === 1 || input === '1' || input === 'true')
+    return true
+  if (input === false || input === 0 || input === '0' || input === 'false')
+    return false
+  throw recordError(source, field, 'a boolean')
+}
+
+function stringArray(input: unknown, source: string, field: string): string[] {
+  const raw = optionalText(input, source, field)
+  if (!raw)
+    return []
+
+  try {
+    const parsed = JSON.parse(raw)
+    if (!Array.isArray(parsed))
+      throw recordError(source, field, 'a JSON string array')
+    if (!parsed.every(item => typeof item === 'string'))
+      throw recordError(source, field, 'a JSON string array')
+    return parsed.map(item => item.trim()).filter(Boolean)
+  }
+  catch (error) {
+    if (error instanceof TypeError)
+      throw error
+    if (/^\s*[\[{]/.test(raw))
+      throw recordError(source, field, 'valid JSON or a legacy comma-delimited string')
+  }
+
+  return raw.split(',').map(item => item.trim()).filter(Boolean)
+}
+
+function stringRecord(input: unknown, source: string, field: string): Record<string, string> {
+  const raw = optionalText(input, source, field)
+  if (!raw)
+    return {}
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  }
+  catch {
+    throw recordError(source, field, 'a valid JSON object')
+  }
+
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+    throw recordError(source, field, 'a valid JSON object')
+  const entries = Object.entries(parsed)
+  if (!entries.every(([, result]) =>
+    result === null || ['string', 'number', 'boolean'].includes(typeof result),
+  )) {
+    throw recordError(source, field, 'a JSON object containing primitive values')
+  }
+  return Object.fromEntries(entries.map(([key, result]) => [key, result === null ? '' : String(result)]))
+}
+
+export function commerceRecordIdentifier(record: any, source: string, ...keys: string[]): string {
+  return identifier(value(record, ...(keys.length ? keys : ['id'])), source, keys[0] || 'id')
+}
+
+export function normalizeCommerceCurrency(input: unknown): string {
+  const currency = requiredText(input, 'Commerce configuration', 'currency').toUpperCase()
+  if (!/^[A-Z]{3}$/.test(currency))
+    throw recordError('Commerce configuration', 'currency', 'a three-letter currency code')
+  return currency
+}
+
+export function countProductRelations(records: any[]): Map<string, number> {
+  const counts = new Map<string, number>()
+  for (const [index, record] of records.entries()) {
+    const productId = identifier(value(record, 'product_id', 'productId'), `Product relation ${index + 1}`, 'product_id')
+    counts.set(productId, (counts.get(productId) || 0) + 1)
+  }
+  return counts
+}
+
+export function normalizeCommerceProductRecord(
+  product: any,
+  categories: Map<string, string>,
+  manufacturers: Map<string, string>,
+  variantCounts: Map<string, number>,
+  unitCounts: Map<string, number>,
+  reviewCounts: Map<string, number>,
+): CommerceProductRecord {
+  const id = identifier(value(product, 'id', 'uuid'), 'Product')
+  const source = `Product ${id}`
+  const categoryValue = value(product, 'category_id', 'categoryId')
+  const manufacturerValue = value(product, 'manufacturer_id', 'manufacturerId')
+  const categoryId = categoryValue === null || categoryValue === undefined || categoryValue === ''
+    ? ''
+    : identifier(categoryValue, source, 'category_id')
+  const manufacturerId = manufacturerValue === null || manufacturerValue === undefined || manufacturerValue === ''
+    ? ''
+    : identifier(manufacturerValue, source, 'manufacturer_id')
+  const nutritionalInfoRaw = optionalText(value(product, 'nutritional_info', 'nutritionalInfo'), source, 'nutritional_info')
+
+  if (categoryId && !categories.has(categoryId))
+    throw new TypeError(`${source}.category_id references missing Category ${categoryId}.`)
+  if (manufacturerId && !manufacturers.has(manufacturerId))
+    throw new TypeError(`${source}.manufacturer_id references missing Manufacturer ${manufacturerId}.`)
+
+  return {
+    id,
+    name: requiredText(value(product, 'name'), source, 'name'),
+    description: optionalText(value(product, 'description'), source, 'description'),
+    price: number(value(product, 'price'), source, 'price', { min: 0 }),
+    imageUrl: optionalText(value(product, 'image_url', 'imageUrl'), source, 'image_url'),
+    isAvailable: boolean(value(product, 'is_available', 'isAvailable'), source, 'is_available'),
+    inventoryCount: number(value(product, 'inventory_count', 'inventoryCount'), source, 'inventory_count', { min: 0 }),
+    preparationTime: number(value(product, 'preparation_time', 'preparationTime'), source, 'preparation_time', { min: 1 }),
+    allergens: stringArray(value(product, 'allergens'), source, 'allergens'),
+    nutritionalInfo: stringRecord(nutritionalInfoRaw, source, 'nutritional_info'),
+    nutritionalInfoRaw,
+    categoryId,
+    categoryName: categoryId ? categories.get(categoryId)! : 'Unassigned category',
+    manufacturerId,
+    manufacturerName: manufacturerId ? manufacturers.get(manufacturerId)! : 'Unassigned manufacturer',
+    variantCount: variantCounts.get(id) || 0,
+    unitCount: unitCounts.get(id) || 0,
+    reviewCount: reviewCounts.get(id) || 0,
+    createdAt: requiredText(value(product, 'created_at', 'createdAt'), source, 'created_at'),
+  }
+}
+
+export function normalizeProductOption(record: any): ProductOption {
+  const id = identifier(value(record, 'id'), 'Category')
+  return { id, label: requiredText(value(record, 'name'), `Category ${id}`, 'name') }
+}
+
+export function normalizeManufacturerOption(record: any): ProductOption {
+  const id = identifier(value(record, 'id'), 'Manufacturer')
+  return { id, label: requiredText(value(record, 'manufacturer'), `Manufacturer ${id}`, 'manufacturer') }
+}
+
+export function normalizeProductVariantDetail(record: any): ProductVariantDetail {
+  const id = identifier(value(record, 'id'), 'ProductVariant')
+  const source = `ProductVariant ${id}`
+  return {
+    id,
+    name: requiredText(value(record, 'variant'), source, 'variant'),
+    type: requiredText(value(record, 'type'), source, 'type'),
+    description: optionalText(value(record, 'description'), source, 'description'),
+    options: stringArray(value(record, 'options'), source, 'options'),
+    status: requiredText(value(record, 'status'), source, 'status'),
+  }
+}
+
+export function normalizeProductUnitDetail(record: any): ProductUnitDetail {
+  const id = identifier(value(record, 'id'), 'ProductUnit')
+  const source = `ProductUnit ${id}`
+  return {
+    id,
+    name: requiredText(value(record, 'name'), source, 'name'),
+    abbreviation: requiredText(value(record, 'abbreviation'), source, 'abbreviation'),
+    type: requiredText(value(record, 'type'), source, 'type'),
+    description: optionalText(value(record, 'description'), source, 'description'),
+    isDefault: boolean(value(record, 'is_default', 'isDefault'), source, 'is_default'),
+  }
+}
+
+export function summarizeCommerceProducts(records: CommerceProductRecord[]): CommerceProductSummary {
+  return {
+    total: records.length,
+    available: records.filter(record => record.isAvailable).length,
+    unavailable: records.filter(record => !record.isAvailable).length,
+    outOfStock: records.filter(record => record.inventoryCount === 0).length,
+    totalInventory: records.reduce((sum, record) => sum + record.inventoryCount, 0),
+  }
+}
+
+export function summarizeProductReviews(records: any[]): ProductReviewSummary {
+  const ratings = records.map((record, index) =>
+    number(value(record, 'rating'), `Review ${index + 1}`, 'rating', { min: 1, max: 5 }),
+  )
+  const approved = records.filter((record, index) =>
+    boolean(value(record, 'is_approved', 'isApproved'), `Review ${index + 1}`, 'is_approved'),
+  ).length
+  return {
+    total: records.length,
+    approved,
+    pending: records.length - approved,
+    averageRating: ratings.length > 0
+      ? Math.round(ratings.reduce((sum, rating) => sum + rating, 0) / ratings.length * 10) / 10
+      : 0,
+  }
+}

package/app/Actions/Dashboard/Commerce/commerce-record.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  commerceBoolean,
+  commerceCurrency,
+  commerceDate,
+  commerceEmail,
+  commerceEnum,
+  commerceIdentifier,
+  commerceNumber,
+  commerceOptionalIdentifier,
+  commerceOptionalEmail,
+  commerceOptionalNumber,
+  commerceOptionalDate,
+  commerceOptionalString,
+  commerceOptionalTimestamp,
+  commerceRequiredString,
+  commerceStringList,
+  commerceTimestamp,
+  commerceUrl,
+} from './commerce-record'
+
+describe('commerce model record validation', () => {
+  test('normalizes recorded scalar values', () => {
+    expect(commerceIdentifier(7, 'Product')).toBe('7')
+    expect(commerceOptionalIdentifier(null, 'Order 1', 'customer_id')).toBe('')
+    expect(commerceRequiredString(' Widget ', 'Product 7', 'name')).toBe('Widget')
+    expect(commerceOptionalString(null, 'Product 7', 'description')).toBe('')
+    expect(commerceStringList('["US","CA","US"]', 'ShippingZone 1', 'countries')).toEqual(['US', 'CA'])
+    expect(commerceNumber('12.50', 'Product 7', 'price', { min: 0 })).toBe(12.5)
+    expect(commerceOptionalNumber(null, 'Product 7', 'discount')).toBeNull()
+    expect(commerceBoolean('0', 'Product 7', 'is_available')).toBeFalse()
+    expect(commerceEnum('active', 'TaxRate 1', 'status', ['active', 'inactive'])).toBe('active')
+    expect(commerceCurrency(' usd ', 'Order 1')).toBe('USD')
+    expect(commerceDate('2026-07-29', 'Coupon 1', 'start_date')).toBe('2026-07-29')
+    expect(commerceOptionalDate(null, 'Coupon 1', 'end_date')).toBe('')
+    expect(commerceEmail('customer@example.com', 'Customer 1')).toBe('customer@example.com')
+    expect(commerceOptionalEmail(null, 'GiftCard 1', 'recipient_email')).toBe('')
+    expect(commerceUrl('https://example.com/avatar.png', 'Customer 1', 'avatar')).toBe('https://example.com/avatar.png')
+    expect(commerceTimestamp('2026-07-29 12:00:00', 'Order 1')).toBe('2026-07-29T12:00:00.000Z')
+    expect(commerceTimestamp(1_788_583_200, 'GiftCard 1', 'last_used_date')).toBe('2026-09-05T04:40:00.000Z')
+    expect(commerceOptionalTimestamp(null, 'Customer 1', 'last_order')).toBe('')
+  })
+
+  test('rejects coercive and invalid values', () => {
+    expect(() => commerceOptionalIdentifier(0, 'Order 1', 'customer_id')).toThrow('positive integer')
+    expect(() => commerceNumber('', 'Product 7', 'price')).toThrow('finite number')
+    expect(() => commerceNumber('0x10', 'Product 7', 'price')).toThrow('finite number')
+    expect(() => commerceBoolean(null, 'Product 7', 'is_available')).toThrow('boolean')
+    expect(() => commerceStringList('[\"US\"', 'ShippingZone 1', 'countries')).toThrow('JSON array')
+    expect(() => commerceEnum('legacy', 'TaxRate 1', 'status', ['active', 'inactive']))
+      .toThrow('active or inactive')
+    expect(() => commerceCurrency('US', 'Order 1')).toThrow('three-letter currency code')
+    expect(() => commerceDate('2026-02-30', 'Coupon 1', 'start_date')).toThrow('valid YYYY-MM-DD date')
+    expect(() => commerceEmail('not-an-email', 'Customer 1')).toThrow('valid email address')
+    expect(() => commerceUrl('javascript:alert(1)', 'Customer 1', 'avatar')).toThrow('valid HTTP or HTTPS URL')
+    expect(() => commerceTimestamp('not-a-date', 'Order 1')).toThrow('valid timestamp')
+  })
+})

package/app/Actions/Dashboard/Commerce/commerce-record.ts

@@ -0,0 +1,213 @@
+export interface CommerceNumberOptions {
+  min?: number
+  max?: number
+  integer?: boolean
+}
+
+export function commerceValue(record: any, ...keys: string[]): unknown {
+  for (const key of keys) {
+    const result = typeof record?.get === 'function' ? record.get(key) : record?.[key]
+    if (result !== null && result !== undefined)
+      return result
+  }
+  return undefined
+}
+
+export function commerceRecordError(source: string, field: string, expectation: string): TypeError {
+  return new TypeError(`${source}.${field} must be ${expectation}.`)
+}
+
+export function commerceIdentifier(input: unknown, source: string, field = 'id'): string {
+  if (typeof input === 'string' && input.trim())
+    return input.trim()
+  if (typeof input === 'number' && Number.isSafeInteger(input) && input > 0)
+    return String(input)
+  if (typeof input === 'bigint' && input > 0)
+    return String(input)
+  throw commerceRecordError(source, field, 'a positive integer or non-empty string')
+}
+
+export function commerceOptionalIdentifier(input: unknown, source: string, field: string): string {
+  if (input === undefined || input === null || input === '')
+    return ''
+  return commerceIdentifier(input, source, field)
+}
+
+export function commerceRequiredString(input: unknown, source: string, field: string): string {
+  if (typeof input !== 'string' || !input.trim())
+    throw commerceRecordError(source, field, 'a non-empty string')
+  return input.trim()
+}
+
+export function commerceOptionalString(input: unknown, source: string, field: string): string {
+  if (input === undefined || input === null || input === '')
+    return ''
+  if (typeof input !== 'string')
+    throw commerceRecordError(source, field, 'a string or null')
+  return input.trim()
+}
+
+export function commerceStringList(input: unknown, source: string, field: string): string[] {
+  if (input === undefined || input === null || input === '')
+    return []
+
+  let values: unknown[]
+  if (Array.isArray(input)) {
+    values = input
+  }
+  else if (typeof input === 'string') {
+    const raw = input.trim()
+    if (!raw)
+      return []
+    if (raw.startsWith('[') || raw.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(raw)
+        if (!Array.isArray(parsed))
+          throw new TypeError('Expected an array.')
+        values = parsed
+      }
+      catch {
+        throw commerceRecordError(source, field, 'a JSON array or delimited string list')
+      }
+    }
+    else {
+      values = raw.split(/[\n,|;]+/)
+    }
+  }
+  else {
+    throw commerceRecordError(source, field, 'a JSON array or delimited string list')
+  }
+
+  const result = values.map((value) => {
+    if (typeof value !== 'string' || !value.trim())
+      throw commerceRecordError(source, field, 'a list of non-empty strings')
+    return value.trim()
+  })
+  return [...new Set(result)]
+}
+
+export function commerceNumber(
+  input: unknown,
+  source: string,
+  field: string,
+  options: CommerceNumberOptions = {},
+): number {
+  const result = typeof input === 'number'
+    ? input
+    : typeof input === 'string' && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(input.trim())
+      ? Number(input)
+      : Number.NaN
+
+  if (!Number.isFinite(result))
+    throw commerceRecordError(source, field, 'a finite number')
+  if (options.integer && !Number.isInteger(result))
+    throw commerceRecordError(source, field, 'an integer')
+  if (options.min !== undefined && result < options.min)
+    throw commerceRecordError(source, field, `at least ${options.min}`)
+  if (options.max !== undefined && result > options.max)
+    throw commerceRecordError(source, field, `at most ${options.max}`)
+  return result
+}
+
+export function commerceOptionalNumber(
+  input: unknown,
+  source: string,
+  field: string,
+  options: CommerceNumberOptions = {},
+): number | null {
+  if (input === undefined || input === null || input === '')
+    return null
+  return commerceNumber(input, source, field, options)
+}
+
+export function commerceBoolean(input: unknown, source: string, field: string): boolean {
+  if (input === true || input === 1 || input === '1' || input === 'true')
+    return true
+  if (input === false || input === 0 || input === '0' || input === 'false')
+    return false
+  throw commerceRecordError(source, field, 'a boolean')
+}
+
+export function commerceEnum<const T extends string>(
+  input: unknown,
+  source: string,
+  field: string,
+  values: readonly T[],
+): T {
+  const result = commerceRequiredString(input, source, field)
+  if (!values.includes(result as T))
+    throw commerceRecordError(source, field, values.join(' or '))
+  return result as T
+}
+
+export function commerceCurrency(input: unknown, source: string, field = 'currency'): string {
+  const result = commerceRequiredString(input, source, field).toUpperCase()
+  if (!/^[A-Z]{3}$/.test(result))
+    throw commerceRecordError(source, field, 'a three-letter currency code')
+  return result
+}
+
+export function commerceEmail(input: unknown, source: string, field = 'email'): string {
+  const result = commerceRequiredString(input, source, field)
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(result))
+    throw commerceRecordError(source, field, 'a valid email address')
+  return result
+}
+
+export function commerceOptionalEmail(input: unknown, source: string, field = 'email'): string {
+  if (input === undefined || input === null || input === '')
+    return ''
+  return commerceEmail(input, source, field)
+}
+
+export function commerceUrl(input: unknown, source: string, field: string): string {
+  const result = commerceRequiredString(input, source, field)
+  try {
+    const url = new URL(result)
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+      throw new TypeError('Unsupported URL protocol.')
+    return url.toString()
+  }
+  catch {
+    throw commerceRecordError(source, field, 'a valid HTTP or HTTPS URL')
+  }
+}
+
+export function commerceTimestamp(input: unknown, source: string, field = 'created_at'): string {
+  const raw = typeof input === 'number'
+    ? String(input)
+    : commerceRequiredString(input, source, field)
+  const timestamp = /^\d{10}$/.test(raw)
+    ? Number(raw) * 1000
+    : /^\d{13}$/.test(raw)
+      ? Number(raw)
+      : /^\d{4}-\d{2}-\d{2} \d/.test(raw)
+        ? `${raw.replace(' ', 'T')}Z`
+        : raw
+  const date = new Date(timestamp)
+  if (!Number.isFinite(date.getTime()))
+    throw commerceRecordError(source, field, 'a valid timestamp')
+  return date.toISOString()
+}
+
+export function commerceOptionalTimestamp(input: unknown, source: string, field: string): string {
+  if (input === undefined || input === null || input === '')
+    return ''
+  return commerceTimestamp(input, source, field)
+}
+
+export function commerceDate(input: unknown, source: string, field: string): string {
+  const raw = commerceRequiredString(input, source, field)
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(raw))
+    throw commerceRecordError(source, field, 'a valid YYYY-MM-DD date')
+  const date = new Date(`${raw}T00:00:00.000Z`)
+  if (!Number.isFinite(date.getTime()) || date.toISOString().slice(0, 10) !== raw)
+    throw commerceRecordError(source, field, 'a valid YYYY-MM-DD date')
+  return raw
+}
+
+export function commerceOptionalDate(input: unknown, source: string, field: string): string {
+  if (input === undefined || input === null || input === '')
+    return ''
+  return commerceDate(input, source, field)
+}

package/app/Actions/Dashboard/Commerce/coupon-records.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test'
+import { normalizeCouponRecord, summarizeCoupons } from './coupon-records'
+
+function coupon(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 4,
+    code: 'SAVE20',
+    description: 'Twenty percent off',
+    status: 'Active',
+    is_active: true,
+    discount_type: 'percentage',
+    discount_value: 20,
+    min_order_amount: null,
+    max_discount_amount: null,
+    free_product_id: null,
+    usage_limit: null,
+    usage_count: 0,
+    start_date: null,
+    end_date: null,
+    product_id: null,
+    created_at: '2026-06-30 09:00:00',
+    ...overrides,
+  }
+}
+
+describe('dashboard coupon records', () => {
+  test('normalizes persisted Coupon model columns and relationships', () => {
+    expect(normalizeCouponRecord(coupon({
+      is_active: 1,
+      discount_value: '20',
+      min_order_amount: 50,
+      max_discount_amount: 100,
+      free_product_id: 'product-1',
+      usage_limit: 200,
+      usage_count: 27,
+      start_date: '2026-07-01',
+      end_date: '2026-08-01',
+      product_id: 9,
+    }), new Set(['9']))).toEqual({
+      id: '4',
+      code: 'SAVE20',
+      description: 'Twenty percent off',
+      status: 'Active',
+      isActive: true,
+      discountType: 'percentage',
+      discountValue: 20,
+      minOrderAmount: 50,
+      maxDiscountAmount: 100,
+      freeProductId: 'product-1',
+      productId: '9',
+      usageLimit: 200,
+      usageCount: 27,
+      startDate: '2026-07-01',
+      endDate: '2026-08-01',
+      createdAt: '2026-06-30T09:00:00.000Z',
+    })
+  })
+
+  test('preserves absent limits and rejects invalid coupon state', () => {
+    expect(normalizeCouponRecord(coupon())).toMatchObject({
+      minOrderAmount: null,
+      maxDiscountAmount: null,
+      usageLimit: null,
+      productId: '',
+    })
+    expect(() => normalizeCouponRecord(coupon({
+      discount_value: 101,
+    }))).toThrow('at most 100 for percentage coupons')
+    expect(() => normalizeCouponRecord(coupon({
+      product_id: 99,
+    }), new Set())).toThrow('Coupon 4.product_id references missing Product 99')
+    expect(() => normalizeCouponRecord(coupon({
+      start_date: '2026-02-30',
+    }))).toThrow('valid YYYY-MM-DD date')
+  })
+
+  test('summarizes persisted status and usage fields', () => {
+    const records = [
+      normalizeCouponRecord(coupon({ id: 1, status: 'Active', is_active: true, usage_count: 3 })),
+      normalizeCouponRecord(coupon({ id: 2, status: 'Scheduled', is_active: true, usage_count: 2 })),
+      normalizeCouponRecord(coupon({ id: 3, status: 'Expired', is_active: false, usage_count: 8 })),
+    ]
+    expect(summarizeCoupons(records)).toEqual({
+      total: 3,
+      enabled: 2,
+      scheduled: 1,
+      expired: 1,
+      redemptions: 13,
+    })
+  })
+})