@markwharton/liquidplanner 1.2.0 → 1.3.0

package/dist/client.d.ts

@@ -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)
      */
@@ -87,7 +100,7 @@ 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 (3 requests max instead of N+1).
      *
      * @param memberId - The member ID to get assignments for
      * @param options - Options for including additional context

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)
      */
@@ -187,7 +209,7 @@ 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 (3 requests max instead of N+1).
      *
      * @param memberId - The member ID to get assignments for
      * @param options - Options for including additional context
@@ -202,21 +224,23 @@ export class LPClient {
             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)));
+        // 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 result of taskResults) {
-            if (result.item)
-                taskMap.set(result.item.id, result.item);
+        for (const task of tasks || []) {
+            taskMap.set(task.id, task);
         }
-        // 4. Optionally fetch grandparent projects
+        // 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 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);
+            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
@@ -226,8 +250,9 @@ export class LPClient {
                 const project = task?.parentId ? projectMap.get(task.parentId) : undefined;
                 return {
                     ...a,
-                    taskName: task?.name ?? '-',
-                    projectName: project?.name,
+                    taskName: task?.name ?? null,
+                    projectId: project?.id,
+                    projectName: project?.name ?? null,
                 };
             }),
         };

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

@@ -31,6 +31,6 @@ export { resolveTaskToAssignment } from './workflows.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
@@ -154,8 +160,10 @@ 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;
 }

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