@stacksjs/defaults 0.72.103 → 0.73.0

package/app/Actions/Commerce/Shipping/CourierPingStoreAction.ts

@@ -0,0 +1,61 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { shippings } from '@stacksjs/commerce'
+import { response } from '@stacksjs/router'
+import { courierFromSession } from './courier-session'
+
+/**
+ * A position fix from a courier's device.
+ *
+ * The one write path into `courier_pings`: `recordCourierPing` also moves the
+ * courier's denormalised position, recomputes the stop's ETA, broadcasts to
+ * everyone watching the order, and latches the nearby and arrival thresholds so
+ * each fires once. Writing the row directly skips all of it.
+ */
+export default new Action({
+  name: 'Courier Ping Store',
+  description: 'Record a position fix from the authenticated courier\'s device.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const session = await courierFromSession(request)
+    if (session.error)
+      return session.error
+
+    const latitude = numeric(request.get('latitude'))
+    const longitude = numeric(request.get('longitude'))
+
+    if (latitude == null || latitude < -90 || latitude > 90)
+      return invalid('latitude must be a number between -90 and 90')
+
+    if (longitude == null || longitude < -180 || longitude > 180)
+      return invalid('longitude must be a number between -180 and 180')
+
+    const result = await shippings.tracking.recordCourierPing({
+      courierId: session.courierId,
+      latitude,
+      longitude,
+      heading: numeric(request.get('heading')),
+      speed: numeric(request.get('speed')),
+      accuracy: numeric(request.get('accuracy')),
+      // The device's own clock. A phone that buffered fixes through a tunnel
+      // sends them late, and stamping them with arrival time would draw the
+      // courier teleporting.
+      recordedAt: typeof request.get('recordedAt') === 'string' ? String(request.get('recordedAt')) : undefined,
+    })
+
+    return response.json(result)
+  },
+})
+
+function numeric(value: unknown): number | null {
+  if (value === null || value === undefined || value === '')
+    return null
+
+  const n = Number(value)
+  return Number.isFinite(n) ? n : null
+}
+
+function invalid(message: string): Response {
+  return response.json({ message }, 422)
+}

package/app/Actions/Commerce/Shipping/{DriverShowAction.ts → CourierShowAction.ts}

@@ -6,18 +6,18 @@ import { response } from '@stacksjs/router'
 import { commerceIdentifier, commerceNotFound } from '../commerce-action'
 
 export default new Action({
-  name: 'Driver Show',
-  description: 'Driver Show ORM Action',
+  name: 'Courier Show',
+  description: 'Courier Show ORM Action',
   method: 'GET',
   async handle(request: RequestInstance) {
-    const identifier = commerceIdentifier(request, 'Driver')
+    const identifier = commerceIdentifier(request, 'Courier')
     if (identifier.error)
       return identifier.error
     const { id } = identifier
 
-    const model = await shippings.drivers.fetchById(id)
+    const model = await shippings.couriers.fetchById(id)
     if (!model)
-      return commerceNotFound('Driver', id)
+      return commerceNotFound('Courier', id)
 
     return response.json(model)
   },

package/app/Actions/Commerce/Shipping/{DriverStoreAction.ts → CourierStoreAction.ts}

@@ -5,14 +5,14 @@ import { shippings } from '@stacksjs/commerce'
 import { response } from '@stacksjs/router'
 
 export default new Action({
-  name: 'Driver Store',
-  description: 'Driver Store ORM Action',
+  name: 'Courier Store',
+  description: 'Courier Store ORM Action',
   method: 'POST',
-  model: Driver,
+  model: Courier,
   async handle(request: RequestInstance) {
     await request.validate()
     const data = await request.all()
-    const model = await shippings.drivers.store(data)
+    const model = await shippings.couriers.store(data)
 
     return response.json(model)
   },

package/app/Actions/Commerce/Shipping/{DriverUpdateAction.ts → CourierUpdateAction.ts}

@@ -6,12 +6,12 @@ import { response } from '@stacksjs/router'
 import { commerceIdentifier, commerceNotFound } from '../commerce-action'
 
 export default new Action({
-  name: 'Driver Update',
-  description: 'Driver Update ORM Action',
+  name: 'Courier Update',
+  description: 'Courier Update ORM Action',
   method: 'PATCH',
-  model: Driver,
+  model: Courier,
   async handle(request: RequestInstance) {
-    const identifier = commerceIdentifier(request, 'Driver')
+    const identifier = commerceIdentifier(request, 'Courier')
     if (identifier.error)
       return identifier.error
     const { id } = identifier
@@ -19,9 +19,9 @@ export default new Action({
     await request.validate()
     const data = await request.all()
 
-    const model = await shippings.drivers.update(id, data)
+    const model = await shippings.couriers.update(id, data)
     if (!model)
-      return commerceNotFound('Driver', id)
+      return commerceNotFound('Courier', id)
 
     return response.json(model)
   },

package/app/Actions/Commerce/Shipping/DeliveryRouteStartAction.ts

@@ -0,0 +1,38 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { shippings } from '@stacksjs/commerce'
+import { response } from '@stacksjs/router'
+import { commerceIdentifier } from '../commerce-action'
+import { assertRouteBelongsToCourier, courierFromSession } from './courier-session'
+
+/**
+ * Begin a run.
+ *
+ * Until a route is active, pings from its courier find no active route, so
+ * positions are stored but no ETA is recomputed and no arrival ever fires. A
+ * courier app that forgets this call looks like a courier who never moves.
+ */
+export default new Action({
+  name: 'Delivery Route Start',
+  description: 'Start a delivery route for the authenticated courier.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const session = await courierFromSession(request)
+    if (session.error)
+      return session.error
+
+    const identifier = commerceIdentifier(request, 'DeliveryRoute')
+    if (identifier.error)
+      return identifier.error
+    const { id } = identifier
+
+    const denied = await assertRouteBelongsToCourier(id, session.courierId)
+    if (denied)
+      return denied
+
+    await shippings.tracking.startRoute(id)
+
+    return response.json({ id, status: 'active' })
+  },
+})

package/app/Actions/Commerce/Shipping/DeliveryStopCompleteAction.ts

@@ -0,0 +1,40 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { shippings } from '@stacksjs/commerce'
+import { response } from '@stacksjs/router'
+import { commerceIdentifier, commerceNotFound } from '../commerce-action'
+import { assertStopBelongsToCourier, courierFromSession } from './courier-session'
+
+/**
+ * The handover is done.
+ *
+ * Completing a dropoff marks the order delivered; completing a pickup means the
+ * order is on the vehicle and moves it out for delivery instead.
+ */
+export default new Action({
+  name: 'Delivery Stop Complete',
+  description: 'Complete a stop for the authenticated courier.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const session = await courierFromSession(request)
+    if (session.error)
+      return session.error
+
+    const identifier = commerceIdentifier(request, 'DeliveryStop')
+    if (identifier.error)
+      return identifier.error
+    const { id } = identifier
+
+    const denied = await assertStopBelongsToCourier(id, session.courierId)
+    if (denied)
+      return denied
+
+    const notes = request.get<string>('notes')
+    const stop = await shippings.tracking.completeStop(id, typeof notes === 'string' && notes ? notes : undefined)
+    if (!stop)
+      return commerceNotFound('DeliveryStop', id)
+
+    return response.json(stop)
+  },
+})

package/app/Actions/Commerce/Shipping/DeliveryStopFailAction.ts

@@ -0,0 +1,44 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { shippings } from '@stacksjs/commerce'
+import { response } from '@stacksjs/router'
+import { commerceIdentifier, commerceNotFound } from '../commerce-action'
+import { assertStopBelongsToCourier, courierFromSession } from './courier-session'
+
+/**
+ * The stop could not be completed.
+ *
+ * A reason is required rather than optional: this is the record a customer
+ * service agent reads back when the customer asks why nobody came, and "failed"
+ * on its own does not answer that.
+ */
+export default new Action({
+  name: 'Delivery Stop Fail',
+  description: 'Mark a stop as failed for the authenticated courier.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const session = await courierFromSession(request)
+    if (session.error)
+      return session.error
+
+    const identifier = commerceIdentifier(request, 'DeliveryStop')
+    if (identifier.error)
+      return identifier.error
+    const { id } = identifier
+
+    const reason = request.get<string>('reason')
+    if (typeof reason !== 'string' || reason.trim() === '')
+      return response.json({ message: 'reason is required' }, 422)
+
+    const denied = await assertStopBelongsToCourier(id, session.courierId)
+    if (denied)
+      return denied
+
+    const stop = await shippings.tracking.failStop(id, reason.trim())
+    if (!stop)
+      return commerceNotFound('DeliveryStop', id)
+
+    return response.json(stop)
+  },
+})

package/app/Actions/Commerce/Shipping/DeliveryStopStartAction.ts

@@ -0,0 +1,39 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { shippings } from '@stacksjs/commerce'
+import { response } from '@stacksjs/router'
+import { commerceIdentifier, commerceNotFound } from '../commerce-action'
+import { assertStopBelongsToCourier, courierFromSession } from './courier-session'
+
+/**
+ * The courier is driving to this stop.
+ *
+ * On a dropoff this is what puts the order out for delivery and starts the
+ * customer's tracking page; on a pickup it only moves the stop.
+ */
+export default new Action({
+  name: 'Delivery Stop Start',
+  description: 'Mark a stop as en route for the authenticated courier.',
+  method: 'POST',
+
+  async handle(request: RequestInstance) {
+    const session = await courierFromSession(request)
+    if (session.error)
+      return session.error
+
+    const identifier = commerceIdentifier(request, 'DeliveryStop')
+    if (identifier.error)
+      return identifier.error
+    const { id } = identifier
+
+    const denied = await assertStopBelongsToCourier(id, session.courierId)
+    if (denied)
+      return denied
+
+    const stop = await shippings.tracking.startStop(id)
+    if (!stop)
+      return commerceNotFound('DeliveryStop', id)
+
+    return response.json(stop)
+  },
+})

package/app/Actions/Commerce/Shipping/courier-session.ts

@@ -0,0 +1,75 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { db } from '@stacksjs/database'
+import { response } from '@stacksjs/router'
+
+export type CourierSessionResult =
+  | { courierId: number, error?: never }
+  | { courierId?: never, error: Response }
+
+/**
+ * The courier making this request.
+ *
+ * Resolved from the session, never from the body. A courier id accepted as
+ * input would let any authenticated account post positions as somebody else -
+ * moving another courier's marker on a customer's live map, and tripping their
+ * arrival notifications.
+ */
+export async function courierFromSession(request: RequestInstance): Promise<CourierSessionResult> {
+  const user = await request.user()
+  if (!user)
+    return { error: response.unauthorized('Authentication required') }
+
+  const courier = await db
+    .selectFrom('couriers')
+    .where('user_id', '=', user.id)
+    .select(['id'])
+    .executeTakeFirst() as { id: number } | undefined
+
+  if (!courier)
+    return { error: response.forbidden('This account is not a courier') }
+
+  return { courierId: Number(courier.id) }
+}
+
+/**
+ * Check that a stop belongs to the run this courier is on.
+ *
+ * Stops are addressed by id, so without this any courier could complete or
+ * fail another courier's delivery - which marks somebody else's order as
+ * handed over.
+ */
+export async function assertStopBelongsToCourier(stopId: number, courierId: number): Promise<Response | null> {
+  const row = await db
+    .selectFrom('delivery_stops')
+    .innerJoin('delivery_routes', 'delivery_routes.id', 'delivery_stops.delivery_route_id')
+    .where('delivery_stops.id', '=', stopId)
+    .select(['delivery_routes.courier_id as courier_id'])
+    .executeTakeFirst() as { courier_id: number | null } | undefined
+
+  if (!row)
+    return response.json({ message: `DeliveryStop ${stopId} was not found.` }, 404)
+
+  if (row.courier_id == null || Number(row.courier_id) !== courierId)
+    return response.forbidden('This stop belongs to another courier')
+
+  return null
+}
+
+/**
+ * Check that a route is this courier's own.
+ */
+export async function assertRouteBelongsToCourier(routeId: number, courierId: number): Promise<Response | null> {
+  const row = await db
+    .selectFrom('delivery_routes')
+    .where('id', '=', routeId)
+    .select(['courier_id'])
+    .executeTakeFirst() as { courier_id: number | null } | undefined
+
+  if (!row)
+    return response.json({ message: `DeliveryRoute ${routeId} was not found.` }, 404)
+
+  if (row.courier_id == null || Number(row.courier_id) !== courierId)
+    return response.forbidden('This route belongs to another courier')
+
+  return null
+}

package/app/Actions/Commerce/commerce-action.test.ts

@@ -10,22 +10,22 @@ function request(id: string): RequestInstance {
 
 describe('commerce action responses', () => {
   test('accepts safe positive route identifiers', () => {
-    expect(commerceIdentifier(request('42'), 'Driver')).toEqual({ id: 42 })
+    expect(commerceIdentifier(request('42'), 'Courier')).toEqual({ id: 42 })
   })
 
   test('returns 422 for invalid identifiers', async () => {
-    const result = commerceIdentifier(request('not-an-id'), 'Driver')
+    const result = commerceIdentifier(request('not-an-id'), 'Courier')
     expect(result.error?.status).toBe(422)
     expect(await result.error?.json()).toEqual({
-      message: 'Driver id must be a positive integer.',
+      message: 'Courier id must be a positive integer.',
     })
   })
 
   test('returns a consistent not-found response', async () => {
-    const result = commerceNotFound('Driver', 42)
+    const result = commerceNotFound('Courier', 42)
     expect(result.status).toBe(404)
     expect(await result.json()).toEqual({
-      message: 'Driver 42 was not found.',
+      message: 'Courier 42 was not found.',
     })
   })
 })

package/app/Actions/Dashboard/Commerce/CommerceDeliveryAction.ts

@@ -1,29 +1,29 @@
 import { Action } from '@stacksjs/actions'
 import { config } from '@stacksjs/config'
-import { DeliveryRoute, Driver, ShippingMethod, ShippingZone } from '@stacksjs/orm'
+import { DeliveryRoute, Courier, ShippingMethod, ShippingZone } from '@stacksjs/orm'
 import { dashboardOperationalError } from '../dashboard-response'
 import { buildDeliveryOverview } from './commerce-delivery'
 
 export default new Action({
   name: 'CommerceDelivery',
-  description: 'Returns the dashboard delivery overview from routes, drivers, shipping methods, and zones.',
+  description: 'Returns the dashboard delivery overview from routes, couriers, shipping methods, and zones.',
   method: 'GET',
   apiResponse: true,
 
   async handle() {
     try {
-      const [allMethods, allRoutes, allZones, allDrivers] = await Promise.all([
+      const [allMethods, allRoutes, allZones, allCouriers] = await Promise.all([
         ShippingMethod.orderBy('id', 'asc').limit(500).get(),
         DeliveryRoute.orderBy('id', 'asc').limit(500).get(),
         ShippingZone.orderBy('id', 'asc').limit(500).get(),
-        Driver.orderBy('id', 'asc').limit(500).get(),
+        Courier.orderBy('id', 'asc').limit(500).get(),
       ])
 
       return buildDeliveryOverview(
         allMethods,
         allRoutes,
         allZones,
-        allDrivers,
+        allCouriers,
         config.commerce?.currency,
       )
     }

package/app/Actions/Dashboard/Commerce/CourierIndexAction.ts

@@ -0,0 +1,24 @@
+import { Action } from '@stacksjs/actions'
+import { Courier, User } from '@stacksjs/orm'
+import { dashboardOperationalError } from '../dashboard-response'
+import { indexCourierUsers, normalizeCourierRecord } from './courier-records'
+
+export default new Action({
+  name: 'Dashboard Couriers',
+  description: 'Returns validated couriers and their optional User relationships.',
+  method: 'GET',
+  apiResponse: true,
+
+  async handle() {
+    try {
+      const couriers = await Courier.orderBy('name', 'asc').limit(500).get()
+      const userIds = [...new Set(couriers.map(courier => courier.get('user_id')).filter(Boolean))]
+      const users = userIds.length ? await User.whereIn('id', userIds).get() : []
+      const usersById = indexCourierUsers(users)
+      return couriers.map(courier => normalizeCourierRecord(courier, usersById))
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Courier records could not be read.', 'CourierIndexAction')
+    }
+  },
+})

package/app/Actions/Dashboard/Commerce/DeliveryRouteIndexAction.ts

@@ -1,24 +1,24 @@
 import { Action } from '@stacksjs/actions'
-import { DeliveryRoute, Driver } from '@stacksjs/orm'
+import { DeliveryRoute, Courier } from '@stacksjs/orm'
 import { dashboardOperationalError } from '../dashboard-response'
 import {
-  indexDeliveryRouteDrivers,
+  indexDeliveryRouteCouriers,
   normalizeDeliveryRouteRecord,
 } from './delivery-route-records'
 
 export default new Action({
   name: 'Dashboard Delivery Routes',
-  description: 'Returns validated delivery routes and their optional Driver relationships.',
+  description: 'Returns validated delivery routes and their optional Courier relationships.',
   method: 'GET',
   apiResponse: true,
 
   async handle() {
     try {
       const routes = await DeliveryRoute.orderByDesc('last_active').limit(500).get()
-      const driverIds = [...new Set(routes.map(route => route.get('driver_id')).filter(Boolean))]
-      const drivers = driverIds.length ? await Driver.whereIn('id', driverIds).get() : []
-      const driversById = indexDeliveryRouteDrivers(drivers)
-      return routes.map(route => normalizeDeliveryRouteRecord(route, driversById))
+      const courierIds = [...new Set(routes.map(route => route.get('courier_id')).filter(Boolean))]
+      const couriers = courierIds.length ? await Courier.whereIn('id', courierIds).get() : []
+      const couriersById = indexDeliveryRouteCouriers(couriers)
+      return routes.map(route => normalizeDeliveryRouteRecord(route, couriersById))
     }
     catch (error) {
       return dashboardOperationalError(error, 'Delivery route records could not be read.', 'DeliveryRouteIndexAction')

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

@@ -26,8 +26,8 @@ describe('commerce delivery overview', () => {
       [
         {
           id: 1,
-          driver_id: 7,
-          driver: 'Old Driver Name',
+          courier_id: 7,
+          courier: 'Old Courier Name',
           vehicle: 'Old Vehicle',
           stops: 4,
           delivery_time: 90,
@@ -36,7 +36,7 @@ describe('commerce delivery overview', () => {
         },
         {
           id: 2,
-          driver: 'Stale Driver',
+          courier: 'Stale Courier',
           vehicle: 'Van S1',
           stops: 8,
           delivery_time: 180,
@@ -49,8 +49,8 @@ describe('commerce delivery overview', () => {
         { id: 2, name: 'Active Zone', status: 'active', countries: '["US","CA"]', regions: '["West"]' },
       ],
       [
-        { id: 7, name: 'Current Driver', vehicle_number: 'VAN-7', status: 'on_delivery' },
-        { id: 8, name: 'Available Driver', vehicle_number: 'VAN-8', status: 'active' },
+        { id: 7, name: 'Current Courier', vehicle_number: 'VAN-7', status: 'on_delivery' },
+        { id: 8, name: 'Available Courier', vehicle_number: 'VAN-8', status: 'active' },
       ],
       'EUR',
       now,
@@ -60,7 +60,7 @@ describe('commerce delivery overview', () => {
     expect(result.routes).toEqual([
       {
         id: 1,
-        driver: 'Current Driver',
+        courier: 'Current Courier',
         vehicle: 'VAN-7',
         stops: 4,
         duration: '1h 30m',
@@ -76,7 +76,7 @@ describe('commerce delivery overview', () => {
     })
     expect(result.methods[1]?.freeShipping).toBe('Not enabled')
     expect(result.zones[0]).toMatchObject({ name: 'Active Zone', countries: 2, regions: 1 })
-    expect(result.drivers).toEqual({
+    expect(result.couriers).toEqual({
       total: 2,
       active: 1,
       onDelivery: 1,
@@ -84,7 +84,7 @@ describe('commerce delivery overview', () => {
     })
   })
 
-  test('rejects corrupt delivery records and missing driver relationships', () => {
+  test('rejects corrupt delivery records and missing courier relationships', () => {
     expect(() => buildDeliveryOverview(
       [{ id: 1, name: 'Ground', status: 'active', base_rate: 'free', free_shipping: null }],
       [],
@@ -98,8 +98,8 @@ describe('commerce delivery overview', () => {
       [],
       [{
         id: 1,
-        driver_id: 99,
-        driver: 'Recorded driver',
+        courier_id: 99,
+        courier: 'Recorded courier',
         vehicle: 'Recorded vehicle',
         stops: 1,
         delivery_time: 30,
@@ -110,6 +110,6 @@ describe('commerce delivery overview', () => {
       [],
       'USD',
       now,
-    )).toThrow('DeliveryRoute 1.driver_id references missing Driver 99')
+    )).toThrow('DeliveryRoute 1.courier_id references missing Courier 99')
   })
 })