@stacksjs/defaults 0.70.229 → 0.70.230

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

@@ -0,0 +1,141 @@
+import {
+  commerceBoolean,
+  commerceEnum,
+  commerceIdentifier,
+  commerceNumber,
+  commerceOptionalDate,
+  commerceOptionalIdentifier,
+  commerceOptionalNumber,
+  commerceOptionalString,
+  commerceRequiredString,
+  commerceTimestamp,
+  commerceValue,
+} from './commerce-record'
+
+export type CouponStatus = 'Active' | 'Scheduled' | 'Expired'
+export type CouponDiscountType = 'fixed_amount' | 'percentage'
+
+export interface CouponRecord {
+  id: string
+  code: string
+  description: string
+  status: CouponStatus
+  isActive: boolean
+  discountType: CouponDiscountType
+  discountValue: number
+  minOrderAmount: number | null
+  maxDiscountAmount: number | null
+  freeProductId: string
+  productId: string
+  usageLimit: number | null
+  usageCount: number
+  startDate: string
+  endDate: string
+  createdAt: string
+}
+
+export interface CouponSummary {
+  total: number
+  enabled: number
+  scheduled: number
+  expired: number
+  redemptions: number
+}
+
+export function normalizeCouponRecord(
+  record: any,
+  productIds = new Set<string>(),
+): CouponRecord {
+  const id = commerceIdentifier(commerceValue(record, 'id', 'uuid'), 'Coupon')
+  const source = `Coupon ${id}`
+  const productId = commerceOptionalIdentifier(
+    commerceValue(record, 'product_id', 'productId'),
+    source,
+    'product_id',
+  )
+  if (productId && !productIds.has(productId))
+    throw new TypeError(`${source}.product_id references missing Product ${productId}.`)
+  const discountType = commerceEnum(
+    commerceValue(record, 'discount_type', 'discountType'),
+    source,
+    'discount_type',
+    ['fixed_amount', 'percentage'],
+  )
+  const discountValue = commerceNumber(
+    commerceValue(record, 'discount_value', 'discountValue'),
+    source,
+    'discount_value',
+    { min: 0.01 },
+  )
+  if (discountType === 'percentage' && discountValue > 100)
+    throw new TypeError(`${source}.discount_value must be at most 100 for percentage coupons.`)
+
+  return {
+    id,
+    code: commerceRequiredString(commerceValue(record, 'code'), source, 'code'),
+    description: commerceOptionalString(commerceValue(record, 'description'), source, 'description'),
+    status: commerceEnum(commerceValue(record, 'status'), source, 'status', [
+      'Active',
+      'Scheduled',
+      'Expired',
+    ]),
+    isActive: commerceBoolean(
+      commerceValue(record, 'is_active', 'isActive'),
+      source,
+      'is_active',
+    ),
+    discountType,
+    discountValue,
+    minOrderAmount: commerceOptionalNumber(
+      commerceValue(record, 'min_order_amount', 'minOrderAmount'),
+      source,
+      'min_order_amount',
+      { min: 0 },
+    ),
+    maxDiscountAmount: commerceOptionalNumber(
+      commerceValue(record, 'max_discount_amount', 'maxDiscountAmount'),
+      source,
+      'max_discount_amount',
+      { min: 0 },
+    ),
+    freeProductId: commerceOptionalString(
+      commerceValue(record, 'free_product_id', 'freeProductId'),
+      source,
+      'free_product_id',
+    ),
+    productId,
+    usageLimit: commerceOptionalNumber(
+      commerceValue(record, 'usage_limit', 'usageLimit'),
+      source,
+      'usage_limit',
+      { min: 1, integer: true },
+    ),
+    usageCount: commerceNumber(
+      commerceValue(record, 'usage_count', 'usageCount'),
+      source,
+      'usage_count',
+      { min: 0, integer: true },
+    ),
+    startDate: commerceOptionalDate(
+      commerceValue(record, 'start_date', 'startDate'),
+      source,
+      'start_date',
+    ),
+    endDate: commerceOptionalDate(
+      commerceValue(record, 'end_date', 'endDate'),
+      source,
+      'end_date',
+    ),
+    createdAt: commerceTimestamp(commerceValue(record, 'created_at', 'createdAt'), source),
+  }
+}
+
+export function summarizeCoupons(records: CouponRecord[]): CouponSummary {
+  return {
+    total: records.length,
+    enabled: records.filter(record => record.isActive).length,
+    scheduled: records.filter(record => record.status === 'Scheduled').length,
+    expired: records.filter(record => record.status === 'Expired').length,
+    redemptions: records.reduce((sum, record) => sum + record.usageCount, 0),
+  }
+}

package/app/Actions/Dashboard/Commerce/delivery-route-records.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  indexDeliveryRouteDrivers,
+  normalizeDeliveryRouteRecord,
+} from './delivery-route-records'
+
+describe('delivery route records', () => {
+  const driver = {
+    id: 2,
+    name: 'Alex Morgan',
+    vehicle_number: 'VAN-204',
+    status: 'active',
+  }
+  const drivers = indexDeliveryRouteDrivers([driver])
+  const base = {
+    id: 1,
+    driver: 'Alex Morgan',
+    driver_id: 2,
+    vehicle: 'VAN-204',
+    stops: 8,
+    delivery_time: 90,
+    total_distance: 42,
+    last_active: '2026-07-29 10:00:00',
+    created_at: '2026-07-29 09:00:00',
+    updated_at: null,
+    uuid: null,
+  }
+
+  test('normalizes route metrics and the linked driver', () => {
+    expect(normalizeDeliveryRouteRecord(base, drivers)).toEqual({
+      id: 1,
+      driver: 'Alex Morgan',
+      driver_id: 2,
+      driver_record: driver,
+      vehicle: 'VAN-204',
+      stops: 8,
+      delivery_time: 90,
+      total_distance: 42,
+      last_active: '2026-07-29T10:00:00.000Z',
+      created_at: '2026-07-29T09:00:00.000Z',
+      updated_at: '',
+      uuid: '',
+    })
+  })
+
+  test('rejects missing drivers and fractional operational counts', () => {
+    expect(() => normalizeDeliveryRouteRecord(base, new Map()))
+      .toThrow('DeliveryRoute 1.driver_id references missing Driver 2')
+    expect(() => normalizeDeliveryRouteRecord({ ...base, driver_id: null, stops: 1.5 }, drivers))
+      .toThrow('DeliveryRoute 1.stops must be an integer')
+  })
+})

package/app/Actions/Dashboard/Commerce/delivery-route-records.ts

@@ -0,0 +1,113 @@
+import {
+  commerceEnum,
+  commerceNumber,
+  commerceOptionalIdentifier,
+  commerceOptionalString,
+  commerceOptionalTimestamp,
+  commerceRequiredString,
+  commerceTimestamp,
+  commerceValue,
+} from './commerce-record'
+import type { DriverStatus } from './driver-records'
+import { driverStatuses } from './driver-records'
+
+export interface DeliveryRouteDriver {
+  id: number
+  name: string
+  vehicle_number: string
+  status: DriverStatus
+}
+
+export interface DeliveryRouteRecord {
+  id: number
+  driver: string
+  driver_id: number | null
+  driver_record: DeliveryRouteDriver | null
+  vehicle: string
+  stops: number
+  delivery_time: number
+  total_distance: number
+  last_active: string
+  created_at: string
+  updated_at: string
+  uuid: string
+}
+
+function numericIdentifier(input: unknown, source: string, field = 'id'): number {
+  const id = commerceNumber(input, source, field, { integer: true, min: 1 })
+  if (!Number.isSafeInteger(id))
+    throw new TypeError(`${source}.${field} must be a safe positive integer.`)
+  return id
+}
+
+export function indexDeliveryRouteDrivers(records: any[]): Map<number, DeliveryRouteDriver> {
+  const result = new Map<number, DeliveryRouteDriver>()
+  for (const record of records) {
+    const id = numericIdentifier(commerceValue(record, 'id'), 'Driver')
+    const source = `Driver ${id}`
+    if (result.has(id))
+      throw new TypeError(`Duplicate Driver ${id}.`)
+    result.set(id, {
+      id,
+      name: commerceRequiredString(commerceValue(record, 'name'), source, 'name'),
+      vehicle_number: commerceRequiredString(
+        commerceValue(record, 'vehicle_number', 'vehicleNumber'),
+        source,
+        'vehicle_number',
+      ),
+      status: commerceEnum(commerceValue(record, 'status'), source, 'status', driverStatuses),
+    })
+  }
+  return result
+}
+
+export function normalizeDeliveryRouteRecord(
+  record: any,
+  drivers: ReadonlyMap<number, DeliveryRouteDriver>,
+): DeliveryRouteRecord {
+  const id = numericIdentifier(commerceValue(record, 'id'), 'DeliveryRoute')
+  const source = `DeliveryRoute ${id}`
+  const driverIdentifier = commerceOptionalIdentifier(
+    commerceValue(record, 'driver_id', 'driverId'),
+    source,
+    'driver_id',
+  )
+  const driverId = driverIdentifier
+    ? numericIdentifier(driverIdentifier, source, 'driver_id')
+    : null
+  const driverRecord = driverId ? drivers.get(driverId) : undefined
+  if (driverId && !driverRecord)
+    throw new TypeError(`${source}.driver_id references missing Driver ${driverId}.`)
+
+  return {
+    id,
+    driver: commerceRequiredString(commerceValue(record, 'driver'), source, 'driver'),
+    driver_id: driverId,
+    driver_record: driverRecord || null,
+    vehicle: commerceRequiredString(commerceValue(record, 'vehicle'), source, 'vehicle'),
+    stops: commerceNumber(commerceValue(record, 'stops'), source, 'stops', {
+      integer: true,
+      min: 0,
+    }),
+    delivery_time: commerceNumber(
+      commerceValue(record, 'delivery_time', 'deliveryTime'),
+      source,
+      'delivery_time',
+      { integer: true, min: 0 },
+    ),
+    total_distance: commerceNumber(
+      commerceValue(record, 'total_distance', 'totalDistance'),
+      source,
+      'total_distance',
+      { integer: true, min: 0 },
+    ),
+    last_active: commerceTimestamp(
+      commerceValue(record, 'last_active', 'lastActive'),
+      source,
+      'last_active',
+    ),
+    created_at: commerceTimestamp(commerceValue(record, 'created_at', 'createdAt'), source),
+    updated_at: commerceOptionalTimestamp(commerceValue(record, 'updated_at', 'updatedAt'), source, 'updated_at'),
+    uuid: commerceOptionalString(commerceValue(record, 'uuid'), source, 'uuid'),
+  }
+}

package/app/Actions/Dashboard/Commerce/digital-delivery-records.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from 'bun:test'
+import { normalizeDigitalDeliveryRecord } from './digital-delivery-records'
+
+describe('digital delivery records', () => {
+  test('normalizes persisted delivery settings', () => {
+    expect(normalizeDigitalDeliveryRecord({
+      id: 1,
+      name: 'Secure download',
+      description: 'Authenticated file delivery',
+      download_limit: null,
+      expiry_days: 30,
+      requires_login: 1,
+      automatic_delivery: 0,
+      status: 'active',
+      created_at: '2026-07-29 10:00:00',
+      updated_at: null,
+      uuid: null,
+    })).toEqual({
+      id: 1,
+      name: 'Secure download',
+      description: 'Authenticated file delivery',
+      download_limit: null,
+      expiry_days: 30,
+      requires_login: true,
+      automatic_delivery: false,
+      status: 'active',
+      created_at: '2026-07-29T10:00:00.000Z',
+      updated_at: '',
+      uuid: '',
+    })
+  })
+
+  test('rejects invalid limits, flags, and statuses', () => {
+    const base = {
+      id: 1,
+      name: 'Secure download',
+      description: 'Authenticated file delivery',
+      download_limit: 5,
+      expiry_days: 30,
+      requires_login: true,
+      automatic_delivery: false,
+      status: 'active',
+      created_at: '2026-07-29 10:00:00',
+    }
+    expect(() => normalizeDigitalDeliveryRecord({ ...base, download_limit: 1.5 }))
+      .toThrow('DigitalDelivery 1.download_limit must be an integer')
+    expect(() => normalizeDigitalDeliveryRecord({ ...base, requires_login: 'yes' }))
+      .toThrow('DigitalDelivery 1.requires_login must be a boolean')
+    expect(() => normalizeDigitalDeliveryRecord({ ...base, status: 'pending' }))
+      .toThrow('DigitalDelivery 1.status must be active or inactive')
+  })
+})

package/app/Actions/Dashboard/Commerce/digital-delivery-records.ts

@@ -0,0 +1,70 @@
+import {
+  commerceBoolean,
+  commerceEnum,
+  commerceNumber,
+  commerceOptionalNumber,
+  commerceOptionalString,
+  commerceOptionalTimestamp,
+  commerceRequiredString,
+  commerceTimestamp,
+  commerceValue,
+} from './commerce-record'
+
+export const digitalDeliveryStatuses = ['active', 'inactive'] as const
+export type DigitalDeliveryStatus = typeof digitalDeliveryStatuses[number]
+
+export interface DigitalDeliveryRecord {
+  id: number
+  name: string
+  description: string
+  download_limit: number | null
+  expiry_days: number
+  requires_login: boolean
+  automatic_delivery: boolean
+  status: DigitalDeliveryStatus
+  created_at: string
+  updated_at: string
+  uuid: string
+}
+
+export function normalizeDigitalDeliveryRecord(record: any): DigitalDeliveryRecord {
+  const id = commerceNumber(commerceValue(record, 'id'), 'DigitalDelivery', 'id', {
+    integer: true,
+    min: 1,
+  })
+  if (!Number.isSafeInteger(id))
+    throw new TypeError('DigitalDelivery.id must be a safe positive integer.')
+  const source = `DigitalDelivery ${id}`
+
+  return {
+    id,
+    name: commerceRequiredString(commerceValue(record, 'name'), source, 'name'),
+    description: commerceRequiredString(commerceValue(record, 'description'), source, 'description'),
+    download_limit: commerceOptionalNumber(
+      commerceValue(record, 'download_limit', 'downloadLimit'),
+      source,
+      'download_limit',
+      { integer: true, min: 0 },
+    ),
+    expiry_days: commerceNumber(
+      commerceValue(record, 'expiry_days', 'expiryDays'),
+      source,
+      'expiry_days',
+      { integer: true, min: 0 },
+    ),
+    requires_login: commerceBoolean(
+      commerceValue(record, 'requires_login', 'requiresLogin'),
+      source,
+      'requires_login',
+    ),
+    automatic_delivery: commerceBoolean(
+      commerceValue(record, 'automatic_delivery', 'automaticDelivery'),
+      source,
+      'automatic_delivery',
+    ),
+    status: commerceEnum(commerceValue(record, 'status'), source, 'status', digitalDeliveryStatuses),
+    created_at: commerceTimestamp(commerceValue(record, 'created_at', 'createdAt'), source),
+    updated_at: commerceOptionalTimestamp(commerceValue(record, 'updated_at', 'updatedAt'), source, 'updated_at'),
+    uuid: commerceOptionalString(commerceValue(record, 'uuid'), source, 'uuid'),
+  }
+}

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

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'bun:test'
+import { indexDriverUsers, normalizeDriverRecord } from './driver-records'
+
+describe('driver records', () => {
+  const user = { id: 2, name: 'Ada Lovelace', email: 'ada@example.com' }
+  const users = indexDriverUsers([user])
+  const base = {
+    id: 1,
+    name: 'Alex Morgan',
+    phone: '+1 555 0100',
+    vehicle_number: 'VAN-204',
+    license: 'D1234567',
+    status: 'active',
+    user_id: 2,
+    created_at: '2026-07-29 10:00:00',
+    updated_at: null,
+    uuid: null,
+  }
+
+  test('normalizes drivers and linked users', () => {
+    expect(normalizeDriverRecord(base, users)).toEqual({
+      id: 1,
+      name: 'Alex Morgan',
+      phone: '+1 555 0100',
+      vehicle_number: 'VAN-204',
+      license: 'D1234567',
+      status: 'active',
+      user_id: 2,
+      user,
+      created_at: '2026-07-29T10:00:00.000Z',
+      updated_at: '',
+      uuid: '',
+    })
+  })
+
+  test('rejects missing users and unknown statuses', () => {
+    expect(() => normalizeDriverRecord(base, new Map()))
+      .toThrow('Driver 1.user_id references missing User 2')
+    expect(() => normalizeDriverRecord({ ...base, user_id: null, status: 'offline' }, users))
+      .toThrow('Driver 1.status must be active or on_delivery or on_break')
+  })
+})

package/app/Actions/Dashboard/Commerce/driver-records.ts

@@ -0,0 +1,92 @@
+import {
+  commerceEmail,
+  commerceEnum,
+  commerceNumber,
+  commerceOptionalIdentifier,
+  commerceOptionalString,
+  commerceOptionalTimestamp,
+  commerceRequiredString,
+  commerceTimestamp,
+  commerceValue,
+} from './commerce-record'
+
+export const driverStatuses = ['active', 'on_delivery', 'on_break'] as const
+export type DriverStatus = typeof driverStatuses[number]
+
+export interface DriverUser {
+  id: number
+  name: string
+  email: string
+}
+
+export interface DriverRecord {
+  id: number
+  name: string
+  phone: string
+  vehicle_number: string
+  license: string
+  status: DriverStatus
+  user_id: number | null
+  user: DriverUser | null
+  created_at: string
+  updated_at: string
+  uuid: string
+}
+
+function numericIdentifier(input: unknown, source: string, field = 'id'): number {
+  const id = commerceNumber(input, source, field, { integer: true, min: 1 })
+  if (!Number.isSafeInteger(id))
+    throw new TypeError(`${source}.${field} must be a safe positive integer.`)
+  return id
+}
+
+export function indexDriverUsers(records: any[]): Map<number, DriverUser> {
+  const result = new Map<number, DriverUser>()
+  for (const record of records) {
+    const id = numericIdentifier(commerceValue(record, 'id'), 'User')
+    const source = `User ${id}`
+    if (result.has(id))
+      throw new TypeError(`Duplicate User ${id}.`)
+    result.set(id, {
+      id,
+      name: commerceRequiredString(commerceValue(record, 'name'), source, 'name'),
+      email: commerceEmail(commerceValue(record, 'email'), source),
+    })
+  }
+  return result
+}
+
+export function normalizeDriverRecord(
+  record: any,
+  users: ReadonlyMap<number, DriverUser>,
+): DriverRecord {
+  const id = numericIdentifier(commerceValue(record, 'id'), 'Driver')
+  const source = `Driver ${id}`
+  const userIdentifier = commerceOptionalIdentifier(
+    commerceValue(record, 'user_id', 'userId'),
+    source,
+    'user_id',
+  )
+  const userId = userIdentifier ? numericIdentifier(userIdentifier, source, 'user_id') : null
+  const user = userId ? users.get(userId) : undefined
+  if (userId && !user)
+    throw new TypeError(`${source}.user_id references missing User ${userId}.`)
+
+  return {
+    id,
+    name: commerceRequiredString(commerceValue(record, 'name'), source, 'name'),
+    phone: commerceRequiredString(commerceValue(record, 'phone'), source, 'phone'),
+    vehicle_number: commerceRequiredString(
+      commerceValue(record, 'vehicle_number', 'vehicleNumber'),
+      source,
+      'vehicle_number',
+    ),
+    license: commerceRequiredString(commerceValue(record, 'license'), source, 'license'),
+    status: commerceEnum(commerceValue(record, 'status'), source, 'status', driverStatuses),
+    user_id: userId,
+    user: user || null,
+    created_at: commerceTimestamp(commerceValue(record, 'created_at', 'createdAt'), source),
+    updated_at: commerceOptionalTimestamp(commerceValue(record, 'updated_at', 'updatedAt'), source, 'updated_at'),
+    uuid: commerceOptionalString(commerceValue(record, 'uuid'), source, 'uuid'),
+  }
+}

package/app/Actions/Dashboard/Commerce/gift-card-records.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from 'bun:test'
+import { normalizeGiftCardRecord, summarizeGiftCards } from './gift-card-records'
+
+function giftCard(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 42,
+    code: 'STACKS-42',
+    initial_balance: 100,
+    current_balance: 25,
+    currency: 'USD',
+    status: 'ACTIVE',
+    purchaser_id: null,
+    recipient_email: null,
+    recipient_name: null,
+    personal_message: null,
+    is_digital: false,
+    is_reloadable: false,
+    is_active: true,
+    expiry_date: null,
+    last_used_date: null,
+    template_id: null,
+    customer_id: null,
+    created_at: '2026-07-29 12:00:00',
+    ...overrides,
+  }
+}
+
+describe('dashboard gift card records', () => {
+  test('normalizes model columns, balances, and timestamps without clamping reloads', () => {
+    const record = normalizeGiftCardRecord(giftCard({
+      current_balance: 125,
+      currency: 'usd',
+      recipient_email: 'gift@example.com',
+      recipient_name: 'Ada',
+      is_digital: 1,
+      is_reloadable: 'true',
+      expiry_date: '2027-01-02 03:04:05',
+      last_used_date: 1_788_583_200,
+    }))
+
+    expect(record).toMatchObject({
+      id: '42',
+      code: 'STACKS-42',
+      initialBalance: 100,
+      currentBalance: 125,
+      currency: 'USD',
+      status: 'ACTIVE',
+      recipientEmail: 'gift@example.com',
+      recipientName: 'Ada',
+      isDigital: true,
+      isReloadable: true,
+      isActive: true,
+      expiryDate: '2027-01-02T03:04:05.000Z',
+      lastUsedDate: '2026-09-05T04:40:00.000Z',
+      createdAt: '2026-07-29T12:00:00.000Z',
+    })
+  })
+
+  test('rejects corrupt values and missing customer relationships', () => {
+    expect(() => normalizeGiftCardRecord(giftCard({
+      current_balance: -1,
+    }))).toThrow('GiftCard 42.current_balance must be at least 0')
+
+    expect(() => normalizeGiftCardRecord(giftCard({
+      status: 'legacy',
+    }))).toThrow('GiftCard 42.status must be ACTIVE')
+
+    expect(() => normalizeGiftCardRecord(
+      giftCard({ customer_id: 7 }),
+      new Set(),
+    )).toThrow('GiftCard 42.customer_id references missing Customer 7')
+  })
+
+  test('keeps currency totals separate and derives real availability', () => {
+    const records = [
+      normalizeGiftCardRecord(giftCard({
+        id: 1,
+        code: 'USD-1',
+        initial_balance: 100,
+        current_balance: 25,
+        currency: 'USD',
+        status: 'ACTIVE',
+        is_active: true,
+        is_digital: true,
+      })),
+      normalizeGiftCardRecord(giftCard({
+        id: 2,
+        code: 'USD-2',
+        initial_balance: 50,
+        current_balance: 0,
+        currency: 'USD',
+        status: 'USED',
+        is_active: true,
+        is_reloadable: true,
+      })),
+      normalizeGiftCardRecord(giftCard({
+        id: 3,
+        code: 'EUR-1',
+        initial_balance: 80,
+        current_balance: 40,
+        currency: 'EUR',
+        status: 'ACTIVE',
+        is_active: false,
+      })),
+    ]
+
+    expect(summarizeGiftCards(records)).toEqual({
+      total: 3,
+      available: 1,
+      enabled: 2,
+      digital: 1,
+      reloadable: 1,
+      statuses: { ACTIVE: 2, USED: 1, EXPIRED: 0, DEACTIVATED: 0 },
+      currencies: [
+        { currency: 'EUR', cards: 1, initialBalance: 80, currentBalance: 40, redeemedBalance: 40 },
+        { currency: 'USD', cards: 2, initialBalance: 150, currentBalance: 25, redeemedBalance: 125 },
+      ],
+    })
+  })
+})