rotacloud 2.1.4 → 2.2.0

package/dist/endpoint.d.ts

@@ -1,11 +1,12 @@
 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, LogbookCategory, DayNoteV2, DayNoteV2QueryParameters } from './interfaces/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
+import { Message } from './interfaces/message.interface.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, CreateEntity extends keyof Entity | Partial<Entity> = any, RequiredFields extends keyof Entity = CreateEntity extends keyof Entity ? CreateEntity : never> = {
+export type Endpoint<Entity, QueryParameters = undefined, CreateEntity extends keyof Entity | object = any, RequiredFields extends keyof Entity = CreateEntity extends keyof Entity ? CreateEntity : never> = {
     /** The type returned by an endpoint */
     type: Entity;
     /** The query parameters for endpoints that support listing */
@@ -35,6 +36,10 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
         leave_types: Endpoint<LeaveType>;
         leave: Endpoint<Leave, LeaveQueryParams, 'users' | 'type' | 'start_date' | 'end_date'>;
         locations: Endpoint<Location, LocationsQueryParams, 'name'>;
+        messages: Endpoint<Message, undefined, Pick<Message, 'message' | 'subject'> & {
+            users: number[];
+            attachments?: Pick<Message['attachments'][number], 'key' | 'bucket' | 'name' | 'extension'>[];
+        }>;
         pins: Endpoint<Pin>;
         roles: Endpoint<Role, RolesQueryParams, 'name'>;
         settings: Endpoint<Settings, SettingsQueryParams>;

package/dist/{models/SDKError.model.d.ts → error.d.ts}

@@ -13,3 +13,6 @@ export declare class SDKError extends Error {
         url?: string;
     });
 }
+export declare class ValidationError extends Error {
+    name: string;
+}

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

@@ -15,3 +15,6 @@ export class SDKError extends Error {
         this.data = errorConfig.data;
     }
 }
+export class ValidationError extends Error {
+    name = 'ValidationError';
+}

package/dist/interfaces/index.d.ts

@@ -36,3 +36,4 @@ export * from './user.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';
+export * from './message.interface.js';

package/dist/interfaces/index.js

@@ -36,3 +36,4 @@ export * from './user.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';
+export * from './message.interface.js';

package/dist/interfaces/message.interface.d.ts

@@ -0,0 +1,27 @@
+export interface Message {
+    id: number;
+    /** Unix timestamp in seconds */
+    sent_at: number;
+    sent_by: number;
+    subject: string;
+    message: string;
+    /** User recipients of the message */
+    users: {
+        /** ID of user */
+        user: number;
+        sent: boolean;
+        opened: boolean;
+        /** Unix timestamp in seconds */
+        opened_at: boolean;
+        error: string | null;
+    }[];
+    attachments: {
+        name: string;
+        extension: string;
+        type: string;
+        /** rounded integer value */
+        size_kb: number;
+        bucket: string;
+        key: string;
+    }[];
+}

package/dist/interfaces/message.interface.js

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

package/dist/main.d.ts

@@ -1,6 +1,6 @@
 export * from './interfaces/index.js';
 export * from './interfaces/query-params/index.js';
-export * from './models/index.js';
+export * from './error.js';
 export declare const createRotaCloudClient: (config: import("./interfaces/sdk-config.interface.js").SDKConfig) => import("./client-builder.js").SdkClient<{
     account: {
         endpoint: "accounts";
@@ -115,6 +115,14 @@ export declare const createRotaCloudClient: (config: import("./interfaces/sdk-co
             };
         };
     };
+    message: {
+        endpoint: "messages";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "listByPage")[];
+        customOperations: {
+            send: (ctx: import("./ops.js").OperationContext, message: import("./endpoint.js").EndpointEntityMap["v1"]["messages"]["createType"]) => import("./ops.js").RequestConfig<unknown, import("./interfaces/message.interface.js").Message>;
+        };
+    };
     pin: {
         endpoint: "pins";
         endpointVersion: "v1";

package/dist/main.js

@@ -2,5 +2,5 @@ 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 * from './error.js';
 export const createRotaCloudClient = createSdkClient(SERVICES);

package/dist/ops.d.ts

@@ -2,7 +2,7 @@ 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';
+import { SDKConfig } from './interfaces/index.js';
 /** Supported common operations */
 export type Operation = 'get' | 'list' | 'listAll' | 'listByPage' | 'delete' | 'deleteBatch' | 'create' | 'update' | 'updateBatch';
 /** Context provided to all operations */
@@ -105,6 +105,8 @@ interface PagedResponse<T> {
 }
 /** 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 creating an entity */
+export declare function createOp<T = unknown, NewEntity = unknown>(ctx: OperationContext, newEntity: NewEntity): RequestConfig<NewEntity, T>;
 /** Operation for deleting an entity */
 declare function deleteOp(ctx: OperationContext, id: number): RequestConfig<unknown, void>;
 /** Operation for deleting a list of entities */

package/dist/ops.js

@@ -1,4 +1,20 @@
 import { assert } from './utils.js';
+import { ValidationError } from './error.js';
+/** For validating the query parameter supplied to list ops
+ *
+ * @throws {ValidationError} if invalid
+ */
+function validateQueryParameter(query) {
+    // undefined is an accepted type for query
+    if (query !== undefined && (typeof query !== 'object' || query === null)) {
+        throw new ValidationError('Invalid type for query', {
+            cause: {
+                type: typeof query,
+                value: query,
+            },
+        });
+    }
+}
 /** Utility for creating a query params map needed by most API requests */
 export function paramsFromOptions(opts) {
     return {
@@ -30,6 +46,21 @@ function* requestPaginated(response, requestConfig) {
 }
 /** Operation for getting an entity */
 function getOp(ctx, id) {
+    if (typeof id !== 'number') {
+        throw new ValidationError('Invalid type for id', {
+            cause: {
+                type: typeof id,
+            },
+        });
+    }
+    if (!Number.isSafeInteger(id)) {
+        throw new ValidationError('Invalid value for id', {
+            cause: {
+                reason: 'Not a safe integer',
+                value: id,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'GET',
@@ -37,7 +68,15 @@ function getOp(ctx, id) {
     };
 }
 /** Operation for creating an entity */
-function createOp(ctx, newEntity) {
+export function createOp(ctx, newEntity) {
+    if (typeof newEntity !== 'object' || newEntity === null) {
+        throw new ValidationError('Invalid type for entity', {
+            cause: {
+                type: typeof newEntity,
+                value: newEntity,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'POST',
@@ -47,6 +86,22 @@ function createOp(ctx, newEntity) {
 }
 /** Operation for updating an entity for v1 endpoints */
 function updateV1Op(ctx, entity) {
+    if (typeof entity !== 'object' || entity === null || !('id' in entity)) {
+        throw new ValidationError('Invalid type for entity', {
+            cause: {
+                type: typeof entity,
+                value: entity,
+            },
+        });
+    }
+    if (!Number.isSafeInteger(entity.id)) {
+        throw new ValidationError('Invalid value for entity id', {
+            cause: {
+                reason: 'Not a safe integer',
+                value: entity.id,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'POST',
@@ -56,6 +111,22 @@ function updateV1Op(ctx, entity) {
 }
 /** Operation for updating an entity for v2 endpoints */
 function updateV2Op(ctx, entity) {
+    if (typeof entity !== 'object' || entity === null || !('id' in entity)) {
+        throw new ValidationError('Invalid type for entity', {
+            cause: {
+                type: typeof entity,
+                value: entity,
+            },
+        });
+    }
+    if (!Number.isSafeInteger(entity.id)) {
+        throw new ValidationError('Invalid value for entity id', {
+            cause: {
+                reason: 'Not a safe integer',
+                value: entity.id,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'PUT',
@@ -65,6 +136,13 @@ function updateV2Op(ctx, entity) {
 }
 /** Operation for deleting a list of entities */
 async function updateBatchOp(ctx, entities) {
+    if (!Array.isArray(entities)) {
+        throw new ValidationError('Invalid type for entity array', {
+            cause: {
+                type: typeof entities,
+            },
+        });
+    }
     const res = await ctx.client.request({
         ...ctx.request,
         method: 'POST',
@@ -83,6 +161,21 @@ async function updateBatchOp(ctx, entities) {
 }
 /** Operation for deleting an entity */
 function deleteOp(ctx, id) {
+    if (typeof id !== 'number') {
+        throw new ValidationError('Invalid type for id', {
+            cause: {
+                type: typeof id,
+            },
+        });
+    }
+    if (!Number.isSafeInteger(id)) {
+        throw new ValidationError('Invalid value for id', {
+            cause: {
+                reason: 'Not a safe integer',
+                value: id,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'DELETE',
@@ -91,6 +184,13 @@ function deleteOp(ctx, id) {
 }
 /** Operation for deleting a list of entities */
 function deleteBatchOp(ctx, ids) {
+    if (!Array.isArray(ids)) {
+        throw new ValidationError('Invalid type for id array', {
+            cause: {
+                type: typeof ids,
+            },
+        });
+    }
     return {
         ...ctx.request,
         method: 'DELETE',
@@ -104,6 +204,7 @@ function deleteBatchOp(ctx, ids) {
 export async function* listOp(ctx, query, 
 // NOTE: offset is only supported in v1
 opts) {
+    validateQueryParameter(query);
     const queriedRequest = {
         ...ctx.request,
         url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -134,6 +235,7 @@ opts) {
  * automatically handling pagination as and when needed
  */
 export async function* listV2Op(ctx, query, opts) {
+    validateQueryParameter(query);
     const queriedRequest = {
         ...ctx.request,
         url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -194,6 +296,7 @@ export async function listAllV2Op(ctx, query, opts) {
 async function* listByPageOp(ctx, query, 
 // NOTE: offset is only supported in v1
 opts) {
+    validateQueryParameter(query);
     const queriedRequest = {
         ...ctx.request,
         url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -222,6 +325,7 @@ opts) {
  * automatically handling pagination as and when needed
  */
 async function* listByPageV2Op(ctx, query, opts) {
+    validateQueryParameter(query);
     const queriedRequest = {
         ...ctx.request,
         url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,

package/dist/ops.test.js

@@ -21,7 +21,7 @@ describe('Operations', () => {
     const serviceV1 = {
         endpoint: 'settings',
         endpointVersion: 'v1',
-        operations: ['get', 'list'],
+        operations: ['get', 'delete', 'list'],
         customOperations: {
             promiseOp: async () => 3,
         },
@@ -29,7 +29,7 @@ describe('Operations', () => {
     const serviceV2 = {
         endpoint: 'logbook',
         endpointVersion: 'v2',
-        operations: ['get', 'list'],
+        operations: ['get', 'delete', 'list'],
         customOperations: {
             promiseOp: async () => 3,
         },
@@ -60,6 +60,21 @@ describe('Operations', () => {
         const promiseOpRes = await serviceV1.customOperations.promiseOp();
         expect(promiseOpRes).toStrictEqual(await client.service.promiseOp());
     });
+    describe('validation', () => {
+        const invalidIds = ['id', { id: 1 }, undefined, null, Infinity, -Infinity, 2.1, NaN];
+        test('getOp rejects invalid IDs', () => {
+            for (const invalidId of invalidIds) {
+                expect(() => client.service.get(invalidId)).toThrowError();
+                expect(() => client.serviceV2.get(invalidId)).toThrowError();
+            }
+        });
+        test('deleteOp rejects invalid IDs', () => {
+            for (const invalidId of invalidIds) {
+                expect(() => client.service.delete(invalidId)).toThrowError();
+                expect(() => client.serviceV2.delete(invalidId)).toThrowError();
+            }
+        });
+    });
     describe('list', () => {
         describe('v1 ops', () => {
             test('respects `maxResults` parameter in pagination', async () => {

package/dist/service.d.ts

@@ -8,6 +8,7 @@ import { ShiftSwapRequest } from './interfaces/swap-request.interface.js';
 import { ShiftDropRequest } from './interfaces/drop-request.interface.js';
 import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
+import { Message } from './interfaces/message.interface.js';
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
     /** Operations allowed and usable for the endpoint */
     operations: Operation[];
@@ -156,6 +157,14 @@ export declare const SERVICES: {
             };
         };
     };
+    message: {
+        endpoint: "messages";
+        endpointVersion: "v1";
+        operations: ("list" | "listAll" | "listByPage")[];
+        customOperations: {
+            send: (ctx: OperationContext, message: EndpointEntityMap["v1"]["messages"]["createType"]) => RequestConfig<unknown, Message>;
+        };
+    };
     pin: {
         endpoint: "pins";
         endpointVersion: "v1";

package/dist/service.js

@@ -1,4 +1,4 @@
-import { listAllOp, listAllV2Op, listOp, listV2Op, paramsFromOptions, } from './ops.js';
+import { createOp, listAllOp, listAllV2Op, listOp, listV2Op, 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
@@ -184,6 +184,14 @@ export const SERVICES = {
             },
         },
     },
+    message: {
+        endpoint: 'messages',
+        endpointVersion: 'v1',
+        operations: ['list', 'listAll', 'listByPage'],
+        customOperations: {
+            send: (ctx, message) => createOp(ctx, message),
+        },
+    },
     pin: {
         endpoint: 'pins',
         endpointVersion: 'v1',

package/dist/utils.d.ts

@@ -23,7 +23,17 @@ export interface RequestOptions<T> {
     dryRun?: boolean;
     fields?: T extends Object ? (keyof T)[] : never;
 }
-export declare function assert(value: unknown, message?: string | Error): asserts value;
+/** Ensures the provided value resolves to `true` before continuing
+ *
+ * If the value doesn't resolve to `true` then the provided `error` will be thrown
+ *
+ * Intended to be run in production and not removed on build
+ *
+ * @param assertion assertion to verify
+ * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
+ * will be thrown instead
+ */
+export declare function assert(assertion: unknown, error?: string | Error): asserts assertion;
 /** Creates and configures an Axios client for use in all calls to API endpoints
  * according to the provided {@see SDKConfig}
  */

package/dist/utils.js

@@ -1,7 +1,7 @@
 import axios, { isAxiosError } from 'axios';
 import axiosRetry, { isNetworkOrIdempotentRequestError } from 'axios-retry';
 import { RetryStrategy } from './interfaces/index.js';
-import { SDKError } from './models/index.js';
+import { SDKError } from './error.js';
 import pkg from '../package.json' with { type: 'json' };
 const DEFAULT_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 2000;
@@ -19,12 +19,22 @@ const DEFAULT_RETRY_STRATEGY_OPTIONS = {
 class AssertionError extends Error {
     name = AssertionError.prototype.name;
 }
-export function assert(value, message) {
-    if (value)
+/** Ensures the provided value resolves to `true` before continuing
+ *
+ * If the value doesn't resolve to `true` then the provided `error` will be thrown
+ *
+ * Intended to be run in production and not removed on build
+ *
+ * @param assertion assertion to verify
+ * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
+ * will be thrown instead
+ */
+export function assert(assertion, error) {
+    if (assertion)
         return;
-    if (!message || typeof message === 'string')
-        throw new AssertionError(message ?? `Assertion failed - value = ${value}`);
-    throw message;
+    if (error === undefined || typeof error === 'string')
+        throw new AssertionError(error ?? `Assertion failed - value = ${assertion}`);
+    throw error;
 }
 /** Converts a map of query parameter key/values into API compatible {@see URLSearchParams} */
 function toSearchParams(parameters) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rotacloud",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "The RotaCloud SDK for the RotaCloud API",
   "type": "module",
   "engines": {

package/src/client-builder.test.ts

@@ -1,7 +1,7 @@
 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 { SDKConfig } from './interfaces/index.js';
 import pkg from '../package.json' with { type: 'json' };
 
 let mockAxiosClient: Axios;

package/src/endpoint.ts

@@ -29,6 +29,7 @@ import {
   DayNoteV2QueryParameters,
 } from './interfaces/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
+import { Message } from './interfaces/message.interface.js';
 import {
   AttendanceQueryParams,
   AvailabilityQueryParams,
@@ -58,7 +59,7 @@ export type EndpointVersion = 'v1' | 'v2';
 export type Endpoint<
   Entity,
   QueryParameters = undefined,
-  CreateEntity extends keyof Entity | Partial<Entity> = any,
+  CreateEntity extends keyof Entity | object = any,
   // NOTE: introduced to work around TS inferring `RequirementsOf<Entity, CreateEntity>` incorrectly
   // TS resolves type to:
   // `RequirementsOf<Entity, "key 1"> | RequirementsOf<Entity "key 2">`
@@ -96,6 +97,14 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
     leave_types: Endpoint<LeaveType>;
     leave: Endpoint<Leave, LeaveQueryParams, 'users' | 'type' | 'start_date' | 'end_date'>;
     locations: Endpoint<Location, LocationsQueryParams, 'name'>;
+    messages: Endpoint<
+      Message,
+      undefined,
+      Pick<Message, 'message' | 'subject'> & {
+        users: number[];
+        attachments?: Pick<Message['attachments'][number], 'key' | 'bucket' | 'name' | 'extension'>[];
+      }
+    >;
     pins: Endpoint<Pin>;
     roles: Endpoint<Role, RolesQueryParams, 'name'>;
     settings: Endpoint<Settings, SettingsQueryParams>;

package/src/{models/SDKError.model.ts → error.ts}

@@ -18,3 +18,7 @@ export class SDKError extends Error {
     this.data = errorConfig.data;
   }
 }
+
+export class ValidationError extends Error {
+  override name = 'ValidationError';
+}

package/src/interfaces/index.ts

@@ -36,3 +36,4 @@ export * from './user.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';
+export * from './message.interface.js';

package/src/interfaces/message.interface.ts

@@ -0,0 +1,27 @@
+export interface Message {
+  id: number;
+  /** Unix timestamp in seconds */
+  sent_at: number;
+  sent_by: number;
+  subject: string;
+  message: string;
+  /** User recipients of the message */
+  users: {
+    /** ID of user */
+    user: number;
+    sent: boolean;
+    opened: boolean;
+    /** Unix timestamp in seconds */
+    opened_at: boolean;
+    error: string | null;
+  }[];
+  attachments: {
+    name: string;
+    extension: string;
+    type: string;
+    /** rounded integer value */
+    size_kb: number;
+    bucket: string;
+    key: string;
+  }[];
+}

package/src/main.ts

@@ -3,5 +3,5 @@ import { SERVICES } from './service.js';
 
 export * from './interfaces/index.js';
 export * from './interfaces/query-params/index.js';
-export * from './models/index.js';
+export * from './error.js';
 export const createRotaCloudClient = createSdkClient(SERVICES);

package/src/ops.test.ts

@@ -25,7 +25,7 @@ describe('Operations', () => {
   const serviceV1 = {
     endpoint: 'settings',
     endpointVersion: 'v1',
-    operations: ['get', 'list'],
+    operations: ['get', 'delete', 'list'],
     customOperations: {
       promiseOp: async () => 3,
     },
@@ -33,7 +33,7 @@ describe('Operations', () => {
   const serviceV2 = {
     endpoint: 'logbook',
     endpointVersion: 'v2',
-    operations: ['get', 'list'],
+    operations: ['get', 'delete', 'list'],
     customOperations: {
       promiseOp: async () => 3,
     },
@@ -74,6 +74,24 @@ describe('Operations', () => {
     expect(promiseOpRes).toStrictEqual(await client.service.promiseOp());
   });
 
+  describe('validation', () => {
+    const invalidIds = ['id', { id: 1 }, undefined, null, Infinity, -Infinity, 2.1, NaN];
+
+    test('getOp rejects invalid IDs', () => {
+      for (const invalidId of invalidIds) {
+        expect(() => client.service.get(invalidId as number)).toThrowError();
+        expect(() => client.serviceV2.get(invalidId as number)).toThrowError();
+      }
+    });
+
+    test('deleteOp rejects invalid IDs', () => {
+      for (const invalidId of invalidIds) {
+        expect(() => client.service.delete(invalidId as number)).toThrowError();
+        expect(() => client.serviceV2.delete(invalidId as number)).toThrowError();
+      }
+    });
+  });
+
   describe('list', () => {
     describe('v1 ops', () => {
       test('respects `maxResults` parameter in pagination', async () => {

package/src/ops.ts

@@ -2,7 +2,8 @@ import { Axios, AxiosRequestConfig, AxiosResponse } from 'axios';
 import { ServiceSpecification } from './service.js';
 import { RequestOptions, QueryParameterValue, RequirementsOf, assert } from './utils.js';
 import { Endpoint, EndpointVersion } from './endpoint.js';
-import { SDKConfig } from './main.js';
+import { SDKConfig } from './interfaces/index.js';
+import { ValidationError } from './error.js';
 
 /** Supported common operations */
 export type Operation =
@@ -163,6 +164,22 @@ interface PagedResponse<T> {
   };
 }
 
+/** For validating the query parameter supplied to list ops
+ *
+ * @throws {ValidationError} if invalid
+ */
+function validateQueryParameter(query: unknown) {
+  // undefined is an accepted type for query
+  if (query !== undefined && (typeof query !== 'object' || query === null)) {
+    throw new ValidationError('Invalid type for query', {
+      cause: {
+        type: typeof query,
+        value: query,
+      },
+    });
+  }
+}
+
 /** Utility for creating a query params map needed by most API requests */
 export function paramsFromOptions<T>(opts: RequestOptions<T>): Record<string, QueryParameterValue> {
   return {
@@ -200,6 +217,22 @@ function* requestPaginated<T>(
 
 /** Operation for getting an entity */
 function getOp<T = undefined>(ctx: OperationContext, id: number): RequestConfig<unknown, T> {
+  if (typeof id !== 'number') {
+    throw new ValidationError('Invalid type for id', {
+      cause: {
+        type: typeof id,
+      },
+    });
+  }
+  if (!Number.isSafeInteger(id)) {
+    throw new ValidationError('Invalid value for id', {
+      cause: {
+        reason: 'Not a safe integer',
+        value: id,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'GET',
@@ -208,10 +241,19 @@ function getOp<T = undefined>(ctx: OperationContext, id: number): RequestConfig<
 }
 
 /** Operation for creating an entity */
-function createOp<T = unknown, NewEntity = unknown>(
+export function createOp<T = unknown, NewEntity = unknown>(
   ctx: OperationContext,
   newEntity: NewEntity,
 ): RequestConfig<NewEntity, T> {
+  if (typeof newEntity !== 'object' || newEntity === null) {
+    throw new ValidationError('Invalid type for entity', {
+      cause: {
+        type: typeof newEntity,
+        value: newEntity,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'POST',
@@ -225,6 +267,23 @@ function updateV1Op<Return, Entity extends { id: number } & Partial<Return>>(
   ctx: OperationContext,
   entity: Entity,
 ): RequestConfig<Entity, Return> {
+  if (typeof entity !== 'object' || entity === null || !('id' in entity)) {
+    throw new ValidationError('Invalid type for entity', {
+      cause: {
+        type: typeof entity,
+        value: entity,
+      },
+    });
+  }
+  if (!Number.isSafeInteger(entity.id)) {
+    throw new ValidationError('Invalid value for entity id', {
+      cause: {
+        reason: 'Not a safe integer',
+        value: entity.id,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'POST',
@@ -238,6 +297,23 @@ function updateV2Op<Return, Entity extends { id: number } & Partial<Return>>(
   ctx: OperationContext,
   entity: Entity,
 ): RequestConfig<Entity, Return> {
+  if (typeof entity !== 'object' || entity === null || !('id' in entity)) {
+    throw new ValidationError('Invalid type for entity', {
+      cause: {
+        type: typeof entity,
+        value: entity,
+      },
+    });
+  }
+  if (!Number.isSafeInteger(entity.id)) {
+    throw new ValidationError('Invalid value for entity id', {
+      cause: {
+        reason: 'Not a safe integer',
+        value: entity.id,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'PUT',
@@ -251,6 +327,14 @@ async function updateBatchOp<Return, Entity extends { id: number } & Partial<Ret
   ctx: OperationContext,
   entities: Entity[],
 ): Promise<{ success: Return[]; failed: { id: number; error: string }[] }> {
+  if (!Array.isArray(entities)) {
+    throw new ValidationError('Invalid type for entity array', {
+      cause: {
+        type: typeof entities,
+      },
+    });
+  }
+
   const res = await ctx.client.request<{ code: number; data?: Return; error?: string }[]>({
     ...ctx.request,
     method: 'POST',
@@ -273,6 +357,22 @@ async function updateBatchOp<Return, Entity extends { id: number } & Partial<Ret
 
 /** Operation for deleting an entity */
 function deleteOp(ctx: OperationContext, id: number): RequestConfig<unknown, void> {
+  if (typeof id !== 'number') {
+    throw new ValidationError('Invalid type for id', {
+      cause: {
+        type: typeof id,
+      },
+    });
+  }
+  if (!Number.isSafeInteger(id)) {
+    throw new ValidationError('Invalid value for id', {
+      cause: {
+        reason: 'Not a safe integer',
+        value: id,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'DELETE',
@@ -282,6 +382,14 @@ function deleteOp(ctx: OperationContext, id: number): RequestConfig<unknown, voi
 
 /** Operation for deleting a list of entities */
 function deleteBatchOp(ctx: OperationContext, ids: number[]): RequestConfig<unknown, void> {
+  if (!Array.isArray(ids)) {
+    throw new ValidationError('Invalid type for id array', {
+      cause: {
+        type: typeof ids,
+      },
+    });
+  }
+
   return {
     ...ctx.request,
     method: 'DELETE',
@@ -299,6 +407,7 @@ export async function* listOp<T, Query>(
   // NOTE: offset is only supported in v1
   opts?: RequestOptions<T[]> & { offset?: number },
 ): AsyncGenerator<T> {
+  validateQueryParameter(query);
   const queriedRequest = {
     ...ctx.request,
     url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -334,6 +443,8 @@ export async function* listV2Op<T, Query>(
   query: Query,
   opts?: RequestOptions<T[]>,
 ): AsyncGenerator<T> {
+  validateQueryParameter(query);
+
   const queriedRequest = {
     ...ctx.request,
     url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -403,6 +514,8 @@ async function* listByPageOp<T, Query>(
   // NOTE: offset is only supported in v1
   opts?: RequestOptions<T[]> & { offset?: number },
 ): AsyncGenerator<AxiosResponse<T[]>> {
+  validateQueryParameter(query);
+
   const queriedRequest = {
     ...ctx.request,
     url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,
@@ -436,6 +549,8 @@ async function* listByPageV2Op<T, Query>(
   query: Query,
   opts?: RequestOptions<T[]>,
 ): AsyncGenerator<AxiosResponse<PagedResponse<T>>> {
+  validateQueryParameter(query);
+
   const queriedRequest = {
     ...ctx.request,
     url: `${ctx.service.endpointVersion}/${ctx.service.endpoint}`,

package/src/service.ts

@@ -19,6 +19,7 @@ import {
   Operation,
   OperationContext,
   RequestConfig,
+  createOp,
   listAllOp,
   listAllV2Op,
   listOp,
@@ -31,6 +32,7 @@ import { ShiftSwapRequest } from './interfaces/swap-request.interface.js';
 import { ShiftDropRequest } from './interfaces/drop-request.interface.js';
 import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
+import { Message } from './interfaces/message.interface.js';
 
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
   /** Operations allowed and usable for the endpoint */
@@ -266,6 +268,14 @@ export const SERVICES = {
       },
     },
   },
+  message: {
+    endpoint: 'messages',
+    endpointVersion: 'v1',
+    operations: ['list', 'listAll', 'listByPage'],
+    customOperations: {
+      send: (ctx, message: EndpointEntityMap['v1']['messages']['createType']) => createOp<Message>(ctx, message),
+    },
+  },
   pin: {
     endpoint: 'pins',
     endpointVersion: 'v1',

package/src/utils.ts

@@ -1,7 +1,7 @@
 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 { SDKError } from './error.js';
 import pkg from '../package.json' with { type: 'json' };
 
 /** Creates a `Partial<T>` where all properties specified by `K` are required
@@ -50,11 +50,21 @@ 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;
+/** Ensures the provided value resolves to `true` before continuing
+ *
+ * If the value doesn't resolve to `true` then the provided `error` will be thrown
+ *
+ * Intended to be run in production and not removed on build
+ *
+ * @param assertion assertion to verify
+ * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
+ * will be thrown instead
+ */
+export function assert(assertion: unknown, error?: string | Error): asserts assertion {
+  if (assertion) return;
+  if (error === undefined || typeof error === 'string')
+    throw new AssertionError(error ?? `Assertion failed - value = ${assertion}`);
+  throw error;
 }
 
 /** Converts a map of query parameter key/values into API compatible {@see URLSearchParams} */

package/dist/models/index.d.ts

@@ -1 +0,0 @@
-export * from './SDKError.model.js';

package/dist/models/index.js

@@ -1 +0,0 @@
-export * from './SDKError.model.js';

package/src/models/index.ts

@@ -1 +0,0 @@
-export * from './SDKError.model.js';