rotacloud 2.2.4 → 2.2.9

package/dist/endpoint.d.ts

@@ -1,4 +1,4 @@
-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 { 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, PartialUserV2 } 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';
@@ -59,5 +59,9 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
         invoices: Endpoint<Invoice, InvoiceQueryParameters>;
         dayNotes: Endpoint<DayNoteV2, DayNoteV2QueryParameters, 'title' | 'message' | 'startDate' | 'endDate' | 'locations' | 'visibleToEmployees'>;
         'logbook/categories': Endpoint<LogbookCategory, undefined, Pick<LogbookCategory, 'name'>>;
+        users: Endpoint<User, undefined, {
+            users: RequirementsOf<PartialUserV2, 'firstName' | 'lastName' | 'roles'>[];
+            sendInvite?: boolean;
+        }>;
     };
 }

package/dist/interfaces/account-subscription.interface.d.ts

@@ -0,0 +1,112 @@
+export interface Entitlement {
+    id: string;
+}
+export interface Plan {
+    id: string;
+    status: {
+        name: 'active' | 'in_trial';
+    };
+}
+export interface PlanExtended extends Plan {
+    trialEnds: string;
+    pricing: PlanPricing;
+}
+export interface Addon {
+    id: string;
+    status: {
+        name: 'active' | 'in_trial' | 'hidden';
+    };
+}
+export interface AddonExtended extends Addon {
+    trialEnds: string;
+    pricing: PlanPricing;
+}
+export interface PlanPricing {
+    itemPriceId: string;
+    price: number;
+    pricingModel: 'flat_fee' | 'per_unit' | 'tiered' | 'volume' | 'stairstep' | null;
+    tiers?: PricingTier;
+    currentTier?: PricingTier;
+    perUnitPrice?: number;
+}
+export interface PricingTier {
+    startingUnit: number;
+    endingUnit: number;
+    price: number;
+}
+export interface AccountSubscription {
+    status: 'in_trial' | 'active' | 'non_renewing' | 'paused' | 'cancelled';
+    dunningEnds?: string;
+    entitlements: Entitlement[];
+    plans: Plan[];
+    addons: Addon[];
+}
+export interface AccountSubscriptionExtended extends AccountSubscription {
+    billingFrequency: string;
+    billingEmail: string;
+    country: number;
+    subscriptionPaymentSourceId: string;
+    nextBillingAt: string;
+    trialEnds: string;
+    canRestartTrial: boolean;
+    totalPrice: number;
+    plans: PlanExtended[];
+    addons: AddonExtended[];
+}
+export interface SubscriptionUpdateReq {
+    paymentFrequency?: 'monthly' | 'yearly';
+    plans?: [{
+        planId: string;
+        trial?: boolean;
+    }];
+    addons?: [{
+        addonId: string;
+        trial?: boolean;
+    }];
+    subscriptionPaymentSourceId?: string;
+    billingEmail?: string;
+    country?: number;
+}
+export interface EstimatesRes {
+    owed: number;
+    totalPrice: number;
+}
+export interface ProductCatalogueItemPrice {
+    id: string;
+    currency: string;
+    pricingModel: 'stairstep' | 'perUnit';
+    unitPrice?: number;
+    stairStep?: {
+        startingUnit: number;
+        endingUnit?: number;
+        tierPrice: number;
+    };
+    billingPeriod: number;
+    billingPeriodUnit: 'monthly' | 'yearly';
+}
+export interface ProductCatalogueItem {
+    id: string;
+    name: string;
+    itemPrice: ProductCatalogueItemPrice[];
+}
+export interface ProductCatalogueRes {
+    plans: ProductCatalogueItem[];
+    addons: ProductCatalogueItem[];
+}
+export declare enum CancellationReason {
+    'features' = 0,
+    'value' = 1,
+    'price' = 2,
+    'not_using' = 3,
+    'incompatible' = 4,
+    'difficulty' = 5,
+    'using_competitor' = 6,
+    'sold' = 7,
+    'temporary_closure' = 8,
+    'closed' = 9
+}
+export interface CancelSubscriptionReq {
+    reason: CancellationReason;
+    message?: string;
+    detail?: string;
+}

package/dist/interfaces/account-subscription.interface.js

@@ -0,0 +1,13 @@
+export var CancellationReason;
+(function (CancellationReason) {
+    CancellationReason[CancellationReason["features"] = 0] = "features";
+    CancellationReason[CancellationReason["value"] = 1] = "value";
+    CancellationReason[CancellationReason["price"] = 2] = "price";
+    CancellationReason[CancellationReason["not_using"] = 3] = "not_using";
+    CancellationReason[CancellationReason["incompatible"] = 4] = "incompatible";
+    CancellationReason[CancellationReason["difficulty"] = 5] = "difficulty";
+    CancellationReason[CancellationReason["using_competitor"] = 6] = "using_competitor";
+    CancellationReason[CancellationReason["sold"] = 7] = "sold";
+    CancellationReason[CancellationReason["temporary_closure"] = 8] = "temporary_closure";
+    CancellationReason[CancellationReason["closed"] = 9] = "closed";
+})(CancellationReason || (CancellationReason = {}));

package/dist/interfaces/index.d.ts

@@ -34,6 +34,7 @@ export * from './time-zone.interface.js';
 export * from './toil-accrual.interface.js';
 export * from './toil-allowance.interface.js';
 export * from './user.interface.js';
+export * from './user-v2.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';

package/dist/interfaces/index.js

@@ -34,6 +34,7 @@ export * from './time-zone.interface.js';
 export * from './toil-accrual.interface.js';
 export * from './toil-allowance.interface.js';
 export * from './user.interface.js';
+export * from './user-v2.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';

package/dist/interfaces/user-clock-in.interface.d.ts

@@ -1,7 +1,7 @@
 import { TerminalLocation } from './terminal.interface.js';
 export interface UserClockIn {
     method: string;
-    shift: number;
+    shift: number | null;
     terminal?: number;
     user: number;
     photo?: string;

package/dist/interfaces/user-v2.interface.d.ts

@@ -0,0 +1,26 @@
+import { ManagerPermission } from './user.interface.js';
+export interface CreateUserRequest extends PartialUserV2 {
+    permissions?: ManagerPermission[];
+    coverLocations?: number[];
+    managedLocations?: number[];
+}
+export interface CreateUserResponse extends PartialUserV2 {
+    id: number;
+}
+export interface PartialUserV2 {
+    firstName: string;
+    lastName: string;
+    locations: number[];
+    roles: UserRole[];
+    email: string | null;
+    level: 'admin' | 'employee' | 'manager';
+    salary: number;
+    salaryType: 'annual' | 'hourly';
+}
+export interface UserRole {
+    id: number;
+    perShift?: number;
+    perHour?: number;
+    payCode?: string;
+    isDefault?: boolean;
+}

package/dist/interfaces/user-v2.interface.js

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

package/dist/interfaces/users-clocked-in.interface.d.ts

@@ -1,11 +1,11 @@
-import { Shift, TerminalLocation, UserBreak } from '../interfaces/index.js';
+import { TerminalLocation, UserBreak } from '../interfaces/index.js';
 export interface UserClockedIn {
     user: number;
     location: number;
     role: number;
     in_time: number;
     minutes_late: number;
-    shift: Pick<Shift, 'id' | 'start_time' | 'end_time' | 'minutes_break' | 'location' | 'role'>;
+    shift: number | null;
     in_method: string;
     in_location: TerminalLocation;
     in_device: string | null;

package/dist/main.d.ts

@@ -239,4 +239,15 @@ export declare const createRotaCloudClient: (config: import("./interfaces/sdk-co
         endpointVersion: "v1";
         operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
     };
+    userV2: {
+        endpoint: "users";
+        endpointVersion: "v2";
+        operations: "create"[];
+        customOperations: {
+            create: ({ request, service }: import("./ops.js").OperationContext, userSpec: {
+                users: import("./utils.js").RequirementsOf<import("./interfaces/user-v2.interface.js").CreateUserRequest, "firstName" | "lastName" | "roles">[];
+                sendInvite?: boolean;
+            }) => import("./ops.js").RequestConfig<typeof userSpec, import("./interfaces/user-v2.interface.js").CreateUserResponse>;
+        };
+    };
 }>;

package/dist/ops.d.ts

@@ -23,69 +23,82 @@ export type RequestConfig<RequestData, ResponseData> = AxiosRequestConfig<Reques
  *
  * 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;
+ * All methods on services follow this typing.
+ */
+export type OpFunction<Return = any, Param = undefined, Opts = RequestOptions<unknown>> = Return extends AsyncIterable<infer U> | Promise<Iterable<infer U>> ? Param extends undefined ? {
+    (query?: Param): Return;
     <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;
+    } & RequestOptions<U>): Return extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : Return extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query: Param, options?: Opts): Return;
 } : Partial<Param> extends Param ? {
-    (query?: Param): R;
+    (query?: Param): Return;
     <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;
+    } & RequestOptions<U>): Return extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : Return extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query?: Param, options?: Opts): Return;
 } : {
-    (query: Param): R;
+    (query: Param): Return;
     <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;
+    } & RequestOptions<U>): Return extends AsyncIterable<U> ? Promise<AsyncIterable<Pick<U, F>>> : Return extends Promise<Array<U>> ? Promise<Array<Pick<U, F>>> : Promise<Iterable<Pick<U, F>>>;
+    (query: Param, Options?: Opts): Return;
 } : Param extends number ? {
-    (id: Param): R;
-    <F extends keyof Awaited<R>>(id: Param, options: {
+    (id: Param): Return;
+    <F extends keyof Awaited<Return>>(id: Param, options: {
         fields: F[];
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
-    <F extends keyof Awaited<R>>(id: Param, options: {
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+    <F extends keyof Awaited<Return>>(id: Param, options: {
         fields: F[];
-    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
+    } & RequestOptions<Awaited<Return>>): Promise<Pick<Awaited<Return>, F>>;
     (id: Param, options?: {
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
-    (id: Param, options?: RequestOptions<Awaited<R>>): R;
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Awaited<Return>>>;
+    (id: Param, options?: RequestOptions<Awaited<Return>>): Return;
+} : Param extends number[] ? {
+    (ids: Param): Return;
+    <F extends keyof Awaited<Return>>(ids: Param, options: {
+        fields: F[];
+        rawResponse: true;
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+    <F extends keyof Awaited<Return>>(ids: Param, options: {
+        fields: F[];
+    } & RequestOptions<Awaited<Return>>): Promise<Pick<Awaited<Return>, F>>;
+    (ids: Param, options?: {
+        rawResponse: true;
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Awaited<Return>>>;
+    (ids: Param, options?: RequestOptions<Awaited<Return>>): Return;
 } : Param extends undefined ? {
-    (entity?: Param): R;
-    <F extends keyof Awaited<R>>(entity: Param, options: {
+    (): Return;
+    <F extends keyof Awaited<Return>>(none: Param, options: {
         fields: F[];
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
-    <F extends keyof Awaited<R>>(entity: Param, options: {
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+    <F extends keyof Awaited<Return>>(none: Param, options: {
         fields: F[];
-    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
-    (entity?: Param, options?: {
+    } & RequestOptions<Awaited<Return>>): Promise<Pick<Awaited<Return>, F>>;
+    (none?: Param, options?: {
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
-    (entity?: Param, options?: RequestOptions<Awaited<R>>): R;
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Awaited<Return>>>;
+    (none?: Param, options?: RequestOptions<Awaited<Return>>): Return;
 } : {
-    (entity: Param): R;
-    <F extends keyof Awaited<R>>(entity: Param, options: {
+    (entity: Param): Return;
+    <F extends keyof Awaited<Return>>(entity: Param, options: {
         fields: F[];
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
-    <F extends keyof Awaited<R>>(entity: Param, options: {
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+    <F extends keyof Awaited<Return>>(entity: Param, options: {
         fields: F[];
-    } & RequestOptions<Awaited<R>>): Promise<Pick<Awaited<R>, F>>;
+    } & RequestOptions<Awaited<Return>>): Promise<Pick<Awaited<Return>, F>>;
     (entity: Param, options?: {
         rawResponse: true;
-    } & RequestOptions<Awaited<R>>): Promise<AxiosResponse<Awaited<R>>>;
-    (entity: Param, options?: RequestOptions<Awaited<R>>): R;
+    } & RequestOptions<Awaited<Return>>): Promise<AxiosResponse<Awaited<Return>>>;
+    (entity: Param, options?: RequestOptions<Awaited<Return>>): Return;
 };
 /** Wrapper type for expressing the response returned by a v2 list op supported endpoint */
 interface PagedResponse<T> {

package/dist/service.d.ts

@@ -10,6 +10,7 @@ import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 import { Message } from './interfaces/message.interface.js';
 import { Invoice, InvoiceDownload } from './interfaces/invoice.interface.js';
+import { CreateUserRequest, CreateUserResponse } from './interfaces/user-v2.interface.js';
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
     /** Operations allowed and usable for the endpoint */
     operations: Operation[];
@@ -282,4 +283,15 @@ export declare const SERVICES: {
         endpointVersion: "v1";
         operations: ("get" | "delete" | "list" | "listAll" | "create" | "update")[];
     };
+    userV2: {
+        endpoint: "users";
+        endpointVersion: "v2";
+        operations: "create"[];
+        customOperations: {
+            create: ({ request, service }: OperationContext, userSpec: {
+                users: RequirementsOf<CreateUserRequest, "firstName" | "lastName" | "roles">[];
+                sendInvite?: boolean;
+            }) => RequestConfig<typeof userSpec, CreateUserResponse>;
+        };
+    };
 };

package/dist/service.js

@@ -381,4 +381,17 @@ export const SERVICES = {
         endpointVersion: 'v1',
         operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
     },
+    userV2: {
+        endpoint: 'users',
+        endpointVersion: 'v2',
+        operations: ['create'],
+        customOperations: {
+            create: ({ request, service }, userSpec) => ({
+                ...request,
+                url: `${service.endpointVersion}/${service.endpoint}`,
+                method: 'POST',
+                data: userSpec,
+            }),
+        },
+    },
 };

package/dist/utils.d.ts

@@ -23,12 +23,14 @@ export interface RequestOptions<T> {
     dryRun?: boolean;
     fields?: T extends Object ? (keyof T)[] : never;
 }
-/** Ensures the provided value resolves to `true` before continuing
- *
+/** 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
  *
+ * We don't use the `node:assert` package as this SDK needs to run in environments like
+ * web and mobile where the `node:assert` package may not be defined.
+ *
  * @param assertion assertion to verify
  * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
  * will be thrown instead

package/dist/utils.js

@@ -19,12 +19,14 @@ const DEFAULT_RETRY_STRATEGY_OPTIONS = {
 class AssertionError extends Error {
     name = AssertionError.prototype.name;
 }
-/** Ensures the provided value resolves to `true` before continuing
- *
+/** 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
  *
+ * We don't use the `node:assert` package as this SDK needs to run in environments like
+ * web and mobile where the `node:assert` package may not be defined.
+ *
  * @param assertion assertion to verify
  * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
  * will be thrown instead
@@ -50,6 +52,7 @@ function toSearchParams(parameters) {
     }, []);
     return new URLSearchParams(reducedParams);
 }
+/** Interceptor for {@link AxiosError}s mapping them into {@link SDKError} */
 function parseClientError(error) {
     const axiosErrorLocation = error.response || error.request;
     const apiErrorMessage = axiosErrorLocation.data?.message ?? axiosErrorLocation.data?.error;

package/package.json

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

package/src/endpoint.ts

@@ -27,6 +27,7 @@ import {
   LogbookCategory,
   DayNoteV2,
   DayNoteV2QueryParameters,
+  PartialUserV2,
 } from './interfaces/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 import { Message } from './interfaces/message.interface.js';
@@ -128,5 +129,13 @@ export interface EndpointEntityMap extends Record<EndpointVersion, Record<string
       'title' | 'message' | 'startDate' | 'endDate' | 'locations' | 'visibleToEmployees'
     >;
     'logbook/categories': Endpoint<LogbookCategory, undefined, Pick<LogbookCategory, 'name'>>;
+    users: Endpoint<
+      User,
+      undefined,
+      {
+        users: RequirementsOf<PartialUserV2, 'firstName' | 'lastName' | 'roles'>[];
+        sendInvite?: boolean;
+      }
+    >;
   };
 }

package/src/interfaces/account-subscription.interface.ts

@@ -0,0 +1,109 @@
+export interface Entitlement {
+  id: string;
+}
+
+export interface Plan {
+  id: string;
+  status: { name: 'active' | 'in_trial' };
+}
+export interface PlanExtended extends Plan {
+  trialEnds: string;
+  pricing: PlanPricing;
+}
+
+export interface Addon {
+  id: string;
+  status: { name: 'active' | 'in_trial' | 'hidden' };
+}
+export interface AddonExtended extends Addon {
+  trialEnds: string;
+  pricing: PlanPricing;
+}
+
+export interface PlanPricing {
+  itemPriceId: string;
+  price: number;
+  pricingModel: 'flat_fee' | 'per_unit' | 'tiered' | 'volume' | 'stairstep' | null;
+  tiers?: PricingTier;
+  currentTier?: PricingTier;
+  perUnitPrice?: number;
+}
+
+export interface PricingTier {
+  startingUnit: number;
+  endingUnit: number;
+  price: number;
+}
+
+export interface AccountSubscription {
+  status: 'in_trial' | 'active' | 'non_renewing' | 'paused' | 'cancelled';
+  dunningEnds?: string;
+  entitlements: Entitlement[];
+  plans: Plan[];
+  addons: Addon[];
+}
+
+export interface AccountSubscriptionExtended extends AccountSubscription {
+  billingFrequency: string;
+  billingEmail: string;
+  country: number;
+  subscriptionPaymentSourceId: string;
+  nextBillingAt: string;
+  trialEnds: string;
+  canRestartTrial: boolean;
+  totalPrice: number;
+  plans: PlanExtended[];
+  addons: AddonExtended[];
+}
+
+export interface SubscriptionUpdateReq {
+  paymentFrequency?: 'monthly' | 'yearly';
+  plans?: [{ planId: string; trial?: boolean }];
+  addons?: [{ addonId: string; trial?: boolean }];
+  subscriptionPaymentSourceId?: string;
+  billingEmail?: string;
+  country?: number;
+}
+
+export interface EstimatesRes {
+  owed: number;
+  totalPrice: number;
+}
+
+export interface ProductCatalogueItemPrice {
+  id: string;
+  currency: string;
+  pricingModel: 'stairstep' | 'perUnit';
+  unitPrice?: number;
+  stairStep?: { startingUnit: number; endingUnit?: number; tierPrice: number };
+  billingPeriod: number;
+  billingPeriodUnit: 'monthly' | 'yearly';
+}
+export interface ProductCatalogueItem {
+  id: string;
+  name: string;
+  itemPrice: ProductCatalogueItemPrice[];
+}
+
+export interface ProductCatalogueRes {
+  plans: ProductCatalogueItem[];
+  addons: ProductCatalogueItem[];
+}
+
+export enum CancellationReason {
+  'features',
+  'value',
+  'price',
+  'not_using',
+  'incompatible',
+  'difficulty',
+  'using_competitor',
+  'sold',
+  'temporary_closure',
+  'closed',
+}
+export interface CancelSubscriptionReq {
+  reason: CancellationReason;
+  message?: string;
+  detail?: string;
+}

package/src/interfaces/index.ts

@@ -34,6 +34,7 @@ export * from './time-zone.interface.js';
 export * from './toil-accrual.interface.js';
 export * from './toil-allowance.interface.js';
 export * from './user.interface.js';
+export * from './user-v2.interface.js';
 export * from './users-clocked-in.interface.js';
 export * from './users-clocked-out.interface.js';
 export * from './document.interface.js';

package/src/interfaces/user-clock-in.interface.ts

@@ -2,7 +2,7 @@ import { TerminalLocation } from './terminal.interface.js';
 
 export interface UserClockIn {
   method: string;
-  shift: number;
+  shift: number | null;
   terminal?: number;
   user: number;
   photo?: string;

package/src/interfaces/user-v2.interface.ts

@@ -0,0 +1,30 @@
+import { ManagerPermission } from './user.interface.js';
+
+export interface CreateUserRequest extends PartialUserV2 {
+  permissions?: ManagerPermission[];
+  coverLocations?: number[];
+  managedLocations?: number[];
+}
+
+export interface CreateUserResponse extends PartialUserV2 {
+  id: number;
+}
+
+export interface PartialUserV2 {
+  firstName: string;
+  lastName: string;
+  locations: number[];
+  roles: UserRole[];
+  email: string | null;
+  level: 'admin' | 'employee' | 'manager';
+  salary: number;
+  salaryType: 'annual' | 'hourly';
+}
+
+export interface UserRole {
+  id: number;
+  perShift?: number;
+  perHour?: number;
+  payCode?: string;
+  isDefault?: boolean;
+}

package/src/interfaces/users-clocked-in.interface.ts

@@ -1,4 +1,4 @@
-import { Shift, TerminalLocation, UserBreak } from '../interfaces/index.js';
+import { TerminalLocation, UserBreak } from '../interfaces/index.js';
 
 export interface UserClockedIn {
   user: number;
@@ -6,7 +6,7 @@ export interface UserClockedIn {
   role: number;
   in_time: number;
   minutes_late: number;
-  shift: Pick<Shift, 'id' | 'start_time' | 'end_time' | 'minutes_break' | 'location' | 'role'>;
+  shift: number | null;
   in_method: string;
   in_location: TerminalLocation;
   in_device: string | null;

package/src/ops.ts

@@ -37,7 +37,7 @@ export type RequestConfig<RequestData, ResponseData> = AxiosRequestConfig<Reques
  *
  * 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>)
@@ -45,107 +45,130 @@ export type OpDef<T, Param = any, Opts extends Partial<RequestOptions<any>> = Re
 
 /** 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
+ * All methods on services follow this typing.
+ */
+export type OpFunction<Return = any, Param = undefined, Opts = RequestOptions<unknown>> = Return extends
   | AsyncIterable<infer U>
   | Promise<Iterable<infer U>>
   ? // List based op parameter names
     Param extends undefined
     ? {
-        (query?: Param): R;
+        (query?: Param): Return;
         <F extends keyof U>(
           query: Param,
           options: { fields: F[] } & RequestOptions<U>,
-        ): R extends AsyncIterable<U>
+        ): Return extends AsyncIterable<U>
           ? Promise<AsyncIterable<Pick<U, F>>>
-          : R extends Promise<Array<U>>
+          : Return extends Promise<Array<U>>
             ? Promise<Array<Pick<U, F>>>
             : Promise<Iterable<Pick<U, F>>>;
-        (query: Param, options?: Opts): R;
+        (query: Param, options?: Opts): Return;
       }
     : Partial<Param> extends Param
       ? {
-          (query?: Param): R;
+          (query?: Param): Return;
           <F extends keyof U>(
             query: Param,
             options: { fields: F[] } & RequestOptions<U>,
-          ): R extends AsyncIterable<U>
+          ): Return extends AsyncIterable<U>
             ? Promise<AsyncIterable<Pick<U, F>>>
-            : R extends Promise<Array<U>>
+            : Return extends Promise<Array<U>>
               ? Promise<Array<Pick<U, F>>>
               : Promise<Iterable<Pick<U, F>>>;
-          (query?: Param, options?: Opts): R;
+          (query?: Param, options?: Opts): Return;
         }
       : {
-          (query: Param): R;
+          (query: Param): Return;
           <F extends keyof U>(
             query: Param,
             options: { fields: F[] } & RequestOptions<U>,
-          ): R extends AsyncIterable<U>
+          ): Return extends AsyncIterable<U>
             ? Promise<AsyncIterable<Pick<U, F>>>
-            : R extends Promise<Array<U>>
+            : Return extends Promise<Array<U>>
               ? Promise<Array<Pick<U, F>>>
               : Promise<Iterable<Pick<U, F>>>;
-          (query: Param, Options?: Opts): R;
+          (query: Param, Options?: Opts): Return;
         }
-  : Param extends number
+  : // ID based op parameters
+    Param extends number
     ? {
-        (id: Param): R;
-        <F extends keyof Awaited<R>>(
+        (id: Param): Return;
+        <F extends keyof Awaited<Return>>(
           id: Param,
-          options: { fields: F[]; rawResponse: true } & RequestOptions<Awaited<R>>,
-        ): Promise<AxiosResponse<Pick<Awaited<R>, F>>>;
-        <F extends keyof Awaited<R>>(
+          options: { fields: F[]; rawResponse: true } & RequestOptions<Awaited<Return>>,
+        ): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+        <F extends keyof Awaited<Return>>(
           id: Param,
-          options: { fields: F[] } & RequestOptions<Awaited<R>>,
-        ): Promise<Pick<Awaited<R>, F>>;
+          options: { fields: F[] } & RequestOptions<Awaited<Return>>,
+        ): Promise<Pick<Awaited<Return>, F>>;
         (
           id: Param,
           options?: {
             rawResponse: true;
-          } & RequestOptions<Awaited<R>>,
-        ): Promise<AxiosResponse<Awaited<R>>>;
-        (id: Param, options?: RequestOptions<Awaited<R>>): R;
+          } & RequestOptions<Awaited<Return>>,
+        ): Promise<AxiosResponse<Awaited<Return>>>;
+        (id: Param, options?: RequestOptions<Awaited<Return>>): Return;
       }
-    : Param extends undefined
+    : Param extends number[]
       ? {
-          (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>>;
+          (ids: Param): Return;
+          <F extends keyof Awaited<Return>>(
+            ids: Param,
+            options: { fields: F[]; rawResponse: true } & RequestOptions<Awaited<Return>>,
+          ): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+          <F extends keyof Awaited<Return>>(
+            ids: Param,
+            options: { fields: F[] } & RequestOptions<Awaited<Return>>,
+          ): Promise<Pick<Awaited<Return>, F>>;
           (
-            entity?: Param,
+            ids: Param,
             options?: {
               rawResponse: true;
-            } & RequestOptions<Awaited<R>>,
-          ): Promise<AxiosResponse<Awaited<R>>>;
-          (entity?: Param, options?: RequestOptions<Awaited<R>>): R;
+            } & RequestOptions<Awaited<Return>>,
+          ): Promise<AxiosResponse<Awaited<Return>>>;
+          (ids: Param, options?: RequestOptions<Awaited<Return>>): Return;
         }
-      : // Entity based op parameter names
-        {
-          (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;
-        };
+      : // Undefined based op parameters - ensures ops that don't require a
+        // param aren't forced to specify `undefined` but can if they need to specify
+        // options
+        Param extends undefined
+        ? {
+            (): Return;
+            <F extends keyof Awaited<Return>>(
+              none: Param,
+              options: { fields: F[]; rawResponse: true } & RequestOptions<Awaited<Return>>,
+            ): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+            <F extends keyof Awaited<Return>>(
+              none: Param,
+              options: { fields: F[] } & RequestOptions<Awaited<Return>>,
+            ): Promise<Pick<Awaited<Return>, F>>;
+            (
+              none?: Param,
+              options?: {
+                rawResponse: true;
+              } & RequestOptions<Awaited<Return>>,
+            ): Promise<AxiosResponse<Awaited<Return>>>;
+            (none?: Param, options?: RequestOptions<Awaited<Return>>): Return;
+          }
+        : // Entity based op parameter names
+          {
+            (entity: Param): Return;
+            <F extends keyof Awaited<Return>>(
+              entity: Param,
+              options: { fields: F[]; rawResponse: true } & RequestOptions<Awaited<Return>>,
+            ): Promise<AxiosResponse<Pick<Awaited<Return>, F>>>;
+            <F extends keyof Awaited<Return>>(
+              entity: Param,
+              options: { fields: F[] } & RequestOptions<Awaited<Return>>,
+            ): Promise<Pick<Awaited<Return>, F>>;
+            (
+              entity: Param,
+              options?: {
+                rawResponse: true;
+              } & RequestOptions<Awaited<Return>>,
+            ): Promise<AxiosResponse<Awaited<Return>>>;
+            (entity: Param, options?: RequestOptions<Awaited<Return>>): Return;
+          };
 
 /** Wrapper type for expressing the response returned by a v2 list op supported endpoint */
 interface PagedResponse<T> {

package/src/service.ts

@@ -9,6 +9,7 @@ import {
   ShiftHistoryRecord,
   Terminal,
   ToilAllowance,
+  User,
   UserBreak,
   UserClockedIn,
   UserClockedOut,
@@ -34,6 +35,7 @@ import { ToilAllowanceQueryParams } from './interfaces/query-params/index.js';
 import { LogbookEntry, LogbookQueryParameters } from './interfaces/logbook.interface.js';
 import { Message } from './interfaces/message.interface.js';
 import { Invoice, InvoiceDownload } from './interfaces/invoice.interface.js';
+import { CreateUserRequest, CreateUserResponse, PartialUserV2 } from './interfaces/user-v2.interface.js';
 
 export type ServiceSpecification<CustomOp extends OpDef<unknown> = OpDef<any>> = {
   /** Operations allowed and usable for the endpoint */
@@ -495,4 +497,23 @@ export const SERVICES = {
     endpointVersion: 'v1',
     operations: ['create', 'get', 'list', 'listAll', 'update', 'delete'],
   },
+  userV2: {
+    endpoint: 'users',
+    endpointVersion: 'v2',
+    operations: ['create'],
+    customOperations: {
+      create: (
+        { request, service },
+        userSpec: {
+          users: RequirementsOf<CreateUserRequest, 'firstName' | 'lastName' | 'roles'>[];
+          sendInvite?: boolean;
+        },
+      ): RequestConfig<typeof userSpec, CreateUserResponse> => ({
+        ...request,
+        url: `${service.endpointVersion}/${service.endpoint}`,
+        method: 'POST',
+        data: userSpec,
+      }),
+    },
+  },
 } satisfies Record<string, ServiceSpecification>;

package/src/utils.ts

@@ -50,12 +50,14 @@ class AssertionError extends Error {
   override name = AssertionError.prototype.name;
 }
 
-/** Ensures the provided value resolves to `true` before continuing
- *
+/** 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
  *
+ * We don't use the `node:assert` package as this SDK needs to run in environments like
+ * web and mobile where the `node:assert` package may not be defined.
+ *
  * @param assertion assertion to verify
  * @param error error to throw. If `undefined` or a `string` then an {@link AssertionError}
  * will be thrown instead
@@ -81,6 +83,7 @@ function toSearchParams(parameters?: Record<string, QueryParameterValue>): URLSe
   return new URLSearchParams(reducedParams);
 }
 
+/** Interceptor for {@link AxiosError}s mapping them into {@link SDKError} */
 function parseClientError(error: AxiosError): SDKError {
   const axiosErrorLocation = error.response || error.request;
   const apiErrorMessage = axiosErrorLocation.data?.message ?? axiosErrorLocation.data?.error;