@fabriktor/fx 0.0.139 → 0.0.141

package/dist/src/routes/routes.js

@@ -3,12 +3,14 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { validateRoutePlanAddresses, } from "./departure.js";
 import { errResolveFailed, errValidation } from "../core/err.js";
+import { RoutesWorkspace, routeCanManage, routeCanPlan, } from "./workspace.js";
+import { RoutePreparationBlocked, RouteMutationBlock, routePlanChanged, } from "./planning.js";
+import { PreActionBlocked } from "../core/pre-action.js";
+import { normalizedTagInput, routeInput, validateClientAvailabilityInput, validateRouteInput, validateRouteTeamInput, validateTrackingInput, } from "./validation.js";
 import { requiredOperationID } from "../core/id.js";
 import { runOwnerSearch, } from "../core/search.js";
-const maxHour = 23;
-const maxMinute = 59;
-const maxMinuteOfDay = 1440;
 const resourceRoute = "route";
 const resourceTag = "tag";
 const resourceClientAvailability = "client_availability";
@@ -16,6 +18,7 @@ const resourceTracking = "tracking";
 const resourceRouteTeam = "route_team";
 const msgCreatedRouteIDMissing = "Created route response did not contain an ID.";
 const msgRouteMissing = "Route could not be resolved after the mutation.";
+const msgRouteOwner = "This route does not belong to the active employer.";
 const msgCreatedTagIDMissing = "Created tag response did not contain an ID.";
 const msgTagMissing = "Tag could not be resolved after the mutation.";
 const msgCreatedClientAvailabilityIDMissing = "Created client availability response did not contain an ID.";
@@ -24,42 +27,198 @@ const msgCreatedTrackingIDMissing = "Created tracking response did not contain a
 const msgTrackingMissing = "Tracking could not be resolved after the mutation.";
 const msgCreatedRouteTeamIDMissing = "Created route team response did not contain an ID.";
 const msgRouteTeamMissing = "Route team could not be resolved after the mutation.";
-const msgGlobalWindowSameDay = "The global route window must stay within one calendar day.";
-const msgGlobalWindowInvalid = "The global route window is invalid.";
-const msgEmployeeDuplicate = "An employee cannot be selected in more than one vehicle.";
-const msgEmployeeUnavailable = "A selected employee is not available for this route.";
-const msgLocationDuplicate = "A location cannot be selected more than once.";
-const msgLocationUnavailable = "A selected location is not available for this route.";
-const msgDestinationWindowInvalid = "A destination time window is invalid.";
-const msgDestinationWindowOutsideGlobal = "A destination time window must stay within the global route window.";
 export class RoutesFX {
+    opts;
     routes;
+    routeMutationPending = false;
+    workspace;
     constructor(opts) {
+        this.opts = opts;
         this.routes = opts.routes;
+        this.workspace = new RoutesWorkspace(opts.routes);
     }
     async createRoute(opts) {
         const out = await this.createValidatedRoute(opts);
         const id = requiredOperationID(out, msgCreatedRouteIDMissing);
-        return await this.findRoute(id);
+        return await this.findRoute(id, opts.signal);
     }
-    async createValidatedRoute(opts) {
-        validateRoute(opts.in, opts.availability);
-        return await this.routes.insertOneRoute({
+    // Recheck availability immediately before each write. An acknowledged ID
+    // resumes only the read, so a failed follow-up GET cannot repeat optimization.
+    async createPlannedRoute(opts) {
+        const { attempt, actor } = opts;
+        if (!routeCanPlan(actor))
+            throw errValidation({ msg: msgRouteOwner });
+        if (attempt.created_id) {
+            const route = await this.findRoute(attempt.created_id, attempt.signal);
+            if (!routeCanManage(actor, route))
+                throw errValidation({ msg: msgRouteOwner });
+            return route;
+        }
+        try {
+            validateRouteInput(opts.in);
+            await validateRoutePlanAddresses(this.opts, {
+                owner_id: actor.owner_id,
+                input: opts.in,
+                departure: opts.departure,
+                signal: attempt.signal,
+            });
+        }
+        catch (error) {
+            throw new RoutePreparationBlocked(error);
+        }
+        const prepared = await this.workspace
+            .prepareRoute({
+            actor,
             in: opts.in,
+            days_ago: opts.days_ago,
+            request: { signal: attempt.signal },
+        })
+            .catch((error) => {
+            // No creation was attempted. Keep the draft editable in the shared queue.
+            throw new RoutePreparationBlocked(error);
+        });
+        return this.createRoute({
+            in: prepared.in,
+            availability: prepared.availability,
+            signal: attempt.signal,
+            idempotency_key: attempt.idempotency_key,
+            before_request: attempt.before_request,
+            on_created: attempt.on_created,
         });
     }
+    async createValidatedRoute(opts) {
+        const input = routeInput(opts.in);
+        validateRouteInput(input, opts.availability);
+        opts.before_request?.();
+        const out = await this.routes.insertOneRoute({
+            in: input,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
+        });
+        opts.on_created?.(requiredOperationID(out, msgCreatedRouteIDMissing));
+        return out;
+    }
     async replaceRoute(opts) {
-        await this.routes.replaceOneRoute(opts);
-        return await this.findRoute(opts.id);
+        const current = await this.findRoute(opts.id, opts.signal);
+        if (opts.expected)
+            this.requireCurrentRoute(current, opts.expected);
+        const input = routeInput({ ...current, ...opts.in });
+        validateRouteInput(input, opts.availability, opts.id);
+        // Recompute changed plans, but do not invalidate vehicle/tracking IDs for
+        // an unchanged save. An explicit override still requests reoptimization.
+        const override_itinerary = routePlanChanged(current, input);
+        if (!override_itinerary)
+            return current;
+        opts.before_request?.();
+        await this.routes.replaceOneRoute({
+            id: opts.id,
+            signal: opts.signal,
+            in: {
+                ...opts.in,
+                ...(opts.in.from !== undefined ? { from: input.from } : {}),
+                ...(opts.in.to !== undefined ? { to: input.to } : {}),
+                ...(opts.in.vehicles !== undefined ? { vehicles: input.vehicles } : {}),
+                ...(opts.in.destinations !== undefined
+                    ? { destinations: input.destinations }
+                    : {}),
+                ...(opts.in.start_place_id !== undefined
+                    ? { start_place_id: input.start_place_id }
+                    : {}),
+                override_itinerary,
+            },
+        });
+        return await this.findRoute(opts.id, opts.signal);
+    }
+    async replacePlannedRoute(opts) {
+        return this.withRouteMutation(async () => {
+            const current = await this.checkedRoute(opts);
+            const input = routeInput(opts.in);
+            validateRouteInput(input);
+            if (!routePlanChanged(current, input))
+                return current;
+            await validateRoutePlanAddresses(this.opts, {
+                owner_id: opts.actor.owner_id,
+                input,
+                departure: opts.departure,
+                current,
+                signal: opts.signal,
+            });
+            const availability = await this.workspace.availability({
+                actor: opts.actor,
+                employee_ids: input.vehicles.flatMap((vehicle) => vehicle.employee_ids),
+                date: input.from,
+                days_ago: opts.days_ago,
+                request: { signal: opts.signal },
+            });
+            // Retain this route's own assignments, but never another route's.
+            validateRouteInput(input, availability, current.id);
+            const result = await this.replaceRoute({
+                id: current.id,
+                in: input,
+                expected: current,
+                availability,
+                signal: opts.signal,
+                before_request: opts.before_request,
+            });
+            if (result.override_itinerary ||
+                routePlanChanged(result, {
+                    ...input,
+                    override_itinerary: false,
+                }))
+                throw new PreActionBlocked(RouteMutationBlock.Unconfirmed);
+            return result;
+        });
+    }
+    async deletePlannedRoute(opts) {
+        return this.withRouteMutation(async () => {
+            const current = await this.checkedRoute(opts);
+            opts.signal?.throwIfAborted();
+            opts.before_request?.();
+            await this.routes.deleteOneRoute({ id: current.id });
+        });
+    }
+    async checkedRoute(opts) {
+        if (!routeCanManage(opts.actor, opts.expected))
+            throw errValidation({ msg: msgRouteOwner });
+        const current = await this.findRoute(opts.expected.id, opts.signal);
+        if (!routeCanManage(opts.actor, current))
+            throw errValidation({ msg: msgRouteOwner });
+        this.requireCurrentRoute(current, opts.expected);
+        return current;
+    }
+    requireCurrentRoute(current, expected) {
+        if (current.id !== expected.id ||
+            current.updated_at !== expected.updated_at)
+            throw new PreActionBlocked(RouteMutationBlock.Changed);
+    }
+    async withRouteMutation(fn) {
+        if (this.routeMutationPending)
+            throw new PreActionBlocked(RouteMutationBlock.Busy);
+        this.routeMutationPending = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this.routeMutationPending = false;
+        }
     }
     async createTag(opts) {
-        const out = await this.routes.insertOneTag(opts);
+        const { on_created, before_request, ...request } = opts;
+        const input = normalizedTagInput(opts.in);
+        before_request?.();
+        const out = await this.routes.insertOneTag({
+            ...request,
+            in: input,
+        });
         const id = requiredOperationID(out, msgCreatedTagIDMissing);
-        return await this.findTag(id);
+        on_created?.(id);
+        return await this.findTag(id, opts.signal);
     }
     async replaceTag(opts) {
-        await this.routes.replaceOneTag(opts);
-        return await this.findTag(opts.id);
+        const current = await this.findTag(opts.id, opts.signal);
+        const input = normalizedTagInput({ ...current, ...opts.in });
+        await this.routes.replaceOneTag({ ...opts, in: input });
+        return await this.findTag(opts.id, opts.signal);
     }
     async searchTags(opts) {
         return await runOwnerSearch({
@@ -68,31 +227,53 @@ export class RoutesFX {
         });
     }
     async createClientAvailability(opts) {
-        const out = await this.routes.insertOneClientAvailability(opts);
+        validateClientAvailabilityInput(opts.in);
+        const { before_request, on_created, ...request } = opts;
+        before_request?.();
+        const out = await this.routes.insertOneClientAvailability(request);
         const id = requiredOperationID(out, msgCreatedClientAvailabilityIDMissing);
-        return await this.findClientAvailability(id);
+        on_created?.(id);
+        return await this.findClientAvailability(id, opts.signal);
     }
     async replaceClientAvailability(opts) {
-        await this.routes.replaceOneClientAvailability(opts);
-        return await this.findClientAvailability(opts.id);
+        const current = await this.findClientAvailability(opts.id, opts.signal);
+        validateClientAvailabilityInput({ ...current, ...opts.in });
+        const { before_request, ...request } = opts;
+        before_request?.();
+        await this.routes.replaceOneClientAvailability(request);
+        return await this.findClientAvailability(opts.id, opts.signal);
     }
     async createTracking(opts) {
-        const out = await this.routes.insertOneTracking(opts);
+        validateTrackingInput(opts.in);
+        const { before_request, on_created, ...request } = opts;
+        before_request?.();
+        const out = await this.routes.insertOneTracking(request);
         const id = requiredOperationID(out, msgCreatedTrackingIDMissing);
-        return await this.findTracking(id);
+        on_created?.(id);
+        return await this.findTracking(id, opts.signal);
     }
     async replaceTracking(opts) {
-        await this.routes.replaceOneTracking(opts);
-        return await this.findTracking(opts.id);
+        const current = await this.findTracking(opts.id, opts.signal);
+        validateTrackingInput({ ...current, ...opts.in }, current);
+        const { before_request, ...request } = opts;
+        before_request?.();
+        await this.routes.replaceOneTracking(request);
+        return await this.findTracking(opts.id, opts.signal);
     }
     async createRouteTeam(opts) {
-        const out = await this.routes.insertOneRouteTeam(opts);
+        const { on_created, before_request, ...request } = opts;
+        validateRouteTeamInput(opts.in);
+        before_request?.();
+        const out = await this.routes.insertOneRouteTeam(request);
         const id = requiredOperationID(out, msgCreatedRouteTeamIDMissing);
-        return await this.findRouteTeam(id);
+        on_created?.(id);
+        return await this.findRouteTeam(id, opts.signal);
     }
     async replaceRouteTeam(opts) {
+        const current = await this.findRouteTeam(opts.id, opts.signal);
+        validateRouteTeamInput({ ...current, ...opts.in });
         await this.routes.replaceOneRouteTeam(opts);
-        return await this.findRouteTeam(opts.id);
+        return await this.findRouteTeam(opts.id, opts.signal);
     }
     async searchRouteTeams(opts) {
         return await runOwnerSearch({
@@ -100,9 +281,10 @@ export class RoutesFX {
             search: (searchOpts) => this.routes.searchManyRouteTeams(searchOpts),
         });
     }
-    async findRoute(id) {
+    async findRoute(id, signal) {
         const out = await this.routes.findOneRoute({
             id,
+            signal,
         });
         const route = out.value;
         if (route === undefined) {
@@ -113,9 +295,10 @@ export class RoutesFX {
         }
         return route;
     }
-    async findTag(id) {
+    async findTag(id, signal) {
         const out = await this.routes.findOneTag({
             id,
+            signal,
         });
         const tag = out.value;
         if (tag === undefined) {
@@ -126,9 +309,10 @@ export class RoutesFX {
         }
         return tag;
     }
-    async findClientAvailability(id) {
+    async findClientAvailability(id, signal) {
         const out = await this.routes.findOneClientAvailability({
             id,
+            signal,
         });
         const client_availability = out.value;
         if (client_availability === undefined) {
@@ -139,9 +323,10 @@ export class RoutesFX {
         }
         return client_availability;
     }
-    async findTracking(id) {
+    async findTracking(id, signal) {
         const out = await this.routes.findOneTracking({
             id,
+            signal,
         });
         const tracking = out.value;
         if (tracking === undefined) {
@@ -152,9 +337,10 @@ export class RoutesFX {
         }
         return tracking;
     }
-    async findRouteTeam(id) {
+    async findRouteTeam(id, signal) {
         const out = await this.routes.findOneRouteTeam({
             id,
+            signal,
         });
         const route_team = out.value;
         if (route_team === undefined) {
@@ -169,105 +355,3 @@ export class RoutesFX {
 export function newRoutesFX(opts) {
     return new RoutesFX(opts);
 }
-function validateRoute(input, availability) {
-    if (!sameDay(input.from, input.to)) {
-        throw errValidation({
-            field: "to",
-            msg: msgGlobalWindowSameDay,
-        });
-    }
-    const fromMinute = minuteOfDay(input.from);
-    const toMinute = minuteOfDay(input.to);
-    if (fromMinute === undefined ||
-        toMinute === undefined ||
-        fromMinute >= toMinute) {
-        throw errValidation({
-            field: "to",
-            msg: msgGlobalWindowInvalid,
-        });
-    }
-    validateVehicles(input, availability);
-    validateDestinations(input, availability, fromMinute, toMinute);
-}
-function validateVehicles(input, availability) {
-    const availableEmployeeIDs = new Set(availability.availables.employees.map((id) => id.trim()));
-    const employeeIDs = new Set();
-    for (const vehicle of input.vehicles) {
-        for (const rawEmployeeID of vehicle.employee_ids) {
-            const employeeID = rawEmployeeID.trim();
-            if (employeeID === "") {
-                continue;
-            }
-            if (employeeIDs.has(employeeID)) {
-                throw errValidation({
-                    field: "vehicles",
-                    msg: msgEmployeeDuplicate,
-                });
-            }
-            if (!availableEmployeeIDs.has(employeeID)) {
-                throw errValidation({
-                    field: "vehicles",
-                    msg: msgEmployeeUnavailable,
-                });
-            }
-            employeeIDs.add(employeeID);
-        }
-    }
-}
-function validateDestinations(input, availability, fromMinute, toMinute) {
-    const availableLocationIDs = new Set(availability.availables.locations.map((id) => id.trim()));
-    const locationIDs = new Set();
-    for (const destination of input.destinations) {
-        const locationID = destination.location_id.trim();
-        if (locationID !== "") {
-            if (locationIDs.has(locationID)) {
-                throw errValidation({
-                    field: "destinations",
-                    msg: msgLocationDuplicate,
-                });
-            }
-            if (!availableLocationIDs.has(locationID)) {
-                throw errValidation({
-                    field: "destinations",
-                    msg: msgLocationUnavailable,
-                });
-            }
-            locationIDs.add(locationID);
-        }
-        if (!destination.use_time_window) {
-            continue;
-        }
-        const start = destination.time_window_start_hour_in_minutes;
-        const end = destination.time_window_end_hour_in_minutes;
-        if (!Number.isInteger(start) ||
-            !Number.isInteger(end) ||
-            start < 0 ||
-            end > maxMinuteOfDay ||
-            start >= end) {
-            throw errValidation({
-                field: "destinations",
-                msg: msgDestinationWindowInvalid,
-            });
-        }
-        if (start < fromMinute || end > toMinute) {
-            throw errValidation({
-                field: "destinations",
-                msg: msgDestinationWindowOutsideGlobal,
-            });
-        }
-    }
-}
-function sameDay(a, b) {
-    return a.y === b.y && a.m === b.m && a.d === b.d;
-}
-function minuteOfDay(v) {
-    if (!Number.isInteger(v.h) ||
-        !Number.isInteger(v.min) ||
-        v.h < 0 ||
-        v.h > maxHour ||
-        v.min < 0 ||
-        v.min > maxMinute) {
-        return undefined;
-    }
-    return v.h * 60 + v.min;
-}

package/dist/src/routes/tracking.d.ts

@@ -0,0 +1,59 @@
+import type { RoutesOperator } from "@fabriktor/client";
+import { type Route, type Tracking } from "@fabriktor/schema";
+import type { ServerClock } from "../core/server-clock.js";
+import type { RoutesFXOperator } from "./routes.js";
+import { type RoutesActor, type RoutesWorkspace } from "./workspace.js";
+export declare const trackingRefreshDelayMS = 15000;
+export declare const trackingRefreshMaxAttempts = 240;
+export declare const trackingStaleAfterMS = 90000;
+export declare const trackingMaximumAccuracyMeters = 200;
+export declare const trackingMaximumSampleAgeMS = 30000;
+export declare const trackingReadTimeoutMS = 15000;
+export declare const TrackingIssue: {
+    readonly Access: "tracking_access";
+    readonly OutsideRoute: "tracking_outside_route";
+    readonly Timezone: "tracking_timezone";
+    readonly Accuracy: "tracking_accuracy";
+    readonly Busy: "tracking_busy";
+    readonly Unconfirmed: "tracking_unconfirmed";
+    readonly Record: "tracking_record";
+};
+export declare class TrackingError extends Error {
+    readonly reason: (typeof TrackingIssue)[keyof typeof TrackingIssue];
+    constructor(reason: (typeof TrackingIssue)[keyof typeof TrackingIssue]);
+}
+export type TrackingPosition = Pick<Tracking, "lat" | "lon"> & {
+    accuracy: number;
+};
+export type TrackingEntry = {
+    employee_id: string;
+    tracking?: Tracking;
+};
+export type TrackingFreshness = "recent" | "stale" | "unknown";
+export type TrackingScope = {
+    actor: RoutesActor;
+    route: Route;
+    vehicle_id: string;
+};
+export declare function trackingFreshness(record: Tracking | undefined, now: number | null): TrackingFreshness;
+export declare function loadRouteTracking(workspace: RoutesWorkspace, scope: TrackingScope, signal?: AbortSignal): Promise<TrackingEntry[]>;
+type ReportOptions = TrackingScope & {
+    timezone: string;
+    position: TrackingPosition;
+    signal: AbortSignal;
+    still_active: () => boolean;
+    sample_current: () => boolean;
+};
+export declare class RouteTrackingReporter {
+    private readonly routes;
+    private readonly actions;
+    private readonly clock;
+    private busy;
+    private readonly checkpoints;
+    constructor(routes: RoutesOperator, actions: RoutesFXOperator, clock: ServerClock);
+    private key;
+    unconfirmed(scope: TrackingScope): boolean;
+    allowNewRecord(scope: TrackingScope): void;
+    report(opts: ReportOptions): Promise<Tracking>;
+}
+export {};