Create HTML and PDF receipts and invoices

Examples

Overview

At its core, Revoice simply combines data into a Handlebars template to generate a HTML file. After that, it uses PhantomJS to render the page and writes it into a PDF file.

Apart from that, it also performs a few more functions:

Provides Handlebar helpers that enables you to create your own templates

Uses JSON Schema-compliant schema

Uses he to decode HTML

Getting Started

Installation

You can install revoice through npmjs.com

$ yarn add revoice

Usage

import Revoice from 'revoice'; const data = { "id": "yvjhn76b87808", "date": "2017-02-02", "issuer": { "name": "Brew Creative Limited", "address": [ "1905, Nan Fung Centre", "264-298 Castle Peak Road", "Tsuen Wan", "New Territories", "Hong Kong" ], "contact": { "name": "Daniel Li", "tel": "+852 1234 5678", "email": "dan@brew.com.hk" } }, "invoicee": { "name": "Cerc Lannister" }, "items": [{ "id": "7A73YHAS", "title": "Amazon Echo Dot (2nd Generation)", "date": "2017-02-02", "amount": 39.99, "tax": 10.00, "quantity": 12 }] } const options = { template: 'default', destination: path, name: 'index' } Revoice.generateHTMLInvoice(data, options); // Returns a promise

Data Schema

The schema for the invoice and each item can be found under /src/schema . The schema are written in accordance with the JSON Schema specification, and are validated using Ajv.

Item

* denotes a required field

id* string - Unique identifier for the item; e.g. UG23H7F9Y

string - Unique identifier for the item; e.g. title* string - Title of the goods or service

string - Title of the goods or service description string - Description of the goods or service

string - Description of the goods or service link string - URL link to the web page for the product or sevice

string - URL link to the web page for the product or sevice date string - The date the goods or service were provided, in a format satisfying RFC3339; e.g. 2017-08-25

string - The date the goods or service were provided, in a format satisfying RFC3339; e.g. amount* number - Unit Price per item (excluding tax)

number - Unit Price per item (excluding tax) tax* number - Amount of tax charged for unit

number - Amount of tax charged for unit quantity* integer - Number of units

Invoice

* denotes a required field

id* string - Unique identifier for the invoice; e.g. AUS-0001-A

string - Unique identifier for the invoice; e.g. date* string - Date the invoice is issued, in a format satisfying RFC3339; e.g. 2017-08-25

string - Date the invoice is issued, in a format satisfying RFC3339; e.g. due string - Date the invoice is due, in a format satisfying RFC3339; e.g. 2017-08-25

string - Date the invoice is due, in a format satisfying RFC3339; e.g. issuer* object - Details about the party issuing the invoice name* string - Name of the issuer; e.g. Acme Corp logo string - URL of the issuer's logo address* [string] - An array of string that composes the issuer's address; e.g. ["123 Example Street", "London", "United Kingdom", "W1 2BC"] contact* object - Details of the issuer's contact details name* string - Name of the contact person representing the issuer position* string - Position / role of the contact person representing the issuer tel* string - Telephone number of the contact person representing the issuer fax string - Fax number of the contact person representing the issuer email* string - Email of the contact person representing the issuer address* [string] - An array of string that composes the contact person's address (this may be different to the issuer's registered address); e.g. ["123 Example Street", "London", "United Kingdom", "W1 2BC"] website string - Website of the contact person representing the issuer

object - Details about the party issuing the invoice invoicee* object - Details of the entity the invoice is addressed to name* string - Name of the invoicee; e.g. Jon Snow address [string] - An array of string that composes the invoicee's address; e.g. ["123 Example Street", "London", "United Kingdom", "W1 2BC"] contact object - Details of the invoicee's contact details name string - Name of the invoicee position* string - Position / role of the contact person representing the invoicee tel string - Telephone number of the invoicee email string - Email of the invoicee

object - Details of the entity the invoice is addressed to items* [Items] - A list of items included in the invoice (see the Item schema above)

[Items] - A list of items included in the invoice (see the schema above) comments string - Any messages/comments the issuer wishes to convey to the invoicee

Options

Default options can be accessed at Revoice.DEFAULT_OPTIONS , which evaluates to:

{ template: 'default', destination: './tmp', format: 'A3', orientation: 'portrait', margin: '1cm', }

A detailed explanation of available options is as follows:

name string - the name to give to the invoice file(s). For example, you can use your invoice number as the name of the file E.g. YG87ASDG . Overrules the nomenclature option.

string - the name to give to the invoice file(s). For example, you can use your invoice number as the name of the file E.g. . Overrules the option. nomenclature string - the rules for which files are named. Valid values are 'hash' , which will generate a SHA512 hash of the HTML invoice and use that as the name of the file. Is overruled by the name option.

string - the rules for which files are named. Valid values are , which will generate a SHA512 hash of the HTML invoice and use that as the name of the file. Is overruled by the option. template string - the template to use for the invoice. You can specify a pre-defined template by using its name (e.g. 'default' ), or specify your own template by entering the path to the file (e.g. './test/sample/templates/test.html' ) .

string - the template to use for the invoice. You can specify a pre-defined template by using its name (e.g. ), or specify your own template by entering the path to the file (e.g. ) . destination string - the destination directory where you want to the invoice to be outputted at (e.g. './tmp' )

string - the destination directory where you want to the invoice to be outputted at (e.g. ) format string - format of the page, valid values are 'A3' , 'A4' , 'A5' , 'Legal' , 'Letter' , 'Tabloid'

string - format of the page, valid values are , , , , , orientation string - orientation of the page, valid values are 'portrait' and 'landscape'

string - orientation of the page, valid values are and margin string - margin on the page. Should be a number followed by a unit (e.g. '1cm' ). Valid units are 'mm' , 'cm' , 'in' , 'px'

format , orientation and margin options are derived from PhantomJS's paperSize object options

Testing

Make sure you're running the latest version of Node (currently 7.8.0) and yarn (currently 0.19.1).

Clone the repository, install the dependencies and run the coverage script.

$ git clone https://github.com/brewhk/revoice.git $ cd revoice/ $ yarn $ yarn run coverage

TODOs