@markwharton/liquidplanner 1.11.0 → 2.0.0

package/dist/index.d.ts

@@ -10,10 +10,12 @@
  * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
  *
  * // Validate credentials
- * await client.validateToken();
+ * const result = await client.validateToken();
+ * if (!result.ok) { console.error(result.error); }
  *
  * // Get workspaces
- * const { workspaces } = await client.getWorkspaces();
+ * const wsResult = await client.getWorkspaces();
+ * const workspaces = wsResult.data;
  *
  * // Resolve task to assignment
  * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
@@ -28,10 +30,12 @@
  */
 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, 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, LPUpsertOptions, LPAssignmentWithContext, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
+export { ok, err, getErrorMessage } from '@markwharton/api-core';
+export type { Result, RetryConfig } from '@markwharton/api-core';
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
-export { getErrorMessage } from '@markwharton/api-core';
+export { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';
 export { LP_API_BASE } from './constants.js';
 export { LPError, parseLPErrorResponse } from './errors.js';
 export type { LPParsedError } from './errors.js';

package/dist/index.js

@@ -10,10 +10,12 @@
  * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
  *
  * // Validate credentials
- * await client.validateToken();
+ * const result = await client.validateToken();
+ * if (!result.ok) { console.error(result.error); }
  *
  * // Get workspaces
- * const { workspaces } = await client.getWorkspaces();
+ * const wsResult = await client.getWorkspaces();
+ * const workspaces = wsResult.data;
  *
  * // Resolve task to assignment
  * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
@@ -30,9 +32,12 @@
 export { LPClient } from './client.js';
 // Workflows
 export { resolveTaskToAssignment } from './workflows.js';
+// Re-export Result from api-core
+export { ok, err, getErrorMessage } from '@markwharton/api-core';
 // Utilities
-export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
-export { getErrorMessage } from '@markwharton/api-core';
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';
+// Tree utilities
+export { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';
 // Constants
 export { LP_API_BASE } from './constants.js';
 // Errors

package/dist/tree.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tree Building and Query Utilities
+ *
+ * Pure functions that operate on LPWorkspaceTree — zero API calls.
+ * Used by LPClient.getWorkspaceTree() for building and by consumers for querying.
+ */
+import type { LPItem, LPAncestor, LPWorkspaceTree } from './types.js';
+/**
+ * Build a workspace tree from a flat array of items
+ *
+ * Assembles items into a tree using parentId relationships.
+ * Items whose parent is not in the array become root nodes.
+ */
+export declare function buildTree(items: LPItem[]): LPWorkspaceTree;
+/**
+ * Get ancestors of an item from root to parent
+ *
+ * Walks up the tree via parentId, collecting ancestors in root→child order.
+ * Same order as LPClient.getItemAncestors() — excludes the item itself.
+ */
+export declare function getTreeAncestors(tree: LPWorkspaceTree, itemId: number): LPAncestor[];
+/**
+ * Build a formatted hierarchy path for an item
+ *
+ * Returns a string like "Project A › Subfolder B" from Project and Folder ancestors.
+ * Excludes system containers (Package, WorkspaceRoot) and Tasks.
+ */
+export declare function getTreeHierarchyPath(tree: LPWorkspaceTree, itemId: number): string;
+/**
+ * Find all items in the tree matching a predicate
+ */
+export declare function findInTree(tree: LPWorkspaceTree, predicate: (item: LPItem) => boolean): LPItem[];

package/dist/tree.js

@@ -0,0 +1,86 @@
+/**
+ * Tree Building and Query Utilities
+ *
+ * Pure functions that operate on LPWorkspaceTree — zero API calls.
+ * Used by LPClient.getWorkspaceTree() for building and by consumers for querying.
+ */
+/**
+ * Build a workspace tree from a flat array of items
+ *
+ * Assembles items into a tree using parentId relationships.
+ * Items whose parent is not in the array become root nodes.
+ */
+export function buildTree(items) {
+    // Create tree nodes with empty children arrays
+    const byId = new Map();
+    for (const item of items) {
+        byId.set(item.id, { ...item, children: [] });
+    }
+    // Wire parent-child relationships
+    const roots = [];
+    for (const node of byId.values()) {
+        if (node.parentId !== undefined && byId.has(node.parentId)) {
+            byId.get(node.parentId).children.push(node);
+        }
+        else {
+            roots.push(node);
+        }
+    }
+    return {
+        roots,
+        byId,
+        fetchedAt: Date.now(),
+        itemCount: items.length,
+    };
+}
+/**
+ * Get ancestors of an item from root to parent
+ *
+ * Walks up the tree via parentId, collecting ancestors in root→child order.
+ * Same order as LPClient.getItemAncestors() — excludes the item itself.
+ */
+export function getTreeAncestors(tree, itemId) {
+    const ancestors = [];
+    let current = tree.byId.get(itemId);
+    if (!current)
+        return ancestors;
+    // Walk up to root
+    while (current.parentId !== undefined) {
+        const parent = tree.byId.get(current.parentId);
+        if (!parent)
+            break;
+        ancestors.push({
+            id: parent.id,
+            name: parent.name,
+            itemType: parent.itemType,
+        });
+        current = parent;
+    }
+    // Reverse to root→child order (we collected child→root)
+    return ancestors.reverse();
+}
+/**
+ * Build a formatted hierarchy path for an item
+ *
+ * Returns a string like "Project A › Subfolder B" from Project and Folder ancestors.
+ * Excludes system containers (Package, WorkspaceRoot) and Tasks.
+ */
+export function getTreeHierarchyPath(tree, itemId) {
+    const ancestors = getTreeAncestors(tree, itemId);
+    const hierarchyAncestors = ancestors.filter(a => a.itemType === 'Project' || a.itemType === 'Folder');
+    return hierarchyAncestors
+        .map(a => a.name ?? `[${a.id}]`)
+        .join(' › ');
+}
+/**
+ * Find all items in the tree matching a predicate
+ */
+export function findInTree(tree, predicate) {
+    const results = [];
+    for (const node of tree.byId.values()) {
+        if (predicate(node)) {
+            results.push(node);
+        }
+    }
+    return results;
+}

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * These types define the data structures used when interacting with
  * the LiquidPlanner API.
  */
+import type { Result, RetryConfig } from '@markwharton/api-core';
 /**
  * LiquidPlanner item types in the hierarchy
  */
@@ -91,6 +92,24 @@ export interface LPItem {
     folderStatus?: string;
     /** Priority ordering (global priority array from LP) */
     globalPriority?: string[];
+    /** Item color */
+    color?: string;
+    /** Work type */
+    workType?: string;
+    /** Item description/notes */
+    description?: string;
+    /** Custom field values with inheritance info */
+    customFieldValues?: Record<string, unknown>;
+    /** When the item was created (ISO string) */
+    createdAt?: string;
+    /** When the item was last updated (ISO string) */
+    updatedAt?: string;
+    /** Hours clipped by work limit */
+    clippedHours?: number;
+    /** Work limit in hours */
+    workLimitHours?: number;
+    /** Whether work limit is at risk */
+    workLimitRisk?: boolean;
 }
 /**
  * A cost code from LiquidPlanner
@@ -168,22 +187,15 @@ export interface LPCacheConfig {
     assignmentsTtl?: number;
     /** TTL for items and ancestors (default: 300000 = 5 min) */
     itemsTtl?: number;
+    /** TTL for workspace tree snapshot (default: 600000 = 10 min) */
+    treeTtl?: 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.
+ * @deprecated Use RetryConfig from @markwharton/api-core instead
  */
-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;
-}
+export type LPRetryConfig = RetryConfig;
 /**
  * LiquidPlanner configuration for API access
  */
@@ -207,16 +219,10 @@ export interface LPConfig {
 }
 /**
  * Result of a timesheet sync operation
+ *
+ * Extends Result<number> where data is the entry ID.
  */
-export interface LPSyncResult {
-    /** Whether the operation succeeded */
-    success: boolean;
-    /** ID of the created entry (if successful) */
-    entryId?: number;
-    /** Error message (if failed) */
-    error?: string;
-    /** HTTP status code (if failed) - useful for detecting rate limits (429) */
-    statusCode?: number;
+export interface LPSyncResult extends Result<number> {
     /** Whether the error was due to a duplicate entry */
     isDuplicate?: boolean;
 }
@@ -244,15 +250,6 @@ export interface LPTimesheetEntryWithId extends LPTimesheetEntry {
     /** User ID who logged the time */
     userId?: number;
 }
-/**
- * Generic result wrapper for LP operations
- */
-export interface LPResult<T> {
-    /** The data if successful */
-    data?: T;
-    /** Error message if failed */
-    error?: string;
-}
 /**
  * Options for upsert timesheet entry operation
  */
@@ -283,15 +280,69 @@ export interface LPAssignmentWithContext extends LPItem {
     hierarchyPath?: string;
 }
 /**
- * Structured error information from LP API
+ * Options for querying items with LP API filters
  *
- * Preserves HTTP status code for proper error handling (e.g., 429 rate limits).
+ * Maps to LP API filter parameters on the items endpoint.
+ * All fields are optional — only specified fields generate filters.
  */
-export interface LPErrorInfo {
-    /** Human-readable error message */
-    message: string;
-    /** HTTP status code from the response */
-    statusCode: number;
-    /** Whether this error indicates a duplicate entry */
-    isDuplicate?: boolean;
+export interface LPFindItemsOptions {
+    /** Filter by parent item ID (parentId[is]) */
+    parentId?: number;
+    /** Filter by item type — use LP API values: 'tasks', 'assignments', 'packages', 'projects', 'folders' */
+    itemType?: string;
+    /** Filter by task status group: 'scheduled', 'unscheduled', 'done' (taskStatusGroup[is]) */
+    taskStatusGroup?: string;
+    /** Exclude a task status group (taskStatusGroup[is_not]) */
+    taskStatusGroupNot?: string;
+    /** Filter by specific task status ID (taskStatusId[is]) */
+    taskStatusId?: number;
+    /** Filter by package collection: 'scheduled', 'backlog', 'archived', 'templates' (packageStatus[is]) */
+    packageStatus?: string;
+    /** Filter by folder status: 'active', 'onHold', 'done' (folderStatus[is]) */
+    folderStatus?: string;
+    /** Filter by scheduling priority (scheduleDirective[is]) */
+    scheduleDirective?: string;
+    /** Items with expected start after this date (expectedStart[after]) */
+    expectedStartAfter?: string;
+    /** Items with expected finish before this date (expectedFinish[before]) */
+    expectedFinishBefore?: string;
+    /** Items with target start after this date (targetStart[after]) */
+    targetStartAfter?: string;
+    /** Items with target finish before this date (targetFinish[before]) */
+    targetFinishBefore?: string;
+    /** Items completed after this date (doneDate[after]) */
+    doneDateAfter?: string;
+    /** Filter for late items (late[is]) */
+    late?: boolean;
+    /** Filter for items at work limit risk (workLimitRisk[is]) */
+    workLimitRisk?: boolean;
+    /** Filter for items with files (hasFiles[is]) */
+    hasFiles?: boolean;
+    /** Filter by item name (name[is]) */
+    name?: string;
+    /** Filter by custom field values (customFieldValues.<key>[is]) */
+    customFieldValues?: Record<string, string>;
+}
+/**
+ * A node in the workspace tree, extending LPItem with children
+ */
+export interface LPTreeNode extends LPItem {
+    /** Direct children of this node */
+    children: LPTreeNode[];
+}
+/**
+ * Workspace tree snapshot with lookup indices
+ *
+ * Built from a single fetch of all active items, this structure
+ * enables zero-API-call hierarchy lookups via the `byId` index.
+ */
+export interface LPWorkspaceTree {
+    /** Root nodes (typically packages) */
+    roots: LPTreeNode[];
+    /** Fast lookup: item ID → tree node */
+    byId: Map<number, LPTreeNode>;
+    /** Timestamp when snapshot was taken (Date.now()) */
+    fetchedAt: number;
+    /** Total number of items in the tree */
+    itemCount: number;
 }

package/dist/utils.d.ts

@@ -1,15 +1,44 @@
 /**
  * LiquidPlanner Utility Functions
  */
-import type { LPItemType, LPErrorInfo } from './types.js';
+import type { LPItemType } from './types.js';
+import type { Result } from '@markwharton/api-core';
 /**
  * Build a URL-encoded filter for LP API: field[is]="value"
  */
 export declare function filterIs(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[is_not]="value"
+ */
+export declare function filterIsNot(field: string, value: string | number): string;
 /**
  * Build a URL-encoded filter for LP API: field[in]=["value1","value2"]
  */
 export declare function filterIn(field: string, values: (string | number)[]): string;
+/**
+ * Build a URL-encoded filter for LP API: field[gt]="value"
+ */
+export declare function filterGt(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[lt]="value"
+ */
+export declare function filterLt(field: string, value: string | number): string;
+/**
+ * Build a URL-encoded filter for LP API: field[after]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export declare function filterAfter(field: string, value: string): string;
+/**
+ * Build a URL-encoded filter for LP API: field[before]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export declare function filterBefore(field: string, value: string): string;
+/**
+ * Join multiple filter expressions with &
+ */
+export declare function joinFilters(...filters: string[]): string;
 /**
  * Options for paginated fetch
  */
@@ -28,10 +57,7 @@ export interface PaginateOptions<TRaw, TResult> {
  *
  * Handles the continuation token pattern used by LP API.
  */
-export declare function paginatedFetch<TRaw, TResult>(options: PaginateOptions<TRaw, TResult>): Promise<{
-    results?: TResult[];
-    error?: LPErrorInfo;
-}>;
+export declare function paginatedFetch<TRaw, TResult>(options: PaginateOptions<TRaw, TResult>): Promise<Result<TResult[]>>;
 /**
  * Convert decimal hours to minutes
  *

package/dist/utils.js

@@ -2,7 +2,7 @@
  * LiquidPlanner Utility Functions
  */
 import { parseLPErrorResponse } from './errors.js';
-import { getErrorMessage } from '@markwharton/api-core';
+import { getErrorMessage, err } from '@markwharton/api-core';
 // ============================================================================
 // LP API Filter Builders
 // ============================================================================
@@ -12,6 +12,12 @@ import { getErrorMessage } from '@markwharton/api-core';
 export function filterIs(field, value) {
     return `${field}%5Bis%5D=%22${value}%22`;
 }
+/**
+ * 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`;
+}
 /**
  * Build a URL-encoded filter for LP API: field[in]=["value1","value2"]
  */
@@ -19,6 +25,51 @@ export function filterIn(field, values) {
     const encoded = values.map(v => `%22${v}%22`).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`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[lt]="value"
+ */
+export function filterLt(field, value) {
+    return `${field}%5Blt%5D=%22${value}%22`;
+}
+/** Normalize YYYY-MM-DD to ISO offset string using local timezone (LP API requires ISO for date filters) */
+function toISODateValue(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return value;
+    const d = new Date(`${value}T00:00:00`);
+    const offset = -d.getTimezoneOffset();
+    const sign = offset >= 0 ? '+' : '-';
+    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+    const minutes = String(Math.abs(offset) % 60).padStart(2, '0');
+    return `${value}T00:00:00${sign}${hours}:${minutes}`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[after]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export function filterAfter(field, value) {
+    return `${field}%5Bafter%5D=%22${toISODateValue(value)}%22`;
+}
+/**
+ * Build a URL-encoded filter for LP API: field[before]="value"
+ *
+ * Accepts YYYY-MM-DD or full ISO strings.
+ */
+export function filterBefore(field, value) {
+    return `${field}%5Bbefore%5D=%22${toISODateValue(value)}%22`;
+}
+/**
+ * Join multiple filter expressions with &
+ */
+export function joinFilters(...filters) {
+    return filters.join('&');
+}
 /**
  * Generic pagination helper for LP API endpoints
  *
@@ -37,8 +88,8 @@ export async function paginatedFetch(options) {
             const response = await fetchFn(url);
             if (!response.ok) {
                 const errorText = await response.text();
-                const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
-                return { error: { message, statusCode: response.status, isDuplicate } };
+                const { message } = parseLPErrorResponse(errorText, response.status);
+                return err(message, response.status);
             }
             const result = await response.json();
             const rawData = result.data || [];
@@ -47,11 +98,11 @@ export async function paginatedFetch(options) {
             allResults.push(...pageResults);
             continuationToken = result.continuationToken;
         } while (continuationToken);
-        return { results: allResults };
+        return { ok: true, data: allResults };
     }
     catch (error) {
         // Network errors or JSON parse errors don't have HTTP status codes
-        return { error: { message: getErrorMessage(error), statusCode: 0 } };
+        return err(getErrorMessage(error), 0);
     }
 }
 /**

package/dist/workflows.js

@@ -37,14 +37,15 @@
  */
 export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
     // Step 1: Fetch the item
-    const { item, error: fetchError } = await client.getItem(itemId);
-    if (fetchError || !item) {
+    const itemResult = await client.getItem(itemId);
+    if (!itemResult.ok || !itemResult.data) {
         return {
             inputItem: { id: itemId, name: null, itemType: 'Task' },
             assignmentId: 0,
-            error: fetchError?.message || 'Item not found',
+            error: itemResult.error || 'Item not found',
         };
     }
+    const item = itemResult.data;
     // Step 2: Check item type and resolve accordingly
     switch (item.itemType) {
         case 'Assignment':
@@ -57,14 +58,15 @@ export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
             };
         case 'Task': {
             // Find assignments under this task
-            const { assignments, error: assignmentError } = await client.findAssignments(item.id);
-            if (assignmentError) {
+            const assignResult = await client.findAssignments(item.id);
+            if (!assignResult.ok) {
                 return {
                     inputItem: item,
                     assignmentId: 0,
-                    error: `Failed to find assignments: ${assignmentError.message}`,
+                    error: `Failed to find assignments: ${assignResult.error}`,
                 };
             }
+            const assignments = assignResult.data;
             if (!assignments || assignments.length === 0) {
                 return {
                     inputItem: item,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/liquidplanner",
-  "version": "1.11.0",
+  "version": "2.0.0",
   "description": "LiquidPlanner API client for timesheet integration",
   "type": "module",
   "main": "dist/index.js",
@@ -16,7 +16,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@markwharton/api-core": "^1.0.0"
+    "@markwharton/api-core": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",

package/dist/cache.d.ts

@@ -1,43 +0,0 @@
-/**
- * Simple in-memory TTL cache with request coalescing
- *
- * 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.
- *
- * Request coalescing: when multiple concurrent callers request the
- * same expired key, only one factory call is made. All callers
- * receive the same resolved value (or the same rejection).
- *
- * 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;
-    private inflight;
-    /**
-     * Get a cached value, or call the factory to populate it.
-     *
-     * If a factory call is already in progress for this key,
-     * returns the existing promise instead of starting a duplicate.
-     *
-     * @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.
-     *
-     * Also cancels any in-flight requests for matching keys,
-     * so subsequent calls will start fresh factory invocations.
-     *
-     * Example: invalidate('timesheet:') clears all timesheet entries.
-     */
-    invalidate(prefix: string): void;
-    /**
-     * Clear all cached data and in-flight requests.
-     */
-    clear(): void;
-}