@markwharton/liquidplanner 1.1.0 → 1.3.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 } from './types.js';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext } 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,18 @@ 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;
+    }>;
     /**
      * Find all assignments under a task (with pagination)
      */
@@ -83,6 +96,22 @@ export declare class LPClient {
         assignments?: LPItem[];
         error?: string;
     }>;
+    /**
+     * 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).
+     *
+     * @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
+     */
+    getMyAssignmentsWithContext(memberId: number, options?: {
+        includeProject?: boolean;
+    }): Promise<{
+        assignments?: LPAssignmentWithContext[];
+        error?: string;
+    }>;
     /**
      * Get all cost codes in the workspace (with pagination)
      */

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,25 @@ 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 };
+    }
     /**
      * Find all assignments under a task (with pagination)
      */
@@ -183,6 +205,58 @@ export class LPClient {
         });
         return error ? { error } : { assignments: results };
     }
+    /**
+     * 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).
+     *
+     * @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
+     */
+    async getMyAssignmentsWithContext(memberId, options) {
+        // 1. Get raw assignments
+        const { assignments, error } = await this.getMyAssignments(memberId);
+        if (error || !assignments)
+            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
+        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);
+            }
+        }
+        // 5. 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,
+                };
+            }),
+        };
+    }
     // ============================================================================
     // Cost Codes
     // ============================================================================

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, } from './types.js';
+export type { LPConfig, LPItemType, LPItem, 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

@@ -14,8 +14,8 @@ export type LPItemType = 'Task' | 'Assignment' | 'Folder' | 'Milestone' | 'Event
 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 +89,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
@@ -147,3 +153,17 @@ export interface LPUpsertOptions {
      */
     accumulate?: boolean;
 }
+/**
+ * Assignment with resolved parent context
+ *
+ * Extends LPItem with additional fields for the parent task name,
+ * grandparent project name, and cost code name.
+ */
+export interface LPAssignmentWithContext extends LPItem {
+    /** 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;
+}

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.1.0",
+  "version": "1.3.0",
   "description": "LiquidPlanner API client for timesheet integration",
   "type": "module",
   "main": "dist/index.js",