Skip to content

API

Members

eventbus

A Framework7 event bus that PostalPoint broadcasts events with. See docs/Events.md for details.

graphics

PostalPoint uses the Jimp library version 1.6 for creating and manipulating images and shipping labels.

reports

Define custom reports for the user.

Objects

i18n : object

Functions to help support multiple currencies and countries.

settings : object

PostalPoint provides a UI for user-configurable plugin settings. See exports.config in examples/basic-demo/plugin.js for details. Settings are typically very short strings. Do not store data in settings. For data storage, see Storing Data. Non-string settings values are transparently converted to/from JSON objects. Use a unique key name prefix for your plugin to prevent key name conflicts. Reverse domain style is recommended (i.e. "com.example.pluginname.keyname").

storage : object

Get and set data.

database : object

Database connection

print : object

Printing to connected printers

kiosk : object

Self-serve kiosk mode

user : object

Access data about employees.

util : object

Various utility functions: HTTP, time/date, barcode creation, clipboard, etc.

Functions

getPluginFolder([id]) ⇒ string

Get the filesystem path to a plugin's installation folder.

getAppFolder() ⇒ string

Get the filesystem path to the PostalPoint installation folder.

f7()

The Framework7 app instance for PostalPoint's entire UI, created by new Framework7(). See https://framework7.io/docs/app for details. Be very careful.

alert(text, title, [callback])

Display a simple alert-style dialog box.

eventbus

A Framework7 event bus that PostalPoint broadcasts events with. See docs/Events.md for details.

Kind: global variable

graphics

PostalPoint uses the Jimp library version 1.6 for creating and manipulating images and shipping labels.

Kind: global variable

graphics.Jimp() ⇒ Jimp

The JavaScript Image Manipulation Program.

Kind: static method of graphics
Example 

const {Jimp} = global.apis.graphics.Jimp();

graphics.loadFont(filename) ⇒ Promise

Replacement for Jimp's loadFont function, which gets very confused about our JS environment and ends up crashing everything.

Kind: static method of graphics

Param Type
filename string

reports

Define custom reports for the user.

Kind: global variable

reports.registerReport(name, onload, date)

Kind: static method of reports

Param Type Description
name string Report name
onload function
date boolean If the report requires a date range be selected.

i18n : object

Functions to help support multiple currencies and countries.

Kind: global namespace

i18n.country() ⇒ string

Get the 2-character ISO country code that PostalPoint is running in.

Kind: static method of i18n
Returns: string - "US", "CA", etc.

i18n.currency() ⇒ string

Get the 3-character currency code in use.

Kind: static method of i18n
Returns: string - "usd", "cad", etc.

i18n.symbol() ⇒ string

Get the currency symbol.

Kind: static method of i18n
Returns: string - "$", "€", "₤", etc

i18n.decimals() ⇒ number

Get the number of decimal places for the currency: for example, USD has 2 ($x.00), KRW has 0 (x), UYW has 4 (x.0000).

Kind: static method of i18n
Returns: number - 0, 2, 3, or 4

i18n.convertCurrency(amount, fromCurrency, [toCurrency]) ⇒ Promise.<number>

Convert an amount of money to a different currency. Conversion rate is retrieved from the internet and cached for 4 hours.

Kind: static method of i18n

Param Type Default Description
amount number Amount of money in the "wrong" currency
fromCurrency string The currency code for the "wrong" currency that needs conversion
[toCurrency] string "getCurrencyCode()" The "correct" currency we want the amount to be in.

i18n.moneyToFixed(amount) ⇒ string

Returns the amount as a string formatted with the correct number of decimal places for the currency in use.

Kind: static method of i18n
Returns: string - "1.23", "1.2345", etc

Param Type
amount number

i18n.moneyString(amount) ⇒ string

Returns the amount as a string, with the correct decimal places, and the local currency symbol.

Kind: static method of i18n
Returns: string - "$1.23", etc

Param Type
amount number

settings : object

PostalPoint provides a UI for user-configurable plugin settings. See exports.config in examples/basic-demo/plugin.js for details. Settings are typically very short strings. Do not store data in settings. For data storage, see Storing Data. Non-string settings values are transparently converted to/from JSON objects. Use a unique key name prefix for your plugin to prevent key name conflicts. Reverse domain style is recommended (i.e. "com.example.pluginname.keyname").

Kind: global namespace

settings.get(key, defaultValue) ⇒ *

Get a setting.

Kind: static method of settings

Param Type Description
key string Setting key/ID
defaultValue * Value to return if setting has no stored value.

settings.set(key, value)

Set a setting.

Kind: static method of settings

Param Type Description
key string Setting key/ID
value string Value to set.

storage : object

Get and set data.

Kind: global namespace

storage.getSmall(key, defaultValue) ⇒ *

Get a value from the small data storage, using localStorage or a similar mechanism (may change in the future).

Kind: static method of storage

Param Type Description
key string Storage item key/ID
defaultValue * Value to return if the item key doesn't have a stored value.

storage.setSmall(key, value)

Set a value in the small data storage, using localStorage or a similar mechanism (may change in the future).

Kind: static method of storage

Param Type Description
key string Storage item key/ID
value * Value to store.

storage.getBig(key, defaultValue)

Get a value in the large data storage. Unserialized from a JSON file on disk.

Kind: static method of storage

Param Type Description
key string Storage item key/ID
defaultValue * Value to return if the item key doesn't have a stored value.

storage.setBig(key, value)

Set a value in the large data storage. Serialized to JSON and stored on disk as a file.

Kind: static method of storage

Param Type Description
key string Storage item key/ID
value * Value to store.

storage.getDB(key, defaultValue) ⇒ Promise.<*>

Get a value from the database storage. Unlike other storage types, values in the database are available on all PostalPoint installations in a single location.

Kind: static method of storage

Param Type Description
key string Storage item key/ID
defaultValue * Value to return if the item key doesn't have a stored value.

storage.setDB(key, value) ⇒ Promise

Set a value in the database storage. Non-string values are serialized to JSON. Unlike other storage types, values in the database are available on all PostalPoint installations in a single location.

Kind: static method of storage

Param Type Description
key string Storage item key/ID
value * Value to store.

database : object

Database connection

Kind: global namespace

database.getConnection() ⇒ Promise.<DatabaseAdapter>

Return a database connection object to run SQL against the store database. See the Database docs for details.

Kind: static method of database

Printing to connected printers

Kind: global namespace

print.printLabelImage(image)

Print a 300 DPI image on the shipping label printer, centered on a 4x6 inch label. Image is automatically scaled to 200 DPI if required by the printer.

Kind: static method of print

Param Type Description
image ArrayBuffer | Buffer | Uint8Array | string | Jimp image data, as a Jimp image object, raw PNG bytes, or a URL (http/https) string. 1200x1800 or 800x1200 images are scaled to 4x6 inches. Other image sizes are assumed to be 300 DPI and are centered on the shipping label. Image orientation is rotated to match the label orientation.

print.getReceiptPrinter() ⇒ Promise.<Object>

Get the receipt printer interface. See the ReceiptPrinter docs for available functions.

Kind: static method of print

print.printReceiptData(data)

Send raw data (generated by the printer interface) to the receipt printer.

Kind: static method of print

Param Type Description
data string | Uint8Array | Array.<string> | Array.<Uint8Array> Data to send to printer.

print.imageToBitmap(jimpImage, [dpiFrom], [dpiTo]) ⇒ Object

Convert a Jimp image object to 1-bit monochrome image data before sending image data to a printer interface. Optionally scales the image to a different DPI before conversion.

Kind: static method of print
Returns: Object - - Example: {width: 300, height: 200, img: Uint8Array}. Pass img to drawImage on a printer interface.

Param Type Default Description
jimpImage Jimp
[dpiFrom] number 300 Original image DPI.
[dpiTo] number 300 New image DPI.

kiosk : object

Self-serve kiosk mode

Kind: global namespace

kiosk.isKiosk() ⇒ boolean

Check if PostalPoint is running in kiosk mode.

Kind: static method of kiosk
Returns: boolean - - True if system is in kiosk mode, else false.

user : object

Access data about employees.

Kind: global namespace

user.User

Kind: static class of user
Properties

Name Type Description
id number
name string
pass string
barcode string
enabled boolean
hasPassword function Returns true if the user has a password set, else false.
checkPassword function Returns true if the provided password matches the user's password, or if there is no password set.
icon function Returns a SVG data URI with a procedurally-generated icon for the user. Size defaults to 50px if not specified.

new User(id, name, password, barcode, enabled)

A User object.

Param Type
id number
name string
password string
barcode string
enabled boolean

user.getUser() ⇒ User

Get the user currently logged in.

Kind: static method of user

user.getUserID() ⇒ number

Get the current user's ID number.

Kind: static method of user

user.getUserByID() ⇒ Promise.<User>

Look up the User for an ID number.

Kind: static method of user

user.listUsers([managerMode]) ⇒ Promise.<Array.<User>>

Get a list of all users in the system.

Kind: static method of user

Param Type Default Description
[managerMode] boolean false If false, list only active/enabled users, and if no users, return a default user account (user ID -1). If true, return all users in the database, and don't return a default account if the list is empty (return an empty list instead).

util : object

Various utility functions: HTTP, time/date, barcode creation, clipboard, etc.

Kind: global namespace

util.uuid : object

Unique ID generators.

Kind: static namespace of util

uuid.v4() ⇒ string

Generate a UUID string

Kind: static method of uuid
Returns: string - UUID v4 with dashes: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

uuid.short([length]) ⇒ string

Generate a short random alphanumeric string.

Kind: static method of uuid
Returns: string - A string of length length, from the character set "acdefhjkmnpqrtuvwxy0123456789".

Param Type Default Description
[length] number 16 String character count.

util.http : object

HTTP requests and webhooks.

Kind: static namespace of util

http.webhook : object

Use webhooks via a PostalPoint cloud relay service.

Kind: static namespace of http

webhook.geturl(sourcename) ⇒ Promise.<string>

geturl - Returns a public URL that can be used as a webhook target/endpoint for third-party integrations.

Kind: static method of webhook
Returns: Promise.<string> - A URL for the webhook.

Param Type Description
sourcename string Unique identifier for the webhook

webhook.poll(sourcename) ⇒ Promise.<Array.<Object>>

poll - Returns an array of webhook payloads received by the webhook identified by sourcename.

Kind: static method of webhook
Returns: Promise.<Array.<Object>> - Payloads as received by the webhook relay service.

Param Type Description
sourcename string Unique identifier for the webhook

Example 

[
     {
         // Unique ID. Used for ack(webhookid).
         id: 123,

         // UNIX timestamp (in seconds) of when the data was received by the webhook URL.
         timestamp: 1234567890,

         // Source name set in geturl()
         source: "sourcename",

         // JSON string of all the HTTP headers sent to the webhook URL.
         headers: "{'Content-Type': 'application/json'}",

         // Entire HTTP request body sent to the webhook URL.
         body: ""
     }
]

webhook.ack(webhookid)

ack - Acknowledge receipt of a webhook payload, deleting it from the relay server.

Kind: static method of webhook

Param Type Description
webhookid number Numeric unique ID received with the payload. See poll.

http.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) ⇒ Promise.<(string|Blob|ArrayBuffer|Object)>

post - Fetch a HTTP POST request.

Kind: static method of http
Returns: Promise.<(string|Blob|ArrayBuffer|Object)> - The server response body. See responseType parameter.

Param Type Default Description
url string
data Object.<string, string> POST data key/value list
[responseType] string "text" "text", "blob", "buffer", or "json"
[headers] Object.<string, string> HTTP headers to send. Defaults to {"Content-Type": "application/json"}.
[method] string "POST"
[continueOnBadStatusCode] boolean false If false, throws an Error when the HTTP response code is not 2XX. If true, ignores the response code and proceeds as normal.
[timeoutSeconds] number 15 Aborts the request (timeout) after this many seconds.

http.fetch(url, [responseType], [timeoutSeconds]) ⇒ Promise.<(string|Blob|ArrayBuffer|Object)>

fetch - Fetch a HTTP GET request.

Kind: static method of http
Returns: Promise.<(string|Blob|ArrayBuffer|Object)> - The server response body. See responseType parameter.

Param Type Default Description
url string
[responseType] string "text" "text", "blob", "buffer", or "json"
[timeoutSeconds] number 15 Aborts the request (timeout) after this many seconds.

util.string : object

String manipulation functions.

Kind: static namespace of util

string.split(input, separator, [limit]) ⇒ Array.<string>

Split a string with a separator regex.

Kind: static method of string

Param Type Description
input string Input string
separator string Passed to new RegExp(separator, 'g')
[limit] number Maximum number of splits to perform

string.chunk(input, chunksize) ⇒ Array.<string>

Split a string into chunks of length chunksize.

Kind: static method of string

Param Type Description
input string Input string
chunksize string Number of characters per chunk

util.time : object

Date and time functions

Kind: static namespace of util

time.now() ⇒ number

Get the current UNIX timestamp in seconds.

Kind: static method of time

time.diff(compareto) ⇒ number

Get the number of seconds between now and the given Date or UNIX timestamp in seconds.

Kind: static method of time

Param Type
compareto number | Date

time.strtotime(str) ⇒ number

Parse a string date and return UNIX timestamp (in seconds).

Kind: static method of time

Param Type
str string

time.format(format, [timestamp]) ⇒ string

Take a Date or UNIX timestamp in seconds and format it to a string. Mostly compatible with the PHP date format codes.

Kind: static method of time

Param Type Default Description
format string "Y-m-d H:i:s", etc
[timestamp] number | Date now()

time.toDateString(timestamp) ⇒ string

Format a UNIX timestamp (in seconds) as a localized date string.

Kind: static method of time

Param Type
timestamp number

time.toTimeString(timestamp) ⇒ string

Format a UNIX timestamp (in seconds) as a localized time string.

Kind: static method of time

Param Type
timestamp number

util.clipboard : object

OS clipboard

Kind: static namespace of util

clipboard.copy(text, [showNotification]) ⇒ Promise.<boolean>

Copy a string to the system clipboard.

Kind: static method of clipboard
Returns: Promise.<boolean> - True if the copy succeeded, else false.

Param Type Default Description
text string
[showNotification] boolean false If true, a "Copied" notification will appear onscreen briefly.

util.barcode : object

Barcode image generation functions.

Kind: static namespace of util

barcode.getBuffer(data, [type], [height], [scale], [includetext]) ⇒ Promise.<Buffer>

Get a PNG image buffer of a barcode. Uses library "bwip-js".

Kind: static method of barcode
Returns: Promise.<Buffer> - PNG data for the barcode.

Param Type Default Description
data string
[type] string "\"code128\""
[height] number 10
[scale] number 2
[includetext] boolean false Set true to render the barcode's content as text below the code.

barcode.getBase64(data, [type], [height], [scale], [includetext]) ⇒ Promise.<string>

Get a PNG image of a barcode as a base64 data URI. Uses library "bwip-js".

Kind: static method of barcode
Returns: Promise.<string> - "data:image/png;base64,..."

Param Type Default Description
data string
[type] string "\"code128\""
[height] number 10
[scale] number 2
[includetext] boolean false Set true to render the barcode's content as text below the code.

util.geography : object

Kind: static namespace of util

geography.isoToCountryName(iso) ⇒ string

Get a human-readable country name from an ISO country code.

Kind: static method of geography

Param Type Description
iso string | number 2 or 3 letter country code, or numeric country code.

util.objectEquals(a, b) ⇒ boolean

Compare two objects for equality. See https://stackoverflow.com/a/16788517

Kind: static method of util
Returns: boolean - True if equal, else false.

Param Type
a *
b *

util.delay([ms]) ⇒ Promise

Pause execution for some amount of time in an async function, i.e., returns a Promise that resolves in some number of milliseconds.

Kind: static method of util

Param Type Default Description
[ms] number 1000 Number of milliseconds to pause.

getPluginFolder([id]) ⇒ string

Get the filesystem path to a plugin's installation folder.

Kind: global function
Returns: string - "/home/user/.config/postalpoint-retail/Default/storage/plugins/...", "C:\Users\user\AppData...", etc

Param Type Description
[id] string Plugin ID. If omitted or empty, will return the parent folder plugins are installed within.

getAppFolder() ⇒ string

Get the filesystem path to the PostalPoint installation folder.

Kind: global function

f7()

The Framework7 app instance for PostalPoint's entire UI, created by new Framework7(). See https://framework7.io/docs/app for details. Be very careful.

Kind: global function

alert(text, title, [callback])

Display a simple alert-style dialog box.

Kind: global function

Param Type Default Description
text string Body text of the dialog.
title string Dialog title.
[callback] function Function to call when the alert is closed.