@stacksjs/defaults 0.70.296 → 0.70.298
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -61,10 +61,11 @@ Each sub-module typically provides:
|
|
|
61
61
|
- Shipping methods
|
|
62
62
|
- Shipping rates (weight-based)
|
|
63
63
|
- Shipping zones
|
|
64
|
-
- Delivery routes
|
|
64
|
+
- Delivery routes and their stops
|
|
65
65
|
- Drivers
|
|
66
66
|
- Digital deliveries
|
|
67
67
|
- License keys
|
|
68
|
+
- **Live tracking** (`commerce.shippings.tracking`) - see below
|
|
68
69
|
|
|
69
70
|
## Commerce Models (20+)
|
|
70
71
|
|
|
@@ -84,13 +85,82 @@ Each sub-module typically provides:
|
|
|
84
85
|
| Manufacturer | manufacturer info | hasMany: Product |
|
|
85
86
|
| Review | rating(1-5), content, isVerifiedPurchase, helpfulVotes | belongsTo: Product, Customer |
|
|
86
87
|
| ShippingRate | weightFrom, weightTo, rate | belongsTo: ShippingMethod, ShippingZone |
|
|
87
|
-
| DeliveryRoute | stops, totalDistance | belongsTo: Driver |
|
|
88
|
+
| DeliveryRoute | stops, totalDistance, status(planned/active/completed), startedAt | belongsTo: Driver; hasMany: DeliveryStop, DriverPing |
|
|
89
|
+
| DeliveryStop | sequence, status, address, latitude, longitude, etaAt, arrivedAt | belongsTo: DeliveryRoute, Order |
|
|
90
|
+
| Driver | name, phone, vehicleNumber, status, latitude, longitude, heading, lastPingAt | hasMany: DeliveryRoute, DriverPing |
|
|
91
|
+
| DriverPing | latitude, longitude, heading, speed, accuracy, recordedAt | belongsTo: Driver, DeliveryRoute |
|
|
88
92
|
| TaxRate | name, rate(0-100), type(VAT/GST/Sales Tax) | |
|
|
89
93
|
| LicenseKey | key(XXXX-XXXX-XXXX-XXXX-XXXX), template, status | belongsTo: Customer, Product, Order |
|
|
90
94
|
| DigitalDelivery | downloadLimit, expiryDays, automaticDelivery | |
|
|
91
95
|
| WaitlistProduct | product waitlist tracking | |
|
|
92
96
|
| Receipt | receipt records | |
|
|
93
97
|
|
|
98
|
+
## Live Delivery Tracking
|
|
99
|
+
|
|
100
|
+
`commerce.shippings.tracking` is the moving part of shipping: position ingest,
|
|
101
|
+
the stop lifecycle, and the fan-out that drives a customer's tracking map.
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
import { commerce } from '@stacksjs/commerce'
|
|
105
|
+
|
|
106
|
+
const { tracking } = commerce.shippings
|
|
107
|
+
|
|
108
|
+
// Put an order on a route, then set the vehicle moving.
|
|
109
|
+
const stop = await tracking.assignStop({
|
|
110
|
+
deliveryRouteId: route.id,
|
|
111
|
+
orderId: order.id,
|
|
112
|
+
address: '3821 Grand View Blvd, Los Angeles CA 90066',
|
|
113
|
+
latitude: 34.0128,
|
|
114
|
+
longitude: -118.4361,
|
|
115
|
+
})
|
|
116
|
+
await tracking.startRoute(route.id)
|
|
117
|
+
await tracking.startStop(stop.id) // order -> OUT_FOR_DELIVERY
|
|
118
|
+
|
|
119
|
+
// One call per position fix from the driver's device.
|
|
120
|
+
await tracking.recordDriverPing({
|
|
121
|
+
driverId, latitude, longitude, speed, accuracy,
|
|
122
|
+
})
|
|
123
|
+
|
|
124
|
+
await tracking.completeStop(stop.id) // order -> DELIVERED, route closes itself
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### What `recordDriverPing` does
|
|
128
|
+
|
|
129
|
+
One entry point, so a tracking page never shows a position its ETA disagrees
|
|
130
|
+
with. Per fix it: appends to `driver_pings`, updates the driver's denormalised
|
|
131
|
+
present position, recomputes the served stop's ETA, broadcasts the position,
|
|
132
|
+
and latches `delivery:nearby` / `delivery:arrived` so each fires exactly once.
|
|
133
|
+
|
|
134
|
+
A fix reporting worse than 250m accuracy is stored but does not move the driver
|
|
135
|
+
or trip a threshold.
|
|
136
|
+
|
|
137
|
+
### Two fan-outs, on purpose
|
|
138
|
+
|
|
139
|
+
| Path | Carries | Why |
|
|
140
|
+
|---|---|---|
|
|
141
|
+
| Realtime channel (`@stacksjs/realtime`) | `delivery:position`, plus every state change | Fires every few seconds per delivery; only browsers care |
|
|
142
|
+
| Event bus (`@stacksjs/events`) | `delivery:assigned`, `:started`, `:nearby`, `:arrived`, `:completed`, `:failed` | Where notifications, analytics and fulfilment subscribe |
|
|
143
|
+
|
|
144
|
+
Position never reaches the event bus. Subscribe to the state changes to send an
|
|
145
|
+
SMS without being woken several times a minute per active delivery.
|
|
146
|
+
|
|
147
|
+
Channels are `order.{id}` for a customer's page and `delivery-route.{id}` for a
|
|
148
|
+
dispatch map, both private: authorise them in your `setWsAuthenticator`.
|
|
149
|
+
|
|
150
|
+
### Order status
|
|
151
|
+
|
|
152
|
+
`OUT_FOR_DELIVERY` sits between `SHIPPED` and `DELIVERED`, reachable from
|
|
153
|
+
`PROCESSING` too (a local kitchen goes straight out on its own van), and falls
|
|
154
|
+
back to `SHIPPED` when a drop fails and the parcel returns to the depot.
|
|
155
|
+
`canTransition` enforces it.
|
|
156
|
+
|
|
157
|
+
### Geodesy
|
|
158
|
+
|
|
159
|
+
`distanceInMeters`, `bearingInDegrees`, `estimateSecondsRemaining`, `isWithin`
|
|
160
|
+
and `hasCoordinates` are exported for building dispatch views. The ETA pads
|
|
161
|
+
straight-line distance by a detour factor and returns `null` for a stationary
|
|
162
|
+
driver rather than `Infinity`.
|
|
163
|
+
|
|
94
164
|
## Integration with Payments
|
|
95
165
|
Commerce works with `@stacksjs/payments` for Stripe integration:
|
|
96
166
|
```typescript
|
package/ide/vscode/package.json
CHANGED
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "@stacksjs/defaults",
|
|
3
3
|
"type": "module",
|
|
4
4
|
"sideEffects": false,
|
|
5
|
-
"version": "0.70.
|
|
5
|
+
"version": "0.70.298",
|
|
6
6
|
"description": "The complete managed Stacks application scaffold, including runtime defaults, AI guidance, editor metadata, and npm-backed project support files.",
|
|
7
7
|
"author": "Chris Breuer",
|
|
8
8
|
"license": "MIT",
|