@fabriktor/fx 0.0.140 → 0.0.142

package/dist/src/core/address.d.ts

@@ -0,0 +1,2 @@
+import type { Address } from "@fabriktor/schema";
+export declare function addressTimezone(address: Pick<Address, "address_timezone">): string | null;

package/dist/src/core/address.js

@@ -0,0 +1,6 @@
+import { dateTimezone } from "./date.js";
+// Always use the saved backend computation, never the device's timezone.
+export function addressTimezone(address) {
+    const timezone = address.address_timezone.trim();
+    return timezone && dateTimezone(timezone) === timezone ? timezone : null;
+}

package/dist/src/core/measurement.d.ts

@@ -0,0 +1,15 @@
+export type DistanceUnit = "meter" | "kilometer" | "foot" | "yard" | "mile";
+export type DurationUnit = "day" | "hour" | "minute" | "second";
+export type Measurement<U extends string> = {
+    value: number;
+    unit: U;
+};
+type RoadUnits = {
+    large: DistanceUnit;
+    small: DistanceUnit;
+    threshold: number;
+};
+export declare const roadDistanceUnits: Readonly<Record<string, RoadUnits>>;
+export declare function roadDistance(meters: number, country: string): Measurement<DistanceUnit> | undefined;
+export declare function durationParts(value: number, unit: DurationUnit): Measurement<DurationUnit>[];
+export {};

package/dist/src/core/measurement.js

@@ -0,0 +1,45 @@
+import convert from "convert";
+// Road-distance preferences, not a country's system for every measurement.
+// Thresholds/units follow Unicode CLDR's road usage; metric is the fallback.
+// https://github.com/unicode-org/cldr/blob/main/common/supplemental/units.xml
+const metricRoadUnits = {
+    large: "kilometer",
+    small: "meter",
+    threshold: 0.9,
+};
+export const roadDistanceUnits = {
+    US: { large: "mile", small: "foot", threshold: 0.5 },
+    GB: { large: "mile", small: "yard", threshold: 0.5 },
+};
+export function roadDistance(meters, country) {
+    if (!Number.isFinite(meters) || meters < 0)
+        return;
+    const units = roadDistanceUnits[country.trim().toUpperCase()] ?? metricRoadUnits;
+    const large = convert(meters, "meter").to(units.large);
+    return large >= units.threshold
+        ? { value: large, unit: units.large }
+        : {
+            value: convert(meters, "meter").to(units.small),
+            unit: units.small,
+        };
+}
+const durationUnits = [
+    "day",
+    "hour",
+    "minute",
+    "second",
+];
+export function durationParts(value, unit) {
+    if (!Number.isFinite(value) || value < 0)
+        return [];
+    let seconds = Math.round(convert(value, unit).to("second"));
+    const parts = [];
+    for (const target of durationUnits) {
+        const amount = Math.floor(convert(seconds, "second").to(target));
+        if (!amount)
+            continue;
+        parts.push({ value: amount, unit: target });
+        seconds -= convert(amount, target).to("second");
+    }
+    return parts.length ? parts : [{ value: 0, unit: "second" }];
+}

package/dist/src/fx.js

@@ -100,6 +100,9 @@ export class FX {
         });
         this.routes = newRoutesFX({
             routes: opts.routes,
+            jobs: opts.jobs,
+            users: opts.users,
+            billable: opts.billable,
         });
         this.storage = newStorageFX({
             storage: opts.storage,

package/dist/src/index.d.ts

@@ -7,10 +7,12 @@ export * from "./chat/optimistic.js";
 export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
 export * from "./contacts/scope.js";
+export * from "./core/address.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/events.js";
 export * from "./core/id.js";
+export * from "./core/measurement.js";
 export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
@@ -36,6 +38,7 @@ export * from "./privacy/privacy.js";
 export * from "./processes/processes.js";
 export * from "./routes/arrival.js";
 export * from "./routes/availability.js";
+export * from "./routes/departure.js";
 export * from "./routes/planning.js";
 export * from "./routes/punch.js";
 export * from "./routes/routes.js";

package/dist/src/index.js

@@ -7,10 +7,12 @@ export * from "./chat/optimistic.js";
 export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
 export * from "./contacts/scope.js";
+export * from "./core/address.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/events.js";
 export * from "./core/id.js";
+export * from "./core/measurement.js";
 export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
@@ -36,6 +38,7 @@ export * from "./privacy/privacy.js";
 export * from "./processes/processes.js";
 export * from "./routes/arrival.js";
 export * from "./routes/availability.js";
+export * from "./routes/departure.js";
 export * from "./routes/planning.js";
 export * from "./routes/punch.js";
 export * from "./routes/routes.js";

package/dist/src/routes/availability.js

@@ -1,5 +1,6 @@
 import { UserTypeClient, UserTypeEmployer, } from "@fabriktor/schema";
-import { dateTimezone, hoursPerDay, minutesOfDay, minutesPerHour, sameCalendarDay, } from "../core/date.js";
+import { addressTimezone } from "../core/address.js";
+import { hoursPerDay, minutesOfDay, minutesPerHour, sameCalendarDay, } from "../core/date.js";
 import { errValidation } from "../core/err.js";
 import { normalizeIDs, resolvedID } from "../core/id.js";
 import { newChatData } from "../chat/data.js";
@@ -11,7 +12,7 @@ export const RoutesChatDataType = {
     AvailabilitySubmitted: "routes.availability.submitted",
 };
 const msgAvailabilityAccess = "This availability does not match the client and employer of the location.";
-const msgAvailabilityTimezone = "The employer needs a valid saved address timezone.";
+const msgAvailabilityTimezone = "The location needs a valid saved address timezone.";
 const msgAvailabilityHours = "The employer's working hours must form a valid same-day window.";
 const msgAvailabilityWindows = "Provide enough distinct, non-overlapping availability windows within the employer's working hours.";
 const msgAvailabilityData = "The availability request is invalid.";
@@ -82,8 +83,8 @@ export async function loadAvailabilityContext(readers, actor, reference, signal)
         employer.id !== reference.employer_id ||
         employer.account_identity !== UserTypeEmployer)
         throw errValidation({ msg: msgAvailabilityAccess });
-    const timezone = employer.address_timezone.trim();
-    if (!timezone || dateTimezone(timezone) !== timezone)
+    const timezone = addressTimezone(location);
+    if (!timezone)
         throw errValidation({ msg: msgAvailabilityTimezone });
     const { work_day_start_hour: start, work_day_end_hour: end } = company;
     if (![start, end].every((hour) => Number.isInteger(hour) && hour >= 0 && hour < hoursPerDay) ||

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

@@ -0,0 +1,45 @@
+import type { BillableOperator, JobsOperator, UsersOperator } from "@fabriktor/client";
+import type { Address, InRoute, Location, Route, User, Warehouse } from "@fabriktor/schema";
+export declare const RouteDepartureSource: {
+    readonly Company: "company";
+    readonly Warehouse: "warehouse";
+    readonly SavedRoute: "saved_route";
+};
+export type RouteDepartureReference = {
+    source: typeof RouteDepartureSource.Company;
+} | {
+    source: typeof RouteDepartureSource.Warehouse;
+    warehouse_id: string;
+} | {
+    source: typeof RouteDepartureSource.SavedRoute;
+    route_id: string;
+};
+export type RouteDeparture = {
+    reference: RouteDepartureReference;
+    address: Address;
+    name: string;
+};
+export type RoutePlanningReaders = {
+    users: Pick<UsersOperator, "findOneUser">;
+    billable: Pick<BillableOperator, "findOneWarehouse">;
+    jobs: Pick<JobsOperator, "findOneLocation">;
+};
+export declare const RoutePlanningBlock: {
+    readonly Departure: "route_departure_invalid";
+    readonly DepartureChanged: "route_departure_changed";
+    readonly DestinationTimezone: "route_destination_timezone";
+    readonly DestinationChanged: "route_destination_changed";
+};
+export declare function companyRouteDeparture(user: User): RouteDeparture;
+export declare function warehouseRouteDeparture(warehouse: Warehouse, owner_id: string): RouteDeparture;
+export declare function loadRouteDeparture(readers: RoutePlanningReaders, owner_id: string, reference: Exclude<RouteDepartureReference, {
+    source: typeof RouteDepartureSource.SavedRoute;
+}>, signal?: AbortSignal): Promise<RouteDeparture>;
+export declare function validateRoutePlanLocation(location: Location, owner_id: string, timezone: string): void;
+export declare function validateRoutePlanAddresses(readers: RoutePlanningReaders, opts: {
+    owner_id: string;
+    input: InRoute;
+    departure: RouteDepartureReference;
+    current?: Route;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/src/routes/departure.js

@@ -0,0 +1,98 @@
+import { UserTypeEmployer } from "@fabriktor/schema";
+import { addressTimezone } from "../core/address.js";
+import { resolvedID } from "../core/id.js";
+import { PreActionBlocked } from "../core/pre-action.js";
+export const RouteDepartureSource = {
+    Company: "company",
+    Warehouse: "warehouse",
+    SavedRoute: "saved_route",
+};
+export const RoutePlanningBlock = {
+    Departure: "route_departure_invalid",
+    DepartureChanged: "route_departure_changed",
+    DestinationTimezone: "route_destination_timezone",
+    DestinationChanged: "route_destination_changed",
+};
+export function companyRouteDeparture(user) {
+    if (user.account_identity !== UserTypeEmployer ||
+        !user.place_id.trim() ||
+        !addressTimezone(user))
+        throw new PreActionBlocked(RoutePlanningBlock.Departure);
+    return {
+        reference: { source: RouteDepartureSource.Company },
+        address: user,
+        name: "",
+    };
+}
+export function warehouseRouteDeparture(warehouse, owner_id) {
+    if (warehouse.owner_id !== owner_id ||
+        warehouse.is_archived ||
+        !warehouse.place_id.trim() ||
+        !addressTimezone(warehouse))
+        throw new PreActionBlocked(RoutePlanningBlock.Departure);
+    return {
+        reference: {
+            source: RouteDepartureSource.Warehouse,
+            warehouse_id: warehouse.id,
+        },
+        address: warehouse,
+        name: warehouse.name,
+    };
+}
+export async function loadRouteDeparture(readers, owner_id, reference, signal) {
+    if (reference.source === RouteDepartureSource.Warehouse) {
+        const warehouse = (await readers.billable.findOneWarehouse({
+            id: reference.warehouse_id,
+            signal,
+        })).value;
+        if (warehouse?.id === reference.warehouse_id)
+            return warehouseRouteDeparture(warehouse, owner_id);
+    }
+    else {
+        const user = (await readers.users.findOneUser({ id: owner_id, signal }))
+            .value;
+        if (user?.id === owner_id)
+            return companyRouteDeparture(user);
+    }
+    throw new PreActionBlocked(RoutePlanningBlock.Departure);
+}
+export function validateRoutePlanLocation(location, owner_id, timezone) {
+    if (location.owner_id !== owner_id ||
+        location.is_archived ||
+        !location.place_id.trim() ||
+        !resolvedID(location.client_id))
+        throw new PreActionBlocked(RoutePlanningBlock.DestinationChanged);
+    if (addressTimezone(location) !== timezone)
+        throw new PreActionBlocked(RoutePlanningBlock.DestinationTimezone);
+}
+// Re-read saved operational addresses before optimization. A queued draft must
+// not submit stale location ownership, Place IDs or address timezones.
+export async function validateRoutePlanAddresses(readers, opts) {
+    const { input, departure, current, signal } = opts;
+    if (departure.source === RouteDepartureSource.SavedRoute) {
+        if (!current ||
+            current.id !== departure.route_id ||
+            current.owner_id !== opts.owner_id ||
+            current.start_place_id !== input.start_place_id ||
+            current.timezone !== input.timezone)
+            throw new PreActionBlocked(RoutePlanningBlock.DepartureChanged);
+    }
+    else {
+        const saved = await loadRouteDeparture(readers, opts.owner_id, departure, signal);
+        if (saved.address.place_id !== input.start_place_id ||
+            addressTimezone(saved.address) !== input.timezone)
+            throw new PreActionBlocked(RoutePlanningBlock.DepartureChanged);
+    }
+    for (const destination of input.destinations) {
+        const location = (await readers.jobs.findOneLocation({
+            id: destination.location_id,
+            signal,
+        })).value;
+        if (!location ||
+            location.id !== destination.location_id ||
+            location.client_id !== destination.client_id ||
+            location.place_id !== destination.place_id)
+            throw new PreActionBlocked(RoutePlanningBlock.DestinationChanged);
+        validateRoutePlanLocation(location, opts.owner_id, input.timezone);
+    }
+}

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

@@ -23,7 +23,7 @@ export declare function newRoutePlan(opts: {
     company: Pick<PrefCompany, "work_day_start_hour" | "work_day_end_hour">;
     start_place_id: string;
 }): InRoute;
-export declare function routeDestination(location: Location, owner_id: string): InRoute["destinations"][number];
+export declare function routeDestination(location: Location, owner_id: string, timezone: string): InRoute["destinations"][number];
 export declare function validateRouteEmployees(ids: readonly string[], allowed: readonly string[], occupied?: readonly string[]): void;
 export type RouteAvailabilityWindow = {
     availability: ClientAvailability;

package/dist/src/routes/planning.js

@@ -1,10 +1,10 @@
 import { isValidInputDate, minutesOfDay, sameCalendarDay, } from "../core/date.js";
 import { errValidation } from "../core/err.js";
-import { normalizeIDs, resolvedID } from "../core/id.js";
+import { normalizeIDs } from "../core/id.js";
 import { routeInput, validateRouteTimeWindow } from "./validation.js";
+import { validateRoutePlanLocation } from "./departure.js";
 import { PreActionBlocked } from "../core/pre-action.js";
 const routePreparationBlocked = "route_preparation";
-const msgPlanningLocation = "Select an active location with a client and a saved address.";
 const msgPlanningEmployees = "Choose available employees who are not already in another vehicle.";
 export const RouteMutationBlock = {
     Busy: "route_mutation_busy",
@@ -46,15 +46,8 @@ export function newRoutePlan(opts) {
         override_itinerary: routePlanningDefaults.override_itinerary,
     };
 }
-export function routeDestination(location, owner_id) {
-    if (location.owner_id !== owner_id ||
-        location.is_archived ||
-        !location.place_id.trim() ||
-        !resolvedID(location.client_id))
-        throw errValidation({
-            field: "destinations",
-            msg: msgPlanningLocation,
-        });
+export function routeDestination(location, owner_id, timezone) {
+    validateRoutePlanLocation(location, owner_id, timezone);
     return {
         location_id: location.id,
         client_id: location.client_id,

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

@@ -1,3 +1,4 @@
+import { type RouteDepartureReference, type RoutePlanningReaders } from "./departure.js";
 import type { RoutesOperator } from "@fabriktor/client";
 import type { ClientAvailability, InRoute, Route, RouteTeam, RPRoutesAvailability, Tag, Tracking } from "@fabriktor/schema";
 import { RoutesWorkspace, type PrepareRouteOptions, type RoutesActor } from "./workspace.js";
@@ -21,6 +22,7 @@ export type CreateValidatedRouteResult = Awaited<ReturnType<RoutesOperator["inse
 export type CreateRouteResult = CreateValidatedRouteResult;
 export type CreatePlannedRouteOptions = Omit<PrepareRouteOptions, "request"> & {
     attempt: MultiCreateAttempt;
+    departure: RouteDepartureReference;
 };
 export type ReplaceRouteOptions = RouteReplaceOptions & {
     availability?: RPRoutesAvailability;
@@ -36,6 +38,7 @@ export type RouteMutationOptions = {
 export type ReplacePlannedRouteOptions = RouteMutationOptions & {
     in: InRoute;
     days_ago: PrepareRouteOptions["days_ago"];
+    departure: RouteDepartureReference;
 };
 export type CreateTagOptions = TagInsertOptions & Pick<MultiCreateCheckpoint, "before_request" | "on_created">;
 export type ReplaceTagOptions = TagReplaceOptions;
@@ -49,7 +52,7 @@ export type CreateRouteTeamOptions = RouteTeamInsertOptions & Pick<MultiCreateCh
 export type ReplaceRouteTeamOptions = RouteTeamReplaceOptions;
 export type SearchRouteTeamsOptions = OwnerSearchOptions;
 export type SearchRouteTeamsPage = SearchPage<RouteTeam>;
-export type RoutesFXOptions = {
+export type RoutesFXOptions = RoutePlanningReaders & {
     routes: RoutesOperator;
 };
 export interface RoutesFXOperator {
@@ -72,6 +75,7 @@ export interface RoutesFXOperator {
     searchRouteTeams(opts: SearchRouteTeamsOptions): Promise<SearchRouteTeamsPage>;
 }
 export declare class RoutesFX implements RoutesFXOperator {
+    private readonly opts;
     private routes;
     private routeMutationPending;
     readonly workspace: RoutesWorkspace;

package/dist/src/routes/routes.js

@@ -3,6 +3,7 @@
 // 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";
@@ -27,10 +28,12 @@ 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.";
 export class RoutesFX {
+    opts;
     routes;
     routeMutationPending = false;
     workspace;
     constructor(opts) {
+        this.opts = opts;
         this.routes = opts.routes;
         this.workspace = new RoutesWorkspace(opts.routes);
     }
@@ -51,6 +54,18 @@ export class RoutesFX {
                 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,
@@ -121,6 +136,13 @@ export class RoutesFX {
             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),
@@ -128,7 +150,7 @@ export class RoutesFX {
                 days_ago: opts.days_ago,
                 request: { signal: opts.signal },
             });
-            // Retain this route's own assignments, but never another route's.
+            // Repeated locations are allowed; employee conflicts remain enforced.
             validateRouteInput(input, availability, current.id);
             const result = await this.replaceRoute({
                 id: current.id,

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

@@ -6,6 +6,7 @@ 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 routeAssignmentsByEntity(assignments: RPRoutesAvailability["assignations"]["locations"], replacing_route_id?: string): Map<string, string[]>;
 export declare function validateClientAvailabilityInput(input: InClientAvailability): void;
 export declare function validateRouteTeamInput(input: InRouteTeam): void;
 export declare function normalizedTagInput(input: InTag): InTag;

package/dist/src/routes/validation.js

@@ -165,10 +165,17 @@ export function validateRouteDestination(destination, window) {
         });
     }
 }
-// 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.
+// Locations may be visited on several routes. Employees stay exclusive for
+// the checked day; editing may retain only this route's employee assignments.
 export function availableRouteIDs(availability, kind, replacing_route_id) {
     const ids = new Set(normalizeIDs(availability.availables[kind]));
+    if (kind === "locations") {
+        for (const assignment of availability.assignations.locations) {
+            for (const id of normalizeIDs(assignment.entity_ids))
+                ids.add(id);
+        }
+        return ids;
+    }
     for (const assignment of availability.assignations[kind]) {
         if (assignment.route_id === replacing_route_id) {
             for (const id of normalizeIDs(assignment.entity_ids))
@@ -183,6 +190,23 @@ export function availableRouteIDs(availability, kind, replacing_route_id) {
     }
     return ids;
 }
+// Group the backend's existing route references for informational display.
+// Exclude the route being edited and count each route only once per entity.
+export function routeAssignmentsByEntity(assignments, replacing_route_id) {
+    const out = new Map();
+    for (const assignment of assignments) {
+        const routeID = resolvedID(assignment.route_id);
+        if (!routeID || routeID === replacing_route_id)
+            continue;
+        for (const entityID of normalizeIDs(assignment.entity_ids)) {
+            const routes = out.get(entityID) ?? [];
+            if (!routes.includes(routeID))
+                routes.push(routeID);
+            out.set(entityID, routes);
+        }
+    }
+    return out;
+}
 export function validateClientAvailabilityInput(input) {
     validateRouteTimeWindow(input);
     for (const field of ["employer_id", "location_id"]) {

package/dist/src/routes/workspace.js

@@ -91,7 +91,8 @@ export class RoutesWorkspace {
         const query = {
             ...queryParams({
                 owner_id,
-                timezone: opts.day?.tz,
+                // A day filter refers to the calendar day stored on each route.
+                // Employers may operate depots in different timezones.
                 utilized_employee_ids: actor.active_mode === UserTypeEmployee
                     ? actor.owner_id
                     : optionalIDs(opts.employee_ids),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.140",
+  "version": "0.0.142",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -19,6 +19,7 @@
   "dependencies": {
     "@fabriktor/client": "0.0.98",
     "@fabriktor/fx": "0.0.94",
-    "@fabriktor/schema": "0.0.68"
+    "@fabriktor/schema": "0.0.68",
+    "convert": "8.0.2"
   }
 }