@fabriktor/fx 0.0.32 → 0.0.33

package/dist/src/timesheets/timesheets.js

@@ -0,0 +1,407 @@
+// 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 { PunchModeDefault, PunchModeDelete, PunchModeReplace, PunchModeWeekSheet, PunchStatusPending, PunchStatusWorking, PunchTypeIn, PunchTypeOut, PunchTypeRideIn, PunchTypeRideOut, ZeroID, } from "@fabriktor/schema";
+import { errRequired, errValidation } from "../core/err.js";
+const allWeekDays = [0, 1, 2, 3, 4, 5, 6];
+const minuteStep = 15;
+const msgPunchInProgress = "A punch action is already in progress.";
+const msgTimezoneRequired = "Timezone is required.";
+const msgLocationIDRequired = "Location ID is required.";
+const msgEmployerIDRequired = "Employer ID is required.";
+const msgWeekSheetIDRequired = "Week sheet ID is required.";
+const msgWeekSheetsRequired = "At least one week sheet is required.";
+const msgDestinationWeekSheetsRequired = "At least one destination week sheet is required.";
+const msgDaysRequired = "At least one week day is required.";
+const msgWeekDayInvalid = "Week day must be an integer between 0 and 6.";
+const msgMinutesInvalid = "Pause and meal minutes must be non-negative 15-minute increments.";
+const msgWeekSheetArchived = "Archived week sheets cannot be modified or approved.";
+const msgWeekSheetEmployerMismatch = "Week sheet employer does not match the requested employer.";
+const msgPunchNotPending = "All punches must be pending before the week sheet can be approved.";
+const msgSyncEmployerMismatch = "Source and destination week sheets must belong to the same employer.";
+export class TimesheetsFX {
+    timesheets;
+    punch_in_progress;
+    constructor(opts) {
+        this.timesheets = opts.timesheets;
+        this.punch_in_progress = false;
+    }
+    punchControls(opts) {
+        validateWeekDay(opts.week_day, "week_day");
+        if (opts.week_sheet?.is_archived) {
+            return disabledPunchControls();
+        }
+        const day = opts.week_sheet?.sheets.find((sheet) => sheet.week_day === opts.week_day);
+        const latest_punch = day?.punches.at(-1);
+        if (latest_punch === undefined) {
+            return readyToPunchInControls();
+        }
+        if (latest_punch.punch_status !== PunchStatusWorking) {
+            return readyToPunchInControls();
+        }
+        const latest_ride = latest_punch.rides.at(-1);
+        const ride_active = latest_ride?.is_active === true;
+        return {
+            can_punch_in: false,
+            can_punch_out: true,
+            can_ride_in: !ride_active,
+            can_ride_out: ride_active,
+        };
+    }
+    async punchIn(opts) {
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeIn,
+                punch_mode: PunchModeDefault,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async punchOut(opts) {
+        validateMinutes(opts.total_pause_minutes, "total_pause_minutes");
+        validateMinutes(opts.total_meal_minutes, "total_meal_minutes");
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeOut,
+                punch_mode: PunchModeDefault,
+                punch_status: PunchStatusPending,
+                total_pause_minutes: opts.total_pause_minutes,
+                total_meal_minutes: opts.total_meal_minutes,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async rideIn(opts) {
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeRideIn,
+                punch_mode: PunchModeDefault,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async rideOut(opts) {
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeRideOut,
+                punch_mode: PunchModeDefault,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async replaceDay(opts) {
+        validateMinutes(opts.total_pause_minutes, "total_pause_minutes");
+        validateMinutes(opts.total_meal_minutes, "total_meal_minutes");
+        return await this.runPunch(async () => {
+            const punch_in = await this.timesheets.punch(buildPunch({
+                context: opts,
+                punch_type: PunchTypeIn,
+                punch_mode: PunchModeReplace,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.punch_in_date,
+            }));
+            const punch_out = await this.timesheets.punch(buildPunch({
+                context: opts,
+                punch_type: PunchTypeOut,
+                punch_mode: PunchModeDefault,
+                punch_status: PunchStatusPending,
+                total_pause_minutes: opts.total_pause_minutes,
+                total_meal_minutes: opts.total_meal_minutes,
+                explicit_date: opts.punch_out_date,
+            }));
+            return {
+                punch_in,
+                punch_out,
+            };
+        });
+    }
+    async deleteDay(opts) {
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeIn,
+                punch_mode: PunchModeDelete,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async createBlankWeekSheet(opts) {
+        return await this.runPunch(async () => {
+            const input = buildPunch({
+                context: opts,
+                punch_type: PunchTypeIn,
+                punch_mode: PunchModeWeekSheet,
+                punch_status: PunchStatusWorking,
+                total_pause_minutes: 0,
+                total_meal_minutes: 0,
+                explicit_date: opts.explicit_date,
+            });
+            return await this.timesheets.punch(input);
+        });
+    }
+    async syncWeek(opts) {
+        await this.syncSheets({
+            from: opts.from,
+            to: opts.to,
+            days: [...allWeekDays],
+        });
+    }
+    async syncDays(opts) {
+        const days = normalizeDays(opts.days);
+        if (days.length === 0) {
+            throw errRequired({
+                field: "days",
+                msg: msgDaysRequired,
+            });
+        }
+        await this.syncSheets({
+            from: opts.from,
+            to: opts.to,
+            days,
+        });
+    }
+    async approveWeekSheets(opts) {
+        const employer_id = requiredID(opts.employer_id, "employer_id", msgEmployerIDRequired);
+        if (opts.week_sheets.length === 0) {
+            throw errRequired({
+                field: "week_sheets",
+                msg: msgWeekSheetsRequired,
+            });
+        }
+        const ids = [];
+        for (const week_sheet of opts.week_sheets) {
+            const id = requiredID(week_sheet.id, "week_sheets", msgWeekSheetIDRequired);
+            if (week_sheet.employer_id !== employer_id) {
+                throw errValidation({
+                    field: "week_sheets",
+                    msg: msgWeekSheetEmployerMismatch,
+                });
+            }
+            if (week_sheet.is_archived) {
+                throw errValidation({
+                    field: "week_sheets",
+                    msg: msgWeekSheetArchived,
+                });
+            }
+            for (const sheet of week_sheet.sheets) {
+                for (const punch of sheet.punches) {
+                    if (punch.punch_status !== PunchStatusPending) {
+                        throw errValidation({
+                            field: "week_sheets",
+                            msg: msgPunchNotPending,
+                        });
+                    }
+                }
+            }
+            ids.push(id);
+        }
+        const input = {
+            ids: normalizeIDs(ids),
+            employer_id,
+        };
+        await this.timesheets.approve(input);
+    }
+    async syncSheets(opts) {
+        const from_id = requiredID(opts.from.id, "from", msgWeekSheetIDRequired);
+        if (opts.to.length === 0) {
+            throw errRequired({
+                field: "to",
+                msg: msgDestinationWeekSheetsRequired,
+            });
+        }
+        const to_ids = [];
+        for (const week_sheet of opts.to) {
+            const id = requiredID(week_sheet.id, "to", msgWeekSheetIDRequired);
+            if (week_sheet.is_archived) {
+                throw errValidation({
+                    field: "to",
+                    msg: msgWeekSheetArchived,
+                });
+            }
+            if (week_sheet.employer_id !== opts.from.employer_id) {
+                throw errValidation({
+                    field: "to",
+                    msg: msgSyncEmployerMismatch,
+                });
+            }
+            to_ids.push(id);
+        }
+        const input = {
+            from_id,
+            to_ids: normalizeIDs(to_ids),
+            days: normalizeDays(opts.days),
+        };
+        await this.timesheets.sync(input);
+    }
+    async runPunch(fn) {
+        if (this.punch_in_progress) {
+            throw errValidation({
+                field: "punch_in_progress",
+                msg: msgPunchInProgress,
+            });
+        }
+        this.punch_in_progress = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this.punch_in_progress = false;
+        }
+    }
+}
+export function newTimesheetsFX(opts) {
+    return new TimesheetsFX(opts);
+}
+function buildPunch(opts) {
+    const context = normalizePunchContext(opts.context);
+    return {
+        punch_in_time: zeroDate(),
+        punch_out_time: zeroDate(),
+        rides: [],
+        punch_status: opts.punch_status,
+        work_hours: 0,
+        ride_hours: 0,
+        owner_id: ZeroID,
+        timezone: context.timezone,
+        punch_type: opts.punch_type,
+        punch_mode: opts.punch_mode,
+        location_id: context.location_id,
+        employer_id: context.employer_id,
+        total_pause_minutes: opts.total_pause_minutes,
+        total_meal_minutes: opts.total_meal_minutes,
+        is_explicit: opts.explicit_date !== undefined,
+        explicit_date: opts.explicit_date === undefined
+            ? zeroDate()
+            : cloneDate(opts.explicit_date),
+    };
+}
+function normalizePunchContext(opts) {
+    return {
+        timezone: requiredText(opts.timezone, "timezone", msgTimezoneRequired),
+        location_id: requiredID(opts.location_id, "location_id", msgLocationIDRequired),
+        employer_id: requiredID(opts.employer_id, "employer_id", msgEmployerIDRequired),
+    };
+}
+function disabledPunchControls() {
+    return {
+        can_punch_in: false,
+        can_punch_out: false,
+        can_ride_in: false,
+        can_ride_out: false,
+    };
+}
+function readyToPunchInControls() {
+    return {
+        can_punch_in: true,
+        can_punch_out: false,
+        can_ride_in: false,
+        can_ride_out: false,
+    };
+}
+function zeroDate() {
+    return {
+        utc: "",
+        y: 0,
+        m: 0,
+        d: 0,
+        h: 0,
+        min: 0,
+        tz: "",
+    };
+}
+function cloneDate(v) {
+    return {
+        utc: v.utc,
+        y: v.y,
+        m: v.m,
+        d: v.d,
+        h: v.h,
+        min: v.min,
+        tz: v.tz,
+    };
+}
+function validateMinutes(v, field) {
+    if (!Number.isFinite(v) ||
+        v < 0 ||
+        !Number.isInteger(v) ||
+        v % minuteStep !== 0) {
+        throw errValidation({
+            field,
+            msg: msgMinutesInvalid,
+        });
+    }
+}
+function validateWeekDay(v, field) {
+    if (!Number.isInteger(v) || v < 0 || v > 6) {
+        throw errValidation({
+            field,
+            msg: msgWeekDayInvalid,
+        });
+    }
+}
+function normalizeDays(days) {
+    const out = new Set();
+    for (const day of days) {
+        validateWeekDay(day, "days");
+        out.add(day);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+function requiredID(v, field, msg) {
+    const out = v?.trim();
+    if (out === undefined || out === "" || out === ZeroID) {
+        throw errRequired({
+            field,
+            msg,
+        });
+    }
+    return out;
+}
+function requiredText(v, field, msg) {
+    const out = v?.trim();
+    if (out === undefined || out === "") {
+        throw errRequired({
+            field,
+            msg,
+        });
+    }
+    return out;
+}
+function normalizeIDs(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of ids) {
+        const id = raw.trim();
+        if (id === "" || id === ZeroID || seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}

package/dist/src/users/users.d.ts

@@ -1,26 +1,30 @@
-import type { PLUsersResolveUsername, PLUsersSendCode, PLUsersUsername, PLUsersVerifyCode } from "@fabriktor/schema";
 import type { OperationResultOf, TmpPhonesOperator, TmpUsernamesOperator, UsernameVerification, UsersOperator } from "@fabriktor/client";
+export type ResolveUsernameOptions = Parameters<UsersOperator["resolveUsername"]>[0];
+export type VerifyUsernameOptions = Parameters<TmpUsernamesOperator["verify"]>[0];
+export type GenerateUsernamesOptions = VerifyUsernameOptions;
+export type SendPhoneCodeOptions = Parameters<TmpPhonesOperator["send"]>[0];
+export type VerifyPhoneCodeOptions = Parameters<TmpPhonesOperator["verify"]>[0];
 export type UsersFXOptions = {
     users: UsersOperator;
     tmp_usernames: TmpUsernamesOperator;
     tmp_phones: TmpPhonesOperator;
 };
 export interface UsersFXOperator {
-    resolveUsername(opts: PLUsersResolveUsername): Promise<string>;
-    verifyUsername(opts: PLUsersUsername): Promise<OperationResultOf<UsernameVerification>>;
-    generateUsernames(opts: PLUsersUsername): Promise<OperationResultOf<UsernameVerification>>;
-    sendPhoneCode(opts: PLUsersSendCode): Promise<void>;
-    verifyPhoneCode(opts: PLUsersVerifyCode): Promise<void>;
+    resolveUsername(opts: ResolveUsernameOptions): Promise<string>;
+    verifyUsername(opts: VerifyUsernameOptions): Promise<OperationResultOf<UsernameVerification>>;
+    generateUsernames(opts: GenerateUsernamesOptions): Promise<OperationResultOf<UsernameVerification>>;
+    sendPhoneCode(opts: SendPhoneCodeOptions): Promise<void>;
+    verifyPhoneCode(opts: VerifyPhoneCodeOptions): Promise<void>;
 }
 export declare class UsersFX implements UsersFXOperator {
     private users;
     private tmp_usernames;
     private tmp_phones;
     constructor(opts: UsersFXOptions);
-    resolveUsername(opts: PLUsersResolveUsername): Promise<string>;
-    verifyUsername(opts: PLUsersUsername): Promise<OperationResultOf<UsernameVerification>>;
-    generateUsernames(opts: PLUsersUsername): Promise<OperationResultOf<UsernameVerification>>;
-    sendPhoneCode(opts: PLUsersSendCode): Promise<void>;
-    verifyPhoneCode(opts: PLUsersVerifyCode): Promise<void>;
+    resolveUsername(opts: ResolveUsernameOptions): Promise<string>;
+    verifyUsername(opts: VerifyUsernameOptions): Promise<OperationResultOf<UsernameVerification>>;
+    generateUsernames(opts: GenerateUsernamesOptions): Promise<OperationResultOf<UsernameVerification>>;
+    sendPhoneCode(opts: SendPhoneCodeOptions): Promise<void>;
+    verifyPhoneCode(opts: VerifyPhoneCodeOptions): Promise<void>;
 }
 export declare function newUsersFX(opts: UsersFXOptions): UsersFX;

package/dist/src/users/users.js

@@ -52,7 +52,7 @@ export class UsersFX {
         if (!validatePhone(phone)) {
             throw errPhoneRequired("phone");
         }
-        return await this.tmp_phones.send({
+        await this.tmp_phones.send({
             phone,
         });
     }
@@ -65,7 +65,7 @@ export class UsersFX {
         if (!validatePhoneCode(code)) {
             throw errPhoneCodeRequired("code");
         }
-        return await this.tmp_phones.verify({
+        await this.tmp_phones.verify({
             phone,
             code,
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.38",
-    "@fabriktor/schema": "0.0.29"
+    "@fabriktor/client": "0.0.42",
+    "@fabriktor/schema": "0.0.31"
   }
 }