logwork-cli 1.1.0 → 1.2.0

package/lib/ro-api-entries.mjs

@@ -0,0 +1,359 @@
+// Logwork entries: reads (legacy GET, /logwork/day, weekly, rejected) and writes
+// (create, resubmit, delete). Writes honor LOGWORK_DRY_RUN.
+import { CONFIG, isDryRun } from './config.mjs';
+import { resolveWorklogTask } from './worklog-task-resolver.mjs';
+import { ApiError, apiFetch } from './ro-api-http.mjs';
+import { fetchWorklogTasksForProject } from './ro-api-tasks.mjs';
+import {
+  assertLogtimeId,
+  extractLogtimeRecord,
+  normalizeDateOnly,
+  preserveNumericId,
+  unwrapRecords
+} from './ro-api-fields.mjs';
+
+const LOGWORK_TYPE_OF_WORK = new Set(['create', 'correct', 'improve', 'other']);
+
+export async function getLogtimeById(token, logtimeId, options = {}) {
+  const path = `${CONFIG.memberLogtimePath}/${encodeURIComponent(assertLogtimeId(logtimeId, 'logtimeId'))}`;
+  const data = await apiFetch(token, path, options);
+  const record = extractLogtimeRecord(data);
+  if (!record) {
+    throw new ApiError(`Resource Optimiser did not return logwork ${logtimeId}.`, {
+      path
+    });
+  }
+  return normalizeEditableLogtime(record);
+}
+
+export async function createLogworkEntry(token, {
+  worklogTaskId,
+  projectId,
+  effortHours,
+  localDateISO,
+  typeOfWork = CONFIG.defaultTypeOfWork,
+  description,
+  needsProjectId = false
+}, options = {}) {
+  const normalizedTaskId = assertLogtimeId(worklogTaskId, 'worklogTaskId');
+  const normalizedProjectId = assertPositiveProjectId(projectId);
+  const normalizedHours = Number(effortHours);
+  const normalizedTypeOfWork = String(typeOfWork || CONFIG.defaultTypeOfWork).trim();
+  if (!Number.isFinite(normalizedHours) || normalizedHours <= 0) {
+    throw new Error('effortHours must be a positive number.');
+  }
+  if (!LOGWORK_TYPE_OF_WORK.has(normalizedTypeOfWork)) {
+    throw new Error(`typeOfWork must be one of: ${[...LOGWORK_TYPE_OF_WORK].join(', ')}.`);
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(localDateISO || ''))) {
+    throw new Error('localDateISO must use YYYY-MM-DD format.');
+  }
+
+  const path = CONFIG.logworkEntriesPath;
+  const body = {
+    worklog_task_id: preserveNumericId(normalizedTaskId),
+    effort_hours: normalizedHours,
+    logdate: localDateISO,
+    type_of_work: normalizedTypeOfWork
+  };
+  if (description !== undefined && description !== null && String(description).trim()) {
+    body.description = String(description).trim();
+  }
+  if (needsProjectId) {
+    body.project_id = preserveNumericId(normalizedProjectId);
+  }
+
+  if (isDryRun()) {
+    return {
+      dryRun: true,
+      method: 'POST',
+      path,
+      body
+    };
+  }
+
+  try {
+    const response = await apiFetch(token, path, {
+      ...options,
+      method: 'POST',
+      body: JSON.stringify(body)
+    });
+    const record = extractLogtimeRecord(response);
+    return {
+      dryRun: false,
+      entry: record ? normalizeEditableLogtime(record) : null,
+      response
+    };
+  } catch (error) {
+    throw mapLogworkEntryApiError(error);
+  }
+}
+
+export async function getLogworkDay(token, { date, projectId } = {}, options = {}) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date || ''))) {
+    throw new Error('date must use YYYY-MM-DD format.');
+  }
+  const qs = new URLSearchParams({ date });
+  if (projectId !== undefined && projectId !== null && projectId !== '') {
+    qs.set('project_id', String(projectId));
+  }
+  const data = await apiFetch(token, `${CONFIG.logworkDayPath}?${qs}`, options);
+  return normalizeLogworkDayPayload(unwrapLogworkObject(data));
+}
+
+export async function getLogworkWeekly(token, { weekStart } = {}, options = {}) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(weekStart || ''))) {
+    throw new Error('weekStart must use YYYY-MM-DD format.');
+  }
+  const qs = new URLSearchParams({ week_start: weekStart });
+  const data = await apiFetch(token, `${CONFIG.logworkWeeklyPath}?${qs}`, options);
+  return normalizeLogworkWeeklyPayload(unwrapLogworkObject(data));
+}
+
+export async function getLogworkRejected(token, options = {}) {
+  const data = await apiFetch(token, CONFIG.logworkRejectedPath, options);
+  return unwrapRecords(data).map(normalizeLogworkF03Entry);
+}
+
+export async function resubmitLogworkEntry(token, entryId, {
+  effortHours,
+  typeOfWork = CONFIG.defaultTypeOfWork,
+  noteToPm,
+  description
+}, options = {}) {
+  const id = assertLogtimeId(entryId, 'entryId');
+  const normalizedHours = Number(effortHours);
+  const normalizedTypeOfWork = String(typeOfWork || CONFIG.defaultTypeOfWork).trim();
+  if (!Number.isFinite(normalizedHours) || normalizedHours <= 0) {
+    throw new Error('effortHours must be a positive number.');
+  }
+  if (!LOGWORK_TYPE_OF_WORK.has(normalizedTypeOfWork)) {
+    throw new Error(`typeOfWork must be one of: ${[...LOGWORK_TYPE_OF_WORK].join(', ')}.`);
+  }
+
+  const path = `${CONFIG.logworkEntriesPath}/${encodeURIComponent(String(id))}/resubmit`;
+  const body = {
+    effort_hours: normalizedHours,
+    type_of_work: normalizedTypeOfWork
+  };
+  if (noteToPm !== undefined && String(noteToPm).trim()) {
+    body.note_to_pm = String(noteToPm).trim();
+  }
+  if (description !== undefined && String(description).trim()) {
+    body.description = String(description).trim();
+  }
+
+  if (isDryRun()) {
+    return { dryRun: true, method: 'PATCH', path, body };
+  }
+
+  try {
+    const response = await apiFetch(token, path, {
+      ...options,
+      method: 'PATCH',
+      body: JSON.stringify(body)
+    });
+    const record = extractLogtimeRecord(response);
+    return {
+      dryRun: false,
+      entry: record ? normalizeLogworkF03Entry(record) : null,
+      response
+    };
+  } catch (error) {
+    throw mapLogworkEntryApiError(error);
+  }
+}
+
+export async function deleteLogworkEntry(token, entryId, options = {}) {
+  const id = assertLogtimeId(entryId, 'entryId');
+  const path = `${CONFIG.logworkEntriesPath}/${encodeURIComponent(String(id))}`;
+
+  if (isDryRun()) {
+    return { dryRun: true, method: 'DELETE', path };
+  }
+
+  try {
+    const response = await apiFetch(token, path, {
+      ...options,
+      method: 'DELETE'
+    });
+    return { dryRun: false, response };
+  } catch (error) {
+    throw mapLogworkEntryApiError(error);
+  }
+}
+
+export function normalizeLogworkF03Entry(record = {}) {
+  const base = normalizeEditableLogtime(record);
+  return {
+    ...base,
+    typeOfWork: record.type_of_work ?? record.typeOfWork ?? '',
+    worklogTaskId: record.worklog_task_id ?? record.worklogTaskId ?? null,
+    description: record.description ?? '',
+    rejectionComment: record.rejection_comment ?? record.rejectionComment ?? '',
+    noteToPm: record.note_to_pm ?? record.noteToPm ?? ''
+  };
+}
+
+function normalizeLogworkDayPayload(payload = {}) {
+  const entries = Array.isArray(payload.entries)
+    ? payload.entries.map(normalizeLogworkF03Entry)
+    : [];
+  return {
+    date: normalizeDateOnly(payload.date) || '',
+    entries,
+    isLocked: Boolean(payload.isLocked ?? payload.is_locked),
+    isProjectClosed: Boolean(payload.isProjectClosed ?? payload.is_project_closed),
+    leaveRequests: Array.isArray(payload.leaveRequests) ? payload.leaveRequests : []
+  };
+}
+
+function normalizeLogworkWeeklyPayload(payload = {}) {
+  return {
+    weekStart: normalizeDateOnly(payload.weekStart ?? payload.week_start) || '',
+    isLocked: Boolean(payload.isLocked ?? payload.is_locked),
+    projects: Array.isArray(payload.projects) ? payload.projects : [],
+    missingDays: Array.isArray(payload.missingDays) ? payload.missingDays : [],
+    weeklyTotals: payload.weeklyTotals ?? payload.weekly_totals ?? null
+  };
+}
+
+function unwrapLogworkObject(data) {
+  if (data?.data && typeof data.data === 'object' && !Array.isArray(data.data)) {
+    return data.data;
+  }
+  if (data && typeof data === 'object' && !Array.isArray(data)) {
+    return data;
+  }
+  return {};
+}
+
+export async function addLogtime(token, entry, options = {}) {
+  const {
+    projectMemberId: _projectMemberId,
+    projectId,
+    logtimes,
+    taskName,
+    localDateISO,
+    typeOfWork,
+    description,
+    worklogTaskId,
+    worklogNeedsProjectId,
+    taskCache
+  } = entry || {};
+
+  const normalizedHours = Number(logtimes);
+  const normalizedTaskName = String(taskName ?? '').trim();
+  if (!Number.isFinite(normalizedHours) || normalizedHours <= 0) {
+    throw new Error('logtimes must be a positive number.');
+  }
+  if (!normalizedTaskName) {
+    throw new Error('taskName must not be empty.');
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(localDateISO || ''))) {
+    throw new Error('localDateISO must use YYYY-MM-DD format.');
+  }
+
+  const normalizedProjectId = assertPositiveProjectId(projectId);
+  let resolvedTaskId = worklogTaskId;
+  let needsProjectId = worklogNeedsProjectId;
+
+  if (resolvedTaskId === undefined || resolvedTaskId === null) {
+    const tasks = await fetchWorklogTasksForProject(token, normalizedProjectId, {
+      cache: taskCache,
+      ...options
+    });
+    const resolution = resolveWorklogTask({
+      taskName: normalizedTaskName,
+      projectId: normalizedProjectId,
+      tasks
+    });
+    resolvedTaskId = resolution.worklogTaskId;
+    needsProjectId = resolution.needsProjectId;
+  }
+
+  return createLogworkEntry(token, {
+    worklogTaskId: resolvedTaskId,
+    projectId: normalizedProjectId,
+    effortHours: normalizedHours,
+    localDateISO,
+    typeOfWork,
+    description,
+    needsProjectId: Boolean(needsProjectId)
+  }, options);
+}
+
+function assertPositiveProjectId(projectId, label = 'projectId') {
+  const normalized = Number(projectId);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error(`${label} must be a positive number.`);
+  }
+  return normalized;
+}
+
+function mapLogworkEntryApiError(error) {
+  if (!(error instanceof ApiError)) {
+    return error;
+  }
+
+  const bodyText = String(error.body || '');
+  const knownMessages = [
+    ['TASK_OR_PROJECT_NOT_FOUND', 'Worklog task or project was not found. Check project_id and worklog_task_id.'],
+    ['HOLIDAY_BLOCKED', 'Logwork is blocked on this date (holiday).'],
+    ['NOT_MEMBER_OF_PROJECT', 'You are not a member of this project.'],
+    ['INVALID_EFFORT', 'Effort hours must be greater than 0.'],
+    ['EFFORT_EXCEEDS_24', 'Effort cannot exceed 24 hours per entry.'],
+    ['ENTRY_NOT_FOUND', 'Logwork entry was not found or is already deleted.'],
+    ['FORBIDDEN', 'You can only delete or change logwork entries you created.']
+  ];
+
+  for (const [code, message] of knownMessages) {
+    if (bodyText.includes(code)) {
+      return new ApiError(message, {
+        status: error.status,
+        path: error.path,
+        body: error.body
+      });
+    }
+  }
+
+  if (bodyText.includes('Can only delete unprocessed entries')) {
+    return new ApiError('Only submitted or approved entries can be deleted. Rejected entries must be resubmitted or edited.', {
+      status: error.status,
+      path: error.path,
+      body: error.body
+    });
+  }
+
+  if (bodyText.includes('LOCKED') || bodyText.includes('locked')) {
+    return new ApiError('This log date is locked and cannot be edited.', {
+      status: error.status,
+      path: error.path,
+      body: error.body
+    });
+  }
+
+  return error;
+}
+
+export function normalizeEditableLogtime(record = {}) {
+  const hours = Number(record.logtimes ?? record.hours ?? record.effort_hours ?? record.time);
+  return {
+    id: record.id ?? record.logtime_id ?? record.logtimeId,
+    projectMemberId: record.project_member_id ?? record.projectMemberId,
+    projectId: record.project_id ?? record.projectId ?? record.project?.id,
+    projectName: record.project_name ?? record.projectName ?? record.project?.name ?? '',
+    date: normalizeDateOnly(record.logdate ?? record.log_date ?? record.date),
+    hours: Number.isFinite(hours) ? hours : 0,
+    taskName: record.task_name ?? record.taskName ?? record.name ?? record.title ?? '',
+    createdBy: record.created_by ?? record.createdBy,
+    updatedBy: record.updated_by ?? record.updatedBy,
+    updatedDate: record.updated_date ?? record.updatedDate ?? '',
+    jiraLogworkId: record.jira_logwork_id ?? record.jiraLogworkId ?? null,
+    referrerUrl: record.referrer_url ?? record.referrerUrl ?? null,
+    source: record.source ?? '',
+    status: record.status ?? '',
+    isLocked: Boolean(record.is_locked ?? record.isLocked),
+    raw: record
+  };
+}

package/lib/ro-api-fields.mjs

@@ -0,0 +1,290 @@
+// Readers for loosely shaped Resource Optimiser responses. Each reader tries a list
+// of candidate field paths; extend those lists rather than hard-coding one shape.
+import { addWarning, diagnosticProjectFields } from './ro-api-diagnostics.mjs';
+
+export function readProjectMemberId(row) {
+  const explicit = readExplicitProjectMemberId(row);
+
+  if (explicit !== undefined) {
+    return explicit;
+  }
+
+  if (looksLikeProjectMemberRow(row)) {
+    return row.id;
+  }
+
+  return undefined;
+}
+
+export function readExplicitProjectMemberId(row) {
+  return pickFirst(row, [
+    'project_member_id',
+    'projectMemberId',
+    'project_member.id',
+    'projectMember.id'
+  ]);
+}
+
+export function readProjectId(row) {
+  return pickFirst(row, [
+    'project_id',
+    'projectId',
+    'project.id',
+    'project.project_id',
+    'projectMember.project_id',
+    'project_member.project_id'
+  ]);
+}
+
+export function readProjectName(row, fallbackId, diagnostics = null, context = {}) {
+  const projectName = pickFirst(row, [
+    'project.name',
+    'project_name',
+    'projectName',
+    'name',
+    'projectMember.project.name',
+    'project_member.project.name'
+  ]);
+
+  if (projectName !== undefined) {
+    return projectName;
+  }
+
+  if (fallbackId !== undefined && fallbackId !== null && String(fallbackId).trim() !== '') {
+    addWarning(diagnostics, 'fallback_project_name', {
+      ...context,
+      ...diagnosticProjectFields({ projectMemberId: readProjectMemberId(row), projectId: readProjectId(row) })
+    });
+    return projectFallbackName(fallbackId);
+  }
+
+  addWarning(diagnostics, 'fallback_project_name', context);
+  return 'Unknown project';
+}
+
+export function projectFallbackName(fallbackId) {
+  return fallbackId !== undefined && fallbackId !== null && String(fallbackId).trim() !== ''
+    ? `Project ${fallbackId}`
+    : 'Unknown project';
+}
+
+export function hasProjectName(row) {
+  return pickFirst(row, [
+    'project.name',
+    'project_name',
+    'projectName',
+    'name',
+    'projectMember.project.name',
+    'project_member.project.name'
+  ]) !== undefined;
+}
+
+function looksLikeProjectMemberRow(row) {
+  return row && typeof row === 'object' && row.id !== undefined && (
+    row.project_id !== undefined ||
+    row.projectId !== undefined ||
+    row.project !== undefined ||
+    row.project_name !== undefined ||
+    row.projectName !== undefined ||
+    row.assign_hours !== undefined ||
+    row.assigned_hours !== undefined ||
+    row.booked_hours !== undefined
+  );
+}
+
+export function readAssignedHours(row, diagnostics = null, context = {}) {
+  return readNumber(row, [
+    'assign_hours',
+    'assigned_hours',
+    'assignedHours',
+    'booking_hours',
+    'booked_hours',
+    'bookedHours',
+    'workload_hours',
+    'workloadHours',
+    'assign_percent',
+    'assignPercent',
+    'hours_per_day',
+    'hoursPerDay',
+    'timesheet',
+    'logtime',
+    'logtimes_plan',
+    'planned_hours',
+    'plannedHours',
+    'effort',
+    'man_day'
+  ], diagnostics, context);
+}
+
+export function readLoggedHours(row, diagnostics = null, context = {}) {
+  return readNumber(row, [
+    'logged_hours',
+    'loggedHours',
+    'actual_hours',
+    'actualHours',
+    'logtimes',
+    'log_times',
+    'logTimes',
+    'logged',
+    'total_logtimes',
+    'totalLoggedHours',
+    'total_logged_hours',
+    'spent_hours',
+    'spentHours'
+  ], diagnostics, context);
+}
+
+export function readNumber(row, paths, diagnostics = null, context = {}) {
+  for (const path of paths) {
+    const value = pickFirst(row, [path]);
+    if (value !== undefined) {
+      const number = Number(value);
+      if (Number.isFinite(number) && number > 0) {
+        return number;
+      }
+      if (Number.isFinite(number) && number === 0) {
+        continue;
+      }
+      addWarning(diagnostics, 'invalid_hours', {
+        ...context,
+        field: path
+      });
+    }
+  }
+
+  return 0;
+}
+
+export function coerceHours(value, diagnostics = null, context = {}) {
+  const number = Number(value);
+  if (Number.isFinite(number) && number >= 0) {
+    return number;
+  }
+
+  addWarning(diagnostics, 'invalid_hours', context);
+  return 0;
+}
+
+export function readDateLike(row) {
+  const value = pickFirst(row, [
+    'logdate',
+    'log_date',
+    'date',
+    'day',
+    'workdate',
+    'work_date',
+    'timesheet_date'
+  ]);
+
+  return normalizeDateOnly(value);
+}
+
+export function normalizeDateOnly(value) {
+  if (!value) {
+    return '';
+  }
+
+  const text = String(value);
+  const match = text.match(/\d{4}-\d{2}-\d{2}/);
+  return match ? match[0] : '';
+}
+
+export function isDateInRange(localDateISO, { from, to } = {}) {
+  if (!localDateISO) {
+    return false;
+  }
+
+  if (from && localDateISO < from) {
+    return false;
+  }
+
+  if (to && localDateISO >= to) {
+    return false;
+  }
+
+  return true;
+}
+
+export function pickFirst(row, paths) {
+  for (const path of paths) {
+    const value = getPath(row, path);
+    if (value !== undefined && value !== null && value !== '') {
+      return value;
+    }
+  }
+
+  return undefined;
+}
+
+function getPath(row, path) {
+  return path.split('.').reduce((current, part) => {
+    if (current === undefined || current === null) {
+      return undefined;
+    }
+
+    return current[part];
+  }, row);
+}
+
+export function unwrapRecords(data) {
+  if (Array.isArray(data)) {
+    return data;
+  }
+
+  if (Array.isArray(data?.data)) {
+    return data.data;
+  }
+
+  if (Array.isArray(data?.data?.data)) {
+    return data.data.data;
+  }
+
+  if (Array.isArray(data?.records)) {
+    return data.records;
+  }
+
+  if (Array.isArray(data?.items)) {
+    return data.items;
+  }
+
+  return [];
+}
+
+export function extractLogtimeRecord(data, collectionKey) {
+  const candidates = collectionKey
+    ? [data?.data?.[collectionKey], data?.[collectionKey]]
+    : [data?.data?.data, data?.data, data?.record, data?.item, data];
+
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      const record = candidate.find((item) => item && typeof item === 'object');
+      if (record) {
+        return record;
+      }
+      continue;
+    }
+    if (candidate && typeof candidate === 'object' && (
+      candidate.id !== undefined ||
+      candidate.logtime_id !== undefined ||
+      candidate.logtimeId !== undefined
+    )) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+export function assertLogtimeId(value, name) {
+  const normalized = String(value ?? '').trim();
+  if (!normalized || !/^[A-Za-z0-9_-]+$/.test(normalized)) {
+    throw new Error(`${name} must be a valid Resource Optimiser identifier.`);
+  }
+  return normalized;
+}
+
+export function preserveNumericId(value) {
+  return /^\d+$/.test(value) && Number.isSafeInteger(Number(value))
+    ? Number(value)
+    : value;
+}

package/lib/ro-api-http.mjs

@@ -0,0 +1,68 @@
+// Resource Optimiser HTTP plumbing: the authenticated JSON fetch and its error type.
+import { CONFIG } from './config.mjs';
+import { fetchWithPolicy, redactedExcerpt } from './http.mjs';
+import { safeJsonParse } from './util.mjs';
+
+export class ApiError extends Error {
+  constructor(message, { status, path, body } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.path = path;
+    this.body = body;
+  }
+}
+
+export async function apiFetch(token, path, options = {}) {
+  const {
+    fetchImpl,
+    retries,
+    retryDelayMs = CONFIG.httpRetryDelayMs,
+    timeoutMs = CONFIG.httpTimeoutMs,
+    cache: _worklogTaskCache,
+    taskCache: _taskCacheAlias,
+    ...requestOptions
+  } = options;
+  const method = requestOptions.method || 'GET';
+  const response = await fetchWithPolicy(`${CONFIG.apiBase}${path}`, {
+    ...requestOptions,
+    fetchImpl,
+    timeoutMs,
+    retryDelayMs,
+    retries: retries ?? CONFIG.httpReadRetries,
+    idempotent: isIdempotentMethod(method),
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...requestOptions.headers
+    }
+  });
+
+  const text = await response.text();
+  const data = text ? safeJsonParse(text, text) : null;
+  const safeBody = redactedExcerpt(text);
+
+  if (response.status === 401) {
+    throw new ApiError('API request returned 401 Unauthorized.', {
+      status: response.status,
+      path,
+      body: safeBody
+    });
+  }
+
+  if (!response.ok) {
+    throw new ApiError(`API request failed: ${response.status} ${response.statusText} for ${path}. Body: ${safeBody}`, {
+      status: response.status,
+      path,
+      body: safeBody
+    });
+  }
+
+  return data;
+}
+
+function isIdempotentMethod(method) {
+  return ['GET', 'HEAD', 'OPTIONS'].includes(String(method || 'GET').toUpperCase());
+}