@markwharton/liquidplanner 2.4.0 → 2.5.0

package/README.md

@@ -44,7 +44,7 @@ await client.createTimesheetEntry({
 
 // Query existing entries for a date
 const tsResult = await client.getTimesheetEntries('2026-01-29', assignmentId);
-if (tsResult.ok) console.log(tsResult.data); // LPTimesheetEntryWithId[]
+if (tsResult.ok) console.log(tsResult.data); // LPTimesheetEntry[]
 
 // Update an existing entry (accumulate hours)
 const existing = tsResult.data![0];
@@ -98,25 +98,7 @@ const lateTasks = findInTree(tree, item => item.late === true);
 
 ## Result Pattern
 
-All methods return `Result<T>` objects rather than throwing exceptions. Always check `ok` before accessing `data`:
-
-```typescript
-interface Result<T> {
-  ok: boolean;
-  data?: T;       // present when ok is true
-  error?: string;  // present when ok is false
-  status?: number; // HTTP status code on error
-}
-```
-
-```typescript
-const result = await client.getAssignments(memberId);
-if (!result.ok) {
-  console.error(result.error, result.status);
-  return;
-}
-const { assignments, treeItemCount } = result.data;
-```
+All methods return `Result<T>` — see [api-core Result Pattern](../../README.md#result-pattern). Always check `ok` before accessing `data`.
 
 ## API Reference
 
@@ -133,11 +115,16 @@ const { assignments, treeItemCount } = result.data;
 | `getChildren(parentId, options?)` | `number, { itemType? }?` | `Result<LPItem[]>` |
 | `getWorkspaceTree()` | — | `Result<LPWorkspaceTree>` |
 | `getAssignments(memberId)` | `number` | `Result<{ assignments: LPAssignment[], treeItemCount: number }>` |
+| `clearCache()` | — | `void` |
+| `invalidateTimesheetCache()` | — | `void` |
 | `invalidateTreeCache()` | — | `void` |
+| `invalidateMemberCache()` | — | `void` |
+| `invalidateItemCache()` | — | `void` |
+| `invalidateCostCodeCache()` | — | `void` |
 | `getCostCodes()` | — | `Result<LPCostCode[]>` |
 | `createTimesheetEntry(entry)` | `LPTimesheetEntry` | `LPSyncResult` |
-| `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `Result<LPTimesheetEntryWithId[]>` |
-| `updateTimesheetEntry(entryId, existing, updates)` | `number, LPTimesheetEntryWithId, Partial<LPTimesheetEntry>` | `LPSyncResult` |
+| `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `Result<LPTimesheetEntry[]>` |
+| `updateTimesheetEntry(entryId, existing, updates)` | `number, LPTimesheetEntry, Partial<LPTimesheetEntry>` | `LPSyncResult` |
 | `upsertTimesheetEntry(entry, options?)` | `LPTimesheetEntry, LPUpsertOptions?` | `LPSyncResult` |
 
 ### Workflow: `resolveTaskToAssignment`
@@ -203,7 +190,7 @@ const client = new LPClient({
 | Items / ancestors | 5 min |
 | Timesheet entries | 60s |
 
-Write operations (`createTimesheetEntry`, `updateTimesheetEntry`) automatically invalidate timesheet cache entries. Call `client.invalidateTreeCache()` to refresh the workspace tree, or `client.clearCache()` to clear all cached data.
+Write operations (`createTimesheetEntry`, `updateTimesheetEntry`) automatically invalidate timesheet cache entries. Use focused invalidation methods (`invalidateTreeCache`, `invalidateMemberCache`, `invalidateItemCache`, `invalidateTimesheetCache`, `invalidateCostCodeCache`) to refresh specific data, or `clearCache()` to clear everything.
 
 Failed API results (`ok: false`) are never cached — transient errors won't persist for the full TTL. See the [root README Cache System section](../../README.md#cache-system) for the full cache architecture (layered stores, restricted data handling, request coalescing).
 

package/dist/client.d.ts

@@ -7,7 +7,7 @@
  * @see https://api-docs.liquidplanner.com/
  */
 import type { Result } from '@markwharton/api-core';
-import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignment, LPAncestor, LPFindItemsOptions, LPWorkspaceTree } from './types.js';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPUpsertOptions, LPAssignment, LPAncestor, LPFindItemsOptions, LPWorkspaceTree } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -39,11 +39,7 @@ export declare class LPClient {
     private readonly cacheTtl;
     private readonly retryConfig?;
     constructor(config: LPConfig);
-    /**
-     * Route through cache if enabled, otherwise call factory directly.
-     * Failed Results (ok === false) are never cached — transient errors
-     * shouldn't persist for the full TTL.
-     */
+    /** Route through cache if enabled, skipping failed Results. */
     private cached;
     /**
      * Clear all cached API responses.
@@ -52,21 +48,24 @@ export declare class LPClient {
     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;
-    /**
-     * Invalidate cached assignments only.
-     * Use when an external event indicates assignment data changed
-     * (e.g., after logging time which updates loggedHoursRollup).
-     */
-    invalidateAssignmentsCache(): void;
     /**
      * Invalidate cached workspace tree snapshot only.
-     * Use when the workspace structure changes (items created, moved, or deleted).
      */
     invalidateTreeCache(): void;
+    /**
+     * Invalidate cached workspace members only.
+     */
+    invalidateMemberCache(): void;
+    /**
+     * Invalidate cached items and ancestors only.
+     */
+    invalidateItemCache(): void;
+    /**
+     * Invalidate cached cost codes only.
+     */
+    invalidateCostCodeCache(): void;
     /**
      * Make an authenticated request to the LP API
      *
@@ -88,7 +87,7 @@ export declare class LPClient {
      */
     private fetchAndParseMutation;
     /**
-     * Validate the API token by listing workspaces
+     * Validate the API token
      */
     validateToken(): Promise<Result<void>>;
     /**
@@ -96,7 +95,7 @@ export declare class LPClient {
      */
     getWorkspaces(): Promise<Result<LPWorkspace[]>>;
     /**
-     * Get all members in the workspace (with pagination)
+     * Get all members in the workspace
      */
     getWorkspaceMembers(): Promise<Result<LPMember[]>>;
     /**
@@ -122,7 +121,7 @@ export declare class LPClient {
      */
     getItemAncestors(itemId: number): Promise<Result<LPAncestor[]>>;
     /**
-     * Find all assignments under a task (with pagination)
+     * Find all assignments under a task
      */
     findAssignments(taskId: number): Promise<Result<LPItem[]>>;
     /**
@@ -177,7 +176,7 @@ export declare class LPClient {
         treeItemCount: number;
     }>>;
     /**
-     * Get all cost codes in the workspace (with pagination)
+     * Get all cost codes in the workspace
      */
     getCostCodes(): Promise<Result<LPCostCode[]>>;
     /**
@@ -201,7 +200,7 @@ export declare class LPClient {
      * @param date - Date(s) in YYYY-MM-DD format (string or array)
      * @param itemId - Optional item ID to filter by
      */
-    getTimesheetEntries(date: string | string[], itemId?: number): Promise<Result<LPTimesheetEntryWithId[]>>;
+    getTimesheetEntries(date: string | string[], itemId?: number): Promise<Result<LPTimesheetEntry[]>>;
     /**
      * Update an existing timesheet entry
      *
@@ -221,7 +220,7 @@ export declare class LPClient {
      * @param existingEntry - The existing entry (needed because PUT requires all fields)
      * @param updates - Fields to update (merged with existing)
      */
-    updateTimesheetEntry(entryId: number, existingEntry: LPTimesheetEntryWithId, updates: Partial<LPTimesheetEntry>): Promise<LPSyncResult>;
+    updateTimesheetEntry(entryId: number, existingEntry: LPTimesheetEntry, updates: Partial<LPTimesheetEntry>): Promise<LPSyncResult>;
     /**
      * Create or update a timesheet entry (upsert)
      *

package/dist/client.js

@@ -10,7 +10,7 @@ import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIsN
 import { buildTree, getTreeAncestors } from './tree.js';
 import { parseLPErrorResponse } from './errors.js';
 import { LP_API_BASE } from './constants.js';
-import { TTLCache, getErrorMessage, fetchWithRetry, ok, okVoid, err, resolveRetryConfig } from '@markwharton/api-core';
+import { getErrorMessage, fetchWithRetry, ok, okVoid, err, resolveRetryConfig, cachedResult, fetchAndParseResponse, resolveClientCache } from '@markwharton/api-core';
 /** Transform raw API item to LPItem, preserving scheduling and effort fields */
 function transformItem(raw) {
     const item = {
@@ -114,9 +114,7 @@ export class LPClient {
         this.baseUrl = config.baseUrl ?? LP_API_BASE;
         this.onRequest = config.onRequest;
         // Initialize cache if configured
-        if (config.cache || config.cacheInstance) {
-            this.cache = config.cacheInstance ?? new TTLCache();
-        }
+        this.cache = resolveClientCache(config);
         this.cacheTtl = {
             membersTtl: config.cache?.membersTtl ?? 300000,
             costCodesTtl: config.cache?.costCodesTtl ?? 300000,
@@ -127,18 +125,9 @@ export class LPClient {
         // Initialize retry config with defaults if provided
         this.retryConfig = resolveRetryConfig(config.retry);
     }
-    /**
-     * Route through cache if enabled, otherwise call factory directly.
-     * Failed Results (ok === false) are never cached — transient errors
-     * shouldn't persist for the full TTL.
-     */
-    async cached(key, ttlMs, factory, options) {
-        if (!this.cache)
-            return factory();
-        return this.cache.get(key, ttlMs, factory, {
-            ...options,
-            shouldCache: (data) => data.ok !== false,
-        });
+    /** Route through cache if enabled, skipping failed Results. */
+    cached(key, ttlMs, factory, options) {
+        return cachedResult(this.cache, key, ttlMs, factory, options);
     }
     /**
      * Clear all cached API responses.
@@ -149,27 +138,35 @@ export class LPClient {
     }
     /**
      * 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:');
     }
-    /**
-     * Invalidate cached assignments only.
-     * Use when an external event indicates assignment data changed
-     * (e.g., after logging time which updates loggedHoursRollup).
-     */
-    invalidateAssignmentsCache() {
-        this.cache?.invalidate('assignments');
-    }
     /**
      * Invalidate cached workspace tree snapshot only.
-     * Use when the workspace structure changes (items created, moved, or deleted).
      */
     invalidateTreeCache() {
         this.cache?.invalidate('tree');
     }
+    /**
+     * Invalidate cached workspace members only.
+     */
+    invalidateMemberCache() {
+        this.cache?.invalidate('members');
+    }
+    /**
+     * Invalidate cached items and ancestors only.
+     */
+    invalidateItemCache() {
+        this.cache?.invalidate('item:');
+        this.cache?.invalidate('ancestors:');
+    }
+    /**
+     * Invalidate cached cost codes only.
+     */
+    invalidateCostCodeCache() {
+        this.cache?.invalidate('costcodes');
+    }
     /**
      * Make an authenticated request to the LP API
      *
@@ -208,19 +205,8 @@ export class LPClient {
     /**
      * Fetch a URL and parse the response, with standardized error handling.
      */
-    async fetchAndParse(url, parse, fetchOptions) {
-        try {
-            const response = await this.fetch(url, fetchOptions);
-            if (!response.ok) {
-                const errorText = await response.text();
-                const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
-                return { ok: false, error: message, status: response.status, ...(isDuplicate ? { isDuplicate } : {}) };
-            }
-            return ok(await parse(response));
-        }
-        catch (error) {
-            return err(getErrorMessage(error), 0);
-        }
+    fetchAndParse(url, parse, fetchOptions) {
+        return fetchAndParseResponse(() => this.fetch(url, fetchOptions), parse, parseLPErrorResponse);
     }
     /**
      * Fetch and parse with isDuplicate support for mutation methods.
@@ -244,7 +230,7 @@ export class LPClient {
     // Workspace & Validation
     // ============================================================================
     /**
-     * Validate the API token by listing workspaces
+     * Validate the API token
      */
     async validateToken() {
         const url = `${this.baseUrl}/workspaces/v1`;
@@ -276,7 +262,7 @@ export class LPClient {
     // Members
     // ============================================================================
     /**
-     * Get all members in the workspace (with pagination)
+     * Get all members in the workspace
      */
     async getWorkspaceMembers() {
         return this.cached('members', this.cacheTtl.membersTtl, async () => {
@@ -359,7 +345,7 @@ export class LPClient {
         });
     }
     /**
-     * Find all assignments under a task (with pagination)
+     * Find all assignments under a task
      */
     async findAssignments(taskId) {
         // parentId[is]="{taskId}"&itemType[is]="assignments" (LP API uses lowercase plural)
@@ -523,7 +509,7 @@ export class LPClient {
     // Cost Codes
     // ============================================================================
     /**
-     * Get all cost codes in the workspace (with pagination)
+     * Get all cost codes in the workspace
      */
     async getCostCodes() {
         return this.cached('costcodes', this.cacheTtl.costCodesTtl, async () => {

package/dist/index.d.ts

@@ -30,7 +30,7 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, HierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPUpsertOptions, LPAssignment, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
+export type { LPConfig, LPCacheConfig, LPRetryConfig, LPItemType, LPHierarchyItem, LPItem, LPAncestor, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTaskResolution, LPUpsertOptions, LPAssignment, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
 export type { AccessTier } from './types.js';
 export { METHOD_TIERS } from './types.js';
 export { ok, err, getErrorMessage, TTLCache, MemoryCacheStore, LayeredCache } from '@markwharton/api-core';

package/dist/types.d.ts

@@ -15,7 +15,7 @@ export type LPItemType = 'Task' | 'Assignment' | 'Folder' | 'Project' | 'Package
  * Used by consumers to store structured hierarchy data from any backend.
  * LP-specific ancestors use the stricter LPAncestor type.
  */
-export interface HierarchyItem {
+export interface LPHierarchyItem {
     /** Unique identifier (number for LP, string UUID for other backends) */
     id: number | string;
     /** Display name */
@@ -217,9 +217,11 @@ export interface LPSyncResult extends Result<number> {
     isDuplicate?: boolean;
 }
 /**
- * Input for a timesheet entry to sync
+ * A timesheet entry (input for create/update, or response from queries)
  */
 export interface LPTimesheetEntry {
+    /** Unique identifier (present in API responses) */
+    id?: number;
     /** Date in YYYY-MM-DD format */
     date: string;
     /** Item ID (should be an Assignment ID) */
@@ -230,14 +232,7 @@ export interface LPTimesheetEntry {
     costCodeId?: number;
     /** Optional note/description */
     note?: string;
-}
-/**
- * A timesheet entry returned from LP API queries (includes ID)
- */
-export interface LPTimesheetEntryWithId extends LPTimesheetEntry {
-    /** Unique identifier for the entry */
-    id: number;
-    /** User ID who logged the time */
+    /** User ID who logged the time (present in API responses) */
     userId?: number;
 }
 /**

package/dist/utils.js

@@ -6,36 +6,40 @@ import { getErrorMessage, err } from '@markwharton/api-core';
 // ============================================================================
 // LP API Filter Builders
 // ============================================================================
+/** Encode a value for embedding in a pre-encoded LP filter string: %22<encoded-value>%22 */
+function encodeFilterValue(value) {
+    return `%22${String(value).replace(/\+/g, '%2B')}%22`;
+}
 /**
  * Build a URL-encoded filter for LP API: field[is]="value"
  */
 export function filterIs(field, value) {
-    return `${field}%5Bis%5D=%22${value}%22`;
+    return `${field}%5Bis%5D=${encodeFilterValue(value)}`;
 }
 /**
  * Build a URL-encoded filter for LP API: field[is_not]="value"
  */
 export function filterIsNot(field, value) {
-    return `${field}%5Bis_not%5D=%22${value}%22`;
+    return `${field}%5Bis_not%5D=${encodeFilterValue(value)}`;
 }
 /**
  * Build a URL-encoded filter for LP API: field[in]=["value1","value2"]
  */
 export function filterIn(field, values) {
-    const encoded = values.map(v => `%22${v}%22`).join(',');
+    const encoded = values.map(v => encodeFilterValue(v)).join(',');
     return `${field}%5Bin%5D=%5B${encoded}%5D`;
 }
 /**
  * Build a URL-encoded filter for LP API: field[gt]="value"
  */
 export function filterGt(field, value) {
-    return `${field}%5Bgt%5D=%22${value}%22`;
+    return `${field}%5Bgt%5D=${encodeFilterValue(value)}`;
 }
 /**
  * Build a URL-encoded filter for LP API: field[lt]="value"
  */
 export function filterLt(field, value) {
-    return `${field}%5Blt%5D=%22${value}%22`;
+    return `${field}%5Blt%5D=${encodeFilterValue(value)}`;
 }
 /** Normalize YYYY-MM-DD to ISO offset string using local timezone (LP API requires ISO for date filters) */
 function toISODateValue(value) {
@@ -54,7 +58,7 @@ function toISODateValue(value) {
  * Accepts YYYY-MM-DD or full ISO strings.
  */
 export function filterAfter(field, value) {
-    return `${field}%5Bafter%5D=%22${toISODateValue(value)}%22`;
+    return `${field}%5Bafter%5D=${encodeFilterValue(toISODateValue(value))}`;
 }
 /**
  * Build a URL-encoded filter for LP API: field[before]="value"
@@ -62,7 +66,7 @@ export function filterAfter(field, value) {
  * Accepts YYYY-MM-DD or full ISO strings.
  */
 export function filterBefore(field, value) {
-    return `${field}%5Bbefore%5D=%22${toISODateValue(value)}%22`;
+    return `${field}%5Bbefore%5D=${encodeFilterValue(toISODateValue(value))}`;
 }
 /**
  * Join multiple filter expressions with &

package/package.json

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