Skip to content

Latest commit

 

History

History
158 lines (119 loc) · 4.41 KB

README.org

File metadata and controls

158 lines (119 loc) · 4.41 KB
Raw

Easy Invoice Maker

Description

Easily generate PDF invoices which are emailed automatically to the client. From a simple YAML file, a PDF invoice is generated and sent to the client.

Example:

to:
  name: Alice Smith
  email: [email protected]
items:
  - name: Development
    description: Website design and development.
    qtyHrs: 65
    unitPrice: 100
  - name: Domain hosting
    description: 1 year
    qtyHrs: 1
    unitPrice: 180

See examples for complete exampes.

Features

  • User-friendly templating
    • The invoice and email templates use Mustache for easy customization
  • Automatic emailing
    • The invoice is automatically sent to the client from your account.
  • Type-safe YAML parsing
    • For example, qtyHrs (quantity/hours) is supposed to be a number, so if any other type of value is given (e.g., abc), the parsing will fail and show a helpful error message. Likewise, any missing parameters will be caught.
  • Type-safe money operations
    • The safe-money Haskell library offers type-safe and lossless encoding and operations for monetary values in all world currencies. This means that rounding errors won’t occur when calculating the invoice prices.

Installation and usage

This project uses nix. It also depends on wkhtmltopdf, which will be installed with the resulting application.

To include it in your nix environment, add it to your list of packages in your configuration:

{ pkgs, ... }:

let
  easy-invoice-maker = (import (builtins.fetchGit {
    name = "easy-invoice-maker";
    url = "https://github.com/SlimTim10/easy-invoice-maker/";
  }));

in
{
  environment.systemPackages = with pkgs; [
    easy-invoice-maker
  ];
}

Or, use Nix flakes and add it as an input:

{
  inputs = {
    # ...
    easy-invoice-maker = {
      url = "github:SlimTim10/easy-invoice-maker";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { easy-invoice-maker , ... }: {
    # ...
    easy-invoice-maker.packages."${pkgs.system}".easy-invoice-maker
  };
}

Add or edit the parameter files (see following sections)

  • defaults.yaml
  • 0047.yaml (a file with the invoice number as its name)
  • email.yaml

Create an invoice:

$ easy-invoice-maker 0047.yaml

This will create the invoice file 0047.pdf.

Development

Build:

$ nix-build

Or, using Nix flakes:

$ nix build

Add or edit the parameter files (see following sections)

  • defaults.yaml
  • 0047.yaml (a file with the invoice number as its name)
  • email.yaml

Use the resulting binary:

$ ./result/bin/easy-invoice-maker 0047.yaml

This will create the invoice file 0047.pdf.

Invoice parameters

The invoice body information must be in YAML format (e.g., see 0047.yaml). The file should be provided as an argument to easy-invoice-maker. A second file, defaults.yaml should be located in the same directory as the invoice body file. See defaults.yaml and 0047.yaml for basic example.

defaults.yaml is for setting the default from and notes (string, optional) information to use in every invoice. These can be overridden by providing values in the invoice body.

The invoice body contains:

  • date (string, optional)
  • from (optional)
    • name (string)
    • website (string, optional)
    • email (string)
  • to
    • name (string)
    • email (string)
  • items (list)
    • name (string)
    • description (string, optional)
    • qtyHrs (number)
    • unitPrice (number)

Email

Put email and SMTP information in email.yaml, in the same directory as the invoice body. For Gmail, create an app password (help center).

Adding dependencies

  • Update easy-invoice-maker.cabal
  • Update easy-invoice-maker.nix

If the package is not found, get it from GitHub:

$ cabal2nix --no-check https://github.com/JustusAdam/mustache.git --revision 530c0f10188fdaead9688d56f728b87fabcb228b > nix/mustache.nix
  • Update default.nix

For more information, read: https://github.com/Gabriella439/haskell-nix/tree/main/project1

TO-DO

  • Allow confirmation before emailing PDF