rotacloud 2.0.3 → 2.1.0

package/dist/client-builder.d.ts

@@ -13,7 +13,15 @@ type ServiceOps<Spec extends ServiceSpecification> = {
 type ServiceCustomOps<Spec extends ServiceSpecification> = {
     [Key in keyof Spec['customOperations']]: Spec['customOperations'][Key] extends OpDef<any, any> ? ReturnType<typeof buildOp<Spec['customOperations'][Key]>> : never;
 };
-type Service<Spec extends ServiceSpecification> = Omit<ServiceOps<Spec>, keyof ServiceCustomOps<Spec>> & ServiceCustomOps<Spec>;
+/** Mapped index type of all sub services defined on a provided {@link ServiceSpecification] */
+type ServiceSubServices<Spec extends ServiceSpecification> = {
+    [Key in keyof Spec['subService']]: Spec['subService'][Key] extends ServiceSpecification ? Service<Spec['subService'][Key]> : never;
+};
+/**
+ * Service constructed from a provided {@link ServiceSpecification} consisting of
+ * built operation and custom operation methods and sub services
+ */
+type Service<Spec extends ServiceSpecification> = Omit<ServiceOps<Spec>, keyof ServiceCustomOps<Spec>> & ServiceCustomOps<Spec> & ServiceSubServices<Spec>;
 export type SdkClient<T extends Record<string, ServiceSpecification>> = {
     [ServiceName in keyof T]: Service<T[ServiceName]>;
 } & {

package/dist/client-builder.js

@@ -19,6 +19,20 @@ function serviceForContext(opContext) {
     for (const [customOpName, customOpFunc] of Object.entries(opContext.service.customOperations ?? {})) {
         service[customOpName] = buildOp(opContext, customOpFunc);
     }
+    for (const [subServiceName, subServiceSpec] of Object.entries(opContext.service.subService ?? {})) {
+        service[subServiceName] = serviceForContext({
+            get client() {
+                return opContext.client;
+            },
+            get request() {
+                return opContext.request;
+            },
+            get sdkConfig() {
+                return opContext.sdkConfig;
+            },
+            service: subServiceSpec,
+        });
+    }
     return service;
 }
 /** Builds the entire SDK client ready to be exported by the library and used by an end

package/dist/endpoint.d.ts

@@ -1,16 +1,17 @@
-import { Account, Attendance, Auth, Availability, DailyBudgets, DailyRevenue, DayNote, DaysOff, Group, Leave, Role, Shift, TimeZone, Document, LeaveEmbargo, LeaveRequest, LeaveType, Location, Pin, Terminal, ToilAccrual, ToilAllowance, UserClockedIn, User, Settings } from './interfaces/index.js';
+import { Account, Attendance, Auth, Availability, DailyBudgets, DailyRevenue, DayNote, DaysOff, Group, Leave, Role, Shift, TimeZone, Document, LeaveEmbargo, LeaveRequest, LeaveType, Location, Pin, Terminal, ToilAccrual, ToilAllowance, UserClockedIn, User, Settings, LogbookCategory } from './interfaces/index.js';
+import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 import { AttendanceQueryParams, AvailabilityQueryParams, DailyBudgetsQueryParams, DailyRevenueQueryParams, DayNotesQueryParams, DaysOffQueryParams, DocumentsQueryParams, GroupsQueryParams, LeaveEmbargoesQueryParams, LeaveQueryParams, LeaveRequestsQueryParams, LocationsQueryParams, RolesQueryParams, SettingsQueryParams, ShiftsQueryParams, TerminalsQueryParams, ToilAccrualsQueryParams, ToilAllowanceQueryParams, UsersQueryParams } from './interfaces/query-params/index.js';
 import { RequirementsOf } from './utils.js';
 /** Endpoint versions supported by the API */
 export type EndpointVersion = 'v1' | 'v2';
 /** Associated types for a given API endpoint */
-export type Endpoint<Entity, QueryParameters = undefined, RequiredFields extends keyof Entity = any> = {
+export type Endpoint<Entity, QueryParameters = undefined, CreateEntity extends keyof Entity | Partial<Entity> = any, RequiredFields extends keyof Entity = CreateEntity extends keyof Entity ? CreateEntity : never> = {
     /** The type returned by an endpoint */
     type: Entity;
     /** The query parameters for endpoints that support listing */
     queryParameters: QueryParameters;
     /** The entity type required for endpoints that support creation */
-    createType: RequirementsOf<Entity, RequiredFields>;
+    createType: CreateEntity extends keyof Entity ? RequirementsOf<Entity, RequiredFields> : CreateEntity;
 };
 /** Mapping between a endpoint URL and it's associated entity type
  *
@@ -47,5 +48,8 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
         users: Endpoint<User, UsersQueryParams, 'first_name' | 'last_name'>;
     };
     /** Type mappings for v2 endpoints */
-    v2: {};
+    v2: {
+        logbook: Endpoint<LogbookEntry, LogbookQueryParameters, 'name' | 'description' | 'date' | 'userId'>;
+        'logbook/categories': Endpoint<LogbookCategory, undefined, Pick<LogbookCategory, 'name'>>;
+    };
 }

package/dist/interfaces/index.d.ts

@@ -20,8 +20,7 @@ export * from './leave-type.interface.js';
 export * from './leave.interface.js';
 export * from './location-coordinate.interface.js';
 export * from './location.interface.js';
-export * from './logbook-category.interface.js';
-export * from './logbook-event.interface.js';
+export * from './logbook.interface.js';
 export * from './pay-period.interface.js';
 export * from './pin.interface.js';
 export * from './role-rate.interface.js';

package/dist/interfaces/index.js

@@ -20,8 +20,7 @@ export * from './leave-type.interface.js';
 export * from './leave.interface.js';
 export * from './location-coordinate.interface.js';
 export * from './location.interface.js';
-export * from './logbook-category.interface.js';
-export * from './logbook-event.interface.js';
+export * from './logbook.interface.js';
 export * from './pay-period.interface.js';
 export * from './pin.interface.js';
 export * from './role-rate.interface.js';

package/dist/interfaces/logbook.interface.d.ts

@@ -0,0 +1,29 @@
+export interface LogbookCategory {
+    id: number;
+    name: string;
+    deleted: boolean;
+    /** Date and time in ISO 8601 format  */
+    createdAt: string;
+    createdBy: number;
+}
+export interface LogbookEntry {
+    id: number;
+    name: string;
+    description: string;
+    categoryId: number;
+    /** Date of entry in ISO 8601 format  */
+    date: string;
+    time: string | null;
+    /** Date and time in ISO 8601 format  */
+    createdAt: string | null;
+    createdBy: number;
+    /** Date and time in ISO 8601 format  */
+    updatedAt: string | null;
+    updatedBy: number | null;
+    userId: number;
+}
+export interface LogbookQueryParameters {
+    userId: number;
+    /** Date in ISO 8601 format */
+    date?: string;
+}

package/dist/interfaces/query-params/index.d.ts

@@ -13,7 +13,6 @@ export * from './leave-embargoes-query-params.interface.js';
 export * from './leave-query-params.interface.js';
 export * from './leave-requests-query-params.interface.js';
 export * from './locations-query-params.interface.js';
-export * from './logbook-events-query-params.interface.js';
 export * from './pay-periods-query-params.interface.js';
 export * from './roles-query-params.interface.js';
 export * from './settings-query-params.interface.js';

package/dist/interfaces/query-params/index.js

@@ -13,7 +13,6 @@ export * from './leave-embargoes-query-params.interface.js';
 export * from './leave-query-params.interface.js';
 export * from './leave-requests-query-params.interface.js';
 export * from './locations-query-params.interface.js';
-export * from './logbook-events-query-params.interface.js';
 export * from './pay-periods-query-params.interface.js';
 export * from './roles-query-params.interface.js';
 export * from './settings-query-params.interface.js';

package/dist/main.d.ts

@@ -92,6 +92,22 @@ export declare const createRotaCloudClient: (config: import("./interfaces/sdk-co
         endpointVersion: "v1";
         operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
     };
+    logbook: {
+        endpoint: "logbook";
+        endpointVersion: "v2";
+        operations: ("get" | "delete" | "create" | "update")[];
+        customOperations: {
+            list: (ctx: import("./ops.js").OperationContext, query: import("./interfaces/logbook.interface.js").LogbookQueryParameters, opts: import("./utils.js").RequestOptions<unknown> | undefined) => AsyncGenerator<import("./interfaces/logbook.interface.js").LogbookEntry, any, any>;
+            listAll: (ctx: import("./ops.js").OperationContext, query: import("./interfaces/logbook.interface.js").LogbookQueryParameters, opts: import("./utils.js").RequestOptions<unknown> | undefined) => Promise<import("./interfaces/logbook.interface.js").LogbookEntry[]>;
+        };
+        subService: {
+            category: {
+                endpoint: "logbook/categories";
+                endpointVersion: "v2";
+                operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+            };
+        };
+    };
     pin: {
         endpoint: "pins";
         endpointVersion: "v1";

package/dist/ops.js

@@ -45,8 +45,8 @@ function createOp(ctx, newEntity) {
         data: newEntity,
     };
 }
-/** Operation for updating an entity */
-function updateOp(ctx, entity) {
+/** Operation for updating an entity for v1 endpoints */
+function updateV1Op(ctx, entity) {
     return {
         ...ctx.request,
         method: 'POST',
@@ -54,6 +54,15 @@ function updateOp(ctx, entity) {
         data: entity,
     };
 }
+/** Operation for updating an entity for v2 endpoints */
+function updateV2Op(ctx, entity) {
+    return {
+        ...ctx.request,
+        method: 'PUT',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}/${entity.id}`,
+        data: entity,
+    };
+}
 /** Operation for deleting a list of entities */
 async function updateBatchOp(ctx, entities) {
     const res = await ctx.client.request({
@@ -228,7 +237,7 @@ async function* listByPageV2Op(ctx, query, opts) {
     yield res;
     if (entityCount >= maxEntities)
         return;
-    let nextPage = res.data.pagination.next;
+    let nextPage = res.data.pagination.next ?? undefined;
     while (nextPage !== undefined) {
         const pagedRes = await ctx.client.request({
             ...queriedRequest,
@@ -237,7 +246,7 @@ async function* listByPageV2Op(ctx, query, opts) {
                 cursor: nextPage,
             },
         });
-        nextPage = pagedRes.data.pagination.next;
+        nextPage = pagedRes.data.pagination.next ?? undefined;
         yield pagedRes;
         entityCount += pagedRes.data.data.length;
         if (entityCount >= maxEntities)
@@ -286,7 +295,7 @@ export function getOpMap() {
             listAll: (listAllOp),
             listByPage: (listByPageOp),
             create: (createOp),
-            update: (updateOp),
+            update: (updateV1Op),
             updateBatch: (updateBatchOp),
         },
         v2: {
@@ -297,7 +306,7 @@ export function getOpMap() {
             listAll: (listAllV2Op),
             listByPage: (listByPageV2Op),
             create: (createOp),
-            update: (updateOp),
+            update: (updateV2Op),
             updateBatch: (updateBatchOp),
         },
     };

package/dist/ops.test.js

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from 'vitest';
+import { afterEach, describe, expect, test, vi } from 'vitest';
 import { createSdkClient } from './client-builder.js';
 import { getOpMap } from './ops.js';
 let mockAxiosClient;
@@ -18,7 +18,7 @@ vi.mock(import('axios'), async (importOriginal) => {
     };
 });
 describe('Operations', () => {
-    const service = {
+    const serviceV1 = {
         endpoint: 'settings',
         endpointVersion: 'v1',
         operations: ['get', 'list'],
@@ -26,16 +26,28 @@ describe('Operations', () => {
             promiseOp: async () => 3,
         },
     };
+    const serviceV2 = {
+        endpoint: 'logbook',
+        endpointVersion: 'v2',
+        operations: ['get', 'list'],
+        customOperations: {
+            promiseOp: async () => 3,
+        },
+    };
     const clientBuilder = createSdkClient({
-        service,
+        service: serviceV1,
+        serviceV2,
     });
     const client = clientBuilder({ basicAuth: '' });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
     test('operations returning a request config trigger a request call', async () => {
         const basicOp = getOpMap().v1.get;
         const basicOpRes = basicOp({
             client: mockAxiosClient,
             request: {},
-            service,
+            service: serviceV1,
             sdkConfig: { apiKey: '' },
         }, 1);
         expect(basicOpRes).toStrictEqual(expect.objectContaining({
@@ -45,57 +57,118 @@ describe('Operations', () => {
         expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining(basicOpRes));
     });
     test('operations returning a promise are returned as is', async () => {
-        const promiseOpRes = await service.customOperations.promiseOp();
+        const promiseOpRes = await serviceV1.customOperations.promiseOp();
         expect(promiseOpRes).toStrictEqual(await client.service.promiseOp());
     });
-    describe('list op', () => {
-        test('respects `maxResults` parameter in legacy pagination', async () => {
-            vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({ data: [] });
-            await client.service.list({}, { maxResults: 2 }).next();
-            expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining({
-                url: expect.any(String),
-                params: {
-                    limit: 2,
-                },
-            }));
-        });
-        test('automatically paginates', async () => {
-            const pageTotal = 3;
-            let pageCount = 0;
-            vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
-                headers: {
-                    'x-limit': 1,
-                    'x-total-count': pageTotal,
-                    // eslint-disable-next-line no-plusplus
-                    'x-offset': pageCount++,
-                },
-                data: [],
+    describe('list', () => {
+        describe('v1 ops', () => {
+            test('respects `maxResults` parameter in pagination', async () => {
+                vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({ data: [] });
+                await client.service.list({}, { maxResults: 2 }).next();
+                expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining({
+                    url: expect.any(String),
+                    params: {
+                        limit: 2,
+                    },
+                }));
+            });
+            test('automatically paginates', async () => {
+                const pageTotal = 3;
+                let pageCount = 0;
+                vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+                    headers: {
+                        'x-limit': 1,
+                        'x-total-count': pageTotal,
+                        // eslint-disable-next-line no-plusplus
+                        'x-offset': pageCount++,
+                    },
+                    data: [],
+                });
+                for await (const res of client.service.list({})) {
+                    res;
+                }
+                expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
+            });
+            test('stops automatic pagination after maxResults reached', async () => {
+                const pageLimit = 2;
+                const pageTotal = 6;
+                let pageCount = 0;
+                vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+                    headers: {
+                        'x-limit': pageLimit,
+                        'x-total-count': pageTotal,
+                        // eslint-disable-next-line no-plusplus
+                        'x-offset': pageCount++,
+                    },
+                    data: new Array(pageLimit).fill('entity'),
+                });
+                let resultCount = 0;
+                for await (const res of client.service.list({}, { maxResults: 3 })) {
+                    resultCount += 1;
+                    res;
+                }
+                expect(resultCount).toBe(3);
+                expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
             });
-            for await (const res of client.service.list({})) {
-                res;
-            }
-            expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
         });
-        test('stops automatic pagination after maxResults reached', async () => {
-            const pageLimit = 2;
-            const pageTotal = 6;
-            let pageCount = 0;
-            vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
-                headers: {
-                    'x-limit': pageLimit,
-                    'x-total-count': pageTotal,
-                    // eslint-disable-next-line no-plusplus
-                    'x-offset': pageCount++,
-                },
-                data: new Array(pageLimit).fill('entity'),
+        describe('v2 ops', () => {
+            test('respects `maxResults` parameter in pagination', async () => {
+                vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+                    data: { data: [], pagination: { next: null, count: 0 } },
+                });
+                await client.serviceV2.list({ userId: 0 }, { maxResults: 2 }).next();
+                expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining({
+                    url: expect.any(String),
+                    params: expect.objectContaining({
+                        limit: 2,
+                    }),
+                }));
+            });
+            test('automatically paginates', async () => {
+                const pageTotal = 3;
+                const pageLimit = 2;
+                let pageCount = 0;
+                vi.spyOn(mockAxiosClient, 'request').mockImplementation(async () => {
+                    pageCount += 1;
+                    return {
+                        data: {
+                            data: new Array(pageLimit).fill('entity'),
+                            pagination: {
+                                next: pageCount < pageTotal ? String(pageCount) : null,
+                                count: pageTotal,
+                            },
+                        },
+                    };
+                });
+                for await (const res of client.serviceV2.list({ userId: 0 })) {
+                    res;
+                }
+                expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
+            });
+            test('stops automatic pagination after maxResults reached', async () => {
+                const pageLimit = 2;
+                const pageTotal = 6;
+                let pageCount = 0;
+                vi.spyOn(mockAxiosClient, 'request').mockImplementation(() => {
+                    pageCount += pageLimit;
+                    return Promise.resolve({
+                        data: {
+                            data: new Array(pageLimit).fill('entity'),
+                            pagination: {
+                                next: pageCount < pageTotal ? String(pageCount) : null,
+                                count: pageTotal,
+                            },
+                        },
+                    });
+                });
+                let resultCount = 0;
+                for await (const res of client.serviceV2.list({ userId: 0 }, { maxResults: 3 })) {
+                    resultCount += 1;
+                    res;
+                }
+                expect(resultCount).toBe(3);
+                expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
             });
-            let resultCount = 0;
-            for await (const res of client.service.list({}, { maxResults: 3 })) {
-                resultCount += 1;
-                res;
-            }
-            expect(resultCount).toBe(3);
-            expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
         });
     });
 });

package/dist/service.d.ts

@@ -7,6 +7,7 @@ import { RequirementsOf, RequestOptions } from './utils.js';
 import { ShiftSwapRequest } from './interfaces/swap-request.interface.js';
 import { ShiftDropRequest } from './interfaces/drop-request.interface.js';
 import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
+import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
     /** Operations allowed and usable for the endpoint */
     operations: Operation[];
@@ -15,6 +16,7 @@ export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> =
      * Can be used to override operations listed in {@see ServiceSpecification['operations']}
      */
     customOperations?: Record<string, CustomOp>;
+    subService?: Record<string, ServiceSpecification<CustomOp>>;
 } & ({
     /** URL of the endpoint */
     endpoint: keyof EndpointEntityMap['v1'];
@@ -25,6 +27,15 @@ export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> =
     endpoint: keyof EndpointEntityMap['v2'];
     /** API version of the endpoint */
     endpointVersion: 'v2';
+} | {
+    endpoint: string;
+    endpointVersion: 'v1' | 'v2';
+    /**
+     * Marks the endpoint as one not defined in the {@link EndpointEntityMap}
+     *
+     * Intended for defining customOperations
+     * */
+    custom: true;
 });
 /**
  * Map of all officially supported service specifications used to generate the
@@ -122,6 +133,22 @@ export declare const SERVICES: {
         endpointVersion: "v1";
         operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
     };
+    logbook: {
+        endpoint: "logbook";
+        endpointVersion: "v2";
+        operations: ("get" | "delete" | "create" | "update")[];
+        customOperations: {
+            list: (ctx: OperationContext, query: LogbookQueryParameters, opts: RequestOptions<unknown> | undefined) => AsyncGenerator<LogbookEntry, any, any>;
+            listAll: (ctx: OperationContext, query: LogbookQueryParameters, opts: RequestOptions<unknown> | undefined) => Promise<LogbookEntry[]>;
+        };
+        subService: {
+            category: {
+                endpoint: "logbook/categories";
+                endpointVersion: "v2";
+                operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+            };
+        };
+    };
     pin: {
         endpoint: "pins";
         endpointVersion: "v1";

package/dist/service.js

@@ -1,4 +1,4 @@
-import { listAllOp, listOp, paramsFromOptions } from './ops.js';
+import { listAllOp, listAllV2Op, listOp, listV2Op, paramsFromOptions, } from './ops.js';
 /**
  * Map of all officially supported service specifications used to generate the
  * SDK client where each key is the service name and each value is the service
@@ -141,6 +141,42 @@ export const SERVICES = {
         endpointVersion: 'v1',
         operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
     },
+    logbook: {
+        endpoint: 'logbook',
+        endpointVersion: 'v2',
+        operations: ['create', 'get', 'delete', 'update'],
+        customOperations: {
+            list: (ctx, query, opts) => 
+            // Maps the "userId" query parameter into the endpoint URL
+            listV2Op({
+                ...ctx,
+                service: {
+                    ...ctx.service,
+                    endpoint: `${ctx.service.endpoint}/user/${query.userId}`,
+                    endpointVersion: 'v2',
+                    custom: true,
+                },
+            }, { date: query.date }, opts),
+            listAll: (ctx, query, opts) => 
+            // Maps the "userId" query parameter into the endpoint URL
+            listAllV2Op({
+                ...ctx,
+                service: {
+                    ...ctx.service,
+                    endpoint: `${ctx.service.endpoint}/user/${query.userId}`,
+                    endpointVersion: 'v2',
+                    custom: true,
+                },
+            }, { date: query.date }, opts),
+        },
+        subService: {
+            category: {
+                endpoint: 'logbook/categories',
+                endpointVersion: 'v2',
+                operations: ['get', 'create', 'update', 'delete', 'list', 'listAll'],
+            },
+        },
+    },
     pin: {
         endpoint: 'pins',
         endpointVersion: 'v1',
@@ -264,6 +300,7 @@ export const SERVICES = {
                     ...ctx.service,
                     endpoint: `${ctx.service.endpoint}/${query.year}`,
                     endpointVersion: 'v1',
+                    custom: true,
                 },
             }, { users: query.users }, opts),
             listAll: (ctx, query, opts) => 
@@ -274,6 +311,7 @@ export const SERVICES = {
                     ...ctx.service,
                     endpoint: `${ctx.service.endpoint}/${query.year}`,
                     endpointVersion: 'v1',
+                    custom: true,
                 },
             }, { users: query.users }, opts),
         },

package/dist/utils.js

@@ -42,7 +42,7 @@ function toSearchParams(parameters) {
 }
 function parseClientError(error) {
     const axiosErrorLocation = error.response || error.request;
-    const apiErrorMessage = axiosErrorLocation.data?.error;
+    const apiErrorMessage = axiosErrorLocation.data?.message;
     let url;
     try {
         url = new URL(error.config?.url ?? '', error.config?.baseURL);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rotacloud",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "The RotaCloud SDK for the RotaCloud API",
   "type": "module",
   "engines": {
@@ -40,9 +40,9 @@
     "eslint-config-airbnb-typescript": "^17.1.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-import": "^2.31.0",
-    "prettier": "~3.4.1",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.6"
+    "prettier": "~3.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
   },
   "dependencies": {
     "axios": "^1.7.7",

package/src/client-builder.ts

@@ -26,8 +26,21 @@ type ServiceCustomOps<Spec extends ServiceSpecification> = {
     ? ReturnType<typeof buildOp<Spec['customOperations'][Key]>>
     : never;
 };
+
+/** Mapped index type of all sub services defined on a provided {@link ServiceSpecification] */
+type ServiceSubServices<Spec extends ServiceSpecification> = {
+  [Key in keyof Spec['subService']]: Spec['subService'][Key] extends ServiceSpecification
+    ? Service<Spec['subService'][Key]>
+    : never;
+};
+
+/**
+ * Service constructed from a provided {@link ServiceSpecification} consisting of
+ * built operation and custom operation methods and sub services
+ */
 type Service<Spec extends ServiceSpecification> = Omit<ServiceOps<Spec>, keyof ServiceCustomOps<Spec>> &
-  ServiceCustomOps<Spec>;
+  ServiceCustomOps<Spec> &
+  ServiceSubServices<Spec>;
 
 export type SdkClient<T extends Record<string, ServiceSpecification>> = {
   [ServiceName in keyof T]: Service<T[ServiceName]>;
@@ -59,6 +72,20 @@ function serviceForContext<Spec extends ServiceSpecification>(opContext: Operati
   for (const [customOpName, customOpFunc] of Object.entries(opContext.service.customOperations ?? {})) {
     service[customOpName] = buildOp(opContext, customOpFunc);
   }
+  for (const [subServiceName, subServiceSpec] of Object.entries(opContext.service.subService ?? {})) {
+    service[subServiceName] = serviceForContext({
+      get client() {
+        return opContext.client;
+      },
+      get request() {
+        return opContext.request;
+      },
+      get sdkConfig() {
+        return opContext.sdkConfig;
+      },
+      service: subServiceSpec,
+    });
+  }
 
   return service as Service<Spec>;
 }

package/src/endpoint.ts

@@ -24,7 +24,9 @@ import {
   UserClockedIn,
   User,
   Settings,
+  LogbookCategory,
 } from './interfaces/index.js';
+import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 import {
   AttendanceQueryParams,
   AvailabilityQueryParams,
@@ -51,13 +53,23 @@ import { RequirementsOf } from './utils.js';
 /** Endpoint versions supported by the API */
 export type EndpointVersion = 'v1' | 'v2';
 /** Associated types for a given API endpoint */
-export type Endpoint<Entity, QueryParameters = undefined, RequiredFields extends keyof Entity = any> = {
+export type Endpoint<
+  Entity,
+  QueryParameters = undefined,
+  CreateEntity extends keyof Entity | Partial<Entity> = any,
+  // NOTE: introduced to work around TS inferring `RequirementsOf<Entity, CreateEntity>` incorrectly
+  // TS resolves type to:
+  // `RequirementsOf<Entity, "key 1"> | RequirementsOf<Entity "key 2">`
+  // instead of:
+  // `RequirementsOf<Entity, "key 1" | "key 2">`
+  RequiredFields extends keyof Entity = CreateEntity extends keyof Entity ? CreateEntity : never,
+> = {
   /** The type returned by an endpoint */
   type: Entity;
   /** The query parameters for endpoints that support listing */
   queryParameters: QueryParameters;
   /** The entity type required for endpoints that support creation */
-  createType: RequirementsOf<Entity, RequiredFields>;
+  createType: CreateEntity extends keyof Entity ? RequirementsOf<Entity, RequiredFields> : CreateEntity;
 };
 
 /** Mapping between a endpoint URL and it's associated entity type
@@ -95,5 +107,8 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
     users: Endpoint<User, UsersQueryParams, 'first_name' | 'last_name'>;
   };
   /** Type mappings for v2 endpoints */
-  v2: {};
+  v2: {
+    logbook: Endpoint<LogbookEntry, LogbookQueryParameters, 'name' | 'description' | 'date' | 'userId'>;
+    'logbook/categories': Endpoint<LogbookCategory, undefined, Pick<LogbookCategory, 'name'>>;
+  };
 }

package/src/interfaces/index.ts

@@ -20,8 +20,7 @@ export * from './leave-type.interface.js';
 export * from './leave.interface.js';
 export * from './location-coordinate.interface.js';
 export * from './location.interface.js';
-export * from './logbook-category.interface.js';
-export * from './logbook-event.interface.js';
+export * from './logbook.interface.js';
 export * from './pay-period.interface.js';
 export * from './pin.interface.js';
 export * from './role-rate.interface.js';

package/src/interfaces/logbook.interface.ts

@@ -0,0 +1,31 @@
+export interface LogbookCategory {
+  id: number;
+  name: string;
+  deleted: boolean;
+  /** Date and time in ISO 8601 format  */
+  createdAt: string;
+  createdBy: number;
+}
+
+export interface LogbookEntry {
+  id: number;
+  name: string;
+  description: string;
+  categoryId: number;
+  /** Date of entry in ISO 8601 format  */
+  date: string;
+  time: string | null;
+  /** Date and time in ISO 8601 format  */
+  createdAt: string | null;
+  createdBy: number;
+  /** Date and time in ISO 8601 format  */
+  updatedAt: string | null;
+  updatedBy: number | null;
+  userId: number;
+}
+
+export interface LogbookQueryParameters {
+  userId: number;
+  /** Date in ISO 8601 format */
+  date?: string;
+}

package/src/interfaces/query-params/index.ts

@@ -13,7 +13,6 @@ export * from './leave-embargoes-query-params.interface.js';
 export * from './leave-query-params.interface.js';
 export * from './leave-requests-query-params.interface.js';
 export * from './locations-query-params.interface.js';
-export * from './logbook-events-query-params.interface.js';
 export * from './pay-periods-query-params.interface.js';
 export * from './roles-query-params.interface.js';
 export * from './settings-query-params.interface.js';

package/src/ops.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from 'vitest';
+import { afterEach, describe, expect, test, vi } from 'vitest';
 import { Axios } from 'axios';
 import { createSdkClient } from './client-builder.js';
 import { getOpMap } from './ops.js';
@@ -22,7 +22,7 @@ vi.mock(import('axios'), async (importOriginal) => {
 });
 
 describe('Operations', () => {
-  const service = {
+  const serviceV1 = {
     endpoint: 'settings',
     endpointVersion: 'v1',
     operations: ['get', 'list'],
@@ -30,18 +30,31 @@ describe('Operations', () => {
       promiseOp: async () => 3,
     },
   } satisfies ServiceSpecification;
+  const serviceV2 = {
+    endpoint: 'logbook',
+    endpointVersion: 'v2',
+    operations: ['get', 'list'],
+    customOperations: {
+      promiseOp: async () => 3,
+    },
+  } satisfies ServiceSpecification;
   const clientBuilder = createSdkClient({
-    service,
+    service: serviceV1,
+    serviceV2,
   });
   const client = clientBuilder({ basicAuth: '' });
 
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   test('operations returning a request config trigger a request call', async () => {
     const basicOp = getOpMap().v1.get;
     const basicOpRes = basicOp(
       {
         client: mockAxiosClient,
         request: {},
-        service,
+        service: serviceV1,
         sdkConfig: { apiKey: '' },
       },
       1,
@@ -57,65 +70,134 @@ describe('Operations', () => {
   });
 
   test('operations returning a promise are returned as is', async () => {
-    const promiseOpRes = await service.customOperations.promiseOp();
+    const promiseOpRes = await serviceV1.customOperations.promiseOp();
     expect(promiseOpRes).toStrictEqual(await client.service.promiseOp());
   });
 
-  describe('list op', () => {
-    test('respects `maxResults` parameter in legacy pagination', async () => {
-      vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({ data: [] });
+  describe('list', () => {
+    describe('v1 ops', () => {
+      test('respects `maxResults` parameter in pagination', async () => {
+        vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({ data: [] });
 
-      await client.service.list({}, { maxResults: 2 }).next();
-      expect(mockAxiosClient.request).toHaveBeenCalledWith(
-        expect.objectContaining({
-          url: expect.any(String),
-          params: {
-            limit: 2,
+        await client.service.list({}, { maxResults: 2 }).next();
+        expect(mockAxiosClient.request).toHaveBeenCalledWith(
+          expect.objectContaining({
+            url: expect.any(String),
+            params: {
+              limit: 2,
+            },
+          }),
+        );
+      });
+
+      test('automatically paginates', async () => {
+        const pageTotal = 3;
+        let pageCount = 0;
+        vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+          headers: {
+            'x-limit': 1,
+            'x-total-count': pageTotal,
+            // eslint-disable-next-line no-plusplus
+            'x-offset': pageCount++,
           },
-        }),
-      );
-    });
+          data: [],
+        });
 
-    test('automatically paginates', async () => {
-      const pageTotal = 3;
-      let pageCount = 0;
-      vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
-        headers: {
-          'x-limit': 1,
-          'x-total-count': pageTotal,
-          // eslint-disable-next-line no-plusplus
-          'x-offset': pageCount++,
-        },
-        data: [],
+        for await (const res of client.service.list({})) {
+          res;
+        }
+        expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
       });
 
-      for await (const res of client.service.list({})) {
-        res;
-      }
-      expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
+      test('stops automatic pagination after maxResults reached', async () => {
+        const pageLimit = 2;
+        const pageTotal = 6;
+        let pageCount = 0;
+        vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+          headers: {
+            'x-limit': pageLimit,
+            'x-total-count': pageTotal,
+            // eslint-disable-next-line no-plusplus
+            'x-offset': pageCount++,
+          },
+          data: new Array(pageLimit).fill('entity'),
+        });
+
+        let resultCount = 0;
+        for await (const res of client.service.list({}, { maxResults: 3 })) {
+          resultCount += 1;
+          res;
+        }
+        expect(resultCount).toBe(3);
+        expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
+      });
     });
 
-    test('stops automatic pagination after maxResults reached', async () => {
-      const pageLimit = 2;
-      const pageTotal = 6;
-      let pageCount = 0;
-      vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
-        headers: {
-          'x-limit': pageLimit,
-          'x-total-count': pageTotal,
-          // eslint-disable-next-line no-plusplus
-          'x-offset': pageCount++,
-        },
-        data: new Array(pageLimit).fill('entity'),
+    describe('v2 ops', () => {
+      test('respects `maxResults` parameter in pagination', async () => {
+        vi.spyOn(mockAxiosClient, 'request').mockResolvedValue({
+          data: { data: [], pagination: { next: null, count: 0 } },
+        });
+
+        await client.serviceV2.list({ userId: 0 }, { maxResults: 2 }).next();
+        expect(mockAxiosClient.request).toHaveBeenCalledWith(
+          expect.objectContaining({
+            url: expect.any(String),
+            params: expect.objectContaining({
+              limit: 2,
+            }),
+          }),
+        );
       });
 
-      let resultCount = 0;
-      for await (const res of client.service.list({}, { maxResults: 3 })) {
-        resultCount += 1;
-        res;
-      }
-      expect(resultCount).toBe(3);
-      expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
+      test('automatically paginates', async () => {
+        const pageTotal = 3;
+        const pageLimit = 2;
+        let pageCount = 0;
+        vi.spyOn(mockAxiosClient, 'request').mockImplementation(async () => {
+          pageCount += 1;
+          return {
+            data: {
+              data: new Array(pageLimit).fill('entity'),
+              pagination: {
+                next: pageCount < pageTotal ? String(pageCount) : null,
+                count: pageTotal,
+              },
+            },
+          };
+        });
+
+        for await (const res of client.serviceV2.list({ userId: 0 })) {
+          res;
+        }
+        expect(mockAxiosClient.request).toHaveBeenCalledTimes(pageTotal);
+      });
+
+      test('stops automatic pagination after maxResults reached', async () => {
+        const pageLimit = 2;
+        const pageTotal = 6;
+        let pageCount = 0;
+        vi.spyOn(mockAxiosClient, 'request').mockImplementation(() => {
+          pageCount += pageLimit;
+          return Promise.resolve({
+            data: {
+              data: new Array(pageLimit).fill('entity'),
+              pagination: {
+                next: pageCount < pageTotal ? String(pageCount) : null,
+                count: pageTotal,
+              },
+            },
+          });
+        });
+
+        let resultCount = 0;
+        for await (const res of client.serviceV2.list({ userId: 0 }, { maxResults: 3 })) {
+          resultCount += 1;
+          res;
+        }
+        expect(resultCount).toBe(3);
+        expect(mockAxiosClient.request).toHaveBeenCalledTimes(2);
+      });
     });
   });
 });

package/src/ops.ts

@@ -220,8 +220,8 @@ function createOp<T = unknown, NewEntity = unknown>(
   };
 }
 
-/** Operation for updating an entity */
-function updateOp<Return, Entity extends { id: number } & Partial<Return>>(
+/** Operation for updating an entity for v1 endpoints */
+function updateV1Op<Return, Entity extends { id: number } & Partial<Return>>(
   ctx: OperationContext,
   entity: Entity,
 ): RequestConfig<Entity, Return> {
@@ -233,6 +233,19 @@ function updateOp<Return, Entity extends { id: number } & Partial<Return>>(
   };
 }
 
+/** Operation for updating an entity for v2 endpoints */
+function updateV2Op<Return, Entity extends { id: number } & Partial<Return>>(
+  ctx: OperationContext,
+  entity: Entity,
+): RequestConfig<Entity, Return> {
+  return {
+    ...ctx.request,
+    method: 'PUT',
+    url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}/${entity.id}`,
+    data: entity,
+  };
+}
+
 /** Operation for deleting a list of entities */
 async function updateBatchOp<Return, Entity extends { id: number } & Partial<Return>>(
   ctx: OperationContext,
@@ -439,7 +452,7 @@ async function* listByPageV2Op<T, Query>(
   yield res;
   if (entityCount >= maxEntities) return;
 
-  let nextPage = res.data.pagination.next;
+  let nextPage = res.data.pagination.next ?? undefined;
   while (nextPage !== undefined) {
     const pagedRes = await ctx.client.request<PagedResponse<T>>({
       ...queriedRequest,
@@ -448,7 +461,7 @@ async function* listByPageV2Op<T, Query>(
         cursor: nextPage,
       },
     });
-    nextPage = pagedRes.data.pagination.next;
+    nextPage = pagedRes.data.pagination.next ?? undefined;
     yield pagedRes;
     entityCount += pagedRes.data.data.length;
     if (entityCount >= maxEntities) return;
@@ -515,7 +528,7 @@ export function getOpMap<E extends Endpoint<any, any>, T extends E['type'] = E['
       listAll: listAllOp<T, E['queryParameters']>,
       listByPage: listByPageOp<T, E['queryParameters']>,
       create: createOp<T, E['createType']>,
-      update: updateOp<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
+      update: updateV1Op<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
       updateBatch: updateBatchOp<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
     },
     v2: {
@@ -526,7 +539,7 @@ export function getOpMap<E extends Endpoint<any, any>, T extends E['type'] = E['
       listAll: listAllV2Op<T, E['queryParameters']>,
       listByPage: listByPageV2Op<T, E['queryParameters']>,
       create: createOp<T, E['createType']>,
-      update: updateOp<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
+      update: updateV2Op<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
       updateBatch: updateBatchOp<T, T extends { id: number } ? RequirementsOf<T, 'id'> : never>,
     },
   } satisfies Record<EndpointVersion, Record<Operation, OpDef<any, any>>>;

package/src/service.ts

@@ -14,12 +14,23 @@ import {
   UserClockedOut,
 } from './interfaces/index.js';
 import { LaunchTerminal } from './interfaces/launch-terminal.interface.js';
-import { OpDef, Operation, OperationContext, RequestConfig, listAllOp, listOp, paramsFromOptions } from './ops.js';
+import {
+  OpDef,
+  Operation,
+  OperationContext,
+  RequestConfig,
+  listAllOp,
+  listAllV2Op,
+  listOp,
+  listV2Op,
+  paramsFromOptions,
+} from './ops.js';
 import { UserBreakRequest, UserClockIn, UserClockOut } from './interfaces/user-clock-in.interface.js';
 import { RequirementsOf, RequestOptions } from './utils.js';
 import { ShiftSwapRequest } from './interfaces/swap-request.interface.js';
 import { ShiftDropRequest } from './interfaces/drop-request.interface.js';
 import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
+import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
   /** Operations allowed and usable for the endpoint */
@@ -29,6 +40,7 @@ export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> =
    * Can be used to override operations listed in {@see ServiceSpecification['operations']}
    */
   customOperations?: Record<string, CustomOp>;
+  subService?: Record<string, ServiceSpecification<CustomOp>>;
 } & (
   | {
       /** URL of the endpoint */
@@ -42,6 +54,16 @@ export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> =
       /** API version of the endpoint */
       endpointVersion: 'v2';
     }
+  | {
+      endpoint: string;
+      endpointVersion: 'v1' | 'v2';
+      /**
+       * Marks the endpoint as one not defined in the {@link EndpointEntityMap}
+       *
+       * Intended for defining customOperations
+       * */
+      custom: true;
+    }
 );
 
 /**
@@ -193,6 +215,50 @@ export const SERVICES = {
     endpointVersion: 'v1',
     operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
   },
+  logbook: {
+    endpoint: 'logbook',
+    endpointVersion: 'v2',
+    operations: ['create', 'get', 'delete', 'update'],
+    customOperations: {
+      list: (ctx, query: LogbookQueryParameters, opts) =>
+        // Maps the "userId" query parameter into the endpoint URL
+        listV2Op<LogbookEntry, Omit<typeof query, 'userId'>>(
+          {
+            ...ctx,
+            service: {
+              ...ctx.service,
+              endpoint: `${ctx.service.endpoint}/user/${query.userId}`,
+              endpointVersion: 'v2',
+              custom: true,
+            },
+          },
+          { date: query.date },
+          opts,
+        ),
+      listAll: (ctx, query: LogbookQueryParameters, opts) =>
+        // Maps the "userId" query parameter into the endpoint URL
+        listAllV2Op<LogbookEntry, Omit<typeof query, 'userId'>>(
+          {
+            ...ctx,
+            service: {
+              ...ctx.service,
+              endpoint: `${ctx.service.endpoint}/user/${query.userId}`,
+              endpointVersion: 'v2',
+              custom: true,
+            },
+          },
+          { date: query.date },
+          opts,
+        ),
+    },
+    subService: {
+      category: {
+        endpoint: 'logbook/categories',
+        endpointVersion: 'v2',
+        operations: ['get', 'create', 'update', 'delete', 'list', 'listAll'],
+      },
+    },
+  },
   pin: {
     endpoint: 'pins',
     endpointVersion: 'v1',
@@ -321,8 +387,9 @@ export const SERVICES = {
             ...ctx,
             service: {
               ...ctx.service,
-              endpoint: `${ctx.service.endpoint}/${query.year}` as typeof ctx.service.endpoint,
+              endpoint: `${ctx.service.endpoint}/${query.year}`,
               endpointVersion: 'v1',
+              custom: true,
             },
           },
           { users: query.users },
@@ -335,8 +402,9 @@ export const SERVICES = {
             ...ctx,
             service: {
               ...ctx.service,
-              endpoint: `${ctx.service.endpoint}/${query.year}` as typeof ctx.service.endpoint,
+              endpoint: `${ctx.service.endpoint}/${query.year}`,
               endpointVersion: 'v1',
+              custom: true,
             },
           },
           { users: query.users },

package/src/utils.ts

@@ -73,7 +73,7 @@ function toSearchParams(parameters?: Record<string, QueryParameterValue>): URLSe
 
 function parseClientError(error: AxiosError): SDKError {
   const axiosErrorLocation = error.response || error.request;
-  const apiErrorMessage = axiosErrorLocation.data?.error;
+  const apiErrorMessage = axiosErrorLocation.data?.message;
   let url: URL | undefined;
   try {
     url = new URL(error.config?.url ?? '', error.config?.baseURL);

package/dist/interfaces/logbook-category.interface.d.ts

@@ -1,5 +0,0 @@
-export interface LogbookCategory {
-    id: number;
-    name: string;
-    deleted?: boolean | null;
-}

package/dist/interfaces/logbook-event.interface.d.ts

@@ -1,16 +0,0 @@
-export interface LogbookEvent {
-    id: number;
-    created_at: number;
-    created_by: number;
-    updated_at: string;
-    updated_by: string;
-    deleted: boolean;
-    deleted_at: string;
-    deleted_by: string;
-    user: number;
-    category: number;
-    date: string;
-    time: string;
-    name: string;
-    description: string;
-}

package/dist/interfaces/logbook-event.interface.js

@@ -1 +0,0 @@
-export {};

package/dist/interfaces/query-params/logbook-events-query-params.interface.d.ts

@@ -1,3 +0,0 @@
-export interface LogbookEventsQueryParams {
-    user?: number;
-}

package/dist/interfaces/query-params/logbook-events-query-params.interface.js

@@ -1 +0,0 @@
-export {};

package/src/interfaces/logbook-category.interface.ts

@@ -1,5 +0,0 @@
-export interface LogbookCategory {
-  id: number;
-  name: string;
-  deleted?: boolean | null;
-}

package/src/interfaces/logbook-event.interface.ts

@@ -1,16 +0,0 @@
-export interface LogbookEvent {
-  id: number;
-  created_at: number;
-  created_by: number;
-  updated_at: string;
-  updated_by: string;
-  deleted: boolean;
-  deleted_at: string;
-  deleted_by: string;
-  user: number;
-  category: number;
-  date: string;
-  time: string;
-  name: string;
-  description: string;
-}

package/src/interfaces/query-params/logbook-events-query-params.interface.ts

@@ -1,3 +0,0 @@
-export interface LogbookEventsQueryParams {
-  user?: number;
-}