@markwharton/liquidplanner 1.3.0 → 1.4.0

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 } from './types.js';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext, LPAncestor } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -79,6 +79,18 @@ export declare class LPClient {
         items?: LPItem[];
         error?: string;
     }>;
+    /**
+     * Get the ancestry chain for an item
+     *
+     * Returns ancestors from root to immediate parent (excludes the item itself).
+     * Uses the items/{itemId}/ancestors endpoint.
+     *
+     * @param itemId - The item ID to get ancestors for
+     */
+    getItemAncestors(itemId: number): Promise<{
+        ancestors?: LPAncestor[];
+        error?: string;
+    }>;
     /**
      * Find all assignments under a task (with pagination)
      */
@@ -100,14 +112,21 @@ export declare class LPClient {
      * Get assignments for a member with parent task names resolved
      *
      * This is a convenience method that fetches assignments and enriches
-     * them with parent task names using batch fetching (3 requests max instead of N+1).
+     * them with parent task names using batch fetching.
+     *
+     * Request counts:
+     * - Default: 2 requests (assignments + tasks)
+     * - includeProject: 3 requests (assignments + tasks + projects)
+     * - includeHierarchy: 1 + N requests (assignments + N ancestors calls)
      *
      * @param memberId - The member ID to get assignments for
      * @param options - Options for including additional context
      * @param options.includeProject - If true, also fetch grandparent project names
+     * @param options.includeHierarchy - If true, fetch full ancestry and build hierarchy path
      */
     getMyAssignmentsWithContext(memberId: number, options?: {
         includeProject?: boolean;
+        includeHierarchy?: boolean;
     }): Promise<{
         assignments?: LPAssignmentWithContext[];
         error?: string;

package/dist/client.js

@@ -176,6 +176,39 @@ export class LPClient {
         });
         return error ? { error } : { items: results };
     }
+    /**
+     * Get the ancestry chain for an item
+     *
+     * Returns ancestors from root to immediate parent (excludes the item itself).
+     * Uses the items/{itemId}/ancestors endpoint.
+     *
+     * @param itemId - The item ID to get ancestors for
+     */
+    async getItemAncestors(itemId) {
+        const url = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1/${itemId}/ancestors`;
+        try {
+            const response = await this.fetch(url, {
+                description: `Get ancestors for item ${itemId}`,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message } = parseLPErrorResponse(errorText, response.status);
+                return { error: message };
+            }
+            const json = (await response.json());
+            // Handle both { data: [...] } and direct array responses
+            const rawData = Array.isArray(json) ? json : (json.data || []);
+            const ancestors = rawData.map((a) => ({
+                id: a.id,
+                name: a.name || null,
+                itemType: normalizeItemType(a.itemType),
+            }));
+            return { ancestors };
+        }
+        catch (error) {
+            return { error: getErrorMessage(error) };
+        }
+    }
     /**
      * Find all assignments under a task (with pagination)
      */
@@ -209,11 +242,17 @@ export class LPClient {
      * Get assignments for a member with parent task names resolved
      *
      * This is a convenience method that fetches assignments and enriches
-     * them with parent task names using batch fetching (3 requests max instead of N+1).
+     * them with parent task names using batch fetching.
+     *
+     * Request counts:
+     * - Default: 2 requests (assignments + tasks)
+     * - includeProject: 3 requests (assignments + tasks + projects)
+     * - includeHierarchy: 1 + N requests (assignments + N ancestors calls)
      *
      * @param memberId - The member ID to get assignments for
      * @param options - Options for including additional context
      * @param options.includeProject - If true, also fetch grandparent project names
+     * @param options.includeHierarchy - If true, fetch full ancestry and build hierarchy path
      */
     async getMyAssignmentsWithContext(memberId, options) {
         // 1. Get raw assignments
@@ -222,38 +261,96 @@ export class LPClient {
             return { error };
         if (assignments.length === 0)
             return { assignments: [] };
-        // 2. Extract unique parent IDs (tasks)
-        const taskIds = [...new Set(assignments.map(a => a.parentId).filter((id) => id !== undefined))];
-        // 3. Batch fetch all parent tasks in a single request
-        const { items: tasks, error: taskError } = await this.getItems(taskIds);
-        if (taskError)
-            return { error: taskError };
-        const taskMap = new Map();
-        for (const task of tasks || []) {
-            taskMap.set(task.id, task);
-        }
-        // 4. Optionally batch fetch grandparent projects in a single request
+        // 2. Handle based on options
+        let taskMap = new Map();
         let projectMap = new Map();
-        if (options?.includeProject) {
-            const projectIds = [...new Set([...taskMap.values()].map(t => t.parentId).filter((id) => id !== undefined))];
-            const { items: projects, error: projectError } = await this.getItems(projectIds);
-            if (projectError)
-                return { error: projectError };
-            for (const project of projects || []) {
-                projectMap.set(project.id, project);
+        let ancestorMap = new Map();
+        if (options?.includeHierarchy) {
+            // Optimized path: fetch ancestors for assignments (includes task info)
+            // This avoids the separate task batch fetch since task is first ancestor
+            // Deduplicate by parentId - only one ancestors call per unique parent task
+            const assignmentsByParent = new Map();
+            for (const a of assignments) {
+                if (a.parentId && !assignmentsByParent.has(a.parentId)) {
+                    assignmentsByParent.set(a.parentId, a);
+                }
+            }
+            const ancestorResults = await Promise.all([...assignmentsByParent.entries()].map(async ([parentId, assignment]) => {
+                const { ancestors } = await this.getItemAncestors(assignment.id);
+                return { parentId, ancestors };
+            }));
+            for (const { parentId, ancestors } of ancestorResults) {
+                ancestorMap.set(parentId, ancestors);
+            }
+        }
+        else {
+            // Original path: batch fetch tasks first
+            const taskIds = [...new Set(assignments.map(a => a.parentId).filter((id) => id !== undefined))];
+            const { items: tasks, error: taskError } = await this.getItems(taskIds);
+            if (taskError)
+                return { error: taskError };
+            for (const task of tasks || []) {
+                taskMap.set(task.id, task);
+            }
+            if (options?.includeProject) {
+                // Also fetch grandparent projects
+                const projectIds = [...new Set([...taskMap.values()].map(t => t.parentId).filter((id) => id !== undefined))];
+                const { items: projects, error: projectError } = await this.getItems(projectIds);
+                if (projectError)
+                    return { error: projectError };
+                for (const project of projects || []) {
+                    projectMap.set(project.id, project);
+                }
             }
         }
-        // 5. Merge context into assignments
+        // 3. Merge context into assignments
         return {
             assignments: assignments.map(a => {
-                const task = a.parentId ? taskMap.get(a.parentId) : undefined;
-                const project = task?.parentId ? projectMap.get(task.parentId) : undefined;
-                return {
-                    ...a,
-                    taskName: task?.name ?? null,
-                    projectId: project?.id,
-                    projectName: project?.name ?? null,
-                };
+                const result = { ...a };
+                if (options?.includeHierarchy && a.parentId) {
+                    // Full hierarchy mode - extract task name from ancestors
+                    const ancestors = ancestorMap.get(a.parentId);
+                    result.ancestors = ancestors;
+                    if (ancestors && ancestors.length > 0) {
+                        // Extract task name from first Task ancestor
+                        const taskAncestor = ancestors.find(anc => anc.itemType === 'Task');
+                        result.taskName = taskAncestor?.name ?? null;
+                        // Build hierarchyPath from Project and Folder ancestors
+                        // Exclude system containers (Package, WorkspaceRoot) and Tasks
+                        const hierarchyAncestors = ancestors
+                            .filter(anc => anc.itemType === 'Project' || anc.itemType === 'Folder')
+                            .reverse(); // LP returns child→root, we want root→child
+                        if (hierarchyAncestors.length > 0) {
+                            result.hierarchyPath = hierarchyAncestors
+                                .map(anc => anc.name ?? `[${anc.id}]`)
+                                .join(' › ');
+                            // Set projectId/projectName from root (first in reversed array)
+                            result.projectId = hierarchyAncestors[0].id;
+                            result.projectName = hierarchyAncestors[0].name;
+                        }
+                        else {
+                            result.projectName = null;
+                        }
+                    }
+                    else {
+                        result.taskName = null;
+                        result.projectName = null;
+                    }
+                }
+                else {
+                    // Original path - use taskMap
+                    const task = a.parentId ? taskMap.get(a.parentId) : undefined;
+                    result.taskName = task?.name ?? null;
+                    if (options?.includeProject) {
+                        const project = task?.parentId ? projectMap.get(task.parentId) : undefined;
+                        result.projectId = project?.id;
+                        result.projectName = project?.name ?? null;
+                    }
+                    else {
+                        result.projectName = null;
+                    }
+                }
+                return result;
             }),
         };
     }

package/dist/index.d.ts

@@ -28,7 +28,7 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPItemType, LPItem, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, } from './types.js';
+export type { LPConfig, LPItemType, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, } from './types.js';
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
 export { LP_API_BASE } from './constants.js';

package/dist/types.d.ts

@@ -7,7 +7,20 @@
 /**
  * LiquidPlanner item types in the hierarchy
  */
-export type LPItemType = 'Task' | 'Assignment' | 'Folder' | 'Milestone' | 'Event';
+export type LPItemType = 'Task' | 'Assignment' | 'Folder' | 'Project' | 'Package' | 'WorkspaceRoot' | 'Milestone' | 'Event';
+/**
+ * An ancestor item in the hierarchy chain
+ *
+ * Returned by getItemAncestors() in order from root to immediate parent.
+ */
+export interface LPAncestor {
+    /** Unique identifier */
+    id: number;
+    /** Display name (null if not set) */
+    name: string | null;
+    /** Type of item in LP hierarchy */
+    itemType: LPItemType;
+}
 /**
  * An item from LiquidPlanner (Task, Assignment, Folder, etc.)
  */
@@ -166,4 +179,8 @@ export interface LPAssignmentWithContext extends LPItem {
     projectId?: number;
     /** Grandparent project name (null if not requested/found) */
     projectName?: string | null;
+    /** Full ancestry from root to parent task (undefined if not requested) */
+    ancestors?: LPAncestor[];
+    /** Formatted hierarchy path like "Project A › Subfolder B" (undefined if not requested) */
+    hierarchyPath?: string;
 }

package/dist/utils.js

@@ -80,12 +80,18 @@ export function normalizeItemType(apiItemType) {
         'tasks': 'Task',
         'assignments': 'Assignment',
         'folders': 'Folder',
+        'projects': 'Project',
+        'packages': 'Package',
+        'workspaceRoots': 'WorkspaceRoot',
         'milestones': 'Milestone',
         'events': 'Event',
         // Already-normalized values (for safety)
         'Task': 'Task',
         'Assignment': 'Assignment',
         'Folder': 'Folder',
+        'Project': 'Project',
+        'Package': 'Package',
+        'WorkspaceRoot': 'WorkspaceRoot',
         'Milestone': 'Milestone',
         'Event': 'Event',
     };

package/package.json

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