rotacloud 1.5.2 → 2.0.0

package/dist/ops.js

@@ -0,0 +1,304 @@
+import { assert } from './utils.js';
+/** Utility for creating a query params map needed by most API requests */
+export function paramsFromOptions(opts) {
+    return {
+        fields: opts?.fields,
+        limit: opts?.maxResults,
+        dry_run: opts?.dryRun,
+    };
+}
+/** Converts a given `{@see AxiosRequestConfig}` into an iterable of paginated requests
+ *
+ * Utility for simplifying {@see listOp}
+ */
+function* requestPaginated(response, requestConfig) {
+    const fallbackLimit = 20;
+    const limit = Number(response.headers?.['x-limit']) || fallbackLimit;
+    const entityCount = Number(response.headers?.['x-total-count']) || 0;
+    const requestOffset = Number(response.headers?.['x-offset']) || 0;
+    for (let offset = requestOffset + limit; offset < entityCount; offset += limit) {
+        yield {
+            ...requestConfig,
+            params: {
+                ...requestConfig.params,
+                limit,
+                offset,
+                exclude_link_header: true,
+            },
+        };
+    }
+}
+/** Operation for getting an entity */
+function getOp(ctx, id) {
+    return {
+        ...ctx.request,
+        method: 'GET',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}/${id}`,
+    };
+}
+/** Operation for creating an entity */
+function createOp(ctx, newEntity) {
+    return {
+        ...ctx.request,
+        method: 'POST',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        data: newEntity,
+    };
+}
+/** Operation for updating an entity */
+function updateOp(ctx, entity) {
+    return {
+        ...ctx.request,
+        method: 'POST',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}/${entity.id}`,
+        data: entity,
+    };
+}
+/** Operation for deleting a list of entities */
+async function updateBatchOp(ctx, entities) {
+    const res = await ctx.client.request({
+        ...ctx.request,
+        method: 'POST',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        data: entities,
+    });
+    return res.data.reduce((acc, entityRes, shiftIdx) => {
+        if (entityRes.error) {
+            acc.failed.push({ id: entities[shiftIdx].id, error: entityRes.error });
+        }
+        else if (entityRes.data) {
+            acc.success.push(entityRes.data);
+        }
+        return acc;
+    }, { success: [], failed: [] });
+}
+/** Operation for deleting an entity */
+function deleteOp(ctx, id) {
+    return {
+        ...ctx.request,
+        method: 'DELETE',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}/${id}`,
+    };
+}
+/** Operation for deleting a list of entities */
+function deleteBatchOp(ctx, ids) {
+    return {
+        ...ctx.request,
+        method: 'DELETE',
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        data: ids,
+    };
+}
+/** Operation for listing all entities on a v1 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+export async function* listOp(ctx, query, 
+// NOTE: offset is only supported in v1
+opts) {
+    const queriedRequest = {
+        ...ctx.request,
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        params: {
+            ...ctx.request.params,
+            ...query,
+            offset: opts?.offset,
+        },
+    };
+    const res = await ctx.client.request(queriedRequest);
+    const maxEntities = opts?.maxResults ?? Infinity;
+    let entityCount = res.data.length;
+    assert(Array.isArray(res.data), 'list can only be performed on endpoints returning an array');
+    yield* res.data.slice(0, maxEntities);
+    if (entityCount >= maxEntities)
+        return;
+    for (const pagedRequest of requestPaginated(res, ctx.request)) {
+        const pagedRes = await ctx.client.request(pagedRequest);
+        for (const entity of pagedRes.data) {
+            yield entity;
+            entityCount += 1;
+            if (entityCount >= maxEntities)
+                return;
+        }
+    }
+}
+/** Operation for listing all entities on a v2 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+export async function* listV2Op(ctx, query, opts) {
+    const queriedRequest = {
+        ...ctx.request,
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        params: {
+            ...ctx.request.params,
+            ...query,
+            limit: opts?.maxResults,
+        },
+    };
+    const res = await ctx.client.request(queriedRequest);
+    const { data: entities, pagination } = res.data;
+    const maxEntities = opts?.maxResults ?? Infinity;
+    let pagedEntityCount = entities.length;
+    assert(Array.isArray(entities), 'list can only be performed on endpoints returning an array');
+    yield* entities.slice(0, maxEntities);
+    if (pagedEntityCount >= maxEntities)
+        return;
+    let nextPage = pagination.next ?? undefined;
+    while (nextPage !== undefined) {
+        const pagedRes = await ctx.client.request({
+            ...queriedRequest,
+            params: {
+                ...queriedRequest.params,
+                limit: pagedEntityCount,
+                cursor: nextPage,
+            },
+        });
+        nextPage = pagedRes.data.pagination.next ?? undefined;
+        for (const entity of pagedRes.data.data) {
+            yield entity;
+            pagedEntityCount += 1;
+            if (pagedEntityCount >= maxEntities)
+                return;
+        }
+    }
+}
+/** Operation for listing all entities on a v1 endpoint for a given query as an array */
+export async function listAllOp(ctx, query, 
+// NOTE: offset is only supported in v1
+opts) {
+    const results = [];
+    for await (const entity of listOp(ctx, query, opts)) {
+        results.push(entity);
+    }
+    return results;
+}
+/** Operation for listing all entities on a v2 endpoint for a given query as an array */
+export async function listAllV2Op(ctx, query, opts) {
+    const results = [];
+    for await (const entity of listV2Op(ctx, query, opts)) {
+        results.push(entity);
+    }
+    return results;
+}
+/** Operation for listing all entity pages on a v1 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+async function* listByPageOp(ctx, query, 
+// NOTE: offset is only supported in v1
+opts) {
+    const queriedRequest = {
+        ...ctx.request,
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        params: {
+            ...ctx.request.params,
+            ...query,
+            offset: opts?.offset,
+        },
+    };
+    const res = await ctx.client.request(queriedRequest);
+    const maxEntities = opts?.maxResults ?? Infinity;
+    let entityCount = res.data.length;
+    assert(Array.isArray(res.data), 'listByPage can only be performed on endpoints returning an array');
+    yield res;
+    if (entityCount >= maxEntities)
+        return;
+    for (const pagedRequest of requestPaginated(res, ctx.request)) {
+        const pagedRes = await ctx.client.request(pagedRequest);
+        yield pagedRes;
+        entityCount += pagedRes.data.length;
+        if (entityCount >= maxEntities)
+            return;
+    }
+}
+/** Operation for listing all entity pages on a v2 endpoint for a given query by
+ * automatically handling pagination as and when needed
+ */
+async function* listByPageV2Op(ctx, query, opts) {
+    const queriedRequest = {
+        ...ctx.request,
+        url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
+        params: {
+            ...ctx.request.params,
+            ...query,
+        },
+    };
+    const res = await ctx.client.request(queriedRequest);
+    const maxEntities = opts?.maxResults ?? Infinity;
+    let entityCount = res.data.data.length;
+    assert(Array.isArray(res.data.data), 'listByPage can only be performed on endpoints returning an array');
+    yield res;
+    if (entityCount >= maxEntities)
+        return;
+    let nextPage = res.data.pagination.next;
+    while (nextPage !== undefined) {
+        const pagedRes = await ctx.client.request({
+            ...queriedRequest,
+            params: {
+                ...queriedRequest.params,
+                cursor: nextPage,
+            },
+        });
+        nextPage = pagedRes.data.pagination.next;
+        yield pagedRes;
+        entityCount += pagedRes.data.data.length;
+        if (entityCount >= maxEntities)
+            return;
+    }
+}
+export function buildOp(ctx, opFunc) {
+    return (param, opts) => {
+        const configuredContext = {
+            ...ctx,
+            request: {
+                ...ctx.request,
+                params: {
+                    ...ctx.request.params,
+                    ...paramsFromOptions(opts ?? {}),
+                },
+            },
+        };
+        const req = opFunc(configuredContext, param, opts);
+        if (Symbol.asyncIterator in req) {
+            return req;
+        }
+        if (req instanceof Promise || ('then' in req && typeof req.then === 'function')) {
+            return req;
+        }
+        return ctx.client.request(req).then((res) => {
+            if (opts?.rawResponse)
+                return res;
+            return res.data;
+        });
+    };
+}
+/** 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 function getOpMap() {
+    return {
+        v1: {
+            get: (getOp),
+            delete: deleteOp,
+            deleteBatch: deleteBatchOp,
+            list: (listOp),
+            listAll: (listAllOp),
+            listByPage: (listByPageOp),
+            create: (createOp),
+            update: (updateOp),
+            updateBatch: (updateBatchOp),
+        },
+        v2: {
+            get: (getOp),
+            delete: deleteOp,
+            deleteBatch: deleteBatchOp,
+            list: (listV2Op),
+            listAll: (listAllV2Op),
+            listByPage: (listByPageV2Op),
+            create: (createOp),
+            update: (updateOp),
+            updateBatch: (updateBatchOp),
+        },
+    };
+}

package/dist/ops.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ops.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, test, vi } from 'vitest';
+import { createSdkClient } from './client-builder.js';
+import { getOpMap } from './ops.js';
+let mockAxiosClient;
+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
+    };
+});
+describe('Operations', () => {
+    const service = {
+        endpoint: 'settings',
+        endpointVersion: 'v1',
+        operations: ['get', 'list'],
+        customOperations: {
+            promiseOp: async () => 3,
+        },
+    };
+    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);
+        });
+    });
+});

package/dist/service.d.ts

@@ -0,0 +1,233 @@
+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 } 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 declare const SERVICES: {
+    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 }: OperationContext) => RequestConfig<void, Auth>;
+        };
+    };
+    availability: {
+        endpoint: "availability";
+        endpointVersion: "v1";
+        operations: ("delete" | "list" | "listAll" | "create" | "update")[];
+        customOperations: {
+            update: ({ request, service }: OperationContext, entity: Availability) => RequestConfig<typeof entity, Availability>;
+            delete: ({ request, service }: OperationContext, entity: {
+                user: number;
+                dates: string[];
+            }) => RequestConfig<Availability, Availability>;
+        };
+    };
+    dailyBudget: {
+        endpoint: "daily_budgets";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "updateBatch")[];
+        customOperations: {
+            updateBatch: ({ request, service }: OperationContext, entities: DailyBudgets[]) => RequestConfig<typeof entities, void>;
+        };
+    };
+    dailyRevenue: {
+        endpoint: "daily_revenue";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "updateBatch")[];
+        customOperations: {
+            updateBatch: ({ request, service }: OperationContext, entities: DailyRevenue[]) => 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 }: OperationContext, entity: EndpointEntityMap["v1"]["leave"]["createType"], opts?: RequestOptions<Leave>) => RequestConfig<typeof entity, Leave[]>;
+            types: ({ request }: OperationContext) => RequestConfig<void, 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 }: OperationContext, shiftIds: number[]) => RequestConfig<{
+                shifts: number[];
+            }, void>;
+            history: ({ request, service }: OperationContext, id: number) => RequestConfig<void, ShiftHistoryRecord[]>;
+            publish: ({ request }: OperationContext, shiftIds: number[]) => RequestConfig<{
+                shifts: number[];
+            }, void>;
+            unpublish: ({ request }: OperationContext, shiftIds: number[]) => RequestConfig<{
+                shifts: number[];
+            }, void>;
+            updateSwap: ({ request }: OperationContext, swapRequest: RequirementsOf<ShiftSwapRequest, "id">) => RequestConfig<{
+                admin_approved: boolean;
+            } | {
+                user_approved: boolean;
+            }, ShiftSwapRequest>;
+            updateDrop: ({ request }: OperationContext, dropRequest: {
+                request: RequirementsOf<ShiftDropRequest, "id" | "user_message">;
+                approved: boolean;
+            }) => RequestConfig<{
+                message: string;
+            }, ShiftDropRequest>;
+        };
+    };
+    terminal: {
+        endpoint: "terminals";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll" | "create" | "update")[];
+        customOperations: {
+            close: ({ request, service }: OperationContext, id: number) => RequestConfig<void, void>;
+        };
+    };
+    terminalActive: {
+        endpoint: "terminals";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll")[];
+        customOperations: {
+            launch: ({ request, service }: OperationContext, id: LaunchTerminal) => RequestConfig<void, Terminal>;
+            ping: ({ request, service }: OperationContext, id: {
+                id: number;
+                action: string;
+                device: string;
+            }) => RequestConfig<void, void>;
+            close: ({ request, service }: OperationContext, id: number) => 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: OperationContext, query: ToilAllowanceQueryParams, opts: RequestOptions<unknown> | undefined) => AsyncGenerator<ToilAllowance, any, any>;
+            listAll: (ctx: OperationContext, query: ToilAllowanceQueryParams, opts: RequestOptions<unknown> | undefined) => Promise<ToilAllowance[]>;
+        };
+    };
+    userClockIn: {
+        endpoint: "users_clocked_in";
+        endpointVersion: "v1";
+        operations: ("get" | "list" | "listAll")[];
+        customOperations: {
+            clockIn: ({ request, service }: OperationContext, entity: {
+                id: number;
+            } & RequirementsOf<UserClockIn, "method">) => RequestConfig<typeof entity, UserClockedIn>;
+            clockOut: ({ request, service }: OperationContext, entity: {
+                id: number;
+            } & RequirementsOf<UserClockOut, "method">) => RequestConfig<typeof entity, UserClockedOut>;
+            startBreak: ({ request, service }: OperationContext, entity: {
+                id: number;
+            } & RequirementsOf<UserBreakRequest, "method" | "action">) => RequestConfig<typeof entity, UserBreak>;
+            endBreak: ({ request, service }: OperationContext, entity: {
+                id: number;
+            } & RequirementsOf<UserBreakRequest, "method" | "action">) => RequestConfig<typeof entity, UserBreak>;
+        };
+    };
+    user: {
+        endpoint: "users";
+        endpointVersion: "v1";
+        operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
+    };
+};