@invoicer/cli 1.1.0

package/src/domain/types.ts

@@ -0,0 +1,129 @@
+export interface FreelancerProfile {
+  name?: string;
+  email?: string;
+  address?: string;
+}
+
+export interface ClientConfig {
+  name: string;
+  email?: string;
+  address?: string;
+  currency?: string;
+  defaultRate: number;
+  payPeriodType?: string;
+}
+
+export interface Config {
+  client: ClientConfig[];
+  defaultDescription?: string;
+  from: FreelancerProfile;
+  invoicePrefix?: string;
+  note?: string;
+}
+
+export interface ClientHistory {
+  lastHours: number;
+  lastRate: number;
+  seqByMonth: Record<string, number>;
+}
+
+export interface LastState {
+  clients: Record<string, ClientHistory>;
+}
+
+export interface TimesheetEntry {
+  id: number;
+  client: string;
+  date: string;
+  hours: number;
+  description: string;
+  rate: number;
+  amount: number;
+  createdAt?: string;
+}
+
+export interface TimesheetData {
+  entries: TimesheetEntry[];
+}
+
+export interface ArchivedEntry extends TimesheetEntry {
+  archivedAt: string;
+  archivedReason: string;
+  invoiceNumber: string;
+  invoiceMonth: string;
+}
+
+export interface ArchiveData {
+  archivedEntries: ArchivedEntry[];
+}
+
+export interface AggregatedTimesheetGroup {
+  description: string;
+  hours: number;
+  rate: number;
+  amount: number;
+  periodFrom: string;
+  periodTo: string;
+  rateVariance: boolean;
+  minRate: number;
+  maxRate: number;
+  entryIds: number[];
+}
+
+export interface LineItem {
+  description: string;
+  hours: number;
+  rate: number;
+  amount: number;
+  periodFrom?: string;
+  periodTo?: string;
+}
+
+export interface GenerateOptions {
+  fromTimesheet?: boolean;
+  client?: string;
+  month?: string;
+  hours?: string;
+  rate?: string;
+  desc?: string;
+  invoice?: string;
+}
+
+export interface ClientsOptions {
+  list?: boolean;
+  add?: boolean;
+  edit?: string;
+  delete?: string;
+}
+
+export interface TimesheetOptions {
+  export?: string;
+  client?: string;
+  month?: string;
+  archive?: boolean;
+}
+
+export interface InvoicePayload {
+  from: FreelancerProfile;
+  client: ClientConfig;
+  currency: string;
+  invoiceNumber: string;
+  invoiceDate: string;
+  periodFrom: string;
+  periodTo: string;
+  lineItems: LineItem[];
+  paymentTerms?: string;
+  note?: string;
+}
+
+export interface SendInvoiceEmailInput {
+  outPath: string;
+  invoiceNumber: string;
+  clientName: string;
+  clientEmail: string;
+  currency: string;
+  total: number;
+  periodFrom: string;
+  periodTo: string;
+  senderName?: string;
+}

package/src/services/email.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import nodemailer from "nodemailer";
+import { type SendInvoiceEmailInput } from "../domain/types.js";
+
+export function hasSmtpConfig(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.SMTP_HOST && env.SMTP_USER && env.SMTP_PASS);
+}
+
+export async function sendInvoiceEmail(
+  input: SendInvoiceEmailInput,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const smtpPort = Number(env.SMTP_PORT || 465);
+
+  const transporter = nodemailer.createTransport({
+    host: env.SMTP_HOST,
+    port: smtpPort,
+    secure: smtpPort === 465,
+    auth: {
+      user: env.SMTP_USER,
+      pass: env.SMTP_PASS,
+    },
+  });
+
+  const emailSubject = `Invoice ${input.invoiceNumber} - ${input.clientName}`;
+  const emailBody = `Dear ${input.clientName},\n\nPlease find attached invoice ${input.invoiceNumber}.\n\nInvoice Details:\n- Period: ${input.periodFrom} to ${input.periodTo}\n- Amount Due: ${input.currency} ${input.total.toFixed(2)}\n\nThank you for your business!\n\nBest regards,\n${input.senderName || ""}`;
+
+  await transporter.sendMail({
+    from: env.INVOICE_FROM || env.SMTP_USER,
+    to: input.clientEmail,
+    subject: emailSubject,
+    text: emailBody,
+    attachments: [
+      {
+        filename: path.basename(input.outPath),
+        path: input.outPath,
+      },
+    ],
+  });
+}

package/src/services/invoice-number.ts

@@ -0,0 +1,46 @@
+export function getDefaultMonth(now = new Date()): string {
+  return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}`;
+}
+
+export function validateMonth(month: string): boolean {
+  return /^\d{4}-\d{2}$/.test(month);
+}
+
+export function resolveInvoiceNumber(params: {
+  month: string;
+  invoicePrefix?: string;
+  overrideInvoice?: string;
+  seqByMonth: Record<string, number>;
+}): string {
+  const { month, invoicePrefix, overrideInvoice, seqByMonth } = params;
+  const trimmedOverride = overrideInvoice?.trim();
+
+  if (trimmedOverride) {
+    return trimmedOverride;
+  }
+
+  if (!seqByMonth[month]) {
+    seqByMonth[month] = 0;
+  }
+
+  seqByMonth[month] += 1;
+  const yyyymm = month.replace("-", "");
+  const prefix = invoicePrefix?.trim() || "INV";
+
+  return `${prefix}-${yyyymm}-${String(seqByMonth[month]).padStart(3, "0")}`;
+}
+
+export function getInvoicePeriod(month: string): { periodFrom: string; periodTo: string } {
+  const year = Number(month.slice(0, 4));
+  const monthNumber = Number(month.slice(5, 7));
+  const monthEnd = new Date(year, monthNumber, 0);
+
+  return {
+    periodFrom: `${month}-01`,
+    periodTo: `${month}-${String(monthEnd.getDate()).padStart(2, "0")}`,
+  };
+}
+
+export function getInvoiceDate(today = new Date()): string {
+  return today.toISOString().slice(0, 10);
+}

package/src/services/pdf-render.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import puppeteer from "puppeteer";
+import { type ProjectPaths } from "../core/paths.js";
+import { type InvoicePayload } from "../domain/types.js";
+import { sanitizePathSegment } from "../utils/sanitize.js";
+
+export async function renderInvoicePdf(
+  paths: ProjectPaths,
+  payload: InvoicePayload,
+  month: string,
+): Promise<string> {
+  const clientOutDir = path.join(paths.outDir, sanitizePathSegment(payload.client.name, "client"));
+  fs.mkdirSync(clientOutDir, { recursive: true });
+
+  const fileUrl = pathToFileURL(paths.indexHtmlPath).toString();
+
+  const browser = await puppeteer.launch({ headless: true });
+
+  try {
+    const page = await browser.newPage();
+    await page.goto(fileUrl, { waitUntil: "networkidle0" });
+
+    await page.evaluate((browserPayload) => {
+      const setVal = (id: string, value: string | number | undefined) => {
+        const el = document.getElementById(id) as HTMLInputElement | HTMLTextAreaElement | null;
+        if (!el) return;
+        el.value = String(value ?? "");
+        el.dispatchEvent(new Event("input", { bubbles: true }));
+        el.dispatchEvent(new Event("change", { bubbles: true }));
+      };
+
+      setVal("in_freelancer", browserPayload.from.name);
+      setVal("in_email", browserPayload.from.email);
+      setVal("in_freelancer_address", browserPayload.from.address);
+
+      setVal("in_client", browserPayload.client.name);
+      setVal("in_client_address", browserPayload.client.address);
+
+      setVal("in_currency", browserPayload.currency);
+      setVal("in_number", browserPayload.invoiceNumber);
+      setVal("in_date", browserPayload.invoiceDate);
+
+      setVal("in_payment_terms", browserPayload.paymentTerms || "");
+      setVal("in_note", browserPayload.note || "");
+
+      type InvoicerWindow = Window & {
+        __invoicer?: {
+          state?: { lineItems: Array<Record<string, unknown>> };
+          builder?: { renderLineItemsUI: () => void; buildPreview: () => void };
+        };
+      };
+
+      const win = window as InvoicerWindow;
+
+      if (win.__invoicer?.state && win.__invoicer.builder) {
+        win.__invoicer.state.lineItems = browserPayload.lineItems.map((item) => ({
+          description: item.description,
+          periodFrom: browserPayload.periodFrom,
+          periodTo: browserPayload.periodTo,
+          days: "",
+          hoursPerDay: "",
+          quantity: String(item.hours),
+          rate: Number(item.rate),
+          amount: Number(item.amount),
+        }));
+
+        win.__invoicer.builder.renderLineItemsUI();
+        win.__invoicer.builder.buildPreview();
+      }
+
+      const preview = document.querySelector("#preview") as HTMLElement | null;
+      if (preview) {
+        preview.style.display = "block";
+        document.body.innerHTML = "";
+        document.body.appendChild(preview);
+      }
+    }, payload);
+
+    const safeInvoiceNumber = sanitizePathSegment(payload.invoiceNumber, "invoice");
+    const outPath = path.join(clientOutDir, `invoice-${month}-${safeInvoiceNumber}.pdf`);
+
+    await page.pdf({
+      path: outPath,
+      format: "A4",
+      printBackground: true,
+      margin: { top: "12mm", right: "12mm", bottom: "12mm", left: "12mm" },
+    });
+
+    return outPath;
+  } finally {
+    await browser.close();
+  }
+}

package/src/services/timesheet.ts

@@ -0,0 +1,173 @@
+import { loadJsonFile, writeJsonFile } from "../core/json-store.js";
+import { type ProjectPaths } from "../core/paths.js";
+import { validateArchiveData, validateTimesheetData } from "../core/validators.js";
+import {
+  type AggregatedTimesheetGroup,
+  type ArchivedEntry,
+  type ArchiveData,
+  type TimesheetData,
+  type TimesheetEntry,
+} from "../domain/types.js";
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+export function readTimesheetEntries(
+  paths: ProjectPaths,
+  filters: { client?: string; month?: string } = {},
+): TimesheetEntry[] {
+  const data = loadJsonFile<TimesheetData>(
+    paths.timesheetPath,
+    { entries: [] },
+    validateTimesheetData,
+  );
+
+  return data.entries.filter((entry) => {
+    const matchesClient = !filters.client || entry.client === filters.client;
+    const matchesMonth = !filters.month || entry.date.startsWith(filters.month);
+    return matchesClient && matchesMonth;
+  });
+}
+
+export function readArchivedEntries(
+  paths: ProjectPaths,
+  filters: { client?: string; month?: string } = {},
+): ArchivedEntry[] {
+  const data = loadJsonFile<ArchiveData>(
+    paths.archivePath,
+    { archivedEntries: [] },
+    validateArchiveData,
+  );
+
+  return data.archivedEntries.filter((entry) => {
+    const matchesClient = !filters.client || entry.client === filters.client;
+    const matchesMonth = !filters.month || entry.date.startsWith(filters.month);
+    return matchesClient && matchesMonth;
+  });
+}
+
+export function aggregateEntriesByDescription(entries: TimesheetEntry[]): AggregatedTimesheetGroup[] {
+  const groups: Record<
+    string,
+    {
+      description: string;
+      entries: TimesheetEntry[];
+      totalHours: number;
+      totalAmount: number;
+      rates: number[];
+      dates: string[];
+    }
+  > = {};
+
+  for (const entry of entries) {
+    const key = entry.description || "Unnamed Service";
+    if (!groups[key]) {
+      groups[key] = {
+        description: key,
+        entries: [],
+        totalHours: 0,
+        totalAmount: 0,
+        rates: [],
+        dates: [],
+      };
+    }
+
+    groups[key].entries.push(entry);
+    groups[key].totalHours += entry.hours;
+    groups[key].totalAmount += entry.amount;
+    groups[key].rates.push(entry.rate);
+    groups[key].dates.push(entry.date);
+  }
+
+  return Object.values(groups).map((group) => {
+    const avgRate = group.totalHours === 0 ? 0 : group.totalAmount / group.totalHours;
+    const minRate = Math.min(...group.rates);
+    const maxRate = Math.max(...group.rates);
+    const dates = [...group.dates].sort();
+
+    return {
+      description: group.description,
+      hours: round2(group.totalHours),
+      rate: round2(avgRate),
+      amount: round2(group.totalAmount),
+      periodFrom: dates[0],
+      periodTo: dates[dates.length - 1],
+      rateVariance: minRate !== maxRate,
+      minRate,
+      maxRate,
+      entryIds: group.entries.map((entry) => entry.id),
+    };
+  });
+}
+
+export function archiveTimesheetEntries(
+  paths: ProjectPaths,
+  entryIds: number[],
+  invoiceNumber: string,
+  invoiceMonth: string,
+): number {
+  const entryIdSet = new Set(entryIds);
+  const timesheetData = loadJsonFile<TimesheetData>(
+    paths.timesheetPath,
+    { entries: [] },
+    validateTimesheetData,
+  );
+
+  const archiveData = loadJsonFile<ArchiveData>(
+    paths.archivePath,
+    { archivedEntries: [] },
+    validateArchiveData,
+  );
+
+  const archivedAt = new Date().toISOString();
+  const moved: ArchivedEntry[] = [];
+
+  timesheetData.entries = timesheetData.entries.filter((entry) => {
+    if (!entryIdSet.has(entry.id)) {
+      return true;
+    }
+
+    moved.push({
+      ...entry,
+      archivedAt,
+      archivedReason: "invoiced",
+      invoiceNumber,
+      invoiceMonth,
+    });
+
+    return false;
+  });
+
+  if (moved.length > 0) {
+    archiveData.archivedEntries.push(...moved);
+    writeJsonFile(paths.timesheetPath, timesheetData);
+    writeJsonFile(paths.archivePath, archiveData);
+  }
+
+  return moved.length;
+}
+
+export function toTimesheetCsv(entries: TimesheetEntry[]): string {
+  return ["date,client,description,hours,rate,amount"]
+    .concat(
+      entries.map(
+        (entry) =>
+          `${entry.date},${entry.client},"${entry.description}",${entry.hours},${entry.rate},${entry.amount}`,
+      ),
+    )
+    .join("\n");
+}
+
+export function toArchiveCsv(entries: ArchivedEntry[]): string {
+  return [
+    "date,client,description,hours,rate,amount,invoiceNumber,invoiceMonth,archivedAt",
+  ]
+    .concat(
+      entries.map(
+        (entry) =>
+          `${entry.date},${entry.client},"${entry.description}",${entry.hours},${entry.rate},${entry.amount},${entry.invoiceNumber},${entry.invoiceMonth},${entry.archivedAt}`,
+      ),
+    )
+    .join("\n");
+}

package/src/utils/sanitize.ts

@@ -0,0 +1,8 @@
+export function sanitizePathSegment(value: unknown, fallback = "invoice"): string {
+  const sanitized = String(value ?? "")
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/g, "")
+    .replace(/[. ]+$/g, "")
+    .trim();
+
+  return sanitized || fallback;
+}

package/test/cli-wiring.test.ts

@@ -0,0 +1,25 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createProgram } from "../dist/cli.js";
+
+test("CLI registers expected commands and options", () => {
+  const program = createProgram();
+
+  const commandNames = program.commands.map((command) => command.name());
+  assert.deepEqual(commandNames, ["generate", "clients", "timesheet"]);
+  assert.equal((program as unknown as { _defaultCommandName?: string })._defaultCommandName, "generate");
+
+  const generate = program.commands.find((command) => command.name() === "generate");
+  assert.ok(generate);
+
+  const generateOptionFlags = generate!.options.map((option) => option.long);
+  assert.deepEqual(generateOptionFlags, [
+    "--from-timesheet",
+    "--client",
+    "--month",
+    "--hours",
+    "--rate",
+    "--desc",
+    "--invoice",
+  ]);
+});

package/test/invoice-number.test.ts

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  getInvoicePeriod,
+  resolveInvoiceNumber,
+  validateMonth,
+} from "../dist/services/invoice-number.js";
+
+test("resolveInvoiceNumber increments sequence per month", () => {
+  const seqByMonth: Record<string, number> = { "2026-02": 4 };
+
+  const invoiceNumber = resolveInvoiceNumber({
+    month: "2026-02",
+    invoicePrefix: "INV",
+    seqByMonth,
+  });
+
+  assert.equal(invoiceNumber, "INV-202602-005");
+  assert.equal(seqByMonth["2026-02"], 5);
+});
+
+test("resolveInvoiceNumber keeps override unchanged", () => {
+  const seqByMonth: Record<string, number> = { "2026-02": 4 };
+
+  const invoiceNumber = resolveInvoiceNumber({
+    month: "2026-02",
+    invoicePrefix: "INV",
+    overrideInvoice: "INV-CUSTOM-001",
+    seqByMonth,
+  });
+
+  assert.equal(invoiceNumber, "INV-CUSTOM-001");
+  assert.equal(seqByMonth["2026-02"], 4);
+});
+
+test("getInvoicePeriod returns month boundaries", () => {
+  const period = getInvoicePeriod("2026-02");
+  assert.deepEqual(period, { periodFrom: "2026-02-01", periodTo: "2026-02-28" });
+});
+
+test("validateMonth accepts YYYY-MM only", () => {
+  assert.equal(validateMonth("2026-02"), true);
+  assert.equal(validateMonth("2026-2"), false);
+  assert.equal(validateMonth("02-2026"), false);
+});

package/test/timesheet.test.ts

@@ -0,0 +1,104 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  aggregateEntriesByDescription,
+  archiveTimesheetEntries,
+  readArchivedEntries,
+  readTimesheetEntries,
+} from "../dist/services/timesheet.js";
+
+function createTestPaths(root: string) {
+  return {
+    projectRoot: root,
+    configPath: path.join(root, "config.json"),
+    lastPath: path.join(root, "data", "last.json"),
+    timesheetPath: path.join(root, "data", "timesheet.json"),
+    archivePath: path.join(root, "data", "archive.json"),
+    outDir: path.join(root, "out"),
+    indexHtmlPath: path.join(root, "index.html"),
+  };
+}
+
+test("aggregateEntriesByDescription groups and computes weighted rate", () => {
+  const grouped = aggregateEntriesByDescription([
+    {
+      id: 1,
+      client: "ACME",
+      date: "2026-02-01",
+      hours: 1,
+      description: "Development",
+      rate: 40,
+      amount: 40,
+    },
+    {
+      id: 2,
+      client: "ACME",
+      date: "2026-02-02",
+      hours: 3,
+      description: "Development",
+      rate: 60,
+      amount: 180,
+    },
+  ]);
+
+  assert.equal(grouped.length, 1);
+  assert.equal(grouped[0]?.description, "Development");
+  assert.equal(grouped[0]?.hours, 4);
+  assert.equal(grouped[0]?.rate, 55);
+  assert.equal(grouped[0]?.amount, 220);
+  assert.equal(grouped[0]?.rateVariance, true);
+  assert.deepEqual(grouped[0]?.entryIds, [1, 2]);
+});
+
+test("archiveTimesheetEntries moves entries from active sheet to archive", () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "invoicer-test-"));
+  const paths = createTestPaths(root);
+
+  fs.mkdirSync(path.dirname(paths.timesheetPath), { recursive: true });
+  fs.writeFileSync(
+    paths.timesheetPath,
+    JSON.stringify(
+      {
+        entries: [
+          {
+            id: 10,
+            client: "ACME",
+            date: "2026-02-10",
+            hours: 2,
+            description: "Dev",
+            rate: 50,
+            amount: 100,
+            createdAt: "2026-02-10T12:00:00.000Z",
+          },
+          {
+            id: 11,
+            client: "ACME",
+            date: "2026-02-11",
+            hours: 1,
+            description: "Meeting",
+            rate: 50,
+            amount: 50,
+            createdAt: "2026-02-11T12:00:00.000Z",
+          },
+        ],
+      },
+      null,
+      2,
+    ),
+  );
+
+  const movedCount = archiveTimesheetEntries(paths, [10], "INV-202602-001", "2026-02");
+  assert.equal(movedCount, 1);
+
+  const remaining = readTimesheetEntries(paths, { client: "ACME", month: "2026-02" });
+  assert.equal(remaining.length, 1);
+  assert.equal(remaining[0]?.id, 11);
+
+  const archived = readArchivedEntries(paths, { client: "ACME", month: "2026-02" });
+  assert.equal(archived.length, 1);
+  assert.equal(archived[0]?.id, 10);
+  assert.equal(archived[0]?.invoiceNumber, "INV-202602-001");
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "node_modules"]
+}