@markwharton/liquidplanner 1.10.0 → 1.12.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,7 @@
  *
  * @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 { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext, LPAncestor, LPErrorInfo, LPFindItemsOptions, LPWorkspaceTree } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -53,6 +53,17 @@ export declare class LPClient {
      * data changed but the write didn't go through this client instance.
      */
     invalidateTimesheetCache(): void;
+    /**
+     * Invalidate cached assignments only.
+     * Use when an external event indicates assignment data changed
+     * (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
      *
@@ -161,6 +172,68 @@ export declare class LPClient {
         assignments?: LPAssignmentWithContext[];
         error?: LPErrorInfo;
     }>;
+    /**
+     * 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<{
+        items?: LPItem[];
+        error?: LPErrorInfo;
+    }>;
+    /**
+     * 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<{
+        items?: LPItem[];
+        error?: LPErrorInfo;
+    }>;
+    /**
+     * 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<{
+        tree?: LPWorkspaceTree;
+        error?: LPErrorInfo;
+    }>;
+    /**
+     * 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<{
+        assignments?: LPAssignmentWithContext[];
+        treeItemCount?: number;
+        error?: LPErrorInfo;
+    }>;
     /**
      * Get all cost codes in the workspace (with pagination)
      */

package/dist/client.js

@@ -6,7 +6,8 @@
  *
  * @see https://api-docs.liquidplanner.com/
  */
-import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, } from './utils.js';
+import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIsNot, filterIn, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
+import { buildTree, getTreeAncestors } from './tree.js';
 import { parseLPErrorResponse } from './errors.js';
 import { LP_API_BASE } from './constants.js';
 import { TTLCache, batchMap, getErrorMessage, fetchWithRetry } from '@markwharton/api-core';
@@ -63,6 +64,25 @@ function transformItem(raw) {
         item.folderStatus = raw.folderStatus;
     if (raw.globalPriority)
         item.globalPriority = raw.globalPriority;
+    // Extended fields — only include if present
+    if (raw.color)
+        item.color = raw.color;
+    if (raw.workType)
+        item.workType = raw.workType;
+    if (raw.description)
+        item.description = raw.description;
+    if (raw.customFieldValues)
+        item.customFieldValues = raw.customFieldValues;
+    if (raw.createdAt)
+        item.createdAt = raw.createdAt;
+    if (raw.updatedAt)
+        item.updatedAt = raw.updatedAt;
+    if (raw.clippedHours !== undefined)
+        item.clippedHours = raw.clippedHours;
+    if (raw.workLimitHours !== undefined)
+        item.workLimitHours = raw.workLimitHours;
+    if (raw.workLimitRisk !== undefined)
+        item.workLimitRisk = raw.workLimitRisk;
     return item;
 }
 /**
@@ -103,6 +123,7 @@ export class LPClient {
             timesheetTtl: config.cache?.timesheetTtl ?? 60000,
             assignmentsTtl: config.cache?.assignmentsTtl ?? 120000,
             itemsTtl: config.cache?.itemsTtl ?? 300000,
+            treeTtl: config.cache?.treeTtl ?? 600000,
         };
         // Initialize retry config with defaults if provided
         if (config.retry) {
@@ -137,6 +158,21 @@ export class LPClient {
     invalidateTimesheetCache() {
         this.cache?.invalidate('timesheet:');
     }
+    /**
+     * Invalidate cached assignments only.
+     * Use when an external event indicates assignment data changed
+     * (e.g., after logging time which updates loggedHoursRollup).
+     */
+    invalidateAssignmentsCache() {
+        this.cache?.invalidate('assignments:');
+    }
+    /**
+     * Invalidate cached workspace tree snapshot only.
+     * Use when the workspace structure changes (items created, moved, or deleted).
+     */
+    invalidateTreeCache() {
+        this.cache?.invalidate('tree');
+    }
     /**
      * Make an authenticated request to the LP API
      *
@@ -463,6 +499,156 @@ export class LPClient {
         };
     }
     // ============================================================================
+    // Item Queries (Rich Filtering)
+    // ============================================================================
+    /**
+     * 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)
+     */
+    async findItems(options) {
+        const filters = [];
+        // Identity
+        if (options.parentId !== undefined)
+            filters.push(filterIs('parentId', options.parentId));
+        if (options.itemType)
+            filters.push(filterIs('itemType', options.itemType));
+        // Status
+        if (options.taskStatusGroup)
+            filters.push(filterIs('taskStatusGroup', options.taskStatusGroup));
+        if (options.taskStatusGroupNot)
+            filters.push(filterIsNot('taskStatusGroup', options.taskStatusGroupNot));
+        if (options.taskStatusId !== undefined)
+            filters.push(filterIs('taskStatusId', options.taskStatusId));
+        if (options.packageStatus)
+            filters.push(filterIs('packageStatus', options.packageStatus));
+        if (options.folderStatus)
+            filters.push(filterIs('folderStatus', options.folderStatus));
+        // Scheduling
+        if (options.scheduleDirective)
+            filters.push(filterIs('scheduleDirective', options.scheduleDirective));
+        if (options.expectedStartAfter)
+            filters.push(filterAfter('expectedStart', options.expectedStartAfter));
+        if (options.expectedFinishBefore)
+            filters.push(filterBefore('expectedFinish', options.expectedFinishBefore));
+        if (options.targetStartAfter)
+            filters.push(filterAfter('targetStart', options.targetStartAfter));
+        if (options.targetFinishBefore)
+            filters.push(filterBefore('targetFinish', options.targetFinishBefore));
+        if (options.doneDateAfter)
+            filters.push(filterAfter('doneDate', options.doneDateAfter));
+        // Flags
+        if (options.late !== undefined)
+            filters.push(filterIs('late', String(options.late)));
+        if (options.workLimitRisk !== undefined)
+            filters.push(filterIs('workLimitRisk', String(options.workLimitRisk)));
+        if (options.hasFiles !== undefined)
+            filters.push(filterIs('hasFiles', String(options.hasFiles)));
+        // Search
+        if (options.name)
+            filters.push(filterIs('name', options.name));
+        // Custom fields
+        if (options.customFieldValues) {
+            for (const [key, value] of Object.entries(options.customFieldValues)) {
+                filters.push(filterIs(`customFieldValues.${key}`, value));
+            }
+        }
+        const query = filters.length > 0 ? `?${joinFilters(...filters)}` : '';
+        const baseUrl = this.workspaceUrl(`items/v1${query}`);
+        const { results, error } = await paginatedFetch({
+            fetchFn: (url) => this.fetch(url),
+            baseUrl,
+            transform: (data) => data.map(transformItem),
+        });
+        return error ? { error } : { items: results };
+    }
+    /**
+     * 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
+     */
+    async getChildren(parentId, options) {
+        return this.findItems({
+            parentId,
+            itemType: options?.itemType,
+        });
+    }
+    // ============================================================================
+    // Workspace Tree
+    // ============================================================================
+    /**
+     * 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.
+     */
+    async getWorkspaceTree() {
+        return this.cached('tree', this.cacheTtl.treeTtl, async () => {
+            // Fetch all workspace items in paginated calls
+            const { items, error } = await this.findItems({});
+            if (error || !items)
+                return { error };
+            const tree = buildTree(items);
+            return { tree };
+        });
+    }
+    /**
+     * 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
+     */
+    async getMyWork(memberId) {
+        const { tree, error } = await this.getWorkspaceTree();
+        if (error || !tree)
+            return { error };
+        const assignments = [];
+        for (const node of tree.byId.values()) {
+            if (node.itemType !== 'Assignment' || node.userId !== memberId)
+                continue;
+            const ancestors = getTreeAncestors(tree, node.id);
+            const taskAncestor = ancestors.find(a => a.itemType === 'Task');
+            const hierarchyAncestors = ancestors.filter(a => a.itemType === 'Project' || a.itemType === 'Folder');
+            const { children: _, ...itemFields } = node;
+            const result = { ...itemFields };
+            result.taskName = taskAncestor?.name ?? null;
+            result.ancestors = ancestors;
+            if (hierarchyAncestors.length > 0) {
+                result.projectId = hierarchyAncestors[0].id;
+                result.projectName = hierarchyAncestors[0].name;
+                result.hierarchyPath = hierarchyAncestors
+                    .map(a => a.name ?? `[${a.id}]`)
+                    .join(' › ');
+            }
+            else {
+                result.projectName = null;
+            }
+            assignments.push(result);
+        }
+        return { assignments, treeItemCount: tree.itemCount };
+    }
+    // ============================================================================
     // Cost Codes
     // ============================================================================
     /**

package/dist/index.d.ts

@@ -28,9 +28,10 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, HierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, LPErrorInfo, } from './types.js';
-export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
+export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, HierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, LPErrorInfo, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
+export { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';
 export { getErrorMessage } from '@markwharton/api-core';
 export { LP_API_BASE } from './constants.js';
 export { LPError, parseLPErrorResponse } from './errors.js';

package/dist/index.js

@@ -31,7 +31,9 @@ export { LPClient } from './client.js';
 // Workflows
 export { resolveTaskToAssignment } from './workflows.js';
 // Utilities
-export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
+// Tree utilities
+export { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';
 export { getErrorMessage } from '@markwharton/api-core';
 // Constants
 export { LP_API_BASE } from './constants.js';

package/dist/tree.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tree Building and Query Utilities
+ *
+ * Pure functions that operate on LPWorkspaceTree — zero API calls.
+ * Used by LPClient.getWorkspaceTree() for building and by consumers for querying.
+ */
+import type { LPItem, LPAncestor, LPWorkspaceTree } from './types.js';
+/**
+ * Build a workspace tree from a flat array of items
+ *
+ * Assembles items into a tree using parentId relationships.
+ * Items whose parent is not in the array become root nodes.
+ */
+export declare function buildTree(items: LPItem[]): LPWorkspaceTree;
+/**
+ * Get ancestors of an item from root to parent
+ *
+ * Walks up the tree via parentId, collecting ancestors in root→child order.
+ * Same order as LPClient.getItemAncestors() — excludes the item itself.
+ */
+export declare function getTreeAncestors(tree: LPWorkspaceTree, itemId: number): LPAncestor[];
+/**
+ * Build a formatted hierarchy path for an item
+ *
+ * Returns a string like "Project A › Subfolder B" from Project and Folder ancestors.
+ * Excludes system containers (Package, WorkspaceRoot) and Tasks.
+ */
+export declare function getTreeHierarchyPath(tree: LPWorkspaceTree, itemId: number): string;
+/**
+ * Find all items in the tree matching a predicate
+ */
+export declare function findInTree(tree: LPWorkspaceTree, predicate: (item: LPItem) => boolean): LPItem[];

package/dist/tree.js

@@ -0,0 +1,86 @@
+/**
+ * Tree Building and Query Utilities
+ *
+ * Pure functions that operate on LPWorkspaceTree — zero API calls.
+ * Used by LPClient.getWorkspaceTree() for building and by consumers for querying.
+ */
+/**
+ * Build a workspace tree from a flat array of items
+ *
+ * Assembles items into a tree using parentId relationships.
+ * Items whose parent is not in the array become root nodes.
+ */
+export function buildTree(items) {
+    // Create tree nodes with empty children arrays
+    const byId = new Map();
+    for (const item of items) {
+        byId.set(item.id, { ...item, children: [] });
+    }
+    // Wire parent-child relationships
+    const roots = [];
+    for (const node of byId.values()) {
+        if (node.parentId !== undefined && byId.has(node.parentId)) {
+            byId.get(node.parentId).children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return {
+        roots,
+        byId,
+        fetchedAt: Date.now(),
+        itemCount: items.length,
+    };
+}
+/**
+ * Get ancestors of an item from root to parent
+ *
+ * Walks up the tree via parentId, collecting ancestors in root→child order.
+ * Same order as LPClient.getItemAncestors() — excludes the item itself.
+ */
+export function getTreeAncestors(tree, itemId) {
+    const ancestors = [];
+    let current = tree.byId.get(itemId);
+    if (!current)
+        return ancestors;
+    // Walk up to root
+    while (current.parentId !== undefined) {
+        const parent = tree.byId.get(current.parentId);
+        if (!parent)
+            break;
+        ancestors.push({
+            id: parent.id,
+            name: parent.name,
+            itemType: parent.itemType,
+        });
+        current = parent;
+    }
+    // Reverse to root→child order (we collected child→root)
+    return ancestors.reverse();
+}
+/**
+ * Build a formatted hierarchy path for an item
+ *
+ * Returns a string like "Project A › Subfolder B" from Project and Folder ancestors.
+ * Excludes system containers (Package, WorkspaceRoot) and Tasks.
+ */
+export function getTreeHierarchyPath(tree, itemId) {
+    const ancestors = getTreeAncestors(tree, itemId);
+    const hierarchyAncestors = ancestors.filter(a => a.itemType === 'Project' || a.itemType === 'Folder');
+    return hierarchyAncestors
+        .map(a => a.name ?? `[${a.id}]`)
+        .join(' › ');
+}
+/**
+ * Find all items in the tree matching a predicate
+ */
+export function findInTree(tree, predicate) {
+    const results = [];
+    for (const node of tree.byId.values()) {
+        if (predicate(node)) {
+            results.push(node);
+        }
+    }
+    return results;
+}

package/dist/types.d.ts

@@ -91,6 +91,24 @@ export interface LPItem {
     folderStatus?: string;
     /** Priority ordering (global priority array from LP) */
     globalPriority?: string[];
+    /** Item color */
+    color?: string;
+    /** Work type */
+    workType?: string;
+    /** Item description/notes */
+    description?: string;
+    /** Custom field values with inheritance info */
+    customFieldValues?: Record<string, unknown>;
+    /** When the item was created (ISO string) */
+    createdAt?: string;
+    /** When the item was last updated (ISO string) */
+    updatedAt?: string;
+    /** Hours clipped by work limit */
+    clippedHours?: number;
+    /** Work limit in hours */
+    workLimitHours?: number;
+    /** Whether work limit is at risk */
+    workLimitRisk?: boolean;
 }
 /**
  * A cost code from LiquidPlanner
@@ -168,6 +186,8 @@ export interface LPCacheConfig {
     assignmentsTtl?: number;
     /** TTL for items and ancestors (default: 300000 = 5 min) */
     itemsTtl?: number;
+    /** TTL for workspace tree snapshot (default: 600000 = 10 min) */
+    treeTtl?: number;
 }
 /**
  * Retry configuration for LPClient
@@ -295,3 +315,70 @@ export interface LPErrorInfo {
     /** Whether this error indicates a duplicate entry */
     isDuplicate?: boolean;
 }
+/**
+ * Options for querying items with LP API filters
+ *
+ * Maps to LP API filter parameters on the items endpoint.
+ * All fields are optional — only specified fields generate filters.
+ */
+export interface LPFindItemsOptions {
+    /** Filter by parent item ID (parentId[is]) */
+    parentId?: number;
+    /** Filter by item type — use LP API values: 'tasks', 'assignments', 'packages', 'projects', 'folders' */
+    itemType?: string;
+    /** Filter by task status group: 'scheduled', 'unscheduled', 'done' (taskStatusGroup[is]) */
+    taskStatusGroup?: string;
+    /** Exclude a task status group (taskStatusGroup[is_not]) */
+    taskStatusGroupNot?: string;
+    /** Filter by specific task status ID (taskStatusId[is]) */
+    taskStatusId?: number;
+    /** Filter by package collection: 'scheduled', 'backlog', 'archived', 'templates' (packageStatus[is]) */
+    packageStatus?: string;
+    /** Filter by folder status: 'active', 'onHold', 'done' (folderStatus[is]) */
+    folderStatus?: string;
+    /** Filter by scheduling priority (scheduleDirective[is]) */
+    scheduleDirective?: string;
+    /** Items with expected start after this date (expectedStart[after]) */
+    expectedStartAfter?: string;
+    /** Items with expected finish before this date (expectedFinish[before]) */
+    expectedFinishBefore?: string;
+    /** Items with target start after this date (targetStart[after]) */
+    targetStartAfter?: string;
+    /** Items with target finish before this date (targetFinish[before]) */
+    targetFinishBefore?: string;
+    /** Items completed after this date (doneDate[after]) */
+    doneDateAfter?: string;
+    /** Filter for late items (late[is]) */
+    late?: boolean;
+    /** Filter for items at work limit risk (workLimitRisk[is]) */
+    workLimitRisk?: boolean;
+    /** Filter for items with files (hasFiles[is]) */
+    hasFiles?: boolean;
+    /** Filter by item name (name[is]) */
+    name?: string;
+    /** Filter by custom field values (customFieldValues.<key>[is]) */
+    customFieldValues?: Record<string, string>;
+}
+/**
+ * A node in the workspace tree, extending LPItem with children
+ */
+export interface LPTreeNode extends LPItem {
+    /** Direct children of this node */
+    children: LPTreeNode[];
+}
+/**
+ * Workspace tree snapshot with lookup indices
+ *
+ * Built from a single fetch of all active items, this structure
+ * enables zero-API-call hierarchy lookups via the `byId` index.
+ */
+export interface LPWorkspaceTree {
+    /** Root nodes (typically packages) */
+    roots: LPTreeNode[];
+    /** Fast lookup: item ID → tree node */
+    byId: Map<number, LPTreeNode>;
+    /** Timestamp when snapshot was taken (Date.now()) */
+    fetchedAt: number;
+    /** Total number of items in the tree */
+    itemCount: number;
+}

package/dist/utils.d.ts

@@ -6,10 +6,38 @@ import type { LPItemType, LPErrorInfo } from './types.js';
  * Build a URL-encoded filter for LP API: field[is]="value"
  */
 export declare function filterIs(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[is_not]="value"
+ */
+export declare function filterIsNot(field: string, value: string | number): string;
 /**
  * Build a URL-encoded filter for LP API: field[in]=["value1","value2"]
  */
 export declare function filterIn(field: string, values: (string | number)[]): string;
+/**
+ * Build a URL-encoded filter for LP API: field[gt]="value"
+ */
+export declare function filterGt(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[lt]="value"
+ */
+export declare function filterLt(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[after]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export declare function filterAfter(field: string, value: string): string;
+/**
+ * Build a URL-encoded filter for LP API: field[before]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export declare function filterBefore(field: string, value: string): string;
+/**
+ * Join multiple filter expressions with &
+ */
+export declare function joinFilters(...filters: string[]): string;
 /**
  * Options for paginated fetch
  */

package/dist/utils.js

@@ -12,6 +12,12 @@ import { getErrorMessage } from '@markwharton/api-core';
 export function filterIs(field, value) {
     return `${field}%5Bis%5D=%22${value}%22`;
 }
+/**
+ * Build a URL-encoded filter for LP API: field[is_not]="value"
+ */
+export function filterIsNot(field, value) {
+    return `${field}%5Bis_not%5D=%22${value}%22`;
+}
 /**
  * Build a URL-encoded filter for LP API: field[in]=["value1","value2"]
  */
@@ -19,6 +25,51 @@ export function filterIn(field, values) {
     const encoded = values.map(v => `%22${v}%22`).join(',');
     return `${field}%5Bin%5D=%5B${encoded}%5D`;
 }
+/**
+ * Build a URL-encoded filter for LP API: field[gt]="value"
+ */
+export function filterGt(field, value) {
+    return `${field}%5Bgt%5D=%22${value}%22`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[lt]="value"
+ */
+export function filterLt(field, value) {
+    return `${field}%5Blt%5D=%22${value}%22`;
+}
+/** Normalize YYYY-MM-DD to ISO offset string using local timezone (LP API requires ISO for date filters) */
+function toISODateValue(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return value;
+    const d = new Date(`${value}T00:00:00`);
+    const offset = -d.getTimezoneOffset();
+    const sign = offset >= 0 ? '+' : '-';
+    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+    const minutes = String(Math.abs(offset) % 60).padStart(2, '0');
+    return `${value}T00:00:00${sign}${hours}:${minutes}`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[after]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export function filterAfter(field, value) {
+    return `${field}%5Bafter%5D=%22${toISODateValue(value)}%22`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[before]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export function filterBefore(field, value) {
+    return `${field}%5Bbefore%5D=%22${toISODateValue(value)}%22`;
+}
+/**
+ * Join multiple filter expressions with &
+ */
+export function joinFilters(...filters) {
+    return filters.join('&');
+}
 /**
  * Generic pagination helper for LP API endpoints
  *

package/package.json

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