@fabriktor/fx 0.0.139 → 0.0.141

package/dist/src/routes/workspace.js

@@ -0,0 +1,212 @@
+// 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 { queryNestedParam, queryParams } from "@fabriktor/client";
+import { ColRoutesClientAvailabilities, ColRoutesRouteTeams, ColRoutesRoutes, ColRoutesTags, ColRoutesTracking, UserTypeClient, UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
+import { isValidInputDate } from "../core/date.js";
+import { errResolveFailed, errValidation } from "../core/err.js";
+import { normalizeIDs, resolvedID } from "../core/id.js";
+import { routeInput, validateRouteInput, validateTrackingInput, } from "./validation.js";
+export const routeRefreshDefaults = {
+    delay_ms: 30_000,
+    max_attempts: 120,
+    timeout_ms: 15_000,
+};
+export const RoutesResource = {
+    Routes: ColRoutesRoutes,
+    Tags: ColRoutesTags,
+    Teams: ColRoutesRouteTeams,
+    ClientAvailabilities: ColRoutesClientAvailabilities,
+    Tracking: ColRoutesTracking,
+};
+// Only tags and teams expose Atlas search. These are UI capabilities, never
+// a substitute for the service's per-record authorization.
+export const routesSearchableResources = [
+    RoutesResource.Tags,
+    RoutesResource.Teams,
+];
+const msgAccess = "This Routes operation is not available for the current actor.";
+const msgOwner = "An explicit employer scope is required.";
+const msgDate = "A valid date with an explicit operational timezone is required.";
+const msgDaysAgo = "days_ago must be a nonnegative whole number.";
+const msgEmployees = "At least one employee must be supplied for availability.";
+const msgAvailabilityMissing = "The availability response did not contain a value.";
+const msgDesignationMissing = "The designation response did not contain a value.";
+const msgAssignment = "Tracking requires an assigned employee and a vehicle with scheduled stops.";
+export function routeCanPlan(actor) {
+    return !!resolvedID(actor.owner_id) && actor.active_mode === UserTypeEmployer;
+}
+export function routeCanManage(actor, route) {
+    return routeCanPlan(actor) && actor.owner_id === route.owner_id;
+}
+export function routeCanRead(actor, route) {
+    if (!resolvedID(actor.owner_id))
+        return false;
+    if (routeCanManage(actor, route))
+        return true;
+    return ((actor.active_mode === UserTypeEmployee &&
+        route.utilized_employee_ids.includes(actor.owner_id)) ||
+        (actor.active_mode === UserTypeClient &&
+            route.utilized_client_ids.includes(actor.owner_id)));
+}
+export function routeTrackingVehicle(route, vehicle_id, employee_id) {
+    if (route.override_itinerary)
+        return undefined;
+    return route.itinerary.routes.find((vehicle) => vehicle.vehicle_id === vehicle_id &&
+        !vehicle.is_omitted &&
+        vehicle.stops.length > 0 &&
+        vehicle.employee_ids.includes(employee_id));
+}
+export function routeCanTrack(actor, route, vehicle_id, employee_id) {
+    return (!!resolvedID(actor.owner_id) &&
+        !!routeTrackingVehicle(route, vehicle_id, employee_id) &&
+        (routeCanManage(actor, route) ||
+            (actor.active_mode === UserTypeEmployee &&
+                actor.owner_id === employee_id)));
+}
+export function routeTrackingInput(actor, route, vehicle_id, employee_id, position) {
+    requireRoutes(routeCanTrack(actor, route, vehicle_id, employee_id), msgAssignment);
+    const input = {
+        ...position,
+        timestamp: { ...position.timestamp },
+        route_id: route.id,
+        vehicle_id,
+        employee_id,
+    };
+    validateTrackingInput(input);
+    return input;
+}
+export class RoutesWorkspace {
+    routes;
+    constructor(routes) {
+        this.routes = routes;
+    }
+    async readRoutes(opts) {
+        const actor = opts.actor;
+        const owner_id = routeReadOwner(actor, opts.employer_id);
+        if (opts.day)
+            requireRoutes(isValidInputDate(opts.day), msgDate);
+        const query = {
+            ...queryParams({
+                owner_id,
+                // 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),
+                utilized_client_ids: actor.active_mode === UserTypeClient
+                    ? actor.owner_id
+                    : optionalIDs(opts.client_ids),
+            }),
+            ...(opts.day
+                ? {
+                    ...queryNestedParam(["from", "y"], opts.day.y),
+                    ...queryNestedParam(["from", "m"], opts.day.m),
+                    ...queryNestedParam(["from", "d"], opts.day.d),
+                }
+                : {}),
+        };
+        const out = await this.routes.queryRoutes({ query, signal: opts.signal });
+        // Preserve backend membership/order; never emulate a collection search.
+        return out.value ?? [];
+    }
+    async availability(opts) {
+        requireRoutes(routeCanPlan(opts.actor), msgAccess);
+        requireRoutes(isValidInputDate(opts.date), msgDate);
+        requireRoutes(Number.isSafeInteger(opts.days_ago) && opts.days_ago >= 0, msgDaysAgo);
+        const employee_ids = normalizeIDs(opts.employee_ids);
+        requireRoutes(employee_ids.length > 0, msgEmployees);
+        const out = await this.routes.getAvailability({ employee_ids, days_ago: opts.days_ago, date: opts.date }, opts.request);
+        if (out.value === undefined)
+            throw errResolveFailed({
+                resource: RoutesResource.ClientAvailabilities,
+                msg: msgAvailabilityMissing,
+            });
+        return out.value;
+    }
+    async prepareRoute(opts) {
+        requireRoutes(routeCanPlan(opts.actor), msgAccess);
+        const input = routeInput(opts.in);
+        validateRouteInput(input);
+        const availability = await this.availability({
+            actor: opts.actor,
+            employee_ids: input.vehicles.flatMap((vehicle) => vehicle.employee_ids),
+            days_ago: opts.days_ago,
+            date: input.from,
+            request: opts.request,
+        });
+        validateRouteInput(input, availability);
+        return { in: input, availability };
+    }
+    async designations(opts) {
+        requireRoutes(!!resolvedID(opts.actor.owner_id) &&
+            (opts.actor.active_mode === UserTypeEmployee ||
+                opts.actor.active_mode === UserTypeClient), msgAccess);
+        const employer_id = resolvedID(opts.employer_id);
+        requireRoutes(employer_id, msgOwner);
+        requireRoutes(isValidInputDate(opts.date), msgDate);
+        // The server derives the viewer from authentication. There is no viewer
+        // ID override in this payload; date means this day onward, not one day.
+        const out = await this.routes.getDesignation({ employer_id, date: opts.date }, opts.request);
+        if (out.value === undefined)
+            throw errResolveFailed({
+                resource: RoutesResource.Routes,
+                msg: msgDesignationMissing,
+            });
+        return out.value;
+    }
+    async clientAvailabilities(opts) {
+        requireRoutes(!!resolvedID(opts.actor.owner_id) &&
+            opts.actor.active_mode === UserTypeClient, msgAccess);
+        const out = await this.routes.queryClientAvailabilities({
+            signal: opts.signal,
+            query: queryParams({
+                owner_id: opts.actor.owner_id,
+                employer_id: optionalIDs(opts.employer_ids),
+                location_id: optionalIDs(opts.location_ids),
+                timezone: opts.timezone,
+            }),
+        });
+        return out.value ?? [];
+    }
+    async tracking(opts) {
+        requireRoutes(routeCanRead(opts.actor, opts.route) &&
+            opts.actor.active_mode !== UserTypeClient, msgAccess);
+        const out = await this.routes.queryTracking({
+            signal: opts.signal,
+            query: queryParams({
+                owner_id: opts.route.owner_id,
+                route_id: opts.route.id,
+                employee_id: opts.actor.active_mode === UserTypeEmployee
+                    ? opts.actor.owner_id
+                    : optionalIDs(opts.employee_ids),
+                vehicle_id: optionalIDs(opts.vehicle_ids),
+            }),
+        });
+        return out.value ?? [];
+    }
+}
+function routeReadOwner(actor, employer_id) {
+    requireRoutes(resolvedID(actor.owner_id), msgAccess);
+    if (routeCanPlan(actor)) {
+        requireRoutes(employer_id === undefined || resolvedID(employer_id) === actor.owner_id, msgAccess);
+        return actor.owner_id;
+    }
+    requireRoutes(actor.active_mode === UserTypeEmployee ||
+        actor.active_mode === UserTypeClient, msgAccess);
+    const owner_id = resolvedID(employer_id);
+    requireRoutes(owner_id, msgOwner);
+    return owner_id;
+}
+function optionalIDs(values) {
+    if (values === undefined)
+        return undefined;
+    const ids = normalizeIDs(values);
+    return ids.length ? ids : undefined;
+}
+function requireRoutes(value, msg) {
+    if (!value)
+        throw errValidation({ msg });
+}

package/dist/src/timesheets/timesheets.d.ts

@@ -1,6 +1,7 @@
 import { type Date as SchemaDate, type OperationResult, type Summary, type WeekSheet } from "@fabriktor/schema";
 import type { BillableOperator, TimesheetsOperator } from "@fabriktor/client";
 import type { ContactsFXOperator } from "../contacts/contacts.js";
+import type { NowProvider } from "../core/server-clock.js";
 import type { MultiCreateAttempt } from "../core/multi-create.js";
 import { type LoadTimesheetsReadContextOptions, type QueryTimesheetSyncDestinationsOptions, type QueryTimesheetSyncSourcesOptions, type TimesheetsReadContext, type TimesheetsReadOptions, type TimesheetSyncTarget } from "./access.js";
 import { TimesheetsWorkspace } from "./workspace.js";
@@ -13,7 +14,7 @@ export type TimesheetsFXOptions = {
     timesheets: TimesheetsOperator;
     contacts_fx: ContactsFXOperator;
     billable?: BillableOperator;
-    now?: () => globalThis.Date;
+    now?: NowProvider;
 };
 export type PunchContext = Pick<PunchPayload, "timezone" | "location_id" | "employer_id">;
 export type PunchInOptions = PunchContext & {
@@ -55,6 +56,7 @@ export type PunchControls = {
     can_punch_out: boolean;
     can_ride_in: boolean;
     can_ride_out: boolean;
+    can_start_transport: boolean;
 };
 export type SyncWeekOptions = {
     from: WeekSheet;

package/dist/src/timesheets/timesheets.js

@@ -129,6 +129,7 @@ export class TimesheetsFX {
             can_punch_out: true,
             can_ride_in: !ride_active,
             can_ride_out: ride_active,
+            can_start_transport: !ride_active,
         };
     }
     async punchIn(opts) {
@@ -454,6 +455,7 @@ function disabledPunchControls() {
         can_punch_out: false,
         can_ride_in: false,
         can_ride_out: false,
+        can_start_transport: false,
     };
 }
 function readyToPunchInControls() {
@@ -462,6 +464,7 @@ function readyToPunchInControls() {
         can_punch_out: false,
         can_ride_in: false,
         can_ride_out: false,
+        can_start_transport: true,
     };
 }
 function cloneDate(v) {

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

@@ -1,5 +1,6 @@
 import { type BillableOperator, type TimesheetsOperator } from "@fabriktor/client";
 import { PunchTypeIn, PunchTypeOut, PunchTypeRideIn, PunchTypeRideOut, type InDate, type Punch, type Summary, type WeekSheet } from "@fabriktor/schema";
+import type { NowProvider } from "../core/server-clock.js";
 import type { TimesheetsFXOperator } from "./timesheets.js";
 export type TimesheetFilters = {
     owner_ids?: WeekSheet["owner_id"][];
@@ -24,12 +25,14 @@ export type TimesheetPunchState = {
 };
 export type TimesheetPunchAction = typeof PunchTypeIn | typeof PunchTypeOut | typeof PunchTypeRideIn | typeof PunchTypeRideOut;
 export type CheckedPunchOptions = PunchStateOptions & {
+    before_request?: () => void;
     location_id: string;
     action: TimesheetPunchAction;
     expected: TimesheetPunchState;
     total_pause_minutes?: number;
     total_meal_minutes?: number;
 };
+export type StartTimesheetTransportOptions = Omit<CheckedPunchOptions, "action" | "total_pause_minutes" | "total_meal_minutes">;
 export type SaveTimesheetDayOptions = PunchStateOptions & {
     location_id: string;
     start: InDate;
@@ -39,6 +42,7 @@ export type SaveTimesheetDayOptions = PunchStateOptions & {
     replace?: WeekSheet;
 };
 export declare const TimesheetsBlock: {
+    readonly Busy: "timesheets_busy";
     readonly Changed: "timesheets_changed";
     readonly Locked: "timesheets_locked";
     readonly Active: "timesheets_active";
@@ -59,7 +63,8 @@ export declare class TimesheetsWorkspace {
     private readonly actions;
     private readonly billable?;
     private readonly now;
-    constructor(client: TimesheetsOperator, actions: TimesheetsFXOperator, billable?: BillableOperator | undefined, now?: () => Date);
+    private punchPending;
+    constructor(client: TimesheetsOperator, actions: TimesheetsFXOperator, billable?: BillableOperator | undefined, now?: NowProvider);
     weeks(opts: TimesheetFilters): Promise<WeekSheet[]>;
     summaries(opts: TimesheetFilters): Promise<Summary[]>;
     week(id: string, signal?: AbortSignal): Promise<WeekSheet>;
@@ -67,6 +72,9 @@ export declare class TimesheetsWorkspace {
     periods(employer_id: string, start: InDate, end?: InDate): Promise<number[]>;
     punchState(opts: PunchStateOptions): Promise<TimesheetPunchState>;
     punch(opts: CheckedPunchOptions): Promise<WeekSheet>;
+    startTransport(opts: StartTimesheetTransportOptions): Promise<WeekSheet>;
+    private withPunch;
+    private performPunch;
     saveDay(opts: SaveTimesheetDayOptions): Promise<WeekSheet>;
     removeDay(owner_id: string, expected: WeekSheet, date: InDate): Promise<void>;
     removeWeek(actor_id: string, expected: WeekSheet): Promise<void>;

package/dist/src/timesheets/workspace.js

@@ -5,6 +5,7 @@ import { errRequired } from "../core/err.js";
 import { PreActionBlocked } from "../core/pre-action.js";
 import { queryRecordParams, runOwnerScopeQuery, } from "../core/query.js";
 export const TimesheetsBlock = {
+    Busy: "timesheets_busy",
     Changed: "timesheets_changed",
     Locked: "timesheets_locked",
     Active: "timesheets_active",
@@ -74,6 +75,7 @@ export class TimesheetsWorkspace {
     actions;
     billable;
     now;
+    punchPending = false;
     constructor(client, actions, billable, now = () => new Date()) {
         this.client = client;
         this.actions = actions;
@@ -109,7 +111,7 @@ export class TimesheetsWorkspace {
     }
     async punchState(opts) {
         requireState(!!opts.owner_id && !!opts.timezone, TimesheetsBlock.InvalidDay);
-        const today = opts.date ?? inDateAtTimestamp(this.now().toISOString(), opts.timezone);
+        const today = opts.date ?? inDateAtTimestamp((await this.now()).toISOString(), opts.timezone);
         const week_day = timesheetWeekDay(today);
         // Check every open work punch, including other employers/locations/weeks.
         // A scope selection must never hide an already open shift.
@@ -124,7 +126,7 @@ export class TimesheetsWorkspace {
         requireState(open.length <= 1, TimesheetsBlock.Active);
         if (open[0]) {
             const current = open[0];
-            const date = inDateAtTimestamp(this.now().toISOString(), current.punch.timezone);
+            const date = inDateAtTimestamp((await this.now()).toISOString(), current.punch.timezone);
             return {
                 ...current,
                 stale_day: !sameDay(current.punch.punch_in_time, opts.date ?? date),
@@ -146,8 +148,47 @@ export class TimesheetsWorkspace {
         return { week_sheet, punch, week_day, stale_day: false };
     }
     async punch(opts) {
+        return await this.withPunch(() => this.performPunch(opts));
+    }
+    // A trip belongs to its destination's work session. Keep both steps ordered
+    // and validate the acknowledged work state before starting its transport.
+    // Never retry or roll back a punch automatically after an uncertain response.
+    async startTransport(opts) {
+        return await this.withPunch(async () => {
+            let expected = opts.expected;
+            if (expected.punch?.punch_status !== PunchStatusWorking) {
+                const week_sheet = await this.performPunch({
+                    ...opts,
+                    action: PunchTypeIn,
+                });
+                const week_day = expected.week_day;
+                const punch = week_sheet.sheets
+                    .find((day) => day.week_day === week_day)
+                    ?.punches.at(-1);
+                expected = { week_sheet, punch, week_day, stale_day: false };
+            }
+            return await this.performPunch({
+                ...opts,
+                expected,
+                action: PunchTypeRideIn,
+            });
+        });
+    }
+    // The existing FX request guard protects individual writes. This guard also
+    // keeps other checked punch actions out of the gap between these two steps.
+    async withPunch(fn) {
+        requireState(!this.punchPending, TimesheetsBlock.Busy);
+        this.punchPending = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this.punchPending = false;
+        }
+    }
+    async performPunch(opts) {
         if (opts.date)
-            this.validateDay(opts.date, opts.timezone);
+            await this.validateDay(opts.date, opts.timezone);
         const current = await this.punchState(opts);
         requireState(timesheetStateKey(current) === timesheetStateKey(opts.expected), TimesheetsBlock.Changed);
         requireState(!current.stale_day, TimesheetsBlock.InvalidDay);
@@ -169,6 +210,7 @@ export class TimesheetsWorkspace {
             requireState(sameDay(opts.date, current.punch.punch_in_time) &&
                 wallTime(opts.date) >= wallTime(current.punch.punch_in_time), TimesheetsBlock.InvalidDay);
         }
+        opts.before_request?.();
         const context = {
             employer_id: opts.employer_id,
             location_id: opts.location_id,
@@ -204,8 +246,8 @@ export class TimesheetsWorkspace {
         return sheet;
     }
     async saveDay(opts) {
-        this.validateDay(opts.start, opts.timezone);
-        this.validateDay(opts.end, opts.timezone);
+        await this.validateDay(opts.start, opts.timezone);
+        await this.validateDay(opts.end, opts.timezone);
         requireState(sameDay(opts.start, opts.end) &&
             wallTime(opts.end) > wallTime(opts.start), TimesheetsBlock.InvalidDay);
         const indexes = await this.periods(opts.employer_id, opts.start);
@@ -267,7 +309,7 @@ export class TimesheetsWorkspace {
         await this.client.deleteOneWeekSheet({ id: sheet.id });
     }
     async blankWeek(opts) {
-        this.validateDay(opts.date, opts.timezone);
+        await this.validateDay(opts.date, opts.timezone);
         const indexes = await this.periods(opts.employer_id, opts.date);
         const matches = await this.weeks({
             owner_ids: [opts.owner_id],
@@ -304,8 +346,8 @@ export class TimesheetsWorkspace {
         requireState(timesheetIsMutable(sheet), TimesheetsBlock.Locked);
         return sheet;
     }
-    validateDay(date, timezone) {
-        const now = inDateAtTimestamp(this.now().toISOString(), timezone);
+    async validateDay(date, timezone) {
+        const now = inDateAtTimestamp((await this.now()).toISOString(), timezone);
         const calendar = new Date(Date.UTC(date.y, date.m - 1, date.d));
         requireState(!!now &&
             date.tz === timezone &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.139",
+  "version": "0.0.141",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,8 +17,9 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.97",
+    "@fabriktor/client": "0.0.98",
     "@fabriktor/fx": "0.0.94",
-    "@fabriktor/schema": "0.0.68"
+    "@fabriktor/schema": "0.0.68",
+    "convert": "8.0.2"
   }
 }