Metadata-Version: 2.4
Name: ivce
Version: 0.1.1
Summary: Local-first CLI for contractor invoices from YAML files.
Project-URL: Homepage, https://github.com/dmnelson/ivce
Project-URL: Source, https://github.com/dmnelson/ivce
Project-URL: Issues, https://github.com/dmnelson/ivce/issues
Author: David Nelson
License-Expression: MIT
License-File: LICENSE
Keywords: cli,contractor,invoice,invoices,ivce,pdf,typst
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.7
Requires-Dist: pypdf>=4.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# ivce

ivce is a local-first CLI for creating, validating, rendering, and emailing contractor invoices from YAML files.

It is designed for service invoices over explicit date ranges, with optional reimbursable expenses and PDF receipt bundles.

## Requirements

- Python 3.12+
- Typst CLI for PDF rendering: `brew install typst`

## Install

```bash
pip install ivce
```

The PyPI package is named `ivce`; it installs the `ivce` command.

## Development Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## Usage

```bash
ivce init
ivce new standard 2026-06
ivce new standard 2026-08 --contractor acme --client globex --reference-profiles
ivce new standard 2026-05 --period-start 2026-05-01 --period-end 2026-05-31
ivce new standard 2026-05 --period-start 2026-05-01 --period-end 2026-05-07 --invoice-number INV-202605-W1 --output workspace/invoices/2026-05-w1.yml
ivce new reimbursement 2026-07
ivce validate workspace/invoices/2026-07.yml
ivce validate private-client/invoices/2026-07.yml --workspace private-client
ivce render workspace/invoices/2026-06.yml
ivce render private-client/invoices/2026-06.yml --workspace private-client
ivce render workspace/invoices/2026-06.yml --template classic
ivce render workspace/invoices/2026-07.yml --with-receipts
ivce email workspace/invoices/2026-06.yml --dry-run
ivce email private-client/invoices/2026-06.yml --workspace private-client --dry-run
```

Generated PDFs are written to `workspace/dist/` by default. Rendered Typst source is written next to the PDF to make debugging template issues straightforward.

## Files

- `workspace/invoice.yml`: contractor/client defaults.
- `workspace/contractors/name.yml`: reusable contractor profiles.
- `workspace/clients/name.yml`: reusable client profiles.
- `workspace/invoices/YYYY-MM.yml`: invoice data with explicit service period dates.
- `workspace/receipts/YYYY-MM/`: optional receipt attachments.
- `workspace/dist/`: generated invoice PDFs and receipt bundles.

## Receipt Formats

Receipt bundles support `pdf`, `jpg`, `jpeg`, `png`, `heic`, and `heif` receipt files. PDF receipts can contain multiple pages. Image receipts are rendered into the bundle as one receipt page per image. HEIC/HEIF support uses the macOS `sips` command to convert images locally before bundling.

```yaml
expenses:
  - date: "2026-07-03"
    description: Train ticket
    amount: "25.00"
    receipt: receipts/2026-07/train-ticket.jpg
```

## Examples

Public fake examples live in `examples/sample-data`. They cover all built-in templates, profile references, a weekly billing period, and reimbursement display modes.

```bash
ivce validate examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data
ivce render examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data
```

Quickstart with the included sample workspace:

```bash
ivce templates list
ivce validate examples/sample-data/invoices/2026-06-modern.yml --workspace examples/sample-data
ivce render examples/sample-data/invoices/2026-06-classic.yml --workspace examples/sample-data --output-dir /tmp/invoice-example
```

## Templates

The CLI ships with three built-in Typst/Jinja2 templates:

- `modern`: polished default with a branded header and summary band.
- `classic`: conservative business invoice.
- `minimal`: sparse type-driven layout for simple retainers.

List templates and render with a specific one:

```bash
ivce templates list
ivce render workspace/invoices/2026-06.yml --template modern
ivce render workspace/invoices/2026-06.yml --template-file ./templates/client.typ.j2
```

Template choices and branding are copied into each generated invoice so old invoices can be rerendered consistently:

```yaml
template: modern
brand_color: "#1f4e79"
accent_color: "#d9e8f5"
font: New Computer Modern
```

## Contractor and Client Profiles

Invoices can either snapshot contractor/client data or reference reusable profile files.

Reusable profiles live in:

```text
workspace/contractors/acme.yml
workspace/clients/globex.yml
```

Snapshot mode is the default. It resolves profiles and copies their current values into the invoice YAML:

```bash
ivce new standard 2026-08 --contractor acme --client globex
```

Reference mode keeps the invoice smaller and resolves profiles when validating, rendering, or emailing:

```bash
ivce new standard 2026-08 --contractor acme --client globex --reference-profiles
```

That creates invoice fields like:

```yaml
contractor_ref: acme
client_ref: globex
```

Profile references are profile names, not paths. Receipt paths may be absolute or relative to the
selected workspace.

## Emailing With Gmail

Client email settings live in each invoice under `client`:

```yaml
client:
  name: Globex Corporation
  billing_email: accounts@example.com
  cc:
    - manager@example.com
  email_from: you@example.com
```

Send through Gmail SMTP with a Gmail app password:

```bash
export GMAIL_USER="you@example.com"
export GMAIL_APP_PASSWORD="your-app-password"
ivce email workspace/invoices/2026-06.yml
```

By default, `ivce email` attaches `workspace/dist/YYYY-MM.pdf`. Use `--pdf` or `--receipt-bundle` to override or add attachments.

For non-default workspaces, pass `--workspace` to `validate`, `render`, and `email` so referenced profiles, receipts, and default output paths resolve from that workspace.

## Privacy and Safety

Invoice data is stored in local YAML files. Generated PDFs, Typst outputs, receipt bundles, and the
default `workspace/` directory are intended to stay private and are ignored by this repository.

Email is sent only when `ivce email` is run without `--dry-run`. Always validate and render an
invoice before sending it.

## Data Model

Currency is a string field, so USD is supported without hardcoding the tool to USD only. Monetary amounts are decimal values and are formatted with two fractional digits.

Due dates are optional. Set `due_date` directly on an invoice, or set
`defaults.payment_terms_days` to generate one automatically. If neither is present, the PDF
and default email body omit the due date.
