@markwharton/liquidplanner 1.2.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
  *
@@ -33,6 +33,7 @@ export declare class LPClient {
     private readonly apiToken;
     private readonly workspaceId;
     private readonly baseUrl;
+    private readonly onRequest?;
     constructor(config: LPConfig);
     /**
      * Make an authenticated request to the LP API
@@ -66,6 +67,30 @@ export declare class LPClient {
         item?: LPItem;
         error?: string;
     }>;
+    /**
+     * Get multiple items by ID in a single request (batch fetch)
+     *
+     * Uses the id[in] filter to fetch multiple items efficiently.
+     * This reduces N individual requests to a single paginated request.
+     *
+     * @param itemIds - Array of item IDs to fetch
+     */
+    getItems(itemIds: number[]): Promise<{
+        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)
      */
@@ -87,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 in a single call (batched internally).
+     * 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

@@ -8,12 +8,12 @@
  */
 import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, } from './utils.js';
 import { parseLPErrorResponse, getErrorMessage } from './errors.js';
-import { LP_API_BASE, DEFAULT_ITEM_NAME } from './constants.js';
+import { LP_API_BASE } from './constants.js';
 /** Transform raw API item to LPItem */
 function transformItem(raw) {
     return {
         id: raw.id,
-        name: raw.name || DEFAULT_ITEM_NAME,
+        name: raw.name || null,
         itemType: normalizeItemType(raw.itemType),
         parentId: raw.parentId,
         costCodeId: raw.costCodeId,
@@ -47,12 +47,15 @@ export class LPClient {
         this.apiToken = config.apiToken;
         this.workspaceId = config.workspaceId;
         this.baseUrl = config.baseUrl ?? LP_API_BASE;
+        this.onRequest = config.onRequest;
     }
     /**
      * Make an authenticated request to the LP API
      */
     async fetch(url, options = {}) {
-        const { method = 'GET', body } = options;
+        const { method = 'GET', body, description } = options;
+        // Notify listener of request (for debugging)
+        this.onRequest?.({ method, url, description });
         return fetch(url, {
             method,
             headers: {
@@ -114,7 +117,7 @@ export class LPClient {
      * Get all members in the workspace (with pagination)
      */
     async getWorkspaceMembers() {
-        const baseUrl = `${this.baseUrl}/users/v1?${filterIs('workspaceId', this.workspaceId)}`;
+        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/users/v1`;
         const { results, error } = await paginatedFetch({
             fetchFn: (url) => this.fetch(url),
             baseUrl,
@@ -154,6 +157,58 @@ export class LPClient {
             return { error: getErrorMessage(error) };
         }
     }
+    /**
+     * Get multiple items by ID in a single request (batch fetch)
+     *
+     * Uses the id[in] filter to fetch multiple items efficiently.
+     * This reduces N individual requests to a single paginated request.
+     *
+     * @param itemIds - Array of item IDs to fetch
+     */
+    async getItems(itemIds) {
+        if (itemIds.length === 0)
+            return { items: [] };
+        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIn('id', itemIds)}`;
+        const { results, error } = await paginatedFetch({
+            fetchFn: (url) => this.fetch(url),
+            baseUrl,
+            transform: (data) => data.map(transformItem),
+        });
+        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)
      */
@@ -187,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 in a single call (batched internally).
+     * 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
@@ -200,35 +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
-        const taskResults = await Promise.all(taskIds.map(id => this.getItem(id)));
-        const taskMap = new Map();
-        for (const result of taskResults) {
-            if (result.item)
-                taskMap.set(result.item.id, result.item);
-        }
-        // 4. Optionally fetch grandparent projects
+        // 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 projectResults = await Promise.all(projectIds.map(id => this.getItem(id)));
-            for (const result of projectResults) {
-                if (result.item)
-                    projectMap.set(result.item.id, result.item);
+        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 ?? '-',
-                    projectName: project?.name,
-                };
+                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/constants.d.ts

@@ -5,7 +5,3 @@
  */
 /** Default LP API base URL */
 export declare const LP_API_BASE = "https://next.liquidplanner.com/api";
-/** Default name for items when not available */
-export declare const DEFAULT_ITEM_NAME = "-";
-/** Default name for assignments when not available */
-export declare const DEFAULT_ASSIGNMENT_NAME = "-";

package/dist/constants.js

@@ -5,7 +5,3 @@
  */
 /** Default LP API base URL */
 export const LP_API_BASE = 'https://next.liquidplanner.com/api';
-/** Default name for items when not available */
-export const DEFAULT_ITEM_NAME = '-';
-/** Default name for assignments when not available */
-export const DEFAULT_ASSIGNMENT_NAME = '-';

package/dist/index.d.ts

@@ -28,9 +28,9 @@
  */
 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, DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME, } from './constants.js';
+export { LP_API_BASE } from './constants.js';
 export { LPError, parseLPErrorResponse, getErrorMessage } from './errors.js';
 export type { LPParsedError } from './errors.js';

package/dist/index.js

@@ -33,6 +33,6 @@ export { resolveTaskToAssignment } from './workflows.js';
 // Utilities
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
 // Constants
-export { LP_API_BASE, DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME, } from './constants.js';
+export { LP_API_BASE } from './constants.js';
 // Errors
 export { LPError, parseLPErrorResponse, getErrorMessage } from './errors.js';

package/dist/types.d.ts

@@ -7,15 +7,28 @@
 /**
  * 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.)
  */
 export interface LPItem {
     /** Unique identifier */
     id: number;
-    /** Display name */
-    name: string;
+    /** Display name (null if not set) */
+    name: string | null;
     /** Type of item in LP hierarchy */
     itemType: LPItemType;
     /** Parent item ID (e.g., Assignment's parent is a Task) */
@@ -89,6 +102,12 @@ export interface LPConfig {
     apiToken: string;
     /** Base URL for LP API (defaults to https://next.liquidplanner.com/api) */
     baseUrl?: string;
+    /** Optional callback invoked on each API request (for debugging/logging) */
+    onRequest?: (info: {
+        method: string;
+        url: string;
+        description?: string;
+    }) => void;
 }
 /**
  * Result of a timesheet sync operation
@@ -154,8 +173,14 @@ export interface LPUpsertOptions {
  * grandparent project name, and cost code name.
  */
 export interface LPAssignmentWithContext extends LPItem {
-    /** Parent task name */
-    taskName?: string;
-    /** Grandparent project name (if requested) */
-    projectName?: string;
+    /** Parent task name (null if not found) */
+    taskName?: string | null;
+    /** Grandparent project ID (undefined if not requested/found) */
+    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/dist/workflows.js

@@ -4,7 +4,6 @@
  * Higher-level functions that combine multiple API calls to accomplish
  * common tasks, like resolving a Task ID to the correct Assignment ID.
  */
-import { DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME } from './constants.js';
 /**
  * Resolve an item ID to the correct Assignment ID for logging time
  *
@@ -41,7 +40,7 @@ export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
     const { item, error: fetchError } = await client.getItem(itemId);
     if (fetchError || !item) {
         return {
-            inputItem: { id: itemId, name: DEFAULT_ITEM_NAME, itemType: 'Task' },
+            inputItem: { id: itemId, name: null, itemType: 'Task' },
             assignmentId: 0,
             error: fetchError || 'Item not found',
         };
@@ -53,7 +52,7 @@ export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
             return {
                 inputItem: item,
                 assignmentId: item.id,
-                assignmentName: item.name || DEFAULT_ASSIGNMENT_NAME,
+                assignmentName: item.name ?? undefined,
                 assignmentUserId: item.userId,
             };
         case 'Task': {
@@ -78,7 +77,7 @@ export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
                 return {
                     inputItem: item,
                     assignmentId: assignments[0].id,
-                    assignmentName: assignments[0].name || DEFAULT_ASSIGNMENT_NAME,
+                    assignmentName: assignments[0].name ?? undefined,
                     assignmentUserId: assignments[0].userId,
                 };
             }
@@ -90,7 +89,7 @@ export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
                     return {
                         inputItem: item,
                         assignmentId: myAssignments[0].id,
-                        assignmentName: myAssignments[0].name || DEFAULT_ASSIGNMENT_NAME,
+                        assignmentName: myAssignments[0].name ?? undefined,
                         assignmentUserId: myAssignments[0].userId,
                     };
                 }

package/package.json

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