@lilaquadrat/studio 13.0.1 → 13.1.0

package/lib/src/services/timeTrackingProjectAllocations.service.js

@@ -0,0 +1,85 @@
+import Immutable from '../Immutable.class.js';
+import ImmutableError from '../classes/errors/Immutable.error.js';
+import TimeTrackingProjectAllocationModel from '../models/timeTrackingProjectAllocation.model.js';
+import TimeTrackingProjectModel from '../models/timeTrackingProject.model.js';
+/** An allocation is one person's hour budget inside a category: plan > category > allocation. */
+export class TimeTrackingProjectAllocationsService extends Immutable {
+    constructor() {
+        super(...arguments);
+        this.model = TimeTrackingProjectAllocationModel;
+    }
+    singleTimeTrackingProjectAllocation(id, options) {
+        return this.model.db.findOne({ _id: id, company: options.company, project: options.project }, { projection: { history: 0 } });
+    }
+    listTimeTrackingProjectAllocations(timeTrackingProject, category, options) {
+        const query = {
+            company: options.company,
+            project: options.project,
+            timeTrackingProject,
+        };
+        if (category)
+            query.category = category;
+        return this.model.db.find(query, { projection: { history: 0 } }).sort({ user: 1 }).toArray();
+    }
+    /** Resolve the category inside the plan so allocation hours can be measured against its budget. */
+    async categoryBudget(timeTrackingProject, category, options) {
+        const project = await TimeTrackingProjectModel.db.findOne({
+            id: timeTrackingProject,
+            company: options.company,
+            project: options.project,
+        });
+        if (!project)
+            throw new ImmutableError('TIME_TRACKING_PROJECT_NOT_FOUND');
+        // a plan without categories books on shifts, where a category allocation has no budget to hold
+        const found = project.categories?.find((single) => single.id === category);
+        if (!found)
+            throw new ImmutableError('TIME_TRACKING_CATEGORY_NOT_FOUND');
+        return found;
+    }
+    /** The sum of a category's allocations may not exceed the category budget it was granted in the plan. */
+    async assertCategoryBudget(timeTrackingProject, category, hours, options, exclude) {
+        const budget = await this.categoryBudget(timeTrackingProject, category, options);
+        const query = {
+            company: options.company,
+            project: options.project,
+            timeTrackingProject,
+            category,
+        };
+        if (exclude)
+            query._id = { $ne: exclude };
+        const existing = await this.model.db.find(query).toArray();
+        // an allocation without hours has no personal limit and contributes nothing to the category budget
+        const used = existing.reduce((total, single) => total + (single.hours ?? 0), 0);
+        // a category without a maximum hours budget is unbounded
+        if (budget.maximumHours !== undefined && used + (hours ?? 0) > budget.maximumHours)
+            throw new ImmutableError('TIME_TRACKING_ALLOCATION_HOURS_EXCEEDED');
+    }
+    async createTimeTrackingProjectAllocation(input, options) {
+        await this.assertCategoryBudget(input.timeTrackingProject, input.category, input.hours, options);
+        const created = await this.create({ ...input, company: options.company, project: options.project }, options.user, options.app);
+        return (await this.singleTimeTrackingProjectAllocation(created._id, options));
+    }
+    async changeTimeTrackingProjectAllocation(id, input, options) {
+        const existing = await this.singleTimeTrackingProjectAllocation(id, options);
+        if (!existing)
+            throw new ImmutableError('TIME_TRACKING_ALLOCATION_NOT_FOUND');
+        await this.assertCategoryBudget(existing.timeTrackingProject, existing.category, input.hours ?? 0, options, id);
+        const filter = { _id: id, company: options.company, project: options.project };
+        if (input.hours === null) {
+            // `null` passes the change schema, options.unset then removes the field instead of storing it
+            await this.immutable(filter, { hours: input.hours }, options.user, 'change', options.app, undefined, undefined, undefined, { unset: ['hours'] });
+        }
+        else {
+            await this.immutable(filter, { hours: input.hours }, options.user, 'change', options.app);
+        }
+        return (await this.singleTimeTrackingProjectAllocation(id, options));
+    }
+    async removeTimeTrackingProjectAllocation(id, options) {
+        const existing = await this.singleTimeTrackingProjectAllocation(id, options);
+        if (!existing)
+            throw new ImmutableError('TIME_TRACKING_ALLOCATION_NOT_FOUND');
+        await this.delete(id, options.user, options.app);
+    }
+}
+export default new TimeTrackingProjectAllocationsService();
+//# sourceMappingURL=timeTrackingProjectAllocations.service.js.map

package/lib/src/services/timeTrackingProjectAllocations.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeTrackingProjectAllocations.service.js","sourceRoot":"","sources":["../../../src/services/timeTrackingProjectAllocations.service.ts"],"names":[],"mappings":"AAEA,OAAO,SAAS,MAAM,uBAAuB,CAAC;AAC9C,OAAO,cAAc,MAAM,sCAAsC,CAAC;AAClE,OAAO,kCAAkC,MAAM,kDAAkD,CAAC;AAClG,OAAO,wBAAwB,MAAM,wCAAwC,CAAC;AAE9E,iGAAiG;AACjG,MAAM,OAAO,qCAAsC,SAAQ,SAAwC;IAAnG;;QAEE,UAAK,GAAG,kCAAkC,CAAC;IA+H7C,CAAC;IA7HC,mCAAmC,CAAC,EAAY,EAAE,OAA+B;QAE/E,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAC1B,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAC/D,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAC/B,CAAC;IAEJ,CAAC;IAED,kCAAkC,CAAC,mBAA2B,EAAE,QAA4B,EAAE,OAA+B;QAE3H,MAAM,KAAK,GAA0C;YACnD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,mBAAmB;SACpB,CAAC;QACF,IAAI,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAExC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IAE/F,CAAC;IAED,mGAAmG;IAC3F,KAAK,CAAC,cAAc,CAAC,mBAA2B,EAAE,QAAgB,EAAE,OAA+B;QAEzG,MAAM,OAAO,GAAG,MAAM,wBAAwB,CAAC,EAAE,CAAC,OAAO,CAAC;YACxD,EAAE,EAAE,mBAAmB;YACvB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QACH,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,cAAc,CAAC,iCAAiC,CAAC,CAAC;QAE1E,+FAA+F;QAC/F,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;QAC3E,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,cAAc,CAAC,kCAAkC,CAAC,CAAC;QAEzE,OAAO,KAAK,CAAC;IAEf,CAAC;IAED,yGAAyG;IACjG,KAAK,CAAC,oBAAoB,CAAC,mBAA2B,EAAE,QAAgB,EAAE,KAAgC,EAAE,OAA+B,EAAE,OAAkB;QAErK,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,mBAAmB,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAEjF,MAAM,KAAK,GAA0C;YACnD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,mBAAmB;YACnB,QAAQ;SACT,CAAC;QACF,IAAI,OAAO;YAAE,KAAK,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QAE1C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAC3D,mGAAmG;QACnG,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAEhF,yDAAyD;QACzD,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,YAAY;YAAE,MAAM,IAAI,cAAc,CAAC,yCAAyC,CAAC,CAAC;IAE1J,CAAC;IAED,KAAK,CAAC,mCAAmC,CAAC,KAAyC,EAAE,OAA+B;QAElH,MAAM,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,mBAAmB,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAEjG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAC/B,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAChE,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,GAAG,CACZ,CAAC;QAEF,OAAO,CAAC,MAAM,IAAI,CAAC,mCAAmC,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAE,CAAC;IAEjF,CAAC;IAED,KAAK,CAAC,mCAAmC,CAAC,EAAY,EAAE,KAA+B,EAAE,OAA+B;QAEtH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,mCAAmC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,cAAc,CAAC,oCAAoC,CAAC,CAAC;QAE9E,MAAM,IAAI,CAAC,oBAAoB,CAAC,QAAQ,CAAC,mBAAmB,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;QAEhH,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAE/E,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YAEzB,8FAA8F;YAC9F,MAAM,IAAI,CAAC,SAAS,CAClB,MAAM,EACN,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAuD,EAC3E,OAAO,CAAC,IAAI,EACZ,QAAQ,EACR,OAAO,CAAC,GAAG,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,EAAE,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CACrB,CAAC;QAEJ,CAAC;aAAM,CAAC;YAEN,MAAM,IAAI,CAAC,SAAS,CAClB,MAAM,EACN,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EACtB,OAAO,CAAC,IAAI,EACZ,QAAQ,EACR,OAAO,CAAC,GAAG,CACZ,CAAC;QAEJ,CAAC;QAED,OAAO,CAAC,MAAM,IAAI,CAAC,mCAAmC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAE,CAAC;IAExE,CAAC;IAED,KAAK,CAAC,mCAAmC,CAAC,EAAY,EAAE,OAA+B;QAErF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,mCAAmC,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,cAAc,CAAC,oCAAoC,CAAC,CAAC;QAE9E,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAEnD,CAAC;CAEF;AAED,eAAe,IAAI,qCAAqC,EAAE,CAAC"}

package/lib/src/services/timeTrackingProjects.service.d.ts

@@ -0,0 +1,18 @@
+import type { TimeTrackingProject, TimeTrackingProjectInput, UserAppOptionsRequired } from '@lilaquadrat/interfaces';
+import Immutable from '../Immutable.class.js';
+/** Time-tracking projects group tracked time and cap it through maximumHours. Distinct from the content project model. */
+export declare class TimeTrackingProjectsService extends Immutable<TimeTrackingProject> {
+    model: import("../classes/modelv2.class.js").default<TimeTrackingProject, string>;
+    /** Categories partition the plan's budget: their ids must be unique and their total must not exceed the plan maximum (when one is set). */
+    private assertCategories;
+    /** A plan is shift-based when it tracks on shifts and links a shift plan; only then may it skip categories. */
+    private assertCategoryRequired;
+    /** Only a shifts project may reference a plan: other modes clear the link, and shifts must point at an existing plan in this project. */
+    private normalizeShiftPlan;
+    singleTimeTrackingProject(id: string, options: UserAppOptionsRequired): Promise<import("mongodb").WithId<TimeTrackingProject> | null>;
+    createTimeTrackingProject(input: TimeTrackingProjectInput, options: UserAppOptionsRequired): Promise<import("mongodb").WithId<TimeTrackingProject>>;
+    changeTimeTrackingProject(id: string, input: Omit<TimeTrackingProjectInput, 'id'>, options: UserAppOptionsRequired): Promise<import("mongodb").WithId<TimeTrackingProject>>;
+    removeTimeTrackingProject(id: string, options: UserAppOptionsRequired): Promise<void>;
+}
+declare const _default: TimeTrackingProjectsService;
+export default _default;

package/lib/src/services/timeTrackingProjects.service.js

@@ -0,0 +1,78 @@
+import { ObjectId } from 'mongodb';
+import Immutable from '../Immutable.class.js';
+import ImmutableError from '../classes/errors/Immutable.error.js';
+import TimeTrackingProjectModel from '../models/timeTrackingProject.model.js';
+import ShiftPlansService from './shiftPlans.service.js';
+/** Time-tracking projects group tracked time and cap it through maximumHours. Distinct from the content project model. */
+export class TimeTrackingProjectsService extends Immutable {
+    constructor() {
+        super(...arguments);
+        this.model = TimeTrackingProjectModel;
+    }
+    /** Categories partition the plan's budget: their ids must be unique and their total must not exceed the plan maximum (when one is set). */
+    assertCategories(maximumHours, categories) {
+        // a plan without categories has nothing to partition, shift-based plans may leave the list empty
+        if (!categories?.length)
+            return;
+        const ids = new Set();
+        let allocated = 0;
+        categories.forEach((category) => {
+            if (ids.has(category.id))
+                throw new ImmutableError('TIME_TRACKING_CATEGORY_ID_DUPLICATE');
+            ids.add(category.id);
+            allocated += category.maximumHours || 0;
+        });
+        if (maximumHours !== undefined && allocated > maximumHours)
+            throw new ImmutableError('TIME_TRACKING_CATEGORY_HOURS_EXCEEDED');
+    }
+    /** A plan is shift-based when it tracks on shifts and links a shift plan; only then may it skip categories. */
+    assertCategoryRequired(modes, shiftPlan, categories) {
+        if (modes === 'shifts' && shiftPlan)
+            return;
+        if (!categories?.length)
+            throw new ImmutableError('TIME_TRACKING_CATEGORY_REQUIRED');
+    }
+    /** Only a shifts project may reference a plan: other modes clear the link, and shifts must point at an existing plan in this project. */
+    async normalizeShiftPlan(input, options) {
+        if (input.modes !== 'shifts' || !input.shiftPlan) {
+            const normalized = { ...input };
+            delete normalized.shiftPlan;
+            return normalized;
+        }
+        if (!ObjectId.isValid(input.shiftPlan))
+            throw new ImmutableError('TIME_TRACKING_SHIFT_PLAN_NOT_FOUND');
+        const plan = await ShiftPlansService.planForScheduling(new ObjectId(input.shiftPlan), options, false);
+        if (!plan)
+            throw new ImmutableError('TIME_TRACKING_SHIFT_PLAN_NOT_FOUND');
+        return input;
+    }
+    singleTimeTrackingProject(id, options) {
+        return this.model.db.findOne({ id, company: options.company, project: options.project }, { projection: { history: 0 } });
+    }
+    async createTimeTrackingProject(input, options) {
+        this.assertCategories(input.maximumHours, input.categories);
+        const normalized = await this.normalizeShiftPlan(input, options);
+        this.assertCategoryRequired(normalized.modes, normalized.shiftPlan, input.categories);
+        await this.create({ ...normalized, company: options.company, project: options.project }, options.user, options.app);
+        return (await this.singleTimeTrackingProject(input.id, options));
+    }
+    async changeTimeTrackingProject(id, input, options) {
+        this.assertCategories(input.maximumHours, input.categories);
+        const existing = await this.singleTimeTrackingProject(id, options);
+        if (!existing?._id)
+            throw new ImmutableError('TIME_TRACKING_PROJECT_NOT_FOUND');
+        const normalized = await this.normalizeShiftPlan(input, options);
+        // modes are immutable, so the stored mode decides whether the changed plan still books on shifts
+        this.assertCategoryRequired(existing.modes, normalized.shiftPlan, input.categories ?? existing.categories);
+        await this.immutable({ _id: existing._id, company: options.company, project: options.project }, normalized, options.user, 'change', options.app);
+        return (await this.singleTimeTrackingProject(id, options));
+    }
+    async removeTimeTrackingProject(id, options) {
+        const existing = await this.singleTimeTrackingProject(id, options);
+        if (!existing?._id)
+            throw new ImmutableError('TIME_TRACKING_PROJECT_NOT_FOUND');
+        await this.delete(existing._id, options.user, options.app);
+    }
+}
+export default new TimeTrackingProjectsService();
+//# sourceMappingURL=timeTrackingProjects.service.js.map

package/lib/src/services/timeTrackingProjects.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeTrackingProjects.service.js","sourceRoot":"","sources":["../../../src/services/timeTrackingProjects.service.ts"],"names":[],"mappings":"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"}

package/lib/src/services/tracker.service.d.ts

@@ -0,0 +1,150 @@
+import { Options, Scope, Tracker, TrackerBooking, TrackerBookingShift, TrackerShiftBooking, TrackerData, TrackerGroup, TrackerInput, TrackerStatistics, TimeTrackingProjectAllocationUsage, UserApp, UserAppOptionsRequired, BasicData, BookingWindow, ProjectIdParams, ProjectParams, TrackerUserQuery } from '@lilaquadrat/interfaces';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import { ObjectId, WithId } from 'mongodb';
+import Immutable from '../Immutable.class.js';
+import type { TrackerDailyLimitInput } from '../interfaces/TrackerDailyLimitInput.js';
+import type { TrackerStatisticsBucket } from '../interfaces/TrackerStatisticsBucket.js';
+import type { TrackerStatisticsRange } from '../interfaces/TrackerStatisticsRange.js';
+/** the `user` query value that lists every person's entries; `filterAdmin` removes `user` for anyone without the admin scope */
+export declare const TRACKER_ALL_USERS = "all";
+export declare class TrackerService extends Immutable<Tracker> {
+    model: import("../classes/modelv2.class.js").default<Tracker, string>;
+    /** writes are pinned to the company and project, so an id from another tenant never matches */
+    private scopeFilter;
+    /** the stored entry of this company and project; it carries the owner and plan, which a change payload does not */
+    scopedBooking(id: ObjectId, options: Pick<UserAppOptionsRequired, 'company' | 'project'>): Promise<WithId<Tracker> | null>;
+    /**
+     * Turns the request entries into bookings of the caller and runs every guard before anything is stored.
+     * Only an admin books for another person, so everybody else loses the `customer` the body names.
+     */
+    private prepareBookings;
+    createBooking(input: Tracker, options: UserAppOptionsRequired): Promise<import("@lilaquadrat/interfaces").CreateResult<BasicData<Tracker>>>;
+    createBookings(input: Tracker[], options: UserAppOptionsRequired): Promise<{
+        ids: any;
+        documentsInserted: number;
+        documentsProvided: number;
+    }>;
+    /** the change payload with real dates, without the keys the model keeps as booked */
+    private changeOf;
+    /**
+     * Changes a booking of this company and project. Access is decided by `ownBookingOrAdmin` before.
+     * The shift assignment is only checked when the shift or the person changes, so entries whose
+     * assignment was removed later can still get their time or description corrected.
+     */
+    changeBooking(id: ObjectId, input: TrackerInput, options: UserAppOptionsRequired): Promise<import("mongodb").UpdateResult<import("bson").Document>>;
+    changeDescription(id: ObjectId, input: Pick<Tracker, 'description'>, options: UserAppOptionsRequired): Promise<import("mongodb").UpdateResult<import("bson").Document>>;
+    removeBooking(id: ObjectId, options: UserAppOptionsRequired): Promise<import("mongodb").DeleteResult>;
+    /** Uses the tracked span when both ends are present, mirroring the duration stored by changeBooking(). */
+    private dailyLimitDuration;
+    /**
+     * The entries that count as one person's time: the ones booked for that customer, which an admin
+     * stores under their own account, and the ones the person's own accounts booked. Counting by the
+     * booking account alone charges everything an admin books for others to the admin.
+     */
+    private personFilter;
+    /**
+     * Rejects entries that would push a user's tracked time for one plan and calendar day above the
+     * plan's maximumHoursPerDay. Missing plans, plans without the option and entries without a plan
+     * fall back to the 24 hour ceiling so existing trackers keep working.
+     */
+    assertDailyLimit(entries: TrackerDailyLimitInput[], options: UserAppOptionsRequired, excludeId?: ObjectId): Promise<void>;
+    /**
+     * The caller's own customer in this project, used to check the shifts the caller is assigned to.
+     * App is intentionally not pinned: the tracker client reaches the same flow with different
+     * `studio-app` ids (entry save uses the editor app, shift and allocation lookups use the tracker
+     * app), and the customer connection is what carries the assignment, not the app that asked.
+     */
+    private callerCustomer;
+    /**
+     * Rejects entries referencing a shift the caller may not book on. A member only books their own
+     * customer, so every shift entry has to carry that customer in `assignments.customer`. A project
+     * admin books for the person on the shift, so the entry's own `customer` is what gets checked
+     * (an admin entry without one still falls back to their own customer, the "record time" screen).
+     * Entries without a shift are ignored, so every other tracking mode is unaffected.
+     */
+    assertShiftAssignment(entries: Array<Pick<Tracker, 'shift' | 'customer'>>, options: UserAppOptionsRequired, admin?: boolean): Promise<void>;
+    /**
+     * Rejects entries whose grouping does not match their plan. A shift-based plan books on shifts
+     * and must not carry a category; every other plan, and an entry without a plan, groups by
+     * category. Entries are checked against one plan lookup per distinct plan.
+     *
+     * A change is lenient: entries created before shift bookings existed carry a category next to
+     * their shift, so it only requires the result to still be grouped at all.
+     */
+    assertPlanGrouping(entries: Array<Pick<Tracker, 'shift' | 'category'> & Partial<Pick<Tracker, 'timeTrackingProject'>>>, options: UserAppOptionsRequired, assertion?: 'create' | 'change'): Promise<void>;
+    /** the owner of an entry, the id when the user is not resolved to a profile */
+    ownerOf(tracker: Pick<Tracker, 'user'>): string | undefined;
+    /** `tracker:admin` reads and changes the entries of everybody, not just the caller's own */
+    isTrackerAdmin(options: Pick<UserAppOptionsRequired, 'user' | 'company' | 'project'>): Promise<boolean>;
+    /**
+     * Changing or removing a booking needs the route's scope and, on top of it, the booking has to be the caller's
+     * own or the caller has `tracker:admin`. The scope guard runs first, so owning a booking never replaces it.
+     * A booking that does not exist is not decided here, the service answers it as missing.
+     */
+    mayChangeBooking(stored: Tracker | null | undefined, options: Pick<UserAppOptionsRequired, 'user' | 'company' | 'project'>): Promise<boolean>;
+    /** preHandler for the routes that change or remove one booking, see mayChangeBooking() */
+    ownBookingOrAdmin(): (request: FastifyRequest<{
+        Params: ProjectIdParams;
+    }>, reply: FastifyReply) => Promise<void>;
+    /**
+     * An admin may book for another person: on a shift for the person assigned to it, or anywhere by
+     * naming their customer. Only asked when an entry carries a shift or a customer, so the ordinary
+     * tracking modes cost no permission lookup.
+     */
+    private bookingAdmin;
+    private withoutCustomer;
+    /**
+     * ISO-normalized booking window; the same overlap convention the shift planning filters use.
+     * Both ends are required, the tracker only works with windows it can bound.
+     */
+    bookingInterval(from: string | undefined, to: string | undefined): {
+        from: string;
+        to: string;
+    };
+    /**
+     * The shifts the caller may book tracked time on: the shifts of the plan that carry the caller's
+     * own customer in `assignments.customer` and overlap the booking window. The narrow projection
+     * lets the tracker app offer them without `shifts:read`.
+     */
+    bookableShifts(timeTrackingProject: string, from: string | undefined, to: string | undefined, options: UserAppOptionsRequired): Promise<TrackerBookingShift[]>;
+    /**
+     * Every time entry booked on a shift of a time tracking project, so each booking can be edited
+     * or removed on its own. An entry names its person in `customer` only when an admin booked it;
+     * a member's own entry carries just the account, so that account is resolved to its connected
+     * customer.
+     */
+    shiftBookings(timeTrackingProject: string, options: Required<Options>): Promise<TrackerShiftBooking[]>;
+    single(internalId: ObjectId, options: Required<Options>): Promise<Tracker | null>;
+    /**
+     * The entries of one plan inside a range, newest last, each with the name of the person who booked it.
+     * `user` is the person to list, or TRACKER_ALL_USERS; the caller decides who may ask for more than their own.
+     */
+    bookings(timeTrackingProject: string, range: BookingWindow, user: string, options: Required<Options>): Promise<TrackerBooking[]>;
+    /**
+     * Hours a person was allocated per category against everything they booked on the plan so far.
+     * One aggregation sums all categories, so the cost does not grow with the number of allocations.
+     */
+    allocationUsage(timeTrackingProject: string, user: string, options: Required<Options>): Promise<TimeTrackingProjectAllocationUsage[]>;
+    statistics(user: string, company?: string, project?: string, timeTrackingProject?: string, dateRange?: TrackerStatisticsRange): Promise<TrackerStatistics>;
+    day(day: string, options: Options & UserApp): Promise<{
+        data: WithId<Tracker>[];
+        count: number;
+        statistics: Partial<Record<string, TrackerData>>;
+        date: Date;
+    }>;
+    /** the categories used in this company and project; the search matches literally, it is no pattern */
+    categories(search: string, options: Options & UserApp): Promise<string[]>;
+    /**
+     * Turns the day and group buckets of the statistics aggregation into the summary. Entries without a
+     * group count towards `count` only, the same as entries the tracker cannot place in any bucket.
+     */
+    statisticsOf(buckets: TrackerStatisticsBucket[]): Omit<TrackerStatistics, 'start' | 'end'>;
+    createStatistics(data: Tracker[], range: 'day' | 'month', rangeIdentifier: string): Partial<Record<TrackerGroup, TrackerData>>;
+    /** preHandler that removes the `user` query for anybody without the given scopes, so they only see their own entries */
+    filterAdmin(scope: Scope): (request: FastifyRequest<{
+        Params: ProjectParams;
+        Querystring: TrackerUserQuery;
+    }>, reply: FastifyReply) => Promise<undefined>;
+}
+declare const _default: TrackerService;
+export default _default;