@fabriktor/fx 0.0.138 → 0.0.140

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 {};

package/dist/src/routes/tracking.js

@@ -0,0 +1,178 @@
+import { UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
+import { dateTimezone, inDateAtTimestamp, timestampDate, } from "../core/date.js";
+import { routeCanRead, routeCanTrack, routeTrackingInput, } from "./workspace.js";
+export const trackingRefreshDelayMS = 15_000;
+export const trackingRefreshMaxAttempts = 240;
+export const trackingStaleAfterMS = 90_000;
+export const trackingMaximumAccuracyMeters = 200;
+export const trackingMaximumSampleAgeMS = 30_000;
+export const trackingReadTimeoutMS = 15_000;
+const serverDateResolutionMS = 1_000;
+export const TrackingIssue = {
+    Access: "tracking_access",
+    OutsideRoute: "tracking_outside_route",
+    Timezone: "tracking_timezone",
+    Accuracy: "tracking_accuracy",
+    Busy: "tracking_busy",
+    Unconfirmed: "tracking_unconfirmed",
+    Record: "tracking_record",
+};
+export class TrackingError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+    }
+}
+export function trackingFreshness(record, now) {
+    const updated = record
+        ? timestampDate(record.updated_at)?.getTime()
+        : undefined;
+    if (updated === undefined ||
+        now === null ||
+        updated > now + serverDateResolutionMS)
+        return "unknown";
+    return now - updated <= trackingStaleAfterMS ? "recent" : "stale";
+}
+// The backend's default CreatedAt order selects the current snapshot. Never
+// sort/filter collection results locally or turn old points into a live trail.
+async function currentTracking(workspace, scope, employee_id, signal) {
+    const rows = await workspace.tracking({
+        ...scope,
+        employee_ids: [employee_id],
+        vehicle_ids: [scope.vehicle_id],
+        signal,
+    });
+    const record = rows[0];
+    if (record &&
+        (record.owner_id !== scope.route.owner_id ||
+            record.route_id !== scope.route.id ||
+            record.vehicle_id !== scope.vehicle_id ||
+            record.employee_id !== employee_id))
+        throw new TrackingError(TrackingIssue.Record);
+    return record;
+}
+export async function loadRouteTracking(workspace, scope, signal) {
+    const vehicle = scope.route.itinerary.routes.find((value) => value.vehicle_id === scope.vehicle_id);
+    if (![UserTypeEmployee, UserTypeEmployer].includes(scope.actor.active_mode) ||
+        !routeCanRead(scope.actor, scope.route) ||
+        !vehicle ||
+        vehicle.is_omitted ||
+        !vehicle.stops.length)
+        throw new TrackingError(TrackingIssue.Access);
+    const employees = scope.actor.active_mode === UserTypeEmployee
+        ? [scope.actor.owner_id]
+        : vehicle.employee_ids;
+    return Promise.all(employees.map(async (employee_id) => ({
+        employee_id,
+        tracking: await currentTracking(workspace, scope, employee_id, signal),
+    })));
+}
+// One application-wide reporter serializes all tracking writes. Acknowledged
+// IDs survive read errors; no uncertain POST is retried by the refresh loop.
+export class RouteTrackingReporter {
+    routes;
+    actions;
+    clock;
+    busy = false;
+    checkpoints = new Map();
+    constructor(routes, actions, clock) {
+        this.routes = routes;
+        this.actions = actions;
+        this.clock = clock;
+    }
+    key(scope) {
+        return [scope.actor.owner_id, scope.route.id, scope.vehicle_id].join(":");
+    }
+    unconfirmed(scope) {
+        return this.checkpoints.get(this.key(scope))?.unconfirmed === true;
+    }
+    allowNewRecord(scope) {
+        const checkpoint = this.checkpoints.get(this.key(scope));
+        if (checkpoint)
+            checkpoint.unconfirmed = false;
+    }
+    async report(opts) {
+        if (this.busy)
+            throw new TrackingError(TrackingIssue.Busy);
+        this.busy = true;
+        let checkWindow = () => { };
+        const ensureActive = () => {
+            opts.signal.throwIfAborted();
+            if (!opts.still_active())
+                throw new TrackingError(TrackingIssue.Access);
+            if (!opts.sample_current())
+                throw new TrackingError(TrackingIssue.Accuracy);
+            checkWindow();
+        };
+        try {
+            ensureActive();
+            const route = (await this.routes.findOneRoute({
+                id: opts.route.id,
+                signal: opts.signal,
+            })).value;
+            if (!route ||
+                route.owner_id !== opts.route.owner_id ||
+                route.updated_at !== opts.route.updated_at ||
+                opts.actor.active_mode !== UserTypeEmployee ||
+                !routeCanTrack(opts.actor, route, opts.vehicle_id, opts.actor.owner_id))
+                throw new TrackingError(TrackingIssue.Access);
+            const from = timestampDate(route.from.utc)?.getTime();
+            const to = timestampDate(route.to.utc)?.getTime();
+            checkWindow = () => {
+                const now = this.clock.requireNow();
+                if (from === undefined || to === undefined || now < from || now > to)
+                    throw new TrackingError(TrackingIssue.OutsideRoute);
+            };
+            checkWindow();
+            if (!opts.timezone || dateTimezone(opts.timezone) !== opts.timezone)
+                throw new TrackingError(TrackingIssue.Timezone);
+            if (!Number.isFinite(opts.position.accuracy) ||
+                opts.position.accuracy < 0 ||
+                opts.position.accuracy > trackingMaximumAccuracyMeters)
+                throw new TrackingError(TrackingIssue.Accuracy);
+            const scope = { ...opts, route };
+            const key = this.key(scope);
+            const checkpoint = this.checkpoints.get(key) ?? { unconfirmed: false };
+            this.checkpoints.set(key, checkpoint);
+            const record = await currentTracking(this.actions.workspace, scope, opts.actor.owner_id, opts.signal);
+            if (record) {
+                checkpoint.id = record.id;
+                checkpoint.unconfirmed = false;
+            }
+            if (!checkpoint.id && checkpoint.unconfirmed)
+                throw new TrackingError(TrackingIssue.Unconfirmed);
+            ensureActive();
+            const timestamp = inDateAtTimestamp(new Date(this.clock.requireNow()).toISOString(), opts.timezone);
+            if (!timestamp)
+                throw new TrackingError(TrackingIssue.Timezone);
+            const input = routeTrackingInput(opts.actor, route, opts.vehicle_id, opts.actor.owner_id, {
+                lat: opts.position.lat,
+                lon: opts.position.lon,
+                timestamp,
+            });
+            // Do not abort a dispatched write when the view closes: keep its acknowledgement.
+            if (checkpoint.id)
+                return await this.actions.replaceTracking({
+                    id: checkpoint.id,
+                    in: input,
+                    before_request: ensureActive,
+                });
+            return await this.actions.createTracking({
+                in: input,
+                idempotency_key: crypto.randomUUID(),
+                before_request: () => {
+                    ensureActive();
+                    checkpoint.unconfirmed = true;
+                },
+                on_created: (id) => {
+                    checkpoint.id = id;
+                    checkpoint.unconfirmed = false;
+                },
+            });
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { InClientAvailability, InRoute, InRouteTeam, InTag, InTracking, RPRoutesAvailability, Tracking } from "@fabriktor/schema";
+type WindowInput = Pick<InRoute, "from" | "to" | "timezone">;
+export declare function validateRouteTimeWindow(input: WindowInput): void;
+export declare function normalizeRouteTags(tags: readonly string[]): string[];
+export declare function routeInput(input: InRoute): InRoute;
+export declare function validateRouteInput(input: InRoute, availability?: RPRoutesAvailability, replacing_route_id?: string): void;
+export declare function validateRouteDestination(destination: InRoute["destinations"][number], window: WindowInput): void;
+export declare function availableRouteIDs(availability: RPRoutesAvailability, kind: keyof RPRoutesAvailability["availables"], replacing_route_id?: string): Set<string>;
+export declare function validateClientAvailabilityInput(input: InClientAvailability): void;
+export declare function validateRouteTeamInput(input: InRouteTeam): void;
+export declare function normalizedTagInput(input: InTag): InTag;
+export declare function validateTrackingInput(input: InTracking, current?: Tracking): void;
+export {};

package/dist/src/routes/validation.js

@@ -0,0 +1,227 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// 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 { isValidInputDate, minutesOfDay, minutesPerDay, sameCalendarDay, } from "../core/date.js";
+import { errValidation } from "../core/err.js";
+import { normalizeIDs, resolvedID } from "../core/id.js";
+const maxLatitude = 90;
+const maxLongitude = 180;
+const msgWindowDate = "The time window must contain valid dates and an explicit timezone.";
+const msgWindowTimezone = "The time window must use the record timezone.";
+const msgWindowSameDay = "The time window must stay within one calendar day.";
+const msgWindowOrder = "The time window must end after it starts.";
+const msgStartPlace = "A starting place is required.";
+const msgVehicles = "At least one vehicle with employees is required.";
+const msgEmployee = "Each employee must occur in exactly one vehicle.";
+const msgEmployeeUnavailable = "A selected employee is not available for this route.";
+const msgDestinations = "At least one destination is required.";
+const msgLocation = "Each destination must have a distinct location, a client and a place.";
+const msgLocationUnavailable = "A selected location is not available for this route.";
+const msgDuration = "The stop duration must be a positive whole number of minutes within one day.";
+const msgDestinationWindow = "A destination time window is invalid or outside the route window.";
+const msgAvailabilityReference = "An employer and a location are required for client availability.";
+const msgTeam = "A team must contain distinct, nonempty employee IDs.";
+const msgTag = "A tag must not be empty.";
+const msgCoordinates = "Tracking coordinates are invalid.";
+const msgTrackingReference = "Tracking requires a route, vehicle and employee.";
+const msgTimestamp = "Tracking requires a valid timestamp with an explicit timezone.";
+const msgTrackingAssignment = "Tracking assignment cannot be changed; create a new record.";
+export function validateRouteTimeWindow(input) {
+    for (const field of ["from", "to"]) {
+        if (!isValidInputDate(input[field])) {
+            throw errValidation({ field, msg: msgWindowDate });
+        }
+    }
+    if (input.from.tz !== input.timezone || input.to.tz !== input.timezone) {
+        throw errValidation({
+            field: "timezone",
+            msg: msgWindowTimezone,
+        });
+    }
+    if (!sameCalendarDay(input.from, input.to)) {
+        throw errValidation({ field: "to", msg: msgWindowSameDay });
+    }
+    if (minutesOfDay(input.from) >= minutesOfDay(input.to)) {
+        throw errValidation({ field: "to", msg: msgWindowOrder });
+    }
+}
+export function normalizeRouteTags(tags) {
+    return [
+        ...new Set(tags.map((tag) => tag.trim().toLowerCase()).filter(Boolean)),
+    ];
+}
+// Project editable fields explicitly: output-only itinerary, ownership and
+// vehicle IDs must never be sent back as a frontend-owned contract.
+export function routeInput(input) {
+    return {
+        timezone: input.timezone,
+        from: {
+            y: input.from.y,
+            m: input.from.m,
+            d: input.from.d,
+            h: input.from.h,
+            min: input.from.min,
+            tz: input.from.tz,
+        },
+        to: {
+            y: input.to.y,
+            m: input.to.m,
+            d: input.to.d,
+            h: input.to.h,
+            min: input.to.min,
+            tz: input.to.tz,
+        },
+        vehicles: input.vehicles.map((vehicle) => ({
+            tags: normalizeRouteTags(vehicle.tags),
+            employee_ids: vehicle.employee_ids.map((id) => id.trim()),
+        })),
+        start_place_id: input.start_place_id.trim(),
+        destinations: input.destinations.map((destination) => ({
+            tags: normalizeRouteTags(destination.tags),
+            location_id: destination.location_id.trim(),
+            client_id: destination.client_id.trim(),
+            place_id: destination.place_id.trim(),
+            duration_in_minutes: destination.duration_in_minutes,
+            use_time_window: destination.use_time_window,
+            time_window_start_hour_in_minutes: destination.time_window_start_hour_in_minutes,
+            time_window_end_hour_in_minutes: destination.time_window_end_hour_in_minutes,
+        })),
+        override_itinerary: input.override_itinerary,
+        consider_traffic: input.consider_traffic,
+        start_early: input.start_early,
+    };
+}
+export function validateRouteInput(input, availability, replacing_route_id) {
+    validateRouteTimeWindow(input);
+    if (!input.start_place_id.trim()) {
+        throw errValidation({
+            field: "start_place_id",
+            msg: msgStartPlace,
+        });
+    }
+    if (!input.vehicles.length ||
+        input.vehicles.some((vehicle) => !vehicle.employee_ids.length)) {
+        throw errValidation({ field: "vehicles", msg: msgVehicles });
+    }
+    const employees = input.vehicles.flatMap((vehicle) => vehicle.employee_ids);
+    if (normalizeIDs(employees).length !== employees.length) {
+        throw errValidation({ field: "vehicles", msg: msgEmployee });
+    }
+    if (!input.destinations.length) {
+        throw errValidation({
+            field: "destinations",
+            msg: msgDestinations,
+        });
+    }
+    const locations = input.destinations.map((destination) => destination.location_id);
+    if (normalizeIDs(locations).length !== locations.length ||
+        input.destinations.some((destination) => !resolvedID(destination.client_id) || !destination.place_id.trim())) {
+        throw errValidation({ field: "destinations", msg: msgLocation });
+    }
+    if (availability) {
+        const availableEmployees = availableRouteIDs(availability, "employees", replacing_route_id);
+        const availableLocations = availableRouteIDs(availability, "locations", replacing_route_id);
+        if (employees.some((id) => !availableEmployees.has(id.trim()))) {
+            throw errValidation({
+                field: "vehicles",
+                msg: msgEmployeeUnavailable,
+            });
+        }
+        if (locations.some((id) => !availableLocations.has(id.trim()))) {
+            throw errValidation({
+                field: "destinations",
+                msg: msgLocationUnavailable,
+            });
+        }
+    }
+    for (const destination of input.destinations) {
+        validateRouteDestination(destination, input);
+    }
+}
+export function validateRouteDestination(destination, window) {
+    validateRouteTimeWindow(window);
+    if (!resolvedID(destination.location_id) ||
+        !resolvedID(destination.client_id) ||
+        !destination.place_id.trim()) {
+        throw errValidation({ field: "destinations", msg: msgLocation });
+    }
+    if (!Number.isInteger(destination.duration_in_minutes) ||
+        destination.duration_in_minutes <= 0 ||
+        destination.duration_in_minutes > minutesPerDay) {
+        throw errValidation({ field: "destinations", msg: msgDuration });
+    }
+    const start = destination.time_window_start_hour_in_minutes;
+    const end = destination.time_window_end_hour_in_minutes;
+    if (![start, end].every((minute) => Number.isInteger(minute) && minute >= 0 && minute <= minutesPerDay) ||
+        (destination.use_time_window &&
+            (start >= end ||
+                start < minutesOfDay(window.from) ||
+                end > minutesOfDay(window.to)))) {
+        throw errValidation({
+            field: "destinations",
+            msg: msgDestinationWindow,
+        });
+    }
+}
+// Editing may retain this route's assignments, but must not re-enable an ID
+// also assigned to another route. Availability is still a backend snapshot.
+export function availableRouteIDs(availability, kind, replacing_route_id) {
+    const ids = new Set(normalizeIDs(availability.availables[kind]));
+    for (const assignment of availability.assignations[kind]) {
+        if (assignment.route_id === replacing_route_id) {
+            for (const id of normalizeIDs(assignment.entity_ids))
+                ids.add(id);
+        }
+    }
+    for (const assignment of availability.assignations[kind]) {
+        if (assignment.route_id !== replacing_route_id) {
+            for (const id of normalizeIDs(assignment.entity_ids))
+                ids.delete(id);
+        }
+    }
+    return ids;
+}
+export function validateClientAvailabilityInput(input) {
+    validateRouteTimeWindow(input);
+    for (const field of ["employer_id", "location_id"]) {
+        if (!resolvedID(input[field])) {
+            throw errValidation({
+                field,
+                msg: msgAvailabilityReference,
+            });
+        }
+    }
+}
+export function validateRouteTeamInput(input) {
+    if (!input.employee_ids.length ||
+        normalizeIDs(input.employee_ids).length !== input.employee_ids.length) {
+        throw errValidation({ field: "employee_ids", msg: msgTeam });
+    }
+}
+export function normalizedTagInput(input) {
+    const v = input.v.trim().toLowerCase();
+    if (!v)
+        throw errValidation({ field: "v", msg: msgTag });
+    return { v };
+}
+export function validateTrackingInput(input, current) {
+    if (!Number.isFinite(input.lat) || Math.abs(input.lat) > maxLatitude) {
+        throw errValidation({ field: "lat", msg: msgCoordinates });
+    }
+    if (!Number.isFinite(input.lon) || Math.abs(input.lon) > maxLongitude) {
+        throw errValidation({ field: "lon", msg: msgCoordinates });
+    }
+    for (const field of ["route_id", "vehicle_id", "employee_id"]) {
+        if (!resolvedID(input[field])) {
+            throw errValidation({ field, msg: msgTrackingReference });
+        }
+        if (current && input[field] !== current[field]) {
+            throw errValidation({ field, msg: msgTrackingAssignment });
+        }
+    }
+    if (!isValidInputDate(input.timestamp)) {
+        throw errValidation({ field: "timestamp", msg: msgTimestamp });
+    }
+}

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

@@ -0,0 +1,74 @@
+import type { GetAvailabilityOptions, GetDesignationOptions, RequestOptions, RoutesOperator } from "@fabriktor/client";
+import { type ClientAvailability, type InDate, type InRoute, type InTracking, type Route, type RPRoutesAvailability, type Tracking, type VehicleRoute } from "@fabriktor/schema";
+import type { EmploymentActor } from "../contacts/scope.js";
+export type RoutesActor = EmploymentActor;
+export declare const routeRefreshDefaults: {
+    readonly delay_ms: 30000;
+    readonly max_attempts: 120;
+    readonly timeout_ms: 15000;
+};
+export declare const RoutesResource: {
+    readonly Routes: "routes";
+    readonly Tags: "tags";
+    readonly Teams: "route_teams";
+    readonly ClientAvailabilities: "client_availabilities";
+    readonly Tracking: "tracking";
+};
+export type RoutesResource = (typeof RoutesResource)[keyof typeof RoutesResource];
+export declare const routesSearchableResources: readonly RoutesResource[];
+export declare function routeCanPlan(actor: RoutesActor): boolean;
+export declare function routeCanManage(actor: RoutesActor, route: Route): boolean;
+export declare function routeCanRead(actor: RoutesActor, route: Route): boolean;
+export declare function routeTrackingVehicle(route: Route, vehicle_id: string, employee_id: string): VehicleRoute | undefined;
+export declare function routeCanTrack(actor: RoutesActor, route: Route, vehicle_id: string, employee_id: string): boolean;
+export declare function routeTrackingInput(actor: RoutesActor, route: Route, vehicle_id: string, employee_id: string, position: Pick<InTracking, "lat" | "lon" | "timestamp">): InTracking;
+export type RoutesReadOptions = {
+    actor: RoutesActor;
+    employer_id?: string;
+    day?: InDate;
+    employee_ids?: string[];
+    client_ids?: string[];
+    signal?: AbortSignal;
+};
+export type RoutesAvailabilityOptions = GetAvailabilityOptions & {
+    actor: RoutesActor;
+    request?: RequestOptions;
+};
+export type RoutesDesignationOptions = GetDesignationOptions & {
+    actor: RoutesActor;
+    request?: RequestOptions;
+};
+export type PrepareRouteOptions = {
+    actor: RoutesActor;
+    in: InRoute;
+    days_ago: GetAvailabilityOptions["days_ago"];
+    request?: RequestOptions;
+};
+export type PreparedRoute = {
+    in: InRoute;
+    availability: RPRoutesAvailability;
+};
+export type ClientAvailabilitiesReadOptions = {
+    actor: RoutesActor;
+    employer_ids?: string[];
+    location_ids?: string[];
+    timezone?: string;
+    signal?: AbortSignal;
+};
+export type RoutesTrackingReadOptions = {
+    actor: RoutesActor;
+    route: Route;
+    employee_ids?: string[];
+    vehicle_ids?: string[];
+    signal?: AbortSignal;
+};
+export declare class RoutesWorkspace {
+    private readonly routes;
+    constructor(routes: RoutesOperator);
+    readRoutes(opts: RoutesReadOptions): Promise<Route[]>;
+    availability(opts: RoutesAvailabilityOptions): Promise<RPRoutesAvailability>;
+    prepareRoute(opts: PrepareRouteOptions): Promise<PreparedRoute>;
+    designations(opts: RoutesDesignationOptions): Promise<Route[]>;
+    clientAvailabilities(opts: ClientAvailabilitiesReadOptions): Promise<ClientAvailability[]>;
+    tracking(opts: RoutesTrackingReadOptions): Promise<Tracking[]>;
+}