rotacloud 1.5.1 → 2.0.0

package/dist/main.d.ts

@@ -0,0 +1,203 @@
+export * from './interfaces/index.js';
+export * from './interfaces/query-params/index.js';
+export * from './models/index.js';
+export declare const createRotaCloudClient: (config: import("./interfaces/sdk-config.interface.js").SDKConfig) => import("./client-builder.js").SdkClient<{
+    account: {
+        endpoint: "accounts";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll")[];
+    };
+    attendance: {
+        endpoint: "attendance";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    auth: {
+        endpoint: "auth";
+        endpointVersion: "v1";
+        operations: never[];
+        customOperations: {
+            get: ({ request, service }: import("./ops.js").OperationContext) => import("./ops.js").RequestConfig<void, import("./interfaces/auth.interface.js").Auth>;
+        };
+    };
+    availability: {
+        endpoint: "availability";
+        endpointVersion: "v1";
+        operations: ("delete" | "list" | "listAll" | "create" | "update")[];
+        customOperations: {
+            update: ({ request, service }: import("./ops.js").OperationContext, entity: import("./interfaces/availability.interface.js").Availability) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/availability.interface.js").Availability>;
+            delete: ({ request, service }: import("./ops.js").OperationContext, entity: {
+                user: number;
+                dates: string[];
+            }) => import("./ops.js").RequestConfig<import("./interfaces/availability.interface.js").Availability, import("./interfaces/availability.interface.js").Availability>;
+        };
+    };
+    dailyBudget: {
+        endpoint: "daily_budgets";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "updateBatch")[];
+        customOperations: {
+            updateBatch: ({ request, service }: import("./ops.js").OperationContext, entities: import("./interfaces/daily-budgets.interface.js").DailyBudgets[]) => import("./ops.js").RequestConfig<typeof entities, void>;
+        };
+    };
+    dailyRevenue: {
+        endpoint: "daily_revenue";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "updateBatch")[];
+        customOperations: {
+            updateBatch: ({ request, service }: import("./ops.js").OperationContext, entities: import("./interfaces/daily-revenue.interface.js").DailyRevenue[]) => import("./ops.js").RequestConfig<typeof entities, void>;
+        };
+    };
+    dayNote: {
+        endpoint: "day_notes";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    dayOff: {
+        endpoint: "days_off";
+        endpointVersion: "v1";
+        operations: ("delete" | "list" | "listAll" | "create")[];
+    };
+    document: {
+        endpoint: "documents";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    group: {
+        endpoint: "groups";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    leaveEmbargo: {
+        endpoint: "leave_embargoes";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    leaveRequest: {
+        endpoint: "leave_requests";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    leave: {
+        endpoint: "leave";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+        customOperations: {
+            create: ({ request, service, sdkConfig }: import("./ops.js").OperationContext, entity: import("./endpoint.js").EndpointEntityMap["v1"]["leave"]["createType"], opts?: import("./utils.js").RequestOptions<import("./interfaces/leave.interface.js").Leave>) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/leave.interface.js").Leave[]>;
+            types: ({ request }: import("./ops.js").OperationContext) => import("./ops.js").RequestConfig<void, import("./interfaces/leave-type.interface.js").LeaveType[]>;
+        };
+    };
+    location: {
+        endpoint: "locations";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+    pin: {
+        endpoint: "pins";
+        endpointVersion: "v1";
+        operations: "get"[];
+    };
+    role: {
+        endpoint: "roles";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll")[];
+    };
+    settings: {
+        endpoint: "settings";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll")[];
+    };
+    shift: {
+        endpoint: "shifts";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "deleteBatch" | "create" | "update" | "updateBatch")[];
+        customOperations: {
+            acknowledge: ({ request }: import("./ops.js").OperationContext, shiftIds: number[]) => import("./ops.js").RequestConfig<{
+                shifts: number[];
+            }, void>;
+            history: ({ request, service }: import("./ops.js").OperationContext, id: number) => import("./ops.js").RequestConfig<void, import("./interfaces/shift.interface.js").ShiftHistoryRecord[]>;
+            publish: ({ request }: import("./ops.js").OperationContext, shiftIds: number[]) => import("./ops.js").RequestConfig<{
+                shifts: number[];
+            }, void>;
+            unpublish: ({ request }: import("./ops.js").OperationContext, shiftIds: number[]) => import("./ops.js").RequestConfig<{
+                shifts: number[];
+            }, void>;
+            updateSwap: ({ request }: import("./ops.js").OperationContext, swapRequest: import("./utils.js").RequirementsOf<import("./interfaces/swap-request.interface.js").ShiftSwapRequest, "id">) => import("./ops.js").RequestConfig<{
+                admin_approved: boolean;
+            } | {
+                user_approved: boolean;
+            }, import("./interfaces/swap-request.interface.js").ShiftSwapRequest>;
+            updateDrop: ({ request }: import("./ops.js").OperationContext, dropRequest: {
+                request: import("./utils.js").RequirementsOf<import("./interfaces/drop-request.interface.js").ShiftDropRequest, "id" | "user_message">;
+                approved: boolean;
+            }) => import("./ops.js").RequestConfig<{
+                message: string;
+            }, import("./interfaces/drop-request.interface.js").ShiftDropRequest>;
+        };
+    };
+    terminal: {
+        endpoint: "terminals";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll" | "create" | "update")[];
+        customOperations: {
+            close: ({ request, service }: import("./ops.js").OperationContext, id: number) => import("./ops.js").RequestConfig<void, void>;
+        };
+    };
+    terminalActive: {
+        endpoint: "terminals";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll")[];
+        customOperations: {
+            launch: ({ request, service }: import("./ops.js").OperationContext, id: import("./interfaces/launch-terminal.interface.js").LaunchTerminal) => import("./ops.js").RequestConfig<void, import("./interfaces/terminal.interface.js").Terminal>;
+            ping: ({ request, service }: import("./ops.js").OperationContext, id: {
+                id: number;
+                action: string;
+                device: string;
+            }) => import("./ops.js").RequestConfig<void, void>;
+            close: ({ request, service }: import("./ops.js").OperationContext, id: number) => import("./ops.js").RequestConfig<void, void>;
+        };
+    };
+    timeZone: {
+        endpoint: "timezones";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll")[];
+    };
+    toilAccrual: {
+        endpoint: "toil_accruals";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "listByPage" | "create")[];
+    };
+    toilAllowance: {
+        endpoint: "toil_allowance";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll")[];
+        customOperations: {
+            list: (ctx: import("./ops.js").OperationContext, query: import("./interfaces/query-params/toil-allowance-query-params.interface.js").ToilAllowanceQueryParams, opts: import("./utils.js").RequestOptions<unknown> | undefined) => AsyncGenerator<import("./interfaces/toil-allowance.interface.js").ToilAllowance, any, any>;
+            listAll: (ctx: import("./ops.js").OperationContext, query: import("./interfaces/query-params/toil-allowance-query-params.interface.js").ToilAllowanceQueryParams, opts: import("./utils.js").RequestOptions<unknown> | undefined) => Promise<import("./interfaces/toil-allowance.interface.js").ToilAllowance[]>;
+        };
+    };
+    userClockIn: {
+        endpoint: "users_clocked_in";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll")[];
+        customOperations: {
+            clockIn: ({ request, service }: import("./ops.js").OperationContext, entity: {
+                id: number;
+            } & import("./utils.js").RequirementsOf<import("./interfaces/user-clock-in.interface.js").UserClockIn, "method">) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/users-clocked-in.interface.js").UserClockedIn>;
+            clockOut: ({ request, service }: import("./ops.js").OperationContext, entity: {
+                id: number;
+            } & import("./utils.js").RequirementsOf<import("./interfaces/user-clock-in.interface.js").UserClockOut, "method">) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/users-clocked-out.interface.js").UserClockedOut>;
+            startBreak: ({ request, service }: import("./ops.js").OperationContext, entity: {
+                id: number;
+            } & import("./utils.js").RequirementsOf<import("./interfaces/user-clock-in.interface.js").UserBreakRequest, "method" | "action">) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/user.interface.js").UserBreak>;
+            endBreak: ({ request, service }: import("./ops.js").OperationContext, entity: {
+                id: number;
+            } & import("./utils.js").RequirementsOf<import("./interfaces/user-clock-in.interface.js").UserBreakRequest, "method" | "action">) => import("./ops.js").RequestConfig<typeof entity, import("./interfaces/user.interface.js").UserBreak>;
+        };
+    };
+    user: {
+        endpoint: "users";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+}>;

package/dist/main.js

@@ -0,0 +1,6 @@
+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/dist/models/SDKError.model.d.ts

@@ -0,0 +1,15 @@
+export declare class SDKError extends Error {
+    name: string;
+    /** 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: {
+        message?: string;
+        code?: number;
+        data?: unknown;
+        url?: string;
+    });
+}

package/dist/{mjs/models → models}/SDKError.model.js

@@ -1,10 +1,17 @@
 export class SDKError extends Error {
+    name = 'SDKError';
+    /** HTTP status code of the error */
+    code;
+    /** Data returned by the API in the event of an error */
+    data;
+    /** URL that triggered the error */
+    url;
     constructor(errorConfig) {
         super(errorConfig.message);
-        this.name = 'SDKError';
-        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
-        this.data = errorConfig.data;
+        Error.captureStackTrace?.(this, SDKError);
         this.code = errorConfig.code;
+        this.url = errorConfig.url;
+        this.data = errorConfig.data;
     }
 }

package/dist/ops.d.ts

@@ -0,0 +1,195 @@
+import { Axios, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { ServiceSpecification } from './service.js';
+import { RequestOptions, QueryParameterValue, RequirementsOf } from './utils.js';
+import { Endpoint } from './endpoint.js';
+import { SDKConfig } from './main.js';
+/** Supported common operations */
+export type Operation = 'get' | 'list' | 'listAll' | 'listByPage' | 'delete' | 'deleteBatch' | 'create' | 'update' | 'updateBatch';
+/** Context provided to all operations */
+export type OperationContext = {
+    client: Readonly<Axios>;
+    request: Readonly<AxiosRequestConfig>;
+    service: Readonly<ServiceSpecification>;
+    sdkConfig: Readonly<SDKConfig>;
+};
+/** Defines the mapping between the data sent for a given request (e.g with
+ * "POST" method) and the return type expected back
+ *
+ * NOTE: This is not type safe on purpose. There is no way to guarantee that a
+ * given HTTP call will return a specific type in TS alone
+ */
+export type RequestConfig<RequestData, ResponseData> = AxiosRequestConfig<RequestData>;
+/** Function to define an {@see OpFunction}
+ *
+ * This is intended as a convenient way of defining {@see OpFunction}s that can then be
+ * "built" ready for the end user to call ({@see buildOp})
+ * */
+export type OpDef<T, Param = any, Opts extends Partial<RequestOptions<any>> = RequestOptions<unknown>, Return = T> = ((ctx: OperationContext, param: Param, opts?: Opts) => RequestConfig<T, Return>) | ((ctx: OperationContext, param: Param, opts?: Opts) => AsyncIterable<T>) | ((ctx: OperationContext, param: Param, opts?: Opts) => Promise<T>);
+/** Operation function type to be called by the end user of the SDK.
+ *
+ * All methods on services follow this typing
+ * */
+export type OpFunction<R = any, Param = undefined, Opts = RequestOptions<unknown>> = R extends AsyncIterable<infer U> | Promise<Iterable<infer U>> ? Param extends undefined ? {
+    (query?: Param): R;
+    <F extends keyof U>(query: Param, options: {
+        fields: F[];
+    } & RequestOptions<U>): R extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : R extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query: Param, options?: Opts): R;
+} : Partial<Param> extends Param ? {
+    (query?: Param): R;
+    <F extends keyof U>(query: Param, options: {
+        fields: F[];
+    } & RequestOptions<U>): R extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : R extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query?: Param, options?: Opts): R;
+} : {
+    (query: Param): R;
+    <F extends keyof U>(query: Param, options: {
+        fields: F[];
+    } & RequestOptions<U>): R extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : R extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query: Param, Options?: Opts): R;
+} : Param extends number ? {
+    (id: Param): R;
+    <F extends keyof Awaited<R>>(id: Param, options: {
+        fields: F[];
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
+    <F extends keyof Awaited<R>>(id: Param, options: {
+        fields: F[];
+    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
+    (id: Param, options?: {
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
+    (id: Param, options?: RequestOptions<Awaited<R>>): R;
+} : Param extends undefined ? {
+    (entity?: Param): R;
+    <F extends keyof Awaited<R>>(entity: Param, options: {
+        fields: F[];
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
+    <F extends keyof Awaited<R>>(entity: Param, options: {
+        fields: F[];
+    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
+    (entity?: Param, options?: {
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
+    (entity?: Param, options?: RequestOptions<Awaited<R>>): R;
+} : {
+    (entity: Param): R;
+    <F extends keyof Awaited<R>>(entity: Param, options: {
+        fields: F[];
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
+    <F extends keyof Awaited<R>>(entity: Param, options: {
+        fields: F[];
+    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
+    (entity: Param, options?: {
+        rawResponse: true;
+    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
+    (entity: Param, options?: RequestOptions<Awaited<R>>): R;
+};
+/** Wrapper type for expressing the response returned by a v2 list op supported endpoint */
+interface PagedResponse<T> {
+    /** List of entities in a page */
+    data: T[];
+    /** Metadata about the current page */
+    pagination: {
+        /**
+         * The "cursor" for the next page where `null` means there is no next page
+         *
+         * Used as a value to the query parameter `cursor` in a supported endpoint
+         */
+        next: string | null;
+        /** Total count of entities matching the list query */
+        count: number;
+    };
+}
+/** Utility for creating a query params map needed by most API requests */
+export declare function paramsFromOptions<T>(opts: RequestOptions<T>): Record<string, QueryParameterValue>;
+/** Operation for deleting an entity */
+declare function deleteOp(ctx: OperationContext, id: number): RequestConfig<unknown, void>;
+/** Operation for deleting a list of entities */
+declare function deleteBatchOp(ctx: OperationContext, ids: number[]): RequestConfig<unknown, void>;
+/** Operation for listing all entities on a v1 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+export declare function listOp<T, Query>(ctx: OperationContext, query: Query, opts?: RequestOptions<T[]> & {
+    offset?: number;
+}): AsyncGenerator<T>;
+/** Operation for listing all entities on a v2 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+export declare function listV2Op<T, Query>(ctx: OperationContext, query: Query, opts?: RequestOptions<T[]>): AsyncGenerator<T>;
+/** Operation for listing all entities on a v1 endpoint for a given query as an array */
+export declare function listAllOp<T, Query>(ctx: OperationContext, query: Query, opts?: RequestOptions<T[]> & {
+    offset?: number;
+}): Promise<T[]>;
+/** Operation for listing all entities on a v2 endpoint for a given query as an array */
+export declare function listAllV2Op<T, Query>(ctx: OperationContext, query: Query, opts?: RequestOptions<T[]>): Promise<T[]>;
+/** Builds an {@see Op} definition into an {@see OpFunction} ready to be called
+ * by the end user
+ *
+ * This will map typings and parameters defined on an {@see Op} into a more
+ * convenient and type safe format for use by the end user
+ */
+export declare function buildOp<F extends OpDef<any>, Param = Parameters<F>[1], Opts = Parameters<F>[2], Return = ReturnType<F> extends RequestConfig<infer _, infer T> ? Promise<T> : ReturnType<F>>(ctx: OperationContext, opFunc: F): OpFunction<Return, Param, Opts>;
+/** Function to return type safe mapping between a given endpoint; endpoint
+ * version and a common "op"
+ *
+ * NOTE: This is a function rather than a constant so that type generics work as
+ * intended. It's currently not possible to define a constant with generics
+ */
+export declare function getOpMap<E extends Endpoint<any, any>, T extends E['type'] = E['type']>(): {
+    v1: {
+        get: (ctx: OperationContext, id: number) => RequestConfig<unknown, T>;
+        delete: typeof deleteOp;
+        deleteBatch: typeof deleteBatchOp;
+        list: (ctx: OperationContext, query: E["queryParameters"], opts?: (RequestOptions<T[]> & {
+            offset?: number;
+        }) | undefined) => AsyncGenerator<T, any, any>;
+        listAll: (ctx: OperationContext, query: E["queryParameters"], opts?: (RequestOptions<T[]> & {
+            offset?: number;
+        }) | undefined) => Promise<T[]>;
+        listByPage: (ctx: OperationContext, query: E["queryParameters"], opts?: (RequestOptions<T[]> & {
+            offset?: number;
+        }) | undefined) => AsyncGenerator<AxiosResponse<T[], any>, any, any>;
+        create: (ctx: OperationContext, newEntity: E["createType"]) => RequestConfig<E["createType"], T>;
+        update: (ctx: OperationContext, entity: T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never) => RequestConfig<T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never, T>;
+        updateBatch: (ctx: OperationContext, entities: (T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never)[]) => Promise<{
+            success: T[];
+            failed: {
+                id: number;
+                error: string;
+            }[];
+        }>;
+    };
+    v2: {
+        get: (ctx: OperationContext, id: number) => RequestConfig<unknown, T>;
+        delete: typeof deleteOp;
+        deleteBatch: typeof deleteBatchOp;
+        list: (ctx: OperationContext, query: E["queryParameters"], opts?: RequestOptions<T[]> | undefined) => AsyncGenerator<T, any, any>;
+        listAll: (ctx: OperationContext, query: E["queryParameters"], opts?: RequestOptions<T[]> | undefined) => Promise<T[]>;
+        listByPage: (ctx: OperationContext, query: E["queryParameters"], opts?: RequestOptions<T[]> | undefined) => AsyncGenerator<AxiosResponse<PagedResponse<T>, any>, any, any>;
+        create: (ctx: OperationContext, newEntity: E["createType"]) => RequestConfig<E["createType"], T>;
+        update: (ctx: OperationContext, entity: T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never) => RequestConfig<T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never, T>;
+        updateBatch: (ctx: OperationContext, entities: (T extends {
+            id: number;
+        } ? RequirementsOf<T, "id"> : never)[]) => Promise<{
+            success: T[];
+            failed: {
+                id: number;
+                error: string;
+            }[];
+        }>;
+    };
+};
+export {};