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
title*
string - Title of the goods or servicedescription
string - Description of the goods or servicelink
string - URL link to the web page for the product or sevicedate
string - The date the goods or service were provided, in a format satisfying RFC3339; e.g. 2017-08-25
amount*
number - Unit Price per item (excluding tax)tax*
number - Amount of tax charged for unitquantity*
integer - Number of units
Invoice
* denotes a required field
id*
string - Unique identifier for the invoice; e.g. AUS-0001-A
date*
string - Date the invoice is issued, in a format satisfying RFC3339; e.g. 2017-08-25
due
string - Date the invoice is due, in a format satisfying RFC3339; e.g. 2017-08-25
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 logoaddress*
[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 issuerposition*
string - Position / role of the contact person representing the issuertel*
string - Telephone number of the contact person representing the issuerfax
string - Fax number of the contact person representing the issueremail*
string - Email of the contact person representing the issueraddress*
[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
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 invoiceeposition*
string - Position / role of the contact person representing the invoiceetel
string - Telephone number of the invoiceeemail
string - Email of the invoicee
items*
[Items] - A list of items included in the invoice (see the Item
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.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.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'
) .destination
string - the destination directory where you want to the invoice to be outputted at (e.g. './tmp'
)format
string - format of the page, valid values are 'A3'
, 'A4'
, 'A5'
, 'Legal'
, 'Letter'
, 'Tabloid'
orientation
string - orientation of the page, valid values are 'portrait'
and 'landscape'
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
- Set up code styling with ESLint
- Provide better documentation on how to create your own template