@stacksjs/defaults 0.70.229 → 0.70.231

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

@@ -0,0 +1,281 @@
+export interface DeliveryOverviewStat {
+  label: string
+  value: string
+  detail: string
+}
+
+export interface DeliveryOverviewRoute {
+  id: number
+  driver: string
+  vehicle: string
+  stops: number
+  duration: string
+  distance: string
+  lastActive: number
+}
+
+export interface DeliveryOverviewMethod {
+  id: number
+  name: string
+  status: string
+  baseRate: string
+  freeShipping: string
+}
+
+export interface DeliveryOverviewZone {
+  id: number
+  name: string
+  status: string
+  countries: number
+  regions: number
+}
+
+export interface DeliveryOverviewResult {
+  stats: DeliveryOverviewStat[]
+  routes: DeliveryOverviewRoute[]
+  methods: DeliveryOverviewMethod[]
+  zones: DeliveryOverviewZone[]
+  drivers: {
+    total: number
+    active: number
+    onDelivery: number
+    onBreak: number
+  }
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000
+
+function formatMoney(cents: number, currency: string): string {
+  try {
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency,
+    }).format(cents / 100)
+  }
+  catch {
+    return `${currency} ${(cents / 100).toFixed(2)}`
+  }
+}
+
+export function deliveryTimestamp(input: unknown, source = 'DeliveryRoute', field = 'last_active'): number {
+  const raw = typeof input === 'number' ? String(input) : commerceRequiredString(input, source, field)
+  if (/^\d{10,13}$/.test(raw)) {
+    const timestamp = raw.length === 10 ? Number(raw) * 1000 : Number(raw)
+    if (Number.isSafeInteger(timestamp))
+      return timestamp
+  }
+
+  const normalized = /^\d{4}-\d{2}-\d{2} \d/.test(raw)
+    ? `${raw.replace(' ', 'T')}Z`
+    : raw
+  const timestamp = new Date(normalized).getTime()
+  if (!Number.isFinite(timestamp))
+    throw new TypeError(`${source}.${field} must be a valid Unix or ISO timestamp.`)
+  return timestamp
+}
+
+export function formatDeliveryDuration(minutes: number): string {
+  if (minutes < 60)
+    return `${minutes} min`
+
+  const hours = Math.floor(minutes / 60)
+  const remainingMinutes = minutes % 60
+  return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`
+}
+
+export function buildDeliveryOverview(
+  methodRows: any[],
+  routeRows: any[],
+  zoneRows: any[],
+  driverRows: any[],
+  currency = 'USD',
+  now = new Date(),
+): DeliveryOverviewResult {
+  const normalizedCurrency = commerceCurrency(currency, 'Commerce configuration')
+  const normalizedDrivers = driverRows.map((driver) => {
+    const identifier = commerceIdentifier(commerceValue(driver, 'id', 'uuid'), 'Driver')
+    const source = `Driver ${identifier}`
+    return {
+      id: identifier,
+      name: commerceRequiredString(commerceValue(driver, 'name'), source, 'name'),
+      vehicle: commerceRequiredString(
+        commerceValue(driver, 'vehicle_number', 'vehicleNumber'),
+        source,
+        'vehicle_number',
+      ),
+      status: commerceEnum(commerceValue(driver, 'status'), source, 'status', [
+        'active',
+        'on_delivery',
+        'on_break',
+      ]),
+    }
+  })
+  const driversById = new Map(normalizedDrivers.map(driver => [driver.id, driver]))
+
+  const routeMinutesById = new Map<number, number>()
+  const allRoutes = routeRows.map((route): DeliveryOverviewRoute => {
+    const numericId = commerceNumber(commerceValue(route, 'id'), 'DeliveryRoute', 'id', {
+      min: 1,
+      integer: true,
+    })
+    const source = `DeliveryRoute ${numericId}`
+    const driverId = commerceOptionalIdentifier(
+      commerceValue(route, 'driver_id', 'driverId'),
+      source,
+      'driver_id',
+    )
+    const linkedDriver = driverId ? driversById.get(driverId) : undefined
+    if (driverId && !linkedDriver)
+      throw new TypeError(`${source}.driver_id references missing Driver ${driverId}.`)
+    const deliveryTime = commerceNumber(
+      commerceValue(route, 'delivery_time', 'deliveryTime'),
+      source,
+      'delivery_time',
+      { min: 0, integer: true },
+    )
+    routeMinutesById.set(numericId, deliveryTime)
+    return {
+      id: numericId,
+      driver: linkedDriver?.name
+        || commerceRequiredString(commerceValue(route, 'driver'), source, 'driver'),
+      vehicle: linkedDriver?.vehicle
+        || commerceRequiredString(commerceValue(route, 'vehicle'), source, 'vehicle'),
+      stops: commerceNumber(commerceValue(route, 'stops'), source, 'stops', {
+        min: 0,
+        integer: true,
+      }),
+      duration: formatDeliveryDuration(deliveryTime),
+      distance: `${commerceNumber(
+        commerceValue(route, 'total_distance', 'totalDistance'),
+        source,
+        'total_distance',
+        { min: 0 },
+      ).toLocaleString('en-US')} mi`,
+      lastActive: deliveryTimestamp(
+        commerceValue(route, 'last_active', 'lastActive'),
+        source,
+        'last_active',
+      ),
+    }
+  })
+
+  const activeCutoff = now.getTime() - DAY_MS
+  const activeRoutes = allRoutes
+    .filter(route => route.lastActive >= activeCutoff && route.lastActive <= now.getTime())
+    .sort((left, right) => right.lastActive - left.lastActive)
+  const methods = methodRows
+    .map((method): DeliveryOverviewMethod => {
+      const id = commerceNumber(commerceValue(method, 'id'), 'ShippingMethod', 'id', {
+        min: 1,
+        integer: true,
+      })
+      const source = `ShippingMethod ${id}`
+      const threshold = commerceOptionalNumber(
+        commerceValue(method, 'free_shipping', 'freeShipping'),
+        source,
+        'free_shipping',
+        { min: 0 },
+      )
+      return {
+        id,
+        name: commerceRequiredString(commerceValue(method, 'name'), source, 'name'),
+        status: commerceEnum(commerceValue(method, 'status'), source, 'status', [
+          'active',
+          'inactive',
+          'draft',
+        ]),
+        baseRate: formatMoney(commerceNumber(
+          commerceValue(method, 'base_rate', 'baseRate'),
+          source,
+          'base_rate',
+          { min: 0 },
+        ), normalizedCurrency),
+        freeShipping: threshold === null
+          ? 'Not enabled'
+          : formatMoney(threshold, normalizedCurrency),
+      }
+    })
+    .sort((left, right) => {
+      const statusOrder = Number(right.status === 'active') - Number(left.status === 'active')
+      return statusOrder || left.name.localeCompare(right.name)
+    })
+
+  const zones = zoneRows
+    .map((zone): DeliveryOverviewZone => {
+      const id = commerceNumber(commerceValue(zone, 'id'), 'ShippingZone', 'id', {
+        min: 1,
+        integer: true,
+      })
+      const source = `ShippingZone ${id}`
+      return {
+        id,
+        name: commerceRequiredString(commerceValue(zone, 'name'), source, 'name'),
+        status: commerceEnum(commerceValue(zone, 'status'), source, 'status', [
+          'active',
+          'inactive',
+          'draft',
+        ]),
+        countries: commerceStringList(commerceValue(zone, 'countries'), source, 'countries').length,
+        regions: commerceStringList(commerceValue(zone, 'regions'), source, 'regions').length,
+      }
+    })
+    .sort((left, right) => {
+      const statusOrder = Number(right.status === 'active') - Number(left.status === 'active')
+      return statusOrder || left.name.localeCompare(right.name)
+    })
+
+  const driverStatusCounts = normalizedDrivers.reduce<Record<string, number>>((counts, driver) => {
+    counts[driver.status] = (counts[driver.status] || 0) + 1
+    return counts
+  }, {})
+
+  const averageRouteMinutes = activeRoutes.length > 0
+    ? Math.round(activeRoutes.reduce((total, route) => total + (routeMinutesById.get(route.id) || 0), 0) / activeRoutes.length)
+    : 0
+  const activeZones = zones.filter(zone => zone.status === 'active')
+
+  return {
+    stats: [
+      {
+        label: 'Active Routes',
+        value: activeRoutes.length.toLocaleString('en-US'),
+        detail: `${activeRoutes.reduce((total, route) => total + route.stops, 0).toLocaleString('en-US')} stops active in 24h`,
+      },
+      {
+        label: 'Drivers on Delivery',
+        value: (driverStatusCounts.on_delivery || 0).toLocaleString('en-US'),
+        detail: `${driverRows.length.toLocaleString('en-US')} drivers total`,
+      },
+      {
+        label: 'Average Route',
+        value: formatDeliveryDuration(averageRouteMinutes),
+        detail: activeRoutes.length > 0 ? 'Active planned duration' : 'No active route duration',
+      },
+      {
+        label: 'Active Zones',
+        value: activeZones.length.toLocaleString('en-US'),
+        detail: `${activeZones.reduce((total, zone) => total + zone.countries, 0).toLocaleString('en-US')} country assignments`,
+      },
+    ],
+    routes: activeRoutes.slice(0, 5),
+    methods: methods.slice(0, 5),
+    zones: zones.slice(0, 5),
+    drivers: {
+      total: normalizedDrivers.length,
+      active: driverStatusCounts.active || 0,
+      onDelivery: driverStatusCounts.on_delivery || 0,
+      onBreak: driverStatusCounts.on_break || 0,
+    },
+  }
+}
+import {
+  commerceCurrency,
+  commerceEnum,
+  commerceIdentifier,
+  commerceNumber,
+  commerceOptionalIdentifier,
+  commerceOptionalNumber,
+  commerceRequiredString,
+  commerceStringList,
+  commerceValue,
+} from './commerce-record'

package/app/Actions/Dashboard/Commerce/commerce-order-records.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  addOrderItemQuantity,
+  normalizeCommerceOrderRecord,
+  normalizeOrderCustomerContext,
+  normalizeOrderCustomerOption,
+  summarizeCommerceOrders,
+} from './commerce-order-records'
+
+function order(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 12,
+    customer_id: null,
+    status: 'READY',
+    total_amount: 90,
+    currency: 'EUR',
+    tax_amount: 10,
+    discount_amount: 5,
+    delivery_fee: 4,
+    tip_amount: 3,
+    order_type: 'DELIVERY',
+    delivery_address: null,
+    special_instructions: null,
+    estimated_delivery_time: null,
+    applied_coupon_id: null,
+    coupon_id: null,
+    created_at: '2026-07-29 12:00:00',
+    ...overrides,
+  }
+}
+
+describe('dashboard commerce order records', () => {
+  test('normalizes persisted order fields and joined context', () => {
+    const record = normalizeCommerceOrderRecord(
+      order({ customer_id: 3, coupon_id: 7, currency: 'eur' }),
+      new Map([['3', { name: 'Ada', email: 'ada@example.test' }]]),
+      new Map([['12', 4]]),
+      new Set(['7']),
+    )
+
+    expect(record).toMatchObject({
+      id: '12',
+      customerId: '3',
+      customerName: 'Ada',
+      customerEmail: 'ada@example.test',
+      status: 'READY',
+      totalAmount: 90,
+      currency: 'EUR',
+      taxAmount: 10,
+      discountAmount: 5,
+      deliveryFee: 4,
+      tipAmount: 3,
+      orderType: 'DELIVERY',
+      couponId: '7',
+      itemCount: 4,
+      createdAt: '2026-07-29T12:00:00.000Z',
+    })
+  })
+
+  test('rejects corrupt values and missing relationships', () => {
+    expect(() => normalizeCommerceOrderRecord(
+      order({ total_amount: 'free' }),
+      new Map(),
+      new Map(),
+    )).toThrow('Order 12.total_amount must be a finite number')
+
+    expect(() => normalizeCommerceOrderRecord(
+      order({ customer_id: 3 }),
+      new Map(),
+      new Map(),
+    )).toThrow('Order 12.customer_id references missing Customer 3')
+
+    expect(() => normalizeCommerceOrderRecord(
+      order({ coupon_id: 7 }),
+      new Map(),
+      new Map(),
+      new Set(),
+    )).toThrow('Order 12.coupon_id references missing Coupon 7')
+  })
+
+  test('sums validated item quantities instead of line count', () => {
+    const orderIds = new Set(['12'])
+    const itemCounts = new Map<string, number>()
+    addOrderItemQuantity({ id: 1, order_id: 12, quantity: 2 }, orderIds, itemCounts)
+    addOrderItemQuantity({ id: 2, order_id: 12, quantity: 3 }, orderIds, itemCounts)
+    expect(itemCounts.get('12')).toBe(5)
+    expect(() => addOrderItemQuantity(
+      { id: 3, order_id: 99, quantity: 1 },
+      orderIds,
+      itemCounts,
+    )).toThrow('OrderItem 3.order_id references missing Order 99')
+  })
+
+  test('keeps currencies separate and summarizes persisted states', () => {
+    const records = [
+      normalizeCommerceOrderRecord(order({ id: 1, status: 'PENDING', total_amount: 10, currency: 'USD' }), new Map(), new Map()),
+      normalizeCommerceOrderRecord(order({ id: 2, status: 'READY', total_amount: 20, currency: 'USD' }), new Map(), new Map()),
+      normalizeCommerceOrderRecord(order({ id: 3, status: 'paid', total_amount: 30, currency: 'EUR' }), new Map(), new Map()),
+      normalizeCommerceOrderRecord(order({ id: 4, status: 'CANCELED', total_amount: 40, currency: 'USD' }), new Map(), new Map()),
+    ]
+
+    expect(summarizeCommerceOrders(records)).toEqual({
+      total: 4,
+      pending: 1,
+      inProgress: 1,
+      completed: 1,
+      cancelled: 1,
+      currencyTotals: [
+        { currency: 'EUR', amount: 30 },
+        { currency: 'USD', amount: 70 },
+      ],
+    })
+  })
+
+  test('validates customer option and lookup records', () => {
+    expect(normalizeOrderCustomerOption({
+      id: 5,
+      name: 'Guest customer',
+      email: 'guest@example.test',
+    })).toEqual({
+      id: '5',
+      label: 'Guest customer',
+    })
+    expect(normalizeOrderCustomerContext({
+      id: 5,
+      name: 'Guest customer',
+      email: 'guest@example.test',
+    })).toEqual({
+      id: '5',
+      context: {
+        name: 'Guest customer',
+        email: 'guest@example.test',
+      },
+    })
+  })
+})

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

@@ -0,0 +1,213 @@
+import {
+  commerceCurrency,
+  commerceEmail,
+  commerceIdentifier,
+  commerceNumber,
+  commerceOptionalIdentifier,
+  commerceOptionalString,
+  commerceOptionalTimestamp,
+  commerceRequiredString,
+  commerceTimestamp,
+  commerceValue,
+} from './commerce-record'
+
+export interface CommerceOrderRecord {
+  id: string
+  customerId: string
+  customerName: string
+  customerEmail: string
+  status: string
+  totalAmount: number
+  currency: string
+  taxAmount: number
+  discountAmount: number
+  deliveryFee: number
+  tipAmount: number
+  orderType: string
+  deliveryAddress: string
+  specialInstructions: string
+  estimatedDeliveryTime: string
+  appliedCouponId: string
+  couponId: string
+  itemCount: number
+  createdAt: string
+}
+
+export interface CommerceOrderSummary {
+  total: number
+  pending: number
+  inProgress: number
+  completed: number
+  cancelled: number
+  currencyTotals: Array<{ currency: string, amount: number }>
+}
+
+export interface OrderCustomerOption {
+  id: string
+  label: string
+}
+
+export interface OrderCustomerContext {
+  name: string
+  email: string
+}
+
+export function normalizeCommerceOrderRecord(
+  order: any,
+  customers: Map<string, OrderCustomerContext>,
+  itemCounts: Map<string, number>,
+  couponIds = new Set<string>(),
+): CommerceOrderRecord {
+  const id = commerceIdentifier(commerceValue(order, 'id', 'uuid'), 'Order')
+  const source = `Order ${id}`
+  const customerId = commerceOptionalIdentifier(
+    commerceValue(order, 'customer_id', 'customerId'),
+    source,
+    'customer_id',
+  )
+  const customer = customers.get(customerId)
+  if (customerId && !customer)
+    throw new TypeError(`${source}.customer_id references missing Customer ${customerId}.`)
+
+  const couponId = commerceOptionalIdentifier(
+    commerceValue(order, 'coupon_id', 'couponId'),
+    source,
+    'coupon_id',
+  )
+  if (couponId && !couponIds.has(couponId))
+    throw new TypeError(`${source}.coupon_id references missing Coupon ${couponId}.`)
+
+  return {
+    id,
+    customerId,
+    customerName: customer?.name || '',
+    customerEmail: customer?.email || '',
+    status: commerceRequiredString(commerceValue(order, 'status'), source, 'status'),
+    totalAmount: commerceNumber(
+      commerceValue(order, 'total_amount', 'totalAmount'),
+      source,
+      'total_amount',
+      { min: 0 },
+    ),
+    currency: commerceCurrency(commerceValue(order, 'currency'), source),
+    taxAmount: commerceNumber(
+      commerceValue(order, 'tax_amount', 'taxAmount'),
+      source,
+      'tax_amount',
+      { min: 0 },
+    ),
+    discountAmount: commerceNumber(
+      commerceValue(order, 'discount_amount', 'discountAmount'),
+      source,
+      'discount_amount',
+      { min: 0 },
+    ),
+    deliveryFee: commerceNumber(
+      commerceValue(order, 'delivery_fee', 'deliveryFee'),
+      source,
+      'delivery_fee',
+      { min: 0 },
+    ),
+    tipAmount: commerceNumber(
+      commerceValue(order, 'tip_amount', 'tipAmount'),
+      source,
+      'tip_amount',
+      { min: 0 },
+    ),
+    orderType: commerceRequiredString(
+      commerceValue(order, 'order_type', 'orderType'),
+      source,
+      'order_type',
+    ),
+    deliveryAddress: commerceOptionalString(
+      commerceValue(order, 'delivery_address', 'deliveryAddress'),
+      source,
+      'delivery_address',
+    ),
+    specialInstructions: commerceOptionalString(
+      commerceValue(order, 'special_instructions', 'specialInstructions'),
+      source,
+      'special_instructions',
+    ),
+    estimatedDeliveryTime: commerceOptionalTimestamp(
+      commerceValue(order, 'estimated_delivery_time', 'estimatedDeliveryTime'),
+      source,
+      'estimated_delivery_time',
+    ),
+    appliedCouponId: commerceOptionalString(
+      commerceValue(order, 'applied_coupon_id', 'appliedCouponId'),
+      source,
+      'applied_coupon_id',
+    ),
+    couponId,
+    itemCount: commerceNumber(itemCounts.get(id) ?? 0, source, 'item_count', {
+      min: 0,
+      integer: true,
+    }),
+    createdAt: commerceTimestamp(commerceValue(order, 'created_at', 'createdAt'), source),
+  }
+}
+
+export function normalizeOrderCustomerOption(customer: any): OrderCustomerOption {
+  const id = commerceIdentifier(commerceValue(customer, 'id', 'uuid'), 'Customer')
+  const source = `Customer ${id}`
+  return {
+    id,
+    label: commerceRequiredString(commerceValue(customer, 'name'), source, 'name'),
+  }
+}
+
+export function normalizeOrderCustomerContext(customer: any): { id: string, context: OrderCustomerContext } {
+  const id = commerceIdentifier(commerceValue(customer, 'id', 'uuid'), 'Customer')
+  const source = `Customer ${id}`
+  return {
+    id,
+    context: {
+      name: commerceRequiredString(commerceValue(customer, 'name'), source, 'name'),
+      email: commerceEmail(commerceValue(customer, 'email'), source),
+    },
+  }
+}
+
+export function normalizeOrderCouponId(coupon: any): string {
+  return commerceIdentifier(commerceValue(coupon, 'id', 'uuid'), 'Coupon')
+}
+
+export function addOrderItemQuantity(
+  item: any,
+  orderIds: Set<string>,
+  itemCounts: Map<string, number>,
+): void {
+  const id = commerceIdentifier(commerceValue(item, 'id'), 'OrderItem')
+  const source = `OrderItem ${id}`
+  const orderId = commerceIdentifier(
+    commerceValue(item, 'order_id', 'orderId'),
+    source,
+    'order_id',
+  )
+  if (!orderIds.has(orderId))
+    throw new TypeError(`${source}.order_id references missing Order ${orderId}.`)
+  const quantity = commerceNumber(commerceValue(item, 'quantity'), source, 'quantity', {
+    min: 1,
+    integer: true,
+  })
+  itemCounts.set(orderId, (itemCounts.get(orderId) ?? 0) + quantity)
+}
+
+export function summarizeCommerceOrders(records: CommerceOrderRecord[]): CommerceOrderSummary {
+  const currencyTotals = new Map<string, number>()
+  for (const record of records)
+    currencyTotals.set(record.currency, (currencyTotals.get(record.currency) || 0) + record.totalAmount)
+
+  const status = (record: CommerceOrderRecord): string => record.status.toUpperCase()
+  return {
+    total: records.length,
+    pending: records.filter(record => ['PENDING', 'NEW'].includes(status(record))).length,
+    inProgress: records.filter(record => ['PREPARING', 'PROCESSING', 'READY', 'SHIPPED'].includes(status(record))).length,
+    completed: records.filter(record => ['DELIVERED', 'COMPLETED', 'PAID'].includes(status(record))).length,
+    cancelled: records.filter(record => ['CANCELED', 'CANCELLED', 'REFUNDED'].includes(status(record))).length,
+    currencyTotals: [...currencyTotals.entries()]
+      .map(([currency, amount]) => ({ currency, amount }))
+      .sort((left, right) => left.currency.localeCompare(right.currency)),
+  }
+}