@jsm-mit/tigi-sharded-package 0.10.0 → 0.11.0

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.
package/README.md CHANGED
@@ -44,6 +44,11 @@ const again = await request.searchAgainAsyncUnsafe(); // a new request, th
44
44
  const ride = await request.getRideAsyncUnsafe(); // from the driver canister, every RIDE_POLL_MS (2 s)
45
45
  await request.getRideRouteAsyncUnsafe(); // K-13: the ride's line while it is active (once; undefined after the end)
46
46
  await request.cancelRideAsyncUnsafe(); // before inProgress, once
47
+ // ZT-*: a ride at a chosen time (1 h … 7 days ahead; drivers asked by their base, 3 → 25 km by the workers themselves):
48
+ const later = await rides.requestScheduledAsyncUnsafe({ pickup, destination, pickupAtMs }); // keep later.token; rides.resumeScheduled(token)
49
+ const s = await later.getAsyncUnsafe(); // phase collecting | booking | booked | started | rescue | closed; offers cheapest first
50
+ await later.chooseAsyncUnsafe(s.offers[0].offerId); // a booking; read again for booked / lastOrderRefused
51
+ // started → rides.resumeRequest(s.rideToken) is the ride; rescue → requestRideAsyncUnsafe with the same A, B from T−10 min (RESCUE_BEFORE_MS)
47
52
  // P-20: card straight to the driver (Stripe) — when ride.cardAccepted, during inProgress:
48
53
  const card = await request.startCardPaymentAsyncUnsafe(returnUrl); // open → go to card.url; the same page again while it stands
49
54
  await request.checkCardPaymentAsyncUnsafe(); // back from Stripe (card=paid|cancelled in the URL); ride.cardPayment shows it too
@@ -65,6 +65,7 @@ type QuoteRequest = record {
65
65
  riderName : text;
66
66
  riderRating : opt nat16; // ×100, e.g. 487 = 4.87; none for a new rider
67
67
  deadlineNs : nat64; // 20 s for the driver's OK (U-42)
68
+ pickupAtNs : opt nat64; // P-21: a ride at this time (asked by the base); absent = as soon as possible
68
69
  };
69
70
 
70
71
  type RideOrder = record {
@@ -77,8 +78,12 @@ type RideOrder = record {
77
78
  destination : Geo;
78
79
  price : Money; // the price of the accepted offer
79
80
  answerByNs : nat64; // safety window: our driver canister accepts at once (U-42)
81
+ pickupAtNs : opt nat64; // P-22: a booking for this time — no ride until the driver's "Jadę"
80
82
  };
81
83
 
84
+ // P-22: a booking of a ride at a chosen time (the driver's "Jadę" / giving it up).
85
+ type BookingRef = record { requestId : RequestId; driverKey : DriverKey };
86
+
82
87
  type CloseReason = variant {
83
88
  offerRejected; // the rider tapped ✕ on this driver's offer (U-39)
84
89
  otherOfferChosen;
@@ -94,6 +99,15 @@ type RequestClosed = record {
94
99
 
95
100
  // ---------------------------------------------------------------- driver → worker
96
101
 
102
+ // P-21: where the driver parks the car after work — for rides at a chosen time. Kept whether
103
+ // the driver works or not; renewed daily, gone after 7 days without a renewal.
104
+ type RegisterBase = record {
105
+ driverKey : DriverKey;
106
+ geohash : Geohash; // geohash6 of the base (~1.2 × 0.6 km), never the exact point
107
+ card : DriverCard;
108
+ cardVersion : nat32;
109
+ };
110
+
97
111
  type RegisterDriver = record {
98
112
  driverKey : DriverKey;
99
113
  geohash : Geohash; // geohash7 of the driver: area by its geohash6 prefix,
@@ -232,6 +246,10 @@ service : {
232
246
  //
233
247
  // service WorkerForDrivers : {
234
248
  // registerDriver : (RegisterDriver) -> (variant { ok; err : ProtocolError });
249
+ // registerBase : (RegisterBase) -> (variant { ok; err : ProtocolError }); // P-21
250
+ // unregisterBase : (DriverKey) -> (); // P-21
251
+ // bookingStarted : (BookingRef) -> (variant { ok; err : ProtocolError }); // P-22
252
+ // bookingDropped : (BookingRef) -> (); // P-22
235
253
  // unregisterDriver : (DriverKey) -> ();
236
254
  // submitQuote : (Quote) -> (variant { ok; err : ProtocolError });
237
255
  // declineQuote : (QuoteDecline) -> ();
@@ -2,6 +2,10 @@ import type { Principal } from '@icp-sdk/core/principal';
2
2
  import type { ActorMethod } from '@icp-sdk/core/agent';
3
3
  import type { IDL } from '@icp-sdk/core/candid';
4
4
 
5
+ /**
6
+ * P-22: a booking of a ride at a chosen time (the driver's "Jadę" / giving it up).
7
+ */
8
+ export interface BookingRef { 'requestId' : RequestId, 'driverKey' : DriverKey }
5
9
  export interface CardPaymentArgs {
6
10
  'returnUrl' : string,
7
11
  'requestId' : RequestId,
@@ -85,9 +89,20 @@ export interface QuoteRequest {
85
89
  'deadlineNs' : bigint,
86
90
  'pickup' : Geo,
87
91
  'driverKey' : DriverKey,
92
+ 'pickupAtNs' : [] | [bigint],
88
93
  'riderRating' : [] | [number],
89
94
  'riderName' : string,
90
95
  }
96
+ /**
97
+ * P-21: where the driver parks the car after work — for rides at a chosen time. Kept whether
98
+ * the driver works or not; renewed daily, gone after 7 days without a renewal.
99
+ */
100
+ export interface RegisterBase {
101
+ 'card' : DriverCard,
102
+ 'cardVersion' : number,
103
+ 'geohash' : Geohash,
104
+ 'driverKey' : DriverKey,
105
+ }
91
106
  export interface RegisterDriver {
92
107
  'card' : DriverCard,
93
108
  'cardVersion' : number,
@@ -110,6 +125,7 @@ export interface RideOrder {
110
125
  'requestId' : RequestId,
111
126
  'pickup' : Geo,
112
127
  'driverKey' : DriverKey,
128
+ 'pickupAtNs' : [] | [bigint],
113
129
  'riderRating' : [] | [number],
114
130
  'answerByNs' : bigint,
115
131
  'price' : Money,
@@ -75,6 +75,7 @@ export const idlFactory = ({ IDL }) => {
75
75
  'deadlineNs' : IDL.Nat64,
76
76
  'pickup' : Geo,
77
77
  'driverKey' : DriverKey,
78
+ 'pickupAtNs' : IDL.Opt(IDL.Nat64),
78
79
  'riderRating' : IDL.Opt(IDL.Nat16),
79
80
  'riderName' : IDL.Text,
80
81
  });
@@ -94,6 +95,7 @@ export const idlFactory = ({ IDL }) => {
94
95
  'requestId' : RequestId,
95
96
  'pickup' : Geo,
96
97
  'driverKey' : DriverKey,
98
+ 'pickupAtNs' : IDL.Opt(IDL.Nat64),
97
99
  'riderRating' : IDL.Opt(IDL.Nat16),
98
100
  'answerByNs' : IDL.Nat64,
99
101
  'price' : Money,
@@ -224,6 +224,9 @@ type QuoteRequest = record {
224
224
  deadlineNs : nat64;
225
225
  pickup : Geo;
226
226
  driverKey : text;
227
+ // P-21: a ride at this time — asked by the driver's base, answered until `deadlineNs`
228
+ // (T−30 min). Absent = as soon as possible.
229
+ pickupAtNs : opt nat64;
227
230
  // ×100, e.g. 487 = 4.87; none for a new rider.
228
231
  riderRating : opt nat16;
229
232
  riderName : text;
@@ -244,6 +247,9 @@ type RideOrder = record {
244
247
  requestId : text;
245
248
  pickup : Geo;
246
249
  driverKey : text;
250
+ // P-22: a booking for this time — accepted as usual, but no ride until the driver's
251
+ // "Jadę" (`bookingStarted`).
252
+ pickupAtNs : opt nat64;
247
253
  riderRating : opt nat16;
248
254
  // 20 s for the driver to accept (U-39).
249
255
  answerByNs : nat64;
@@ -327,6 +327,11 @@ export interface QuoteRequest {
327
327
  'deadlineNs' : bigint,
328
328
  'pickup' : Geo,
329
329
  'driverKey' : string,
330
+ /**
331
+ * P-21: a ride at this time — asked by the driver's base, answered until `deadlineNs`
332
+ * (T−30 min). Absent = as soon as possible.
333
+ */
334
+ 'pickupAtNs' : [] | [bigint],
330
335
  /**
331
336
  * ×100, e.g. 487 = 4.87; none for a new rider.
332
337
  */
@@ -356,6 +361,11 @@ export interface RideOrder {
356
361
  'requestId' : string,
357
362
  'pickup' : Geo,
358
363
  'driverKey' : string,
364
+ /**
365
+ * P-22: a booking for this time — accepted as usual, but no ride until the driver's
366
+ * "Jadę" (`bookingStarted`).
367
+ */
368
+ 'pickupAtNs' : [] | [bigint],
359
369
  'riderRating' : [] | [number],
360
370
  /**
361
371
  * 20 s for the driver to accept (U-39).
@@ -148,6 +148,7 @@ export const idlFactory = ({ IDL }) => {
148
148
  'deadlineNs' : IDL.Nat64,
149
149
  'pickup' : Geo,
150
150
  'driverKey' : IDL.Text,
151
+ 'pickupAtNs' : IDL.Opt(IDL.Nat64),
151
152
  'riderRating' : IDL.Opt(IDL.Nat16),
152
153
  'riderName' : IDL.Text,
153
154
  });
@@ -167,6 +168,7 @@ export const idlFactory = ({ IDL }) => {
167
168
  'requestId' : IDL.Text,
168
169
  'pickup' : Geo,
169
170
  'driverKey' : IDL.Text,
171
+ 'pickupAtNs' : IDL.Opt(IDL.Nat64),
170
172
  'riderRating' : IDL.Opt(IDL.Nat16),
171
173
  'answerByNs' : IDL.Nat64,
172
174
  'price' : Money,
@@ -27,56 +27,75 @@ type TigiWorker =
27
27
  /// driver wasms. Answers the seq this worker holds after the call; the core sends again
28
28
  /// from there. Blocks act at once (WO-2); ratings go into offers and orders (P-12).
29
29
  applyCoreChanges: (batch: CoreChanges) -> (Result);
30
+ /// ZT-18 (P-22): the booked driver gives the booking up.
31
+ bookingDropped: (ref: BookingRef) -> ();
32
+ /// ZT-17 (P-22): the booked driver's "Jadę" — the ride starts here as an accepted request.
33
+ bookingStarted: (ref: BookingRef) -> (ProtocolResult);
34
+ /// ZT-13: the rider gives the ride at a chosen time up.
35
+ cancelScheduled: (ref: RequestRef) -> (Result_3);
30
36
  /// ZO-13, ZO-14, ZO-17.
31
- chooseOffer: (ref: OfferRef) -> (Result_9);
37
+ chooseOffer: (ref: OfferRef) -> (Result_10);
38
+ /// ZT-14: "Wybierz" on an offer for a ride at a chosen time — a booking order.
39
+ chooseScheduledOffer: (ref: OfferRef) -> (Result_10);
32
40
  clearLogs: () -> ();
33
41
  /// ZO-15 (otherOfferChosen after an acceptance in another worker), ZO-18 (riderGaveUp).
34
- closeRequest: (args: CloseRequestArgs) -> (Result_2);
42
+ closeRequest: (args: CloseRequestArgs) -> (Result_3);
43
+ /// ZT-21: the copies in the other workers close once one booked.
44
+ closeScheduled: (args: CloseRequestArgs) -> (Result_3);
35
45
  /// The coordinator only: the settings it computes for every worker.
36
- configure: (args: ConfigureArgs) -> (Result_8);
46
+ configure: (args: ConfigureArgs) -> (Result_9);
37
47
  /// ZO-6.
38
48
  declineQuote: (decline: QuoteDecline) -> ();
39
49
  /// What this worker holds of the core's network state.
40
50
  getCoreCopyStatus: () -> (CoreCopyStatus) query;
41
51
  /// The flow's numbers (scripts, the coordinator's front).
42
- getFlowStatus: () -> (Result_7) query;
52
+ getFlowStatus: () -> (Result_8) query;
43
53
  getLogs: () -> (text) query;
44
54
  /// ZO-21 (2026-10-24, route line): the route line of one offer, for the rider of the
45
55
  /// request only (the package asks after a tap on the offer).
46
- getOfferRoute: (ref: OfferRef) -> (Result_6) query;
56
+ getOfferRoute: (ref: OfferRef) -> (Result_7) query;
47
57
  /// The load this worker counts per geohash prefix of the given length (1–6): the
48
58
  /// coordinator picks from it what to give another worker on a split (KO-5).
49
- getPrefixCounts: (length: nat) -> (Result_5) query;
59
+ getPrefixCounts: (length: nat) -> (Result_6) query;
50
60
  /// ZO-11: the state and the offers (the package polls it every second).
51
- getRequest: (ref: RequestRef) -> (Result_1) query;
61
+ getRequest: (ref: RequestRef) -> (Result_2) query;
62
+ /// ZT-12: the state and the offers of a ride at a chosen time.
63
+ getScheduled: (ref: RequestRef) -> (Result_1) query;
52
64
  /// The worker's own view of itself — for the coordinator and its front.
53
- getStatus: () -> (Result_4) query;
65
+ getStatus: () -> (Result_5) query;
54
66
  /// The coordinator only, before it deletes the worker: what a deleted canister still
55
67
  /// holds is burned.
56
- giveBackCycles: () -> (Result_3);
68
+ giveBackCycles: () -> (Result_4);
57
69
  /// ZO-18: the rider gives up.
58
- giveUp: (ref: RequestRef) -> (Result_2);
70
+ giveUp: (ref: RequestRef) -> (Result_3);
59
71
  /// WO-20 (stage and the test modes): simulated drivers within 3 km of the point?
60
- hasSimulatedDrivers: (args: HasSimulatedDriversArgs) -> (Result_2) query;
72
+ hasSimulatedDrivers: (args: HasSimulatedDriversArgs) -> (Result_3) query;
61
73
  /// The coordinator only, in a test mode only (prod and stage refuse, and so does the
62
74
  /// coordinator): a load put on this worker. The cells' counters grow, and the worker
63
75
  /// reports `reportLevel` as a real minute would — what a local script uses to force a
64
76
  /// split.
65
- injectTestLoad: (args: TestLoadArgs) -> (Result_2);
77
+ injectTestLoad: (args: TestLoadArgs) -> (Result_3);
66
78
  /// WO-3: the geohash lies in this worker's area (by the coordinator's newest map).
67
79
  isMyArea: (geohash: text) -> (bool) query;
68
80
  /// K-8: the rider rates the driver.
69
- rateDriver: (args: RateDriverArgs) -> (Result_2);
81
+ rateDriver: (args: RateDriverArgs) -> (Result_3);
70
82
  /// K-8.
71
83
  rateRider: (rating: RiderRating) -> (ProtocolResult);
72
84
  /// ZO-10: a stale offer asks its driver again.
73
- refreshOffer: (ref: OfferRef) -> (Result_2);
85
+ refreshOffer: (ref: OfferRef) -> (Result_3);
86
+ /// ZT-1 … ZT-3 (P-21): a driver's base — on a change and once a day, whether the driver
87
+ /// works or not.
88
+ registerBase: (args: RegisterBase) -> (ProtocolResult);
74
89
  /// WO-1 … WO-8: a driver reports itself — on a cell change and every 60 s (U-27).
75
90
  registerDriver: (args: RegisterDriver) -> (ProtocolResult);
76
91
  /// ZO-12: ✕.
77
- rejectOffer: (ref: OfferRef) -> (Result_2);
92
+ rejectOffer: (ref: OfferRef) -> (Result_3);
93
+ /// ZT-9: ✕ on one offer.
94
+ rejectScheduledOffer: (ref: OfferRef) -> (Result_3);
78
95
  /// ZO-1 … ZO-4, ZO-8: a request in this worker; the drivers are asked after the answer.
79
- requestRide: (args: RequestRideArgs) -> (Result_1);
96
+ requestRide: (args: RequestRideArgs) -> (Result_2);
97
+ /// ZT-4: a ride at a chosen time in this worker (kurs-na-termin.md).
98
+ requestScheduled: (args: ScheduledRideArgs) -> (Result_1);
80
99
  /// K-2, K-6, K-7.
81
100
  rideStatusChanged: (change: RideStatusChange) -> (ProtocolResult);
82
101
  /// The coordinator only (KO-6): the whole prefix map. The newest version wins; answers
@@ -84,6 +103,8 @@ type TigiWorker =
84
103
  setAreaMap: (map: AreaMap) -> (Result);
85
104
  /// ZO-9, ZO-10.
86
105
  submitQuote: (quote: Quote) -> (ProtocolResult);
106
+ /// ZT-2 (P-21).
107
+ unregisterBase: (driverKey: DriverKey) -> ();
87
108
  /// WO-6.
88
109
  unregisterDriver: (driverKey: DriverKey) -> ();
89
110
  };
@@ -92,6 +113,54 @@ type TestLoadArgs =
92
113
  cells: vec PrefixCount;
93
114
  reportLevel: opt nat;
94
115
  };
116
+ type ScheduledView =
117
+ record {
118
+ asOfNs: nat64;
119
+ asked: nat32;
120
+ closesNs: nat64;
121
+ createdNs: nat64;
122
+ lastOrderRefused: bool;
123
+ nextStageNs: opt nat64;
124
+ offers: vec OfferView;
125
+ pickupAtNs: nat64;
126
+ radiusMeters: nat32;
127
+ requestId: RequestId;
128
+ state: ScheduledStateView;
129
+ waiting: nat32;
130
+ };
131
+ type ScheduledStateView =
132
+ variant {
133
+ booked:
134
+ record {
135
+ card: DriverCard;
136
+ driverCanister: principal;
137
+ driverKey: DriverKey;
138
+ driverRating: opt nat16;
139
+ price: Money;
140
+ };
141
+ booking:
142
+ record {
143
+ answerByNs: nat64;
144
+ driverCanister: principal;
145
+ driverKey: DriverKey;
146
+ };
147
+ closed: record {reason: CloseReason;};
148
+ collecting;
149
+ rescue: record {reason: RescueReason;};
150
+ started: record {
151
+ driverCanister: principal;
152
+ driverKey: DriverKey;
153
+ };
154
+ };
155
+ type ScheduledRideArgs =
156
+ record {
157
+ destination: Geo;
158
+ maxRadiusMeters: nat32;
159
+ pickup: Geo;
160
+ pickupAtNs: nat64;
161
+ requestId: RequestId;
162
+ riderName: text;
163
+ };
95
164
  type RouteLine =
96
165
  record {
97
166
  ride: text;
@@ -122,53 +191,63 @@ type RideStatus =
122
191
  type Result_9 =
123
192
  variant {
124
193
  err: Error;
125
- ok: ChooseOutcome;
194
+ ok: WorkerConfig;
126
195
  };
127
196
  type Result_8 =
128
197
  variant {
129
198
  err: Error;
130
- ok: WorkerConfig;
199
+ ok: FlowStatus;
131
200
  };
132
201
  type Result_7 =
133
202
  variant {
134
203
  err: Error;
135
- ok: FlowStatus;
204
+ ok: RouteLine;
136
205
  };
137
206
  type Result_6 =
138
207
  variant {
139
208
  err: Error;
140
- ok: RouteLine;
209
+ ok: vec PrefixCount;
141
210
  };
142
211
  type Result_5 =
143
212
  variant {
144
213
  err: Error;
145
- ok: vec PrefixCount;
214
+ ok: WorkerStatus;
146
215
  };
147
216
  type Result_4 =
148
217
  variant {
149
218
  err: Error;
150
- ok: WorkerStatus;
219
+ ok: nat;
151
220
  };
152
221
  type Result_3 =
153
222
  variant {
154
223
  err: Error;
155
- ok: nat;
224
+ ok: bool;
156
225
  };
157
226
  type Result_2 =
158
227
  variant {
159
228
  err: Error;
160
- ok: bool;
229
+ ok: RequestView;
230
+ };
231
+ type Result_10 =
232
+ variant {
233
+ err: Error;
234
+ ok: ChooseOutcome;
161
235
  };
162
236
  type Result_1 =
163
237
  variant {
164
238
  err: Error;
165
- ok: RequestView;
239
+ ok: ScheduledView;
166
240
  };
167
241
  type Result =
168
242
  variant {
169
243
  err: Error;
170
244
  ok: nat64;
171
245
  };
246
+ type RescueReason =
247
+ variant {
248
+ driverDropped;
249
+ noChoice;
250
+ };
172
251
  type RequestView =
173
252
  record {
174
253
  asOfNs: opt nat64;
@@ -219,6 +298,13 @@ type RegisterDriver =
219
298
  geohash: Geohash;
220
299
  validUntilNs: opt nat64;
221
300
  };
301
+ type RegisterBase =
302
+ record {
303
+ card: DriverCard;
304
+ cardVersion: nat32;
305
+ driverKey: DriverKey;
306
+ geohash: Geohash;
307
+ };
222
308
  type RateDriverArgs =
223
309
  record {
224
310
  requestId: RequestId;
@@ -464,6 +550,11 @@ type CarrierKind =
464
550
  rideHailing;
465
551
  taxi;
466
552
  };
553
+ type BookingRef =
554
+ record {
555
+ driverKey: DriverKey;
556
+ requestId: RequestId;
557
+ };
467
558
  type AreaMap =
468
559
  record {
469
560
  entries: vec PrefixEntry;