diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..26e9e3e --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/site +/.cache diff --git a/README.md b/README.md index 570df50..6f927ea 100644 --- a/README.md +++ b/README.md @@ -1,479 +1,5 @@ # PostalPoint Plugins -PostalPoint® supports JavaScript plugin extensions. Plugins can hook into PostalPoint to add features and integrations. +This repository is the source for the PostalPoint plugin development site. -## What plugins can do - -* Process card payments and handle saved payment methods -* Process cryptocurrency payments -* Add additional carriers, providing shipping rates and labels -* Print to label and receipt printers, letting PostalPoint handle hardware support and drivers -* Extend support for prepaid label acceptance, prepaid barcode recognition, and carrier dropoff QR codes -* Install pages in the Tools menu, creating new interfaces and features -* Receive transaction receipts for ingestion into third-party accounting or business software -* Display interactive HTML5 content on the customer-facing screen -* Run both Node.JS and browser code. - -## Plugin Package Structure - -A plugin is distributed as a simple ZIP file, containing a folder. The folder then has at least one file, named `plugin.js`. -The `exports.init` function in `plugin.js` is executed when PostalPoint launches, allowing the plugin -to request involvement with various events in PostalPoint. - -PostalPoint installs plugin packages by unzipping their contents into a plugins folder. -Plugins are uninstalled by deleting their folder. - -## Minimal Plugin Code - -```javascript -// plugin-name/plugin.js -exports.init = function () { - global.apis.alert("This message appears when PostalPoint launches.", "Hello!"); -}; -``` - -Yes, the smallest plugin really is just two lines of code, and accessing PostalPoint features -really is that easy. - -## Plugin Metadata File - -While not strictly required, a `package.json` is encouraged, and allows specifying the plugin's -display name, PostalPoint version compatibility, and using a filename other than `plugin.js` -for the main plugin script. - -Sample: - -```js -{ - "name": "plugin-id-here", - "main": "plugin.js", - "description": "Human-readable description of the plugin", - "version": "1.0.0", - "author": "Your Name", - "license": "Code license name", - "postalpoint": { - "pluginname": "Display Name for Plugin", - "minVersion": "000034", - "maxVersion": "001000" - } -} - -``` - -PostalPoint version codes are MMMnnn where MMM is the major version and nnn is the minor version, zero-padded. -So version 0.35 is "000035", and 1.23 is "001023". - -## Example Plugins - -Check out the `examples` folder for sample plugins demonstrating the API features. - -## PostalPoint Plugin API - -The PostalPoint plugin API is a globally-available object named `global.apis`. - -### API List - -Note: API functions shown here are available in the -[latest testing build](https://build.netsyms.net/job/PostalPoint_Retail/), -but may not yet be present in the most recent release. - -Functions listed as `async ...` return a Promise. - -#### Core - -`global.apis.`: - -* `alert(text, title)`: Display an alert dialog. -* `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. - -#### Barcode - -`global.apis.barcode.`: - -* `TrackingBarcode`: A class defining a prepaid barcode and related information. See docs/TrackingBarcode.md for details. -* `onPrepaidScan(function (codeString) {})`: The function passed to onPrepaidScan is run -when a barcode is scanned on the Prepaid page. The function is passed one argument, a string -containing the raw barcode data. The function shall return boolean `false` if unable or unwilling -to handle the barcode. If the barcode is handled by this function, it shall return a TrackingBarcode object. -* `addPrepaidBarcode(trackingBarcodeData)`: Add a TrackingBarcode object to the transaction receipt at any time other than `onPrepaidScan`. -* `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. - -#### Database - -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. - -#### International and Currency - -PostalPoint only officially supports the US and Canada, but does not prohibit use in other countries. -It's recommended to use these functions instead of assuming the US dollar. - -`global.apis.i18n.`: - -* `country()`: Returns the 2-character country code that PostalPoint is running in (examples: "US", "CA"). -* `currency()`: Returns the 3-character currency code (examples: "usd", "cad"). -* `symbol()`: Returns the currency symbol (example: "$"). -* `decimals()`: Returns the number of decimal places for the currency (2 for USD 1.23, 3 for TND 1.234, etc) -* `async convertCurrency(amount = 1.0, fromCurrency = "usd", toCurrency = global.apis.i18n.currency())`: Convert an amount of money to a different currency. Conversion rate is retrieved from the cloud service and cached for 4 hours. -* `moneyToFixed(amount)`: Returns the amount as a string with the correct number of decimal places. Same as running `amount.toFixed(global.apis.i18n.decimals())`. -* `moneyString(amount)`: Returns the money amount formatted as a string with currency symbol. Same as running `global.apis.i18n.symbol() + amount.toFixed(global.apis.i18n.decimals())`. - -#### Kiosk - -`global.apis.kiosk.`: - -* `isKiosk()`: Returns a boolean to indicate if PostalPoint is running in kiosk mode. - -#### Mailboxes - -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. - -```js -{ - name: [bizname, fname, mname, lname].filter(Boolean).join(" "), - fname: "", // First name - mname: "", // Middle name - lname: "", // Last name - email: "", // Email - phone: "", // Phone - uuid: "", // Customer UUID - bizname: "", // Business name - street1: "", // Street address - city: "", // City - state: "", // Two-character state - zipcode: "", // ZIP or postal code - country: "", // Two-character country code - primary: true // True if the primary (first) boxholder, false if an additional authorized mail recipient -} -``` - -##### Mailbox getList()[].packages format - -```js -{ - tracking: tracking ?? "[Untracked]", // Package tracking number - finalized: true, // True if package check-in is finished and shelf tag/mailbox slips printed, false if not finalized - available_date: Date(), // The date and time the package was checked in - tag: "" // Unique number assigned to the package and printed on shelf tags, scanned by employee when customer picks up package -} -``` - -##### Mailbox merchandise item format (getMailboxProducts) - -These fields are returned as entered in the Merchandise Admin user interface or as shown in the merchandise CSV export. - -```js -{ - id: "", // Unique ID for this entry in the merchandise table - name: "", // Merch item name - category: "", // Merch item category - price: 0.0, // Sale price in dollars - cost: 0.0, // Merchandise cost in dollars (likely not used for mailboxes) - barcode: "", // Barcode/UPC (likely not used for mailboxes) - tax: 0.0, // Sales tax rate - rentaldays: 30, // Number of days this item adds to a mailbox (mutually exclusive with rentalmonths) - rentalmonths: 1, // Number of months (mutually exclusive with rentaldays) - boxsize: "1" // Mailbox size tier, 1-10 -} -``` - -#### Point of Sale - -`global.apis.pos.`: - -* `addReceiptItem(item)`: Add a `ReceiptItem` to the current transaction. -* `addReceiptPayment(item)`: Add a `ReceiptPayment` to the current transaction. -* `addOnscreenPaymentLog(string)`: Append a line of text to the onscreen log displayed during credit card processing. Not shown in kiosk mode. -* `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. -* `onReceiptChange(function (receipt) {})`: Add a function to be called whenever the transaction data/receipt is changed. -* `onTransactionFinished(function (receipt) {})`: Same as `onReceiptChange` except run when a transaction is completed. -* `registerCardProcessor(...)`: Register the plugin as a credit card processor. See examples/payment-processor for details. -* `registerCryptoProcessor(...)`: Register the plugin as a cryptocurrency payment provider. See examples/crypto-processor for details. -* `ReceiptItem`: A class representing a sale item in the current transaction. See docs/Receipt.md for details. -* `ReceiptPayment`: A class representing a payment entry for the current transaction. See docs/Receipt.md for details. - -#### Printing - -`global.apis.print.`: - -* `async printLabelImage(image)`: Print a 300 DPI image to the configured shipping label printer. centered on a 4x6 shipping label. - If the printer is 200/203 DPI, the image is automatically scaled down to keep the same real size. - Accepts a Jimp image, or the raw image file data as a Node Buffer, ArrayBuffer, or Uint8Array. - Also accepts an http/https image URL, but it is recommended you fetch the image yourself and handle any network errors. - Recommended image size is 1200x1800, which is 4x6 inches at 300 DPI. 800x1200 images are assumed to be 4x6 but at 200 DPI. - For compatibility reasons, the bottom 200 pixels on an 800x1400 image is cropped off. - Images wider than they are tall will be rotated 90 degrees. Images that are 1200 or 800 pixels - wide and multiples of 1800 or 1200 pixels tall, respectively, are automatically split and printed - onto multiple 1200x1800 or 800x1200 labels. -* `async getReceiptPrinter()`: Get the receipt printer interface. See docs/ReceiptPrinter.md for available printer functions and example code. -* `async printReceiptData(data)`: Print the raw data generated by the receipt printer interface. -* `imageToBitmap(jimpImage, dpiFrom = 300, dpiTo = 300)`: Convert a Jimp image to monochrome 1-bit - pixel data for printing on a receipt printer. Converts color to grayscale, and grayscale is dithered to monochrome. - Optionally changes the image DPI. Use this to get image data for sending to a receipt printer. - Returns an object such as {width: 300, height: 200, img: Uint8Array}. Pass the img value to `drawImage`. - - -#### Reports - -Plugins can supply reports which the PostalPoint user can run. Reports can be exported to a CSV file. - -`global.apis.reports.`: - -* `registerReport(name, onload, date = true)`: Add a report to the Reports UI in PostalPoint. -`name` is the user-visible name of the report in the list. `onload` is an async function that -returns the report (see below for format). It is passed two arguments consisting of UNIX timestamps -for the start and end date selected by the user. Setting `date` to `false` turns off the date range -selection for reports that don't need a date range. - -##### Report format: - -Single table report: - -```js -{ - table: { - header: ["Column 1", "Column 2"], - datatypes: ["string", "string"], - rows: [ - ["Row 1 Col 1", "Row 1 Col 2"], - ["Row 2 Col 1", "Row 2 Col 2"] - ] - } -} -``` - -Multiple table report: (several tables in one report): - -```js -{ - multitable: true, - table: { - titles: ["Report 1 Title", "Report 2 Title"], - header: [["Report 1 Column 1", "Report 1 Column 2"], ["Report 2 Column 1", ...]], - datatypes: [["string", "string"], ["string", "string"]], - rows: [ - [ - ["Report 1 Row 1 Col 1", "Report 1 Row 1 Col 2"], - ["Report 1 Row 2 Col 1", "Report 1 Row 2 Col 2"] - ], - [ - ["Report 2 Row 1 Col 1", "Report 2 Row 1 Col 2"], - ["Report 2 Row 2 Col 1", "Report 2 Row 2 Col 2"] - ] - ] - } -} -``` - -##### Report datatypes/column values: - -With a few exceptions, report columns must be strings. -If the datatype provided is not recognized, it is treated as `string`. -Strings are displayed as-is, except newlines are replaced with markup -so multi-line data displays as expected. - -Special datatype values: - -* `datetime`: Column is a UNIX timestamp (in seconds). It is displayed as a formatted date and time string. -* `receiptid`: Column is a PostalPoint receipt ID number. -Displayed as a link. Clicking the ID will fetch and open the receipt in a popup. -* `userid`: Column contains an employee ID number from the PostalPoint database. It is queried in -the database and replaced with the employee's name, or with an empty string if the ID lookup has -no results. - -Other datatypes may be defined in the future, so always use `string` when no special behavior is desired. - -#### Settings/Configuration Storage - -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"`). - -`global.apis.settings.`: - -* `get(key, defaultValue)`: Get a setting value, or the `defaultValue` if the setting is not set. -* `set(key, value)`: Set a setting value. - - -#### Storing Data - -There are three key/value stores available in PostalPoint. - -1. `setSmall` and `getSmall` currently use -[localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) as a backend, -but this may change in the future. -2. `setBig` and `getBig` store the data to disk as a JSON file. -3. `setDB` and `getDB` store the data in the PostalPoint database, making stored data -available on the network to other PostalPoint installations. Depending on the backend in use, data -is stored either as a SQLite TEXT column or a MariaDB/MySQL LONGTEXT. - -`*Big` and `*Small` functions perform synchronous disk access while `*Database` functions are -asynchronous and return a Promise. - -String values are stored and fetched as-is; all other datatypes are encoded to JSON before saving, -and decoded back when fetched. - -Storing a value of `null` causes the key to be deleted. Fetching a key that doesn't exist without -specifying a default value returns `null`. - -Behavior if the host machine is out of disk space or has a drive failure is undefined. - -`global.apis.storage.`: - -* `getBig(key, defaultValue)` -* `setBig(key, value)` -* `getSmall(key, defaultValue)` -* `setSmall(key, value)` -* `async getDB(key, defaultValue)` -* `async setDB(key, value)` - - -#### Shipping and Rates - -`global.apis.shipping.`: - -* `Address`: A class representing an address. See docs/Address.md. -* `getZIPCode(zip)`: Get data for a 5-digit US ZIP Code, such as - `{"city": "HELENA", "state": "MT", "type": "STANDARD"}`. - Returns `false` if the ZIP Code isn't in the database. -* `getCarrierName(carrierId)`: Converts the carrier ID string into a consistent and human-readable name. Useful with registerMarkupCalculator. -See docs/Carrier_Service.md for info. -* `getServiceName(serviceId, carrier = "USPS")`: Converts the service ID string into a consistent and human-readable name. -Set the carrier ID for better results. Useful with registerMarkupCalculator. -See docs/Carrier_Service.md for info. -* `registerRateEndpoint(getRate, purchase, idPrefix)`: Register the plugin as a shipping rate and label provider. - See examples/shipping/plugin.js for example usage. -* `registerMarkupCalculator(function (cost, retail, suggested, carrier, service) {})`: -Register the plugin to modify PostalPoint's shipping markup calculation during shipment rating. -The function shall return either `false` (to opt out of making the decision) or a numeric retail price for the shipment rate. -Only one plugin may register with this function at a time. If a plugin attempts to register later, it will throw an `Error`. -See examples/shipping/plugin.js for details. - -#### UI - -`global.apis.ui.`: - -* `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. -* `showProgressSpinner(title, text = "", subtitle = "")`: Show a Framework7 notification with a loading icon. -* `hideProgressSpinner()`: hide the UI element created by `showProgressSpinner`. -* `openInternalWebBrowser(url)`: Open a web browser UI, navigating to the URL. The browser has forward/back/close buttons. -* `openSystemWebBrowser(url)`: Open the native OS default browser to the URL given. -* `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 `` 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. - - -#### Utilities - -Various useful helper functions. - -`global.apis.util.`: - -* `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". -* `async http.webhook.geturl(sourcename)`: Returns a URL that can be used as a webhook target/endpoint for third-party integrations. The `sourcename` is a unique identifier for the webhook. There is a limit on webhook payload size; large payloads over 500KB will be rejected by the server. -* `async http.webhook.poll(sourcename)`: Returns an array of webhook payloads received by the webhook URL generated by `geturl(sourcename)`. -* `async http.webhook.ack(webhookid)`: Acknowledge a webhook payload, clearing it from the list returned by `poll`. - -##### Webhook poll result format: - -```javascript -[ - { - // 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: "" - } -] -``` \ No newline at end of file +[Click here to go there.](https://dev.postalpoint.app) diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..a26a937 --- /dev/null +++ b/build.sh @@ -0,0 +1,7 @@ +#!/bin/bash + +rm -r docs/Plugin\ API +mkdir docs/Plugin\ API + +PLUGINAPISRC="$HOME/Documents/Projects/Sources/PostalPoint_Retail/src/js/pluginapi/*.js" +node jsdoc2md.js "$PLUGINAPISRC" diff --git a/docs/Address.md b/docs/Docs/Address.md similarity index 100% rename from docs/Address.md rename to docs/Docs/Address.md diff --git a/docs/Carrier_Service.md b/docs/Docs/Carrier_Service.md similarity index 100% rename from docs/Carrier_Service.md rename to docs/Docs/Carrier_Service.md diff --git a/docs/Database.md b/docs/Docs/Database.md similarity index 70% rename from docs/Database.md rename to docs/Docs/Database.md index d3d5fa7..8c41e0c 100644 --- a/docs/Database.md +++ b/docs/Docs/Database.md @@ -1,4 +1,4 @@ -# SQL Database Drivers +# Database Drivers `global.apis.database.getConnection()` returns one of these, depending on which database is in use. @@ -66,6 +66,63 @@ export class SQLiteAdapter { } ``` +## Remote host/master + +```javascript +export class RemoteDatabaseAdapter { + constructor() { + this.type = "remote"; + } + + async apirequest(args) { + var resp = await sendToPostalPointHTTPServer(args, "database"); + if (typeof resp.status == "string" && resp.status == "OK") { + return resp.result; + } else if (typeof resp.status == "string" && resp.status == "ERR") { + if (typeof resp.message == "string") { + throw new Error(resp.message); + } else { + throw new Error(resp); + } + } else { + throw new Error(resp); + } + } + + async query(query, replace = []) { + return await this.apirequest({type: "query", query: query, replace: replace}); + } + + async run(statement, replace = []) { + return await this.apirequest({type: "run", query: statement, replace: replace}); + } + + async exec(statement) { + return await this.apirequest({type: "exec", query: statement}); + } + + async exists(table, where, replace = []) { + return await this.apirequest({type: "exists", table: table, where: where, replace: replace}); + } + + async close() { + // NOOP: We don't care about this + } + + async tableExists(table) { + return await this.apirequest({type: "tableExists", table: table}); + } + + async getSchemaVersion() { + return await this.apirequest({type: "getSchemaVersion"}); + } + + async setSchemaVersion(version) { + // NOOP: Don't upgrade server's installation, it can do that itself + } +} +``` + ## MariaDB/MySQL ```javascript @@ -141,4 +198,4 @@ export class MariaDBAdapter { } } } -``` \ No newline at end of file +``` diff --git a/docs/Events.md b/docs/Docs/Events.md similarity index 93% rename from docs/Events.md rename to docs/Docs/Events.md index d6d8760..5e0d444 100644 --- a/docs/Events.md +++ b/docs/Docs/Events.md @@ -14,6 +14,7 @@ Plugins can use `global.apis.eventbus` to receive events when certain actions ha * `settingsSaved`: Emitted when PostalPoint's settings are saved. Usually this means the user changed a setting in the UI. * `pluginSettingsSaved`: Emitted when the user saves a plugin's settings. The plugin ID string is sent as the event data. * `packageCheckIn`: Emitted when a package is checked in to a mailbox or for Hold At Location. See below for event data details. +* `mailboxMailDelivered`: Emitted when mail delivery notifications are sent by the user. Data is an array of the mailbox numbers notifications are being sent for. ## Example Code @@ -36,7 +37,7 @@ For events that return an object instead of a single value. ### transactionFinished -See Receipt.md +See [Receipt](./Receipt.md) ### customerSignatureCollected @@ -60,4 +61,4 @@ See Receipt.md toLocker: "5", // Parcel locker number, or false if not going to a parcel locker. shelfLabelPrinted: true // Indicates if a shelf label was printed for this package. Will be false if going to a locker, if the user requested no label, or if the label failed to print. } -``` \ No newline at end of file +``` diff --git a/docs/FormPS1583.md b/docs/Docs/FormPS1583.md similarity index 100% rename from docs/FormPS1583.md rename to docs/Docs/FormPS1583.md diff --git a/docs/Parcel.md b/docs/Docs/Parcel.md similarity index 100% rename from docs/Parcel.md rename to docs/Docs/Parcel.md diff --git a/docs/Receipt.md b/docs/Docs/Receipt.md similarity index 100% rename from docs/Receipt.md rename to docs/Docs/Receipt.md diff --git a/docs/ReceiptPrinter.md b/docs/Docs/ReceiptPrinter.md similarity index 100% rename from docs/ReceiptPrinter.md rename to docs/Docs/ReceiptPrinter.md diff --git a/docs/TrackingBarcode.md b/docs/Docs/TrackingBarcode.md similarity index 100% rename from docs/TrackingBarcode.md rename to docs/Docs/TrackingBarcode.md diff --git a/docs/Examples/01Minimal.md b/docs/Examples/01Minimal.md new file mode 100644 index 0000000..875d9e0 --- /dev/null +++ b/docs/Examples/01Minimal.md @@ -0,0 +1,10 @@ +# Minimal Plugin + +This is the smallest possible valid plugin. + + +```js title="plugin-name/plugin.js" +exports.init = function () { + global.apis.alert("This message appears when PostalPoint launches.", "Hello!"); +}; +``` diff --git a/docs/Examples/02Basic.md b/docs/Examples/02Basic.md new file mode 100644 index 0000000..60a6b1b --- /dev/null +++ b/docs/Examples/02Basic.md @@ -0,0 +1,15 @@ +# Basic Plugin + +This sample plugin showcases some of the features many plugins will want to use. + +[Download JavaScript](basic-demo/plugin.js) + +```js title="plugin.js" +--8<-- "Examples/basic-demo/plugin.js" +``` + +[Download HTML](basic-demo/uipluginpage.f7) + +```html title="uipluginpage.f7" +--8<-- "Examples/basic-demo/uipluginpage.f7" +``` diff --git a/docs/Examples/03Shipping.md b/docs/Examples/03Shipping.md new file mode 100644 index 0000000..c0d21bc --- /dev/null +++ b/docs/Examples/03Shipping.md @@ -0,0 +1,9 @@ +# Shipping Plugin + +This sample plugin demonstrates how to add support for a custom shipping carrier. + +[Download JavaScript](shipping/plugin.js) + +```js title="plugin.js" +--8<-- "Examples/shipping/plugin.js" +``` diff --git a/docs/Examples/04CardProcessor.md b/docs/Examples/04CardProcessor.md new file mode 100644 index 0000000..2a15dff --- /dev/null +++ b/docs/Examples/04CardProcessor.md @@ -0,0 +1,11 @@ +# Card Payments + +This plugin template shows how to implement a card payment processor, +allowing PostalPoint to interface with your card reader/terminal hardware, +as well as saving, retrieving, and charging cards on file. + +[Download JavaScript](payment-processor/plugin.js) + +```js title="plugin-name/plugin.js" +--8<-- "Examples/payment-processor/plugin.js" +``` diff --git a/docs/Examples/05CryptoProcessor.md b/docs/Examples/05CryptoProcessor.md new file mode 100644 index 0000000..ea14c6f --- /dev/null +++ b/docs/Examples/05CryptoProcessor.md @@ -0,0 +1,10 @@ +# Cryptocurrency Payments + +This plugin template shows how to implement a cryptocurrency payment processor, +using the customer-facing display to show a payment QR code webpage. + +[Download JavaScript](crypto-processor/plugin.js) + +```js title="plugin-name/plugin.js" +--8<-- "Examples/crypto-processor/plugin.js" +``` diff --git a/examples/basic-demo/plugin.js b/docs/Examples/basic-demo/plugin.js similarity index 100% rename from examples/basic-demo/plugin.js rename to docs/Examples/basic-demo/plugin.js diff --git a/examples/basic-demo/uipluginpage.f7 b/docs/Examples/basic-demo/uipluginpage.f7 similarity index 100% rename from examples/basic-demo/uipluginpage.f7 rename to docs/Examples/basic-demo/uipluginpage.f7 diff --git a/examples/crypto-processor/plugin.js b/docs/Examples/crypto-processor/plugin.js similarity index 100% rename from examples/crypto-processor/plugin.js rename to docs/Examples/crypto-processor/plugin.js diff --git a/examples/payment-processor/plugin.js b/docs/Examples/payment-processor/plugin.js similarity index 100% rename from examples/payment-processor/plugin.js rename to docs/Examples/payment-processor/plugin.js diff --git a/examples/shipping/plugin.js b/docs/Examples/shipping/plugin.js similarity index 56% rename from examples/shipping/plugin.js rename to docs/Examples/shipping/plugin.js index 8a89065..d58e59b 100644 --- a/examples/shipping/plugin.js +++ b/docs/Examples/shipping/plugin.js @@ -4,7 +4,10 @@ var rateCache = []; var parcelCache = {}; exports.init = function () { + // Add support for shipping rating and label purchasing global.apis.shipping.registerRateEndpoint(getRates, purchase, "uniqueprefixhere_"); + + // Add support for prepaid drop-offs global.apis.barcode.onPrepaidScan(function (barcode) { if (barcode.startsWith("mycarrierbarcode")) { // Replace this with your checks for barcode validity var data = new global.apis.barcode.TrackingBarcode(barcode); @@ -14,46 +17,6 @@ exports.init = function () { } return false; }); - - - - /* - * Plugins can override PostalPoint's built-in shipment markup calculation. - * Only one plugin on an instance of PostalPoint can register, on a first-come basis. - * This function throws an Error if another plugin has already registered. - */ - /** - * Add your code for calculating shipping markup. - * @param {number} cost Cost to shipper - * @param {number} retail Carrier-suggested retail price - * @param {number} suggested PostalPoint-suggested retail (default margin calc) - * @param {string} carrier Shipping carrier name - * @param {string} service Shipping service code - * @param {number|null} weightOz The weight of the shipment in ounces, or null if not available. - * @param {string} packaging An empty string if not available, or "Letter", "FlatRateEnvelope", etc. See https://docs.easypost.com/docs/parcels#predefined-packages - * @returns {Boolean|number} false if opting out of setting markup, otherwise the retail price - */ - global.apis.shipping.registerMarkupCalculator( - function (cost, retail, suggested, carrier, service, weightOz, packaging) { - if (carrier == "USPS") { - if (service == "First-Class Mail") { - // Handle First-Class Mail differently if it's a 1oz letter (i.e. Forever stamp) - if (weightOz <= 1 && packaging == "Letter") { - return retail + 0.05; - } else { - return retail + 0.25; - } - } - // Handle flat rate envelopes differently - if (global.apis.shipping.getServiceName(service, carrier) == "Priority Mail" && packaging == "FlatRateEnvelope") { - return retail + 1.0; - } - return suggested + 2.0; // Charge the PostalPoint-calculated amount plus $2 - } else { - return cost * 2; // Charges the customer double the shipment's cost. - } - } - ); } async function purchase(rateid) { @@ -116,4 +79,4 @@ async function getRates(parcel) { parcelCache = parcel; return rates; -} \ No newline at end of file +} diff --git a/docs/Plugin API/barcode.md b/docs/Plugin API/barcode.md new file mode 100644 index 0000000..c530e9c --- /dev/null +++ b/docs/Plugin API/barcode.md @@ -0,0 +1,86 @@ + + +## barcode : object +Handle tracking barcodes + +**Kind**: global namespace + +* [barcode](#barcode) : object + * [.TrackingBarcode](#barcode.TrackingBarcode) + * [new TrackingBarcode(code)](#new_barcode.TrackingBarcode_new) + * [.addPrepaidBarcode(trackingBarcodeData)](#barcode.addPrepaidBarcode) + * [.inject(barcodeData)](#barcode.inject) + * [.onPrepaidScan(f)](#barcode.onPrepaidScan) + + + +### barcode.TrackingBarcode +**Kind**: static class of [barcode](#barcode) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| tracking | string | Tracking number | +| barcode | string | Original barcode data this was created from | +| toZip | string | Destination ZIP Code, for domestic shipments. The city and state are automatically added. If toAddress is specified, toZip is ignored in favor of it. | +| toCountry | string | Two-letter destination country code. If it doesn't match the country PostalPoint is running in, the full country name is appended to the displayed address information. | +| toAddress | string | Destination mailing/shipping address. | +| carrier | string | Shipping carrier name. | +| service | string | Shipping service/mail class name. Example: "Priority Mail". | +| dropoff | boolean | If set to false, the barcode will be rejected with a suitable message when PostalPoint is running in self-serve kiosk mode. | +| confidentCarrier | boolean | If false, PostalPoint may prompt user to specify the shipping carrier. | +| extraInfo | Array.<string> | Extra description strings, like "Signature Required". | +| message | string | If not empty, the barcode will NOT be added and the contents of `message` will be displayed to the user. | +| warning | string | If not empty, the barcode WILL be added and the contents of `warning` will be displayed to the user. | +| destString | string | (read only) Get the destination information as a human-presentable multiline string. | +| serviceString | string | (read only) Get the carrier and service. | +| toString() | function | Get the package information in a format suitable for display on a receipt. | +| toString(false) | function | Get the package information in a format suitable for display on a receipt, suppressing the tracking number. | + + + +#### new TrackingBarcode(code) +A Tracking barcode object. + + +| Param | Type | Description | +| --- | --- | --- | +| code | string | Barcode data | + + + +### barcode.addPrepaidBarcode(trackingBarcodeData) +Add a TrackingBarcode object to the transaction receipt at any time other than `onPrepaidScan`. + +**Kind**: static method of [barcode](#barcode) + +| Param | Type | +| --- | --- | +| trackingBarcodeData | TrackingBarcode | + + + +### barcode.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. + +**Kind**: static method of [barcode](#barcode) + +| Param | Type | +| --- | --- | +| barcodeData | string | + + + +### barcode.onPrepaidScan(f) +The function passed to onPrepaidScan is run when a barcode is scanned on the Prepaid page. +The function is passed one argument, a string containing the raw barcode data. +The function shall return boolean false if unable or unwilling to handle the barcode. +If the barcode is handled by this function, it shall return a TrackingBarcode object. + +**Kind**: static method of [barcode](#barcode) + +| Param | Type | +| --- | --- | +| f | function | + diff --git a/docs/Plugin API/database.md b/docs/Plugin API/database.md new file mode 100644 index 0000000..58e3685 --- /dev/null +++ b/docs/Plugin API/database.md @@ -0,0 +1,12 @@ + + +## 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](#database) diff --git a/docs/Plugin API/fs.md b/docs/Plugin API/fs.md new file mode 100644 index 0000000..28a71c0 --- /dev/null +++ b/docs/Plugin API/fs.md @@ -0,0 +1,81 @@ + + +## fs : object +Basic filesystem access utility functions, wrapping Node.JS and/or NW.JS code. + +**Kind**: global namespace + +* [fs](#fs) : object + * [.openFileSaveDialog(suggestedFilename, fileExtensions)](#fs.openFileSaveDialog) ⇒ Promise.<(string\|null)> + * [.openFileBrowseDialog(chooseFolder, accept, dialogTitle)](#fs.openFileBrowseDialog) ⇒ string \| null + * [.writeFile(filename, data, encoding, flag)](#fs.writeFile) ⇒ Promise + * [.readFile(filename, encoding, flag)](#fs.readFile) ⇒ Promise.<(string\|Buffer)> + * [.fileExists(filename)](#fs.fileExists) ⇒ boolean + + + +### fs.openFileSaveDialog(suggestedFilename, fileExtensions) ⇒ Promise.<(string\|null)> +Open a file save as dialog prompting the user to save a file. +Opens to the user's Documents folder, with sane fallbacks if it cannot be located. + +**Kind**: static method of [fs](#fs) +**Returns**: Promise.<(string\|null)> - The full file path the user selected, or null if they cancelled. + +| Param | Type | Description | +| --- | --- | --- | +| suggestedFilename | string | The filename string to pre-fill in the dialog. | +| fileExtensions | string | The file type filter to show. Examples: ".csv", ".csv,.html" | + + + +### fs.openFileBrowseDialog(chooseFolder, accept, dialogTitle) ⇒ string \| null +Open a file browse/file open dialog prompting the user to select a file or folder. +Opens to the user's Documents folder, with sane fallbacks if it cannot be located. + +**Kind**: static method of [fs](#fs) +**Returns**: string \| null - The selected file/folder path, or null if cancelled. + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| chooseFolder | boolean | false | Set to true to choose a folder instead of a file. | +| accept | string | | File filter. ".csv,.html", "image/*", etc. | +| dialogTitle | string \| null | null | Title of the file open dialog. | + + + +### fs.writeFile(filename, data, encoding, flag) ⇒ Promise +Write a file to disk. + +**Kind**: static method of [fs](#fs) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| filename | string | | The path and filename to write to. | +| data | string \| Buffer \| ArrayBuffer \| Uint8Array | | Data to write to the file. | +| encoding | string \| null | "utf8" | Text encoding. Set to empty if not passing string data. | +| flag | string \| null | "w+" | Filesystem flag. | + + + +### fs.readFile(filename, encoding, flag) ⇒ Promise.<(string\|Buffer)> +Read a file from disk and return its contents. + +**Kind**: static method of [fs](#fs) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| filename | string | | The path and filename to read from. | +| encoding | string | "utf8" | File encoding. Set to null or empty string when reading binary data. | +| flag | string | "r+" | Filesystem flag. | + + + +### fs.fileExists(filename) ⇒ boolean +Check if a file exists. + +**Kind**: static method of [fs](#fs) + +| Param | Type | Description | +| --- | --- | --- | +| filename | string | Path and filename to check. | + diff --git a/docs/Plugin API/global functions.md b/docs/Plugin API/global functions.md new file mode 100644 index 0000000..c576da8 --- /dev/null +++ b/docs/Plugin API/global functions.md @@ -0,0 +1,38 @@ + + +## f7 +The Framework7 app instance for PostalPoint's entire UI, created by new Framework7(). +See https://framework7.io/docs/app for details. + +**Kind**: global constant + + +## 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 + + +## 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. | + diff --git a/docs/Plugin API/graphics.md b/docs/Plugin API/graphics.md new file mode 100644 index 0000000..0ded118 --- /dev/null +++ b/docs/Plugin API/graphics.md @@ -0,0 +1,33 @@ + + +## graphics : object +PostalPoint uses the Jimp library version 1.6 for creating and manipulating images and shipping labels. + +**Kind**: global namespace + +* [graphics](#graphics) : object + * [.Jimp()](#graphics.Jimp) ⇒ Jimp + * [.loadFont(filename)](#graphics.loadFont) ⇒ Promise + + + +### graphics.Jimp() ⇒ Jimp +The [JavaScript Image Manipulation Program](https://jimp-dev.github.io/jimp/). + +**Kind**: static method of [graphics](#graphics) +**Example** +```js +const {Jimp} = global.apis.graphics.Jimp(); +``` + + +### graphics.loadFont(filename) ⇒ Promise +Replacement for [Jimp's loadFont function](https://jimp-dev.github.io/jimp/api/jimp/functions/loadfont/), +which gets very confused about our JS environment and ends up crashing everything. + +**Kind**: static method of [graphics](#graphics) + +| Param | Type | +| --- | --- | +| filename | string | + diff --git a/docs/Plugin API/i18n.md b/docs/Plugin API/i18n.md new file mode 100644 index 0000000..a5f3d4f --- /dev/null +++ b/docs/Plugin API/i18n.md @@ -0,0 +1,107 @@ + + +## i18n : object +Functions to help support multiple currencies and countries. + +**Kind**: global namespace + +* [i18n](#i18n) : object + * [.country()](#i18n.country) ⇒ string + * [.currency()](#i18n.currency) ⇒ string + * [.symbol()](#i18n.symbol) ⇒ string + * [.decimals()](#i18n.decimals) ⇒ number + * [.convertCurrency(amount, fromCurrency, [toCurrency])](#i18n.convertCurrency) ⇒ Promise.<number> + * [.moneyToFixed(amount)](#i18n.moneyToFixed) ⇒ string + * [.moneyString(amount)](#i18n.moneyString) ⇒ string + * [.currencyMinorToMajor(amount)](#i18n.currencyMinorToMajor) ⇒ number + * [.currencyMajorToMinor(amount)](#i18n.currencyMajorToMinor) ⇒ number + + + +### i18n.country() ⇒ string +Get the 2-character ISO country code that PostalPoint is running in. + +**Kind**: static method of [i18n](#i18n) +**Returns**: string - "US", "CA", etc. + + +### i18n.currency() ⇒ string +Get the 3-character currency code in use. + +**Kind**: static method of [i18n](#i18n) +**Returns**: string - "usd", "cad", etc. + + +### i18n.symbol() ⇒ string +Get the currency symbol. + +**Kind**: static method of [i18n](#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](#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](#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](#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](#i18n) +**Returns**: string - "$1.23", etc + +| Param | Type | +| --- | --- | +| amount | number | + + + +### i18n.currencyMinorToMajor(amount) ⇒ number +Convert an amount in cents to dollars (or the local equivalent currency units). + +**Kind**: static method of [i18n](#i18n) +**Returns**: number - Dollars, etc + +| Param | Type | Description | +| --- | --- | --- | +| amount | number | Cents, etc | + + + +### i18n.currencyMajorToMinor(amount) ⇒ number +Convert an amount in dollars to cents (or the local equivalent currency units). + +**Kind**: static method of [i18n](#i18n) +**Returns**: number - Cents, etc + +| Param | Type | Description | +| --- | --- | --- | +| amount | number | Dollars, etc | + diff --git a/docs/Plugin API/kiosk.md b/docs/Plugin API/kiosk.md new file mode 100644 index 0000000..bc1d744 --- /dev/null +++ b/docs/Plugin API/kiosk.md @@ -0,0 +1,13 @@ + + +## 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](#kiosk) +**Returns**: boolean - - True if system is in kiosk mode, else false. diff --git a/docs/Plugin API/mailboxes.md b/docs/Plugin API/mailboxes.md new file mode 100644 index 0000000..99114a6 --- /dev/null +++ b/docs/Plugin API/mailboxes.md @@ -0,0 +1,258 @@ + + +## mailboxes : object +Add, modify, and delete mailboxes and mailbox customers. + +**Kind**: global namespace + +* [mailboxes](#mailboxes) : object + * [.FormPS1583](#mailboxes.FormPS1583) + * [new FormPS1583()](#new_mailboxes.FormPS1583_new) + * [.getList(filter)](#mailboxes.getList) ⇒ Promise.<Array> + * [.addDaysToMailbox(boxNumber, days, months)](#mailboxes.addDaysToMailbox) ⇒ Promise + * [.setMailboxExpirationDate(boxNumber, date)](#mailboxes.setMailboxExpirationDate) ⇒ Promise + * [.createMailbox(number, size, notes, barcode)](#mailboxes.createMailbox) ⇒ Promise + * [.editMailbox(oldNumber, newNumber, newSize, barcode)](#mailboxes.editMailbox) ⇒ Promise + * [.deleteMailbox(number)](#mailboxes.deleteMailbox) ⇒ Promise + * [.closeMailbox(number)](#mailboxes.closeMailbox) ⇒ Promise + * [.mailboxExists(number)](#mailboxes.mailboxExists) ⇒ Promise.<boolean> + * [.addOrUpdateBoxholder(boxNumber, info)](#mailboxes.addOrUpdateBoxholder) ⇒ Promise + * [.removeBoxholder(boxNumber, uuid)](#mailboxes.removeBoxholder) ⇒ Promise + * [.get1583(boxNumber, uuid, archiveNumber)](#mailboxes.get1583) ⇒ Promise.<FormPS1583> + * [.set1583(boxNumber, uuid, formps1583)](#mailboxes.set1583) ⇒ Promise + * [.boxNumberValid()](#mailboxes.boxNumberValid) ⇒ boolean + * [.getMailboxProducts()](#mailboxes.getMailboxProducts) ⇒ Promise.<Array> + + + +### mailboxes.FormPS1583 +**Kind**: static class of [mailboxes](#mailboxes) + + +#### new FormPS1583() +USPS Form PS1583 object, with all the fields needed by USPS for CMRA customers. + + + +### mailboxes.getList(filter) ⇒ Promise.<Array> +Get the list of mailboxes and boxholders as an array of objects, see example. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| filter | null \| object | | Filter to mailboxes matching a column condition, such as `getList({number: "102"})` or `getList({"size >=": "2"})`. Supported filter names include "number" (string, box number), "expires" (expiration date), "size" (number 1-10), and "barcode" (string) SQL injection warning: Filter names are inserted directly into query strings without sanitization. Only the values are safe for user input. | + +**Example** +```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 addOrUpdateBoxholder for the format. + packages: [], // Array of packages awaiting pickup, see below + vacant: false // True if the box is currently vacant, else false +}] +``` +**Example** +```js +// Data objects in the packages array: +{ + tracking: tracking ?? "[Untracked]", // Package tracking number + finalized: true, // True if package check-in is finished and shelf tag/mailbox slips printed, false if not finalized + available_date: Date(), // The date and time the package was checked in + tag: "" // Unique number assigned to the package and printed on shelf tags, scanned by employee when customer picks up package +} +``` + + +### mailboxes.addDaysToMailbox(boxNumber, days, months) ⇒ Promise +Add a number of days or months to a mailbox's expiration. Use either days or months, not both. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| boxNumber | string | | Mailbox number. | +| days | number | 0 | Days to add. | +| months | number | 0 | Months to add. | + + + +### mailboxes.setMailboxExpirationDate(boxNumber, date) ⇒ Promise +Set the box expiration to a specific JavaScript Date object, or a UNIX timestamp (in seconds). + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | +| --- | --- | +| boxNumber | string | +| date | number \| Date | + + + +### mailboxes.createMailbox(number, size, notes, barcode) ⇒ Promise +Create a new mailbox number with the specified box size. Throws an error if the box number is already in use. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| number | string | Mailbox number | +| size | number | Box size (1 - 10) | +| notes | string | Arbitrary string with human-readable notes about the box. | +| barcode | null \| string | A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail. | + + + +### mailboxes.editMailbox(oldNumber, newNumber, newSize, barcode) ⇒ Promise +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. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| oldNumber | string | | Currently assigned box number. | +| newNumber | string | | New box number. Must not exist yet. | +| newSize | number \| null | | Box size (1 - 10), if changing the size. | +| barcode | null \| string | | A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail. | + + + +### mailboxes.deleteMailbox(number) ⇒ Promise +Delete a mailbox. Throws an Error if the mailbox has boxholders attached. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| number | string | Mailbox number to delete. | + + + +### mailboxes.closeMailbox(number) ⇒ Promise +Close a mailbox by removing the boxholders and marking it as vacant. +Boxholder PS Form 1583 records are automatically archived per USPS regulations. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| number | string | Mailbox number to close. | + + + +### mailboxes.mailboxExists(number) ⇒ Promise.<boolean> +Returns true if the mailbox number exists, false if it doesn't. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| number | string | Mailbox number to check. | + + + +### mailboxes.addOrUpdateBoxholder(boxNumber, info) ⇒ Promise +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. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| boxNumber | string | Mailbox number | +| info | Object | Boxholder information. | + +**Example** +```js +// Unless noted, all fields are strings and default to an empty string. +{ + name: [bizname, fname, mname, lname].filter(Boolean).join(" "), + fname: "", // First name + mname: "", // Middle name + lname: "", // Last name + email: "", // Email + phone: "", // Phone + uuid: "", // Customer UUID + bizname: "", // Business name + street1: "", // Street address + city: "", // City + state: "", // Two-character state + zipcode: "", // ZIP or postal code + country: "", // Two-character country code + primary: true // True if the primary (first) boxholder, false if an additional authorized mail recipient +} +``` + + +### mailboxes.removeBoxholder(boxNumber, uuid) ⇒ Promise +Remove a boxholder by their UUID, and archive their PS Form 1583 data per USPS regulations. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| boxNumber | string | Mailbox number. | +| uuid | string | Boxholder UUID. | + + + +### mailboxes.get1583(boxNumber, uuid, archiveNumber) ⇒ Promise.<FormPS1583> +Get the FormPS1583 object for a boxholder by UUID. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| boxNumber | string | | Mailbox number. | +| uuid | string | | Boxholder UUID. | +| archiveNumber | boolean | false | If true, returns the form for a deleted boxholder from the archive. | + + + +### mailboxes.set1583(boxNumber, uuid, formps1583) ⇒ Promise +Set the FormPS1583 object for a boxholder by UUID. + +**Kind**: static method of [mailboxes](#mailboxes) + +| Param | Type | Description | +| --- | --- | --- | +| boxNumber | string | Mailbox number. | +| uuid | string | Boxholder UUID. | +| formps1583 | FormPS1583 | The FormPS1583 object to use. | + + + +### mailboxes.boxNumberValid() ⇒ boolean +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. + +**Kind**: static method of [mailboxes](#mailboxes) + + +### mailboxes.getMailboxProducts() ⇒ Promise.<Array> +Get a list of merchandise items that are usable for mailbox renewals. + +**Kind**: static method of [mailboxes](#mailboxes) +**Example** +```js +[{ + id: "", // Unique ID for this entry in the merchandise table + name: "", // Merch item name + category: "", // Merch item category + price: 0.0, // Sale price in dollars + cost: 0.0, // Merchandise cost in dollars (likely not used for mailboxes) + barcode: "", // Barcode/UPC (likely not used for mailboxes) + tax: 0.0, // Sales tax rate + rentaldays: 30, // Number of days this item adds to a mailbox (mutually exclusive with rentalmonths) + rentalmonths: 1, // Number of months (mutually exclusive with rentaldays) + boxsize: "1" // Mailbox size tier, 1-10 +}] +``` diff --git a/docs/Plugin API/pos.md b/docs/Plugin API/pos.md new file mode 100644 index 0000000..3e49c3c --- /dev/null +++ b/docs/Plugin API/pos.md @@ -0,0 +1,353 @@ + + +## pos : object +Point of Sale, transaction, and payment-related functionality. + +**Kind**: global namespace + +* [pos](#pos) : object + * [.ReceiptItem](#pos.ReceiptItem) + * [new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)](#new_pos.ReceiptItem_new) + * [.ReceiptPayment](#pos.ReceiptPayment) + * [new ReceiptPayment(amount, type, text)](#new_pos.ReceiptPayment_new) + * [.addReceiptItem(item)](#pos.addReceiptItem) + * [.addReceiptPayment(payment)](#pos.addReceiptPayment) + * [.addOnscreenPaymentLog(msg)](#pos.addOnscreenPaymentLog) + * [.getReceiptID()](#pos.getReceiptID) ⇒ string + * [.onReceiptChange(f)](#pos.onReceiptChange) + * ~~[.onTransactionFinished(f)](#pos.onTransactionFinished)~~ + * [.registerCardProcessor(f)](#pos.registerCardProcessor) + * [.registerCryptoProcessor(f)](#pos.registerCryptoProcessor) + * [.getShippingSalesTax()](#pos.getShippingSalesTax) ⇒ Object + + + +### pos.ReceiptItem +**Kind**: static class of [pos](#pos) +**Properties** + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| merch | boolean | false | True if merchandise, false if shipping. | +| barcode | string | | Item barcode, or tracking number if `merch = false`. | +| qty | number | 1 | Item quantity. | +| retailPrice | number | | The calculated retail/markup price for a shipment, regardless of actual sale price. If unset, defaults to priceEach * qty. | +| taxRate | number | 0 | Tax rate | +| toAddress | Address | | Shipping destination address. | +| fromAddress | Address | | Shipping return address. | +| carrier | string | | Shipping carrier. | +| service | string | | Shipping service. | +| category | string | | Merchandise/item category. | +| electronicReturnReceipt | boolean | false | If true, the customer's receipt will have instructions on retrieveing the return receipt from USPS. | +| mailboxDays | number | 0 | Number of days this item adds to a mailbox's expiration date. | +| mailboxMonths | number | 0 | Number of months this item adds to a mailbox's expiration date. | +| mailboxNumber | string | | Mailbox number to apply `mailboxDays` or `mailboxMonths` to after checkout. | +| setCertifiedInfo() | function | | Set Certified Mail receipt data. `setCertifiedInfo(trackingNumber, certfee, extrafees, postage, date, location, toaddress)` | +| toJSON() | function | | Get the item as an object suitable for JSON encoding. | +| fromJSON(json) | static\_function | | Returns a ReceiptItem created from the object returned by `item.toJSON()`. | + + + +#### new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount) +A class representing a sale item in the current transaction. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| id | string | | Unique ID number for this item (UPC code, inventory number, etc). Used to deduplicate and merge line items on the receipt. Unique items (like shipping labels) should be a unique/random ID. | +| label | string | | One-line item information. | +| text | string | | Extra multi-line item information. | +| priceEach | number | | Sale price per unit. | +| quantity | number | | Number of units. | +| cost | number | | Cost per unit. Used for automatic expense tracking. | +| taxrate | number | 0.0 | Examples: 0 (for 0%), 0.05 (for 5%), etc | +| taxableAmount | string | | The part of the sale price that's taxable. "" for default (all), "markup" for only taxing profit. | + + + +### pos.ReceiptPayment +**Kind**: static class of [pos](#pos) +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| label | string | (readonly) The human-readable string of the payment type. | +| id | string | Automatically-generated unique ID for this payment. | +| toJSON() | function | Get the payment as an object suitable for JSON encoding. | +| fromJSON(json) | static\_function | Returns a ReceiptPayment created from the object returned by `payment.toJSON()`. | + + + +#### new ReceiptPayment(amount, type, text) +A class representing a payment entry for the current transaction. + + +| Param | Type | Description | +| --- | --- | --- | +| amount | number | amount paid | +| type | string | payment type | +| text | string | extra data (credit card info, etc) | + + + +### pos.addReceiptItem(item) +Add an item (shipment, merchandise, etc) to the current transaction. + +**Kind**: static method of [pos](#pos) + +| Param | Type | +| --- | --- | +| item | ReceiptItem | + + + +### pos.addReceiptPayment(payment) +Add a payment to the current transaction/receipt. + +**Kind**: static method of [pos](#pos) + +| Param | Type | +| --- | --- | +| payment | ReceiptPayment | + + + +### pos.addOnscreenPaymentLog(msg) +Append a line of text to the onscreen log displayed during credit card processing. +Not shown in kiosk mode. + +**Kind**: static method of [pos](#pos) + +| Param | Type | Description | +| --- | --- | --- | +| msg | string | Line of text to add to the log. | + + + +### pos.getReceiptID() ⇒ string +Get the unique alphanumeric ID for the current transaction/receipt. +This is the same code printed on receipts and used in digital receipt URLs. + +**Kind**: static method of [pos](#pos) + + +### pos.onReceiptChange(f) +Specify a function to be called whenever the transaction data/receipt is changed. +It is passed a single argument, a Receipt object containing the entire transaction so far. + +**Kind**: static method of [pos](#pos) + +| Param | Type | +| --- | --- | +| f | function | + + + +### ~~pos.onTransactionFinished(f)~~ +***Deprecated*** + +The supplied function will be called when a transaction is finished. +It is passed a single argument, a Receipt object containing the entire transaction. +Recommended to listen for the `transactionFinished` event instead. + +**Kind**: static method of [pos](#pos) + +| Param | Type | +| --- | --- | +| f | function | + + + +### pos.registerCardProcessor(f) +Register as a card payment processor. + +**Kind**: static method of [pos](#pos) + +| Param | Type | Description | +| --- | --- | --- | +| f | Object | Payment processor functions | + +**Example** +```js +global.apis.pos.registerCardProcessor({ + name: "Demo Card Processor", // Shown in PostalPoint settings menu + init: async function () { + // This will run after PostalPoint launches + // and before any payments are processed. + // In some situations it might run multiple times in a session. + }, + checkout: async function ({amount, capture = true}) { + // Charge a credit card using a card reader device. + // amount is in pennies (or the equivalent base unit in the local currency). + + // Add a payment to the receipt with the total amount paid, card details, etc. + global.apis.pos.addReceiptPayment( + new global.apis.pos.ReceiptPayment( + global.apis.i18n.currencyMinorToMajor(amount), + "card", // Payment type. Accepted values are card, ach, crypto, cash, + // check, account, and free. Other types will be displayed as-is. + "Demo Card\nCardholder Name, etc\nMore info for receipt" // Additional text for receipt + ) + ); + + + // Must return boolean false if the payment failed. + // Otherwise it will be assumed it succeeded. + // If an error is encountered, handle it and return false. + // It's recommended to display a short "payment failed" error + // message via global.apis.alert, and outputting more details + // via global.apis.pos.addOnscreenPaymentLog. + + // If capture is false, perform an authorization but don't capture, + // and return a value you can use to identify the authorization later + // and complete it. The value will be passed back to finishPayment, below. + // This is used mainly for the self-serve kiosk mode, in case the label fails + // to be purchased/generated by the carrier. + }, + cancelCheckout: function () { + // The user has requested the card transaction be canceled before it completes. + // Reset the terminal to its resting state, clear its screen, etc. + }, + finishPayment: async function ({checkoutResponse}) { + // Finish a payment that was authorized but not captured + // because checkout() was called with capture = false. + // If payment was already captured and added + // to the receipt, just return true. + global.apis.pos.addReceiptPayment( + new global.apis.pos.ReceiptPayment( + global.apis.i18n.currencyMinorToMajor(amount), + "card", + "Demo Card\nCardholder Name, etc\nMore info for receipt" + ) + ); + }, + updateCartDisplay: function (receipt) { + // Show transaction data on the card reader display. + // This function is called when the "cart" or total changes. + // `receipt` is a receipt object, see docs for details. + }, + checkoutSavedMethod: async function ({customerID, paymentMethodID, amount}) { + // Same as checkout() except using a payment method already on file. + // customerID and paymentMethodID are provided by getSavedPaymentMethods below. + + // Must return true upon success. + // If the payment is not successful, and you didn't throw an Error to show the user, + // then `return false` instead and it'll appear that the user's action to start the payment did nothing. + return true; + }, + saveCardForOfflineUse: async function ({statusCallback, customerUUID, name, + company, street1, street2, city, state, zip, country, email, phone}) { + // Use the card reader to capture an in-person card and save it for offline use. + // Provided details are the customer's info, which might be empty strings except for the customerUUID. + // Saved card details must be tied to the customerUUID, as that's how saved cards are looked up. + + // statusCallback(string, boolean) updates the progress message on the cashier's screen. + // If the boolean is true, the progress message is replaced with a confirmation message. + statusCallback("Saving card details...", false); + + return true; // Card saved to customer + // If an error occurred, you can throw it and the error + // message will be displayed to the cashier. + // Alternatively, return boolean false and display the error + // yourself with global.apis.alert(message, title) or something. + }, + cancelSaveCardForOfflineUse: function () { + // Cancel the process running in saveCardForOfflineUse() at the user/cashier's request. + }, + getSavedPaymentMethods: async function ({customerUUID}) { + // Return all saved payment methods tied to the provided customer UUID. + return [{ + customer: "", // Passed to checkoutSavedMethod as customerID + customer_uuid: customerUUID, + id: "", // Passed to checkoutSavedMethod as paymentMethodID + type: "card", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free. + label: "Visa debit x1234 (exp. 12/29)", // Label for payment method + label_short: "Visa debit x1234" // Abbreviated label for payment method + }]; + }, + deleteSavedPaymentMethod: async function ({customerUUID, customerID, paymentMethodID}) { + // Delete the payment method identified by paymentMethodID + // and tied to the PostalPoint customerUUID and the card processor customerID. + // If unable to delete, throw an error and the error message + // will be displayed to the cashier. + } +}); +``` + + +### pos.registerCryptoProcessor(f) +Register as a cryptocurrency payment processor. + +**Kind**: static method of [pos](#pos) + +| Param | Type | Description | +| --- | --- | --- | +| f | Object | Payment processor functions | + +**Example** +```js +global.apis.pos.registerCryptoProcessor({ + name: "Demo Crypto", // Shown in PostalPoint settings menu + init: async function () { + // This is run after PostalPoint starts, + // and before any other crypto functions are called. + }, + checkout: async function ({amount}) { + // Run the checkout process. + // amount is the amount of fiat currency to collect, + // in pennies (or the local equivalent). + + // If an error is encountered during processing, + // display an error message in a dialog and return boolean false. + // If this function returns anything except false or undefined, + // and doesn't throw an error, + // it is assumed the payment was successful. + + // Adds a line of text visible to the cashier + global.apis.pos.addOnscreenPaymentLog("Getting crypto payment..."); + + // Display a web page (i.e. with a payment QR code) + // to the customer on the customer-facing display. + global.apis.ui.setCustomerScreen("", "html"); + global.apis.ui.setCustomerScreen("https://postalpoint.app", "raw"); + + // Poll the status of the crypto transaction + var paymentComplete = false; + do { + await global.apis.util.delay(1000); + paymentComplete = true; + } while (paymentComplete != true); + + global.apis.pos.addReceiptPayment( + new global.apis.pos.ReceiptPayment( + global.apis.i18n.currencyMinorToMajor(amount), + "crypto", // Payment type. + "Bitcoin\n0.00001234 BTC" // Additional text for receipt + ) + ); + global.apis.pos.addOnscreenPaymentLog("Payment successful!"); + global.apis.ui.clearCustomerScreen(); + }, + cancelCheckout: function () { + // The user requested to cancel the payment. + // Reset things accordingly. + global.apis.ui.clearCustomerScreen(); + }, + isConfigured: function () { + // Is this plugin properly setup + // and able to process payments? + // If not, return false. + // This determines if the crypto payment method button will be shown. + return true; + } +}); +``` + + +### pos.getShippingSalesTax() ⇒ Object +Get the sales tax percentage to charge on a shipping service ReceiptItem. + +**Kind**: static method of [pos](#pos) +**Returns**: Object - `{type: "", percent: 0.15}` +`type` is an empty string for taxing the entire price, or "markup" for only adding tax to the markup amount. +`percent` is the tax percentage. A value of 0.15 means a 15% tax. diff --git a/docs/Plugin API/print.md b/docs/Plugin API/print.md new file mode 100644 index 0000000..8e54710 --- /dev/null +++ b/docs/Plugin API/print.md @@ -0,0 +1,55 @@ + + +## print : object +Printing to connected printers + +**Kind**: global namespace + +* [print](#print) : object + * [.printLabelImage(image)](#print.printLabelImage) + * [.getReceiptPrinter()](#print.getReceiptPrinter) ⇒ Promise.<Object> + * [.printReceiptData(data)](#print.printReceiptData) + * [.imageToBitmap(jimpImage, [dpiFrom], [dpiTo])](#print.imageToBitmap) ⇒ Object + + + +### 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](#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) + + +### print.printReceiptData(data) +Send raw data (generated by the printer interface) to the receipt printer. + +**Kind**: static method of [print](#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](#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. | + diff --git a/docs/Plugin API/reports.md b/docs/Plugin API/reports.md new file mode 100644 index 0000000..2d0e77d --- /dev/null +++ b/docs/Plugin API/reports.md @@ -0,0 +1,70 @@ + + +## reports : object +Define custom reports for the user. + +**Kind**: global namespace + + +### reports.registerReport(name, onload(startDate,endDate), date) +**Kind**: static method of [reports](#reports) + +| Param | Type | Description | +| --- | --- | --- | +| name | string | Report name | +| onload(startDate,endDate) | function | Called when the report is loaded, with start and end Date objects. See example. | +| date | boolean | If the report requires a date range be selected. | + +**Example** +```js +global.apis.reports.registerReport("sample", function (startDate, endDate) { + + // Note about column datatypes: + // Use "string" for the datatype, except for the special cases listed here. + // Other datatypes may be added in the future, so use "string" + // unless you like unexpected behavior! + // + // datetime: Column is a UNIX timestamp (in seconds). + // It is displayed as a formatted date and time string. + // receiptid: Column is a PostalPoint receipt ID number. Displayed as a link. + // Clicking the ID will fetch and open the receipt in a popup. + // userid: Column contains an employee ID number from the PostalPoint database. + // It is queried in the database and replaced with the employee's name, + // or with an empty string if the ID lookup has no results. + // money: Column is a number that will be formatted as currency for display. + // percent: Column is a percent value (as 12.3, not .123) and will be formatted + // with a trailing % sign and rounded to two decimal places. + + // Single-table report + return { + table: { + header: ["Column 1", "Column 2"], + datatypes: ["string", "string"], + rows: [ + ["Row 1 Col 1", "Row 1 Col 2"], + ["Row 2 Col 1", "Row 2 Col 2"] + ] + } + }; + + // Multiple-table report + return { + multitable: true, + table: { + titles: ["Report 1 Title", "Report 2 Title"], + header: [["Report 1 Column 1", "Report 1 Column 2"], ["Report 2 Column 1", ...]], + datatypes: [["string", "string"], ["string", "string"]], + rows: [ + [ + ["Report 1 Row 1 Col 1", "Report 1 Row 1 Col 2"], + ["Report 1 Row 2 Col 1", "Report 1 Row 2 Col 2"] + ], + [ + ["Report 2 Row 1 Col 1", "Report 2 Row 1 Col 2"], + ["Report 2 Row 2 Col 1", "Report 2 Row 2 Col 2"] + ] + ] + } + } +}, true); +``` diff --git a/docs/Plugin API/settings.md b/docs/Plugin API/settings.md new file mode 100644 index 0000000..e15195b --- /dev/null +++ b/docs/Plugin API/settings.md @@ -0,0 +1,40 @@ + + +## 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](#settings) : object + * [.get(key, defaultValue)](#settings.get) ⇒ \* + * [.set(key, value)](#settings.set) + + + +### settings.get(key, defaultValue) ⇒ \* +Get a setting. + +**Kind**: static method of [settings](#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](#settings) + +| Param | Type | Description | +| --- | --- | --- | +| key | string | Setting key/ID | +| value | string | Value to set. | + diff --git a/docs/Plugin API/shipping.md b/docs/Plugin API/shipping.md new file mode 100644 index 0000000..5c5691d --- /dev/null +++ b/docs/Plugin API/shipping.md @@ -0,0 +1,243 @@ + + +## shipping : object +Add custom carrier and rates, and adjust markup. + +**Kind**: global namespace + +* [shipping](#shipping) : object + * [.Address](#shipping.Address) + * [new Address()](#new_shipping.Address_new) + * [.getZIPCode(zipcode, country)](#shipping.getZIPCode) ⇒ Object + * [.getPackagingByID(id)](#shipping.getPackagingByID) ⇒ Promise.<Object> + * [.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging)](#shipping.getRetailPriceWithMarkup) ⇒ Promise.<number> + * [.getCarrierName(carrierId)](#shipping.getCarrierName) ⇒ string + * [.getServiceName(serviceId, carrier)](#shipping.getServiceName) ⇒ string + * [.registerRateEndpoint(getRates, purchase, idPrefix)](#shipping.registerRateEndpoint) + * [.registerMarkupCalculator(markupFn)](#shipping.registerMarkupCalculator) + + + +### shipping.Address +**Kind**: static class of [shipping](#shipping) + + +#### new Address() +A class representing an address. + + + +### shipping.getZIPCode(zipcode, country) ⇒ Object +Get data for a ZIP Code. + +**Kind**: static method of [shipping](#shipping) +**Returns**: Object - Data about the ZIP code. See example. Fields may be empty if not available. Type may be "STANDARD", "UNIQUE", "PO BOX", or "MILITARY". + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| zipcode | string | | ZIP or postal code. | +| country | string | "US" | Currently only "US" and "CA" are supported. | + +**Example** +```js +{city: "NEW YORK", state: "NY", type: "STANDARD"} +``` + + +### shipping.getPackagingByID(id) ⇒ Promise.<Object> +Get a parcel's packaging type from PostalPoint's internal ID for it. + +**Kind**: static method of [shipping](#shipping) +**Returns**: Promise.<Object> - See examples. + +| Param | Type | +| --- | --- | +| id | number | + +**Example** +```js +{ + id: 100, + type: "Parcel", + img: "box.png", + name: "Box", + service: "", + l: -1, + w: -1, + h: -1, + weight: true, + hazmat: true, + source: "Customer" +} +``` +**Example** +```js +{ + id: 1, + type: "FlatRateEnvelope", + img: "pm-fres.png", + name: "Flat Rate Envelope", + service: "Priority", + l: -2, + w: -2, + h: -2, + weight: false, + hazmat: true, + usps_supplied: true, + envelope: true, + source: "USPS", + skus: ["PS00001000014", "PS00001000012", "PS00001000027", "PS00001000064", "PS00001001921", "PS00001035000", "PS00001036014", "PS00001128600", "https://qr.usps.com/epsspu?p=30", "https://qr.usps.com/epsspu?p=8"] +} +``` +**Example** +```js +{ + id: 201, + type: "UPSLetter", + img: "ups-env.png", + name: "Envelope", + carrier: "UPS", + l: -2, + w: -2, + h: -2, + weight: true, + hazmat: true, + source: "OtherCarrier" +} +``` + + +### shipping.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging) ⇒ Promise.<number> +Calculate the retail price for a shipment rate based on the configured margin settings. + +**Kind**: static method of [shipping](#shipping) +**Returns**: Promise.<number> - The amount to charge the customer + +| Param | Type | Description | +| --- | --- | --- | +| cost | number | Cost of shipment to business | +| retail | number | Default retail price from label provider | +| carrier | string | Shipment carrier | +| service | string | Shipment service | +| weightOz | number | The weight of the shipment in ounces, or null if not available. | +| packaging | string | An empty string if not available, or "Letter", "FlatRateEnvelope", etc. | + + + +### shipping.getCarrierName(carrierId) ⇒ string +Converts the carrier ID string into a consistent and human-readable name. + +**Kind**: static method of [shipping](#shipping) + +| Param | Type | +| --- | --- | +| carrierId | string | + + + +### shipping.getServiceName(serviceId, carrier) ⇒ string +Converts the service ID string into a consistent and human-readable name. Set the carrier ID for better results. + +**Kind**: static method of [shipping](#shipping) + +| Param | Type | Default | +| --- | --- | --- | +| serviceId | string | | +| carrier | string | "USPS" | + + + +### shipping.registerRateEndpoint(getRates, purchase, idPrefix) +Register the plugin as a shipping rate and label provider. See the Shipping example plugin. + +**Kind**: static method of [shipping](#shipping) + +| Param | Type | Description | +| --- | --- | --- | +| getRates | function | A function passed a Parcel object to get rates for. Returns a Promise that resolves to an array of rate objects. | +| purchase | function | A function passed a rate ID to purchase. Returns a Promise that resolves to the label information. | +| idPrefix | string | A unique string that will be prefixing all rate IDs from this plugin. | + +**Example** +```js +// getRates sample return value: +[{ + rateid: `${idPrefix}_${global.apis.util.uuid.v4()}`, + carrier: "CarrierID", + carrierName: "Carrier Name", + service: "CARRIER_SERVICE_ID", + cost_rate: 10, + retail_rate: 15, + delivery_days: 3, + delivery_date: null, + guaranteed: true, + serviceName: "Service Name", + color: "green" // Rate card color +}] +``` +**Example** +```js +// purchase sample return value: +{ + label: labelImageToPrint, + labeltype: "PNG", + receiptItem: ReceiptItem, + tracking: "12345678901234567890", + cost: 10.0, + price: 15.0, + carrier: "Carrier Name", + service: "Service Name", + delivery_days: 3, + delivery_date: 1234567890, // UNIX timestamp + to: toAddressLines // Array of strings +} +``` + + +### shipping.registerMarkupCalculator(markupFn) +Register the plugin to modify PostalPoint's shipping markup calculation during shipment rating. + +**Kind**: static method of [shipping](#shipping) +**Throws**: + +- Error Only one plugin may register with this function; +any subsequent attempts to register will throw an Error. + + +| Param | Type | Description | +| --- | --- | --- | +| markupFn | function | A function that must return either the retail price to charge for this rate, or `false` to opt-out of setting this particular rate. | + +**Example** +```js +global.apis.shipping.registerMarkupCalculator( + // Parameters: + // cost: Cost to shipper + // retail: Carrier-suggested retail price + // suggested: PostalPoint-suggested retail (default margin calc) + // carrier: Shipping carrier name + // service: Shipping service code + // weightOz: The weight of the shipment in ounces, or null if not available. + // packaging: An empty string if not available, or "Letter", "FlatRateEnvelope", etc. See https://docs.easypost.com/docs/parcels#predefined-package + // parcel: The Parcel object for this shipment. May be null for some rate-only requests without a shipment, such as USPS price calculations. + function (cost, retail, suggested, carrier, service, weightOz, packaging, parcel) { + if (carrier == "USPS") { + if (service == "First-Class Mail") { + // Handle First-Class Mail differently if it's a 1oz letter (i.e. Forever stamp) + if (weightOz <= 1 && packaging == "Letter") { + return retail + 0.05; + } else { + return retail + 0.25; + } + } + // Handle flat rate envelopes differently + if (global.apis.shipping.getServiceName(service, carrier) == "Priority Mail" && packaging == "FlatRateEnvelope") { + return retail + 1.0; + } + return suggested + 2.0; // Charge the PostalPoint-calculated amount plus $2 + } else { + return cost * 2; // Charges the customer double the shipment's cost. + } + } +); +``` diff --git a/docs/Plugin API/storage.md b/docs/Plugin API/storage.md new file mode 100644 index 0000000..4000791 --- /dev/null +++ b/docs/Plugin API/storage.md @@ -0,0 +1,87 @@ + + +## storage : object +Get and set data. + +**Kind**: global namespace + +* [storage](#storage) : object + * [.getSmall(key, defaultValue)](#storage.getSmall) ⇒ \* + * [.setSmall(key, value)](#storage.setSmall) + * [.getBig(key, defaultValue)](#storage.getBig) + * [.setBig(key, value)](#storage.setBig) + * [.getDB(key, defaultValue)](#storage.getDB) ⇒ Promise.<\*> + * [.setDB(key, value)](#storage.setDB) ⇒ Promise + + + +### 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](#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](#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](#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](#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](#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](#storage) + +| Param | Type | Description | +| --- | --- | --- | +| key | string | Storage item key/ID | +| value | \* | Value to store. | + diff --git a/docs/Plugin API/ui.md b/docs/Plugin API/ui.md new file mode 100644 index 0000000..3076ee0 --- /dev/null +++ b/docs/Plugin API/ui.md @@ -0,0 +1,291 @@ + + +## ui : object +Interact with and modify the PostalPoint user interface. + +**Kind**: global namespace + +* [ui](#ui) : object + * [.addToolsPage(page, title, id, description, cardTitle, icon, type)](#ui.addToolsPage) + * [.addHomeTab(content, title, icon, id)](#ui.addHomeTab) ⇒ undefined + * [.showProgressSpinner(title, text, subtitle)](#ui.showProgressSpinner) ⇒ undefined + * [.hideProgressSpinner()](#ui.hideProgressSpinner) + * [.openSystemWebBrowser(url)](#ui.openSystemWebBrowser) + * [.openInternalWebBrowser(url)](#ui.openInternalWebBrowser) + * [.clearCustomerScreen()](#ui.clearCustomerScreen) + * [.setCustomerScreen(content, type, displayInCard, cardSize, displayStatusBar)](#ui.setCustomerScreen) + * [.collectSignatureFromCustomerScreen(title, terms, termstype)](#ui.collectSignatureFromCustomerScreen) + * [.cancelSignatureCollection()](#ui.cancelSignatureCollection) + * [.clearSignaturePad()](#ui.clearSignaturePad) + * [.getCustomerDisplayInfo()](#ui.getCustomerDisplayInfo) ⇒ Object + + + +### ui.addToolsPage(page, title, id, description, cardTitle, icon, type) +Add a page to the Tools screen. 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. +[Framework7 Page Component documentation](https://framework7.io/docs/router-component#single-file-component) + +**Kind**: static method of [ui](#ui) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| page | string \| function | | Page content as a Framework7 component page. If `page` is a string ending in `.f7` it is treated as a file path and the page content will be loaded from disk. If `page` is any other string, it is treated as the page content. If `page` is a function, it will be called and must return the page content (unless `type` is set to `"function"`, see examples) | +| title | string | | Page title. | +| id | string | | Page ID. Make it unique, or pass an empty string to be assigned a random ID. | +| description | string | | Description of this tool for its card on the Tools screen. | +| cardTitle | string | | Title of the card for this page on the Tools screen. | +| icon | string | | FontAwesome icon class, for example, "fa-solid fa-globe". FontAwesome Pro solid, regular, light, and duotone icons are available. | +| type | string | "page" | What kind of data is supplied by `page`: "page" or "function". | + +**Example** +```js +// Full plugin that displays an alert when the card is clicked on the Tools page +exports.init = function () { + global.apis.ui.addToolsPage( + displayMessage, + "click me", + "clickmecard", + "Click here to see a message", + "Click This Card", + "fa-solid fa-arrow-pointer", + "function" + ); +} + +function displayMessage() { + global.apis.alert("Card clicked"); +} +``` +**Example** +```js +// Open a dynamically-generated page +function rollDice() { + var randomNumber = Math.round(Math.random() * 6) + 1; + return `
+
+
+
+ + + +
Random Number
+
+
+
+
+

You rolled ${randomNumber}

+
+
+
`; +} +global.apis.ui.addToolsPage( + rollDice, + "Random", + "randomnumbercard", + "Click here for a random number", + "Random Number", + "fa-regular fa-dice", + "page" + ); +``` +**Example** +```js +// Open a page from a file. +// See https://framework7.io/docs/router-component#single-file-component +global.apis.ui.addToolsPage( + global.apis.getPluginFolder("example-plugin") + "/page.f7", + "Page", + "filepage", + "Open page.f7 from the plugin installation folder", + "Open Custom Page", + "fa-regular fa-file", + "page" + ); +``` + + +### ui.addHomeTab(content, title, icon, id) ⇒ undefined +Add a custom tab to the PostalPoint home screen. Works almost the same as addToolsPage. + +**Kind**: static method of [ui](#ui) + +| Param | Type | Description | +| --- | --- | --- | +| content | string \| function | Tab content. It is rendered/processed when the user navigates to the Home screen and clicks the tab; if the user navigates to a different screen and back to Home, it will be re-rendered. If `content` is a string ending in `.f7` it is treated as a file path and the content will be loaded from disk. If `content` is any other string, it is treated as the content. If `content` is a function, it will be called and must return the content. | +| title | string | Tab title. Keep it short; depending on screen size and tab count, you have as little as 150px of space. | +| icon | string | FontAwesome icon displayed above the tab title. | +| id | string | Tab ID. Make it unique, or pass an empty string to be assigned a random ID. If addHomeTab is called with a tab ID that is already registered, it will be overwritten. | + +**Example** +```js +global.apis.ui.addHomeTab("
Hello
", "Hello Tab", "fa-duotone fa-hand-wave", "hellotab"); +``` +**Example** +```js +function renderTab() { + return ""; +} +global.apis.ui.addHomeTab(renderTab, "Hello Template", "fa-duotone fa-file-code", "hellotemplatetab"); +``` + + +### ui.showProgressSpinner(title, text, subtitle) ⇒ undefined +Show a notification with a loading icon. + +**Kind**: static method of [ui](#ui) + +| Param | Type | Description | +| --- | --- | --- | +| title | string | The message to show on the spinner. | +| text | string | Optional. Body text on the spinner. | +| subtitle | string | Optional. Sub-heading under the `title`. | + + + +### ui.hideProgressSpinner() +Close the notification opened by `showProgressSpinner`. + +**Kind**: static method of [ui](#ui) + + +### ui.openSystemWebBrowser(url) +Open the native OS default browser to the URL given. + +**Kind**: static method of [ui](#ui) + +| Param | Type | +| --- | --- | +| url | string | + + + +### ui.openInternalWebBrowser(url) +Open a web browser inside PostalPoint. The browser has forward/back/close buttons. + +**Kind**: static method of [ui](#ui) + +| Param | Type | +| --- | --- | +| url | string | + +**Example** +```js +global.apis.ui.openInternalWebBrowser("https://postalpoint.app"); +global.apis.eventbus.on("browserNavigate", function (newUrl) { + global.apis.alert(`New URL: ${newUrl}`, "Browser Navigated"); + if (newUrl == "https://closeme.com") { + global.apis.eventbus.emit("browserCloseRequest"); + } +}); +``` + + +### ui.clearCustomerScreen() +Clear any custom content on the customer-facing display, defaulting back to blank/receipt/shipping rates, as applicable. + +**Kind**: static method of [ui](#ui) + + +### ui.setCustomerScreen(content, type, displayInCard, cardSize, displayStatusBar) +Render content on the customer-facing display. +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 tag if you need to display one. + +**Kind**: static method of [ui](#ui) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| content | string | | Page content. | +| type | string | "html" | Format of the `content`. One of "html", "pdf", "raw", "body", or "text". | +| displayInCard | boolean | false | Set to true to wrap the content in a card UI. | +| cardSize | Array.<number> | [300,300 | Size of the card UI if displayInCard == true. | +| displayStatusBar | boolean | true | Whether the bar on the bottom of the screen should be visible, containing the store logo and scale weight. | + +**Example** +```js +// How content is converted by PostalPoint before display: +if (type == "html") { + customerScreenContent = `data:text/html;charset=utf-8,${content}`; +} else if (type == "pdf") { + customerScreenContent = `data:application/pdf,${content}`; +} else if (type == "raw") { + global.customerScreenContent = `${content}`; +} else if (type == "body") { + customerScreenContent = `data:text/html;charset=utf-8, + + + +
${content}
`; +} else { + customerScreenContent = `data:text/plain;charset=utf-8,${content}`; +} +``` + + +### ui.collectSignatureFromCustomerScreen(title, terms, termstype) +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,..."} + +**Kind**: static method of [ui](#ui) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| title | string | null | Display a title/header on the customer screen. Currently ignored, but may be used in the future. | +| terms | string \| boolean | false | Set to a string to display terms and conditions or other text content next to the signature pad. | +| termstype | string | "body" | "html", "pdf", "raw", or "body". See setCustomerScreen() | + +**Example** +```js +global.apis.ui.collectSignatureFromCustomerScreen("", "

By signing, you agree to pay us lots of money

", "body"); +global.apis.eventbus.on("customerSignatureCollected", function (sigdata) { + const pngDataURL = sigdata.png; + const svgDataURL = sigdata.svg; +}); +``` + + +### ui.cancelSignatureCollection() +Cancels customer signature collection and returns the customer-facing display to normal operation. + +**Kind**: static method of [ui](#ui) +**Example** +```js +global.apis.ui.cancelSignatureCollection(); +``` + + +### ui.clearSignaturePad() +Erase the signature drawn on the customer-facing display. +Note that the customer is also provided a button to do this. + +**Kind**: static method of [ui](#ui) +**Example** +```js +global.apis.ui.clearSignaturePad(); +``` + + +### ui.getCustomerDisplayInfo() ⇒ Object +Describes if the customer-facing display is currently enabled, +and if it supports customer touch interaction. + +**Kind**: static method of [ui](#ui) +**Returns**: Object - {"enabled": true, "touch": true} +**Example** +```js +var info = global.apis.ui.getCustomerDisplayInfo(); +``` diff --git a/docs/Plugin API/user.md b/docs/Plugin API/user.md new file mode 100644 index 0000000..f7576f0 --- /dev/null +++ b/docs/Plugin API/user.md @@ -0,0 +1,75 @@ + + +## user : object +Access data about employees. + +**Kind**: global namespace + +* [user](#user) : object + * [.User](#user.User) + * [new User(id, name, password, barcode, enabled)](#new_user.User_new) + * [.getUser()](#user.getUser) ⇒ User + * [.getUserID()](#user.getUserID) ⇒ number + * [.getUserByID()](#user.getUserByID) ⇒ Promise.<User> + * [.listUsers([managerMode])](#user.listUsers) ⇒ Promise.<Array.<User>> + + + +### user.User +**Kind**: static class of [user](#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(string) | function | Returns true if the provided password matches the user's password, or if there is no password set. | +| icon(number) | 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) + + +### user.getUserID() ⇒ number +Get the current user's ID number. + +**Kind**: static method of [user](#user) + + +### user.getUserByID() ⇒ Promise.<User> +Look up the User for an ID number. + +**Kind**: static method of [user](#user) + + +### user.listUsers([managerMode]) ⇒ Promise.<Array.<User>> +Get a list of all users in the system. + +**Kind**: static method of [user](#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). | + diff --git a/docs/Plugin API/util.md b/docs/Plugin API/util.md new file mode 100644 index 0000000..3557cea --- /dev/null +++ b/docs/Plugin API/util.md @@ -0,0 +1,399 @@ + + +## util : object +Various utility functions: HTTP, time/date, barcode creation, clipboard, etc. + +**Kind**: global namespace + +* [util](#util) : object + * [.uuid](#util.uuid) : object + * [.v4()](#util.uuid.v4) ⇒ string + * [.short([length])](#util.uuid.short) ⇒ string + * [.http](#util.http) : object + * [.webhook](#util.http.webhook) : object + * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> + * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> + * [.ack(webhookid)](#util.http.webhook.ack) + * [.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds])](#util.http.post) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> + * [.fetch(url, [responseType], [timeoutSeconds])](#util.http.fetch) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> + * [.string](#util.string) : object + * [.split(input, separator, [limit])](#util.string.split) ⇒ Array.<string> + * [.chunk(input, chunksize)](#util.string.chunk) ⇒ Array.<string> + * [.time](#util.time) : object + * [.now()](#util.time.now) ⇒ number + * [.diff(compareto)](#util.time.diff) ⇒ number + * [.strtotime(str)](#util.time.strtotime) ⇒ number + * [.format(format, [timestamp])](#util.time.format) ⇒ string + * [.toDateString(timestamp)](#util.time.toDateString) ⇒ string + * [.toTimeString(timestamp)](#util.time.toTimeString) ⇒ string + * [.clipboard](#util.clipboard) : object + * [.copy(text, [showNotification])](#util.clipboard.copy) ⇒ Promise.<boolean> + * [.barcode](#util.barcode) : object + * [.getBuffer(data, [type], [height], [scale], [includetext])](#util.barcode.getBuffer) ⇒ Promise.<Buffer> + * [.getBase64(data, [type], [height], [scale], [includetext])](#util.barcode.getBase64) ⇒ Promise.<string> + * [.geography](#util.geography) : object + * [.isoToCountryName(iso)](#util.geography.isoToCountryName) ⇒ string + * [.objectEquals(a, b)](#util.objectEquals) ⇒ boolean + * [.delay([ms])](#util.delay) ⇒ Promise + + + +### util.uuid : object +Unique ID generators. + +**Kind**: static namespace of [util](#util) + +* [.uuid](#util.uuid) : object + * [.v4()](#util.uuid.v4) ⇒ string + * [.short([length])](#util.uuid.short) ⇒ string + + + +#### uuid.v4() ⇒ string +Generate a UUID string + +**Kind**: static method of [uuid](#util.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](#util.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](#util) + +* [.http](#util.http) : object + * [.webhook](#util.http.webhook) : object + * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> + * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> + * [.ack(webhookid)](#util.http.webhook.ack) + * [.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds])](#util.http.post) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> + * [.fetch(url, [responseType], [timeoutSeconds])](#util.http.fetch) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> + + + +#### http.webhook : object +Use webhooks via a PostalPoint cloud relay service. + +**Kind**: static namespace of [http](#util.http) + +* [.webhook](#util.http.webhook) : object + * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> + * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> + * [.ack(webhookid)](#util.http.webhook.ack) + + + +##### 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](#util.http.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](#util.http.webhook) +**Returns**: Promise.<Array.<Object>> - Payloads as received by the webhook relay service. + +| Param | Type | Description | +| --- | --- | --- | +| sourcename | string | Unique identifier for the webhook | + +**Example** +```js +[ + { + // 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) +Acknowledge receipt of a webhook payload, deleting it from the relay server. +Webhook payload is only queued for deletion, so polling may still return it for a short time. + +**Kind**: static method of [webhook](#util.http.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](#util.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](#util.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](#util) + +* [.string](#util.string) : object + * [.split(input, separator, [limit])](#util.string.split) ⇒ Array.<string> + * [.chunk(input, chunksize)](#util.string.chunk) ⇒ Array.<string> + + + +#### string.split(input, separator, [limit]) ⇒ Array.<string> +Split a string with a separator regex. + +**Kind**: static method of [string](#util.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](#util.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](#util) + +* [.time](#util.time) : object + * [.now()](#util.time.now) ⇒ number + * [.diff(compareto)](#util.time.diff) ⇒ number + * [.strtotime(str)](#util.time.strtotime) ⇒ number + * [.format(format, [timestamp])](#util.time.format) ⇒ string + * [.toDateString(timestamp)](#util.time.toDateString) ⇒ string + * [.toTimeString(timestamp)](#util.time.toTimeString) ⇒ string + + + +#### time.now() ⇒ number +Get the current UNIX timestamp in seconds. + +**Kind**: static method of [time](#util.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](#util.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](#util.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](https://www.php.net/manual/en/datetime.format.php). + +**Kind**: static method of [time](#util.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](#util.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](#util.time) + +| Param | Type | +| --- | --- | +| timestamp | number | + + + +### util.clipboard : object +OS clipboard + +**Kind**: static namespace of [util](#util) + + +#### clipboard.copy(text, [showNotification]) ⇒ Promise.<boolean> +Copy a string to the system clipboard. + +**Kind**: static method of [clipboard](#util.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](#util) + +* [.barcode](#util.barcode) : object + * [.getBuffer(data, [type], [height], [scale], [includetext])](#util.barcode.getBuffer) ⇒ Promise.<Buffer> + * [.getBase64(data, [type], [height], [scale], [includetext])](#util.barcode.getBase64) ⇒ Promise.<string> + + + +#### 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](#util.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](#util.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](#util) + + +#### geography.isoToCountryName(iso) ⇒ string +Get a human-readable country name from an ISO country code. + +**Kind**: static method of [geography](#util.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](#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](#util) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [ms] | number | 1000 | Number of milliseconds to pause. | + diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 0000000..009183e --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,176 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/styles.css b/docs/assets/styles.css new file mode 100644 index 0000000..f14b6a4 --- /dev/null +++ b/docs/assets/styles.css @@ -0,0 +1,4 @@ + +.md-header__button.md-logo img { + height: 2rem; +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..54c64bd --- /dev/null +++ b/docs/index.md @@ -0,0 +1,68 @@ +# Overview + +PostalPoint® supports JavaScript plugin extensions. Plugins can hook into PostalPoint to add features and integrations. + +## What plugins can do + +* Process card payments and handle saved payment methods +* Process cryptocurrency payments +* Add additional carriers, providing shipping rates and labels +* Print to label and receipt printers, letting PostalPoint handle hardware support and drivers +* Extend support for prepaid label acceptance, prepaid barcode recognition, and carrier dropoff QR codes +* Install pages in the Tools menu, creating new interfaces and features +* Receive transaction receipts for ingestion into third-party accounting or business software +* Display interactive HTML5 content on the customer-facing screen +* Run both Node.JS and browser code. + +## Plugin Package Structure + +A plugin is distributed as a simple ZIP file, containing a folder. The folder then has at least one file, named `plugin.js`. +The `exports.init` function in `plugin.js` is executed when PostalPoint launches, allowing the plugin +to request involvement with various events in PostalPoint. + +PostalPoint installs plugin packages by unzipping their contents into a plugins folder. +Plugins are uninstalled by deleting their folder. + +## PostalPoint Plugin API + +The PostalPoint plugin API is a globally-available object named `global.apis`. +It contains many useful functions for integrating with PostalPoint. +All the APIs listed under the Plugin API section must be prefixed with `global.apis.` in order to work. + +## Minimal Plugin Code + +```javascript title="plugin-name/plugin.js" +exports.init = function () { + global.apis.alert("This message appears when PostalPoint launches.", "Hello!"); +}; +``` + +Yes, the smallest plugin really is just two lines of code, and accessing PostalPoint features +really is that easy. + +## Plugin Metadata File + +While not strictly required, a `package.json` is encouraged, and allows specifying the plugin's +display name, PostalPoint version compatibility, and other metadata. + +Sample: + +```json +{ + "name": "plugin-id-here", + "main": "plugin.js", + "description": "Human-readable description of the plugin", + "version": "1.0.0", + "author": "Your Name", + "license": "Code license name", + "postalpoint": { + "pluginname": "Display Name for Plugin", + "minVersion": "000034", + "maxVersion": "001000" + } +} + +``` + +PostalPoint version codes are MMMnnn where MMM is the major version and nnn is the minor version, zero-padded. +So version 0.35 is "000035", and 1.23 is "001023". diff --git a/jsdoc2md.js b/jsdoc2md.js new file mode 100644 index 0000000..33e2ddb --- /dev/null +++ b/jsdoc2md.js @@ -0,0 +1,43 @@ +import jsdoc2md from 'jsdoc-to-markdown'; +import { promises as fs } from 'node:fs'; +import path from 'path'; + +/* input and output paths */ +const inputFiles = process.argv.slice(2); +const docroot = "./docs/Plugin API"; + +/* get template data */ +const templateData = await jsdoc2md.getTemplateData({ files: inputFiles }); + +/* reduce templateData to an array of class names */ +const namespaces = templateData.filter(i => i.kind === 'namespace'); +const globals = templateData.filter(i => (i.kind === 'constant' || i.kind === 'function') && i.scope === "global"); + +var template, output; + +/* create a documentation file for each class */ +for (const namespace of namespaces) { + //console.log(namespace); + template = `{{#namespace longname="${namespace.longname}"}}{{>docs}}{{/namespace}}`; + console.log(`rendering ${namespace.longname}`); + output = await jsdoc2md.render({ data: templateData, template: template, "example-lang": "js" }); + const isPrimaryFile = namespace.longname == namespace.name; + const folder = namespace.longname.split(".").slice(0, -1).join("/"); + await fs.mkdir(path.resolve(`${docroot}/${folder}`), {recursive: true}); + if (isPrimaryFile) { + await fs.writeFile(path.resolve(`${docroot}/${namespace.name}.md`), output); + } else { + //const folder = namespace.longname.split(".").slice(0, -1).join("/"); + //await fs.mkdir(path.resolve(`${docroot}/${folder}`), {recursive: true}); + //await fs.writeFile(path.resolve(`${docroot}/${folder}/${namespace.name}.md`), output); + } +} + +template = ""; +console.log(`rendering globals`); +for (const glob of globals) { + //console.log(namespace); + template += `{{#globals longname="${glob.longname}"}}{{>docs}}{{/globals}}`; +} +output = await jsdoc2md.render({ data: templateData, template: template, "example-lang": "js" }); +await fs.writeFile(path.resolve(`${docroot}/global functions.md`), output); diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..229992a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,32 @@ +site_name: PostalPoint Plugin Development +theme: + name: material + custom_dir: overrides + palette: + scheme: default + primary: blue + logo: assets/logo.svg + favicon: https://postalpoint.app/images/favicon-voxel.png + features: + - content.code.copy +extra: + homepage: https://postalpoint.app + analytics: + provider: custom + url: analytics.netsyms.net + siteid: 57 +extra_css: + - assets/styles.css +plugins: + - privacy + - search +markdown_extensions: + - def_list + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets: + base_path: 'docs/' + - pymdownx.superfences diff --git a/overrides/partials/integrations/analytics/custom.html b/overrides/partials/integrations/analytics/custom.html new file mode 100644 index 0000000..4091d1a --- /dev/null +++ b/overrides/partials/integrations/analytics/custom.html @@ -0,0 +1,15 @@ + + + diff --git a/publish.sh b/publish.sh new file mode 100755 index 0000000..99664ab --- /dev/null +++ b/publish.sh @@ -0,0 +1,6 @@ +#!/bin/bash + +./build.sh +mkdocs build + +rsync -rv site/ webhost.netsyms.net:/var/www/dev.postalpoint.app/web