@markwharton/liquidplanner 3.2.1 → 3.2.3

package/README.md

@@ -43,11 +43,11 @@ await client.createTimesheetEntry({
 });
 
 // Query existing entries for a date
-const tsResult = await client.getTimesheetEntries('2026-01-29', assignmentId);
-if (tsResult.ok) console.log(tsResult.data); // LPTimesheetEntry[]
+const tsResult = await client.getTimesheetEntries('2026-01-29');
+if (tsResult.ok) console.log(tsResult.data); // LPTimesheetEntries (grouped by member)
 
 // Update an existing entry (accumulate hours)
-const existing = tsResult.data![0];
+const existing = tsResult.data!.members[0].entries[0];
 await client.updateTimesheetEntry(existing.id, existing, {
   hours: existing.hours + 1.5,
   note: 'Additional work'
@@ -114,7 +114,7 @@ All methods return `Result<T>` — see [api-core Result Pattern](../../README.md
 | `findItems(options)` | `LPFindItemsOptions` | `Result<LPItem[]>` |
 | `getChildren(parentId, options?)` | `number, { itemType? }?` | `Result<LPItem[]>` |
 | `getWorkspaceTree()` | — | `Result<LPWorkspaceTree>` |
-| `getAssignments(memberId)` | `number` | `Result<{ assignments: LPAssignment[], treeItemCount: number }>` |
+| `getAssignments(memberId?)` | `number?` | `Result<LPAssignments>` |
 | `clearCache()` | — | `void` |
 | `invalidateTimesheetCache()` | — | `void` |
 | `invalidateTreeCache()` | — | `void` |
@@ -123,9 +123,10 @@ All methods return `Result<T>` — see [api-core Result Pattern](../../README.md
 | `invalidateCostCodeCache()` | — | `void` |
 | `getCostCodes()` | — | `Result<LPCostCode[]>` |
 | `createTimesheetEntry(entry)` | `LPTimesheetEntry` | `LPSyncResult` |
-| `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `Result<LPTimesheetEntry[]>` |
+| `getTimesheetEntries(date, options?)` | `string \| string[], LPTimesheetOptions?` | `Result<LPTimesheetEntries>` |
 | `updateTimesheetEntry(entryId, existing, updates)` | `number, LPTimesheetEntry, Partial<LPTimesheetEntry>` | `LPSyncResult` |
 | `upsertTimesheetEntry(entry, options?)` | `LPTimesheetEntry, LPUpsertOptions?` | `LPSyncResult` |
+| `getWeeklySummary(dates, options?)` | `string[], LPWeeklySummaryOptions?` | `Result<LPWeeklySummary>` |
 
 ### Workflow: `resolveTaskToAssignment`
 

package/dist/client.d.ts

@@ -7,7 +7,7 @@
  * @see https://api-docs.liquidplanner.com/
  */
 import type { Result } from '@markwharton/api-core';
-import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetOptions, LPUpsertOptions, LPAncestor, LPFindItemsOptions, LPWorkspaceTree, LPAssignmentsResult } from './types.js';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetOptions, LPUpsertOptions, LPTimesheetEntries, LPAncestor, LPFindItemsOptions, LPWorkspaceTree, LPAssignments, LPWeeklySummaryOptions, LPWeeklySummary } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -178,7 +178,7 @@ export declare class LPClient {
      *
      * @param memberId - Filter to a specific member's assignments. When omitted, returns all members' assignments.
      */
-    getAssignments(memberId?: number): Promise<Result<LPAssignmentsResult>>;
+    getAssignments(memberId?: number): Promise<Result<LPAssignments>>;
     /**
      * Get all cost codes in the workspace
      */
@@ -204,7 +204,7 @@ export declare class LPClient {
      * @param date - Date(s) in YYYY-MM-DD format (string or array)
      * @param options - Optional filters (itemId, memberId)
      */
-    getTimesheetEntries(date: string | string[], options?: LPTimesheetOptions): Promise<Result<LPTimesheetEntry[]>>;
+    getTimesheetEntries(date: string | string[], options?: LPTimesheetOptions): Promise<Result<LPTimesheetEntries>>;
     /**
      * Update an existing timesheet entry
      *
@@ -260,4 +260,17 @@ export declare class LPClient {
      * @param options - Upsert options (accumulate defaults to true)
      */
     upsertTimesheetEntry(entry: LPTimesheetEntry, options?: LPUpsertOptions): Promise<LPSyncResult>;
+    /**
+     * Get a weekly summary with per-member time breakdowns.
+     *
+     * Aggregates timesheet entries by member and date. Optionally includes
+     * assignments and late items when specified via the `include` option.
+     *
+     * Fetches are parallelized — timesheet entries are always fetched, while
+     * assignments and late items are conditionally fetched based on `include`.
+     *
+     * @param dates - Array of date strings (YYYY-MM-DD) for the week
+     * @param options - Optional memberId filter and detail sections to include
+     */
+    getWeeklySummary(dates: string[], options?: LPWeeklySummaryOptions): Promise<Result<LPWeeklySummary>>;
 }

package/dist/client.js

@@ -640,7 +640,7 @@ export class LPClient {
             if (memberId) {
                 baseUrl += `&${filterIs('userId', memberId)}`;
             }
-            return paginatedFetch({
+            const flatResult = await paginatedFetch({
                 fetchFn: (url) => this.fetch(url),
                 baseUrl,
                 transform: (data) => data.map(entry => ({
@@ -653,6 +653,23 @@ export class LPClient {
                     userId: entry.userId,
                 })),
             });
+            if (!flatResult.ok)
+                return err(flatResult.error, flatResult.status);
+            // Group by member (same pattern as getAssignments)
+            const memberMap = new Map();
+            for (const entry of flatResult.data) {
+                const uid = entry.userId ?? 0;
+                let entries = memberMap.get(uid);
+                if (!entries) {
+                    entries = [];
+                    memberMap.set(uid, entries);
+                }
+                entries.push(entry);
+            }
+            const members = [...memberMap.entries()]
+                .sort(([a], [b]) => a - b)
+                .map(([memberId, entries]) => ({ memberId, entries }));
+            return ok({ members });
         });
     }
     /**
@@ -734,10 +751,11 @@ export class LPClient {
         if (!fetchResult.ok) {
             return { ok: false, error: fetchResult.error, status: fetchResult.status };
         }
-        // Find matching entry
+        // Find matching entry from grouped result
         // If no costCodeId specified, match any entry (LP uses assignment's default)
         // If costCodeId specified, match exactly
-        const existingEntry = fetchResult.data?.find((e) => {
+        const allEntries = fetchResult.data?.members.flatMap(m => m.entries) ?? [];
+        const existingEntry = allEntries.find((e) => {
             if (entry.costCodeId === undefined || entry.costCodeId === null) {
                 return true;
             }
@@ -756,4 +774,53 @@ export class LPClient {
         // No existing entry, create new
         return this.createTimesheetEntry(entry);
     }
+    // ============================================================================
+    // Weekly Summary
+    // ============================================================================
+    /**
+     * Get a weekly summary with per-member time breakdowns.
+     *
+     * Aggregates timesheet entries by member and date. Optionally includes
+     * assignments and late items when specified via the `include` option.
+     *
+     * Fetches are parallelized — timesheet entries are always fetched, while
+     * assignments and late items are conditionally fetched based on `include`.
+     *
+     * @param dates - Array of date strings (YYYY-MM-DD) for the week
+     * @param options - Optional memberId filter and detail sections to include
+     */
+    async getWeeklySummary(dates, options) {
+        const { memberId, include = [] } = options || {};
+        const includeSet = new Set(include);
+        // Parallel fetch: timesheet (always) + optional sections
+        const [timesheetResult, assignmentsResult, lateItemsResult] = await Promise.all([
+            this.getTimesheetEntries(dates, memberId ? { memberId } : undefined),
+            includeSet.has('assignments') ? this.getAssignments(memberId) : Promise.resolve(null),
+            includeSet.has('lateItems')
+                ? this.findItems({ itemType: 'tasks', taskStatusGroupNot: 'done', late: true })
+                : Promise.resolve(null),
+        ]);
+        if (!timesheetResult.ok)
+            return err(timesheetResult.error, timesheetResult.status);
+        if (assignmentsResult && !assignmentsResult.ok)
+            return err(assignmentsResult.error, assignmentsResult.status);
+        if (lateItemsResult && !lateItemsResult.ok)
+            return err(lateItemsResult.error, lateItemsResult.status);
+        // Build per-member weekly summaries from grouped timesheet entries
+        const members = timesheetResult.data.members.map(({ memberId, entries }) => {
+            const timeSummary = {};
+            let totalHours = 0;
+            for (const entry of entries) {
+                timeSummary[entry.date] = (timeSummary[entry.date] || 0) + entry.hours;
+                totalHours += entry.hours;
+            }
+            return { memberId, timeSummary, totalHours, entries };
+        });
+        const result = { members };
+        if (assignmentsResult)
+            result.assignments = assignmentsResult.data;
+        if (lateItemsResult)
+            result.lateItems = lateItemsResult.data;
+        return ok(result);
+    }
 }

package/dist/index.d.ts

@@ -30,7 +30,7 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, LPUserType, LPHierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTaskResolution, LPTimesheetOptions, LPUpsertOptions, LPAssignment, LPItemRef, LPNormalizedAssignment, LPMemberAssignments, LPAssignmentsResult, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
+export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, LPUserType, LPHierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTaskResolution, LPTimesheetOptions, LPUpsertOptions, LPMemberTimesheetEntries, LPTimesheetEntries, LPAssignment, LPItemRef, LPNormalizedAssignment, LPMemberAssignments, LPAssignments, LPWeeklySummaryOptions, LPMemberWeeklySummary, LPWeeklySummary, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
 export type { AccessTier } from './types.js';
 export { METHOD_TIERS, ENTITIES } from './types.js';
 export { ok, err, getErrorMessage, normalizeEnum, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';

package/dist/types.d.ts

@@ -265,6 +265,20 @@ export interface LPUpsertOptions {
      */
     accumulate?: boolean;
 }
+/**
+ * One member's timesheet entries in the grouped result
+ */
+export interface LPMemberTimesheetEntries {
+    memberId: number;
+    entries: LPTimesheetEntry[];
+}
+/**
+ * Timesheet entries grouped by member.
+ * One member entry when memberId specified, all members when omitted.
+ */
+export interface LPTimesheetEntries {
+    members: LPMemberTimesheetEntries[];
+}
 /**
  * Assignment with resolved parent context
  *
@@ -350,7 +364,7 @@ export interface LPMemberAssignments {
  * Normalized assignments result with shared lookup tables.
  * Deduplicates ancestor items and custom field values to reduce payload size.
  */
-export interface LPAssignmentsResult {
+export interface LPAssignments {
     /** Assignments grouped by member. One entry when memberId specified, all members when omitted. */
     members: LPMemberAssignments[];
     /** Shared items lookup — walk parentId chains to reconstruct ancestor paths */
@@ -360,6 +374,39 @@ export interface LPAssignmentsResult {
     /** Total items in the workspace tree snapshot */
     treeItemCount: number;
 }
+/**
+ * Options for getWeeklySummary
+ */
+export interface LPWeeklySummaryOptions {
+    /** Filter to a specific member. When omitted, returns all members. */
+    memberId?: number;
+    /** Optional detail sections to include alongside the time summary */
+    include?: ('assignments' | 'lateItems')[];
+}
+/**
+ * One member's weekly summary with time breakdown by date
+ */
+export interface LPMemberWeeklySummary {
+    memberId: number;
+    /** Total hours per date (date string → hours) */
+    timeSummary: Record<string, number>;
+    /** Sum of all hours across all dates */
+    totalHours: number;
+    /** Raw timesheet entries for this member */
+    entries: LPTimesheetEntry[];
+}
+/**
+ * Weekly summary with per-member time breakdowns and optional detail sections.
+ * Aggregates timesheet entries, assignments, and late items into a single result.
+ */
+export interface LPWeeklySummary {
+    /** Per-member weekly summaries */
+    members: LPMemberWeeklySummary[];
+    /** Assignments data (when 'assignments' included) */
+    assignments?: LPAssignments;
+    /** Late items (when 'lateItems' included) */
+    lateItems?: LPItem[];
+}
 /**
  * Options for querying items with LP API filters
  *

package/dist/types.js

@@ -26,6 +26,7 @@ export const METHOD_TIERS = {
     getTimesheetEntries: 'standard',
     updateTimesheetEntry: 'standard',
     upsertTimesheetEntry: 'standard',
+    getWeeklySummary: 'standard',
 };
 // ============================================================================
 // Entity Registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/liquidplanner",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "description": "LiquidPlanner API client for timesheet integration",
   "type": "module",
   "main": "dist/index.js",