@liebig-technology/clockodo-cli 0.1.0 → 0.2.1

package/README.md

@@ -17,6 +17,8 @@ Commands:
   status         Show running clock and today's summary
   start          Start time tracking
   stop           Stop time tracking
+  edit           Edit the running clock entry
+  extend         Extend the running clock by N minutes
   entries        Manage time entries
   customers      Manage customers
   projects       Manage projects
@@ -54,18 +56,23 @@ Credentials are stored in `~/.config/clockodo-cli/config.json`. Environment vari
 ```bash
 # Time tracking
 clockodo start --customer 123 --service 456 --text "Working on feature"
+clockodo start --customer 123 --service 456 --billable   # explicit billability
 clockodo stop
 clockodo status
+clockodo edit --text "New description" --billable         # edit running entry
+clockodo extend 30                                        # extend running clock by 30 minutes
 
 # Entries
 clockodo entries                                         # list today's entries
 clockodo entries --since 2026-01-01 --until 2026-01-31   # date range
+clockodo entries --billable                              # only billable entries
 clockodo entries create --from "09:00" --to "12:30" --customer 123 --service 456
+clockodo entries update 42 --text "New description" --customer 789 --service 456
 
 # Reports
-clockodo report              # today
-clockodo report week         # this week
-clockodo report month        # this month
+clockodo report                          # today, grouped by project
+clockodo report week --group customer    # this week by customer
+clockodo report month --group text       # this month by description
 
 # Absences, work times, user reports
 clockodo absences list --year 2026

package/dist/index.js

@@ -458,7 +458,7 @@ function registerAbsencesCommands(program2) {
 }
 
 // src/commands/clock.ts
-import { Billability } from "clockodo";
+import { Billability, getEntryDurationUntilNow } from "clockodo";
 
 // src/lib/prompts.ts
 import * as p2 from "@clack/prompts";
@@ -595,7 +595,7 @@ function parseDateTime(input) {
 
 // src/commands/clock.ts
 function registerClockCommands(program2) {
-  program2.command("start").description("Start time tracking").option("-c, --customer <id>", "Customer ID", parseIntStrict).option("-p, --project <id>", "Project ID", parseIntStrict).option("-s, --service <id>", "Service ID", parseIntStrict).option("-t, --text <description>", "Entry description").option("-b, --billable", "Mark as billable").action(async (cmdOpts) => {
+  program2.command("start").description("Start time tracking").option("-c, --customer <id>", "Customer ID", parseIntStrict).option("-p, --project <id>", "Project ID", parseIntStrict).option("-s, --service <id>", "Service ID", parseIntStrict).option("-t, --text <description>", "Entry description").option("-b, --billable", "Mark as billable").option("--no-billable", "Mark as not billable").action(async (cmdOpts) => {
     const opts = program2.opts();
     const mode = resolveOutputMode(opts);
     const client = getClient();
@@ -619,9 +619,11 @@ function registerClockCommands(program2) {
     const result = await client.startClock({
       customersId,
       servicesId,
+      ...cmdOpts.billable !== void 0 && {
+        billable: cmdOpts.billable ? Billability.Billable : Billability.NotBillable
+      },
       ...projectsId && { projectsId },
-      ...cmdOpts.text && { text: cmdOpts.text },
-      ...cmdOpts.billable && { billable: Billability.Billable }
+      ...cmdOpts.text && { text: cmdOpts.text }
     });
     if (mode !== "human") {
       printResult({ data: result.running }, opts);
@@ -652,6 +654,57 @@ function registerClockCommands(program2) {
       console.log(`  Description: ${result.stopped.text}`);
     }
   });
+  program2.command("edit").description("Edit the running clock entry").option("-c, --customer <id>", "Customer ID", parseIntStrict).option("-p, --project <id>", "Project ID", parseIntStrict).option("-s, --service <id>", "Service ID", parseIntStrict).option("-t, --text <description>", "Entry description").option("-b, --billable", "Mark as billable").option("--no-billable", "Mark as not billable").action(async (cmdOpts) => {
+    const opts = program2.opts();
+    const client = getClient();
+    const clock = await client.getClock();
+    if (!clock.running) {
+      throw new CliError("No clock is currently running.", ExitCode.EMPTY_RESULTS);
+    }
+    const updates = { id: clock.running.id };
+    if (cmdOpts.customer !== void 0) updates.customersId = cmdOpts.customer;
+    if (cmdOpts.project !== void 0) updates.projectsId = cmdOpts.project;
+    if (cmdOpts.service !== void 0) updates.servicesId = cmdOpts.service;
+    if (cmdOpts.text !== void 0) updates.text = cmdOpts.text;
+    if (cmdOpts.billable !== void 0)
+      updates.billable = cmdOpts.billable ? Billability.Billable : Billability.NotBillable;
+    if (Object.keys(updates).length === 1) {
+      throw new CliError(
+        "No update flags provided.",
+        ExitCode.INVALID_ARGS,
+        "Use --text, --customer, --project, --service, --billable, or --no-billable"
+      );
+    }
+    const result = await client.editEntry(updates);
+    const mode = resolveOutputMode(opts);
+    if (mode !== "human") {
+      printResult({ data: result.entry }, opts);
+      return;
+    }
+    printSuccess("Running entry updated");
+  });
+  program2.command("extend").description("Extend the running clock by N minutes").argument("<minutes>", "Minutes to extend by", parseIntStrict).action(async (minutes) => {
+    const opts = program2.opts();
+    const client = getClient();
+    const clock = await client.getClock();
+    if (!clock.running) {
+      throw new CliError("No clock is currently running.", ExitCode.EMPTY_RESULTS);
+    }
+    const durationBefore = getEntryDurationUntilNow(clock.running);
+    const duration = durationBefore + minutes * 60;
+    const result = await client.changeClockDuration({
+      entriesId: clock.running.id,
+      durationBefore,
+      duration
+    });
+    const mode = resolveOutputMode(opts);
+    if (mode !== "human") {
+      printResult({ data: result.updated }, opts);
+      return;
+    }
+    printSuccess(`Clock extended by ${minutes} minutes`);
+    console.log(`  New duration: ${formatDuration(duration)}`);
+  });
 }
 
 // src/commands/config.ts
@@ -764,10 +817,10 @@ function registerCustomersCommands(program2) {
 // src/commands/entries.ts
 import { styleText as styleText4 } from "util";
 import * as p4 from "@clack/prompts";
-import { getEntryDurationUntilNow, isTimeEntry } from "clockodo";
+import { Billability as Billability2, getEntryDurationUntilNow as getEntryDurationUntilNow2, isTimeEntry } from "clockodo";
 function registerEntriesCommands(program2) {
   const entries = program2.command("entries").description("Manage time entries");
-  entries.command("list", { isDefault: true }).description("List time entries").option("--since <date>", "Start date (default: today)", "today").option("--until <date>", "End date (default: today)").option("--customer <id>", "Filter by customer ID", parseIntStrict).option("--project <id>", "Filter by project ID", parseIntStrict).option("--service <id>", "Filter by service ID", parseIntStrict).option("--text <search>", "Filter by description text").option(
+  entries.command("list", { isDefault: true }).description("List time entries").option("--since <date>", "Start date (default: today)", "today").option("--until <date>", "End date (default: today)").option("--customer <id>", "Filter by customer ID", parseIntStrict).option("--project <id>", "Filter by project ID", parseIntStrict).option("--service <id>", "Filter by service ID", parseIntStrict).option("--text <search>", "Filter by description text").option("-b, --billable", "Show only billable entries").option("--no-billable", "Show only non-billable entries").option(
     "-g, --group <field>",
     "Group by: customer, project, service, text (shows summary table instead)"
   ).action(async (cmdOpts) => {
@@ -780,6 +833,8 @@ function registerEntriesCommands(program2) {
     if (cmdOpts.project) filter.projectsId = cmdOpts.project;
     if (cmdOpts.service) filter.servicesId = cmdOpts.service;
     if (cmdOpts.text) filter.text = cmdOpts.text;
+    if (cmdOpts.billable !== void 0)
+      filter.billable = cmdOpts.billable ? Billability2.Billable : Billability2.NotBillable;
     const result = await client.getEntries({
       timeSince: since,
       timeUntil: until,
@@ -795,7 +850,7 @@ function registerEntriesCommands(program2) {
       }
       return;
     }
-    const totalSeconds = entryList.reduce((sum, e) => sum + getEntryDurationUntilNow(e), 0);
+    const totalSeconds = entryList.reduce((sum, e) => sum + getEntryDurationUntilNow2(e), 0);
     if (cmdOpts.group) {
       const groupKey = resolveGroupKey(cmdOpts.group);
       const groups = groupEntries(entryList, groupKey);
@@ -841,7 +896,7 @@ function registerEntriesCommands(program2) {
       formatDate(new Date(e.timeSince)),
       formatTime(e.timeSince),
       isTimeEntry(e) && !e.timeUntil ? styleText4("green", "running") : formatTime(e.timeUntil ?? e.timeSince),
-      formatDuration(getEntryDurationUntilNow(e)),
+      formatDuration(getEntryDurationUntilNow2(e)),
       e.text || styleText4("dim", "\u2014")
     ]);
     printTable(["ID", "Date", "Start", "End", "Duration", "Description"], rows, opts);
@@ -862,7 +917,7 @@ function registerEntriesCommands(program2) {
       return;
     }
     const timeUntilDisplay = isTimeEntry(e) && !e.timeUntil ? "running" : formatTime(e.timeUntil ?? e.timeSince);
-    const duration = getEntryDurationUntilNow(e);
+    const duration = getEntryDurationUntilNow2(e);
     printDetail(
       [
         ["ID", e.id],
@@ -874,12 +929,12 @@ function registerEntriesCommands(program2) {
         ["Customer ID", e.customersId],
         ["Project ID", e.projectsId ?? null],
         ["Service ID", isTimeEntry(e) ? e.servicesId : null],
-        ["Billable", e.billable === 1 ? "Yes" : e.billable === 2 ? "Billed" : "No"]
+        ["Billable", formatBillable(e.billable)]
       ],
       opts
     );
   });
-  entries.command("create").description("Create a time entry").requiredOption("--from <datetime>", "Start time (e.g., '2024-01-15 09:00' or '09:00')").requiredOption("--to <datetime>", "End time (e.g., '2024-01-15 17:00' or '17:00')").option("-c, --customer <id>", "Customer ID", parseIntStrict).option("-p, --project <id>", "Project ID", parseIntStrict).option("-s, --service <id>", "Service ID", parseIntStrict).option("-t, --text <description>", "Entry description").option("-b, --billable", "Mark as billable").action(async (cmdOpts) => {
+  entries.command("create").description("Create a time entry").requiredOption("--from <datetime>", "Start time (e.g., '2024-01-15 09:00' or '09:00')").requiredOption("--to <datetime>", "End time (e.g., '2024-01-15 17:00' or '17:00')").option("-c, --customer <id>", "Customer ID", parseIntStrict).option("-p, --project <id>", "Project ID", parseIntStrict).option("-s, --service <id>", "Service ID", parseIntStrict).option("-t, --text <description>", "Entry description").option("-b, --billable", "Mark as billable").option("--no-billable", "Mark as not billable").action(async (cmdOpts) => {
     const opts = program2.opts();
     const mode = resolveOutputMode(opts);
     const client = getClient();
@@ -900,10 +955,20 @@ function registerEntriesCommands(program2) {
         "Use --customer and --service flags, or set defaults via: clockodo config set"
       );
     }
+    let billable;
+    if (cmdOpts.billable !== void 0) {
+      billable = cmdOpts.billable ? Billability2.Billable : Billability2.NotBillable;
+    } else if (projectsId) {
+      const { data: project } = await client.getProject({ id: projectsId });
+      billable = project.billableDefault ? Billability2.Billable : Billability2.NotBillable;
+    } else {
+      const { data: customer } = await client.getCustomer({ id: customersId });
+      billable = customer.billableDefault ? Billability2.Billable : Billability2.NotBillable;
+    }
     const result = await client.addEntry({
       customersId,
       servicesId,
-      billable: cmdOpts.billable ? 1 : 0,
+      billable,
       timeSince: parseDateTime(cmdOpts.from),
       timeUntil: parseDateTime(cmdOpts.to),
       ...projectsId && { projectsId },
@@ -914,20 +979,24 @@ function registerEntriesCommands(program2) {
       return;
     }
     const entry = result.entry;
-    const duration = getEntryDurationUntilNow(entry);
+    const duration = getEntryDurationUntilNow2(entry);
     printSuccess(`Entry created (ID: ${entry.id})`);
     console.log(
       `  ${formatTime(entry.timeSince)} \u2014 ${entry.timeUntil ? formatTime(entry.timeUntil) : "?"} (${formatDuration(duration)})`
     );
   });
-  entries.command("update <id>").description("Update a time entry").option("--from <datetime>", "New start time").option("--to <datetime>", "New end time").option("-t, --text <description>", "New description").option("-b, --billable", "Mark as billable").option("--no-billable", "Mark as not billable").action(async (id, cmdOpts) => {
+  entries.command("update <id>").description("Update a time entry").option("--from <datetime>", "New start time").option("--to <datetime>", "New end time").option("-t, --text <description>", "New description").option("-c, --customer <id>", "New customer ID", parseIntStrict).option("--project <id>", "New project ID", parseIntStrict).option("-s, --service <id>", "New service ID", parseIntStrict).option("-b, --billable", "Mark as billable").option("--no-billable", "Mark as not billable").action(async (id, cmdOpts) => {
     const opts = program2.opts();
     const client = getClient();
     const updates = { id: parseId(id) };
     if (cmdOpts.from) updates.timeSince = parseDateTime(cmdOpts.from);
     if (cmdOpts.to) updates.timeUntil = parseDateTime(cmdOpts.to);
     if (cmdOpts.text !== void 0) updates.text = cmdOpts.text;
-    if (cmdOpts.billable !== void 0) updates.billable = cmdOpts.billable ? 1 : 0;
+    if (cmdOpts.customer !== void 0) updates.customersId = cmdOpts.customer;
+    if (cmdOpts.project !== void 0) updates.projectsId = cmdOpts.project;
+    if (cmdOpts.service !== void 0) updates.servicesId = cmdOpts.service;
+    if (cmdOpts.billable !== void 0)
+      updates.billable = cmdOpts.billable ? Billability2.Billable : Billability2.NotBillable;
     const result = await client.editEntry(updates);
     const mode = resolveOutputMode(opts);
     if (mode !== "human") {
@@ -989,7 +1058,7 @@ function groupEntries(entries, key) {
       groupValue = val != null ? String(val) : "(none)";
     }
     const existing = map.get(groupValue);
-    const duration = getEntryDurationUntilNow(e);
+    const duration = getEntryDurationUntilNow2(e);
     if (existing) {
       existing.count++;
       existing.seconds += duration;
@@ -999,6 +1068,16 @@ function groupEntries(entries, key) {
   }
   return [...map.entries()].map(([k, v]) => ({ key: k, ...v })).sort((a, b) => b.seconds - a.seconds);
 }
+function formatBillable(value) {
+  switch (value) {
+    case Billability2.Billable:
+      return "Yes";
+    case Billability2.Billed:
+      return "Billed";
+    default:
+      return "No";
+  }
+}
 
 // src/commands/projects.ts
 function registerProjectsCommands(program2) {
@@ -1058,14 +1137,112 @@ function registerProjectsCommands(program2) {
 
 // src/commands/report.ts
 import { styleText as styleText5 } from "util";
+import { getEntryDurationUntilNow as getEntryDurationUntilNow3 } from "clockodo";
+var GROUP_ALIASES = {
+  customer: "customers_id",
+  customers: "customers_id",
+  customers_id: "customers_id",
+  project: "projects_id",
+  projects: "projects_id",
+  projects_id: "projects_id",
+  service: "services_id",
+  services: "services_id",
+  services_id: "services_id",
+  text: "text",
+  description: "text"
+};
+function resolveReportGroupKey(input) {
+  const resolved = GROUP_ALIASES[input.toLowerCase()];
+  if (!resolved) {
+    throw new CliError(
+      `Unknown group field: "${input}". Valid options: customer, project, service, text`,
+      ExitCode.INVALID_ARGS
+    );
+  }
+  return resolved;
+}
+function groupEntriesByText(entries) {
+  const map = /* @__PURE__ */ new Map();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const e of entries) {
+    const groupKey = e.text || "(no description)";
+    const duration = getEntryDurationUntilNow3(e);
+    const existing = map.get(groupKey);
+    const timeRange = { since: e.timeSince, until: e.timeUntil ?? now };
+    if (existing) {
+      existing.count++;
+      existing.seconds += duration;
+      existing.timeRanges.push(timeRange);
+    } else {
+      map.set(groupKey, {
+        key: groupKey,
+        count: 1,
+        seconds: duration,
+        timeRanges: [timeRange]
+      });
+    }
+  }
+  return [...map.values()].sort((a, b) => b.seconds - a.seconds);
+}
+async function runTextReport(program2, since, until) {
+  const opts = program2.opts();
+  const client = getClient();
+  const result = await client.getEntries({
+    timeSince: toClockodoDateTime(since),
+    timeUntil: toClockodoDateTime(until)
+  });
+  const entryList = result.entries ?? [];
+  const groups = groupEntriesByText(entryList);
+  const totalSeconds = groups.reduce((sum, g) => sum + g.seconds, 0);
+  const mode = resolveOutputMode(opts);
+  if (mode !== "human") {
+    printResult(
+      {
+        data: {
+          period: { since: formatDate(since), until: formatDate(until) },
+          groups,
+          total: { seconds: totalSeconds, formatted: formatDuration(totalSeconds) }
+        }
+      },
+      opts
+    );
+    return;
+  }
+  printReportHeader(since, until);
+  if (groups.length === 0) {
+    console.log(styleText5("dim", "  No entries found for this period."));
+    return;
+  }
+  const rows = groups.map((g) => {
+    const ranges = g.timeRanges.map((r) => `${formatTime(r.since)}\u2013${formatTime(r.until)}`).join(", ");
+    return [g.key, formatDuration(g.seconds), formatDecimalHours(g.seconds), ranges];
+  });
+  printTable(["Description", "Duration", "Hours", "Time Ranges"], rows, opts);
+  printReportTotal(totalSeconds);
+}
+function printReportHeader(since, until) {
+  console.log();
+  console.log(`  ${styleText5("bold", "Report")}: ${formatDate(since)} \u2014 ${formatDate(until)}`);
+  console.log();
+}
+function printReportTotal(totalSeconds) {
+  console.log();
+  console.log(
+    `  ${styleText5("bold", "Total")}: ${formatDuration(totalSeconds)} (${formatDecimalHours(totalSeconds)})`
+  );
+  console.log();
+}
 async function runReport(program2, since, until, cmdOpts) {
+  const groupField = resolveReportGroupKey(cmdOpts.group ?? "projects_id");
+  if (groupField === "text") {
+    return runTextReport(program2, since, until);
+  }
   const opts = program2.opts();
   const client = getClient();
-  const grouping = [cmdOpts.group ?? "projects_id"];
   const result = await client.getEntryGroups({
     timeSince: toClockodoDateTime(since),
     timeUntil: toClockodoDateTime(until),
-    grouping
+    grouping: [groupField]
   });
   const groups = result.groups ?? [];
   const totalSeconds = groups.reduce((sum, g) => sum + (g.duration ?? 0), 0);
@@ -1083,9 +1260,7 @@ async function runReport(program2, since, until, cmdOpts) {
     );
     return;
   }
-  console.log();
-  console.log(`  ${styleText5("bold", "Report")}: ${formatDate(since)} \u2014 ${formatDate(until)}`);
-  console.log();
+  printReportHeader(since, until);
   if (groups.length === 0) {
     console.log(styleText5("dim", "  No entries found for this period."));
     return;
@@ -1096,31 +1271,23 @@ async function runReport(program2, since, until, cmdOpts) {
     formatDecimalHours(g.duration ?? 0)
   ]);
   printTable(["Name", "Duration", "Hours"], rows, opts);
-  console.log();
-  console.log(
-    `  ${styleText5("bold", "Total")}: ${formatDuration(totalSeconds)} (${formatDecimalHours(totalSeconds)})`
-  );
-  console.log();
+  printReportTotal(totalSeconds);
 }
 function registerReportCommands(program2) {
   const report = program2.command("report").description("Aggregated time reports");
-  report.command("today", { isDefault: true }).description("Today's summary").option(
-    "-g, --group <field>",
-    "Group by: projects_id, customers_id, services_id",
-    "projects_id"
-  ).action(async (cmdOpts) => {
+  report.command("today", { isDefault: true }).description("Today's summary").option("-g, --group <field>", "Group by: customer, project, service, text", "projects_id").action(async (cmdOpts) => {
     const now = /* @__PURE__ */ new Date();
     await runReport(program2, startOfDay(now), endOfDay(now), cmdOpts);
   });
-  report.command("week").description("This week's summary (Mon-Sun)").option("-g, --group <field>", "Group by field", "projects_id").action(async (cmdOpts) => {
+  report.command("week").description("This week's summary (Mon-Sun)").option("-g, --group <field>", "Group by: customer, project, service, text", "projects_id").action(async (cmdOpts) => {
     const now = /* @__PURE__ */ new Date();
     await runReport(program2, startOfWeek(now), endOfWeek(now), cmdOpts);
   });
-  report.command("month").description("This month's summary").option("-g, --group <field>", "Group by field", "projects_id").action(async (cmdOpts) => {
+  report.command("month").description("This month's summary").option("-g, --group <field>", "Group by: customer, project, service, text", "projects_id").action(async (cmdOpts) => {
     const now = /* @__PURE__ */ new Date();
     await runReport(program2, startOfMonth(now), endOfMonth(now), cmdOpts);
   });
-  report.command("custom").description("Custom date range report").requiredOption("--since <date>", "Start date").requiredOption("--until <date>", "End date").option("-g, --group <field>", "Group by field", "projects_id").action(async (cmdOpts) => {
+  report.command("custom").description("Custom date range report").requiredOption("--since <date>", "Start date").requiredOption("--until <date>", "End date").option("-g, --group <field>", "Group by: customer, project, service, text", "projects_id").action(async (cmdOpts) => {
     const since = new Date(parseDateTime(cmdOpts.since));
     const until = new Date(parseDateTime(cmdOpts.until));
     await runReport(program2, since, until, cmdOpts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liebig-technology/clockodo-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "AI-friendly CLI for the Clockodo time tracking API",
   "type": "module",
   "bin": {
@@ -13,17 +13,6 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsx src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check .",
-    "lint:fix": "biome check --write .",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "pnpm build",
-    "prepare": "husky"
-  },
   "keywords": [
     "clockodo",
     "time-tracking",
@@ -62,5 +51,14 @@
     "*": [
       "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
     ]
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}