rotacloud 1.5.1 → 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

@@ -1,5 +1,17 @@
 import { LeaveRate, RoleRate, TerminalLocation } from './index.js';
 
+export type ManagerPermission =
+  | 'rotas'
+  | 'rota_requests'
+  | 'leave_requests'
+  | 'leave_self'
+  | 'leave_embargoes'
+  | 'employees'
+  | 'employees_salary'
+  | 'timesheets'
+  | 'payroll'
+  | 'roles'
+  | 'reports';
 export interface User {
   id: number;
   created_at: number;
@@ -7,7 +19,7 @@ export interface User {
   deleted: boolean;
   deleted_at: number | null;
   deleted_by: number | null;
-  level: string;
+  level: 'admin' | 'employee' | 'manager';
   first_name: string;
   middle_name: string | null;
   last_name: string;
@@ -29,16 +41,16 @@ export interface User {
   holiday_allowance_unit: string;
   payroll_id: string | null;
   salary: number;
-  salary_type: string;
+  salary_type: 'annual' | 'hourly';
   overtime_rate: number;
   role_rates: RoleRate | null;
   leave_rates: LeaveRate;
   leave_rates_unit: string;
   leave_rates_type: string;
   notes: string | null;
-  pin: string | null;
+  pin?: string | null;
   salaried_cost_location: number | null;
-  permissions: string[] | null;
+  permissions: ManagerPermission[];
 }
 
 export interface UserBreak {

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;
   }
 }