@managemint-solutions/sdk 0.39.0 → 0.40.0

package/dist/service-client/index.d.ts

@@ -4,6 +4,7 @@ import { BillingResource } from '../billing';
 import { InvoicesResource } from '../billing/invoices';
 import { ConfigsResource } from '../configs';
 import { FeatureRequestsResource } from '../feature-requests';
+import { LeaveEntitlementsResource, LeaveRequestsResource, LeaveTypesResource } from '../leave';
 import { NotificationsOutboxResource } from '../notifications';
 import { OrganizationInvitesResource } from '../organization-invites';
 import { OrganizationPaymentMethodsResource, type PaymentMethodLookupColumn } from '../organization-payment-methods';
@@ -30,6 +31,9 @@ export declare class SupabaseOrganizationScope {
     readonly billing: BillingResource;
     readonly invoices: InvoicesResource;
     readonly invites: OrganizationInvitesResource;
+    readonly leaveTypes: LeaveTypesResource;
+    readonly leaveEntitlements: LeaveEntitlementsResource;
+    readonly leaveRequests: LeaveRequestsResource;
     readonly organizations: OrganizationsResource;
     readonly paymentMethod: OrganizationPaymentMethodsResource;
     readonly permissions: PermissionsResource;
@@ -85,6 +89,15 @@ export declare class SupabaseServiceClient {
      * Unscoped by nature: the cron has no tenant until it picks one.
      */
     organizationsWithPaystackCustomer(): Promise<string[]>;
+    /**
+     * Every organization whose leave year starts on the first of `month` (1-12) - the tenants the
+     * nightly rollover visits on that day. Unscoped like the reconcile: the cron picks its tenants
+     * from here. `modules` comes along so the caller can skip an organization without HR.
+     */
+    organizationsWithLeaveYearStartingIn(month: number): Promise<{
+        mms_id: string;
+        modules: string[];
+    }[]>;
     /**
      * A ledger row by id alone. Also unscoped by necessity: a `charge.success` carries the
      * transaction id in its metadata, and the row is what says which tenant it belongs to.

package/dist/service-client/index.js

@@ -8,6 +8,7 @@ const billing_1 = require("../billing");
 const invoices_1 = require("../billing/invoices");
 const configs_1 = require("../configs");
 const feature_requests_1 = require("../feature-requests");
+const leave_1 = require("../leave");
 const notifications_1 = require("../notifications");
 const errors_1 = require("../errors");
 const organization_invites_1 = require("../organization-invites");
@@ -28,6 +29,9 @@ class SupabaseOrganizationScope {
     billing;
     invoices;
     invites;
+    leaveTypes;
+    leaveEntitlements;
+    leaveRequests;
     organizations;
     paymentMethod;
     permissions;
@@ -39,6 +43,10 @@ class SupabaseOrganizationScope {
         this.billing = new billing_1.BillingResource(supabase, actor, this.audit);
         this.invoices = new invoices_1.InvoicesResource(supabase, actor, this.audit);
         this.invites = new organization_invites_1.OrganizationInvitesResource(supabase, actor);
+        // The leave-year rollover writes next period's entitlements as the system (`mms_id: null`).
+        this.leaveTypes = new leave_1.LeaveTypesResource(supabase, actor, this.audit);
+        this.leaveEntitlements = new leave_1.LeaveEntitlementsResource(supabase, actor, this.audit);
+        this.leaveRequests = new leave_1.LeaveRequestsResource(supabase, actor, this.audit);
         this.organizations = new organizations_1.OrganizationsResource(supabase, actor, this.audit);
         this.paymentMethod = new organization_payment_methods_1.OrganizationPaymentMethodsResource(supabase, actor, this.audit);
         this.permissions = new permissions_1.PermissionsResource(supabase, actor, this.audit);
@@ -146,6 +154,20 @@ class SupabaseServiceClient {
             throw (0, errors_1.mapPostgrestError)(error);
         return (data ?? []).map((row) => row.organization_id);
     }
+    /**
+     * Every organization whose leave year starts on the first of `month` (1-12) - the tenants the
+     * nightly rollover visits on that day. Unscoped like the reconcile: the cron picks its tenants
+     * from here. `modules` comes along so the caller can skip an organization without HR.
+     */
+    async organizationsWithLeaveYearStartingIn(month) {
+        const { data, error } = await this.supabase
+            .from('organizations')
+            .select('mms_id, modules')
+            .eq('leave_calendar_start_month', month);
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (data ?? []);
+    }
     /**
      * A ledger row by id alone. Also unscoped by necessity: a `charge.success` carries the
      * transaction id in its metadata, and the row is what says which tenant it belongs to.

package/dist/timesheets/dto.d.ts

@@ -0,0 +1,42 @@
+import type { CreateTimesheetEntryDto as CreateTimesheetEntryDtoType, GetTimesheetReportDto as GetTimesheetReportDtoType, GetTimesheetsDto as GetTimesheetsDtoType, ReviewTimesheetDto as ReviewTimesheetDtoType, TimesheetEntryIdDto as TimesheetEntryIdDtoType, TimesheetIdDto as TimesheetIdDtoType, UpdateTimesheetEntryDto as UpdateTimesheetEntryDtoType } from '@managemint-solutions/entities/timesheets/dto';
+import { TimesheetReviewDecision, TimesheetStatus } from '@managemint-solutions/entities/timesheets/enum';
+export declare class TimesheetIdDto implements TimesheetIdDtoType {
+    readonly timesheetId: string;
+}
+export declare class GetTimesheetsDto implements GetTimesheetsDtoType {
+    readonly page: number;
+    readonly page_size: number;
+    readonly user_id?: string | null;
+    readonly status?: TimesheetStatus | null;
+    readonly week_start?: string | null;
+}
+export declare class ReviewTimesheetDto implements ReviewTimesheetDtoType {
+    readonly status: TimesheetReviewDecision;
+    readonly review_note: string | null;
+}
+export declare class GetTimesheetReportDto implements GetTimesheetReportDtoType {
+    readonly date_from: string;
+    readonly date_to: string;
+    readonly user_id?: string | null;
+}
+export declare class TimesheetEntryIdDto implements TimesheetEntryIdDtoType {
+    readonly timesheetEntryId: string;
+}
+export declare class CreateTimesheetEntryDto implements CreateTimesheetEntryDtoType {
+    readonly date: string;
+    readonly start_time: string;
+    readonly end_time: string;
+    readonly client_id: string | null;
+    readonly project_id: string | null;
+    readonly task_id: string | null;
+    readonly description: string | null;
+}
+export declare class UpdateTimesheetEntryDto implements UpdateTimesheetEntryDtoType {
+    readonly date: string;
+    readonly start_time: string;
+    readonly end_time: string;
+    readonly client_id: string | null;
+    readonly project_id: string | null;
+    readonly task_id: string | null;
+    readonly description: string | null;
+}

package/dist/timesheets/dto.js

@@ -0,0 +1,211 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateTimesheetEntryDto = exports.CreateTimesheetEntryDto = exports.TimesheetEntryIdDto = exports.GetTimesheetReportDto = exports.ReviewTimesheetDto = exports.GetTimesheetsDto = exports.TimesheetIdDto = void 0;
+const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
+const enum_1 = require("@managemint-solutions/entities/timesheets/enum");
+const validators_1 = require("../validators");
+// class-validator versions of the shared DTO types from @managemint-solutions/entities.
+// Each class `implements` its entities type so the wire contract cannot drift.
+//
+// Body fields are required: a nullable one carries `@IsNullable()` without `@IsOptional()`,
+// so `null` passes and a missing key fails. Only the query-string filters are optional.
+/** A description is stored trimmed; one that is blank once trimmed means "none". Goes above `EmptyToNull()`, which runs after it. */
+const Trim = () => (0, class_transformer_1.Transform)(({ value }) => (typeof value === 'string' ? value.trim() : value), { toClassOnly: true });
+// `user_id` is v4 (the GoTrue auth uid, see users/dto.ts); every other id is v7.
+// ---- Timesheets (weeks) ----
+class TimesheetIdDto {
+    timesheetId;
+}
+exports.TimesheetIdDto = TimesheetIdDto;
+__decorate([
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid timesheet ID format' }),
+    __metadata("design:type", String)
+], TimesheetIdDto.prototype, "timesheetId", void 0);
+class GetTimesheetsDto {
+    page = 1;
+    page_size = 10;
+    user_id;
+    status;
+    week_start;
+}
+exports.GetTimesheetsDto = GetTimesheetsDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Transform)(({ value }) => value ? Number(value) : 1, { toClassOnly: true }),
+    (0, class_validator_1.IsNumber)({}, { message: 'Page must be a number' }),
+    (0, class_validator_1.Min)(1, { message: 'Page must be at least 1' }),
+    __metadata("design:type", Number)
+], GetTimesheetsDto.prototype, "page", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Transform)(({ value }) => value ? Number(value) : 10, { toClassOnly: true }),
+    (0, class_validator_1.IsNumber)({}, { message: 'Page size must be a number' }),
+    (0, class_validator_1.Min)(1, { message: 'Page size must be at least 1' }),
+    (0, class_validator_1.Max)(100, { message: 'Page size cannot exceed 100' }),
+    __metadata("design:type", Number)
+], GetTimesheetsDto.prototype, "page_size", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('4', { message: 'Invalid user ID format' }),
+    __metadata("design:type", Object)
+], GetTimesheetsDto.prototype, "user_id", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsEnum)(enum_1.TimesheetStatus, { message: 'Invalid status' }),
+    __metadata("design:type", Object)
+], GetTimesheetsDto.prototype, "status", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, validators_1.IsCalendarDate)({ message: 'Week start must be a calendar date (YYYY-MM-DD)' }),
+    __metadata("design:type", Object)
+], GetTimesheetsDto.prototype, "week_start", void 0);
+class ReviewTimesheetDto {
+    status;
+    review_note;
+}
+exports.ReviewTimesheetDto = ReviewTimesheetDto;
+__decorate([
+    (0, class_validator_1.IsEnum)(enum_1.TimesheetReviewDecision, { message: 'Status must be approved or rejected' }),
+    __metadata("design:type", String)
+], ReviewTimesheetDto.prototype, "status", void 0);
+__decorate([
+    (0, validators_1.EmptyToNull)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsString)({ message: 'Invalid review note' }),
+    (0, class_validator_1.MaxLength)(2000, { message: 'Review note cannot exceed 2000 characters' }),
+    __metadata("design:type", Object)
+], ReviewTimesheetDto.prototype, "review_note", void 0);
+class GetTimesheetReportDto {
+    date_from;
+    date_to;
+    user_id;
+}
+exports.GetTimesheetReportDto = GetTimesheetReportDto;
+__decorate([
+    (0, validators_1.IsCalendarDate)({ message: 'Date from must be a calendar date (YYYY-MM-DD)' }),
+    __metadata("design:type", String)
+], GetTimesheetReportDto.prototype, "date_from", void 0);
+__decorate([
+    (0, validators_1.IsCalendarDate)({ message: 'Date to must be a calendar date (YYYY-MM-DD)' }),
+    __metadata("design:type", String)
+], GetTimesheetReportDto.prototype, "date_to", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('4', { message: 'Invalid user ID format' }),
+    __metadata("design:type", Object)
+], GetTimesheetReportDto.prototype, "user_id", void 0);
+// ---- Timesheet entries ----
+class TimesheetEntryIdDto {
+    timesheetEntryId;
+}
+exports.TimesheetEntryIdDto = TimesheetEntryIdDto;
+__decorate([
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid timesheet entry ID format' }),
+    __metadata("design:type", String)
+], TimesheetEntryIdDto.prototype, "timesheetEntryId", void 0);
+// No `user_id`: an entry is always the caller's own, and leaving the field out is what keeps a
+// forged one from validating. The week is found or created from `date` by the api.
+class CreateTimesheetEntryDto {
+    date;
+    start_time;
+    end_time;
+    client_id;
+    project_id;
+    task_id;
+    description;
+}
+exports.CreateTimesheetEntryDto = CreateTimesheetEntryDto;
+__decorate([
+    (0, validators_1.IsCalendarDate)({ message: 'Date must be a calendar date (YYYY-MM-DD)' }),
+    __metadata("design:type", String)
+], CreateTimesheetEntryDto.prototype, "date", void 0);
+__decorate([
+    (0, validators_1.IsClockTime)({ message: 'Start time must be a clock time (HH:MM)' }),
+    __metadata("design:type", String)
+], CreateTimesheetEntryDto.prototype, "start_time", void 0);
+__decorate([
+    (0, validators_1.IsClockTime)({ allowEndOfDay: true, message: 'End time must be a clock time (HH:MM, or 24:00 for midnight)' }),
+    __metadata("design:type", String)
+], CreateTimesheetEntryDto.prototype, "end_time", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid client ID format' }),
+    __metadata("design:type", Object)
+], CreateTimesheetEntryDto.prototype, "client_id", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid project ID format' }),
+    __metadata("design:type", Object)
+], CreateTimesheetEntryDto.prototype, "project_id", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid task ID format' }),
+    __metadata("design:type", Object)
+], CreateTimesheetEntryDto.prototype, "task_id", void 0);
+__decorate([
+    Trim(),
+    (0, validators_1.EmptyToNull)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsString)({ message: 'Invalid description' }),
+    (0, class_validator_1.MaxLength)(2000, { message: 'Description cannot exceed 2000 characters' }),
+    __metadata("design:type", Object)
+], CreateTimesheetEntryDto.prototype, "description", void 0);
+class UpdateTimesheetEntryDto {
+    date;
+    start_time;
+    end_time;
+    client_id;
+    project_id;
+    task_id;
+    description;
+}
+exports.UpdateTimesheetEntryDto = UpdateTimesheetEntryDto;
+__decorate([
+    (0, validators_1.IsCalendarDate)({ message: 'Date must be a calendar date (YYYY-MM-DD)' }),
+    __metadata("design:type", String)
+], UpdateTimesheetEntryDto.prototype, "date", void 0);
+__decorate([
+    (0, validators_1.IsClockTime)({ message: 'Start time must be a clock time (HH:MM)' }),
+    __metadata("design:type", String)
+], UpdateTimesheetEntryDto.prototype, "start_time", void 0);
+__decorate([
+    (0, validators_1.IsClockTime)({ allowEndOfDay: true, message: 'End time must be a clock time (HH:MM, or 24:00 for midnight)' }),
+    __metadata("design:type", String)
+], UpdateTimesheetEntryDto.prototype, "end_time", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid client ID format' }),
+    __metadata("design:type", Object)
+], UpdateTimesheetEntryDto.prototype, "client_id", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid project ID format' }),
+    __metadata("design:type", Object)
+], UpdateTimesheetEntryDto.prototype, "project_id", void 0);
+__decorate([
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid task ID format' }),
+    __metadata("design:type", Object)
+], UpdateTimesheetEntryDto.prototype, "task_id", void 0);
+__decorate([
+    Trim(),
+    (0, validators_1.EmptyToNull)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsString)({ message: 'Invalid description' }),
+    (0, class_validator_1.MaxLength)(2000, { message: 'Description cannot exceed 2000 characters' }),
+    __metadata("design:type", Object)
+], UpdateTimesheetEntryDto.prototype, "description", void 0);

package/dist/timesheets/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dto';
+export * from './weeks';
+export { TimesheetsResource, type CreateTimesheetRow, type ReviewTimesheetRow, type TimesheetCover, } from './timesheets';
+export { TimesheetEntriesResource, type CreateTimesheetEntryRow, type TimesheetReportRow, type UpdateTimesheetEntryRow, } from './timesheet-entries';

package/dist/timesheets/index.js

@@ -0,0 +1,27 @@
+"use strict";
+// Timesheets, the second slice of the HR module: the entries an employee logs, the
+// Monday-to-Sunday weeks they submit, the DTOs the api validates with, and the week arithmetic
+// it derives the week from. The resources hang off `SupabaseClient` as `timesheets` and
+// `timesheetEntries`; the report itself is aggregated in the api from `forReport` rows.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimesheetEntriesResource = exports.TimesheetsResource = void 0;
+__exportStar(require("./dto"), exports);
+__exportStar(require("./weeks"), exports);
+var timesheets_1 = require("./timesheets");
+Object.defineProperty(exports, "TimesheetsResource", { enumerable: true, get: function () { return timesheets_1.TimesheetsResource; } });
+var timesheet_entries_1 = require("./timesheet-entries");
+Object.defineProperty(exports, "TimesheetEntriesResource", { enumerable: true, get: function () { return timesheet_entries_1.TimesheetEntriesResource; } });

package/dist/timesheets/timesheet-entries.d.ts

@@ -0,0 +1,54 @@
+import type { TimesheetEntryEntity } from '@managemint-solutions/entities/timesheets';
+import type { AuthContext } from '../auth';
+import { type AuditResource } from '../audit';
+import type { TypedSupabaseClient } from '../client';
+export declare const TIMESHEET_ENTRY_SELECT: "\n        mms_id,\n        created_at,\n        created_by:user_profiles!created_by (*),\n        updated_at,\n        last_updated_by:user_profiles!last_updated_by (*),\n        timesheet_id,\n        user:user_profiles!user_id (*),\n        date,\n        start_time,\n        end_time,\n        duration_minutes,\n        client:client_profiles!client_id (*),\n        project:project_profiles!project_id (*),\n        task:task_profiles!task_id (*),\n        description\n      ";
+/** An entry as the api inserts it: the caller's own, in the week the api found or created for `date`. */
+export type CreateTimesheetEntryRow = {
+    timesheet_id: string;
+    user_id: string;
+    date: string;
+    start_time: string;
+    end_time: string;
+    client_id: string | null;
+    project_id: string | null;
+    task_id: string | null;
+    description: string | null;
+};
+/** The editable fields; `timesheet_id` moves with the date when the api re-resolves the week. */
+export type UpdateTimesheetEntryRow = Omit<CreateTimesheetEntryRow, 'user_id'>;
+/** One entry as the report aggregates it: what was logged and who it is attributed to, without the audit stamps. */
+export type TimesheetReportRow = Pick<TimesheetEntryEntity, 'timesheet_id' | 'user' | 'date' | 'start_time' | 'end_time' | 'duration_minutes' | 'client' | 'project' | 'task' | 'description'>;
+/**
+ * Postgres returns a `time` as `HH:MM:SS`; the contract is `HH:MM`, the shape the DTOs accept,
+ * so a row read back can be sent straight back in. The one place a time is shaped on read.
+ */
+export declare const withClockTimes: <T extends {
+    start_time: string;
+    end_time: string;
+    duration_minutes: number | string;
+}>(row: T) => T;
+export declare class TimesheetEntriesResource {
+    private readonly supabase;
+    private readonly auth;
+    private readonly table;
+    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    getById(timesheetEntryId: string): Promise<TimesheetEntryEntity>;
+    /**
+     * Whether `userId` already has an entry on `date` sharing a minute with `start`..`end` (two
+     * entries may touch: one ending 12:00 and one starting 12:00 do not overlap). The readable
+     * half of the rule; the table's exclusion constraint is the half that survives a race.
+     * `excludeId` leaves out the entry being edited.
+     */
+    overlaps(userId: string, date: string, start: string, end: string, excludeId?: string): Promise<boolean>;
+    create(input: CreateTimesheetEntryRow): Promise<TimesheetEntryEntity>;
+    update(timesheetEntryId: string, input: UpdateTimesheetEntryRow): Promise<TimesheetEntryEntity>;
+    /** Hard delete; the week's totals are counted on read, so nothing else moves. */
+    remove(timesheetEntryId: string): Promise<void>;
+    /**
+     * Every entry of `userIds` dated `dateFrom`..`dateTo`, flat, for the api to aggregate into the
+     * report - it keeps the ones whose `timesheet_id` is in `timesheets.approvedIds`. Paged, since
+     * a year of a team's entries outgrows one response.
+     */
+    forReport(userIds: string[], dateFrom: string, dateTo: string): Promise<TimesheetReportRow[]>;
+}

package/dist/timesheets/timesheet-entries.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimesheetEntriesResource = exports.withClockTimes = exports.TIMESHEET_ENTRY_SELECT = void 0;
+const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
+const audit_1 = require("../audit");
+const errors_1 = require("../errors");
+const transforms_1 = require("../transforms");
+// The public contract is the shared TimesheetEntryEntity from @managemint-solutions/entities;
+// the casts at the returns declare the shape the select string produces (the columns are
+// defined in the api's supabase/migrations). The attribution embeds go through the same
+// `*_profiles` views the tasks resource uses - `(mms_id, name)`, the identity shapes.
+exports.TIMESHEET_ENTRY_SELECT = `
+        mms_id,
+        created_at,
+        created_by:user_profiles!created_by (*),
+        updated_at,
+        last_updated_by:user_profiles!last_updated_by (*),
+        timesheet_id,
+        user:user_profiles!user_id (*),
+        date,
+        start_time,
+        end_time,
+        duration_minutes,
+        client:client_profiles!client_id (*),
+        project:project_profiles!project_id (*),
+        task:task_profiles!task_id (*),
+        description
+      `;
+const REPORT_SELECT = `
+        timesheet_id,
+        user:user_profiles!user_id (*),
+        date,
+        start_time,
+        end_time,
+        duration_minutes,
+        client:client_profiles!client_id (*),
+        project:project_profiles!project_id (*),
+        task:task_profiles!task_id (*),
+        description
+      `;
+/**
+ * Postgres returns a `time` as `HH:MM:SS`; the contract is `HH:MM`, the shape the DTOs accept,
+ * so a row read back can be sent straight back in. The one place a time is shaped on read.
+ */
+const withClockTimes = (row) => ({
+    ...row,
+    start_time: row.start_time.slice(0, 5),
+    end_time: row.end_time.slice(0, 5),
+    duration_minutes: Number(row.duration_minutes),
+});
+exports.withClockTimes = withClockTimes;
+class TimesheetEntriesResource {
+    supabase;
+    auth;
+    table;
+    constructor(supabase, auth, audit) {
+        this.supabase = supabase;
+        this.auth = auth;
+        this.table = (0, audit_1.auditedTable)(supabase, auth, audit, {
+            table: 'timesheet_entries',
+            entityType: enum_1.AuditTrailEntityType.TIMESHEET_ENTRIES,
+        });
+    }
+    async getById(timesheetEntryId) {
+        const { data, error } = await this.supabase
+            .from('timesheet_entries')
+            .select(exports.TIMESHEET_ENTRY_SELECT)
+            .eq('mms_id', timesheetEntryId)
+            .eq('organization_id', this.auth.organization_id)
+            .single();
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (0, exports.withClockTimes)(data);
+    }
+    /**
+     * Whether `userId` already has an entry on `date` sharing a minute with `start`..`end` (two
+     * entries may touch: one ending 12:00 and one starting 12:00 do not overlap). The readable
+     * half of the rule; the table's exclusion constraint is the half that survives a race.
+     * `excludeId` leaves out the entry being edited.
+     */
+    async overlaps(userId, date, start, end, excludeId) {
+        let overlapQuery = this.supabase
+            .from('timesheet_entries')
+            .select('mms_id', { count: 'exact', head: true })
+            .eq('organization_id', this.auth.organization_id)
+            .eq('user_id', userId)
+            .eq('date', date)
+            .lt('start_time', end)
+            .gt('end_time', start);
+        if (excludeId) {
+            overlapQuery = overlapQuery.neq('mms_id', excludeId);
+        }
+        const { count, error } = await overlapQuery;
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (count ?? 0) > 0;
+    }
+    async create(input) {
+        const row = await this.table.insert({
+            ...input,
+            organization_id: this.auth.organization_id,
+            created_by: this.auth.mms_id,
+            created_at: new Date().toISOString(),
+        });
+        return this.getById(row.mms_id);
+    }
+    async update(timesheetEntryId, input) {
+        await this.table.update(timesheetEntryId, {
+            ...input,
+            last_updated_by: this.auth.mms_id,
+            updated_at: new Date().toISOString(),
+        });
+        return this.getById(timesheetEntryId);
+    }
+    /** Hard delete; the week's totals are counted on read, so nothing else moves. */
+    async remove(timesheetEntryId) {
+        await this.table.remove(timesheetEntryId);
+    }
+    /**
+     * Every entry of `userIds` dated `dateFrom`..`dateTo`, flat, for the api to aggregate into the
+     * report - it keeps the ones whose `timesheet_id` is in `timesheets.approvedIds`. Paged, since
+     * a year of a team's entries outgrows one response.
+     */
+    async forReport(userIds, dateFrom, dateTo) {
+        if (userIds.length === 0)
+            return [];
+        const rows = await (0, transforms_1.allRows)((from, to) => this.supabase
+            .from('timesheet_entries')
+            .select(REPORT_SELECT)
+            .eq('organization_id', this.auth.organization_id)
+            .in('user_id', userIds)
+            .gte('date', dateFrom)
+            .lte('date', dateTo)
+            .order('date')
+            .order('start_time')
+            .order('mms_id')
+            .range(from, to));
+        return rows.map(exports.withClockTimes);
+    }
+}
+exports.TimesheetEntriesResource = TimesheetEntriesResource;

package/dist/timesheets/timesheets.d.ts

@@ -0,0 +1,67 @@
+import type { MmsList } from '@managemint-solutions/entities/common';
+import type { TimesheetEntity, TimesheetSummary } from '@managemint-solutions/entities/timesheets';
+import { TimesheetReviewDecision, TimesheetStatus } from '@managemint-solutions/entities/timesheets/enum';
+import type { AuthContext } from '../auth';
+import { type AuditResource } from '../audit';
+import type { TypedSupabaseClient } from '../client';
+import type { GetTimesheetsDto } from './dto';
+/** What the entry path needs of the week an entry falls in: its id and whether it is still open. */
+export type TimesheetCover = {
+    mms_id: string;
+    status: TimesheetStatus;
+    week_start: string;
+};
+/** A week as the api creates it - as a draft, for the first entry dated inside it. */
+export type CreateTimesheetRow = {
+    user_id: string;
+    week_start: string;
+};
+export type ReviewTimesheetRow = {
+    status: TimesheetReviewDecision;
+    reviewed_by: string;
+    review_note: string | null;
+};
+/** The list's visibility: `userIds` is what the api resolved for the caller. */
+type ListOptions = {
+    userIds?: string[];
+};
+export declare class TimesheetsResource {
+    private readonly supabase;
+    private readonly auth;
+    private readonly table;
+    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    list(query: GetTimesheetsDto, options?: ListOptions): Promise<MmsList<TimesheetSummary>>;
+    /** The week with its entries, by date then start time. */
+    getById(timesheetId: string): Promise<TimesheetEntity>;
+    /**
+     * The week of `userId` starting on `weekStart`, or null when no entry has opened it yet. One
+     * row per user and Monday (the table's unique key), so there is at most one.
+     */
+    findFor(userId: string, weekStart: string): Promise<TimesheetCover | null>;
+    /** Opens a week as a draft. A second opener of the same week hits the unique key - the SDK's 409. */
+    create(input: CreateTimesheetRow): Promise<TimesheetSummary>;
+    /**
+     * Sends a draft or rejected week for review, clearing the previous decision. Resolves to null
+     * when the week was no longer in either state - submitted twice from two tabs, say.
+     */
+    submit(timesheetId: string): Promise<TimesheetSummary | null>;
+    /**
+     * Approves or rejects a submitted week. Resolves to null when the week was no longer
+     * submitted - another reviewer got there first - so the caller can say so instead of
+     * overwriting their decision.
+     */
+    review(timesheetId: string, input: ReviewTimesheetRow): Promise<TimesheetSummary | null>;
+    /**
+     * The ids of `userIds`' approved weeks that could hold an entry dated `dateFrom`..`dateTo` -
+     * the weeks starting from the Monday of `dateFrom` up to `dateTo`. The report keeps only the
+     * entries of these weeks.
+     */
+    approvedIds(userIds: string[], dateFrom: string, dateTo: string): Promise<Set<string>>;
+    private summaryById;
+    /**
+     * Adds `week_end` and the totals to each row from one query over the entries of these weeks.
+     * Nothing is stored: a total is always what the entries add up to.
+     */
+    private withTotals;
+}
+export {};