rotacloud 1.5.2 → 2.0.0

package/README.md

@@ -2,31 +2,38 @@
 
 ## Getting started
 
-To use this SDK you'll need to `npm install rotacloud`. This will ensure you're ready to start working with the SDK in your project.
+To use this SDK you'll need to `npm install rotacloud`. This will ensure you're ready
+to start working with the SDK in your project.
 
 ## Contributing
 
-Please ensure you perform the `npm run version:bump` command before commiting and pushing your changes to the remote branch.
+Please ensure you perform the `npm run version:bump` command before commiting and
+pushing your changes to the remote branch.
 
 ## Configuration
 
-Configuration is simple, just import the core RotaCloud SDK and supply your API key as necessary.
+Configuration is simple, import the `createRotaCloudClient` function from the SDK
+and supply your API key:
 
 ```typescript
-import { RotaCloud } from 'rotacloud';
+import { createRotaCloudClient } from 'rotacloud';
 
-const rc = new RotaCloud({
+const client = createRotaCloudClient({
   apiKey: 'YOUR_API_KEY',
 });
 ```
 
 ## Auto paging
 
-Our SDK support auto pagination as a way for developers to quickly consume list based endpoints. You will find a `list()` method on most services within the SDK which can be consumed using `for await of`. **Please ensure you are catching errors in your implementation.**
+Our SDK supports auto pagination as a way for developers to quickly consume list based endpoints.
+You will find a `list()` method on most services within the SDK which can be consumed using
+`for await of`. **Please ensure you are catching errors in your implementation.**
 
 ```typescript
+const client = createRotaCloudClient({...})
+
 try {
-  for await (const user of rc.users.list()) {
+  for await (const user of client.user.list()) {
     console.log(user);
   }
 } catch (e) {
@@ -36,25 +43,28 @@ try {
 
 ## Retry Policies
 
-Our SDK supports both basic and customisable retry polices. Both can be easily configured in the SDKConfig object at time of instantiation. Both exponential and static value based back offs are supported.
+Our SDK supports both basic and customisable retry polices.
+Both can be easily configured in the SDKConfig object at time of instantiation.
+Both exponential and static value based back offs are supported.
 
 Only idempotent requests will be retried.
 
 ```typescript
-import { RotaCloud } from 'rotacloud';
+import { createRotaCloudClient } from 'rotacloud';
 
-const rc = new RotaCloud({
+const client = createRotaCloudClient({
   apiKey: 'YOUR_API_KEY',
   retry: 'expo' | 'static',
 });
 ```
 
-If more granular control is required of the internal retry policy values, an object can be passed through the `retry` field.
+If more granular control is required of the internal retry policy values, an object
+of retry configuration can be passed through to the `retry` field instead.
 
 ```typescript
-import { RotaCloud } from 'rotacloud';
+import { createRotaCloudClient } from 'rotacloud';
 
-const rc = new RotaCloud({
+const client = createRotaCloudClient({
   apiKey: 'YOUR_API_KEY',
   retry: { delay: 2000, exponential: false, maxRetries: 10 },
 });

package/dist/client-builder.d.ts

@@ -0,0 +1,34 @@
+import { Axios } from 'axios';
+import { RetryStrategy, SDKConfig } from './interfaces/index.js';
+import { buildOp, getOpMap, OpDef } from './ops.js';
+import { ServiceSpecification } from './service.js';
+import { Endpoint, EndpointEntityMap } from './endpoint.js';
+/** Utility type to make working with the Endpoint map easier */
+type ExtractEndpoint<Spec extends ServiceSpecification> = Spec['endpoint'] extends keyof EndpointEntityMap[Spec['endpointVersion']] ? EndpointEntityMap[Spec['endpointVersion']][Spec['endpoint']] extends Endpoint<any, any> ? EndpointEntityMap[Spec['endpointVersion']][Spec['endpoint']] : never : never;
+/** Mapped index type of all specified service operations with their corresponding op function */
+type ServiceOps<Spec extends ServiceSpecification> = {
+    [Key in Spec['operations'][number]]: Spec['endpoint'] extends keyof EndpointEntityMap[Spec['endpointVersion']] ? ReturnType<typeof buildOp<ReturnType<typeof getOpMap<ExtractEndpoint<Spec>>>[Spec['endpointVersion']][Key]>> : never;
+};
+/** Mapped index type of all specified custom/overload service operations with their corresponding op function */
+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>;
+export type SdkClient<T extends Record<string, ServiceSpecification>> = {
+    [ServiceName in keyof T]: Service<T[ServiceName]>;
+} & {
+    fetch: Axios['request'];
+    /**
+     * The underlying settings for the SDK
+     */
+    config: Readonly<SDKConfig>;
+};
+export declare const DEFAULT_CONFIG: {
+    baseUri: string;
+    retry: RetryStrategy.Exponential;
+};
+/** Builds the entire SDK client ready to be exported by the library and used by an end
+ * user of the SDK
+ */
+export declare function createSdkClient<T extends Record<string, ServiceSpecification>>(serviceMap: T): (config: SDKConfig) => SdkClient<T>;
+export {};

package/dist/client-builder.js

@@ -0,0 +1,70 @@
+import { createCustomAxiosClient, defaultObject, getBaseRequestConfig } from './utils.js';
+import { RetryStrategy } from './interfaces/index.js';
+import { buildOp, getOpMap } from './ops.js';
+export const DEFAULT_CONFIG = {
+    baseUri: 'https://api.rotacloud.com',
+    retry: RetryStrategy.Exponential,
+};
+/** Converts a provided {@see OperationContext} into a {@see Service} with all
+ * associated types configured ready to be used by an end user of the SDK.
+ *
+ * The context object provided will be used as is for all operations on a service
+ */
+function serviceForContext(opContext) {
+    const service = {};
+    const opMap = getOpMap();
+    for (const op of opContext.service.operations) {
+        service[op] = buildOp(opContext, opMap[opContext.service.endpointVersion][op]);
+    }
+    for (const [customOpName, customOpFunc] of Object.entries(opContext.service.customOperations ?? {})) {
+        service[customOpName] = buildOp(opContext, customOpFunc);
+    }
+    return service;
+}
+/** Builds the entire SDK client ready to be exported by the library and used by an end
+ * user of the SDK
+ */
+export function createSdkClient(serviceMap) {
+    return (sdkConfig) => {
+        let clientConfig = Object.freeze(defaultObject(sdkConfig, DEFAULT_CONFIG));
+        let axiosClient = createCustomAxiosClient(clientConfig);
+        let requestConfig = getBaseRequestConfig(clientConfig);
+        const sdkClient = {
+            fetch: (req) => axiosClient.request({
+                ...req,
+                headers: {
+                    ...req.headers,
+                    ...requestConfig.headers,
+                },
+            }),
+            get config() {
+                return clientConfig;
+            },
+            set config(val) {
+                clientConfig = Object.freeze(defaultObject(val, DEFAULT_CONFIG));
+                axiosClient = createCustomAxiosClient(clientConfig);
+                requestConfig = getBaseRequestConfig(clientConfig);
+            },
+        };
+        for (const [serviceName, serviceSpec] of Object.entries(serviceMap)) {
+            sdkClient[serviceName] = serviceForContext({
+                service: serviceSpec,
+                // NOTE: using getters here to allow for changes after client creation
+                // eslint-disable-next-line @typescript-eslint/no-loop-func
+                get client() {
+                    return axiosClient;
+                },
+                // eslint-disable-next-line @typescript-eslint/no-loop-func
+                get request() {
+                    return requestConfig;
+                },
+                // eslint-disable-next-line @typescript-eslint/no-loop-func
+                get sdkConfig() {
+                    return clientConfig;
+                },
+            });
+        }
+        // NOTE: guarantied to be safe due to the service iteration above
+        return sdkClient;
+    };
+}

package/dist/client-builder.test.js

@@ -0,0 +1,163 @@
+import { test, expect, describe, vi } from 'vitest';
+import { createSdkClient, DEFAULT_CONFIG } from './client-builder.js';
+import pkg from '../package.json' with { type: 'json' };
+let mockAxiosClient;
+vi.mock(import('axios'), async (importOriginal) => {
+    const mod = await importOriginal();
+    return {
+        ...mod,
+        default: {
+            ...mod.default,
+            create: (...args) => {
+                mockAxiosClient = mod.default.create(...args);
+                mockAxiosClient.request = vi.fn().mockImplementation(() => Promise.resolve({}));
+                return mockAxiosClient;
+            },
+        },
+        // NOTE: vitest does not correctly infer the type for default hence the cast
+    };
+});
+const sdkConfig = {
+    basicAuth: '',
+};
+describe('SDK client builder', () => {
+    test('basic services are created', () => {
+        const clientBuilder = createSdkClient({
+            basicService1: {
+                endpoint: 'accounts',
+                endpointVersion: 'v1',
+                operations: [],
+            },
+            basicService2: {
+                endpoint: 'attendance',
+                endpointVersion: 'v1',
+                operations: [],
+            },
+        });
+        const client = clientBuilder(sdkConfig);
+        expect(client).toMatchObject({ basicService1: {}, basicService2: {} });
+    });
+    test('operations are created for services', () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'accounts',
+                endpointVersion: 'v1',
+                operations: ['get', 'listAll', 'create'],
+            },
+        });
+        const client = clientBuilder(sdkConfig);
+        expect(client.service).toStrictEqual({
+            get: expect.any(Function),
+            listAll: expect.any(Function),
+            create: expect.any(Function),
+        });
+    });
+    test('custom operations are created for services', () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'accounts',
+                endpointVersion: 'v1',
+                operations: ['get'],
+                customOperations: {
+                    customOp: async () => { },
+                },
+            },
+        });
+        const client = clientBuilder(sdkConfig);
+        expect(client.service).toStrictEqual({
+            get: expect.any(Function),
+            customOp: expect.any(Function),
+        });
+    });
+    test("service URL's have their versions specified in the URL", async () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'accounts',
+                endpointVersion: 'v1',
+                operations: ['get'],
+            },
+        });
+        const client = clientBuilder(sdkConfig);
+        await client.service.get(1);
+        expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining({
+            url: 'v1/accounts/1',
+        }));
+    });
+    test('SDK version is included as a header', async () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'settings',
+                endpointVersion: 'v1',
+                operations: ['get'],
+            },
+        });
+        const client = clientBuilder(sdkConfig);
+        await client.service.get(1);
+        expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining({
+            headers: expect.objectContaining({
+                'SDK-Version': pkg.version,
+            }),
+        }));
+    });
+});
+describe('SDK client configuration', () => {
+    test('default config settings are applied to missing config properties', () => {
+        const clientBuilder = createSdkClient({});
+        const client = clientBuilder({ basicAuth: '' });
+        expect(client.config).toStrictEqual({
+            ...DEFAULT_CONFIG,
+            basicAuth: '',
+        });
+    });
+    test('default config settings can be overridden', () => {
+        const clientBuilder = createSdkClient({});
+        const client = clientBuilder({ basicAuth: '', baseUri: 'http://example.com' });
+        expect(client.config).toStrictEqual({
+            ...DEFAULT_CONFIG,
+            basicAuth: '',
+            baseUri: 'http://example.com',
+        });
+    });
+    test('changing config properties with defaults to undefined will restore default values', () => {
+        const clientBuilder = createSdkClient({});
+        const client = clientBuilder({ basicAuth: '', baseUri: 'http://example.com' });
+        client.config = {
+            ...client.config,
+            baseUri: undefined,
+        };
+        expect(client.config).toStrictEqual({
+            ...DEFAULT_CONFIG,
+            basicAuth: '',
+        });
+    });
+    test('config is passed through to services', async () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'settings',
+                endpointVersion: 'v1',
+                operations: ['get'],
+            },
+        });
+        const baseUri = 'http://example.com';
+        const client = clientBuilder({ basicAuth: '', baseUri, retry: false });
+        await client.service.get(1);
+        expect(mockAxiosClient.getUri()).toBe(`${baseUri}/`);
+    });
+    test('config changes are reflected in services', async () => {
+        const clientBuilder = createSdkClient({
+            service: {
+                endpoint: 'settings',
+                endpointVersion: 'v1',
+                operations: ['get'],
+            },
+        });
+        const baseUri = 'http://example.com';
+        const client = clientBuilder({ basicAuth: '', baseUri, retry: false });
+        client.config = {
+            ...client.config,
+            baseUri: undefined,
+        };
+        await client.service.get(1);
+        expect(mockAxiosClient.getUri()).toBe(new URL(DEFAULT_CONFIG.baseUri).toString());
+    });
+});

package/dist/endpoint.d.ts

@@ -0,0 +1,51 @@
+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 { 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> = {
+    /** 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>;
+};
+/** Mapping between a endpoint URL and it's associated entity type
+ *
+ * Keys of each version map should be the URL of a given endpoint
+ */
+export interface EndpointEntityMap extends Record<EndpointVersion, Record<string, Endpoint<unknown, any>>> {
+    /** Type mappings for v1 endpoints */
+    v1: {
+        accounts: Endpoint<Account>;
+        attendance: Endpoint<Attendance, AttendanceQueryParams, 'user' | 'in_time'>;
+        auth: Endpoint<Auth>;
+        availability: Endpoint<Availability, AvailabilityQueryParams>;
+        daily_budgets: Endpoint<DailyBudgets, DailyBudgetsQueryParams>;
+        daily_revenue: Endpoint<DailyRevenue, DailyRevenueQueryParams>;
+        day_notes: Endpoint<DayNote, DayNotesQueryParams>;
+        days_off: Endpoint<DaysOff, DaysOffQueryParams>;
+        documents: Endpoint<Document, DocumentsQueryParams, 'name' | 'bucket' | 'key'>;
+        groups: Endpoint<Group, GroupsQueryParams, 'name'>;
+        leave_embargoes: Endpoint<LeaveEmbargo, LeaveEmbargoesQueryParams, 'start_date' | 'end_date' | 'users'>;
+        leave_requests: Endpoint<LeaveRequest, LeaveRequestsQueryParams, 'start_date' | 'end_date' | 'type' | 'user'>;
+        leave_types: Endpoint<LeaveType>;
+        leave: Endpoint<Leave, LeaveQueryParams, 'users' | 'type' | 'start_date' | 'end_date'>;
+        locations: Endpoint<Location, LocationsQueryParams, 'name'>;
+        pins: Endpoint<Pin>;
+        roles: Endpoint<Role, RolesQueryParams, 'name'>;
+        settings: Endpoint<Settings, SettingsQueryParams>;
+        shifts: Endpoint<Shift, ShiftsQueryParams, 'start_time' | 'end_time' | 'location'>;
+        terminals: Endpoint<Terminal, TerminalsQueryParams, 'name' | 'timezone'>;
+        terminals_active: Endpoint<Terminal>;
+        timezones: Endpoint<TimeZone>;
+        toil_accruals: Endpoint<ToilAccrual, ToilAccrualsQueryParams, 'duration_hours' | 'leave_year' | 'user_id'>;
+        toil_allowance: Endpoint<ToilAllowance, ToilAllowanceQueryParams>;
+        users_clocked_in: Endpoint<UserClockedIn, undefined, 'in_method'>;
+        users: Endpoint<User, UsersQueryParams, 'first_name' | 'last_name'>;
+    };
+    /** Type mappings for v2 endpoints */
+    v2: {};
+}

package/dist/interfaces/launch-terminal.interface.d.ts

@@ -0,0 +1,6 @@
+import { TerminalLocation } from './terminal.interface.js';
+export interface LaunchTerminal {
+    terminal: number;
+    device: string;
+    location?: TerminalLocation;
+}

package/dist/{mjs/interfaces → interfaces}/leave-request.interface.d.ts

@@ -1,4 +1,4 @@
-import { LeaveDate } from './leave-date.interface';
+import { LeaveDate } from './leave-date.interface.js';
 export interface LeaveRequest {
     id: number;
     deleted: boolean;

package/dist/{cjs/interfaces → interfaces}/leave.interface.d.ts

@@ -1,4 +1,4 @@
-import { LeaveRequest } from './leave-request.interface';
+import { LeaveRequest } from './leave-request.interface.js';
 export interface Leave extends LeaveRequest {
     admin: number;
     admin_message: string | null;

package/dist/{mjs/interfaces → interfaces}/query-params/toil-allowance-query-params.interface.d.ts

@@ -1,3 +1,4 @@
 export interface ToilAllowanceQueryParams {
+    year: number;
     users?: number[];
 }

package/dist/{cjs/interfaces → interfaces}/sdk-config.interface.d.ts

@@ -18,7 +18,13 @@ export type RetryOptions = {
 };
 type RequestInterceptor = Parameters<AxiosInterceptorManager<InternalAxiosRequestConfig>['use']>;
 type ResponseInterceptor = Parameters<AxiosInterceptorManager<AxiosResponse>['use']>;
-export interface SDKBase {
+export type SDKConfig = ({
+    apiKey: string;
+    basicAuth?: never;
+} | {
+    apiKey?: never;
+    basicAuth: string;
+}) & {
     baseUri?: string;
     accountId?: number;
     userId?: number;
@@ -34,14 +40,5 @@ export interface SDKBase {
         })[];
     };
     [key: string]: unknown;
-}
-export interface SDKBearerAuth extends SDKBase {
-    apiKey: string;
-    basicAuth?: never;
-}
-export interface SDKBasicAuth extends SDKBase {
-    apiKey?: never;
-    basicAuth: string;
-}
-export type SDKConfig = SDKBasicAuth | SDKBearerAuth;
+};
 export {};

package/dist/{mjs/interfaces → interfaces}/shift.interface.d.ts

@@ -23,3 +23,14 @@ export interface Shift {
     swap_requests: number[];
     unavailability_requests: number[];
 }
+export interface ShiftHistoryRecord {
+    changes?: {
+        key: string;
+        value: string;
+    }[];
+    colour: string | null;
+    icon: string | null;
+    text: string;
+    time: number;
+    user: number;
+}

package/dist/interfaces/user-clock-in.interface.d.ts

@@ -0,0 +1,18 @@
+import { TerminalLocation } from './terminal.interface.js';
+export interface UserClockIn {
+    method: string;
+    shift: number;
+    terminal?: number;
+    user: number;
+    photo?: string;
+    location?: TerminalLocation;
+}
+export interface UserClockOut extends Omit<UserClockIn, 'user' | 'shift'> {
+}
+export interface UserBreakRequest {
+    method: string;
+    action: string;
+    terminal: number;
+    photo?: string;
+    location: TerminalLocation;
+}

package/dist/interfaces/user-clock-in.interface.js

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

package/dist/{cjs/interfaces → interfaces}/user.interface.d.ts

@@ -36,7 +36,7 @@ export interface User {
     leave_rates_unit: string;
     leave_rates_type: string;
     notes: string | null;
-    pin: string | null;
+    pin?: string | null;
     salaried_cost_location: number | null;
     permissions: ManagerPermission[];
 }

package/dist/interfaces/user.interface.js

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

package/dist/interfaces/users-clocked-in.interface.js

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

package/dist/interfaces/users-clocked-out.interface.js

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