@managemint-solutions/sdk 0.39.0 → 0.40.0

package/README.md

@@ -275,8 +275,11 @@ const deleted = await users.remove(userId);                              // hard
 ```
 
 Cross-tenant lookups - the organization behind a Paystack code, a ledger row by id, every
-organization with a Paystack customer - hang off `service` itself, because a webhook or cron does
-not know its tenant until it looks one up.
+organization with a Paystack customer, every organization whose leave year starts in a given month
+(`organizationsWithLeaveYearStartingIn(month)` → `{ mms_id, modules }[]`)
+- hang off `service` itself, because a webhook or cron does not know its tenant until it looks one
+up. The scope also carries `leaveTypes`, `leaveEntitlements` and `leaveRequests` for the leave-year
+rollover, whose writes are attributed to the system.
 
 `update` / `transition` / `remove` pre-read the flat row (by `mms_id`, and by `organization_id`
 unless `scopeByOrganization: false` - the `organizations` table is its own tenant), so a missing
@@ -424,7 +427,7 @@ const today = todayInJohannesburg();                                        // "
 
 ```ts
 const types = await supabase.leaveTypes.list({ active: true });
-const annual = await supabase.leaveTypes.create({ name: 'Annual', description: null, default_days: 15, is_paid: true, requires_approval: true });
+const annual = await supabase.leaveTypes.create({ name: 'Annual', description: null, default_days: 15, is_paid: true, requires_approval: true, requires_document: false });
 await supabase.leaveTypes.remove(annual.mms_id);        // hard delete; 409 once a request or entitlement references it
 
 const taken = await supabase.leaveEntitlements.overlaps(userId, annual.mms_id, '2026-01-01', '2026-12-31'); // an entitlement of that type already covers part of the period
@@ -440,6 +443,27 @@ const annualOnly = await supabase.leaveRequests.list({ ...query, leave_type_id:
 const reports = await supabase.leaveRequests.list(query, { userIds: [me, ...(await supabase.users.idsManagedBy(me))] });
 ```
 
+A leave type with `requires_document` set is one the api will not approve until a supporting file
+is attached to the request; the `leave_type` embed on requests and entitlements carries the flag so
+a caller need not fetch the type. The reporting line is two deep on the user: `manager_id` and
+`secondary_manager_id` (`UpdateUserDto`, both v4 user ids, nullable), and
+`users.idsManagedBy(managerId)` returns everyone naming that person as either - one level down,
+`active` ignored.
+
+An entitlement carries `max_carry_over_days` (HR-set, default 0): on the leave-year boundary the
+api's nightly rollover creates next period's entitlement for each person and type as
+`default_days + min(unused, cap)`. What it runs on:
+
+```ts
+import { leavePeriodFor, shiftDays } from '@managemint-solutions/sdk';
+
+const scope = service.forOrganization(organizationId);                  // system actor: created_by stays null
+const ended = leavePeriodFor(shiftDays(today, -1), startMonth);          // the period that closed yesterday
+const rows = await scope.leaveEntitlements.endingOn(ended.period_end);   // every entitlement ending that day, balances included, paged
+const active = new Set(await scope.users.activeIds());                   // who still gets a new period
+await scope.leaveEntitlements.create({ ...next, user_id, leave_type_id, days_entitled, max_carry_over_days, notes });
+```
+
 `review`, `cancel` and `update` are compare-and-set writes (`updateWhere`): they land only while
 the request is still in the status they expect and resolve to `null` otherwise, so two reviewers
 cannot both decide the same request. The `leave_requests` table also carries an exclusion
@@ -448,6 +472,54 @@ constraint so two overlapping live requests of one user cannot both be inserted
 Notes, additional details and supporting files may attach to leave as well: their `entity`
 accepts `leave_requests` and `leave_entitlements` alongside the CRM entity types.
 
+## Timesheets
+
+The second slice of the HR module: `timesheet_entries` (what an employee logs - a date, a start and
+end `HH:MM`, optionally a client / project / task, a description) grouped into `timesheets`, one
+row per person and Monday-to-Sunday week, which the employee submits and a manager approves or
+rejects with a note. Both are org-scoped audited resources on the caller's client. A week's
+`total_minutes` / `entry_count` are counted on read from its entries, never stored;
+`duration_minutes` on an entry is generated by Postgres. Times are read back trimmed to `HH:MM`
+(the column is `time`), so a row can be sent straight back in; `24:00` is a valid end for a shift
+finishing at midnight, and an entry never crosses midnight - split it.
+
+The week arithmetic is plain exported functions, shared with the api:
+
+```ts
+import { minutesBetween, weekStartOf } from '@managemint-solutions/sdk';
+
+weekStartOf('2026-09-27');       // '2026-09-21' - a Sunday belongs to the week before it
+minutesBetween('22:00', '24:00'); // 120; zero or negative when the end is not after the start
+```
+
+```ts
+const weekStart = weekStartOf(body.date);
+const week =
+  (await supabase.timesheets.findFor(me, weekStart)) ??                  // { mms_id, status, week_start } or null
+  (await supabase.timesheets.create({ user_id: me, week_start: weekStart })); // opened as a draft
+
+const clash = await supabase.timesheetEntries.overlaps(me, body.date, body.start_time, body.end_time); // same day, sharing a minute
+const entry = await supabase.timesheetEntries.create({ timesheet_id: week.mms_id, user_id: me, ...body });
+await supabase.timesheetEntries.update(entry.mms_id, { timesheet_id: week.mms_id, ...body });
+await supabase.timesheetEntries.remove(entry.mms_id);
+
+const mine = await supabase.timesheets.list({ ...query, user_id: me });  // one list; user_id / status / week_start narrow it
+const reports = await supabase.timesheets.list(query, { userIds: [me, ...(await supabase.users.idsManagedBy(me))] });
+const detail = await supabase.timesheets.getById(week.mms_id);          // summary + entries
+const submitted = await supabase.timesheets.submit(week.mms_id);         // null = no longer draft or rejected
+const reviewed = await supabase.timesheets.review(week.mms_id, { status: TimesheetReviewDecision.APPROVED, reviewed_by: managerId, review_note: null }); // null = no longer submitted
+
+// The report: the api aggregates flat rows, keeping only the entries of approved weeks.
+const approved = await supabase.timesheets.approvedIds(userIds, date_from, date_to);
+const rows = (await supabase.timesheetEntries.forReport(userIds, date_from, date_to)).filter((row) => approved.has(row.timesheet_id));
+```
+
+`submit` and `review` are compare-and-set writes (`updateWhere`): `submit` lands only on a draft or
+rejected week (and clears the previous decision), `review` only on a submitted one, and each
+resolves to `null` otherwise. The `timesheet_entries` table also carries an exclusion constraint so
+two overlapping entries of one user cannot both be inserted in a race. `forReport`, `approvedIds`
+and the per-page totals walk their tables in pages of 1000, PostgREST's row cap.
+
 ## Public holidays
 
 The public-holiday calendar, `public_holidays`, on the caller's client as `supabase.publicHolidays`.

package/dist/client.d.ts

@@ -16,6 +16,7 @@ import { PublicHolidaysResource } from './public-holidays';
 import { StatusesResource } from './statuses';
 import { SupportingFilesResource } from './supporting-files';
 import { TasksResource } from './tasks';
+import { TimesheetEntriesResource, TimesheetsResource } from './timesheets';
 import { UsersResource } from './users';
 export type TypedSupabaseClient = SupabaseJsClient;
 export type SupabaseClientConfig = {
@@ -62,6 +63,8 @@ export declare class SupabaseClient {
     readonly publicHolidays: PublicHolidaysResource;
     readonly leaveEntitlements: LeaveEntitlementsResource;
     readonly leaveRequests: LeaveRequestsResource;
+    readonly timesheets: TimesheetsResource;
+    readonly timesheetEntries: TimesheetEntriesResource;
     constructor(config: SupabaseClientConfig);
 }
 export declare const createSupabaseClient: (config: SupabaseClientConfig) => SupabaseClient;

package/dist/client.js

@@ -18,6 +18,7 @@ const public_holidays_1 = require("./public-holidays");
 const statuses_1 = require("./statuses");
 const supporting_files_1 = require("./supporting-files");
 const tasks_1 = require("./tasks");
+const timesheets_1 = require("./timesheets");
 const users_1 = require("./users");
 /**
  * The caller's data client: every query carries their bearer token, so RLS decides what they
@@ -47,6 +48,8 @@ class SupabaseClient {
     publicHolidays;
     leaveEntitlements;
     leaveRequests;
+    timesheets;
+    timesheetEntries;
     constructor(config) {
         this.auth = config.auth;
         this.supabase =
@@ -72,6 +75,8 @@ class SupabaseClient {
         this.publicHolidays = new public_holidays_1.PublicHolidaysResource(this.supabase);
         this.leaveEntitlements = new leave_1.LeaveEntitlementsResource(this.supabase, this.auth, this.audit);
         this.leaveRequests = new leave_1.LeaveRequestsResource(this.supabase, this.auth, this.audit);
+        this.timesheets = new timesheets_1.TimesheetsResource(this.supabase, this.auth, this.audit);
+        this.timesheetEntries = new timesheets_1.TimesheetEntriesResource(this.supabase, this.auth, this.audit);
     }
 }
 exports.SupabaseClient = SupabaseClient;

package/dist/index.d.ts

@@ -39,5 +39,8 @@ export { CreateTaskDto, GetTasksDto, TaskIdDto, UpdateTaskDto } from './tasks';
 export type { CreateLeaveEntitlementInput, CreateLeaveRequestRow, LeaveEntitlementCover, ReviewLeaveRequestRow, UpdateLeaveRequestRow, } from './leave';
 export { CreateLeaveEntitlementDto, CreateLeaveRequestDto, CreateLeaveTypeDto, GetLeaveEntitlementsDto, GetLeaveRequestsDto, GetLeaveTypesDto, LeaveEntitlementIdDto, LeaveRequestIdDto, LeaveTypeIdDto, ReviewLeaveRequestDto, UpdateLeaveEntitlementDto, UpdateLeaveRequestDto, UpdateLeaveTypeDto, } from './leave';
 export { GetPublicHolidaysDto } from './public-holidays';
-export { addOneYearMinusDay, countWorkingDays, isWithinPeriod, leavePeriodFor, todayInJohannesburg, } from './leave';
+export { addOneYearMinusDay, countWorkingDays, isWithinPeriod, leavePeriodFor, shiftDays, todayInJohannesburg, } from './leave';
+export type { CreateTimesheetEntryRow, CreateTimesheetRow, ReviewTimesheetRow, TimesheetCover, TimesheetReportRow, UpdateTimesheetEntryRow, } from './timesheets';
+export { CreateTimesheetEntryDto, GetTimesheetReportDto, GetTimesheetsDto, ReviewTimesheetDto, TimesheetEntryIdDto, TimesheetIdDto, UpdateTimesheetEntryDto, } from './timesheets';
+export { minutesBetween, weekStartOf } from './timesheets';
 export { monthlyTotalMinor } from './pricebooks';

package/dist/index.js

@@ -8,7 +8,7 @@
 // to keep. The row and input types they produce and accept are exported for annotations.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UserIdDto = exports.UpdateUserDto = exports.UpdateMyProfileDto = exports.GetUsersQueryDto = exports.AddUserDto = exports.UpdatePermissionsDto = exports.PermissionsResource = exports.UpdateOrganizationDto = exports.CreateOrganizationDto = exports.NotificationIdDto = exports.GetNotificationsDto = exports.NoteIdDto = exports.GetNotesDto = exports.AddNoteDto = exports.UpdateAdditionalDetailsDto = exports.IsAdditionalDetailsValueByType = exports.GetAdditionalDetailsDto = exports.AdditionalDetailsIdDto = exports.AddAdditionalDetailsDto = exports.UpdateStatusDto = exports.StatusIdDto = exports.GetStatusesDto = exports.AddStatusDto = exports.CreateSupportRequestDto = exports.UpdateConfigDto = exports.CreateConfigDto = exports.CreateFeatureRequestDto = exports.InvoiceIdDto = exports.GetInvoicesQueryDto = exports.ReinstateSubscriptionDto = exports.PurchaseModuleDto = exports.PaymentIdDto = exports.InitialPaymentDto = exports.GetPaymentsQueryDto = exports.CancelSubscriptionDto = exports.GetAuditTrailDto = exports.IsNullable = exports.EmptyToNull = exports.SupabaseClientError = exports.createSupabaseServiceClient = exports.SupabaseServiceClient = exports.SignInDto = exports.SendPasswordResetEmailDto = exports.ResetPasswordDto = exports.ExchangeTokenHashDto = exports.ExchangeRefreshTokenDto = exports.createSupabaseAuthClient = exports.SupabaseAuthClient = exports.createSupabaseClient = exports.SupabaseClient = void 0;
-exports.monthlyTotalMinor = exports.todayInJohannesburg = exports.leavePeriodFor = exports.isWithinPeriod = exports.countWorkingDays = exports.addOneYearMinusDay = exports.GetPublicHolidaysDto = exports.UpdateLeaveTypeDto = exports.UpdateLeaveRequestDto = exports.UpdateLeaveEntitlementDto = exports.ReviewLeaveRequestDto = exports.LeaveTypeIdDto = exports.LeaveRequestIdDto = exports.LeaveEntitlementIdDto = exports.GetLeaveTypesDto = exports.GetLeaveRequestsDto = exports.GetLeaveEntitlementsDto = exports.CreateLeaveTypeDto = exports.CreateLeaveRequestDto = exports.CreateLeaveEntitlementDto = exports.UpdateTaskDto = exports.TaskIdDto = exports.GetTasksDto = exports.CreateTaskDto = exports.UpdateProjectDto = exports.ProjectIdDto = exports.GetProjectsDto = exports.CreateProjectDto = exports.UpdateClientDto = exports.GetClientsDto = exports.CreateClientDto = exports.ClientIdDto = exports.SupportingFileIdDto = exports.GetSupportingFilesDto = void 0;
+exports.monthlyTotalMinor = exports.weekStartOf = exports.minutesBetween = exports.UpdateTimesheetEntryDto = exports.TimesheetIdDto = exports.TimesheetEntryIdDto = exports.ReviewTimesheetDto = exports.GetTimesheetsDto = exports.GetTimesheetReportDto = exports.CreateTimesheetEntryDto = exports.todayInJohannesburg = exports.shiftDays = exports.leavePeriodFor = exports.isWithinPeriod = exports.countWorkingDays = exports.addOneYearMinusDay = exports.GetPublicHolidaysDto = exports.UpdateLeaveTypeDto = exports.UpdateLeaveRequestDto = exports.UpdateLeaveEntitlementDto = exports.ReviewLeaveRequestDto = exports.LeaveTypeIdDto = exports.LeaveRequestIdDto = exports.LeaveEntitlementIdDto = exports.GetLeaveTypesDto = exports.GetLeaveRequestsDto = exports.GetLeaveEntitlementsDto = exports.CreateLeaveTypeDto = exports.CreateLeaveRequestDto = exports.CreateLeaveEntitlementDto = exports.UpdateTaskDto = exports.TaskIdDto = exports.GetTasksDto = exports.CreateTaskDto = exports.UpdateProjectDto = exports.ProjectIdDto = exports.GetProjectsDto = exports.CreateProjectDto = exports.UpdateClientDto = exports.GetClientsDto = exports.CreateClientDto = exports.ClientIdDto = exports.SupportingFileIdDto = exports.GetSupportingFilesDto = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "SupabaseClient", { enumerable: true, get: function () { return client_1.SupabaseClient; } });
 Object.defineProperty(exports, "createSupabaseClient", { enumerable: true, get: function () { return client_1.createSupabaseClient; } });
@@ -122,6 +122,19 @@ Object.defineProperty(exports, "addOneYearMinusDay", { enumerable: true, get: fu
 Object.defineProperty(exports, "countWorkingDays", { enumerable: true, get: function () { return leave_2.countWorkingDays; } });
 Object.defineProperty(exports, "isWithinPeriod", { enumerable: true, get: function () { return leave_2.isWithinPeriod; } });
 Object.defineProperty(exports, "leavePeriodFor", { enumerable: true, get: function () { return leave_2.leavePeriodFor; } });
+Object.defineProperty(exports, "shiftDays", { enumerable: true, get: function () { return leave_2.shiftDays; } });
 Object.defineProperty(exports, "todayInJohannesburg", { enumerable: true, get: function () { return leave_2.todayInJohannesburg; } });
+var timesheets_1 = require("./timesheets");
+Object.defineProperty(exports, "CreateTimesheetEntryDto", { enumerable: true, get: function () { return timesheets_1.CreateTimesheetEntryDto; } });
+Object.defineProperty(exports, "GetTimesheetReportDto", { enumerable: true, get: function () { return timesheets_1.GetTimesheetReportDto; } });
+Object.defineProperty(exports, "GetTimesheetsDto", { enumerable: true, get: function () { return timesheets_1.GetTimesheetsDto; } });
+Object.defineProperty(exports, "ReviewTimesheetDto", { enumerable: true, get: function () { return timesheets_1.ReviewTimesheetDto; } });
+Object.defineProperty(exports, "TimesheetEntryIdDto", { enumerable: true, get: function () { return timesheets_1.TimesheetEntryIdDto; } });
+Object.defineProperty(exports, "TimesheetIdDto", { enumerable: true, get: function () { return timesheets_1.TimesheetIdDto; } });
+Object.defineProperty(exports, "UpdateTimesheetEntryDto", { enumerable: true, get: function () { return timesheets_1.UpdateTimesheetEntryDto; } });
+// The week arithmetic, like the leave calendar: plain functions the api resolves a week with.
+var timesheets_2 = require("./timesheets");
+Object.defineProperty(exports, "minutesBetween", { enumerable: true, get: function () { return timesheets_2.minutesBetween; } });
+Object.defineProperty(exports, "weekStartOf", { enumerable: true, get: function () { return timesheets_2.weekStartOf; } });
 var pricebooks_1 = require("./pricebooks");
 Object.defineProperty(exports, "monthlyTotalMinor", { enumerable: true, get: function () { return pricebooks_1.monthlyTotalMinor; } });

package/dist/leave/dto.d.ts

@@ -12,6 +12,7 @@ export declare class CreateLeaveTypeDto implements CreateLeaveTypeDtoType {
     readonly default_days: number;
     readonly is_paid: boolean;
     readonly requires_approval: boolean;
+    readonly requires_document: boolean;
 }
 export declare class UpdateLeaveTypeDto implements UpdateLeaveTypeDtoType {
     readonly name: string;
@@ -19,6 +20,7 @@ export declare class UpdateLeaveTypeDto implements UpdateLeaveTypeDtoType {
     readonly default_days: number;
     readonly is_paid: boolean;
     readonly requires_approval: boolean;
+    readonly requires_document: boolean;
     readonly active: boolean;
 }
 export declare class LeaveEntitlementIdDto implements LeaveEntitlementIdDtoType {
@@ -35,12 +37,14 @@ export declare class CreateLeaveEntitlementDto implements CreateLeaveEntitlement
     readonly user_id: string;
     readonly leave_type_id: string;
     readonly days_entitled: number;
+    readonly max_carry_over_days: number;
     readonly period_start: string | null;
     readonly period_end: string | null;
     readonly notes: string | null;
 }
 export declare class UpdateLeaveEntitlementDto implements UpdateLeaveEntitlementDtoType {
     readonly days_entitled: number;
+    readonly max_carry_over_days: number;
     readonly period_end: string;
     readonly notes: string | null;
 }

package/dist/leave/dto.js

@@ -52,6 +52,7 @@ class CreateLeaveTypeDto {
     default_days;
     is_paid;
     requires_approval;
+    requires_document;
 }
 exports.CreateLeaveTypeDto = CreateLeaveTypeDto;
 __decorate([
@@ -82,12 +83,17 @@ __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Requires approval must be true or false' }),
     __metadata("design:type", Boolean)
 ], CreateLeaveTypeDto.prototype, "requires_approval", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Requires document must be true or false' }),
+    __metadata("design:type", Boolean)
+], CreateLeaveTypeDto.prototype, "requires_document", void 0);
 class UpdateLeaveTypeDto {
     name;
     description;
     default_days;
     is_paid;
     requires_approval;
+    requires_document;
     active;
 }
 exports.UpdateLeaveTypeDto = UpdateLeaveTypeDto;
@@ -119,6 +125,10 @@ __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Requires approval must be true or false' }),
     __metadata("design:type", Boolean)
 ], UpdateLeaveTypeDto.prototype, "requires_approval", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Requires document must be true or false' }),
+    __metadata("design:type", Boolean)
+], UpdateLeaveTypeDto.prototype, "requires_document", void 0);
 __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Active must be true or false' }),
     __metadata("design:type", Boolean)
@@ -177,6 +187,7 @@ class CreateLeaveEntitlementDto {
     user_id;
     leave_type_id;
     days_entitled;
+    max_carry_over_days;
     period_start;
     period_end;
     notes;
@@ -196,6 +207,12 @@ __decorate([
     (0, class_validator_1.Max)(999.9, { message: 'Days entitled cannot exceed 999.9' }),
     __metadata("design:type", Number)
 ], CreateLeaveEntitlementDto.prototype, "days_entitled", void 0);
+__decorate([
+    (0, class_validator_1.IsNumber)({ maxDecimalPlaces: 1 }, { message: 'Max carry over days must be a number with at most one decimal' }),
+    (0, class_validator_1.Min)(0, { message: 'Max carry over days cannot be negative' }),
+    (0, class_validator_1.Max)(999.9, { message: 'Max carry over days cannot exceed 999.9' }),
+    __metadata("design:type", Number)
+], CreateLeaveEntitlementDto.prototype, "max_carry_over_days", void 0);
 __decorate([
     (0, validators_1.IsNullable)(),
     (0, validators_1.IsCalendarDate)({ message: 'Period start must be a calendar date (YYYY-MM-DD)' }),
@@ -215,6 +232,7 @@ __decorate([
 ], CreateLeaveEntitlementDto.prototype, "notes", void 0);
 class UpdateLeaveEntitlementDto {
     days_entitled;
+    max_carry_over_days;
     period_end;
     notes;
 }
@@ -225,6 +243,12 @@ __decorate([
     (0, class_validator_1.Max)(999.9, { message: 'Days entitled cannot exceed 999.9' }),
     __metadata("design:type", Number)
 ], UpdateLeaveEntitlementDto.prototype, "days_entitled", void 0);
+__decorate([
+    (0, class_validator_1.IsNumber)({ maxDecimalPlaces: 1 }, { message: 'Max carry over days must be a number with at most one decimal' }),
+    (0, class_validator_1.Min)(0, { message: 'Max carry over days cannot be negative' }),
+    (0, class_validator_1.Max)(999.9, { message: 'Max carry over days cannot exceed 999.9' }),
+    __metadata("design:type", Number)
+], UpdateLeaveEntitlementDto.prototype, "max_carry_over_days", void 0);
 __decorate([
     (0, validators_1.IsCalendarDate)({ message: 'Period end must be a calendar date (YYYY-MM-DD)' }),
     __metadata("design:type", String)

package/dist/leave/leave-entitlements.d.ts

@@ -1,7 +1,6 @@
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { LeaveEntitlementEntity, LeavePeriod } from '@managemint-solutions/entities/leave';
-import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import { type AuditActor, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { GetLeaveEntitlementsDto, UpdateLeaveEntitlementDto } from './dto';
 /** What the request path needs of the entitlement covering a date: the period and the cap. */
@@ -14,13 +13,14 @@ export type CreateLeaveEntitlementInput = LeavePeriod & {
     user_id: string;
     leave_type_id: string;
     days_entitled: number;
+    max_carry_over_days: number;
     notes?: string | null;
 };
 export declare class LeaveEntitlementsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, auth: AuditActor, audit: AuditResource);
     list(query: GetLeaveEntitlementsDto): Promise<MmsList<LeaveEntitlementEntity>>;
     getById(leaveEntitlementId: string): Promise<LeaveEntitlementEntity>;
     /**
@@ -35,6 +35,12 @@ export declare class LeaveEntitlementsResource {
      * that survives a race. `excludeId` leaves out the entitlement being edited.
      */
     overlaps(userId: string, leaveTypeId: string, start: string, end: string, excludeId?: string): Promise<boolean>;
+    /**
+     * Every entitlement of the organization whose period ends on `periodEnd`, balances included -
+     * what the leave-year rollover carries forward. Walks the table in pages so a large tenant is
+     * not cut short by the row cap.
+     */
+    endingOn(periodEnd: string): Promise<LeaveEntitlementEntity[]>;
     create(input: CreateLeaveEntitlementInput): Promise<LeaveEntitlementEntity>;
     update(leaveEntitlementId: string, input: UpdateLeaveEntitlementDto): Promise<LeaveEntitlementEntity>;
     /** Hard delete: the type simply becomes untracked for that user and period. */
@@ -43,6 +49,7 @@ export declare class LeaveEntitlementsResource {
      * Adds the computed balance to each row from one query over the requests that could count
      * against any of them - the approved and pending ones of these users and types, starting in
      * the span the periods cover. Nothing is stored: a balance is always what the requests say.
+     * Paged, since `endingOn` hands it a whole tenant at once.
      */
     private withBalances;
 }

package/dist/leave/leave-entitlements.js

@@ -15,11 +15,13 @@ const LEAVE_ENTITLEMENT_SELECT = `
         user:user_profiles!user_id (*),
         leave_type:leave_types!leave_type_id (
           mms_id,
-          name
+          name,
+          requires_document
         ),
         period_start,
         period_end,
         days_entitled,
+        max_carry_over_days,
         notes
       `;
 class LeaveEntitlementsResource {
@@ -116,6 +118,21 @@ class LeaveEntitlementsResource {
             throw (0, errors_1.mapPostgrestError)(error);
         return (count ?? 0) > 0;
     }
+    /**
+     * Every entitlement of the organization whose period ends on `periodEnd`, balances included -
+     * what the leave-year rollover carries forward. Walks the table in pages so a large tenant is
+     * not cut short by the row cap.
+     */
+    async endingOn(periodEnd) {
+        const rows = await (0, transforms_1.allRows)((from, to) => this.supabase
+            .from('leave_entitlements')
+            .select(LEAVE_ENTITLEMENT_SELECT)
+            .eq('organization_id', this.auth.organization_id)
+            .eq('period_end', periodEnd)
+            .order('mms_id')
+            .range(from, to));
+        return this.withBalances(rows);
+    }
     async create(input) {
         const row = await this.table.insert({
             user_id: input.user_id,
@@ -123,6 +140,7 @@ class LeaveEntitlementsResource {
             period_start: input.period_start,
             period_end: input.period_end,
             days_entitled: input.days_entitled,
+            max_carry_over_days: input.max_carry_over_days,
             notes: input.notes ?? null,
             organization_id: this.auth.organization_id,
             created_by: this.auth.mms_id,
@@ -133,6 +151,7 @@ class LeaveEntitlementsResource {
     async update(leaveEntitlementId, input) {
         await this.table.update(leaveEntitlementId, {
             days_entitled: input.days_entitled,
+            max_carry_over_days: input.max_carry_over_days,
             period_end: input.period_end,
             notes: input.notes,
             last_updated_by: this.auth.mms_id,
@@ -148,6 +167,7 @@ class LeaveEntitlementsResource {
      * Adds the computed balance to each row from one query over the requests that could count
      * against any of them - the approved and pending ones of these users and types, starting in
      * the span the periods cover. Nothing is stored: a balance is always what the requests say.
+     * Paged, since `endingOn` hands it a whole tenant at once.
      */
     async withBalances(rows) {
         if (rows.length === 0)
@@ -156,7 +176,7 @@ class LeaveEntitlementsResource {
         const typeIds = [...new Set(rows.map((row) => row.leave_type.mms_id))];
         const earliest = rows.map((row) => row.period_start).sort()[0];
         const latest = rows.map((row) => row.period_end).sort().reverse()[0];
-        const { data, error } = await this.supabase
+        const requests = await (0, transforms_1.allRows)((from, to) => this.supabase
             .from('leave_requests')
             .select('user_id, leave_type_id, start_date, days, status')
             .eq('organization_id', this.auth.organization_id)
@@ -164,10 +184,9 @@ class LeaveEntitlementsResource {
             .in('leave_type_id', typeIds)
             .in('status', [enum_2.LeaveRequestStatus.APPROVED, enum_2.LeaveRequestStatus.PENDING])
             .gte('start_date', earliest)
-            .lte('start_date', latest);
-        if (error)
-            throw (0, errors_1.mapPostgrestError)(error);
-        const requests = (data ?? []);
+            .lte('start_date', latest)
+            .order('mms_id')
+            .range(from, to));
         return rows.map((row) => {
             const mine = requests.filter((request) => request.user_id === row.user.mms_id &&
                 request.leave_type_id === row.leave_type.mms_id &&
@@ -182,6 +201,7 @@ class LeaveEntitlementsResource {
             return {
                 ...row,
                 days_entitled: daysEntitled,
+                max_carry_over_days: Number(row.max_carry_over_days),
                 days_used: daysUsed,
                 days_pending: daysPending,
                 days_remaining: daysEntitled - daysUsed - daysPending,

package/dist/leave/leave-requests.d.ts

@@ -1,8 +1,7 @@
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { LeavePeriod, LeaveRequestEntity } from '@managemint-solutions/entities/leave';
 import { LeaveRequestStatus, LeaveReviewDecision } from '@managemint-solutions/entities/leave/enum';
-import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import { type AuditActor, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { GetLeaveRequestsDto } from './dto';
 /** A request as the api inserts it: the caller's own, with the days already counted. */
@@ -40,7 +39,7 @@ export declare class LeaveRequestsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, auth: AuditActor, audit: AuditResource);
     list(query: GetLeaveRequestsDto, options?: ListOptions): Promise<MmsList<LeaveRequestEntity>>;
     getById(leaveRequestId: string): Promise<LeaveRequestEntity>;
     /**

package/dist/leave/leave-requests.js

@@ -15,7 +15,8 @@ const LEAVE_REQUEST_SELECT = `
         user:user_profiles!user_id (*),
         leave_type:leave_types!leave_type_id (
           mms_id,
-          name
+          name,
+          requires_document
         ),
         start_date,
         end_date,

package/dist/leave/leave-types.d.ts

@@ -1,13 +1,12 @@
 import type { LeaveTypeEntity } from '@managemint-solutions/entities/leave';
-import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import { type AuditActor, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { CreateLeaveTypeDto, GetLeaveTypesDto, UpdateLeaveTypeDto } from './dto';
 export declare class LeaveTypesResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, auth: AuditActor, audit: AuditResource);
     /** Every type by name; `active` narrows to one side of the flag. Small enough not to page. */
     list(query: GetLeaveTypesDto): Promise<LeaveTypeEntity[]>;
     getById(leaveTypeId: string): Promise<LeaveTypeEntity>;

package/dist/leave/leave-types.js

@@ -18,6 +18,7 @@ const LEAVE_TYPE_SELECT = `
         default_days,
         is_paid,
         requires_approval,
+        requires_document,
         active
       `;
 class LeaveTypesResource {
@@ -65,6 +66,7 @@ class LeaveTypesResource {
             default_days: input.default_days,
             is_paid: input.is_paid,
             requires_approval: input.requires_approval,
+            requires_document: input.requires_document,
             organization_id: this.auth.organization_id,
             created_by: this.auth.mms_id,
             created_at: new Date().toISOString(),
@@ -78,6 +80,7 @@ class LeaveTypesResource {
             default_days: input.default_days,
             is_paid: input.is_paid,
             requires_approval: input.requires_approval,
+            requires_document: input.requires_document,
             active: input.active,
             last_updated_by: this.auth.mms_id,
             updated_at: new Date().toISOString(),

package/dist/leave/working-days.d.ts

@@ -4,6 +4,8 @@ import type { LeavePeriod } from '@managemint-solutions/entities/leave';
  * customer is South African; this is the one place to change when a column arrives.
  */
 export declare const LEAVE_TIME_ZONE = "Africa/Johannesburg";
+/** A `Date` at UTC midnight of a `YYYY-MM-DD` string (a longer ISO string is cut to its date). */
+export declare const parseIsoDate: (value: string) => Date;
 /** The `YYYY-MM-DD` of a `Date`'s UTC calendar day. */
 export declare const toIsoDate: (date: Date) => string;
 /** Today's calendar date in `LEAVE_TIME_ZONE`. */
@@ -18,6 +20,8 @@ export declare const isWorkingDay: (isoDate: string, holidays: ReadonlySet<strin
  * on a weekend or holiday - the caller rejects a zero either way.
  */
 export declare const countWorkingDays: (start: string, end: string, holidays: ReadonlySet<string>, isHalfDay?: boolean) => number;
+/** `isoDate` moved by `days` calendar days, either way; `shiftDays('2026-03-01', -1)` is Feb 28. */
+export declare const shiftDays: (isoDate: string, days: number) => string;
 /** The day before the same date next year - the end of a period that starts on `isoDate`. */
 export declare const addOneYearMinusDay: (isoDate: string) => string;
 /**

package/dist/leave/working-days.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWithinPeriod = exports.leavePeriodFor = exports.addOneYearMinusDay = exports.countWorkingDays = exports.isWorkingDay = exports.eachDate = exports.todayInJohannesburg = exports.toIsoDate = exports.LEAVE_TIME_ZONE = void 0;
+exports.isWithinPeriod = exports.leavePeriodFor = exports.addOneYearMinusDay = exports.shiftDays = exports.countWorkingDays = exports.isWorkingDay = exports.eachDate = exports.todayInJohannesburg = exports.toIsoDate = exports.parseIsoDate = exports.LEAVE_TIME_ZONE = void 0;
 // The calendar arithmetic behind leave: which days of a request count, and which leave year a
 // date belongs to. Pure functions over `YYYY-MM-DD` strings - the columns are `date`, so a
 // request never carries a time and nothing here depends on the caller's clock zone.
@@ -17,6 +17,7 @@ const parseIsoDate = (value) => {
     const [year, month, day] = value.slice(0, 10).split('-').map(Number);
     return new Date(Date.UTC(year, month - 1, day));
 };
+exports.parseIsoDate = parseIsoDate;
 /** The `YYYY-MM-DD` of a `Date`'s UTC calendar day. */
 const toIsoDate = (date) => `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
 exports.toIsoDate = toIsoDate;
@@ -34,14 +35,14 @@ exports.todayInJohannesburg = todayInJohannesburg;
 const eachDate = (start, end) => {
     const dates = [];
     const last = end.slice(0, 10);
-    for (const cursor = parseIsoDate(start); (0, exports.toIsoDate)(cursor) <= last; cursor.setUTCDate(cursor.getUTCDate() + 1)) {
+    for (const cursor = (0, exports.parseIsoDate)(start); (0, exports.toIsoDate)(cursor) <= last; cursor.setUTCDate(cursor.getUTCDate() + 1)) {
         dates.push((0, exports.toIsoDate)(cursor));
     }
     return dates;
 };
 exports.eachDate = eachDate;
 /** Monday to Friday and not one of the organization's holidays. */
-const isWorkingDay = (isoDate, holidays) => !WEEKEND_DAYS.has(parseIsoDate(isoDate).getUTCDay()) && !holidays.has(isoDate.slice(0, 10));
+const isWorkingDay = (isoDate, holidays) => !WEEKEND_DAYS.has((0, exports.parseIsoDate)(isoDate).getUTCDay()) && !holidays.has(isoDate.slice(0, 10));
 exports.isWorkingDay = isWorkingDay;
 /**
  * The days a request is worth: the working days from `start` to `end` inclusive, halved for a
@@ -53,9 +54,16 @@ const countWorkingDays = (start, end, holidays, isHalfDay = false) => {
     return isHalfDay ? working * 0.5 : working;
 };
 exports.countWorkingDays = countWorkingDays;
+/** `isoDate` moved by `days` calendar days, either way; `shiftDays('2026-03-01', -1)` is Feb 28. */
+const shiftDays = (isoDate, days) => {
+    const date = (0, exports.parseIsoDate)(isoDate);
+    date.setUTCDate(date.getUTCDate() + days);
+    return (0, exports.toIsoDate)(date);
+};
+exports.shiftDays = shiftDays;
 /** The day before the same date next year - the end of a period that starts on `isoDate`. */
 const addOneYearMinusDay = (isoDate) => {
-    const date = parseIsoDate(isoDate);
+    const date = (0, exports.parseIsoDate)(isoDate);
     date.setUTCFullYear(date.getUTCFullYear() + 1);
     date.setUTCDate(date.getUTCDate() - 1);
     return (0, exports.toIsoDate)(date);
@@ -67,7 +75,7 @@ exports.addOneYearMinusDay = addOneYearMinusDay;
  * 2026-02-10 in the year that began 2025-03-01.
  */
 const leavePeriodFor = (date, startMonth) => {
-    const parsed = parseIsoDate(date);
+    const parsed = (0, exports.parseIsoDate)(date);
     const year = parsed.getUTCMonth() + 1 >= startMonth ? parsed.getUTCFullYear() : parsed.getUTCFullYear() - 1;
     const period_start = (0, exports.toIsoDate)(new Date(Date.UTC(year, startMonth - 1, 1)));
     return { period_start, period_end: (0, exports.addOneYearMinusDay)(period_start) };

package/dist/permissions/dto.d.ts

@@ -12,6 +12,10 @@ export declare class UpdatePermissionsDto implements UpdatePermissionsDtoType {
     readonly read_tasks: boolean;
     readonly update_tasks: boolean;
     readonly delete_tasks: boolean;
+    readonly create_timesheets: boolean;
+    readonly read_timesheets: boolean;
+    readonly update_timesheets: boolean;
+    readonly delete_timesheets: boolean;
     readonly create_leave: boolean;
     readonly read_leave: boolean;
     readonly update_leave: boolean;

package/dist/permissions/dto.js

@@ -34,6 +34,10 @@ class UpdatePermissionsDto {
     read_tasks;
     update_tasks;
     delete_tasks;
+    create_timesheets;
+    read_timesheets;
+    update_timesheets;
+    delete_timesheets;
     // @IsBoolean({ message: 'Create Documents must be a boolean' })
     // readonly create_documents!: boolean;
     // @IsBoolean({ message: 'Read Documents must be a boolean' })
@@ -152,6 +156,22 @@ __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Delete Tasks must be a boolean' }),
     __metadata("design:type", Boolean)
 ], UpdatePermissionsDto.prototype, "delete_tasks", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Create Timesheets must be a boolean' }),
+    __metadata("design:type", Boolean)
+], UpdatePermissionsDto.prototype, "create_timesheets", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Read Timesheets must be a boolean' }),
+    __metadata("design:type", Boolean)
+], UpdatePermissionsDto.prototype, "read_timesheets", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Update Timesheets must be a boolean' }),
+    __metadata("design:type", Boolean)
+], UpdatePermissionsDto.prototype, "update_timesheets", void 0);
+__decorate([
+    (0, class_validator_1.IsBoolean)({ message: 'Delete Timesheets must be a boolean' }),
+    __metadata("design:type", Boolean)
+], UpdatePermissionsDto.prototype, "delete_timesheets", void 0);
 __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Create Leave must be a boolean' }),
     __metadata("design:type", Boolean)