@markwharton/liquidplanner 1.7.0 → 1.8.0

package/dist/client.d.ts

@@ -36,6 +36,7 @@ export declare class LPClient {
     private readonly onRequest?;
     private readonly cache?;
     private readonly cacheTtl;
+    private readonly retryConfig?;
     constructor(config: LPConfig);
     /**
      * Route through cache if enabled, otherwise call factory directly.
@@ -54,6 +55,10 @@ export declare class LPClient {
     invalidateTimesheetCache(): void;
     /**
      * Make an authenticated request to the LP API
+     *
+     * When retry is configured, automatically retries on HTTP 429 (Too Many Requests)
+     * and 503 (Service Unavailable) with exponential backoff.
+     * Respects the Retry-After header when present.
      */
     private fetch;
     /**
@@ -99,7 +104,7 @@ export declare class LPClient {
     /**
      * Get the ancestry chain for an item
      *
-     * Returns ancestors from root to immediate parent (excludes the item itself).
+     * Returns ancestors from root to immediate parent (root→child order, excludes the item itself).
      * Uses the items/{itemId}/ancestors endpoint.
      *
      * @param itemId - The item ID to get ancestors for

package/dist/client.js

@@ -6,7 +6,7 @@
  *
  * @see https://api-docs.liquidplanner.com/
  */
-import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, } from './utils.js';
+import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, batchMap, } from './utils.js';
 import { parseLPErrorResponse, getErrorMessage } from './errors.js';
 import { LP_API_BASE } from './constants.js';
 import { TTLCache } from './cache.js';
@@ -60,6 +60,14 @@ export class LPClient {
             assignmentsTtl: config.cache?.assignmentsTtl ?? 120000,
             itemsTtl: config.cache?.itemsTtl ?? 300000,
         };
+        // Initialize retry config with defaults if provided
+        if (config.retry) {
+            this.retryConfig = {
+                maxRetries: config.retry.maxRetries ?? 3,
+                initialDelayMs: config.retry.initialDelayMs ?? 1000,
+                maxDelayMs: config.retry.maxDelayMs ?? 10000,
+            };
+        }
     }
     /**
      * Route through cache if enabled, otherwise call factory directly.
@@ -87,19 +95,56 @@ export class LPClient {
     }
     /**
      * Make an authenticated request to the LP API
+     *
+     * When retry is configured, automatically retries on HTTP 429 (Too Many Requests)
+     * and 503 (Service Unavailable) with exponential backoff.
+     * Respects the Retry-After header when present.
      */
     async fetch(url, options = {}) {
         const { method = 'GET', body, description } = options;
         // Notify listener of request (for debugging)
         this.onRequest?.({ method, url, description });
-        return fetch(url, {
-            method,
-            headers: {
-                Authorization: buildAuthHeader(this.apiToken),
-                'Content-Type': 'application/json',
-            },
-            body: body ? JSON.stringify(body) : undefined,
-        });
+        const maxAttempts = this.retryConfig ? 1 + this.retryConfig.maxRetries : 1;
+        let lastResponse;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            lastResponse = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: buildAuthHeader(this.apiToken),
+                    'Content-Type': 'application/json',
+                },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            // Check if this is a retryable status
+            if (this.retryConfig && (lastResponse.status === 429 || lastResponse.status === 503)) {
+                if (attempt >= this.retryConfig.maxRetries) {
+                    return lastResponse; // Exhausted retries
+                }
+                // Calculate delay: respect Retry-After header, or use exponential backoff
+                let delayMs;
+                const retryAfterHeader = lastResponse.headers.get('Retry-After');
+                if (retryAfterHeader) {
+                    const retryAfterSeconds = parseInt(retryAfterHeader, 10);
+                    delayMs = Number.isFinite(retryAfterSeconds)
+                        ? retryAfterSeconds * 1000
+                        : this.retryConfig.initialDelayMs * Math.pow(2, attempt);
+                }
+                else {
+                    delayMs = this.retryConfig.initialDelayMs * Math.pow(2, attempt);
+                }
+                delayMs = Math.min(delayMs, this.retryConfig.maxDelayMs);
+                // Notify listener of retry (for debugging)
+                this.onRequest?.({
+                    method,
+                    url,
+                    description: `Retry ${attempt + 1}/${this.retryConfig.maxRetries} after ${delayMs}ms (HTTP ${lastResponse.status})`,
+                });
+                await new Promise(resolve => setTimeout(resolve, delayMs));
+                continue;
+            }
+            return lastResponse;
+        }
+        return lastResponse;
     }
     // ============================================================================
     // Workspace & Validation
@@ -219,7 +264,7 @@ export class LPClient {
     /**
      * Get the ancestry chain for an item
      *
-     * Returns ancestors from root to immediate parent (excludes the item itself).
+     * Returns ancestors from root to immediate parent (root→child order, excludes the item itself).
      * Uses the items/{itemId}/ancestors endpoint.
      *
      * @param itemId - The item ID to get ancestors for
@@ -243,7 +288,7 @@ export class LPClient {
                     id: a.id,
                     name: a.name || null,
                     itemType: normalizeItemType(a.itemType),
-                }));
+                })).reverse(); // LP API returns child→root, normalize to root→child
                 return { ancestors };
             }
             catch (error) {
@@ -319,10 +364,11 @@ export class LPClient {
                     assignmentsByParent.set(a.parentId, a);
                 }
             }
-            const ancestorResults = await Promise.all([...assignmentsByParent.entries()].map(async ([parentId, assignment]) => {
+            const parentEntries = [...assignmentsByParent.entries()];
+            const ancestorResults = await batchMap(parentEntries, 5, async ([parentId, assignment]) => {
                 const { ancestors, error } = await this.getItemAncestors(assignment.id);
                 return { parentId, ancestors, error };
-            }));
+            });
             const firstError = ancestorResults.find(r => r.error);
             if (firstError) {
                 return { error: firstError.error };
@@ -366,8 +412,7 @@ export class LPClient {
                         // 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
+                            .filter(anc => anc.itemType === 'Project' || anc.itemType === 'Folder');
                         if (hierarchyAncestors.length > 0) {
                             result.hierarchyPath = hierarchyAncestors
                                 .map(anc => anc.name ?? `[${anc.id}]`)

package/dist/index.d.ts

@@ -28,8 +28,8 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPCacheConfig, 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, } from './types.js';
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, batchMap, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
 export { LP_API_BASE } from './constants.js';
 export { LPError, parseLPErrorResponse, getErrorMessage } from './errors.js';

package/dist/index.js

@@ -31,7 +31,7 @@ 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, filterIn, paginatedFetch, batchMap, } from './utils.js';
 // Constants
 export { LP_API_BASE } from './constants.js';
 // Errors

package/dist/types.d.ts

@@ -129,6 +129,21 @@ export interface LPCacheConfig {
     /** TTL for items and ancestors (default: 300000 = 5 min) */
     itemsTtl?: number;
 }
+/**
+ * Retry configuration for LPClient
+ *
+ * Controls automatic retry behavior for transient failures
+ * (HTTP 429 Too Many Requests, 503 Service Unavailable).
+ * Uses exponential backoff with optional Retry-After header support.
+ */
+export interface LPRetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelayMs?: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelayMs?: number;
+}
 /**
  * LiquidPlanner configuration for API access
  */
@@ -147,6 +162,8 @@ export interface LPConfig {
     }) => void;
     /** Enable caching with optional TTL overrides. Omit to disable caching. */
     cache?: LPCacheConfig;
+    /** Retry configuration for transient failures (429, 503). Omit to disable retry. */
+    retry?: LPRetryConfig;
 }
 /**
  * Result of a timesheet sync operation

package/dist/utils.d.ts

@@ -54,3 +54,16 @@ export declare function normalizeItemType(apiItemType: string): LPItemType;
  * Build the Authorization header for LP API requests
  */
 export declare function buildAuthHeader(apiToken: string): string;
+/**
+ * Map over items with bounded concurrency
+ *
+ * Processes items in batches of `concurrency`, waiting for each batch
+ * to complete before starting the next. This prevents overwhelming
+ * APIs with too many simultaneous requests.
+ *
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent operations
+ * @param fn - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ */
+export declare function batchMap<T, R>(items: T[], concurrency: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/utils.js

@@ -104,3 +104,27 @@ export function normalizeItemType(apiItemType) {
 export function buildAuthHeader(apiToken) {
     return `Bearer ${apiToken}`;
 }
+// ============================================================================
+// Concurrency Helper
+// ============================================================================
+/**
+ * Map over items with bounded concurrency
+ *
+ * Processes items in batches of `concurrency`, waiting for each batch
+ * to complete before starting the next. This prevents overwhelming
+ * APIs with too many simultaneous requests.
+ *
+ * @param items - Array of items to process
+ * @param concurrency - Maximum number of concurrent operations
+ * @param fn - Async function to apply to each item
+ * @returns Array of results in the same order as input items
+ */
+export async function batchMap(items, concurrency, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += concurrency) {
+        const batch = items.slice(i, i + concurrency);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}

package/package.json

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