rotacloud 1.5.2 → 2.0.1

package/src/service.ts

@@ -0,0 +1,395 @@
+import { EndpointEntityMap } from './endpoint.js';
+import {
+  Auth,
+  Availability,
+  DailyBudgets,
+  DailyRevenue,
+  Leave,
+  LeaveType,
+  ShiftHistoryRecord,
+  Terminal,
+  ToilAllowance,
+  UserBreak,
+  UserClockedIn,
+  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 { 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';
+
+export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
+  /** Operations allowed and usable for the endpoint */
+  operations: Operation[];
+  /**
+   * Operations unique to the service
+   * Can be used to override operations listed in {@see ServiceSpecification['operations']}
+   */
+  customOperations?: Record<string, CustomOp>;
+} & (
+  | {
+      /** URL of the endpoint */
+      endpoint: keyof EndpointEntityMap['v1'];
+      /** API version of the endpoint */
+      endpointVersion: 'v1';
+    }
+  | {
+      /** URL of the endpoint */
+      endpoint: keyof EndpointEntityMap['v2'];
+      /** API version of the endpoint */
+      endpointVersion: 'v2';
+    }
+);
+
+/**
+ * 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
+ * definition conforming to the {@see ServiceSpecification} type
+ */
+export const SERVICES = {
+  account: {
+    endpoint: 'accounts',
+    endpointVersion: 'v1',
+    operations: ['get', 'list', 'listAll'],
+  },
+  attendance: {
+    endpoint: 'attendance',
+    endpointVersion: 'v1',
+    operations: ['get', 'list', 'listAll', 'delete', 'create', 'update'],
+  },
+  auth: {
+    endpoint: 'auth',
+    endpointVersion: 'v1',
+    operations: [],
+    customOperations: {
+      get: ({ request, service }): RequestConfig<void, Auth> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        method: 'GET',
+      }),
+    },
+  },
+  availability: {
+    endpoint: 'availability',
+    endpointVersion: 'v1',
+    operations: ['update', 'create', 'delete', 'list', 'listAll'],
+    customOperations: {
+      update: ({ request, service }, entity: Availability): RequestConfig<typeof entity, Availability> => ({
+        ...request,
+        method: 'POST',
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        data: entity,
+      }),
+      delete: (
+        { request, service },
+        entity: { user: number; dates: string[] },
+      ): RequestConfig<Availability, Availability> => ({
+        ...request,
+        method: 'POST',
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        data: {
+          ...entity,
+          dates: entity.dates.map((date) => ({
+            date,
+            available: [],
+            unavailable: [],
+          })),
+        },
+      }),
+    },
+  },
+  dailyBudget: {
+    endpoint: 'daily_budgets',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll', 'updateBatch'],
+    customOperations: {
+      updateBatch: ({ request, service }, entities: DailyBudgets[]): RequestConfig<typeof entities, void> => ({
+        ...request,
+        method: 'POST',
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        data: entities,
+      }),
+    },
+  },
+  dailyRevenue: {
+    endpoint: 'daily_revenue',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll', 'updateBatch'],
+    customOperations: {
+      updateBatch: ({ request, service }, entities: DailyRevenue[]): RequestConfig<typeof entities, void> => ({
+        ...request,
+        method: 'POST',
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        data: entities,
+      }),
+    },
+  },
+  dayNote: {
+    endpoint: 'day_notes',
+    endpointVersion: 'v1',
+    operations: ['get', 'create', 'list', 'listAll', 'update', 'delete'],
+  },
+  dayOff: {
+    endpoint: 'days_off',
+    endpointVersion: 'v1',
+    operations: ['create', 'list', 'listAll', 'delete'],
+  },
+  document: {
+    endpoint: 'documents',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  group: {
+    endpoint: 'groups',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  leaveEmbargo: {
+    endpoint: 'leave_embargoes',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  leaveRequest: {
+    endpoint: 'leave_requests',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  leave: {
+    endpoint: 'leave',
+    endpointVersion: 'v1',
+    operations: ['get', 'list', 'listAll', 'delete', 'create', 'update'],
+    customOperations: {
+      create: (
+        { request, service, sdkConfig }: OperationContext,
+        entity: EndpointEntityMap['v1']['leave']['createType'],
+        opts?: RequestOptions<Leave>,
+      ): RequestConfig<typeof entity, Leave[]> => ({
+        ...request,
+        method: 'POST',
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        data: entity,
+        headers: {
+          ...request.headers,
+          Account: sdkConfig.accountId,
+          User: entity.user,
+        },
+        params: {
+          ...request.params,
+          ...paramsFromOptions(opts ?? {}),
+        },
+      }),
+      types: ({ request }): RequestConfig<void, LeaveType[]> => ({
+        ...request,
+        method: 'GET',
+        url: 'v1/leave_types',
+      }),
+    },
+  },
+  location: {
+    endpoint: 'locations',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  pin: {
+    endpoint: 'pins',
+    endpointVersion: 'v1',
+    operations: ['get'],
+  },
+  role: {
+    endpoint: 'roles',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+  settings: {
+    endpoint: 'settings',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll'],
+  },
+  shift: {
+    endpoint: 'shifts',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'updateBatch', 'delete', 'deleteBatch'],
+    customOperations: {
+      acknowledge: ({ request }, shiftIds: number[]): RequestConfig<{ shifts: number[] }, void> => ({
+        ...request,
+        method: 'POST',
+        url: 'v1/shifts_acknowledged',
+        data: { shifts: shiftIds },
+      }),
+      history: ({ request, service }, id: number): RequestConfig<void, ShiftHistoryRecord[]> => ({
+        ...request,
+        method: 'GET',
+        url: `v1/${service.endpoint}/${id}/history`,
+      }),
+      publish: ({ request }, shiftIds: number[]): RequestConfig<{ shifts: number[] }, void> => ({
+        ...request,
+        method: 'POST',
+        url: 'v1/shifts_published',
+        data: { shifts: shiftIds },
+      }),
+      unpublish: ({ request }, shiftIds: number[]): RequestConfig<{ shifts: number[] }, void> => ({
+        ...request,
+        method: 'DELETE',
+        url: 'v1/shifts_published',
+        data: { shifts: shiftIds },
+      }),
+      updateSwap: (
+        { request },
+        swapRequest: RequirementsOf<ShiftSwapRequest, 'id'>,
+      ): RequestConfig<{ admin_approved: boolean } | { user_approved: boolean }, ShiftSwapRequest> => {
+        let payload: { admin_approved: boolean } | { user_approved: boolean } | undefined;
+        if (swapRequest.admin_approved !== null && swapRequest.admin_approved !== undefined) {
+          payload = { admin_approved: swapRequest.admin_approved };
+        } else if (swapRequest.user_approved !== null && swapRequest.user_approved !== undefined) {
+          payload = { user_approved: swapRequest.user_approved };
+        }
+
+        return {
+          ...request,
+          method: 'POST',
+          url: `v1/swap_requests/${swapRequest.id}`,
+          data: payload,
+        };
+      },
+      updateDrop: (
+        { request },
+        dropRequest: { request: RequirementsOf<ShiftDropRequest, 'id' | 'user_message'>; approved: boolean },
+      ): RequestConfig<{ message: string }, ShiftDropRequest> => ({
+        ...request,
+        method: 'POST',
+        url: `v1/unavailability_requests/${dropRequest.request.id}/${dropRequest.approved ? 'approve' : 'deny'}`,
+        data: { message: dropRequest.request.user_message },
+      }),
+    },
+  },
+  terminal: {
+    endpoint: 'terminals',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'update', 'list', 'listAll'],
+    customOperations: {
+      close: ({ request, service }, id: number): RequestConfig<void, void> => ({
+        ...request,
+        method: 'DELETE',
+        url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+      }),
+    },
+  },
+  terminalActive: {
+    endpoint: 'terminals',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll'],
+    customOperations: {
+      launch: ({ request, service }, id: LaunchTerminal): RequestConfig<void, Terminal> => ({
+        ...request,
+        method: 'DELETE',
+        url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+      }),
+      ping: ({ request, service }, id: { id: number; action: string; device: string }): RequestConfig<void, void> => ({
+        ...request,
+        method: 'DELETE',
+        url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+      }),
+      close: ({ request, service }, id: number): RequestConfig<void, void> => ({
+        ...request,
+        method: 'DELETE',
+        url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+      }),
+    },
+  },
+  timeZone: {
+    endpoint: 'timezones',
+    endpointVersion: 'v1',
+    operations: ['get', 'list', 'listAll'],
+  },
+  toilAccrual: {
+    endpoint: 'toil_accruals',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'listByPage', 'delete'],
+  },
+  toilAllowance: {
+    endpoint: 'toil_allowance',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll'],
+    customOperations: {
+      list: (ctx, query: ToilAllowanceQueryParams, opts) =>
+        // Maps the "year" query parameter into the endpoint URL
+        listOp<ToilAllowance, Omit<typeof query, 'year'>>(
+          {
+            ...ctx,
+            service: {
+              ...ctx.service,
+              endpoint: `${ctx.service.endpoint}/${query.year}` as typeof ctx.service.endpoint,
+              endpointVersion: 'v1',
+            },
+          },
+          { users: query.users },
+          opts,
+        ),
+      listAll: (ctx, query: ToilAllowanceQueryParams, opts) =>
+        // Maps the "year" query parameter into the endpoint URL
+        listAllOp<ToilAllowance, Omit<typeof query, 'year'>>(
+          {
+            ...ctx,
+            service: {
+              ...ctx.service,
+              endpoint: `${ctx.service.endpoint}/${query.year}` as typeof ctx.service.endpoint,
+              endpointVersion: 'v1',
+            },
+          },
+          { users: query.users },
+          opts,
+        ),
+    },
+  },
+  userClockIn: {
+    endpoint: 'users_clocked_in',
+    endpointVersion: 'v1',
+    operations: ['get', 'list', 'listAll'],
+    customOperations: {
+      clockIn: (
+        { request, service },
+        entity: { id: number } & RequirementsOf<UserClockIn, 'method'>,
+      ): RequestConfig<typeof entity, UserClockedIn> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+        method: 'POST',
+        data: entity,
+      }),
+      clockOut: (
+        { request, service },
+        entity: { id: number } & RequirementsOf<UserClockOut, 'method'>,
+      ): RequestConfig<typeof entity, UserClockedOut> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+        method: 'POST',
+        data: entity,
+      }),
+      startBreak: (
+        { request, service },
+        entity: { id: number } & RequirementsOf<UserBreakRequest, 'method' | 'action'>,
+      ): RequestConfig<typeof entity, UserBreak> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+        method: 'POST',
+        data: entity,
+      }),
+      endBreak: (
+        { request, service },
+        entity: { id: number } & RequirementsOf<UserBreakRequest, 'method' | 'action'>,
+      ): RequestConfig<typeof entity, UserBreak> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+        method: 'POST',
+        data: entity,
+      }),
+    },
+  },
+  user: {
+    endpoint: 'users',
+    endpointVersion: 'v1',
+    operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+  },
+} satisfies Record<string, ServiceSpecification>;

package/src/utils.ts

@@ -0,0 +1,193 @@
+import axios, { Axios, AxiosError, AxiosRequestConfig, isAxiosError } from 'axios';
+import axiosRetry, { isNetworkOrIdempotentRequestError } from 'axios-retry';
+import { RetryOptions, RetryStrategy, SDKConfig } from './interfaces/index.js';
+import { SDKError } from './models/index.js';
+import pkg from '../package.json' with { type: 'json' };
+
+/** Creates a `Partial<T>` where all properties specified by `K` are required
+ *
+ * e.g.
+ * `RequirementsOf<{id: number, user: number, location: number}, "id" | "user">` is
+ * equivalent to `{id: number, user: number, location?: number}`
+ * */
+export type RequirementsOf<T, K extends keyof T> = Required<Pick<T, K>> & Partial<T>;
+
+/** Supported primitive/atomic types for query parameters */
+type QueryParameterPrimitive = string | boolean | number | null | symbol;
+/** Supported types for query parameters */
+export type QueryParameterValue = QueryParameterPrimitive | QueryParameterPrimitive[] | undefined;
+
+/** SDK specific options for configuring a request */
+export interface RequestOptions<T> {
+  /** Client side option to determine whether to return the entire response
+   * including metadata such as status code and headers */
+  rawResponse?: boolean;
+  /** The maximum number of entities to return
+   *
+   * Once the limit is reached, paginated requests will stop automatically */
+  maxResults?: number;
+  /* Prevent the API from committing to a desired action */
+  dryRun?: boolean;
+  /* Specify which fields should be returned for an entity */
+  fields?: T extends Object ? (keyof T)[] : never;
+}
+
+const DEFAULT_RETRIES = 3;
+const DEFAULT_RETRY_DELAY = 2000;
+const DEFAULT_RETRY_STRATEGY_OPTIONS: Record<RetryStrategy, RetryOptions> = {
+  [RetryStrategy.Exponential]: {
+    exponential: true,
+    maxRetries: DEFAULT_RETRIES,
+  },
+  [RetryStrategy.Static]: {
+    exponential: false,
+    maxRetries: DEFAULT_RETRIES,
+    delay: DEFAULT_RETRY_DELAY,
+  },
+};
+
+class AssertionError extends Error {
+  override name = AssertionError.prototype.name;
+}
+
+export function assert(value: unknown, message?: string | Error): asserts value {
+  if (value) return;
+  if (!message || typeof message === 'string')
+    throw new AssertionError(message ?? `Assertion failed - value = ${value}`);
+  throw message;
+}
+
+/** Converts a map of query parameter key/values into API compatible {@see URLSearchParams} */
+function toSearchParams(parameters?: Record<string, QueryParameterValue>): URLSearchParams {
+  const queryParams: Record<string, QueryParameterValue> = { ...parameters };
+  const reducedParams = Object.entries(queryParams ?? {}).reduce((params, [key, val]) => {
+    if (val !== undefined && val !== '') {
+      if (Array.isArray(val)) params.push(...val.map((item) => [`${key}[]`, String(item)]));
+      else params.push([key, String(val)]);
+    }
+    return params;
+  }, [] as string[][]);
+
+  return new URLSearchParams(reducedParams);
+}
+
+function parseClientError(error: AxiosError): SDKError {
+  const axiosErrorLocation = error.response || error.request;
+  const apiErrorMessage = axiosErrorLocation.data?.error;
+  let url: URL | undefined;
+  try {
+    url = new URL(error.config?.url ?? '', error.config?.baseURL);
+    for (const [key, value] of toSearchParams(error.config?.params)) {
+      url.searchParams.set(key, value);
+    }
+  } catch (err) {
+    url = undefined;
+  }
+  return new SDKError({
+    url: url?.toString(),
+    code: axiosErrorLocation.status,
+    message: apiErrorMessage || error.message,
+    data: axiosErrorLocation.data,
+  });
+}
+
+/** Creates and configures an Axios client for use in all calls to API endpoints
+ * according to the provided {@see SDKConfig}
+ */
+export function createCustomAxiosClient(config: Readonly<SDKConfig>): Axios {
+  let baseURL: string | undefined;
+  try {
+    baseURL = new URL(config?.baseUri ?? '').toString();
+  } catch {
+    baseURL = undefined;
+  }
+  assert(baseURL !== undefined, `Must have a valid base URL. Got: ${config.baseUri}`);
+  const axiosClient = axios.create({
+    baseURL,
+    paramsSerializer: (params) => toSearchParams({ ...params, exclude_link_header: true }).toString(),
+  });
+
+  // NOTE: Retry interceptor - must be setup first
+  if (config?.retry) {
+    const retryConfig = typeof config.retry === 'string' ? DEFAULT_RETRY_STRATEGY_OPTIONS[config.retry] : config.retry;
+
+    axiosRetry(axiosClient, {
+      retries: retryConfig.maxRetries,
+      shouldResetTimeout: true,
+      retryCondition: (err) => isNetworkOrIdempotentRequestError(err) || err.response?.status === 429,
+      retryDelay: (retryCount) => {
+        if (retryConfig.exponential) {
+          return axiosRetry.exponentialDelay(retryCount);
+        }
+        return retryConfig.delay;
+      },
+    });
+  }
+  // NOTE: Error interceptor - must be setup after retry but before custom
+  axiosClient.interceptors.response.use(
+    (response) => response,
+    (error: unknown) => {
+      let parsedError = error;
+      if (isAxiosError(error)) {
+        parsedError = parseClientError(error);
+      }
+      return Promise.reject(parsedError);
+    },
+  );
+
+  // NOTE: Custom interceptors - must be setup last
+  for (const requestInterceptor of config?.interceptors?.request ?? []) {
+    const callbacks =
+      typeof requestInterceptor === 'function'
+        ? ([requestInterceptor] as const)
+        : ([requestInterceptor?.success, requestInterceptor?.error] as const);
+    axiosClient.interceptors.request.use(...callbacks);
+  }
+  for (const responseInterceptor of config?.interceptors?.response ?? []) {
+    const callbacks =
+      typeof responseInterceptor === 'function'
+        ? ([responseInterceptor] as const)
+        : ([responseInterceptor?.success, responseInterceptor?.error] as const);
+    axiosClient.interceptors.response.use(...callbacks);
+  }
+
+  return axiosClient;
+}
+
+/** Utility for getting a basic {@see AxiosRequestConfig} for a given request ready
+ * for an {@see OpFunction} to adapt/use
+ */
+export function getBaseRequestConfig(opts: SDKConfig): AxiosRequestConfig<unknown> {
+  const headers: Record<string, string> = {};
+
+  const extraHeaders = opts.headers;
+  if (extraHeaders && typeof extraHeaders === 'object') {
+    for (const [key, val] of Object.entries(extraHeaders)) {
+      headers[key] = String(val);
+    }
+  }
+  if (opts.accountId) {
+    headers.Account = String(opts.accountId);
+  }
+
+  // Set last to prevent being overridden
+  headers.Authorization = opts.apiKey ? `Bearer ${opts.apiKey}` : `Basic ${opts.basicAuth}`;
+  headers['SDK-Version'] = pkg.version;
+
+  return {
+    headers,
+  };
+}
+
+/** Defaults all undefined properties in a given object with the value specified
+ * in the provided {@see defaultObj} parameter
+ *
+ * This returns a new object and does not modify {@see obj}
+ */
+export function defaultObject<T extends object>(obj: Readonly<T>, defaultObj: Readonly<Partial<T>>): T {
+  const defaulted = { ...obj };
+  for (const [key, value] of Object.entries(defaultObj)) {
+    defaulted[key] ??= value;
+  }
+  return defaulted;
+}

package/.eslintignore

@@ -1,5 +0,0 @@
-node_modules
-dist
-coverage
-.eslintrc
-version.ts

package/.eslintrc.json

@@ -1,27 +0,0 @@
-{
-  "env": {
-    "es2021": true,
-    "node": true
-  },
-  "extends": ["airbnb-base", "airbnb-typescript/base", "prettier"],
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "ecmaVersion": 13,
-    "sourceType": "module",
-    "project": "./tsconfig.json"
-  },
-  "plugins": ["@typescript-eslint"],
-  "rules": {
-    "@typescript-eslint/no-useless-constructor": ["off"],
-    "@typescript-eslint/no-unused-vars": ["warn"],
-    "@typescript-eslint/no-unused-expressions": ["off"],
-    "@typescript-eslint/no-shadow": ["warn"],
-    "@typescript-eslint/lines-between-class-members": ["off"],
-    "no-restricted-syntax": ["off"],
-    "import/prefer-default-export": ["off"],
-    "max-classes-per-file": ["off"],
-    "class-methods-use-this": ["off"],
-    "no-await-in-loop": ["off"],
-    "no-param-reassign": ["error", { "props": false }]
-  }
-}

package/.gitattributes

@@ -1 +0,0 @@
-* text=auto

package/.github/workflows/check.yml

@@ -1,36 +0,0 @@
-name: Check
-on:
-  workflow_call:
-    inputs:
-      NODE_VERSION:
-        type: string
-        description: 'The version of Node to run the checks with'
-        default: 16.10
-  pull_request:
-    branches: [develop]
-
-jobs:
-  checks:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Use Node.js ${{ inputs.NODE_VERSION }}
-        uses: actions/setup-node@v3
-        with:
-          node-version: ${{ inputs.NODE_VERSION }}
-          cache: 'npm'
-          registry-url: https://registry.npmjs.org/
-
-      - name: npm install
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Build
-        run: npm run build --if-present
-
-      - name: Publishable
-        run: npm publish --dry-run