@markwharton/liquidplanner 1.5.0 → 1.6.1

package/dist/cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple in-memory TTL cache
+ *
+ * Provides per-instance memoization for LPClient API responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export declare class TTLCache {
+    private store;
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    get<T>(key: string, ttlMs: number, factory: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate cache entries matching a key prefix.
+     *
+     * Example: invalidate('timesheet:') clears all timesheet entries.
+     */
+    invalidate(prefix: string): void;
+    /**
+     * Clear all cached data.
+     */
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,50 @@
+/**
+ * Simple in-memory TTL cache
+ *
+ * Provides per-instance memoization for LPClient API responses.
+ * In serverless environments (Azure Functions, Static Web Apps),
+ * module-level state persists across warm invocations within the
+ * same instance — this cache leverages that behavior.
+ *
+ * Not a distributed cache: each instance has its own cache.
+ * Cold starts and instance recycling naturally clear stale data.
+ */
+export class TTLCache {
+    constructor() {
+        this.store = new Map();
+    }
+    /**
+     * Get a cached value, or call the factory to populate it.
+     *
+     * @param key - Cache key
+     * @param ttlMs - Time-to-live in milliseconds
+     * @param factory - Async function to produce the value on cache miss
+     */
+    async get(key, ttlMs, factory) {
+        const existing = this.store.get(key);
+        if (existing && existing.expiresAt > Date.now()) {
+            return existing.data;
+        }
+        const data = await factory();
+        this.store.set(key, { data, expiresAt: Date.now() + ttlMs });
+        return data;
+    }
+    /**
+     * Invalidate cache entries matching a key prefix.
+     *
+     * Example: invalidate('timesheet:') clears all timesheet entries.
+     */
+    invalidate(prefix) {
+        for (const key of this.store.keys()) {
+            if (key.startsWith(prefix)) {
+                this.store.delete(key);
+            }
+        }
+    }
+    /**
+     * Clear all cached data.
+     */
+    clear() {
+        this.store.clear();
+    }
+}

package/dist/client.d.ts

@@ -34,7 +34,24 @@ export declare class LPClient {
     private readonly workspaceId;
     private readonly baseUrl;
     private readonly onRequest?;
+    private readonly cache?;
+    private readonly cacheTtl;
     constructor(config: LPConfig);
+    /**
+     * Route through cache if enabled, otherwise call factory directly.
+     */
+    private cached;
+    /**
+     * Clear all cached API responses.
+     * Useful after external changes that the cache wouldn't know about.
+     */
+    clearCache(): void;
+    /**
+     * Invalidate cached timesheet entries only.
+     * Use when an external event (e.g., SignalR broadcast) indicates timesheet
+     * data changed but the write didn't go through this client instance.
+     */
+    invalidateTimesheetCache(): void;
     /**
      * Make an authenticated request to the LP API
      */
@@ -146,17 +163,20 @@ export declare class LPClient {
      */
     createTimesheetEntry(entry: LPTimesheetEntry): Promise<LPSyncResult>;
     /**
-     * Get timesheet entries for a specific date
+     * Get timesheet entries for one or more dates
      *
      * Uses the Logged Time Entries API to query existing entries.
-     * GET /api/workspaces/{workspaceId}/logged-time-entries/v1?date[in]=["{date}"]&itemId[is]="{itemId}"
+     * Supports both single date and multi-date queries using LP's date[in] filter.
+     *
+     * Multi-date queries reduce API calls — e.g., fetching a full week's entries
+     * in a single request instead of 7 separate calls.
      *
      * @see https://api-docs.liquidplanner.com/docs/task-status-1
      *
-     * @param date - Date in YYYY-MM-DD format
+     * @param date - Date(s) in YYYY-MM-DD format (string or array)
      * @param itemId - Optional item ID to filter by
      */
-    getTimesheetEntries(date: string, itemId?: number): Promise<{
+    getTimesheetEntries(date: string | string[], itemId?: number): Promise<{
         entries?: LPTimesheetEntryWithId[];
         error?: LPErrorInfo;
     }>;

package/dist/client.js

@@ -9,6 +9,7 @@
 import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, } from './utils.js';
 import { parseLPErrorResponse, getErrorMessage } from './errors.js';
 import { LP_API_BASE } from './constants.js';
+import { TTLCache } from './cache.js';
 /** Transform raw API item to LPItem */
 function transformItem(raw) {
     return {
@@ -48,6 +49,41 @@ export class LPClient {
         this.workspaceId = config.workspaceId;
         this.baseUrl = config.baseUrl ?? LP_API_BASE;
         this.onRequest = config.onRequest;
+        // Initialize cache if configured
+        if (config.cache) {
+            this.cache = new TTLCache();
+        }
+        this.cacheTtl = {
+            membersTtl: config.cache?.membersTtl ?? 300000,
+            costCodesTtl: config.cache?.costCodesTtl ?? 300000,
+            timesheetTtl: config.cache?.timesheetTtl ?? 60000,
+            assignmentsTtl: config.cache?.assignmentsTtl ?? 120000,
+            itemsTtl: config.cache?.itemsTtl ?? 300000,
+        };
+    }
+    /**
+     * Route through cache if enabled, otherwise call factory directly.
+     */
+    async cached(key, ttlMs, factory) {
+        if (this.cache) {
+            return this.cache.get(key, ttlMs, factory);
+        }
+        return factory();
+    }
+    /**
+     * Clear all cached API responses.
+     * Useful after external changes that the cache wouldn't know about.
+     */
+    clearCache() {
+        this.cache?.clear();
+    }
+    /**
+     * Invalidate cached timesheet entries only.
+     * Use when an external event (e.g., SignalR broadcast) indicates timesheet
+     * data changed but the write didn't go through this client instance.
+     */
+    invalidateTimesheetCache() {
+        this.cache?.invalidate('timesheet:');
     }
     /**
      * Make an authenticated request to the LP API
@@ -117,20 +153,22 @@ export class LPClient {
      * Get all members in the workspace (with pagination)
      */
     async getWorkspaceMembers() {
-        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/users/v1`;
-        const { results, error } = await paginatedFetch({
-            fetchFn: (url) => this.fetch(url),
-            baseUrl,
-            transform: (data) => data.map(m => ({
-                id: m.id,
-                username: m.username,
-                email: m.email,
-                firstName: m.firstName,
-                lastName: m.lastName,
-                userType: m.userType,
-            })),
+        return this.cached('members', this.cacheTtl.membersTtl, async () => {
+            const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/users/v1`;
+            const { results, error } = await paginatedFetch({
+                fetchFn: (url) => this.fetch(url),
+                baseUrl,
+                transform: (data) => data.map(m => ({
+                    id: m.id,
+                    username: m.username,
+                    email: m.email,
+                    firstName: m.firstName,
+                    lastName: m.lastName,
+                    userType: m.userType,
+                })),
+            });
+            return error ? { error } : { members: results };
         });
-        return error ? { error } : { members: results };
     }
     // ============================================================================
     // Items
@@ -139,23 +177,25 @@ export class LPClient {
      * Get a single item by ID
      */
     async getItem(itemId) {
-        const url = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIs('id', itemId)}`;
-        try {
-            const response = await this.fetch(url);
-            if (!response.ok) {
-                const errorText = await response.text();
-                const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
-                return { error: { message, statusCode: response.status, isDuplicate } };
+        return this.cached(`item:${itemId}`, this.cacheTtl.itemsTtl, async () => {
+            const url = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIs('id', itemId)}`;
+            try {
+                const response = await this.fetch(url);
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
+                    return { error: { message, statusCode: response.status, isDuplicate } };
+                }
+                const result = await response.json();
+                if (!result.data || result.data.length === 0) {
+                    return { error: { message: `Item ${itemId} not found`, statusCode: 404 } };
+                }
+                return { item: transformItem(result.data[0]) };
             }
-            const result = await response.json();
-            if (!result.data || result.data.length === 0) {
-                return { error: { message: `Item ${itemId} not found`, statusCode: 404 } };
+            catch (error) {
+                return { error: { message: getErrorMessage(error), statusCode: 0 } };
             }
-            return { item: transformItem(result.data[0]) };
-        }
-        catch (error) {
-            return { error: { message: getErrorMessage(error), statusCode: 0 } };
-        }
+        });
     }
     /**
      * Get multiple items by ID in a single request (batch fetch)
@@ -185,29 +225,31 @@ export class LPClient {
      * @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, isDuplicate } = parseLPErrorResponse(errorText, response.status);
-                return { error: { message, statusCode: response.status, isDuplicate } };
+        return this.cached(`ancestors:${itemId}`, this.cacheTtl.itemsTtl, async () => {
+            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, isDuplicate } = parseLPErrorResponse(errorText, response.status);
+                    return { error: { message, statusCode: response.status, isDuplicate } };
+                }
+                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 };
             }
-            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: { message: getErrorMessage(error), statusCode: 0 } };
-        }
+            catch (error) {
+                return { error: { message: getErrorMessage(error), statusCode: 0 } };
+            }
+        });
     }
     /**
      * Find all assignments under a task (with pagination)
@@ -229,14 +271,16 @@ export class LPClient {
      * Note: userId is not a supported filter field in the LP API, so we filter client-side.
      */
     async getMyAssignments(memberId) {
-        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIs('itemType', 'assignments')}`;
-        const { results, error } = await paginatedFetch({
-            fetchFn: (url) => this.fetch(url),
-            baseUrl,
-            filter: (data) => data.filter(item => item.userId === memberId),
-            transform: (data) => data.map(transformItem),
+        return this.cached(`assignments:${memberId}`, this.cacheTtl.assignmentsTtl, async () => {
+            const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIs('itemType', 'assignments')}`;
+            const { results, error } = await paginatedFetch({
+                fetchFn: (url) => this.fetch(url),
+                baseUrl,
+                filter: (data) => data.filter(item => item.userId === memberId),
+                transform: (data) => data.map(transformItem),
+            });
+            return error ? { error } : { assignments: results };
         });
-        return error ? { error } : { assignments: results };
     }
     /**
      * Get assignments for a member with parent task names resolved
@@ -365,17 +409,19 @@ export class LPClient {
      * Get all cost codes in the workspace (with pagination)
      */
     async getCostCodes() {
-        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/cost-codes/v1`;
-        const { results, error } = await paginatedFetch({
-            fetchFn: (url) => this.fetch(url),
-            baseUrl,
-            transform: (data) => data.map(cc => ({
-                id: cc.id,
-                name: cc.name,
-                billable: cc.billable,
-            })),
+        return this.cached('costcodes', this.cacheTtl.costCodesTtl, async () => {
+            const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/cost-codes/v1`;
+            const { results, error } = await paginatedFetch({
+                fetchFn: (url) => this.fetch(url),
+                baseUrl,
+                transform: (data) => data.map(cc => ({
+                    id: cc.id,
+                    name: cc.name,
+                    billable: cc.billable,
+                })),
+            });
+            return error ? { error } : { costCodes: results };
         });
-        return error ? { error } : { costCodes: results };
     }
     // ============================================================================
     // Timesheet
@@ -410,6 +456,8 @@ export class LPClient {
                 const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
                 return { success: false, error: message, statusCode: response.status, isDuplicate };
             }
+            // Invalidate cached timesheet entries for this date
+            this.cache?.invalidate(`timesheet:`);
             const result = await response.json();
             return { success: true, entryId: result.id };
         }
@@ -418,37 +466,45 @@ export class LPClient {
         }
     }
     /**
-     * Get timesheet entries for a specific date
+     * Get timesheet entries for one or more dates
      *
      * Uses the Logged Time Entries API to query existing entries.
-     * GET /api/workspaces/{workspaceId}/logged-time-entries/v1?date[in]=["{date}"]&itemId[is]="{itemId}"
+     * Supports both single date and multi-date queries using LP's date[in] filter.
+     *
+     * Multi-date queries reduce API calls — e.g., fetching a full week's entries
+     * in a single request instead of 7 separate calls.
      *
      * @see https://api-docs.liquidplanner.com/docs/task-status-1
      *
-     * @param date - Date in YYYY-MM-DD format
+     * @param date - Date(s) in YYYY-MM-DD format (string or array)
      * @param itemId - Optional item ID to filter by
      */
     async getTimesheetEntries(date, itemId) {
-        // Build query with date[in] filter (date field uses [in] operator with array)
-        let baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/logged-time-entries/v1?${filterIn('date', [date])}`;
-        // Optional filter by itemId
-        if (itemId) {
-            baseUrl += `&${filterIs('itemId', itemId)}`;
-        }
-        const { results, error } = await paginatedFetch({
-            fetchFn: (url) => this.fetch(url),
-            baseUrl,
-            transform: (data) => data.map(entry => ({
-                id: entry.id,
-                date: entry.date,
-                itemId: entry.itemId,
-                hours: entry.loggedEntriesInMinutes / 60,
-                costCodeId: entry.costCodeId,
-                note: entry.note,
-                userId: entry.userId,
-            })),
+        const dates = Array.isArray(date) ? date : [date];
+        const sortedKey = [...dates].sort().join(',');
+        const cacheKey = itemId ? `timesheet:${sortedKey}:${itemId}` : `timesheet:${sortedKey}`;
+        return this.cached(cacheKey, this.cacheTtl.timesheetTtl, async () => {
+            // Build query with date[in] filter (supports multiple dates)
+            let baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/logged-time-entries/v1?${filterIn('date', dates)}`;
+            // Optional filter by itemId
+            if (itemId) {
+                baseUrl += `&${filterIs('itemId', itemId)}`;
+            }
+            const { results, error } = await paginatedFetch({
+                fetchFn: (url) => this.fetch(url),
+                baseUrl,
+                transform: (data) => data.map(entry => ({
+                    id: entry.id,
+                    date: entry.date,
+                    itemId: entry.itemId,
+                    hours: entry.loggedEntriesInMinutes / 60,
+                    costCodeId: entry.costCodeId,
+                    note: entry.note,
+                    userId: entry.userId,
+                })),
+            });
+            return error ? { error } : { entries: results };
         });
-        return error ? { error } : { entries: results };
     }
     /**
      * Update an existing timesheet entry
@@ -490,6 +546,8 @@ export class LPClient {
                 const { message } = parseLPErrorResponse(errorText, response.status);
                 return { success: false, error: message, statusCode: response.status };
             }
+            // Invalidate cached timesheet entries
+            this.cache?.invalidate(`timesheet:`);
             return { success: true, entryId };
         }
         catch (error) {

package/dist/index.d.ts

@@ -28,7 +28,7 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPItemType, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, LPErrorInfo, } from './types.js';
+export type { LPConfig, LPCacheConfig, LPItemType, 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 { PaginateOptions } from './utils.js';
 export { LP_API_BASE } from './constants.js';

package/dist/types.d.ts

@@ -92,6 +92,29 @@ export interface LPTaskResolution {
     /** Error message if resolution failed */
     error?: string;
 }
+/**
+ * Cache configuration for LPClient
+ *
+ * When provided to LPConfig, enables in-memory TTL caching of API responses.
+ * All TTL values are in milliseconds. Omit individual TTLs to use defaults.
+ *
+ * Caching uses a simple in-memory Map that persists across warm invocations
+ * in serverless environments (Azure Functions, Static Web Apps). Each instance
+ * has its own independent cache — this is per-instance memoization, not a
+ * distributed cache. Cold starts and instance recycling naturally clear data.
+ */
+export interface LPCacheConfig {
+    /** TTL for workspace members (default: 300000 = 5 min) */
+    membersTtl?: number;
+    /** TTL for cost codes (default: 300000 = 5 min) */
+    costCodesTtl?: number;
+    /** TTL for timesheet entries (default: 60000 = 60s) */
+    timesheetTtl?: number;
+    /** TTL for user assignments (default: 120000 = 2 min) */
+    assignmentsTtl?: number;
+    /** TTL for items and ancestors (default: 300000 = 5 min) */
+    itemsTtl?: number;
+}
 /**
  * LiquidPlanner configuration for API access
  */
@@ -108,6 +131,8 @@ export interface LPConfig {
         url: string;
         description?: string;
     }) => void;
+    /** Enable caching with optional TTL overrides. Omit to disable caching. */
+    cache?: LPCacheConfig;
 }
 /**
  * Result of a timesheet sync operation

package/package.json

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