GithubHelp home page GithubHelp logo

revoice's Introduction

Build Status codecov Codacy Badge CodeFactor Code Climate VersionEye NSP Status

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": "[email protected]"
    }
  },
  "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 service
  • description string - Description of the goods or service
  • link 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
  • amount* number - Unit Price per item (excluding tax)
  • tax* 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
  • 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 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
  • 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
  • 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

revoice's People

Contributors

d4nyll avatar dependabot[bot] avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.