@managemint-solutions/entities 1.27.0 → 1.32.0

package/dist/audit-trail/enum/index.d.ts

@@ -24,6 +24,7 @@ export declare enum AuditTrailEntityType {
     LEAVE_TYPES = "leave_types",
     LEAVE_ENTITLEMENTS = "leave_entitlements",
     LEAVE_REQUESTS = "leave_requests",
+    LEAVE_ADJUSTMENTS = "leave_adjustments",
     BILLING_TRANSACTIONS = "billing_transactions",
     INVOICE = "invoices",
     NOTIFICATION = "notifications"

package/dist/audit-trail/enum/index.js

@@ -29,6 +29,7 @@ var AuditTrailEntityType;
     AuditTrailEntityType["LEAVE_TYPES"] = "leave_types";
     AuditTrailEntityType["LEAVE_ENTITLEMENTS"] = "leave_entitlements";
     AuditTrailEntityType["LEAVE_REQUESTS"] = "leave_requests";
+    AuditTrailEntityType["LEAVE_ADJUSTMENTS"] = "leave_adjustments";
     AuditTrailEntityType["BILLING_TRANSACTIONS"] = "billing_transactions";
     AuditTrailEntityType["INVOICE"] = "invoices";
     AuditTrailEntityType["NOTIFICATION"] = "notifications";

package/dist/leave/dto/index.d.ts

@@ -1,4 +1,4 @@
-import { LeaveRequestStatus, LeaveReviewDecision } from '../enum';
+import { LeaveGrantMethod, LeaveRequestStatus, LeaveReviewDecision } from '../enum';
 /**
  * The wire shapes of the leave routes. The api runs a global ValidationPipe with
  * `forbidNonWhitelisted`, so every field a route accepts is declared here and mirrored by
@@ -14,21 +14,29 @@ export type GetLeaveTypesDto = {
     /** Omitted = every type; true/false filters on the flag. */
     active?: boolean | null;
 };
-export type CreateLeaveTypeDto = {
-    name: string;
-    description: string | null;
+/** The policy half of a leave type; see LeaveTypeEntity for what each field means. */
+type LeaveTypePolicyDto = {
     default_days: number;
     is_paid: boolean;
     requires_approval: boolean;
-    requires_document: boolean;
+    document_after_days: number | null;
+    cycle_years: number;
+    grant_method: LeaveGrantMethod;
+    max_carry_over_days: number;
+    carry_over_expiry_months: number | null;
+    min_service_months: number;
+    min_days_per_week: number;
+    initial_months: number;
+    initial_days_per_month: number | null;
+    paid_on_exit: boolean;
 };
-export type UpdateLeaveTypeDto = {
+export type CreateLeaveTypeDto = LeaveTypePolicyDto & {
+    name: string;
+    description: string | null;
+};
+export type UpdateLeaveTypeDto = LeaveTypePolicyDto & {
     name: string;
     description: string | null;
-    default_days: number;
-    is_paid: boolean;
-    requires_approval: boolean;
-    requires_document: boolean;
     active: boolean;
 };
 export type LeaveEntitlementIdDto = {
@@ -45,20 +53,36 @@ export type GetLeaveEntitlementsDto = {
 export type CreateLeaveEntitlementDto = {
     user_id: string;
     leave_type_id: string;
-    days_entitled: number;
-    /** Null = the organization's current leave year. */
+    /** Null = the type's `default_days`, pro-rated when the period is shorter than a full cycle. */
+    days_entitled: number | null;
+    /** Null = the start of the type's current cycle for this person (their start date, if later). */
     period_start: string | null;
-    /** Null = one year after `period_start`, less a day. */
+    /** Null = the end of that cycle. */
     period_end: string | null;
-    max_carry_over_days: number;
+    /** Null = the type's cap. */
+    max_carry_over_days: number | null;
+    /** An opening balance brought in from before - 0 for none. */
+    days_carried: number;
+    carried_expires_on: string | null;
     notes: string | null;
 };
 export type UpdateLeaveEntitlementDto = {
     days_entitled: number;
-    period_end: string;
     max_carry_over_days: number;
+    days_carried: number;
+    carried_expires_on: string | null;
     notes: string | null;
 };
+/** One entitlement of a type for each person in `user_ids` (null = every active user), for their current cycle. */
+export type BulkCreateLeaveEntitlementsDto = {
+    leave_type_id: string;
+    user_ids: string[] | null;
+};
+export type CreateLeaveAdjustmentDto = {
+    /** Either sign, never zero. */
+    days: number;
+    reason: string;
+};
 export type LeaveRequestIdDto = {
     leaveRequestId: string;
 };
@@ -72,8 +96,9 @@ export type GetLeaveRequestsDto = {
     start_date_after?: string | null;
     start_date_before?: string | null;
 };
-/** Always the caller's own request: there is no `user_id` to file on someone's behalf. */
 export type CreateLeaveRequestDto = {
+    /** Null = the caller's own request; a manager may file one for a report. */
+    user_id: string | null;
     leave_type_id: string;
     start_date: string;
     end_date: string;
@@ -92,3 +117,11 @@ export type ReviewLeaveRequestDto = {
     status: LeaveReviewDecision;
     review_note: string | null;
 };
+/** The organization-wide calendar: pending and approved leave touching `date_from`..`date_to`. */
+export type GetLeaveCalendarDto = {
+    date_from: string;
+    date_to: string;
+    user_id?: string | null;
+    leave_type_id?: string | null;
+};
+export {};

package/dist/leave/enum/index.d.ts

@@ -1,8 +1,7 @@
 /**
  * The lifecycle of a leave request. Stored as text on `leave_requests.status` and validated
  * here, never by a Postgres enum. `pending` moves to any of the other three; `approved` may
- * still be cancelled (a future booking the employee no longer needs); `rejected` and
- * `cancelled` are terminal.
+ * still be cancelled by a manager before its first day; `rejected` and `cancelled` are terminal.
  */
 export declare enum LeaveRequestStatus {
     PENDING = "pending",
@@ -15,3 +14,8 @@ export declare enum LeaveReviewDecision {
     APPROVED = "approved",
     REJECTED = "rejected"
 }
+/** Whether a period's days are all available on its first day, or earned month by month. */
+export declare enum LeaveGrantMethod {
+    UPFRONT = "upfront",
+    MONTHLY = "monthly"
+}

package/dist/leave/enum/index.js

@@ -1,11 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LeaveReviewDecision = exports.LeaveRequestStatus = void 0;
+exports.LeaveGrantMethod = exports.LeaveReviewDecision = exports.LeaveRequestStatus = void 0;
 /**
  * The lifecycle of a leave request. Stored as text on `leave_requests.status` and validated
  * here, never by a Postgres enum. `pending` moves to any of the other three; `approved` may
- * still be cancelled (a future booking the employee no longer needs); `rejected` and
- * `cancelled` are terminal.
+ * still be cancelled by a manager before its first day; `rejected` and `cancelled` are terminal.
  */
 var LeaveRequestStatus;
 (function (LeaveRequestStatus) {
@@ -20,3 +19,9 @@ var LeaveReviewDecision;
     LeaveReviewDecision["APPROVED"] = "approved";
     LeaveReviewDecision["REJECTED"] = "rejected";
 })(LeaveReviewDecision || (exports.LeaveReviewDecision = LeaveReviewDecision = {}));
+/** Whether a period's days are all available on its first day, or earned month by month. */
+var LeaveGrantMethod;
+(function (LeaveGrantMethod) {
+    LeaveGrantMethod["UPFRONT"] = "upfront";
+    LeaveGrantMethod["MONTHLY"] = "monthly";
+})(LeaveGrantMethod || (exports.LeaveGrantMethod = LeaveGrantMethod = {}));

package/dist/leave/index.d.ts

@@ -1,4 +1,4 @@
-import { LeaveRequestStatus } from './enum';
+import { LeaveGrantMethod, LeaveRequestStatus } from './enum';
 import { UserIdentity } from '../users';
 export * from './enum';
 /**
@@ -11,8 +11,13 @@ export type LeaveTypeIdentity = {
     mms_id: string;
     name: string;
     /** Carried on requests and entitlements so a reviewer knows without a second fetch. */
-    requires_document: boolean;
+    document_after_days: number | null;
 };
+/**
+ * A leave type is also its policy. The policy fields are copied onto an entitlement when it is
+ * created, so editing a type shapes the periods created after the edit and never rewrites a
+ * balance that already exists.
+ */
 export type LeaveTypeEntity = {
     mms_id: string;
     created_at: string;
@@ -21,22 +26,67 @@ export type LeaveTypeEntity = {
     last_updated_by: UserIdentity | null;
     name: string;
     description: string | null;
-    /** The days a full year of this type is worth - the suggested entitlement. */
+    /** The days a full cycle of this type is worth; a shorter first cycle gets its share. */
     default_days: number;
     is_paid: boolean;
     /** False auto-approves a request on submission. */
     requires_approval: boolean;
-    /** Approval waits until a supporting file is attached to the request; implies `requires_approval`. */
-    requires_document: boolean;
+    /**
+     * Approval waits for a supporting file when a request is longer than this many days: 0 asks
+     * for one on every request, 2 on the third day onwards (the BCEA sick note), null never.
+     * Needs `requires_approval`.
+     */
+    document_after_days: number | null;
+    /**
+     * How many leave years one cycle runs: 1 for annual leave, 3 for a three-year sick-leave
+     * cycle. Every cycle starts in the organization's leave-year month; a person's first cycle
+     * begins in the leave year they joined and is pro-rated from their start date.
+     */
+    cycle_years: number;
+    grant_method: LeaveGrantMethod;
+    /** The most unused days the rollover carries into the next cycle. */
+    max_carry_over_days: number;
+    /** Carried days not taken within this many months of the new cycle are forfeited; null keeps them. */
+    carry_over_expiry_months: number | null;
+    /** Service needed before this type can be requested (4 for family responsibility leave). */
+    min_service_months: number;
+    /** Working days a week needed before this type can be requested (4 for family responsibility). */
+    min_days_per_week: number;
+    /**
+     * A slower rate for a person's first months: during `initial_months` from their start date
+     * they earn `initial_days_per_month` per completed month, capped at the cycle's days. The
+     * BCEA sick-leave rule of a day per 26 worked for the first six months is 6 and 0.83.
+     */
+    initial_months: number;
+    initial_days_per_month: number | null;
+    /** Unused days are paid out when someone leaves - annual leave, under the BCEA. */
+    paid_on_exit: boolean;
     /** An inactive type keeps its history but cannot be chosen for new requests. */
     active: boolean;
 };
-/** The window an entitlement covers - normally the organization's leave year. */
+/** The window an entitlement covers - one cycle of its type, or the part of it after a joiner started. */
 export type LeavePeriod = {
     period_start: string;
     period_end: string;
 };
-export type LeaveEntitlementEntity = LeavePeriod & {
+/**
+ * The balance of an entitlement on `as_of`. Nothing here is stored; it is worked out from the
+ * entitlement, its adjustments and the requests whose start date falls inside the period.
+ * `days_remaining` is accrued + carried - forfeited + adjusted - used - pending.
+ */
+export type LeaveBalance = {
+    as_of: string;
+    /** The part of `days_entitled` earned by `as_of` - all of it on an upfront type. */
+    days_accrued: number;
+    /** Carried days that expired before they were taken. */
+    days_forfeited: number;
+    /** The sum of the manual adjustments, either sign. */
+    days_adjusted: number;
+    days_used: number;
+    days_pending: number;
+    days_remaining: number;
+};
+export type LeaveEntitlementEntity = LeavePeriod & LeaveBalance & {
     mms_id: string;
     created_at: string;
     created_by: UserIdentity | null;
@@ -44,17 +94,29 @@ export type LeaveEntitlementEntity = LeavePeriod & {
     last_updated_by: UserIdentity | null;
     user: UserIdentity;
     leave_type: LeaveTypeIdentity;
+    /** The days this period is worth, excluding anything carried in. */
     days_entitled: number;
+    /** Unused days brought in from the previous period; spent before `days_entitled`. */
+    days_carried: number;
+    /** The last day carried days can be taken; null when they do not expire. */
+    carried_expires_on: string | null;
+    /** Copied from the type when this entitlement was created, like the three below. */
+    grant_method: LeaveGrantMethod;
+    /** The last day of the slower first-months rate, or null when it does not apply. */
+    initial_until: string | null;
+    initial_days_per_month: number | null;
     /** Cap on the unused days the nightly rollover carries into the next period. */
     max_carry_over_days: number;
     notes: string | null;
-    /**
-     * Computed on read, never stored: the approved and pending requests of this user and
-     * type whose start date falls inside the period. `days_remaining` already subtracts both.
-     */
-    days_used: number;
-    days_pending: number;
-    days_remaining: number;
+};
+/** A manual correction to an entitlement, either sign. Never edited or deleted - a mistake is corrected by another. */
+export type LeaveAdjustmentEntity = {
+    mms_id: string;
+    created_at: string;
+    created_by: UserIdentity | null;
+    leave_entitlement_id: string;
+    days: number;
+    reason: string;
 };
 export type LeaveRequestEntity = {
     mms_id: string;
@@ -69,7 +131,7 @@ export type LeaveRequestEntity = {
     /** Only for a single-day request; halves its `days`. */
     is_half_day: boolean;
     /**
-     * Working days (Monday to Friday, less the organization's public holidays) as counted
+     * The requester's working days (their `working_days`, less public holidays) as counted
      * when the request was submitted or last edited. A snapshot: a holiday added afterwards
      * does not rewrite approved history.
      */
@@ -83,3 +145,30 @@ export type LeaveRequestEntity = {
     cancelled_by: UserIdentity | null;
     cancelled_at: string | null;
 };
+/** Who is off when: the organization-wide calendar, without reasons or review notes. */
+export type LeaveCalendarEntry = {
+    mms_id: string;
+    user: UserIdentity;
+    /** Who filed it - a manager, when it differs from `user`. */
+    created_by: UserIdentity | null;
+    leave_type: {
+        mms_id: string;
+        name: string;
+    };
+    start_date: string;
+    end_date: string;
+    is_half_day: boolean;
+    status: LeaveRequestStatus;
+};
+/** What `POST /bulk` did: one entitlement per person created, or skipped with the reason why. */
+export type BulkLeaveEntitlementsResult = {
+    created: number;
+    skipped: {
+        user: UserIdentity;
+        reason: string;
+    }[];
+};
+/** A private subscription address for the leave calendar; shown once, when it is made. */
+export type LeaveCalendarFeedEntity = {
+    url: string;
+};

package/dist/modules/index.d.ts

@@ -17,6 +17,8 @@ export declare const MODULE_KEYS: {
 export type BillingModule = {
     mms_id: string;
     module_key: string;
+    /** What the module is called on screen ("Client and Project Management"). */
+    name: string;
     active: boolean;
 };
 /**
@@ -26,6 +28,8 @@ export type BillingModule = {
 export type PricedModule = {
     module_id: string;
     module_key: string;
+    /** The catalog name, for display. */
+    name: string;
     unit_amount_minor: number;
     currency: string;
 };

package/dist/notifications/enum/index.d.ts

@@ -16,6 +16,8 @@ export declare enum NotificationType {
     LEAVE_REQUEST_SUBMITTED = "leave_request_submitted",
     LEAVE_REQUEST_APPROVED = "leave_request_approved",
     LEAVE_REQUEST_REJECTED = "leave_request_rejected",
+    LEAVE_REQUEST_CANCELLED = "leave_request_cancelled",
+    LEAVE_REQUEST_FILED_FOR_YOU = "leave_request_filed_for_you",
     TIMESHEET_SUBMITTED = "timesheet_submitted",
     TIMESHEET_APPROVED = "timesheet_approved",
     TIMESHEET_REJECTED = "timesheet_rejected",

package/dist/notifications/enum/index.js

@@ -24,6 +24,8 @@ var NotificationType;
     NotificationType["LEAVE_REQUEST_SUBMITTED"] = "leave_request_submitted";
     NotificationType["LEAVE_REQUEST_APPROVED"] = "leave_request_approved";
     NotificationType["LEAVE_REQUEST_REJECTED"] = "leave_request_rejected";
+    NotificationType["LEAVE_REQUEST_CANCELLED"] = "leave_request_cancelled";
+    NotificationType["LEAVE_REQUEST_FILED_FOR_YOU"] = "leave_request_filed_for_you";
     NotificationType["TIMESHEET_SUBMITTED"] = "timesheet_submitted";
     NotificationType["TIMESHEET_APPROVED"] = "timesheet_approved";
     NotificationType["TIMESHEET_REJECTED"] = "timesheet_rejected";

package/dist/organization/dto/index.d.ts

@@ -60,4 +60,6 @@ export type UpdateOrganizationDto = {
     industry?: string | null;
     marketing_consent?: boolean;
     currency?: string;
+    /** The month (1-12) the leave year starts on; shapes entitlements created after the change. */
+    leave_calendar_start_month?: number;
 };

package/dist/users/dto/index.d.ts

@@ -8,6 +8,8 @@ export type GetUsersDto = {
     page_size: number;
     /** Comma-joined booleans on the wire, e.g. "true,false". Absent = all users. */
     active_in?: string | null;
+    /** A manager's team: everyone naming this user as their manager or second manager. */
+    manager_id?: string | null;
 };
 export type CreateUserDto = {
     email: string;
@@ -29,6 +31,8 @@ export type UpdateUserDto = {
     start_date?: string | null;
     end_date?: string | null;
     employment_type?: EmploymentType | null;
+    /** ISO weekdays, 1 (Monday) to 7 (Sunday), at least one. */
+    working_days?: number[];
     job_title?: string | null;
     manager_id?: string | null;
     /** Must differ from `manager_id` and needs a manager set first; the api refuses otherwise. */

package/dist/users/index.d.ts

@@ -39,6 +39,8 @@ export interface UserEntity {
     job_title: string | null;
     start_date: Date;
     end_date: Date | null;
+    /** ISO weekdays this person works, 1 (Monday) to 7 (Sunday); leave counts only these days. */
+    working_days: number[];
     social_facebook: URL | null;
     social_linkedin: URL | null;
     social_twitter: URL | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/entities",
-  "version": "1.27.0",
+  "version": "1.32.0",
   "description": "Entity types used by both the api and portal",
   "homepage": "https://github.com/ManageMint-Solutions/managemint-solutions-entities#readme",
   "bugs": {