Invoice Generator

A powerful and flexible command-line tool for generating PDF invoices from simple JSON data files. It features an interactive mode for ease of use and a robust, non-interactive mode for scripting and automation.

Features

• Interactive & Non-Interactive Modes: Use the simple interactive wizard (npm start) or pass arguments directly for scripted use.
• Safe Preview-First Workflow: Always generates a development preview first. You must confirm before the official invoice is created and recorded, preventing accidental invoice generation.
• Data-Driven: Senders, clients, and products are managed in simple .json files, making them easy to update without changing code.
• Automatic Invoice Numbering: Invoice numbers are automatically incremented based on the year and existing records. The sequence resets annually.
• Organized Output: Generated PDFs are neatly stored in folders organized by sender (invoice/<sender_name>/).
• Unit Tested: Core logic is verified with unit tests using Jest.

Prerequisites

• Node.js (v16 or higher recommended)
• npm (comes with Node.js)

Setup

1. Clone the repository or download the source code.
2. Open your terminal in the project directory.
3. Install the dependencies:

   npm install
   

Usage

There are two primary ways to generate an invoice:

1. Interactive Mode (Recommended for most users)

Run the interactive wizard. The tool will guide you through selecting a sender, client, and one or more products.

npm start

The script will first generate a development preview PDF. After you review it, you will be prompted to confirm whether you want to create the final production invoice.

2. Non-Interactive / Scripted Mode

You can also generate an invoice by passing command-line arguments. This is useful for automation and scripting.

The basic command is: npm run generate -- --sender <sender_key> --client <client_key> --products <product_key_1> <product_key_2>

Example:

npm run generate -- --sender company1 --client company4 --products linkedin_scraper web_design

Like the interactive mode, this will also generate a preview and prompt for confirmation before creating the production invoice.

Running Tests

To run the automated tests for the project:

npm test

How the Data Files Work

All data is managed in the data/ directory.

sender.json

Stores your company or sender profiles. Each key represents a unique sender.

{
  "company1": { "company": "Your Company", "address": ... },
  "company2": { "company": "Another Profile", "address": ... }
}

client.json

Stores your client profiles. The invoiceFileName key is optional; if provided, it will be used for the generated PDF's filename.

{
  "company3": { "company": "First Client", "address": ... },
  "company4": { "company": "Second Client", "invoiceFileName": "second_client_invoices", "address": ... }
}

products.json

A catalog of the services or products you offer.

{
  "linkedin_scraper": {
    "description": "LinkedIn Scraper Bot",
    "price": 250,
    "taxRate": 0
  },
  "web_design": { "description": "Website Design", "price": 1200, "taxRate": 0 }
}

invoices.json

This file is your ledger. It's automatically updated when you create a production invoice. It tracks all generated invoices to determine the next sequential number. You should not need to edit this file manually.

{
  "invoices": [
    {
      "number": "2024-0001",
      "date": "2024-07-31",
      ...
    }
  ]
}