121 lines
3.7 KiB
Markdown
121 lines
3.7 KiB
Markdown
# 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](https://nodejs.org/) (v16 or higher recommended)
|
|
- [npm](https://www.npmjs.com/) (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:
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"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.
|
|
|
|
```json
|
|
{
|
|
"invoices": [
|
|
{
|
|
"number": "2024-0001",
|
|
"date": "2024-07-31",
|
|
...
|
|
}
|
|
]
|
|
}
|
|
```
|