@markwharton/liquidplanner 2.0.0 → 2.1.0

package/README.md

@@ -16,29 +16,36 @@ import { LPClient, resolveTaskToAssignment } from '@markwharton/liquidplanner';
 const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
 
 // Validate credentials
-await client.validateToken();
+const validation = await client.validateToken();
+if (!validation.ok) throw new Error(validation.error);
 
 // Get workspaces
-const { workspaces } = await client.getWorkspaces();
+const wsResult = await client.getWorkspaces();
+if (wsResult.ok) console.log(wsResult.data); // LPWorkspace[]
 
 // Get workspace members
-const { members } = await client.getWorkspaceMembers();
+const membersResult = await client.getWorkspaceMembers();
+if (membersResult.ok) console.log(membersResult.data); // LPMember[]
 
 // Get user's assignments (for task picker)
-const { assignments } = await client.getMyAssignments(memberId);
+const assignResult = await client.getMyAssignments(memberId);
+if (assignResult.ok) console.log(assignResult.data); // LPItem[]
 
 // Get assignments with parent task/project names resolved
-const { assignments: enriched } = await client.getMyAssignmentsWithContext(memberId, {
+const ctxResult = await client.getMyAssignmentsWithContext(memberId, {
   includeProject: true  // optional: also fetch project names
 });
+if (ctxResult.ok) console.log(ctxResult.data); // LPAssignmentWithContext[]
 
 // Get assignments with full hierarchy path
-const { assignments: withHierarchy } = await client.getMyAssignmentsWithContext(memberId, {
+const hierResult = await client.getMyAssignmentsWithContext(memberId, {
   includeHierarchy: true  // includes ancestors and hierarchyPath
 });
+if (hierResult.ok) console.log(hierResult.data); // LPAssignmentWithContext[]
 
 // Get item ancestors (hierarchy chain)
-const { ancestors } = await client.getItemAncestors(itemId);
+const ancResult = await client.getItemAncestors(itemId);
+if (ancResult.ok) console.log(ancResult.data); // LPAncestor[]
 
 // Resolve task to assignment
 const resolution = await resolveTaskToAssignment(client, taskId, memberId);
@@ -52,31 +59,39 @@ await client.createTimesheetEntry({
 });
 
 // Query existing entries for a date
-const { entries } = await client.getTimesheetEntries('2026-01-29', assignmentId);
+const tsResult = await client.getTimesheetEntries('2026-01-29', assignmentId);
+if (tsResult.ok) console.log(tsResult.data); // LPTimesheetEntryWithId[]
 
 // Update an existing entry (accumulate hours)
-await client.updateTimesheetEntry(entryId, existingEntry, {
-  hours: existingEntry.hours + 1.5,
+const existing = tsResult.data![0];
+await client.updateTimesheetEntry(existing.id, existing, {
+  hours: existing.hours + 1.5,
   note: 'Additional work'
 });
 
 // Find items with filters
-const { items } = await client.findItems({
+const lateResult = await client.findItems({
   itemType: 'tasks',
   taskStatusGroupNot: 'done',
   late: true,
 });
+if (lateResult.ok) console.log(lateResult.data); // LPItem[]
 
 // Get children of an item
-const { items: children } = await client.getChildren(parentId);
+const childResult = await client.getChildren(parentId);
+if (childResult.ok) console.log(childResult.data); // LPItem[]
 
 // Get workspace tree snapshot (cached, all hierarchy lookups resolved in memory)
-const { tree } = await client.getWorkspaceTree();
+const treeResult = await client.getWorkspaceTree();
+if (treeResult.ok) console.log(treeResult.data); // LPWorkspaceTree
 
 // Get a member's work with full context from the tree
-const { assignments: myWork, treeItemCount } = await client.getMyWork(memberId);
-// Each assignment includes taskName, projectId, projectName, hierarchyPath, ancestors
-// treeItemCount shows total items loaded (only member's assignments returned downstream)
+const workResult = await client.getMyWork(memberId);
+if (workResult.ok) {
+  const { assignments, treeItemCount } = workResult.data;
+  // Each assignment includes taskName, projectId, projectName, hierarchyPath, ancestors
+  // treeItemCount shows total items loaded (only member's assignments returned downstream)
+}
 ```
 
 ### Tree Utilities
@@ -97,29 +112,49 @@ const path = getTreeHierarchyPath(tree, itemId);
 const lateTasks = findInTree(tree, item => item.late === true);
 ```
 
-## API Reference
+## 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
+}
+```
 
-All methods return `{ data?, error? }` result objects rather than throwing exceptions.
+```typescript
+const result = await client.getMyWork(memberId);
+if (!result.ok) {
+  console.error(result.error, result.status);
+  return;
+}
+const { assignments, treeItemCount } = result.data;
+```
+
+## API Reference
 
 | Method | Parameters | Returns |
 |--------|-----------|---------|
-| `validateToken()` | — | `{ valid, error? }` |
-| `getWorkspaces()` | — | `{ workspaces?, error? }` |
-| `getWorkspaceMembers()` | — | `{ members?, error? }` |
-| `getItem(itemId)` | `number` | `{ item?, error? }` |
-| `getItems(itemIds)` | `number[]` | `{ items?, error? }` |
-| `getItemAncestors(itemId)` | `number` | `{ ancestors?, error? }` |
-| `findAssignments(taskId)` | `number` | `{ assignments?, error? }` |
-| `getMyAssignments(memberId)` | `number` | `{ assignments?, error? }` |
-| `getMyAssignmentsWithContext(memberId, options?)` | `number, { includeProject?, includeHierarchy? }` | `{ assignments?, error? }` |
-| `findItems(options)` | `LPFindItemsOptions` | `{ items?, error? }` |
-| `getChildren(parentId, options?)` | `number, { itemType? }?` | `{ items?, error? }` |
-| `getWorkspaceTree()` | — | `{ tree?, error? }` |
-| `getMyWork(memberId)` | `number` | `{ assignments?, treeItemCount?, error? }` |
+| `validateToken()` | — | `Result<void>` |
+| `getWorkspaces()` | — | `Result<LPWorkspace[]>` |
+| `getWorkspaceMembers()` | — | `Result<LPMember[]>` |
+| `getItem(itemId)` | `number` | `Result<LPItem>` |
+| `getItems(itemIds)` | `number[]` | `Result<LPItem[]>` |
+| `getItemAncestors(itemId)` | `number` | `Result<LPAncestor[]>` |
+| `findAssignments(taskId)` | `number` | `Result<LPItem[]>` |
+| `getMyAssignments(memberId)` | `number` | `Result<LPItem[]>` |
+| `getMyAssignmentsWithContext(memberId, options?)` | `number, { includeProject?, includeHierarchy? }` | `Result<LPAssignmentWithContext[]>` |
+| `findItems(options)` | `LPFindItemsOptions` | `Result<LPItem[]>` |
+| `getChildren(parentId, options?)` | `number, { itemType? }?` | `Result<LPItem[]>` |
+| `getWorkspaceTree()` | — | `Result<LPWorkspaceTree>` |
+| `getMyWork(memberId)` | `number` | `Result<{ assignments: LPAssignmentWithContext[], treeItemCount: number }>` |
 | `invalidateTreeCache()` | — | `void` |
-| `getCostCodes()` | — | `{ costCodes?, error? }` |
+| `getCostCodes()` | — | `Result<LPCostCode[]>` |
 | `createTimesheetEntry(entry)` | `LPTimesheetEntry` | `LPSyncResult` |
-| `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `{ entries?, error? }` |
+| `getTimesheetEntries(date, itemId?)` | `string \| string[], number?` | `Result<LPTimesheetEntryWithId[]>` |
 | `updateTimesheetEntry(entryId, existing, updates)` | `number, LPTimesheetEntryWithId, Partial<LPTimesheetEntry>` | `LPSyncResult` |
 | `upsertTimesheetEntry(entry, options?)` | `LPTimesheetEntry, LPUpsertOptions?` | `LPSyncResult` |
 

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, batchMap, getErrorMessage, fetchWithRetry, ok, err } from '@markwharton/api-core';
+import { TTLCache, batchMap, getErrorMessage, fetchWithRetry, ok, err, resolveRetryConfig } from '@markwharton/api-core';
 /** Transform raw API item to LPItem, preserving scheduling and effort fields */
 function transformItem(raw) {
     const item = {
@@ -126,13 +126,7 @@ export class LPClient {
             treeTtl: config.cache?.treeTtl ?? 600000,
         };
         // 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,
-            };
-        }
+        this.retryConfig = resolveRetryConfig(config.retry);
     }
     /**
      * Route through cache if enabled, otherwise call factory directly.
@@ -262,7 +256,7 @@ export class LPClient {
             return err(`Unexpected response: HTTP ${response.status}`, response.status);
         }
         catch (error) {
-            return err(getErrorMessage(error) || 'Connection failed');
+            return err(getErrorMessage(error, 'Connection failed'));
         }
     }
     /**

package/dist/errors.d.ts

@@ -6,6 +6,7 @@
  * - {"message":"..."} or {"error":"..."}
  * - Plain text
  */
+import { ApiError } from '@markwharton/api-core';
 /**
  * Parsed LP error response
  */
@@ -25,14 +26,12 @@ export interface LPParsedError {
 export declare function parseLPErrorResponse(errorText: string, statusCode: number): LPParsedError;
 /**
  * Custom error class for LP API errors
+ *
+ * Extends ApiError from api-core with LP-specific isDuplicate flag.
  */
-export declare class LPError extends Error {
-    /** HTTP status code */
-    status: number;
+export declare class LPError extends ApiError {
     /** Whether this is a duplicate entry error */
     isDuplicate: boolean;
-    /** Raw error response */
-    rawResponse?: string;
     constructor(message: string, status: number, options?: {
         isDuplicate?: boolean;
         rawResponse?: string;

package/dist/errors.js

@@ -6,7 +6,7 @@
  * - {"message":"..."} or {"error":"..."}
  * - Plain text
  */
-import { parseJsonErrorResponse } from '@markwharton/api-core';
+import { ApiError, parseJsonErrorResponse } from '@markwharton/api-core';
 /** Error code for duplicate entry errors */
 const LP_ERROR_CODE_DUPLICATE = 'duplicate_value';
 /**
@@ -36,14 +36,14 @@ export function parseLPErrorResponse(errorText, statusCode) {
 }
 /**
  * Custom error class for LP API errors
+ *
+ * Extends ApiError from api-core with LP-specific isDuplicate flag.
  */
-export class LPError extends Error {
+export class LPError extends ApiError {
     constructor(message, status, options) {
-        super(message);
+        super(message, status, options);
         this.name = 'LPError';
-        this.status = status;
         this.isDuplicate = options?.isDuplicate ?? false;
-        this.rawResponse = options?.rawResponse;
     }
     /**
      * Create an LPError from an API response

package/dist/index.d.ts

@@ -32,7 +32,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, LPAssignmentWithContext, LPFindItemsOptions, LPTreeNode, LPWorkspaceTree, } from './types.js';
 export { ok, err, getErrorMessage } from '@markwharton/api-core';
-export type { Result, RetryConfig } from '@markwharton/api-core';
+export type { Result, RetryConfig, OnRequestCallback, BaseClientConfig } 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 { buildTree, getTreeAncestors, getTreeHierarchyPath, findInTree, } from './tree.js';

package/dist/index.js

@@ -32,7 +32,7 @@
 export { LPClient } from './client.js';
 // Workflows
 export { resolveTaskToAssignment } from './workflows.js';
-// Re-export Result from api-core
+// Re-exported from @markwharton/api-core
 export { ok, err, getErrorMessage } from '@markwharton/api-core';
 // Utilities
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIsNot, filterIn, filterGt, filterLt, filterAfter, filterBefore, joinFilters, paginatedFetch, } from './utils.js';

package/dist/types.d.ts

@@ -4,7 +4,7 @@
  * These types define the data structures used when interacting with
  * the LiquidPlanner API.
  */
-import type { Result, RetryConfig } from '@markwharton/api-core';
+import type { Result, RetryConfig, BaseClientConfig } from '@markwharton/api-core';
 /**
  * LiquidPlanner item types in the hierarchy
  */
@@ -199,23 +199,13 @@ export type LPRetryConfig = RetryConfig;
 /**
  * LiquidPlanner configuration for API access
  */
-export interface LPConfig {
+export interface LPConfig extends BaseClientConfig {
     /** Workspace ID to operate on */
     workspaceId: number;
     /** API token for authentication */
     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;
     /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markwharton/liquidplanner",
-  "version": "2.0.0",
+  "version": "2.1.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.1.0"
+    "@markwharton/api-core": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",