@invoicer/cli 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,236 @@
+# @invoicer/cli
+
+Professional invoice generator with timesheet integration. Turn hours into polished PDF invoices and email them automatically—all from the command line.
+
+- ⚡ **Fast** - Generate invoices in seconds
+- 📋 **Smart** - Auto-fills client details from config
+- 🔢 **Auto-numbering** - Tracks invoice numbers per month
+- 📊 **Multi-line items** - Add services with different rates
+- 📧 **Email integration** - Send via SMTP automatically
+- 🌍 **Open source** - MIT licensed
+
+## Installation
+
+```bash
+npm install -g @invoicer/cli
+```
+
+Then run:
+```bash
+invoicer --help
+```
+
+## Quick Start
+
+### 1. Configure Your Details
+
+Create or edit `~/.invoicer/config.json`:
+
+```json
+{
+  "from": {
+    "name": "Your Name",
+    "email": "you@example.com",
+    "address": "Your Address"
+  },
+  "client": [
+    {
+      "name": "Acme Corp",
+      "email": "billing@acme.com",
+      "address": "123 Business St",
+      "currency": "USD",
+      "defaultRate": 50,
+      "payPeriodType": "Net 30"
+    }
+  ]
+}
+```
+
+### 2. Generate an Invoice
+
+```bash
+invoicer
+```
+
+Interactive prompts will guide you through:
+- Client selection
+- Hours worked
+- Hourly rate
+- Line item details
+- Additional items (optional)
+
+### 3. Output
+
+PDF is saved to:
+```
+./out/{client-name}/Invoice_YYYYMM_01.pdf
+```
+
+## Usage
+
+### Interactive Mode (Recommended)
+
+```bash
+invoicer
+```
+
+### With CLI Arguments
+
+```bash
+# Specific month and hours
+invoicer --month=2026-02 --hours=160 --rate=75
+
+# Custom invoice number
+invoicer --invoice=INV-202602-007
+
+# Specific description for first item
+invoicer --desc="Web Development Services"
+```
+
+### Generate Current Month's Invoice
+
+```bash
+invoicer:month
+```
+
+This automatically fills the current month (YYYY-MM).
+
+## Features
+
+### Invoice Number Auto-Generation
+
+Format: `{prefix}-{YYYYMM}-{sequence}`
+
+Example: `INV-202602-001`, `INV-202602-002`
+
+Sequence numbers are tracked per month and per client, stored in `data/last.json`.
+
+### Multiple Line Items
+
+Add as many services as needed:
+- Description (e.g., "Development", "Design")
+- Hours worked
+- Hourly rate
+- Period (from/to dates)
+
+Running calculation shown after each item.
+
+### Email Integration (Optional)
+
+After PDF generation, you'll be prompted:
+```
+Send invoice via email? (y/n)
+```
+
+Automatically:
+- Attaches PDF
+- Uses client email from config
+- Professional subject and body
+- Error handling if SMTP not configured
+
+## Configuration
+
+### config.json Structure
+
+```json
+{
+  "from": {
+    "name": "string",           // Your name
+    "email": "string",          // Your email
+    "address": "string"         // Your business address
+  },
+  "client": [
+    {
+      "name": "string",         // Client name
+      "email": "string",        // Client email
+      "address": "string",      // Client address
+      "currency": "string",     // USD, EUR, GBP, etc.
+      "defaultRate": 50,        // Default hourly rate
+      "payPeriodType": "Net 30" // Payment terms
+    }
+  ],
+  "invoicePrefix": "INV"        // (Optional) Prefix for invoice numbers
+}
+```
+
+### Environment Variables (.env)
+
+For email sending:
+
+```bash
+cp .env.example .env
+```
+
+```
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=465
+SMTP_USER=your@gmail.com
+SMTP_PASS=your-app-password
+INVOICE_FROM=Your Name <your@gmail.com>
+```
+
+**For Gmail:**
+1. Enable 2FA on your Google account
+2. Create App Password: https://myaccount.google.com/apppasswords
+3. Use the 16-character password in `SMTP_PASS`
+
+## Data Files
+
+The CLI stores data locally:
+
+```
+~/.invoicer/
+├── config.json              # Your configuration
+├── data/
+│   ├── last.json           # Last used hours/rate per client
+│   ├── timesheet.json      # Time entries (optional)
+│   └── active-timer.json   # Timer state (optional)
+└── .env                    # SMTP credentials
+```
+
+## Output
+
+All PDFs saved to: `./out/{client-name}/`
+
+Example structure:
+```
+out/
+├── Acme Corp/
+│   ├── Invoice_202602_001.pdf
+│   └── Invoice_202602_002.pdf
+└── TechCorp/
+    └── Invoice_202602_001.pdf
+```
+
+## Development
+
+```bash
+# Build TypeScript
+npm run build
+
+# Run tests
+npm test
+
+# Build and run
+npm run invoice
+
+# Current month shortcut
+npm run invoice:month
+```
+
+## Links
+
+- **Website:** https://invoicer.inbrief.sh/
+- **GitHub:** https://github.com/miladezzat/InvoicePilot
+- **Issues:** https://github.com/miladezzat/InvoicePilot/issues
+- **Desktop App:** https://invoicer.inbrief.sh/ (cross-platform with timer)
+
+## License
+
+MIT © 2026 Milad Fahmy
+
+## Support
+
+For issues, questions, or suggestions:
+- GitHub Issues: https://github.com/miladezzat/InvoicePilot/issues
+- Website: https://invoicer.inbrief.sh/

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "@invoicer/cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Professional invoice generator with timesheet integration and CLI support",
+  "homepage": "https://invoicer.inbrief.sh/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/miladezzat/InvoicePilot"
+  },
+  "bugs": {
+    "url": "https://github.com/miladezzat/InvoicePilot/issues"
+  },
   "type": "module",
   "preferGlobal": true,
   "bin": {
     "invoicer": "./scripts/invoice.mjs"
   },
+  "files": [
+    "scripts/",
+    "dist/",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "invoice": "npm run build && node scripts/invoice.mjs",

package/.env.example

@@ -1,15 +0,0 @@
-# SMTP Configuration for Email Sending
-# Copy this file to .env and fill in your details
-
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=465
-SMTP_USER=your@email.com
-SMTP_PASS=your_app_password
-INVOICE_FROM="Your Name <your@email.com>"
-
-# Gmail App Password Setup:
-# 1. Go to https://myaccount.google.com/security
-# 2. Enable 2-Factor Authentication
-# 3. Go to App Passwords: https://myaccount.google.com/apppasswords
-# 4. Create app password for "Mail" on "Other (Custom name)"
-# 5. Copy the 16-character password and use it as SMTP_PASS

package/config.json

@@ -1,19 +0,0 @@
-{
-  "client": [
-    {
-      "address": "",
-      "currency": "USD",
-      "defaultRate": 40,
-      "email": "miladezzat.f+dasix@gmail.com",
-      "name": "Dasix Inc.",
-      "payPeriodType": "Net 7"
-    }
-  ],
-  "defaultDescription": "",
-  "from": {
-    "address": "Test",
-    "email": "miladezzat.f@gmail.com",
-    "name": "Milad"
-  },
-  "invoicePrefix": "INV"
-}

package/data/last.json

@@ -1,11 +0,0 @@
-{
-  "clients": {
-    "Dasix Inc.": {
-      "lastHours": 34.56,
-      "lastRate": 40,
-      "seqByMonth": {
-        "2026-02": 4
-      }
-    }
-  }
-}