rotacloud 1.5.2 → 2.0.0

package/src/client-builder.test.ts

@@ -0,0 +1,188 @@
+import { test, expect, describe, vi } from 'vitest';
+import { Axios } from 'axios';
+import { createSdkClient, DEFAULT_CONFIG } from './client-builder.js';
+import { SDKConfig } from './main.js';
+import pkg from '../package.json' with { type: 'json' };
+
+let mockAxiosClient: Axios;
+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
+  } as any;
+});
+
+const sdkConfig: 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/src/client-builder.ts

@@ -0,0 +1,118 @@
+import { Axios } from 'axios';
+import { createCustomAxiosClient, defaultObject, getBaseRequestConfig } from './utils.js';
+import { RetryStrategy, SDKConfig } from './interfaces/index.js';
+import { buildOp, getOpMap, OpDef, OperationContext } 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 const DEFAULT_CONFIG = {
+  baseUri: 'https://api.rotacloud.com',
+  retry: RetryStrategy.Exponential,
+} satisfies Partial<SDKConfig>;
+
+/** 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<Spec extends ServiceSpecification>(opContext: OperationContext): Service<Spec> {
+  const service = {};
+
+  const opMap = getOpMap<ExtractEndpoint<Spec>>();
+  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 as Service<Spec>;
+}
+
+/** Builds the entire SDK client ready to be exported by the library and used by an end
+ * user of the SDK
+ */
+export function createSdkClient<T extends Record<string, ServiceSpecification>>(
+  serviceMap: T,
+): (config: SDKConfig) => SdkClient<T> {
+  return (sdkConfig: SDKConfig) => {
+    let clientConfig = Object.freeze(defaultObject<SDKConfig>(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: SDKConfig) {
+        clientConfig = Object.freeze(defaultObject<SDKConfig>(val, DEFAULT_CONFIG));
+        axiosClient = createCustomAxiosClient(clientConfig);
+        requestConfig = getBaseRequestConfig(clientConfig);
+      },
+    } satisfies SdkClient<{}>;
+
+    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 as SdkClient<T>;
+  };
+}

package/src/endpoint.ts

@@ -0,0 +1,99 @@
+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/src/interfaces/launch-terminal.interface.ts

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

package/src/interfaces/leave-request.interface.ts

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

package/src/interfaces/leave.interface.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;

package/src/interfaces/query-params/toil-allowance-query-params.interface.ts

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

package/src/interfaces/sdk-config.interface.ts

@@ -24,7 +24,16 @@ 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;
@@ -46,16 +55,4 @@ 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;
+};

package/src/interfaces/shift.interface.ts

@@ -23,3 +23,15 @@ 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/src/interfaces/time-zone.interface.ts

@@ -1,7 +1,7 @@
 export interface TimeZone {
-    id: number;
-    name: string;
-    continent: string;
-    city: string;
-    sub: string;
-}
+  id: number;
+  name: string;
+  continent: string;
+  city: string;
+  sub: string;
+}

package/src/interfaces/user-clock-in.interface.ts

@@ -0,0 +1,20 @@
+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/src/interfaces/user.interface.ts

@@ -48,7 +48,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/src/main.ts

@@ -0,0 +1,7 @@
+import { createSdkClient } from './client-builder.js';
+import { SERVICES } from './service.js';
+
+export * from './interfaces/index.js';
+export * from './interfaces/query-params/index.js';
+export * from './models/index.js';
+export const createRotaCloudClient = createSdkClient(SERVICES);

package/src/models/SDKError.model.ts

@@ -1,20 +1,20 @@
-export interface SDKErrorConfig {
-  message?: string;
-  code?: number;
-  data?: unknown;
-}
 export class SDKError extends Error {
   override name = 'SDKError';
+  /** HTTP status code of the error */
   readonly code?: number;
+  /** Data returned by the API in the event of an error */
   readonly data?: unknown;
+  /** URL that triggered the error */
+  readonly url?: string;
 
-  constructor(errorConfig: SDKErrorConfig) {
+  constructor(errorConfig: { message?: string; code?: number; data?: unknown; url?: string }) {
     super(errorConfig.message);
 
-    Error.captureStackTrace?.(this, SDKError);
     // optional chaining needed as is v8 specific https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#static_methods
+    Error.captureStackTrace?.(this, SDKError);
 
-    this.data = errorConfig.data;
     this.code = errorConfig.code;
+    this.url = errorConfig.url;
+    this.data = errorConfig.data;
   }
 }

package/src/ops.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test, vi } from 'vitest';
+import { Axios } from 'axios';
+import { createSdkClient } from './client-builder.js';
+import { getOpMap } from './ops.js';
+import { ServiceSpecification } from './service.js';
+
+let mockAxiosClient: Axios;
+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
+  } as any;
+});
+
+describe('Operations', () => {
+  const service = {
+    endpoint: 'settings',
+    endpointVersion: 'v1',
+    operations: ['get', 'list'],
+    customOperations: {
+      promiseOp: async () => 3,
+    },
+  } satisfies ServiceSpecification;
+  const clientBuilder = createSdkClient({
+    service,
+  });
+  const client = clientBuilder({ basicAuth: '' });
+
+  test('operations returning a request config trigger a request call', async () => {
+    const basicOp = getOpMap().v1.get;
+    const basicOpRes = basicOp(
+      {
+        client: mockAxiosClient,
+        request: {},
+        service,
+        sdkConfig: { apiKey: '' },
+      },
+      1,
+    );
+    expect(basicOpRes).toStrictEqual(
+      expect.objectContaining({
+        method: 'GET',
+      }),
+    );
+
+    await client.service.get(1);
+    expect(mockAxiosClient.request).toHaveBeenCalledWith(expect.objectContaining(basicOpRes));
+  });
+
+  test('operations returning a promise are returned as is', async () => {
+    const promiseOpRes = await service.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: [],
+      });
+
+      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);
+    });
+  });
+});