*`getAppFolder()`: Get the filesystem path to the PostalPoint installation folder.
*`getPluginFolder(pluginName)`: Get the filesystem path to a plugin's folder.
If used without arguments, gets the root plugin storage 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.
*`eventbus`: A [Framework7 event bus](https://framework7.io/docs/events#events-bus) that parts of PostalPoint broadcast on. See docs/Events.md for details.
*`inject(barcodeData)`: Pass data to the internal barcode event subsystem. The data is handled as if it were just received from a physical barcode scanner.
PostalPoint supports multiple SQL databases, currently SQLite and MariaDB.
`global.apis.database.`:
*`async getConnection()`: Returns a database driver. See docs/Database.md for details.
#### Graphics
PostalPoint uses the Jimp library version 1.6 for creating and manipulating images and shipping labels.
`global.apis.graphics.`:
*`Jimp()`: The [JavaScript Image Manipulation Program](https://jimp-dev.github.io/jimp/). Access like so: `const {Jimp} = global.apis.graphics.Jimp();`.
*`async loadFont(filename)`: Replacement for [Jimp's loadFont](https://jimp-dev.github.io/jimp/api/jimp/functions/loadfont/), which gets very confused about our JS environment and ends up crashing everything.
Note: Functions will throw an error if a mailbox number is not valid (must be alphanumeric).
Use `boxNumberValid(number)` to validate user input and avoid errors.
`global.apis.mailboxes.`:
*`FormPS1583`: PS Form 1583 object. See docs/FormPS1583.md
*`boxNumberValid(number)`: Returns true if the mailbox number is an acceptable format, false if it isn't. Does not check if the box actually exists, merely if the number is acceptable to use as a mailbox number.
*`async getList()`: Get the list of mailboxes and boxholders as an array of objects (see below)
*`async addDaysToMailbox(boxNumber, days = 0, months = 0)`: Add a number of days or months to a mailbox's expiration.
*`async setMailboxExpirationDate(boxNumber, date)`: Set the box expiration to a specific JavaScript Date object, or a UNIX timestamp (in seconds).
*`async createMailbox(number, size, notes)`: Create a new mailbox number with the specified box size. Throws an error if the box number is already in use.
*`async editMailbox(oldNumber, newNumber, newSize = null)`: Change the number and/or size of a mailbox while preserving the boxholders and packages associated. If only changing size, set oldNumber and newNumber to the same value.
*`async deleteMailbox(number)`: Delete a mailbox. Throws an error if the mailbox has boxholders attached.
*`async closeMailbox(number)`: Close a mailbox by removing the boxholders and marking it as vacant. Boxholder PS Form 1583 records are archived per USPS regulations.
*`async mailboxExists(number)`: Returns true if the mailbox number exists, false if it doesn't.
*`async addOrUpdateBoxholder(boxNumber, info)`: Modify or add a boxholder to a mailbox. `info` is the boxholder structure below. If the `uuid` given already belongs to a boxholder, their info is updated with what you supply. Otherwise, the info is added as a new boxholder.
*`async removeBoxholder(boxNumber, uuid)`: Remove a boxholder by their UUID, and archive their PS Form 1583 data per USPS regulations.
*`async get1583(boxNumber, uuid, archiveNumber = false)`: Get the FormPS1583 object for a boxholder by UUID. If `archiveNumber` is true, returns the form for a deleted boxholder from the archive.
*`async set1583(boxNumber, uuid, formps1583)`: Set the FormPS1583 object for a boxholder by UUID.
*`async getMailboxProducts()`: Get a list of merchandise items that are usable for mailbox renewals. See below.
##### Mailbox getList() output
```js
[{
num: "123", // Box number as string
expires: 1234567890, // UNIX timestamp (in seconds) or false if box vacant
size: "2", // Box size, 1-10
notes: "", // Notes for mailbox, not currently shown in Mailbox Manager UI but may be used in the future
barcode: "", // Unique barcode for the mailbox, for future use
renewalMerchID: "", // Merchandise item ID used for autorenewing this mailbox
isBusiness: false, // True if the box is for a business, false if for personal use
names: [], // Array of boxholders, see Boxholder structure below
packages: [], // Array of packages awaiting pickup, see below
vacant: false // True if the box is currently vacant, else false
}]
```
##### Boxholder structure
Unless noted, all fields are strings and default to an empty string if data not available.
*`getReceiptID()`: Get the unique alphanumeric ID for the current transaction/receipt. This is the same code printed on receipts and used in digital receipt URLs.
*`addToolsPage(page, title, id = "", description = "", cardTitle = "", icon = "", type = "page")`: Add a page to the Tools screen. See examples/basic-demo for example usage. If `type` is set to "function", the `page` argument will be run as a function and will not be expected to return a page component.
*`getCustomerDisplayInfo()`: Describes if the customer-facing display is currently enabled, and if it supports customer touch interaction: `{"enabled": true, "touch": true}`.
*`clearCustomerScreen()`: Clear any custom content on the customer-facing display, defaulting back to blank/receipt/shipping rates, as applicable.
*`setCustomerScreen(content, type = "html", displayInCard = false, cardSize = [300, 300])`: Encodes `content` as a data URI (example: `` `data:text/html;charset=utf-8,${content}` ``) and renders on the customer-facing display. If `type` is `html`, renders the string as HTML. If `type` is `pdf`, displays a PDF viewer. If `type` is `raw`, functions like setting an iframe's src to `content`. All other `type` values are rendered as `text/plain`. To display the iframe in a card centered on the screen, set displayInCard to true and pass the desired dimensions (w, h) of the card in px. If the requested size is larger than the available screen space, the card will instead fill the available space. Warning: Do not load third-party websites, this is a security risk. Wrap it in a `<webviewsrc="..."></webview>` tag if you need to display one.
*`collectSignatureFromCustomerScreen()`: Show a signature pad on the customer-facing display. When the customer indicates the signature is finished, the `customerSignatureCollected` event is emitted with the data `{"svg": "data:image/svg+xml;base64,...", "png": "data:image/png;base64,..."}`
*`cancelSignatureCollection()`: Cancels customer signature collection and returns the customer-facing display to normal operation.
*`clearSignaturePad()`: Erase the signature on the customer-facing display. Note that the customer is also provided a button to do this.
*`async barcode.getBuffer(data, type = "code128", height = 10, scale = 2, includetext = false)`: Get a PNG image buffer of a barcode. Uses library "bwip-js".
*`async barcode.getBase64`: Same as `barcode.getBuffer` except returns a base64 image URL.
*`clipboard.copy(text, showNotification = false)`: Copy a string to the system clipboard, optionally showing a "copied" notification to the user.
*`async delay(ms = 1000)`: Pause execution for some amount of time in an async function, i.e., returns a Promise that resolves in some number of milliseconds.
*`async http.fetch(url, responseType = "text", timeout = 15)`: Fetch a URL. `responseType` can be "text", "blob", "buffer", or "json". Timeout is in seconds.
*`async http.post(url, data, responseType = "text", headers = {"Content-Type": "application/json"}, method = "POST", continueOnBadStatusCode = false)`: POST to a URL. `data` is sent as a JSON body.
*`objectEquals(a, b)`: Compare two objects for equality.
*`string.chunk(str, chunksize)`: Split a string into an array of strings of length `chunksize`.
*`string.split(input, separator, limit)`: Split a string with a RegExp separator an optionally limited number of times.
*`time.diff(compareto)`: Get the number of seconds between now and the given UNIX timestamp.
*`time.format(format, timestamp = time.now())`: Take a UNIX timestamp in seconds and format it to a string. (Mostly) compatible with PHP's date() function.
*`time.now()`: Get the current UNIX timestamp in seconds.
*`time.strtotime(str)`: Parse a string date and return a UNIX timestamp.
*`time.toDateString(timestamp)`: Get a localized date string for a UNIX timestamp.
*`time.toTimeString(timestamp)`: Get a time string for a UNIX timestamp, for example, "2:01 PM".
*`uuid.v4()`: Generate a version 4 UUID string, for example, "fcca5b12-6a11-46eb-96e4-5ed6365de977".
*`uuid.short()`: Generate a 16-character random alphanumeric string, for example, "4210cd8f584e6f6c".
