0cb8ad3d11
Add --print to regenerate PDFs from invoices.json without ledger writes. Support optional dueDate on ledger rows (default remains invoice date + 14 days) and persist dueDate when saving new production rows. Data: limmud_fsu_canada client with invoiceFileName, cruise_event_av_it product, 2026-LFSU01 sample invoice, Levkin contact fields in sender.json. README and project.md describe CLI, schema, and May 2026 changelog. Co-authored-by: Cursor <cursoragent@cursor.com>
151 lines
3.7 KiB
Markdown
151 lines
3.7 KiB
Markdown
# Invoice Generator
|
||
|
||
A command-line tool for generating professional PDF invoices from JSON data files. Features interactive and non-interactive modes with preview-first workflow.
|
||
|
||
## Quick Start
|
||
|
||
1. **Install dependencies:**
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. **Generate an invoice:**
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
## Usage Options
|
||
|
||
### Interactive Mode (Recommended)
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
Guided wizard to select sender, client, and products.
|
||
|
||
### Non-Interactive Mode
|
||
|
||
```bash
|
||
npm run generate -- --sender levkin --client levitin --products linkedin_scraper web_design
|
||
```
|
||
|
||
### Test Mode
|
||
|
||
```bash
|
||
npm run test-invoice
|
||
```
|
||
|
||
Uses first available options for testing.
|
||
|
||
### Reprint an existing invoice (from ledger)
|
||
|
||
Generates a PDF from `data/invoices.json` only — **does not** change the ledger or run the preview prompt:
|
||
|
||
```bash
|
||
node index.js --print 2026-LFSU01
|
||
```
|
||
|
||
Output path: `invoice/<senderKey>/<filenamePrefix>_<number>.pdf`. The filename prefix is the client’s optional `invoiceFileName` in `client.json`, otherwise the client key.
|
||
|
||
**Due date on the PDF:** Each ledger row can include optional `"dueDate": "YYYY-MM-DD"`. If omitted, the tool uses invoice `date` plus 14 days.
|
||
|
||
All data is stored in the `data/` directory:
|
||
|
||
### `data/sender.json` - Your Company Profiles
|
||
|
||
```json
|
||
{
|
||
"levkin": {
|
||
"company": "Levkin Inc.",
|
||
"contactName": "Ilia Dobkin",
|
||
"phone": "647 987 2792",
|
||
"email": "idobkin@gmail.com",
|
||
"address": "6 Keefer Court",
|
||
"zip": "L4J 5Y4",
|
||
"city": "Thornhill, ON",
|
||
"country": "Canada",
|
||
"taxName": "HST",
|
||
"taxNumber": "79438 2895 RT0001",
|
||
"paymentInfo": "Bank transfer details..."
|
||
}
|
||
}
|
||
```
|
||
|
||
### `data/client.json` - Client Information
|
||
|
||
```json
|
||
{
|
||
"levitin": {
|
||
"company": "LEVITIN EMPLOYMENT LAWYERS",
|
||
"address": "#2809 - 330 Richmond Street West",
|
||
"zip": "M5V 0M4",
|
||
"city": "Toronto, ON",
|
||
"country": "Canada"
|
||
}
|
||
}
|
||
```
|
||
|
||
### `data/products.json` - Services/Products Catalog
|
||
|
||
```json
|
||
{
|
||
"linkedin_scraper": {
|
||
"description": "LinkedIn Scraper Bot",
|
||
"price": 250,
|
||
"taxRate": 13
|
||
},
|
||
"web_design": {
|
||
"description": "Website Design",
|
||
"price": 1200,
|
||
"taxRate": 13
|
||
}
|
||
}
|
||
```
|
||
|
||
## Workflow
|
||
|
||
1. **Preview Generation**: Creates a development preview PDF first
|
||
2. **Review**: Check the preview in `invoice/<sender>/<client>_<year>-DEV-PREVIEW.pdf`
|
||
3. **Confirmation**: Choose to create the production invoice or keep only the preview
|
||
4. **Production**: Generates final invoice with sequential numbering and saves to ledger
|
||
|
||
## Output Structure
|
||
|
||
```
|
||
invoice/
|
||
├── levkin/
|
||
│ ├── levitin_2025-0007.pdf # Production invoice
|
||
│ └── levitin_2025-DEV-PREVIEW.pdf # Preview
|
||
└── dobit/
|
||
└── ...
|
||
```
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
npm test
|
||
```
|
||
|
||
Tests cover invoice numbering logic including year resets and sequential ordering.
|
||
|
||
## Key Features
|
||
|
||
- **Safe Preview-First**: Always generates preview before production
|
||
- **Automatic Numbering**: Sequential invoice numbers (YYYY-0001, YYYY-0002...)
|
||
- **Year Reset**: Invoice numbers reset annually
|
||
- **Organized Output**: PDFs stored by sender in separate folders
|
||
- **Tax Support**: Configurable tax rates per product
|
||
- **Payment Info**: Custom payment instructions in footer
|
||
- **Ledger Tracking**: All invoices automatically recorded in `data/invoices.json`
|
||
- **Reprint mode** (`--print`): PDF from ledger without editing it
|
||
- **Optional `dueDate`** on ledger rows for custom payment deadlines when reprinting
|
||
|
||
See [project.md](project.md) for full schema, CLI details, and changelog.
|
||
|
||
## Requirements
|
||
|
||
- Node.js v16+
|
||
- npm
|