npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

revoice

v0.1.15

Published

Generate HTML / PDF receipts and invoices

Downloads

43

Readme

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