@markwharton/liquidplanner 1.11.0 → 2.0.0

package/README.md

@@ -59,6 +59,42 @@ await client.updateTimesheetEntry(entryId, existingEntry, {
   hours: existingEntry.hours + 1.5,
   note: 'Additional work'
 });
+
+// Find items with filters
+const { items } = await client.findItems({
+  itemType: 'tasks',
+  taskStatusGroupNot: 'done',
+  late: true,
+});
+
+// Get children of an item
+const { items: children } = await client.getChildren(parentId);
+
+// Get workspace tree snapshot (cached, all hierarchy lookups resolved in memory)
+const { tree } = await client.getWorkspaceTree();
+
+// Get a member's work with full context from the tree
+const { assignments: myWork, treeItemCount } = await client.getMyWork(memberId);
+// Each assignment includes taskName, projectId, projectName, hierarchyPath, ancestors
+// treeItemCount shows total items loaded (only member's assignments returned downstream)
+```
+
+### Tree Utilities
+
+```typescript
+import { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree } from '@markwharton/liquidplanner';
+
+// Build tree from flat item array
+const tree = buildTree(items);
+
+// Get ancestors (root → parent order)
+const ancestors = getTreeAncestors(tree, itemId);
+
+// Get formatted path like "Project A › Subfolder B"
+const path = getTreeHierarchyPath(tree, itemId);
+
+// Find items matching a predicate
+const lateTasks = findInTree(tree, item => item.late === true);
 ```
 
 ## API Reference
@@ -76,6 +112,11 @@ All methods return `{ data?, error? }` result objects rather than throwing excep
 | `findAssignments(taskId)` | `number` | `{ assignments?, error? }` |
 | `getMyAssignments(memberId)` | `number` | `{ assignments?, error? }` |
 | `getMyAssignmentsWithContext(memberId, options?)` | `number, { includeProject?, includeHierarchy? }` | `{ assignments?, error? }` |
+| `findItems(options)` | `LPFindItemsOptions` | `{ items?, error? }` |
+| `getChildren(parentId, options?)` | `number, { itemType? }?` | `{ items?, error? }` |
+| `getWorkspaceTree()` | — | `{ tree?, error? }` |
+| `getMyWork(memberId)` | `number` | `{ assignments?, treeItemCount?, error? }` |
+| `invalidateTreeCache()` | — | `void` |
 | `getCostCodes()` | — | `{ costCodes?, error? }` |
 | `createTimesheetEntry(entry)` | `LPTimesheetEntry` | `LPSyncResult` |
 | `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `{ entries?, error? }` |
@@ -93,6 +134,28 @@ const resolution = await resolveTaskToAssignment(client, taskId, memberId);
 
 Resolves a Task ID to the correct Assignment ID for time logging. Handles cases where a task has multiple assignments by filtering on member ID.
 
+### Tree Utilities
+
+| Function | Description |
+|----------|-------------|
+| `buildTree(items)` | Build a navigable tree from a flat item array |
+| `getTreeAncestors(tree, itemId)` | Get ancestors from root to parent (excludes item) |
+| `getTreeHierarchyPath(tree, itemId)` | Formatted path like "Project A > Subfolder B" |
+| `findInTree(tree, predicate)` | Find all items matching a predicate |
+
+### Filter Utilities
+
+| Function | Description |
+|----------|-------------|
+| `filterIs(field, value)` | `field[is]="value"` |
+| `filterIsNot(field, value)` | `field[is_not]="value"` |
+| `filterIn(field, values)` | `field[in]=["v1","v2"]` |
+| `filterGt(field, value)` | `field[gt]="value"` |
+| `filterLt(field, value)` | `field[lt]="value"` |
+| `filterAfter(field, value)` | `field[after]="value"` — accepts YYYY-MM-DD (local timezone) or ISO |
+| `filterBefore(field, value)` | `field[before]="value"` — accepts YYYY-MM-DD (local timezone) or ISO |
+| `joinFilters(...filters)` | Join filter strings with `&` |
+
 ## Configuration
 
 ```typescript
@@ -114,13 +177,14 @@ const client = new LPClient({
 
 | Cache Key | Default TTL |
 |-----------|-------------|
+| Workspace tree | 10 min |
 | Workspace members | 5 min |
 | Cost codes | 5 min |
 | Items / ancestors | 5 min |
 | Assignments | 2 min |
 | Timesheet entries | 60s |
 
-Write operations (`createTimesheetEntry`, `updateTimesheetEntry`) automatically invalidate timesheet cache entries. Call `client.clearCache()` to manually clear all cached data.
+Write operations (`createTimesheetEntry`, `updateTimesheetEntry`) automatically invalidate timesheet cache entries. Call `client.invalidateTreeCache()` to refresh the workspace tree, or `client.clearCache()` to clear all cached data.
 
 ### Retry
 

package/dist/client.d.ts

@@ -6,7 +6,8 @@
  *
  * @see https://api-docs.liquidplanner.com/
  */
-import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext, LPAncestor, LPErrorInfo } from './types.js';
+import type { Result } from '@markwharton/api-core';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext, LPAncestor, LPFindItemsOptions, LPWorkspaceTree } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -59,6 +60,11 @@ export declare class LPClient {
      * (e.g., after logging time which updates loggedHoursRollup).
      */
     invalidateAssignmentsCache(): void;
+    /**
+     * Invalidate cached workspace tree snapshot only.
+     * Use when the workspace structure changes (items created, moved, or deleted).
+     */
+    invalidateTreeCache(): void;
     /**
      * Make an authenticated request to the LP API
      *
@@ -75,34 +81,26 @@ export declare class LPClient {
      * Fetch a URL and parse the response, with standardized error handling.
      */
     private fetchAndParse;
+    /**
+     * Fetch and parse with isDuplicate support for mutation methods.
+     */
+    private fetchAndParseMutation;
     /**
      * Validate the API token by listing workspaces
      */
-    validateToken(): Promise<{
-        valid: boolean;
-        error?: string;
-    }>;
+    validateToken(): Promise<Result<void>>;
     /**
      * Get all workspaces accessible to the API token
      */
-    getWorkspaces(): Promise<{
-        workspaces?: LPWorkspace[];
-        error?: LPErrorInfo;
-    }>;
+    getWorkspaces(): Promise<Result<LPWorkspace[]>>;
     /**
      * Get all members in the workspace (with pagination)
      */
-    getWorkspaceMembers(): Promise<{
-        members?: LPMember[];
-        error?: LPErrorInfo;
-    }>;
+    getWorkspaceMembers(): Promise<Result<LPMember[]>>;
     /**
      * Get a single item by ID
      */
-    getItem(itemId: number): Promise<{
-        item?: LPItem;
-        error?: LPErrorInfo;
-    }>;
+    getItem(itemId: number): Promise<Result<LPItem>>;
     /**
      * Get multiple items by ID in a single request (batch fetch)
      *
@@ -111,10 +109,7 @@ export declare class LPClient {
      *
      * @param itemIds - Array of item IDs to fetch
      */
-    getItems(itemIds: number[]): Promise<{
-        items?: LPItem[];
-        error?: LPErrorInfo;
-    }>;
+    getItems(itemIds: number[]): Promise<Result<LPItem[]>>;
     /**
      * Get the ancestry chain for an item
      *
@@ -123,27 +118,18 @@ export declare class LPClient {
      *
      * @param itemId - The item ID to get ancestors for
      */
-    getItemAncestors(itemId: number): Promise<{
-        ancestors?: LPAncestor[];
-        error?: LPErrorInfo;
-    }>;
+    getItemAncestors(itemId: number): Promise<Result<LPAncestor[]>>;
     /**
      * Find all assignments under a task (with pagination)
      */
-    findAssignments(taskId: number): Promise<{
-        assignments?: LPItem[];
-        error?: LPErrorInfo;
-    }>;
+    findAssignments(taskId: number): Promise<Result<LPItem[]>>;
     /**
      * Get all assignments for a specific member
      *
      * This enables PWA apps to show a task picker populated from LP directly.
      * Note: userId is not a supported filter field in the LP API, so we filter client-side.
      */
-    getMyAssignments(memberId: number): Promise<{
-        assignments?: LPItem[];
-        error?: LPErrorInfo;
-    }>;
+    getMyAssignments(memberId: number): Promise<Result<LPItem[]>>;
     /**
      * Get assignments for a member with parent task names resolved
      *
@@ -163,17 +149,63 @@ export declare class LPClient {
     getMyAssignmentsWithContext(memberId: number, options?: {
         includeProject?: boolean;
         includeHierarchy?: boolean;
-    }): Promise<{
-        assignments?: LPAssignmentWithContext[];
-        error?: LPErrorInfo;
-    }>;
+    }): Promise<Result<LPAssignmentWithContext[]>>;
+    /**
+     * Query items with LP API filters
+     *
+     * General-purpose method that exposes the full filtering capabilities of
+     * the LP items endpoint. Not cached — use higher-level methods like
+     * getWorkspaceTree() for cached access.
+     *
+     * @see https://api-docs.liquidplanner.com/docs/plan-items
+     *
+     * @param options - Filter options (all optional, combined with AND)
+     */
+    findItems(options: LPFindItemsOptions): Promise<Result<LPItem[]>>;
+    /**
+     * Get direct children of an item
+     *
+     * Uses parentId[is] filter to fetch immediate descendants.
+     * Optionally filter by item type.
+     *
+     * @param parentId - The parent item ID
+     * @param options - Optional item type filter
+     */
+    getChildren(parentId: number, options?: {
+        itemType?: string;
+    }): Promise<Result<LPItem[]>>;
+    /**
+     * Fetch a snapshot of the active workspace tree
+     *
+     * Fetches all workspace items in paginated API calls, then builds a
+     * navigable tree in memory from parentId relationships.
+     *
+     * The result is cached with treeTtl (default: 10 minutes).
+     * Use invalidateTreeCache() to force a refresh.
+     *
+     * After the initial fetch, all hierarchy queries (ancestors, paths, assignments
+     * with context) can be answered from the cached tree with zero API calls.
+     */
+    getWorkspaceTree(): Promise<Result<LPWorkspaceTree>>;
+    /**
+     * Get a member's active work with full context from the workspace tree
+     *
+     * This is the optimized alternative to getMyAssignmentsWithContext().
+     * Uses the workspace tree snapshot (cached) to resolve hierarchy locally,
+     * eliminating the N+1 ancestor request pattern.
+     *
+     * API calls: 0 (if tree cached) or 1-3 (cold load)
+     *
+     * @param memberId - The member ID to get work for
+     */
+    getMyWork(memberId: number): Promise<Result<{
+        assignments: LPAssignmentWithContext[];
+        treeItemCount: number;
+    }>>;
     /**
      * Get all cost codes in the workspace (with pagination)
      */
-    getCostCodes(): Promise<{
-        costCodes?: LPCostCode[];
-        error?: LPErrorInfo;
-    }>;
+    getCostCodes(): Promise<Result<LPCostCode[]>>;
     /**
      * Create a timesheet entry (log time)
      *
@@ -195,10 +227,7 @@ export declare class LPClient {
      * @param date - Date(s) in YYYY-MM-DD format (string or array)
      * @param itemId - Optional item ID to filter by
      */
-    getTimesheetEntries(date: string | string[], itemId?: number): Promise<{
-        entries?: LPTimesheetEntryWithId[];
-        error?: LPErrorInfo;
-    }>;
+    getTimesheetEntries(date: string | string[], itemId?: number): Promise<Result<LPTimesheetEntryWithId[]>>;
     /**
      * Update an existing timesheet entry
      *