rotacloud 1.5.2 → 2.0.1

package/dist/service.js

@@ -0,0 +1,317 @@
+import { listAllOp, listOp, 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
+ * 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 }) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}`,
+                method: 'GET',
+            }),
+        },
+    },
+    availability: {
+        endpoint: 'availability',
+        endpointVersion: 'v1',
+        operations: ['update', 'create', 'delete', 'list', 'listAll'],
+        customOperations: {
+            update: ({ request, service }, entity) => ({
+                ...request,
+                method: 'POST',
+                url: `${service.endpointVersion}/${service.endpoint}`,
+                data: entity,
+            }),
+            delete: ({ request, service }, entity) => ({
+                ...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) => ({
+                ...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) => ({
+                ...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 }, entity, opts) => ({
+                ...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 }) => ({
+                ...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) => ({
+                ...request,
+                method: 'POST',
+                url: 'v1/shifts_acknowledged',
+                data: { shifts: shiftIds },
+            }),
+            history: ({ request, service }, id) => ({
+                ...request,
+                method: 'GET',
+                url: `v1/${service.endpoint}/${id}/history`,
+            }),
+            publish: ({ request }, shiftIds) => ({
+                ...request,
+                method: 'POST',
+                url: 'v1/shifts_published',
+                data: { shifts: shiftIds },
+            }),
+            unpublish: ({ request }, shiftIds) => ({
+                ...request,
+                method: 'DELETE',
+                url: 'v1/shifts_published',
+                data: { shifts: shiftIds },
+            }),
+            updateSwap: ({ request }, swapRequest) => {
+                let payload;
+                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,
+                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) => ({
+                ...request,
+                method: 'DELETE',
+                url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+            }),
+        },
+    },
+    terminalActive: {
+        endpoint: 'terminals',
+        endpointVersion: 'v1',
+        operations: ['list', 'listAll'],
+        customOperations: {
+            launch: ({ request, service }, id) => ({
+                ...request,
+                method: 'DELETE',
+                url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+            }),
+            ping: ({ request, service }, id) => ({
+                ...request,
+                method: 'DELETE',
+                url: `${service.endpointVersion}/${service.endpoint}/${id}`,
+            }),
+            close: ({ request, service }, id) => ({
+                ...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, opts) => 
+            // Maps the "year" query parameter into the endpoint URL
+            listOp({
+                ...ctx,
+                service: {
+                    ...ctx.service,
+                    endpoint: `${ctx.service.endpoint}/${query.year}`,
+                    endpointVersion: 'v1',
+                },
+            }, { users: query.users }, opts),
+            listAll: (ctx, query, opts) => 
+            // Maps the "year" query parameter into the endpoint URL
+            listAllOp({
+                ...ctx,
+                service: {
+                    ...ctx.service,
+                    endpoint: `${ctx.service.endpoint}/${query.year}`,
+                    endpointVersion: 'v1',
+                },
+            }, { users: query.users }, opts),
+        },
+    },
+    userClockIn: {
+        endpoint: 'users_clocked_in',
+        endpointVersion: 'v1',
+        operations: ['get', 'list', 'listAll'],
+        customOperations: {
+            clockIn: ({ request, service }, entity) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+                method: 'POST',
+                data: entity,
+            }),
+            clockOut: ({ request, service }, entity) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+                method: 'POST',
+                data: entity,
+            }),
+            startBreak: ({ request, service }, entity) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+                method: 'POST',
+                data: entity,
+            }),
+            endBreak: ({ request, service }, entity) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}/${entity.id}`,
+                method: 'POST',
+                data: entity,
+            }),
+        },
+    },
+    user: {
+        endpoint: 'users',
+        endpointVersion: 'v1',
+        operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
+    },
+};

package/dist/utils.d.ts

@@ -0,0 +1,41 @@
+import { Axios, AxiosRequestConfig } from 'axios';
+import { SDKConfig } from './interfaces/index.js';
+/** 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;
+    dryRun?: boolean;
+    fields?: T extends Object ? (keyof T)[] : never;
+}
+export declare function assert(value: unknown, message?: string | Error): asserts value;
+/** Creates and configures an Axios client for use in all calls to API endpoints
+ * according to the provided {@see SDKConfig}
+ */
+export declare function createCustomAxiosClient(config: Readonly<SDKConfig>): Axios;
+/** Utility for getting a basic {@see AxiosRequestConfig} for a given request ready
+ * for an {@see OpFunction} to adapt/use
+ */
+export declare function getBaseRequestConfig(opts: SDKConfig): AxiosRequestConfig<unknown>;
+/** 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 declare function defaultObject<T extends object>(obj: Readonly<T>, defaultObj: Readonly<Partial<T>>): T;
+export {};

package/dist/utils.js

@@ -0,0 +1,149 @@
+import axios, { isAxiosError } from 'axios';
+import axiosRetry, { isNetworkOrIdempotentRequestError } from 'axios-retry';
+import { RetryStrategy } from './interfaces/index.js';
+import { SDKError } from './models/index.js';
+import pkg from '../package.json' with { type: 'json' };
+const DEFAULT_RETRIES = 3;
+const DEFAULT_RETRY_DELAY = 2000;
+const DEFAULT_RETRY_STRATEGY_OPTIONS = {
+    [RetryStrategy.Exponential]: {
+        exponential: true,
+        maxRetries: DEFAULT_RETRIES,
+    },
+    [RetryStrategy.Static]: {
+        exponential: false,
+        maxRetries: DEFAULT_RETRIES,
+        delay: DEFAULT_RETRY_DELAY,
+    },
+};
+class AssertionError extends Error {
+    name = AssertionError.prototype.name;
+}
+export function assert(value, message) {
+    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) {
+    const queryParams = { ...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;
+    }, []);
+    return new URLSearchParams(reducedParams);
+}
+function parseClientError(error) {
+    const axiosErrorLocation = error.response || error.request;
+    const apiErrorMessage = axiosErrorLocation.data?.error;
+    let url;
+    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) {
+    let baseURL;
+    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) => {
+        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]
+            : [requestInterceptor?.success, requestInterceptor?.error];
+        axiosClient.interceptors.request.use(...callbacks);
+    }
+    for (const responseInterceptor of config?.interceptors?.response ?? []) {
+        const callbacks = typeof responseInterceptor === 'function'
+            ? [responseInterceptor]
+            : [responseInterceptor?.success, responseInterceptor?.error];
+        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) {
+    const headers = {};
+    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(obj, defaultObj) {
+    const defaulted = { ...obj };
+    for (const [key, value] of Object.entries(defaultObj)) {
+        defaulted[key] ??= value;
+    }
+    return defaulted;
+}

package/package.json

@@ -1,24 +1,23 @@
 {
   "name": "rotacloud",
-  "version": "1.5.2",
+  "version": "2.0.1",
   "description": "The RotaCloud SDK for the RotaCloud API",
+  "type": "module",
   "engines": {
-    "node": ">=16.10.0"
-  },
-  "main": "./dist/cjs/rotacloud.js",
-  "module": "./dist/mjs/rotacloud.js",
-  "exports": {
-    ".": {
-      "require": "./dist/cjs/rotacloud.js",
-      "import": "./dist/mjs/rotacloud.js"
-    }
+    "node": ">=18.18.0"
   },
+  "exports": "./dist/main.js",
+  "files": [
+    "src",
+    "dist",
+    "*.md"
+  ],
   "scripts": {
     "version:bump": "npm --no-git-tag-version version patch",
-    "watch": "rm -rf dist/* && concurrently \"tsc -p tsconfig.json --watch\" \"tsc -p tsconfig-cjs.json --watch\" && ./fixup",
-    "build": "rm -rf dist/* && tsc -p tsconfig.json && tsc -p tsconfig-cjs.json && ./fixup",
+    "watch": "rm -rf dist/* && tsc -p tsconfig.json --watch",
+    "build": "rm -rf dist/* && tsc -p tsconfig.json",
     "lint": "eslint src --ext .ts",
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -32,21 +31,21 @@
   },
   "homepage": "https://github.com/rotacloud/rotacloud-node#readme",
   "devDependencies": {
+    "@types/node": "^18.19.64",
     "@typescript-eslint/eslint-plugin": "^6.2.1",
     "@typescript-eslint/parser": "^6.3.0",
-    "concurrently": "^8.2.0",
     "eslint": "^8.46.0",
     "eslint-config-airbnb": "^19.0.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-airbnb-typescript": "^17.1.0",
     "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-import": "^2.28.0",
-    "prettier": "~3.2.2",
-    "typescript": "^5.3.3"
+    "eslint-plugin-import": "^2.31.0",
+    "prettier": "~3.4.1",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.6"
   },
   "dependencies": {
-    "@types/node": "^16.11.7",
-    "axios": "^1.6.5",
-    "axios-retry": "^4.0.0"
+    "axios": "^1.7.7",
+    "axios-retry": "^4.5.0"
   }
 }