bamboohr.com 1.5.7 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # bamboohr.com [![npm version](https://img.shields.io/npm/v/bamboohr.com.svg)](https://www.npmjs.com/package/bamboohr.com)
 
-An [BambooHR](https://bamboohr.com) API client. For a documentation on the API see the [BambooHR API](https://documentation.bamboohr.com/reference).
+An [BambooHR](https://bamboohr.com) API client. For a documentation on the API see the [BambooHR API reference](https://documentation.bamboohr.com/reference).
 
 ### Installation
 

package/dist/BambooHR.js

@@ -22,6 +22,9 @@ class BambooHR {
             },
         });
         this.apiClient.interceptors.response.push(response => {
+            if (response.ok) {
+                return;
+            }
             const errorMessage = response.headers.get('x-bamboohr-error-message') || response.statusText;
             throw new Error(`HTTP error ${response.status}: ${errorMessage}`);
         });

package/dist/Endpoints.d.ts

@@ -1,17 +1,24 @@
-import type { Fields } from './interfaces/Fields';
+import type { EmployeesListOptions, Fields } from './interfaces';
 export declare const Endpoint: {
     DIRECTORY: string;
     EMPLOYEES: string;
     Employees: {
+        employee(id: number, options?: {
+            fields?: Array<keyof Fields>;
+            onlyCurrent?: boolean;
+        }): string;
         employeeDirectory(): string;
-        employees(id?: number, fields?: Array<keyof Fields>): string;
+        employees(id?: number): string;
+        listEmployees(options?: EmployeesListOptions): string;
     };
     META: string;
     POLICIES: string;
     REQUESTS: string;
     TIME_OFF: string;
     TimeOff: {
+        timeOffBalance(id: number): string;
         timeOffPolicies(): string;
+        timeOffRequest(id: number): string;
         timeOffRequests(): string;
         timeOffTypes(): string;
         whosOut(): string;

package/dist/Endpoints.js

@@ -5,20 +5,64 @@ exports.Endpoint = {
     DIRECTORY: 'directory',
     EMPLOYEES: 'employees',
     Employees: {
+        employee(id, options) {
+            const url = new URL(`${exports.Endpoint.EMPLOYEES}/${id}/`, 'https://example.com');
+            const params = new URLSearchParams();
+            if ((options === null || options === void 0 ? void 0 : options.fields) && options.fields.length > 0) {
+                params.append('fields', options.fields.join(','));
+            }
+            if ((options === null || options === void 0 ? void 0 : options.onlyCurrent) !== undefined) {
+                params.append('onlyCurrent', String(options.onlyCurrent));
+            }
+            url.search = params.toString();
+            return `${url.pathname.slice(1)}${url.search}`;
+        },
         employeeDirectory() {
-            return `/${exports.Endpoint.EMPLOYEES}/${exports.Endpoint.DIRECTORY}/`;
+            return `${exports.Endpoint.EMPLOYEES}/${exports.Endpoint.DIRECTORY}/`;
         },
-        employees(id, fields) {
-            const url = new URL(`/${exports.Endpoint.EMPLOYEES}/`, 'https://example.com');
-            if (id) {
+        employees(id) {
+            const url = new URL(`${exports.Endpoint.EMPLOYEES}/`, 'https://example.com');
+            if (id !== undefined) {
                 url.pathname += `${id}/`;
             }
-            if (fields) {
-                const params = new URLSearchParams();
-                params.append('fields', fields.join(','));
-                url.search = params.toString();
+            return `${url.pathname.slice(1)}${url.search}`;
+        },
+        listEmployees(options) {
+            var _a, _b, _c, _d, _e, _f, _g, _h;
+            const url = new URL(exports.Endpoint.EMPLOYEES, 'https://example.com');
+            const params = new URLSearchParams();
+            if ((options === null || options === void 0 ? void 0 : options.fields) && options.fields.length > 0) {
+                params.append('fields', options.fields.join(','));
+            }
+            if (options === null || options === void 0 ? void 0 : options.sort) {
+                params.append('sort', options.sort);
+            }
+            if (((_a = options === null || options === void 0 ? void 0 : options.filter) === null || _a === void 0 ? void 0 : _a.ids) && options.filter.ids.length > 0) {
+                params.append('filter[ids]', options.filter.ids.join(','));
+            }
+            if ((_b = options === null || options === void 0 ? void 0 : options.filter) === null || _b === void 0 ? void 0 : _b.firstName) {
+                params.append('filter[firstName]', options.filter.firstName);
+            }
+            if ((_c = options === null || options === void 0 ? void 0 : options.filter) === null || _c === void 0 ? void 0 : _c.lastName) {
+                params.append('filter[lastName]', options.filter.lastName);
             }
-            return `${url.pathname}${url.search}`;
+            if ((_d = options === null || options === void 0 ? void 0 : options.filter) === null || _d === void 0 ? void 0 : _d.jobTitleName) {
+                params.append('filter[jobTitleName]', options.filter.jobTitleName);
+            }
+            if ((_e = options === null || options === void 0 ? void 0 : options.filter) === null || _e === void 0 ? void 0 : _e.status) {
+                params.append('filter[status]', options.filter.status);
+            }
+            if (((_f = options === null || options === void 0 ? void 0 : options.page) === null || _f === void 0 ? void 0 : _f.limit) !== undefined) {
+                params.append('page[limit]', String(options.page.limit));
+            }
+            if ((_g = options === null || options === void 0 ? void 0 : options.page) === null || _g === void 0 ? void 0 : _g.after) {
+                params.append('page[after]', options.page.after);
+            }
+            if ((_h = options === null || options === void 0 ? void 0 : options.page) === null || _h === void 0 ? void 0 : _h.before) {
+                params.append('page[before]', options.page.before);
+            }
+            url.search = params.toString();
+            return `${url.pathname.slice(1)}${url.search}`;
         },
     },
     META: 'meta',
@@ -26,17 +70,23 @@ exports.Endpoint = {
     REQUESTS: 'requests',
     TIME_OFF: 'time_off',
     TimeOff: {
+        timeOffBalance(id) {
+            return `${exports.Endpoint.EMPLOYEES}/${id}/${exports.Endpoint.TIME_OFF}/calculator/`;
+        },
         timeOffPolicies() {
-            return `/${exports.Endpoint.META}/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.POLICIES}/`;
+            return `${exports.Endpoint.META}/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.POLICIES}/`;
+        },
+        timeOffRequest(id) {
+            return `${exports.Endpoint.TIME_OFF}/${exports.Endpoint.REQUESTS}/${id}/`;
         },
         timeOffRequests() {
-            return `/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.REQUESTS}/`;
+            return `${exports.Endpoint.TIME_OFF}/${exports.Endpoint.REQUESTS}/`;
         },
         timeOffTypes() {
-            return `/${exports.Endpoint.META}/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.TYPES}/`;
+            return `${exports.Endpoint.META}/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.TYPES}/`;
         },
         whosOut() {
-            return `/${exports.Endpoint.TIME_OFF}/${exports.Endpoint.WHOS_OUT}/`;
+            return `${exports.Endpoint.TIME_OFF}/${exports.Endpoint.WHOS_OUT}/`;
         },
     },
     TYPES: 'types',

package/dist/api/EmployeesAPI.d.ts

@@ -1,26 +1,27 @@
 import type { APIClient } from '@ffflorian/api-client';
-import type { Employee, EmployeeDirectory, Fields, WritableFields } from '../interfaces';
+import type { Employee, EmployeeDirectory, EmployeesListOptions, EmployeesListResponse, Fields, WritableFields } from '../interfaces';
 export declare class EmployeesAPI {
     private readonly apiClient;
     constructor(apiClient: APIClient);
     /**
      * Update an employee, based on employee id.
-     * @see https://documentation.bamboohr.com/reference#add-employee-1
      */
-    addEmployee(fields: Pick<Fields, 'firstName' | 'lastName'>): Promise<Employee>;
+    addEmployee(fields: WritableFields): Promise<Employee>;
     /**
      * Get employee data by specifying a set of fields. This is suitable for getting basic employee information, including current values for fields that are part of a historical table, like job title, or compensation information.
-     * @see https://documentation.bamboohr.com/reference#get-employee
      */
-    getEmployee(id: number, fields?: Array<keyof Fields>): Promise<Employee>;
+    getEmployee(id: number, fields?: Array<keyof Fields>, onlyCurrent?: boolean): Promise<Employee>;
     /**
      * Gets employee directory.
-     * @see https://documentation.bamboohr.com/reference#get-employees-directory-1
      */
     getEmployeeDirectory(): Promise<EmployeeDirectory>;
+    /**
+     * Returns a cursor-paginated collection of employees with optional filter and sort criteria.
+     * @see https://documentation.bamboohr.com/reference/list-employees
+     */
+    listEmployees(options?: EmployeesListOptions): Promise<EmployeesListResponse>;
     /**
      * Update an employee, based on employee id.
-     * @see https://documentation.bamboohr.com/reference#update-employee
      */
     updateEmployee(id: number, fields: WritableFields): Promise<Employee>;
 }

package/dist/api/EmployeesAPI.js

@@ -17,7 +17,6 @@ class EmployeesAPI {
     }
     /**
      * Update an employee, based on employee id.
-     * @see https://documentation.bamboohr.com/reference#add-employee-1
      */
     addEmployee(fields) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -28,18 +27,16 @@ class EmployeesAPI {
     }
     /**
      * Get employee data by specifying a set of fields. This is suitable for getting basic employee information, including current values for fields that are part of a historical table, like job title, or compensation information.
-     * @see https://documentation.bamboohr.com/reference#get-employee
      */
-    getEmployee(id, fields) {
+    getEmployee(id, fields, onlyCurrent) {
         return __awaiter(this, void 0, void 0, function* () {
-            const endpoint = Endpoints_1.Endpoint.Employees.employees(id, fields);
+            const endpoint = Endpoints_1.Endpoint.Employees.employee(id, { fields, onlyCurrent });
             const { data } = yield this.apiClient.get(endpoint);
             return data;
         });
     }
     /**
      * Gets employee directory.
-     * @see https://documentation.bamboohr.com/reference#get-employees-directory-1
      */
     getEmployeeDirectory() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -48,9 +45,19 @@ class EmployeesAPI {
             return data;
         });
     }
+    /**
+     * Returns a cursor-paginated collection of employees with optional filter and sort criteria.
+     * @see https://documentation.bamboohr.com/reference/list-employees
+     */
+    listEmployees(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.Employees.listEmployees(options);
+            const { data } = yield this.apiClient.get(endpoint);
+            return data;
+        });
+    }
     /**
      * Update an employee, based on employee id.
-     * @see https://documentation.bamboohr.com/reference#update-employee
      */
     updateEmployee(id, fields) {
         return __awaiter(this, void 0, void 0, function* () {

package/dist/api/TimeOffAPI.d.ts

@@ -3,9 +3,18 @@ import type { OffEmployee, TimeOffPolicy, TimeOffRequest, TimeOffRequestsOptions
 export declare class TimeOffAPI {
     private readonly apiClient;
     constructor(apiClient: APIClient);
+    /**
+     * Creates a time off request.
+     * @see https://documentation.bamboohr.com/reference/create-time-off-request
+     */
+    createTimeOffRequest(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Returns calculated balances as of the provided end date.
+     * @see https://documentation.bamboohr.com/reference/get-time-off-balance
+     */
+    getTimeOffBalance(employeeId: number, end: string, precision?: number): Promise<Record<string, unknown>>;
     /**
      * This endpoint gets a list of time off policies.
-     * @see https://documentation.bamboohr.com/reference#get-time-off-policies
      */
     timeOffPolicies(): Promise<TimeOffPolicy[]>;
     /**
@@ -18,7 +27,6 @@ export declare class TimeOffAPI {
      * If there are zero notes for a request then the "notes" tag will be still included as an empty array.
      *
      * Newer time off requests may also include details for each day of the request in a element.
-     * @see https://documentation.bamboohr.com/reference#time-off-get-time-off-requests-1
      */
     timeOffRequests(options: TimeOffRequestsOptions): Promise<TimeOffRequest[]>;
     /**
@@ -27,12 +35,15 @@ export declare class TimeOffAPI {
      * request. The default is to return the list of time off types the user has permissions on. This distinction is
      * important, as employees can request time off for types that they don't have permission to view balances and
      * requests for.
-     * @see https://documentation.bamboohr.com/reference#get-time-off-types
      */
     timeOffTypes(mode?: 'request'): Promise<TimeOffTypes>;
+    /**
+     * Updates an existing time off request status.
+     * @see https://documentation.bamboohr.com/reference/update-time-off-request-status
+     */
+    updateTimeOffRequestStatus(id: number, request: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
      * This endpoint will return a list, sorted by date, of employees who will be out, and company holidays, for a period of time.
-     * @see https://documentation.bamboohr.com/reference#get-a-list-of-whos-out-1
      */
-    whosOut(start?: string, end?: string): Promise<OffEmployee[]>;
+    whosOut(start?: string, end?: string, filter?: 'off'): Promise<OffEmployee[]>;
 }

package/dist/api/TimeOffAPI.js

@@ -15,9 +15,30 @@ class TimeOffAPI {
     constructor(apiClient) {
         this.apiClient = apiClient;
     }
+    /**
+     * Creates a time off request.
+     * @see https://documentation.bamboohr.com/reference/create-time-off-request
+     */
+    createTimeOffRequest(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.TimeOff.timeOffRequests();
+            const { data } = yield this.apiClient.put(endpoint, request);
+            return data;
+        });
+    }
+    /**
+     * Returns calculated balances as of the provided end date.
+     * @see https://documentation.bamboohr.com/reference/get-time-off-balance
+     */
+    getTimeOffBalance(employeeId, end, precision) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.TimeOff.timeOffBalance(employeeId);
+            const { data } = yield this.apiClient.get(endpoint, { params: { end, precision } });
+            return data;
+        });
+    }
     /**
      * This endpoint gets a list of time off policies.
-     * @see https://documentation.bamboohr.com/reference#get-time-off-policies
      */
     timeOffPolicies() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -36,7 +57,6 @@ class TimeOffAPI {
      * If there are zero notes for a request then the "notes" tag will be still included as an empty array.
      *
      * Newer time off requests may also include details for each day of the request in a element.
-     * @see https://documentation.bamboohr.com/reference#time-off-get-time-off-requests-1
      */
     timeOffRequests(options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -51,7 +71,6 @@ class TimeOffAPI {
      * request. The default is to return the list of time off types the user has permissions on. This distinction is
      * important, as employees can request time off for types that they don't have permission to view balances and
      * requests for.
-     * @see https://documentation.bamboohr.com/reference#get-time-off-types
      */
     timeOffTypes(mode) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -60,14 +79,24 @@ class TimeOffAPI {
             return data;
         });
     }
+    /**
+     * Updates an existing time off request status.
+     * @see https://documentation.bamboohr.com/reference/update-time-off-request-status
+     */
+    updateTimeOffRequestStatus(id, request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const endpoint = Endpoints_1.Endpoint.TimeOff.timeOffRequest(id);
+            const { data } = yield this.apiClient.put(endpoint, request);
+            return data;
+        });
+    }
     /**
      * This endpoint will return a list, sorted by date, of employees who will be out, and company holidays, for a period of time.
-     * @see https://documentation.bamboohr.com/reference#get-a-list-of-whos-out-1
      */
-    whosOut(start, end) {
+    whosOut(start, end, filter) {
         return __awaiter(this, void 0, void 0, function* () {
             const endpoint = Endpoints_1.Endpoint.TimeOff.whosOut();
-            const { data } = yield this.apiClient.get(endpoint, { params: { end, start } });
+            const { data } = yield this.apiClient.get(endpoint, { params: { end, filter, start } });
             return data;
         });
     }

package/dist/interfaces/Employee.d.ts

@@ -1,7 +1,7 @@
 import { Fields } from './Fields';
 export interface BaseEmployee {
     firstName: string;
-    id: string;
+    id: number;
     lastName: string;
 }
 export type Employee = BaseEmployee & PartialNull<Fields>;

package/dist/interfaces/EmployeesList.d.ts

@@ -0,0 +1,20 @@
+import { Fields } from './Fields';
+export interface EmployeesListFilter {
+    firstName?: string;
+    ids?: number[];
+    jobTitleName?: string;
+    lastName?: string;
+    status?: 'active' | 'inactive';
+}
+export interface EmployeesListOptions {
+    fields?: Array<keyof Fields>;
+    filter?: EmployeesListFilter;
+    page?: EmployeesListPage;
+    sort?: string;
+}
+export interface EmployeesListPage {
+    after?: string;
+    before?: string;
+    limit?: number;
+}
+export type EmployeesListResponse = Record<string, unknown>;

package/dist/interfaces/EmployeesList.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/interfaces/TimeOffRequestsOptions.d.ts

@@ -1,10 +1,12 @@
 export interface TimeOffRequestsOptions {
-    /** Limit to requests that the user has a particular level of access to. Legal values are: "view" or "approve". Defaults to view. */
-    action?: string;
+    /** Limit to requests the user can view, approve, or to their own requests. Defaults to "view". */
+    action?: 'approve' | 'myRequests' | 'view';
     /** A particular employee ID to limit the response to. */
-    employeeId?: string;
+    employeeId?: number;
     /** YYYY-MM-DD. Only show time off that occurs on/before the specified end date. */
     end: string;
+    /** When true, omits the notes object from each request in the response. */
+    excludeNote?: boolean;
     /** A particular request ID to limit the response to. */
     id?: number;
     /** YYYY-MM-DD. Only show time off that occurs on/after the specified start date. */

package/dist/interfaces/index.d.ts

@@ -2,6 +2,7 @@ export * from './API';
 export * from './ClientOptions';
 export * from './DefaultHour';
 export * from './Employee';
+export * from './EmployeesList';
 export * from './Fields';
 export * from './TimeOffPolicy';
 export * from './TimeOffRequest';

package/dist/interfaces/index.js

@@ -18,6 +18,7 @@ __exportStar(require("./API"), exports);
 __exportStar(require("./ClientOptions"), exports);
 __exportStar(require("./DefaultHour"), exports);
 __exportStar(require("./Employee"), exports);
+__exportStar(require("./EmployeesList"), exports);
 __exportStar(require("./Fields"), exports);
 __exportStar(require("./TimeOffPolicy"), exports);
 __exportStar(require("./TimeOffRequest"), exports);

package/package.json

@@ -8,9 +8,11 @@
   "devDependencies": {
     "@types/hapi__hawk": "8.0.7",
     "@types/node": "~24",
+    "nock": "14.0.12",
     "rimraf": "6.1.3",
-    "typedoc": "0.28.18",
-    "typescript": "6.0.2"
+    "typedoc": "0.28.19",
+    "typescript": "6.0.3",
+    "vitest": "4.1.4"
   },
   "engines": {
     "node": ">= 21"
@@ -35,7 +37,7 @@
     "build:docs": "typedoc --tsconfig tsconfig.build.json --options ../../typedoc.json --out ../../docs/packages/bamboohr.com src/index.ts",
     "clean": "rimraf dist",
     "dist": "yarn clean && yarn build",
-    "test": "exit 0"
+    "test": "vitest"
   },
-  "version": "1.5.7"
+  "version": "1.7.0"
 }