@markwharton/liquidplanner 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,135 @@
+/**
+ * LiquidPlanner API Client
+ *
+ * Provides methods for interacting with the LiquidPlanner API.
+ * Uses Bearer Token authentication.
+ *
+ * @see https://api-docs.liquidplanner.com/
+ */
+import type { LPConfig, LPWorkspace, LPMember, LPItem, LPCostCode, LPSyncResult, LPTimesheetEntry, LPTimesheetEntryWithId } from './types.js';
+/**
+ * LiquidPlanner API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
+ *
+ * // Validate credentials
+ * const validation = await client.validateToken();
+ *
+ * // Get workspaces
+ * const workspaces = await client.getWorkspaces();
+ *
+ * // Log time
+ * await client.createTimesheetEntry({
+ *   date: '2026-01-29',
+ *   itemId: 12345,
+ *   hours: 2.5,
+ *   note: 'Working on feature'
+ * });
+ * ```
+ */
+export declare class LPClient {
+    private readonly apiToken;
+    private readonly workspaceId;
+    private readonly baseUrl;
+    constructor(config: LPConfig);
+    /**
+     * Make an authenticated request to the LP API
+     */
+    private fetch;
+    /**
+     * Validate the API token by listing workspaces
+     */
+    validateToken(): Promise<{
+        valid: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get all workspaces accessible to the API token
+     */
+    getWorkspaces(): Promise<{
+        workspaces?: LPWorkspace[];
+        error?: string;
+    }>;
+    /**
+     * Get all members in the workspace (with pagination)
+     */
+    getWorkspaceMembers(): Promise<{
+        members?: LPMember[];
+        error?: string;
+    }>;
+    /**
+     * Get a single item by ID
+     */
+    getItem(itemId: number): Promise<{
+        item?: LPItem;
+        error?: string;
+    }>;
+    /**
+     * Find all assignments under a task (with pagination)
+     */
+    findAssignments(taskId: number): Promise<{
+        assignments?: LPItem[];
+        error?: string;
+    }>;
+    /**
+     * Get all assignments for a specific member
+     *
+     * This enables PWA apps to show a task picker populated from LP directly.
+     * Note: userId is not a supported filter field in the LP API, so we filter client-side.
+     */
+    getMyAssignments(memberId: number): Promise<{
+        assignments?: LPItem[];
+        error?: string;
+    }>;
+    /**
+     * Get all cost codes in the workspace (with pagination)
+     */
+    getCostCodes(): Promise<{
+        costCodes?: LPCostCode[];
+        error?: string;
+    }>;
+    /**
+     * Create a timesheet entry (log time)
+     *
+     * Uses the Logged Time Entries API to create time entries.
+     * POST /api/workspaces/{workspaceId}/logged-time-entries/v1
+     */
+    createTimesheetEntry(entry: LPTimesheetEntry): Promise<LPSyncResult>;
+    /**
+     * Get timesheet entries for a specific date
+     *
+     * Uses the Logged Time Entries API to query existing entries.
+     * GET /api/workspaces/{workspaceId}/logged-time-entries/v1?date[in]=["{date}"]&itemId[is]="{itemId}"
+     *
+     * @see https://api-docs.liquidplanner.com/docs/task-status-1
+     *
+     * @param date - Date in YYYY-MM-DD format
+     * @param itemId - Optional item ID to filter by
+     */
+    getTimesheetEntries(date: string, itemId?: number): Promise<{
+        entries?: LPTimesheetEntryWithId[];
+        error?: string;
+    }>;
+    /**
+     * Update an existing timesheet entry
+     *
+     * Uses the Logged Time Entries API to update an entry.
+     * PUT /api/workspaces/{workspaceId}/logged-time-entries/v1/{entryId}
+     *
+     * **API Quirk:** Field behaviors are inconsistent in this endpoint:
+     * - `loggedEntriesInMinutes`: Replaces existing value (absolute)
+     * - `note`: Appended to existing value by the API
+     *
+     * To avoid note duplication, pass empty string when not updating notes.
+     * To accumulate time, compute the new total client-side before calling.
+     *
+     * @see https://api-docs.liquidplanner.com/reference/updateloggedentry
+     *
+     * @param entryId - The ID of the entry to update
+     * @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>;
+}

package/dist/client.js

@@ -0,0 +1,324 @@
+/**
+ * LiquidPlanner API Client
+ *
+ * Provides methods for interacting with the LiquidPlanner API.
+ * Uses Bearer Token authentication.
+ *
+ * @see https://api-docs.liquidplanner.com/
+ */
+import { buildAuthHeader, hoursToMinutes, normalizeItemType, filterIs, filterIn, paginatedFetch, } from './utils.js';
+import { parseLPErrorResponse, getErrorMessage } from './errors.js';
+import { LP_API_BASE, DEFAULT_ITEM_NAME } from './constants.js';
+/** Transform raw API item to LPItem */
+function transformItem(raw) {
+    return {
+        id: raw.id,
+        name: raw.name || DEFAULT_ITEM_NAME,
+        itemType: normalizeItemType(raw.itemType),
+        parentId: raw.parentId,
+        costCodeId: raw.costCodeId,
+        userId: raw.userId,
+    };
+}
+/**
+ * LiquidPlanner API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
+ *
+ * // Validate credentials
+ * const validation = await client.validateToken();
+ *
+ * // Get workspaces
+ * const workspaces = await client.getWorkspaces();
+ *
+ * // Log time
+ * await client.createTimesheetEntry({
+ *   date: '2026-01-29',
+ *   itemId: 12345,
+ *   hours: 2.5,
+ *   note: 'Working on feature'
+ * });
+ * ```
+ */
+export class LPClient {
+    constructor(config) {
+        this.apiToken = config.apiToken;
+        this.workspaceId = config.workspaceId;
+        this.baseUrl = config.baseUrl ?? LP_API_BASE;
+    }
+    /**
+     * Make an authenticated request to the LP API
+     */
+    async fetch(url, options = {}) {
+        const { method = 'GET', body } = options;
+        return fetch(url, {
+            method,
+            headers: {
+                Authorization: buildAuthHeader(this.apiToken),
+                'Content-Type': 'application/json',
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+    }
+    // ============================================================================
+    // Workspace & Validation
+    // ============================================================================
+    /**
+     * Validate the API token by listing workspaces
+     */
+    async validateToken() {
+        const url = `${this.baseUrl}/workspaces/v1`;
+        try {
+            const response = await this.fetch(url);
+            if (response.ok) {
+                return { valid: true };
+            }
+            if (response.status === 401 || response.status === 403) {
+                return { valid: false, error: 'Invalid or expired API token' };
+            }
+            return { valid: false, error: `Unexpected response: HTTP ${response.status}` };
+        }
+        catch (error) {
+            return { valid: false, error: getErrorMessage(error) || 'Connection failed' };
+        }
+    }
+    /**
+     * Get all workspaces accessible to the API token
+     */
+    async getWorkspaces() {
+        const url = `${this.baseUrl}/workspaces/v1`;
+        try {
+            const response = await this.fetch(url);
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message } = parseLPErrorResponse(errorText, response.status);
+                return { error: message };
+            }
+            const result = await response.json();
+            const workspaces = (result.data || []).map(ws => ({
+                id: ws.id,
+                name: ws.name,
+            }));
+            return { workspaces };
+        }
+        catch (error) {
+            return { error: getErrorMessage(error) };
+        }
+    }
+    // ============================================================================
+    // Members
+    // ============================================================================
+    /**
+     * Get all members in the workspace (with pagination)
+     */
+    async getWorkspaceMembers() {
+        const baseUrl = `${this.baseUrl}/users/v1?${filterIs('workspaceId', this.workspaceId)}`;
+        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 };
+    }
+    // ============================================================================
+    // Items
+    // ============================================================================
+    /**
+     * 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 } = parseLPErrorResponse(errorText, response.status);
+                return { error: message };
+            }
+            const result = await response.json();
+            if (!result.data || result.data.length === 0) {
+                return { error: `Item ${itemId} not found` };
+            }
+            return { item: transformItem(result.data[0]) };
+        }
+        catch (error) {
+            return { error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Find all assignments under a task (with pagination)
+     */
+    async findAssignments(taskId) {
+        // parentId[is]="{taskId}"&itemType[is]="assignments" (LP API uses lowercase plural)
+        const baseUrl = `${this.baseUrl}/workspaces/${this.workspaceId}/items/v1?${filterIs('parentId', taskId)}&${filterIs('itemType', 'assignments')}`;
+        const { results, error } = await paginatedFetch({
+            fetchFn: (url) => this.fetch(url),
+            baseUrl,
+            transform: (data) => data.map(transformItem),
+        });
+        return error ? { error } : { assignments: results };
+    }
+    /**
+     * Get all assignments for a specific member
+     *
+     * This enables PWA apps to show a task picker populated from LP directly.
+     * 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 error ? { error } : { assignments: results };
+    }
+    // ============================================================================
+    // Cost Codes
+    // ============================================================================
+    /**
+     * 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 error ? { error } : { costCodes: results };
+    }
+    // ============================================================================
+    // Timesheet
+    // ============================================================================
+    /**
+     * Create a timesheet entry (log time)
+     *
+     * Uses the Logged Time Entries API to create time entries.
+     * POST /api/workspaces/{workspaceId}/logged-time-entries/v1
+     */
+    async createTimesheetEntry(entry) {
+        const { date, itemId, hours, costCodeId, note } = entry;
+        const url = `${this.baseUrl}/workspaces/${this.workspaceId}/logged-time-entries/v1`;
+        // Build request body according to LP Logged Time Entries API
+        const body = {
+            date,
+            loggedEntriesInMinutes: hoursToMinutes(hours),
+            itemId,
+        };
+        // Add optional cost code
+        if (costCodeId) {
+            body.costCodeId = costCodeId;
+        }
+        // Add optional note
+        if (note) {
+            body.note = note;
+        }
+        try {
+            const response = await this.fetch(url, { method: 'POST', body });
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message, isDuplicate } = parseLPErrorResponse(errorText, response.status);
+                return { success: false, error: message, isDuplicate };
+            }
+            const result = await response.json();
+            return { success: true, entryId: result.id };
+        }
+        catch (error) {
+            return { success: false, error: getErrorMessage(error) };
+        }
+    }
+    /**
+     * Get timesheet entries for a specific date
+     *
+     * Uses the Logged Time Entries API to query existing entries.
+     * GET /api/workspaces/{workspaceId}/logged-time-entries/v1?date[in]=["{date}"]&itemId[is]="{itemId}"
+     *
+     * @see https://api-docs.liquidplanner.com/docs/task-status-1
+     *
+     * @param date - Date in YYYY-MM-DD format
+     * @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,
+            })),
+        });
+        return error ? { error } : { entries: results };
+    }
+    /**
+     * Update an existing timesheet entry
+     *
+     * Uses the Logged Time Entries API to update an entry.
+     * PUT /api/workspaces/{workspaceId}/logged-time-entries/v1/{entryId}
+     *
+     * **API Quirk:** Field behaviors are inconsistent in this endpoint:
+     * - `loggedEntriesInMinutes`: Replaces existing value (absolute)
+     * - `note`: Appended to existing value by the API
+     *
+     * To avoid note duplication, pass empty string when not updating notes.
+     * To accumulate time, compute the new total client-side before calling.
+     *
+     * @see https://api-docs.liquidplanner.com/reference/updateloggedentry
+     *
+     * @param entryId - The ID of the entry to update
+     * @param existingEntry - The existing entry (needed because PUT requires all fields)
+     * @param updates - Fields to update (merged with existing)
+     */
+    async updateTimesheetEntry(entryId, existingEntry, updates) {
+        const url = `${this.baseUrl}/workspaces/${this.workspaceId}/logged-time-entries/v1/${entryId}`;
+        // PUT requires all fields - merge updates with existing entry
+        // IMPORTANT: LP API appends the note field, so only send new notes
+        // If no new note, send empty string to avoid re-appending existing notes
+        const body = {
+            id: entryId,
+            date: updates.date ?? existingEntry.date,
+            itemId: updates.itemId ?? existingEntry.itemId,
+            loggedEntriesInMinutes: hoursToMinutes(updates.hours ?? existingEntry.hours),
+            costCodeId: updates.costCodeId ?? existingEntry.costCodeId,
+            note: updates.note ?? '',
+            userId: existingEntry.userId,
+        };
+        try {
+            const response = await this.fetch(url, { method: 'PUT', body });
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message } = parseLPErrorResponse(errorText, response.status);
+                return { success: false, error: message };
+            }
+            return { success: true, entryId };
+        }
+        catch (error) {
+            return { success: false, error: getErrorMessage(error) };
+        }
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * LiquidPlanner Constants
+ *
+ * Centralized constants used across the library.
+ */
+/** Default LP API base URL */
+export declare const LP_API_BASE = "https://next.liquidplanner.com/api";
+/** Default name for items when not available */
+export declare const DEFAULT_ITEM_NAME = "-";
+/** Default name for assignments when not available */
+export declare const DEFAULT_ASSIGNMENT_NAME = "-";

package/dist/constants.js

@@ -0,0 +1,11 @@
+/**
+ * LiquidPlanner Constants
+ *
+ * Centralized constants used across the library.
+ */
+/** Default LP API base URL */
+export const LP_API_BASE = 'https://next.liquidplanner.com/api';
+/** Default name for items when not available */
+export const DEFAULT_ITEM_NAME = '-';
+/** Default name for assignments when not available */
+export const DEFAULT_ASSIGNMENT_NAME = '-';

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * LiquidPlanner Error Handling
+ *
+ * LP returns errors in various formats:
+ * - {"errors":[{"title":"...","detail":"...","code":"..."}]}
+ * - {"message":"..."} or {"error":"..."}
+ * - Plain text
+ */
+/**
+ * Parsed LP error response
+ */
+export interface LPParsedError {
+    /** Human-readable error message */
+    message: string;
+    /** Whether this error indicates a duplicate entry */
+    isDuplicate?: boolean;
+}
+/**
+ * Parse LP API error response text into a human-readable message.
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code
+ * @returns Parsed error with message and optional duplicate flag
+ */
+export declare function parseLPErrorResponse(errorText: string, statusCode: number): LPParsedError;
+/**
+ * Custom error class for LP API errors
+ */
+export declare class LPError extends Error {
+    /** HTTP status code */
+    statusCode: number;
+    /** Whether this is a duplicate entry error */
+    isDuplicate: boolean;
+    /** Raw error response */
+    rawResponse?: string;
+    constructor(message: string, statusCode: number, options?: {
+        isDuplicate?: boolean;
+        rawResponse?: string;
+    });
+    /**
+     * Create an LPError from an API response
+     */
+    static fromResponse(statusCode: number, responseText: string): LPError;
+}
+/**
+ * Get a safe error message from any error type
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/errors.js

@@ -0,0 +1,70 @@
+/**
+ * LiquidPlanner Error Handling
+ *
+ * LP returns errors in various formats:
+ * - {"errors":[{"title":"...","detail":"...","code":"..."}]}
+ * - {"message":"..."} or {"error":"..."}
+ * - Plain text
+ */
+/** Error code for duplicate entry errors */
+const LP_ERROR_CODE_DUPLICATE = 'duplicate_value';
+/** Default error message when none is available */
+const DEFAULT_ERROR_MESSAGE = 'Unknown error';
+/**
+ * Parse LP API error response text into a human-readable message.
+ *
+ * @param errorText - Raw error response text
+ * @param statusCode - HTTP status code
+ * @returns Parsed error with message and optional duplicate flag
+ */
+export function parseLPErrorResponse(errorText, statusCode) {
+    try {
+        const errorJson = JSON.parse(errorText);
+        // LP returns errors array with structured error objects
+        if (errorJson.errors && Array.isArray(errorJson.errors)) {
+            const isDuplicate = errorJson.errors.some((err) => err.code === LP_ERROR_CODE_DUPLICATE);
+            const firstError = errorJson.errors[0];
+            const message = firstError?.detail || firstError?.title || `HTTP ${statusCode}`;
+            return { message, isDuplicate };
+        }
+        // Fallback to message/error fields
+        return {
+            message: errorJson.message || errorJson.error || `HTTP ${statusCode}`,
+        };
+    }
+    catch {
+        // Not JSON, return as-is or fallback
+        return { message: errorText || `HTTP ${statusCode}` };
+    }
+}
+/**
+ * Custom error class for LP API errors
+ */
+export class LPError extends Error {
+    constructor(message, statusCode, options) {
+        super(message);
+        this.name = 'LPError';
+        this.statusCode = statusCode;
+        this.isDuplicate = options?.isDuplicate ?? false;
+        this.rawResponse = options?.rawResponse;
+    }
+    /**
+     * Create an LPError from an API response
+     */
+    static fromResponse(statusCode, responseText) {
+        const parsed = parseLPErrorResponse(responseText, statusCode);
+        return new LPError(parsed.message, statusCode, {
+            isDuplicate: parsed.isDuplicate,
+            rawResponse: responseText,
+        });
+    }
+}
+/**
+ * Get a safe error message from any error type
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return DEFAULT_ERROR_MESSAGE;
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @markwharton/liquidplanner
+ *
+ * LiquidPlanner API client for timesheet integration.
+ *
+ * @example
+ * ```typescript
+ * import { LPClient, resolveTaskToAssignment } from '@markwharton/liquidplanner';
+ *
+ * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
+ *
+ * // Validate credentials
+ * await client.validateToken();
+ *
+ * // Get workspaces
+ * const { workspaces } = await client.getWorkspaces();
+ *
+ * // Resolve task to assignment
+ * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
+ *
+ * // Log time
+ * await client.createTimesheetEntry({
+ *   date: '2026-01-29',
+ *   itemId: resolution.assignmentId,
+ *   hours: 2.5
+ * });
+ * ```
+ */
+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 { 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';
+export { LPError, parseLPErrorResponse, getErrorMessage } from './errors.js';
+export type { LPParsedError } from './errors.js';

package/dist/index.js

@@ -0,0 +1,38 @@
+/**
+ * @markwharton/liquidplanner
+ *
+ * LiquidPlanner API client for timesheet integration.
+ *
+ * @example
+ * ```typescript
+ * import { LPClient, resolveTaskToAssignment } from '@markwharton/liquidplanner';
+ *
+ * const client = new LPClient({ apiToken: 'xxx', workspaceId: 123 });
+ *
+ * // Validate credentials
+ * await client.validateToken();
+ *
+ * // Get workspaces
+ * const { workspaces } = await client.getWorkspaces();
+ *
+ * // Resolve task to assignment
+ * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
+ *
+ * // Log time
+ * await client.createTimesheetEntry({
+ *   date: '2026-01-29',
+ *   itemId: resolution.assignmentId,
+ *   hours: 2.5
+ * });
+ * ```
+ */
+// Main client
+export { LPClient } from './client.js';
+// Workflows
+export { resolveTaskToAssignment } from './workflows.js';
+// Utilities
+export { hoursToMinutes, normalizeItemType, buildAuthHeader, filterIs, filterIn, paginatedFetch, } from './utils.js';
+// Constants
+export { LP_API_BASE, DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME, } from './constants.js';
+// Errors
+export { LPError, parseLPErrorResponse, getErrorMessage } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * LiquidPlanner Type Definitions
+ *
+ * These types define the data structures used when interacting with
+ * the LiquidPlanner API.
+ */
+/**
+ * LiquidPlanner item types in the hierarchy
+ */
+export type LPItemType = 'Task' | 'Assignment' | 'Folder' | 'Milestone' | 'Event';
+/**
+ * An item from LiquidPlanner (Task, Assignment, Folder, etc.)
+ */
+export interface LPItem {
+    /** Unique identifier */
+    id: number;
+    /** Display name */
+    name: string;
+    /** Type of item in LP hierarchy */
+    itemType: LPItemType;
+    /** Parent item ID (e.g., Assignment's parent is a Task) */
+    parentId?: number;
+    /** Cost code ID if assigned */
+    costCodeId?: number;
+    /** User ID this assignment is for (if Assignment type) */
+    userId?: number;
+}
+/**
+ * A cost code from LiquidPlanner
+ */
+export interface LPCostCode {
+    /** Unique identifier */
+    id: number;
+    /** Display name */
+    name: string;
+    /** Whether this cost code is billable */
+    billable: boolean;
+}
+/**
+ * A workspace from LiquidPlanner
+ */
+export interface LPWorkspace {
+    /** Unique identifier */
+    id: number;
+    /** Workspace name */
+    name: string;
+}
+/**
+ * A workspace member from LiquidPlanner
+ */
+export interface LPMember {
+    /** Unique identifier */
+    id: number;
+    /** Username (login name) */
+    username: string;
+    /** Email address */
+    email: string;
+    /** First name */
+    firstName: string;
+    /** Last name */
+    lastName: string;
+    /** User type (member, resource, or placeholder) */
+    userType: 'member' | 'resource' | 'placeholder';
+}
+/**
+ * Result of resolving an LP Item ID to the correct Assignment ID for logging time
+ */
+export interface LPTaskResolution {
+    /** The original item that was looked up */
+    inputItem: LPItem;
+    /** The Assignment ID to use for logging time (may be same as input if input was an Assignment) */
+    assignmentId: number;
+    /** Name of the assignment */
+    assignmentName?: string;
+    /** User ID the assignment belongs to (LP member ID) */
+    assignmentUserId?: number;
+    /** If Task had multiple Assignments, list them for user selection */
+    multipleAssignments?: LPItem[];
+    /** Error message if resolution failed */
+    error?: string;
+}
+/**
+ * LiquidPlanner configuration for API access
+ */
+export interface LPConfig {
+    /** 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;
+}
+/**
+ * Result of a timesheet sync operation
+ */
+export interface LPSyncResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** ID of the created entry (if successful) */
+    entryId?: number;
+    /** Error message (if failed) */
+    error?: string;
+    /** Whether the error was due to a duplicate entry */
+    isDuplicate?: boolean;
+}
+/**
+ * Input for a timesheet entry to sync
+ */
+export interface LPTimesheetEntry {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Item ID (should be an Assignment ID) */
+    itemId: number;
+    /** Hours worked (decimal) */
+    hours: number;
+    /** Optional cost code ID */
+    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 */
+    userId?: number;
+}
+/**
+ * Generic result wrapper for LP operations
+ */
+export interface LPResult<T> {
+    /** The data if successful */
+    data?: T;
+    /** Error message if failed */
+    error?: string;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * LiquidPlanner Type Definitions
+ *
+ * These types define the data structures used when interacting with
+ * the LiquidPlanner API.
+ */
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * LiquidPlanner Utility Functions
+ */
+import type { LPItemType } from './types.js';
+/**
+ * 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[in]=["value1","value2"]
+ */
+export declare function filterIn(field: string, values: (string | number)[]): string;
+/**
+ * Options for paginated fetch
+ */
+export interface PaginateOptions<TRaw, TResult> {
+    /** Authenticated fetch function */
+    fetchFn: (url: string) => Promise<Response>;
+    /** Base URL (without continuation token) */
+    baseUrl: string;
+    /** Transform raw API data to result type */
+    transform: (data: TRaw[]) => TResult[];
+    /** Optional filter to apply to each page */
+    filter?: (data: TRaw[]) => TRaw[];
+}
+/**
+ * Generic pagination helper for LP API endpoints
+ *
+ * Handles the continuation token pattern used by LP API.
+ */
+export declare function paginatedFetch<TRaw, TResult>(options: PaginateOptions<TRaw, TResult>): Promise<{
+    results?: TResult[];
+    error?: string;
+}>;
+/**
+ * Convert decimal hours to minutes
+ *
+ * @example
+ * hoursToMinutes(6.5)  // 390
+ * hoursToMinutes(2.25) // 135
+ * hoursToMinutes(0.5)  // 30
+ *
+ * @throws Error if hours is not a valid non-negative number
+ */
+export declare function hoursToMinutes(hours: number): number;
+/**
+ * Normalize LP API itemType values to internal format
+ *
+ * LP API returns lowercase plural (e.g., "tasks", "assignments")
+ * but our code uses PascalCase singular (e.g., "Task", "Assignment")
+ */
+export declare function normalizeItemType(apiItemType: string): LPItemType;
+/**
+ * Build the Authorization header for LP API requests
+ */
+export declare function buildAuthHeader(apiToken: string): string;

package/dist/utils.js

@@ -0,0 +1,99 @@
+/**
+ * LiquidPlanner Utility Functions
+ */
+import { parseLPErrorResponse, getErrorMessage } from './errors.js';
+// ============================================================================
+// LP API Filter Builders
+// ============================================================================
+/**
+ * Build a URL-encoded filter for LP API: field[is]="value"
+ */
+export function filterIs(field, value) {
+    return `${field}%5Bis%5D=%22${value}%22`;
+}
+/**
+ * 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(',');
+    return `${field}%5Bin%5D=%5B${encoded}%5D`;
+}
+/**
+ * Generic pagination helper for LP API endpoints
+ *
+ * Handles the continuation token pattern used by LP API.
+ */
+export async function paginatedFetch(options) {
+    const { fetchFn, baseUrl, transform, filter } = options;
+    const hasQueryParams = baseUrl.includes('?');
+    try {
+        const allResults = [];
+        let continuationToken;
+        do {
+            const url = continuationToken
+                ? `${baseUrl}${hasQueryParams ? '&' : '?'}continuationToken=${continuationToken}`
+                : baseUrl;
+            const response = await fetchFn(url);
+            if (!response.ok) {
+                const errorText = await response.text();
+                const { message } = parseLPErrorResponse(errorText, response.status);
+                return { error: message };
+            }
+            const result = await response.json();
+            const rawData = result.data || [];
+            const filteredData = filter ? filter(rawData) : rawData;
+            const pageResults = transform(filteredData);
+            allResults.push(...pageResults);
+            continuationToken = result.continuationToken;
+        } while (continuationToken);
+        return { results: allResults };
+    }
+    catch (error) {
+        return { error: getErrorMessage(error) };
+    }
+}
+/**
+ * Convert decimal hours to minutes
+ *
+ * @example
+ * hoursToMinutes(6.5)  // 390
+ * hoursToMinutes(2.25) // 135
+ * hoursToMinutes(0.5)  // 30
+ *
+ * @throws Error if hours is not a valid non-negative number
+ */
+export function hoursToMinutes(hours) {
+    if (!Number.isFinite(hours) || hours < 0) {
+        throw new Error(`Invalid hours value: ${hours}`);
+    }
+    return Math.round(hours * 60);
+}
+/**
+ * Normalize LP API itemType values to internal format
+ *
+ * LP API returns lowercase plural (e.g., "tasks", "assignments")
+ * but our code uses PascalCase singular (e.g., "Task", "Assignment")
+ */
+export function normalizeItemType(apiItemType) {
+    const mapping = {
+        // LP API lowercase plural format
+        'tasks': 'Task',
+        'assignments': 'Assignment',
+        'folders': 'Folder',
+        'milestones': 'Milestone',
+        'events': 'Event',
+        // Already-normalized values (for safety)
+        'Task': 'Task',
+        'Assignment': 'Assignment',
+        'Folder': 'Folder',
+        'Milestone': 'Milestone',
+        'Event': 'Event',
+    };
+    return mapping[apiItemType] || apiItemType;
+}
+/**
+ * Build the Authorization header for LP API requests
+ */
+export function buildAuthHeader(apiToken) {
+    return `Bearer ${apiToken}`;
+}

package/dist/workflows.d.ts

@@ -0,0 +1,40 @@
+/**
+ * LiquidPlanner Workflows
+ *
+ * Higher-level functions that combine multiple API calls to accomplish
+ * common tasks, like resolving a Task ID to the correct Assignment ID.
+ */
+import type { LPClient } from './client.js';
+import type { LPTaskResolution } from './types.js';
+/**
+ * Resolve an item ID to the correct Assignment ID for logging time
+ *
+ * LP hierarchy: Folder -> Task -> Assignment
+ * - User typically enters Task ID (what they see in LP UI)
+ * - API needs Assignment ID to log time
+ *
+ * Resolution logic:
+ * 1. If item is an Assignment -> use it directly
+ * 2. If item is a Task -> find Assignments underneath
+ *    - If lpMemberId is provided, filter to assignment matching that user
+ * 3. If item is a Folder -> error (can't log time to folders)
+ *
+ * @example
+ * ```typescript
+ * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
+ *
+ * if (resolution.error) {
+ *   console.error(resolution.error);
+ *   if (resolution.multipleAssignments) {
+ *     // Show picker UI for user to select
+ *   }
+ * } else {
+ *   await client.createTimesheetEntry({
+ *     date: '2026-01-29',
+ *     itemId: resolution.assignmentId,
+ *     hours: 2.5
+ *   });
+ * }
+ * ```
+ */
+export declare function resolveTaskToAssignment(client: LPClient, itemId: number, lpMemberId?: number): Promise<LPTaskResolution>;

package/dist/workflows.js

@@ -0,0 +1,136 @@
+/**
+ * LiquidPlanner Workflows
+ *
+ * Higher-level functions that combine multiple API calls to accomplish
+ * common tasks, like resolving a Task ID to the correct Assignment ID.
+ */
+import { DEFAULT_ITEM_NAME, DEFAULT_ASSIGNMENT_NAME } from './constants.js';
+/**
+ * Resolve an item ID to the correct Assignment ID for logging time
+ *
+ * LP hierarchy: Folder -> Task -> Assignment
+ * - User typically enters Task ID (what they see in LP UI)
+ * - API needs Assignment ID to log time
+ *
+ * Resolution logic:
+ * 1. If item is an Assignment -> use it directly
+ * 2. If item is a Task -> find Assignments underneath
+ *    - If lpMemberId is provided, filter to assignment matching that user
+ * 3. If item is a Folder -> error (can't log time to folders)
+ *
+ * @example
+ * ```typescript
+ * const resolution = await resolveTaskToAssignment(client, taskId, memberId);
+ *
+ * if (resolution.error) {
+ *   console.error(resolution.error);
+ *   if (resolution.multipleAssignments) {
+ *     // Show picker UI for user to select
+ *   }
+ * } else {
+ *   await client.createTimesheetEntry({
+ *     date: '2026-01-29',
+ *     itemId: resolution.assignmentId,
+ *     hours: 2.5
+ *   });
+ * }
+ * ```
+ */
+export async function resolveTaskToAssignment(client, itemId, lpMemberId) {
+    // Step 1: Fetch the item
+    const { item, error: fetchError } = await client.getItem(itemId);
+    if (fetchError || !item) {
+        return {
+            inputItem: { id: itemId, name: DEFAULT_ITEM_NAME, itemType: 'Task' },
+            assignmentId: 0,
+            error: fetchError || 'Item not found',
+        };
+    }
+    // Step 2: Check item type and resolve accordingly
+    switch (item.itemType) {
+        case 'Assignment':
+            // Already an assignment, use it directly
+            return {
+                inputItem: item,
+                assignmentId: item.id,
+                assignmentName: item.name || DEFAULT_ASSIGNMENT_NAME,
+                assignmentUserId: item.userId,
+            };
+        case 'Task': {
+            // Find assignments under this task
+            const { assignments, error: assignmentError } = await client.findAssignments(item.id);
+            if (assignmentError) {
+                return {
+                    inputItem: item,
+                    assignmentId: 0,
+                    error: `Failed to find assignments: ${assignmentError}`,
+                };
+            }
+            if (!assignments || assignments.length === 0) {
+                return {
+                    inputItem: item,
+                    assignmentId: 0,
+                    error: 'No assignments found for this task. Time can only be logged to assignments.',
+                };
+            }
+            if (assignments.length === 1) {
+                // Single assignment - use it
+                return {
+                    inputItem: item,
+                    assignmentId: assignments[0].id,
+                    assignmentName: assignments[0].name || DEFAULT_ASSIGNMENT_NAME,
+                    assignmentUserId: assignments[0].userId,
+                };
+            }
+            // Multiple assignments - try to filter by lpMemberId if provided
+            if (lpMemberId) {
+                const myAssignments = assignments.filter(a => a.userId === lpMemberId);
+                if (myAssignments.length === 1) {
+                    // Single match - auto-select
+                    return {
+                        inputItem: item,
+                        assignmentId: myAssignments[0].id,
+                        assignmentName: myAssignments[0].name || DEFAULT_ASSIGNMENT_NAME,
+                        assignmentUserId: myAssignments[0].userId,
+                    };
+                }
+                if (myAssignments.length > 1) {
+                    // Multiple matches for this user - let them choose
+                    return {
+                        inputItem: item,
+                        assignmentId: 0,
+                        error: 'Multiple assignments found for your user. Please select one.',
+                        multipleAssignments: myAssignments,
+                    };
+                }
+                // lpMemberId is set but no assignments match - don't show others' assignments
+                return {
+                    inputItem: item,
+                    assignmentId: 0,
+                    error: 'No assignments found for your configured LP Member ID.',
+                };
+            }
+            // No lpMemberId configured - show all for selection
+            return {
+                inputItem: item,
+                assignmentId: 0,
+                error: 'Multiple assignments found. Configure LP Member ID in settings to auto-select.',
+                multipleAssignments: assignments,
+            };
+        }
+        case 'Folder':
+        case 'Milestone':
+        case 'Event':
+            return {
+                inputItem: item,
+                assignmentId: 0,
+                error: `Cannot log time to a ${item.itemType}. Enter a Task or Assignment ID.`,
+            };
+        default:
+            return {
+                inputItem: item,
+                assignmentId: 0,
+                error: `Unsupported item type: ${item.itemType}`,
+            };
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@markwharton/liquidplanner",
+  "version": "1.0.0",
+  "description": "LiquidPlanner API client for timesheet integration",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarkWharton/api-packages.git",
+    "directory": "packages/liquidplanner"
+  },
+  "author": "Mark Wharton",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}