@markwharton/liquidplanner 1.0.0 → 1.2.0

package/dist/client.d.ts

@@ -6,7 +6,7 @@
  *
  * @see https://api-docs.liquidplanner.com/
  */
-import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId } from './types.js';
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPUpsertOptions, LPAssignmentWithContext } from './types.js';
 /**
  * LiquidPlanner API Client
  *
@@ -83,6 +83,22 @@ export declare class LPClient {
         assignments?: LPItem[];
         error?: string;
     }>;
+    /**
+     * Get assignments for a member with parent task names resolved
+     *
+     * This is a convenience method that fetches assignments and enriches
+     * them with parent task names in a single call (batched internally).
+     *
+     * @param memberId - The member ID to get assignments for
+     * @param options - Options for including additional context
+     * @param options.includeProject - If true, also fetch grandparent project names
+     */
+    getMyAssignmentsWithContext(memberId: number, options?: {
+        includeProject?: boolean;
+    }): Promise<{
+        assignments?: LPAssignmentWithContext[];
+        error?: string;
+    }>;
     /**
      * Get all cost codes in the workspace (with pagination)
      */
@@ -132,4 +148,39 @@ export declare class LPClient {
      * @param updates - Fields to update (merged with existing)
      */
     updateTimesheetEntry(entryId: number, existingEntry: LPTimesheetEntryWithId, updates: Partial<LPTimesheetEntry>): Promise<LPSyncResult>;
+    /**
+     * Create or update a timesheet entry (upsert)
+     *
+     * Checks for an existing entry first. If found, updates it (accumulating
+     * hours by default). If not found, creates a new entry.
+     *
+     * This follows the proven "fetch first" pattern from the CLI.
+     *
+     * By default, hours are accumulated (added to existing). Set `accumulate: false`
+     * to replace existing hours instead.
+     *
+     * **Note behavior:** Notes are appended to existing notes by the LP API.
+     * Pass an empty string to avoid adding notes on update.
+     *
+     * @example
+     * ```typescript
+     * // Accumulate hours (default)
+     * await client.upsertTimesheetEntry({
+     *   date: '2026-01-29',
+     *   itemId: 12345,
+     *   hours: 1.5,
+     *   note: 'Timer session'
+     * });
+     *
+     * // Replace hours instead of accumulating
+     * await client.upsertTimesheetEntry(
+     *   { date: '2026-01-29', itemId: 12345, hours: 4.0 },
+     *   { accumulate: false }
+     * );
+     * ```
+     *
+     * @param entry - The timesheet entry to create or update
+     * @param options - Upsert options (accumulate defaults to true)
+     */
+    upsertTimesheetEntry(entry: LPTimesheetEntry, options?: LPUpsertOptions): Promise<LPSyncResult>;
 }

package/dist/client.js

@@ -183,6 +183,55 @@ export class LPClient {
         });
         return error ? { error } : { assignments: results };
     }
+    /**
+     * Get assignments for a member with parent task names resolved
+     *
+     * This is a convenience method that fetches assignments and enriches
+     * them with parent task names in a single call (batched internally).
+     *
+     * @param memberId - The member ID to get assignments for
+     * @param options - Options for including additional context
+     * @param options.includeProject - If true, also fetch grandparent project names
+     */
+    async getMyAssignmentsWithContext(memberId, options) {
+        // 1. Get raw assignments
+        const { assignments, error } = await this.getMyAssignments(memberId);
+        if (error || !assignments)
+            return { error };
+        if (assignments.length === 0)
+            return { assignments: [] };
+        // 2. Extract unique parent IDs (tasks)
+        const taskIds = [...new Set(assignments.map(a => a.parentId).filter((id) => id !== undefined))];
+        // 3. Batch fetch all parent tasks
+        const taskResults = await Promise.all(taskIds.map(id => this.getItem(id)));
+        const taskMap = new Map();
+        for (const result of taskResults) {
+            if (result.item)
+                taskMap.set(result.item.id, result.item);
+        }
+        // 4. Optionally fetch grandparent projects
+        let projectMap = new Map();
+        if (options?.includeProject) {
+            const projectIds = [...new Set([...taskMap.values()].map(t => t.parentId).filter((id) => id !== undefined))];
+            const projectResults = await Promise.all(projectIds.map(id => this.getItem(id)));
+            for (const result of projectResults) {
+                if (result.item)
+                    projectMap.set(result.item.id, result.item);
+            }
+        }
+        // 5. Merge context into assignments
+        return {
+            assignments: assignments.map(a => {
+                const task = a.parentId ? taskMap.get(a.parentId) : undefined;
+                const project = task?.parentId ? projectMap.get(task.parentId) : undefined;
+                return {
+                    ...a,
+                    taskName: task?.name ?? '-',
+                    projectName: project?.name,
+                };
+            }),
+        };
+    }
     // ============================================================================
     // Cost Codes
     // ============================================================================
@@ -321,4 +370,67 @@ export class LPClient {
             return { success: false, error: getErrorMessage(error) };
         }
     }
+    /**
+     * Create or update a timesheet entry (upsert)
+     *
+     * Checks for an existing entry first. If found, updates it (accumulating
+     * hours by default). If not found, creates a new entry.
+     *
+     * This follows the proven "fetch first" pattern from the CLI.
+     *
+     * By default, hours are accumulated (added to existing). Set `accumulate: false`
+     * to replace existing hours instead.
+     *
+     * **Note behavior:** Notes are appended to existing notes by the LP API.
+     * Pass an empty string to avoid adding notes on update.
+     *
+     * @example
+     * ```typescript
+     * // Accumulate hours (default)
+     * await client.upsertTimesheetEntry({
+     *   date: '2026-01-29',
+     *   itemId: 12345,
+     *   hours: 1.5,
+     *   note: 'Timer session'
+     * });
+     *
+     * // Replace hours instead of accumulating
+     * await client.upsertTimesheetEntry(
+     *   { date: '2026-01-29', itemId: 12345, hours: 4.0 },
+     *   { accumulate: false }
+     * );
+     * ```
+     *
+     * @param entry - The timesheet entry to create or update
+     * @param options - Upsert options (accumulate defaults to true)
+     */
+    async upsertTimesheetEntry(entry, options = {}) {
+        const { accumulate = true } = options;
+        // Fetch existing entries for this date/item first
+        const { entries, error: fetchError } = await this.getTimesheetEntries(entry.date, entry.itemId);
+        if (fetchError) {
+            return { success: false, error: fetchError };
+        }
+        // Find matching entry
+        // If no costCodeId specified, match any entry (LP uses assignment's default)
+        // If costCodeId specified, match exactly
+        const existingEntry = entries?.find((e) => {
+            if (entry.costCodeId === undefined || entry.costCodeId === null) {
+                return true;
+            }
+            return e.costCodeId === entry.costCodeId;
+        });
+        if (existingEntry) {
+            // Update existing entry
+            const newHours = accumulate
+                ? existingEntry.hours + entry.hours
+                : entry.hours;
+            return this.updateTimesheetEntry(existingEntry.id, existingEntry, {
+                hours: newHours,
+                note: entry.note,
+            });
+        }
+        // No existing entry, create new
+        return this.createTimesheetEntry(entry);
+    }
 }

package/dist/index.d.ts

@@ -28,7 +28,7 @@
  */
 export { LPClient } from './client.js';
 export { resolveTaskToAssignment } from './workflows.js';
-export type { LPConfig, LPItemType, LPItem, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, } from './types.js';
+export type { LPConfig, LPItemType, LPItem, LPWorkspace, LPMember, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId, LPTaskResolution, LPResult, LPUpsertOptions, LPAssignmentWithContext, } from './types.js';
 export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
 export type { PaginateOptions } from './utils.js';
 export { LP_API_BASE, DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME, } from './constants.js';

package/dist/types.d.ts

@@ -136,3 +136,26 @@ export interface LPResult<T> {
     /** Error message if failed */
     error?: string;
 }
+/**
+ * Options for upsert timesheet entry operation
+ */
+export interface LPUpsertOptions {
+    /**
+     * Whether to accumulate hours with existing entry (default: true)
+     * - true: Add new hours to existing hours
+     * - false: Replace existing hours with new hours
+     */
+    accumulate?: boolean;
+}
+/**
+ * Assignment with resolved parent context
+ *
+ * Extends LPItem with additional fields for the parent task name,
+ * grandparent project name, and cost code name.
+ */
+export interface LPAssignmentWithContext extends LPItem {
+    /** Parent task name */
+    taskName?: string;
+    /** Grandparent project name (if requested) */
+    projectName?: string;
+}

package/package.json

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