feat: Add surcharge model and api request handlers

src/clockodo.ts

@@ -41,6 +41,7 @@ import {
   WorkTimeChangeRequestStatus,
   WorkTimeDay,
 } from "./models/workTimes.js";
+import { Surcharge } from "./models/surcharge.js";
 
 export class Clockodo {
   api: Api;
@@ -329,6 +330,20 @@ export class Clockodo {
     return this.api.get("/users", params);
   }
 
+  async getSurcharge(
+    params: Params<{ id: Surcharge["id"] }>
+  ): Promise<SurchargeReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.GET_SURCHARGE);
+
+    const { id, ...remainingParams } = params;
+
+    return this.api.get("/v2/surcharges/" + id, remainingParams);
+  }
+
+  async getSurcharges(params?: Params): Promise<SurchargesReturnType> {
+    return this.api.get("/v2/surcharges", params);
+  }
+
   async getUserReport<
     GivenUserReportType extends UserReportType = UserReportType.Year
   >(
@@ -449,6 +464,14 @@ export class Clockodo {
     return this.api.post("/users", params);
   }
 
+  async addSurcharge(
+    params: Params<Pick<Surcharge, typeof REQUIRED.ADD_SURCHARGE[number]>>
+  ): Promise<AddSurchargeReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.ADD_SURCHARGE);
+
+    return this.api.post("/v2/surcharges", params);
+  }
+
   async startClock(
     params: Params<
       Pick<TimeEntry, typeof REQUIRED.START_CLOCK[number]> & {
@@ -557,6 +580,16 @@ export class Clockodo {
     return this.api.put("/users/" + id, params);
   }
 
+  async editSurcharge(
+    params: Params<Pick<Surcharge, typeof REQUIRED.EDIT_SURCHARGE[number]>>
+  ): Promise<SurchargeReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.EDIT_SURCHARGE);
+
+    const { id } = params;
+
+    return this.api.put("/v2/surcharges/" + id, params);
+  }
+
   async deactivateCustomer(
     params: Params<Pick<Customer, typeof REQUIRED.DEACTIVATE_CUSTOMER[number]>>
   ): Promise<CustomerReturnType> {
@@ -597,6 +630,16 @@ export class Clockodo {
     return this.api.delete("/users/" + id, params);
   }
 
+  async deleteSurcharge(
+    params: Params<Pick<Surcharge, typeof REQUIRED.DELETE_SURCHARGE[number]>>
+  ): Promise<DeleteReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.DELETE_SURCHARGE);
+
+    const { id } = params;
+
+    return this.api.delete("/v2/surcharges/" + id);
+  }
+
   async deleteAbsence(
     params: Params<Pick<Absence, typeof REQUIRED.DELETE_ABSENCE[number]>>
   ): Promise<DeleteReturnType> {
@@ -810,6 +853,8 @@ export type LumpsumServicesReturnType = {
 };
 export type UserReturnType = { user: User };
 export type UsersReturnType = { users: Array<User> };
+export type SurchargeReturnType = { surcharge: Surcharge };
+export type SurchargesReturnType = { surcharges: Array<Surcharge> };
 export type EntryReturnType = { entry: Entry };
 export type AddEntryReturnType = { entry: Entry; stopped?: Entry };
 export type EditEntryReturnType = {
@@ -1000,6 +1045,10 @@ export type AddUserReturnType = {
   user: User;
 };
 
+export type AddSurchargeReturnType = {
+  surcharge: Surcharge;
+};
+
 export type WorkTimesParams = {
   /** The user ID by which the work times should be filtered */
   usersId?: number;

src/lib/requiredParams.ts

@@ -25,6 +25,7 @@ export const ADD_PROJECT = ["name", "customersId"] as const;
 export const ADD_SERVICE = ["name"] as const;
 export const ADD_TEAM = ["name"] as const;
 export const ADD_USER = ["name", "number", "email", "role"] as const;
+export const ADD_SURCHARGE = ["name", "accumulation"] as const;
 export const CHANGE_CLOCK_DURATION = [
   "entriesId",
   "durationBefore",
@@ -34,6 +35,7 @@ export const DEACTIVATE_CUSTOMER = ["id"] as const;
 export const DEACTIVATE_PROJECT = ["id"] as const;
 export const DEACTIVATE_SERVICE = ["id"] as const;
 export const DEACTIVATE_USER = ["id"] as const;
+export const DELETE_SURCHARGE = ["id"] as const;
 export const DELETE_ENTRY = ["id"] as const;
 export const DELETE_ENTRY_GROUP = ["timeSince", "timeUntil"] as const;
 export const DELETE_ABSENCE = ["id"] as const;
@@ -43,6 +45,7 @@ export const EDIT_PROJECT = ["id"] as const;
 export const EDIT_SERVICE = ["id"] as const;
 export const EDIT_TEAM = ["id"] as const;
 export const EDIT_USER = ["id"] as const;
+export const EDIT_SURCHARGE = ["id"] as const;
 export const EDIT_ENTRY_GROUP = ["timeSince", "timeUntil"] as const;
 export const EDIT_ABSENCE = ["id"] as const;
 export const EDIT_ENTRY = ["id"] as const;
@@ -62,6 +65,7 @@ export const GET_LUMPSUM_SERVICE = ["id"] as const;
 export const GET_TARGETHOURS_ROW = ["id"] as const;
 export const GET_TEAM = ["id"] as const;
 export const GET_USER = ["id"] as const;
+export const GET_SURCHARGE = ["id"] as const;
 export const GET_USER_REPORT = ["usersId", "year"] as const;
 export const GET_USER_REPORTS = ["year"] as const;
 export const GET_NONBUSINESS_DAYS = ["year"] as const;

src/models/__snapshots__/targethours.mocks.test.ts.snap

@@ -8,6 +8,7 @@ Array [
     "dateUntil": "2019-04-30",
     "id": 0,
     "monthlyTarget": 48093,
+    "surchargeModelsId": null,
     "type": "monthly",
     "usersId": 0,
     "workdayFriday": true,
@@ -24,6 +25,7 @@ Array [
     "dateUntil": "2019-07-31",
     "id": 1,
     "monthlyTarget": 44025,
+    "surchargeModelsId": null,
     "type": "monthly",
     "usersId": 0,
     "workdayFriday": true,
@@ -40,6 +42,7 @@ Array [
     "dateUntil": "2019-09-30",
     "id": 2,
     "monthlyTarget": 65472,
+    "surchargeModelsId": null,
     "type": "monthly",
     "usersId": 0,
     "workdayFriday": false,
@@ -61,6 +64,7 @@ Array [
     "monday": 0,
     "saturday": 4,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 4.16,
     "tuesday": 24,
     "type": "weekly",
@@ -78,6 +82,7 @@ Array [
     "monday": 24,
     "saturday": 0,
     "sunday": 24,
+    "surchargeModelsId": null,
     "thursday": 2.74,
     "tuesday": 3,
     "type": "weekly",
@@ -95,6 +100,7 @@ Array [
     "monday": 5.36,
     "saturday": 0,
     "sunday": 5.36,
+    "surchargeModelsId": null,
     "thursday": 6,
     "tuesday": 0,
     "type": "weekly",
@@ -112,6 +118,7 @@ Array [
     "monday": 6.11,
     "saturday": 24,
     "sunday": 6.11,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 1,
     "type": "weekly",
@@ -129,6 +136,7 @@ Array [
     "monday": 0,
     "saturday": 24,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 5.02,
     "tuesday": 4,
     "type": "weekly",
@@ -146,6 +154,7 @@ Array [
     "monday": 1,
     "saturday": 1.22,
     "sunday": 1,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 0,
     "type": "weekly",
@@ -163,6 +172,7 @@ Array [
     "monday": 5,
     "saturday": 24,
     "sunday": 5,
+    "surchargeModelsId": null,
     "thursday": 2,
     "tuesday": 0,
     "type": "weekly",
@@ -180,6 +190,7 @@ Array [
     "monday": 24,
     "saturday": 6,
     "sunday": 24,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 2,
     "type": "weekly",
@@ -197,6 +208,7 @@ Array [
     "monday": 1.21,
     "saturday": 0,
     "sunday": 1.21,
+    "surchargeModelsId": null,
     "thursday": 8,
     "tuesday": 3,
     "type": "weekly",
@@ -214,6 +226,7 @@ Array [
     "monday": 24,
     "saturday": 0,
     "sunday": 24,
+    "surchargeModelsId": null,
     "thursday": 6,
     "tuesday": 3,
     "type": "weekly",
@@ -231,6 +244,7 @@ Array [
     "monday": 24,
     "saturday": 8,
     "sunday": 24,
+    "surchargeModelsId": null,
     "thursday": 3,
     "tuesday": 6.84,
     "type": "weekly",
@@ -248,6 +262,7 @@ Array [
     "monday": 0,
     "saturday": 4,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 2.71,
     "tuesday": 4,
     "type": "weekly",
@@ -265,6 +280,7 @@ Array [
     "monday": 7.25,
     "saturday": 4,
     "sunday": 7.25,
+    "surchargeModelsId": null,
     "thursday": 24,
     "tuesday": 7,
     "type": "weekly",
@@ -282,6 +298,7 @@ Array [
     "monday": 0,
     "saturday": 2.06,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 24,
     "tuesday": 0,
     "type": "weekly",
@@ -299,6 +316,7 @@ Array [
     "monday": 0,
     "saturday": 24,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 4,
     "type": "weekly",
@@ -316,6 +334,7 @@ Array [
     "monday": 0,
     "saturday": 24,
     "sunday": 0,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 3.6,
     "type": "weekly",
@@ -333,6 +352,7 @@ Array [
     "monday": 24,
     "saturday": 0,
     "sunday": 24,
+    "surchargeModelsId": null,
     "thursday": 0,
     "tuesday": 3.66,
     "type": "weekly",

src/models/dateTime.ts

@@ -21,3 +21,11 @@ export type IsoDate =
 export type IsoUtcDateTime =
   // This type is not 100% correct but enough for our use-case
   `${IsoDate}T${number}${number}:${number}${number}:${number}${number}Z`;
+
+/**
+ * An ISO 8601 time format.
+ *
+ * Example: 23:00:00 (hh:mm:ss)
+ */
+export type IsoTime =
+  `${number}${number}:${number}${number}:${number}${number}`;

src/models/surcharge.ts

@@ -0,0 +1,54 @@
+import { IsoTime } from "./dateTime.js";
+
+export type Surcharge = {
+  /** The ID of the surcharge model  */
+  id: number;
+  /** The name of the surcharge model */
+  name: string;
+  /**
+   * Should night surcharges apply in addition to another surcharge?
+   * If `false`, only the surcharge with the higher percent value applies
+   */
+  accumulation: boolean;
+  /** Night surcharge configuration */
+  night: NightSurchargeConfiguration | null;
+  /** Increased night surcharge configuration */
+  nightIncreased: NightSurchargeConfiguration | null;
+  /** Nonbusiness surcharge configuration */
+  nonbusiness: NightSurchargeConfiguration | null;
+  /** Nonbusiness surcharge configuration for special nonbusiness days */
+  nonbusinessSpecial: SurchargeConfiguration | null;
+  /** Sunday surcharge configuration */
+  sunday: SurchargeConfiguration | null;
+  /** Saturday surcharge configuration */
+  saturday: SurchargeConfiguration | null;
+};
+
+type NightSurchargeConfiguration = {
+  /** Percentage of the work time that is added to the work time account */
+  percent: number;
+  /**
+   * Start of the period during which the surcharge applies
+   * - Format hh:mm:ss, e.g. 23:00:00
+   */
+  timeSince: IsoTime;
+  /**
+   * End of the period during which the surcharge applies
+   * - Format hh:mm:ss, e.g. 23:00:00
+   */
+  timeUntil: IsoTime;
+};
+
+export type SurchargeConfiguration = NightSurchargeConfiguration & {
+  /**
+   * Does the surcharge period start on the previous day?
+   *
+   * Not for `night` and `nightIncreased`, as these surcharges apply every day
+   */
+  timeSinceIsPreviousDay: boolean;
+  /**
+   * Does the surcharge period end on the next day?
+   * Not for `night` and `nightIncreased`, as these surcharges apply every day
+   */
+  timeUntilIsNextDay: boolean;
+};

src/models/targethours.mocks.ts

@@ -32,6 +32,7 @@ const createCommonTargethoursRowMock = (dateSince: Date) => {
     dateUntil: null,
     compensationMonthly: faker.datatype.number({ min: 0, max: 8 }),
     usersId: 0,
+    surchargeModelsId: null,
   };
 };
 

src/models/targethours.ts

@@ -22,6 +22,8 @@ type CommonTargethoursRow = {
   compensationMonthly: number;
   /** The related employee's ID */
   usersId: number;
+  /** The corresponding surcharge model */
+  surchargeModelsId: number | null;
 };
 
 export type TargethoursRowWeekly = CommonTargethoursRow & {