feat: Add surcharge model and api request handlers

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
   "editor.codeActionsOnSave": {
-    "source.fixAll.eslint": true
+    "source.fixAll.eslint": true,
+    "source.organizeImports": false
   },
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.formatOnSave": true,

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,18 @@ export class Clockodo {
     return this.api.get("/users", params);
   }
 
+  async getSurcharge(params: Params<{ id: User["id"] }>): Promise<SurchargeReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.GET_SURCHARGE);
+
+    const { id, ...remainingParams } = params;
+
+    return this.api.get("/surcharges/" + id, remainingParams);
+  }
+
+  async getSurcharges(params?: Params): Promise<SurchargesReturnType> {
+    return this.api.get("/surcharges", params);
+  }
+
   async getUserReport<
     GivenUserReportType extends UserReportType = UserReportType.Year
   >(
@@ -449,6 +462,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("/surcharges", params);
+  }
+
   async startClock(
     params: Params<
       Pick<TimeEntry, typeof REQUIRED.START_CLOCK[number]> & {
@@ -557,6 +578,16 @@ export class Clockodo {
     return this.api.put("/users/" + id, params);
   }
 
+  async editSurcharge(
+    params: Params<Pick<User, typeof REQUIRED.EDIT_SURCHARGE[number]>>
+  ): Promise<SurchargeReturnType> {
+    REQUIRED.checkRequired(params, REQUIRED.EDIT_SURCHARGE);
+
+    const { id } = params;
+
+    return this.api.put("/surcharges/" + id, params);
+  }
+
   async deactivateCustomer(
     params: Params<Pick<Customer, typeof REQUIRED.DEACTIVATE_CUSTOMER[number]>>
   ): Promise<CustomerReturnType> {
@@ -597,6 +628,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("/surcharges/" + id);
+  }
+
   async deleteAbsence(
     params: Params<Pick<Absence, typeof REQUIRED.DELETE_ABSENCE[number]>>
   ): Promise<DeleteReturnType> {
@@ -810,6 +851,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 +1043,10 @@ export type AddUserReturnType = {
   user: User;
 };
 
+export type AddSurchargeReturnType = {
+  surcharge: Surcharge;
+};
+
 export type WorkTimesParams = ParamsWithPage & {
   /** 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 = ["nonbusinessgroupsId", "year"] as const;

src/models/surcharge.ts

@@ -0,0 +1,43 @@
+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: SurchargeConfiguration | null;
+  /** Increased night surcharge configuration */
+  nightIncreased: SurchargeConfiguration | null;
+  /** Nonbusiness surcharge configuration */
+  nonbusiness: SurchargeConfiguration | null;
+  /** Nonbusiness surcharge configuration for special nonbusiness days */
+  nonbusinessSpecial: SurchargeConfiguration | null;
+  /** Sunday surcharge configuration */
+  sunday: SurchargeConfiguration | null;
+  /** Saturday surcharge configuration */
+  saturday: SurchargeConfiguration | null;
+};
+
+export type SurchargeConfiguration = {
+  /** 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: string;	
+  /** 
+   * End of the period during which the surcharge applies
+   * - Format hh:mm:ss, e.g. 23:00:00 
+  */
+  timeUntil: string;	
+  /** 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
+}
+