1 line
209 KiB
JSON
1 line
209 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Overview","text":"<p>PostalPoint\u00ae supports JavaScript plugin extensions. Plugins can hook into PostalPoint to add features and integrations.</p>"},{"location":"#what-plugins-can-do","title":"What plugins can do","text":"<ul> <li>Process card payments and handle saved payment methods</li> <li>Process cryptocurrency payments</li> <li>Add additional carriers, providing shipping rates and labels</li> <li>Print to label and receipt printers, letting PostalPoint handle hardware support and drivers</li> <li>Extend support for prepaid label acceptance, prepaid barcode recognition, and carrier dropoff QR codes</li> <li>Install pages in the Tools menu, creating new interfaces and features</li> <li>Receive transaction receipts for ingestion into third-party accounting or business software</li> <li>Display interactive HTML5 content on the customer-facing screen</li> <li>Run both Node.JS and browser code.</li> </ul>"},{"location":"#postalpoint-devtools-and-testing-builds","title":"PostalPoint DevTools and Testing Builds","text":"<p>The PostalPoint build server creates installers from the latest prerelease changes. It is not recommended to use these builds for production purposes, but they contain the latest changes to plugin APIs.</p> <p>For Windows developers, you'll want to download a \"postalpoint-retail-sdk_x.xx.exe\" installer, as it contains the Chromium DevTools.</p> <p>To enable DevTools on Linux, simply run <code>sudo apt install nw.js-sdk</code> and restart PostalPoint.</p> <p>To access the DevTools, press F12 or right-click anywhere inside PostalPoint and click Inspect. Depending on various factors, some plugin console output may go to the \"background page\"; right-click and click \"Inspect background page\" to view that console.</p>"},{"location":"#plugin-package-structure","title":"Plugin Package Structure","text":"<p>A plugin is distributed as a simple ZIP file, containing a folder. The folder then has at least one file, named <code>plugin.js</code>. The <code>exports.init</code> function in <code>plugin.js</code> is executed when PostalPoint launches, allowing the plugin to request involvement with various events in PostalPoint.</p> <p>PostalPoint installs plugin packages by unzipping their contents into a plugins folder. Plugins are uninstalled by deleting their folder.</p>"},{"location":"#postalpoint-plugin-api","title":"PostalPoint Plugin API","text":"<p>The PostalPoint plugin API is a globally-available object named <code>global.apis</code>. It contains many useful functions for integrating with PostalPoint. All the APIs listed under the Plugin API section must be prefixed with <code>global.apis.</code> in order to work.</p>"},{"location":"#minimal-plugin-code","title":"Minimal Plugin Code","text":"plugin-name/plugin.js<pre><code>exports.init = function () {\n global.apis.alert(\"This message appears when PostalPoint launches.\", \"Hello!\");\n};\n</code></pre> <p>Yes, the smallest plugin really is just two lines of code, and accessing PostalPoint features really is that easy.</p>"},{"location":"#plugin-metadata-file","title":"Plugin Metadata File","text":"<p>While not strictly required, a <code>package.json</code> is encouraged, and allows specifying the plugin's display name, PostalPoint version compatibility, and other metadata.</p> <p>Sample:</p> <pre><code>{\n \"name\": \"plugin-id-here\",\n \"main\": \"plugin.js\",\n \"description\": \"Human-readable description of the plugin\",\n \"version\": \"1.0.0\",\n \"author\": \"Your Name\",\n \"license\": \"Code license name\",\n \"postalpoint\": {\n \"pluginname\": \"Display Name for Plugin\",\n \"minVersion\": \"000034\",\n \"maxVersion\": \"001000\"\n }\n}\n</code></pre> <p>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\".</p>"},{"location":"Docs/Address/","title":"Address object","text":"<pre><code>export default class Address {\n constructor(uuid = \"\", name = \"\", company = \"\", street1 = \"\", street2 = \"\", zip = \"\", city = \"\", state = \"\", country = \"\", phone = \"\", email = \"\", taxid = \"\") {\n this.uuid = uuid;\n this.name = name;\n this.company = company;\n this.street1 = street1;\n this.street2 = street2;\n this.zip = zip;\n this.city = city;\n this.state = state;\n this.country = country;\n this.phone = phone;\n this.email = email;\n this.taxid = taxid;\n this.residential = null;\n }\n\n static fromObject(address) {\n if (address instanceof Address) {\n return address;\n }\n var a = new Address(address.uuid ?? \"\", address.name, address.company, address.street1,\n address.street2, address.zip, address.city, address.state, address.country,\n address.phone, address.email, address.taxid);\n return a;\n }\n\n toStringArray(expandCountry = false) {\n var citystatezipLine = [this.city, this.state, this.zip].filter(Boolean);\n var country = this.country == defaultCountryCode() ? \"\" : this.country;\n if (expandCountry && country != \"\") {\n country = getCountryNameForISO(country);\n }\n return [this.name, this.company, this.street1, this.street2, `${citystatezipLine.join(\" \")}`, country, (this.taxid ? \"Tax ID \" + this.taxid : \"\")].filter(Boolean);\n }\n\n /**\n * Test if the address provided is the same as this address.\n */\n equals(address, checkUUID = false) {\n if (\n (checkUUID ? this.uuid == address.uuid : true)\n && this.name == address.name\n && this.company == address.company\n && this.street1 == address.street1\n && this.street2 == address.street2\n && this.city == address.city\n && this.state == address.state\n && this.zip == address.zip\n && this.country == address.country\n && this.taxid == address.taxid) {\n return true;\n }\n return false;\n }\n\n /**\n * Test if an address is the same delivery point as this address.\n */\n dpEquals(address) {\n if (\n this.street1 == address.street1\n && this.street2 == address.street2\n && this.city == address.city\n && this.state == address.state\n && this.zip == address.zip\n && this.country == address.country) {\n return true;\n }\n return false;\n }\n}\n</code></pre>"},{"location":"Docs/Carrier_Service/","title":"getCarrierName and getServiceName","text":"<p>This is the source code for <code>global.apis.shipping.getCarrierName</code> and <code>global.apis.shipping.getServiceName</code>.</p>"},{"location":"Docs/Carrier_Service/#getcarriername","title":"getCarrierName","text":"<pre><code>export function getCarrierName(carrier) {\n switch (carrier) {\n case \"USPS\":\n case \"USPSReturns\":\n case \"usps\":\n return \"USPS\";\n case \"UPS\":\n case \"UPSDAP\":\n case \"ups\":\n return \"UPS\";\n case \"FedExDefault\":\n case \"FedExSmartPost\":\n case \"fedex\":\n return \"FedEx\";\n case \"DHLExpress\":\n case \"dhl_express\":\n return \"DHL Express\";\n case \"DhlEcs\":\n return \"DHL eCommerce\";\n case \"SpeedeeAccount\":\n return \"Spee-Dee\";\n case \"globalpost\":\n return \"GlobalPost\";\n case \"AccurateAccount\":\n return \"Accurate Courier Express\";\n case \"ApcAccount\":\n return \"APC\";\n case \"AsendiaUsaAccount\":\n return \"Asendia\";\n case \"BetterTrucksAccount\":\n return \"Better Trucks\";\n case \"BluestreakAccount\":\n return \"Blue Streak\";\n case \"CanadaPostAccount\":\n case \"CanadaPost\":\n return \"Canada Post\";\n case \"GsoAccount\":\n return \"GLS\";\n case \"LsoAccount\":\n return \"LSO\";\n case \"OntracV3Account\":\n return \"OnTrac\";\n case \"USAExportPBA\":\n return \"Asendia\";\n case \"FirstChoiceAccount\":\n return \"1st Choice Delivery\";\n case \"PurolatorAccount\":\n return \"Purolator\";\n case \"CanparAccount\":\n return \"Canpar\";\n case \"MaerskAccount\":\n return \"Maersk\";\n }\n if (carrier.endsWith(\"Account\")) {\n // A lot of EasyPost carriers are the carrier name and the word Account\n return carrier.replace(\"Account\", \"\");\n }\n return carrier;\n}\n</code></pre>"},{"location":"Docs/Carrier_Service/#getservicename","title":"getServiceName","text":"<pre><code>export function getServiceName(serviceId, carrierId = \"USPS\") {\n var carrier = getCarrierName(carrierId);\n switch (serviceId) {\n // Ambiguous\n case \"\":\n // Used internally if no service ID defined by a plugin or whatever\n return \"\";\n case \"Ground\":\n return \"Ground\";\n case \"Express\":\n if (carrier == \"UPS\") {\n return \"Worldwide Express\";\n } else if (carrier == \"USPS\") {\n return \"Priority Mail Express\";\n } else {\n return \"Express\";\n }\n case \"Priority\":\n if (carrier == \"USPS\") {\n return \"Priority Mail\";\n }\n return \"Priority\";\n\n\n // USPS\n case \"First\":\n case \"usps_first_class_mail\":\n case \"First-Class Mail\":\n return \"First-Class Mail\";\n case \"FirstClassMailInternational\":\n case \"usps_first_class_mail_international\":\n case \"First-Class Mail International\":\n return \"First-Class Mail International\";\n case \"GroundAdvantage\":\n case \"usps_ground_advantage\":\n case \"Ground Advantage\":\n return \"Ground Advantage\";\n case \"MediaMail\":\n case \"usps_media_mail\":\n case \"Media Mail\":\n return \"Media Mail\";\n case \"LibraryMail\":\n case \"usps_library_mail\":\n case \"Library Mail\":\n return \"Library Mail\";\n case \"usps_priority_mail\":\n case \"Priority Mail\":\n return \"Priority Mail\";\n case \"PriorityMailInternational\":\n case \"usps_priority_mail_international\":\n case \"Priority Mail International\":\n return \"Priority Mail International\";\n case \"usps_priority_mail_express\":\n case \"Priority Mail Express\":\n return \"Priority Mail Express\";\n case \"ExpressMailInternational\":\n case \"usps_priority_mail_express_international\":\n case \"Priority Mail Express International\":\n return \"Priority Mail Express International\";\n case \"FirstClassPackageInternationalService\":\n case \"First-Class Pkg International\":\n return \"First-Class Pkg International\";\n\n\n // UPS\n case \"UPSWorldwideExpress\":\n case \"ups_worldwide_express\":\n return \"Worldwide Express\";\n case \"ExpressPlus\":\n case \"UPSExpressPlus\":\n case \"ups_worldwide_express_plus\":\n return \"Worldwide Express Plus\";\n case \"Expedited\":\n case \"UPSWorldwideExpedited\":\n case \"ups_worldwide_expedited\":\n return \"Worldwide Expedited\";\n case \"UPSWorldwideEconomyDDU\":\n return \"Worldwide Economy DDU\";\n case \"NextDayAir\":\n case \"ups_next_day_air\":\n return \"Next Day Air\";\n case \"NextDayAirSaver\":\n case \"ups_next_day_air_saver\":\n return \"Next Day Air Saver\";\n case \"NextDayAirEarlyAM\":\n case \"ups_next_day_air_early\":\n return \"Next Day Air A.M.\";\n case \"2ndDayAir\":\n case \"ups_2nd_day_air\":\n return \"2nd Day Air\";\n case \"2ndDayAirAM\":\n case \"ups_2nd_day_air_am\":\n return \"2nd Day Air A.M.\";\n case \"3DaySelect\":\n case \"ups_3_day_select\":\n return \"3-Day Select\";\n case \"ups_ground\":\n return \"Ground\";\n case \"UPSGroundsaverGreaterThan1lb\":\n return \"Ground Saver\";\n case \"UPSStandard\":\n case \"ups_standard\":\n return \"Standard\";\n case \"UPSSaver\":\n case \"ups_worldwide_saver\":\n return \"Worldwide Saver\";\n\n\n // FedEx\n case \"FEDEX_GROUND\":\n case \"fedex_ground\":\n return \"Ground\";\n case \"FEDEX_2_DAY\":\n case \"fedex_2day\":\n return \"2 Day\";\n case \"FEDEX_2_DAY_AM\":\n case \"fedex_2day_am\":\n return \"2 Day AM\";\n case \"FEDEX_EXPRESS_SAVER\":\n case \"fedex_express_saver\":\n return \"Express Saver\";\n case \"STANDARD_OVERNIGHT\":\n case \"fedex_standard_overnight\":\n return \"Standard Overnight\";\n case \"FIRST_OVERNIGHT\":\n case \"fedex_first_overnight\":\n return \"First Overnight\";\n case \"PRIORITY_OVERNIGHT\":\n case \"fedex_priority_overnight\":\n return \"Priority Overnight\";\n case \"INTERNATIONAL_ECONOMY\":\n case \"fedex_international_economy\":\n return \"International Economy\";\n case \"INTERNATIONAL_FIRST\":\n case \"fedex_international_first\":\n return \"International First\";\n case \"FEDEX_INTERNATIONAL_PRIORITY\":\n case \"INTERNATIONAL_PRIORITY\":\n case \"fedex_international_priority\":\n return \"International Priority\";\n case \"FEDEX_INTERNATIONAL_PRIORITY_EXPRESS\":\n case \"INTERNATIONAL_PRIORITY_EXPRESS\":\n return \"International Priority Express\";\n case \"FEDEX_INTERNATIONAL_CONNECT_PLUS\":\n case \"INTERNATIONAL_CONNECT_PLUS\":\n return \"International Connect Plus\";\n case \"GROUND_HOME_DELIVERY\":\n case \"fedex_home_delivery\":\n return \"Ground Home Delivery\";\n case \"SMART_POST\":\n return \"Ground Economy\";\n case \"FEDEX_FIRST_FREIGHT\":\n return \"First Overnight Freight\";\n case \"FEDEX_1_DAY_FREIGHT\":\n return \"1-Day Freight\";\n case \"FEDEX_2_DAY_FREIGHT\":\n return \"2-Day Freight\";\n case \"FEDEX_3_DAY_FREIGHT\":\n return \"3-Day Freight\";\n case \"INTERNATIONAL_PRIORITY_FREIGHT\":\n return \"International Priority Freight\";\n case \"INTERNATIONAL_ECONOMY_FREIGHT\":\n return \"International Economy Freight\";\n\n\n // USPS Returns\n case \"GroundAdvantageReturn\":\n return \"Ground Advantage Return\";\n case \"PriorityMailReturn\":\n return \"Priority Mail Return\";\n case \"PriorityMailExpressReturn\":\n return \"Priority Mail Express Return\";\n\n\n // DHL Express\n case \"DomesticEconomySelect\":\n return \"Domestic Economy Select\";\n case \"DomesticExpress\":\n return \"Domestic Express\";\n case \"DomesticExpress1030\":\n return \"Domestic Express 10:30\";\n case \"DomesticExpress1200\":\n return \"Domestic Express 12:00\";\n case \"EconomySelect\":\n return \"Economy Select Document\";\n case \"EconomySelectNonDoc\":\n return \"Economy Select Non-Document\";\n case \"EuroPack\":\n return \"EuroPack Document\";\n case \"EuropackNonDoc\":\n return \"EuroPack Non-Document\";\n case \"Express1030\":\n return \"10:30 Document\";\n case \"Express1030NonDoc\":\n return \"10:30 Non-Document\";\n case \"Express1200NonDoc\":\n return \"12:00 Non-Document\";\n case \"Express1200\":\n return \"12:00 Document\";\n case \"Express900\":\n return \"9:00 Document\";\n case \"Express900NonDoc\":\n return \"9:00 Non-Doc\";\n case \"ExpressEasy\":\n return \"Easy Document\";\n case \"ExpressEasyNonDoc\":\n return \"Easy Non-Document\";\n case \"ExpressEnvelope\":\n return \"Envelope\";\n case \"ExpressWorldwide\":\n case \"dhl_express_worldwide\":\n return \"Worldwide Document\";\n case \"ExpressWorldwideB2C\":\n return \"Worldwide B2C\";\n case \"ExpressWorldwideB2CNonDoc\":\n return \"Worldwide B2C Non-Document\";\n case \"ExpressWorldwideECX\":\n return \"Worldwide ECX\";\n case \"ExpressWorldwideNonDoc\":\n return \"Worldwide Non-Document\";\n\n\n // DHL eCommerce\n case \"DHLParcelExpedited\":\n return \"Parcel Expedited\";\n case \"DHLParcelExpeditedMax\":\n return \"Parcel Expedited Max\";\n case \"DHLParcelGround\":\n return \"Parcel Ground\";\n case \"DHLBPMExpedited\":\n return \"PM Expedited\";\n case \"DHLBPMGround\":\n return \"PM Ground\";\n case \"DHLParcelInternationalDirect\":\n return \"Parcel International Direct\";\n case \"DHLParcelInternationalStandard\":\n return \"Parcel International Standard\";\n case \"DHLParcelInternationalDirectSMB\":\n return \"Parcel International Direct\";\n case \"DHLParcelInternationalStandardSMB\":\n return \"Parcel International Standard\";\n case \"DHLPacketInternational\":\n return \"Packet International\";\n case \"DHLParcelInternationalDirectPriority\":\n return \"Parcel International Direct Priority\";\n case \"DHLParcelInternationalDirectStandard\":\n return \"Parcel International Direct Standard\";\n\n // Asendia USA Export\n case \"USAExportStandard\":\n return \"USA Export Standard\";\n case \"USAExportPlus\":\n return \"USA Export Plus\";\n case \"USAExportSelect\":\n return \"USA Export Select\";\n\n // Spee-Dee\n case \"SpeeDeeDelivery\":\n return \"Delivery\";\n\n // GlobalPost\n case \"globalpost_standard_international\":\n return \"Standard International\";\n case \"globalpost_economy_international\":\n return \"Economy International\";\n case \"globalpost_plus\":\n return \"Plus\";\n case \"globalpost_first_class_international\":\n return \"First-Class International\";\n\n // Canada Post\n case \"RegularParcel\":\n return \"Regular Parcel\";\n case \"ExpeditedParcel\":\n return \"Expedited Parcel\";\n case \"Xpresspost\":\n return \"Xpresspost\";\n case \"ExpeditedParcelUSA\":\n return \"Expedited Parcel USA\";\n case \"SmallPacketUSAAir\":\n return \"Small Packet USA Air\";\n case \"TrackedPacketUSA\":\n return \"Tracked Packet USA\";\n case \"TrackedPacketUSALVM\":\n return \"Tracked Packet USA LVM\";\n case \"XpresspostUSA\":\n return \"Xpresspost USA\";\n case \"XpresspostInternational\":\n return \"Xpresspost Int'l\";\n case \"InternationalParcelAir\":\n return \"Int'l Parcel Air\";\n case \"InternationalParcelSurface\":\n return \"Int'l Parcel Surface\";\n case \"SmallPacketInternationalAir\":\n return \"Small Packet Int'l Air\";\n case \"SmallPacketInternationalSurface\":\n return \"Small Packet Int'l Surface\";\n case \"TrackedPacketInternational\":\n return \"Tracked Packet Int'l\";\n case \"ExpeditedParcelPlus\":\n return \"Expedited Parcel Plus\";\n\n\n // GLS US\n case \"EarlyPriorityOvernight\":\n return \"Early Priority Overnight\";\n case \"PriorityOvernight\":\n return \"Priority Overnight\";\n case \"CaliforniaParcelService\":\n return \"California Parcel\";\n case \"SaturdayDeliveryService\":\n return \"Saturday Delivery\";\n case \"EarlySaturdayService\":\n return \"Early Saturday\";\n case \"NoonPriorityService\":\n return \"Noon Priority\";\n\n // OnTrac\n case \"GRND\":\n return \"Ground\";\n\n // LSO\n case \"PriorityEarly\":\n return \"Priority Early\";\n case \"PriorityBasic\":\n return \"Priority Basic\";\n case \"Priority2ndDay\":\n return \"Priority 2nd Day\";\n case \"GroundEarly\":\n return \"Ground Early\";\n case \"GroundBasic\":\n return \"Ground Basic\";\n case \"ECommerce\":\n return \"ECommerce\";\n\n // Canpar\n case \"USA\":\n return \"USA\";\n case \"SelectLetter\":\n return \"Select Letter\";\n case \"SelectPak\":\n return \"Select Pak\";\n case \"Select\":\n return \"Select\";\n case \"OvernightLetter\":\n return \"Overnight Letter\";\n case \"Overnight\":\n return \"Overnight\";\n case \"USALetter\":\n return \"USA Letter\";\n case \"USAPak\":\n return \"USA Pak\";\n case \"SelectUSA\":\n return \"Select USA\";\n case \"International\":\n return \"International\";\n\n // Purolator\n case \"PurolatorExpress\":\n return \"Express\";\n case \"PurolatorExpress12PM\":\n return \"Express 12PM\";\n case \"PurolatorExpressPack12PM\":\n return \"Express Pack 12PM\";\n case \"PurolatorExpressBox12PM\":\n return \"Express Box 12PM\";\n case \"PurolatorExpressEnvelope12PM\":\n return \"Express Envelope 12PM\";\n case \"PurolatorExpress1030AM\":\n return \"Express 10:30AM\";\n case \"PurolatorExpress9AM\":\n return \"Express 9AM\";\n case \"PurolatorExpressBox\":\n return \"Express Box\";\n case \"PurolatorExpressBox1030AM\":\n return \"Express Box 10:30AM\";\n case \"PurolatorExpressBox9AM\":\n return \"Express Box 9AM\";\n case \"PurolatorExpressBoxEvening\":\n return \"Express Box Evening\";\n case \"PurolatorExpressBoxInternational\":\n return \"Express Box International\";\n case \"PurolatorExpressBoxUS\":\n return \"Express Box US\";\n case \"PurolatorExpressEnvelope\":\n return \"Express Envelope\";\n case \"PurolatorExpressEnvelope1030AM\":\n return \"Express Envelope 10:30AM\";\n case \"PurolatorExpressEnvelope9AM\":\n return \"Express Envelope 9AM\";\n case \"PurolatorExpressEnvelopeEvening\":\n return \"Express Envelope Evening\";\n case \"PurolatorExpressEnvelopeInternational\":\n return \"Express Envelope International\";\n case \"PurolatorExpressEnvelopeUS\":\n return \"Express Envelope US\";\n case \"PurolatorExpressEvening\":\n return \"Express Evening\";\n case \"PurolatorExpressInternational\":\n return \"Express International\";\n case \"PurolatorExpressInternational1030AM\":\n return \"Express International 10:30AM\";\n case \"PurolatorExpressInternational1200\":\n return \"Express International 12:00\";\n case \"PurolatorExpressInternational9AM\":\n return \"Express International 9AM\";\n case \"PurolatorExpressBoxInternational1030AM\":\n return \"Express Box International 10:30AM\";\n case \"PurolatorExpressBoxInternational1200\":\n return \"Express Box International 12:00\";\n case \"PurolatorExpressBoxInternational9AM\":\n return \"Express Box International 9AM\";\n case \"PurolatorExpressEnvelopeInternational1030AM\":\n return \"Express Envelope International 10:30AM\";\n case \"PurolatorExpressEnvelopeInternational1200\":\n return \"Express Envelope International 12:00\";\n case \"PurolatorExpressEnvelopeInternational9AM\":\n return \"Express Envelope International 9AM\";\n case \"PurolatorExpressPackInternational1030AM\":\n return \"Express Pack International 10:30AM\";\n case \"PurolatorExpressPackInternational1200\":\n return \"Express Pack International 12:00\";\n case \"PurolatorExpressPackInternational9AM\":\n return \"Express Pack International 9AM\";\n case \"PurolatorExpressPack\":\n return \"Express Pack\";\n case \"PurolatorExpressPack1030AM\":\n return \"Express Pack 10:30AM\";\n case \"PurolatorExpressPack9AM\":\n return \"Express Pack 9AM\";\n case \"PurolatorExpressPackEvening\":\n return \"Express Pack Evening\";\n case \"PurolatorExpressPackInternational\":\n return \"Express Pack International\";\n case \"PurolatorExpressPackUS\":\n return \"Express Pack US\";\n case \"PurolatorExpressUS\":\n return \"Express US\";\n case \"PurolatorExpressUS1030AM\":\n return \"Express US 10:30AM\";\n case \"PurolatorExpressUS1200\":\n return \"Express US 12:00\";\n case \"PurolatorExpressUS9AM\":\n return \"Express US 9AM\";\n case \"PurolatorExpressBoxUS1030AM\":\n return \"Express Box US 10:30AM\";\n case \"PurolatorExpressBoxUS1200\":\n return \"Express Box US 12:00\";\n case \"PurolatorExpressBoxUS9AM\":\n return \"Express Box US 9AM\";\n case \"PurolatorExpressEnvelopeUS1030AM\":\n return \"Express Envelope US 10:30AM\";\n case \"PurolatorExpressEnvelopeUS1200\":\n return \"Express Envelope US 12:00\";\n case \"PurolatorExpressEnvelopeUS9AM\":\n return \"Express Envelope US 9AM\";\n case \"PurolatorExpressPackUS1030AM\":\n return \"Express Pack US 10:30AM\";\n case \"PurolatorExpressPackUS1200\":\n return \"Express Pack US 12:00\";\n case \"PurolatorExpressPackUS9AM\":\n return \"Express Pack US 9AM\";\n case \"PurolatorGround\":\n return \"Ground\";\n case \"PurolatorGround1030AM\":\n return \"Ground 10:30AM\";\n case \"PurolatorGround9AM\":\n return \"Ground 9AM\";\n case \"PurolatorGround12PM\":\n return \"Ground 12PM\";\n case \"PurolatorGroundDistribution\":\n return \"Ground Distribution\";\n case \"PurolatorGroundEvening\":\n return \"Ground Evening\";\n case \"PurolatorGroundUS\":\n return \"Ground US\";\n case \"PurolatorQuickShip\":\n return \"QuickShip\";\n case \"PurolatorQuickShipEnvelope\":\n return \"QuickShip Envelope\";\n case \"PurolatorQuickShipPack\":\n return \"QuickShip Pack\";\n case \"PurolatorQuickShipBox\":\n return \"QuickShip Box\";\n\n\n // Maersk Parcel\n case \"Maersk-3-Day\":\n return \"3 Day\";\n\n }\n\n console.warn(\"Unknown shipping service ID: \", serviceId, \"Carrier ID:\", carrierId);\n\n // Snipped: code that attempts to format the service ID nicely based on common naming patterns found in the wild.\n\n return serviceName;\n}\n</code></pre>"},{"location":"Docs/Database/","title":"Database Drivers","text":"<p><code>global.apis.database.getConnection()</code> returns one of these, depending on which database is in use.</p>"},{"location":"Docs/Database/#sqlite","title":"SQLite","text":"<pre><code>export class SQLiteAdapter {\n constructor(db) {\n this.type = \"sqlite\";\n this.db = db;\n }\n\n async query(query, replace) {\n if (global.devMode) {\n console.info(query, replace);\n }\n return await this.db.all(query, replace);\n }\n\n async run(statement, replace) {\n if (global.devMode) {\n console.info(statement, replace);\n }\n return await this.db.run(statement, replace);\n }\n\n async exec(statement) {\n if (global.devMode) {\n console.info(statement);\n }\n return await this.db.exec(statement);\n }\n\n async exists(table, where, replace) {\n const q = await this.db.all(\"SELECT EXISTS(SELECT 1 FROM \" + table + \" WHERE \" + where + \") as n\", replace);\n if (q[0].n > 0) {\n return true;\n }\n return false;\n }\n\n async close() {\n\n }\n\n async tableExists(table) {\n return (await this.db.get(`SELECT count(name) AS cnt FROM sqlite_master WHERE type='table' AND name=?`, table)).cnt > 0;\n }\n\n /**\n * Get the version code set in the database by setSchemaVersion().\n */\n async getSchemaVersion() {\n var res = await this.db.all(`PRAGMA user_version`);\n return res[0].user_version;\n }\n\n /**\n * Set the database version, using PRAGMA user_version. Must be an integer.\n */\n async setSchemaVersion(version) {\n await this.db.exec(`PRAGMA user_version = ${version}`);\n }\n\n}\n</code></pre>"},{"location":"Docs/Database/#remote-hostmaster","title":"Remote host/master","text":"<pre><code>export class RemoteDatabaseAdapter {\n constructor() {\n this.type = \"remote\";\n }\n\n async apirequest(args) {\n var resp = await sendToPostalPointHTTPServer(args, \"database\");\n if (typeof resp.status == \"string\" && resp.status == \"OK\") {\n return resp.result;\n } else if (typeof resp.status == \"string\" && resp.status == \"ERR\") {\n if (typeof resp.message == \"string\") {\n throw new Error(resp.message);\n } else {\n throw new Error(resp);\n }\n } else {\n throw new Error(resp);\n }\n }\n\n async query(query, replace = []) {\n return await this.apirequest({type: \"query\", query: query, replace: replace});\n }\n\n async run(statement, replace = []) {\n return await this.apirequest({type: \"run\", query: statement, replace: replace});\n }\n\n async exec(statement) {\n return await this.apirequest({type: \"exec\", query: statement});\n }\n\n async exists(table, where, replace = []) {\n return await this.apirequest({type: \"exists\", table: table, where: where, replace: replace});\n }\n\n async close() {\n // NOOP: We don't care about this\n }\n\n async tableExists(table) {\n return await this.apirequest({type: \"tableExists\", table: table});\n }\n\n async getSchemaVersion() {\n return await this.apirequest({type: \"getSchemaVersion\"});\n }\n\n async setSchemaVersion(version) {\n // NOOP: Don't upgrade server's installation, it can do that itself\n }\n}\n</code></pre>"},{"location":"Docs/Database/#mariadbmysql","title":"MariaDB/MySQL","text":"<pre><code>export class MariaDBAdapter {\n constructor(connection) {\n this.type = \"mariadb\";\n this.conn = connection;\n }\n\n async query(query, replace) {\n if (global.devMode) {\n console.info(query, replace);\n }\n return await this.conn.query(query, replace);\n }\n\n async run(statement, replace) {\n if (global.devMode) {\n console.info(statement, replace);\n }\n return await this.query(statement, replace);\n }\n\n async exec(statement) {\n if (global.devMode) {\n console.info(statement);\n }\n return await this.run(statement);\n }\n\n async exists(table, where, replace) {\n const q = await this.query(\"SELECT EXISTS(SELECT 1 FROM \" + table + \" WHERE \" + where + \") as n\", replace);\n if (q[0].n > 0) {\n return true;\n }\n return false;\n }\n\n async close() {\n await this.conn.release();\n }\n\n async tableExists(table) {\n return (await this.query(\"SHOW TABLES LIKE ?\", table)).length > 0;\n }\n\n /**\n * Get the version code set in the database by setSchemaVersion(). Returns zero if not set.\n */\n async getSchemaVersion() {\n if (await this.tableExists(\"database_metadata\")) {\n var res = await this.query(\"SELECT `value` FROM database_metadata WHERE `key`='schema_version' LIMIT 1\");\n console.log(res);\n console.log(res[0].value);\n if (res.length == 1) {\n return res[0].value;\n }\n }\n return 0;\n }\n\n /**\n * Set a version number for the database schema.\n * Must be an integer to maintain code compatibility with SQLite driver.\n * Will create a \"database_metadata\" table if required to store the version number.\n */\n async setSchemaVersion(version) {\n if (await this.tableExists(\"database_metadata\")) {\n await this.query(\"REPLACE INTO `database_metadata` (`key`, `value`) VALUES (?, ?)\", [\"schema_version\", version]);\n } else {\n await this.exec(\"CREATE TABLE IF NOT EXISTS `database_metadata` ( `key` VARCHAR(50) NOT NULL, `value` VARCHAR(255) NOT NULL DEFAULT '', PRIMARY KEY (`key`))\");\n await this.setSchemaVersion(version);\n }\n }\n}\n</code></pre>"},{"location":"Docs/Events/","title":"Event Bus","text":"<p>Plugins can use <code>global.apis.eventbus</code> to receive events when certain actions happen in PostalPoint.</p>"},{"location":"Docs/Events/#event-list","title":"Event List","text":"<ul> <li><code>barcodeScanned</code>: Contents of a barcode that was just scanned, as a string. String also contains any non-printing characters in the barcode.</li> <li><code>browserCloseRequest</code>: The embedded web browser listens for this event, and closes itself when received.</li> <li><code>browserNavigate</code>: Contains the URL the embedded web browser just navigated to.</li> <li><code>sendToCustomerScreen</code>: Emit to send data via <code>window.postMessage</code> to a custom HTML interface on the customer-facing display.</li> <li><code>receiveFromCustomerScreen</code>: Contains the event sent from the customer-facing display's custom HTML interface via <code>window.parent.postMessage</code></li> <li><code>transactionFinished</code>: Contains a receipt object of a transaction that was just finalized. See below for event data details.</li> <li><code>customerSignatureCollected</code>: Contains a signature image from the customer-facing display. See below for event data details.</li> <li><code>settingsSaved</code>: Emitted when PostalPoint's settings are saved. Usually this means the user changed a setting in the UI.</li> <li><code>pluginSettingsSaved</code>: Emitted when the user saves a plugin's settings. The plugin ID string is sent as the event data.</li> <li><code>packageCheckIn</code>: Emitted when a package is checked in to a mailbox or for Hold At Location. See below for event data details.</li> <li><code>mailboxMailDelivered</code>: Emitted when mail delivery notifications are sent by the user. Data is an array of the mailbox numbers notifications are being sent for.</li> </ul>"},{"location":"Docs/Events/#example-code","title":"Example Code","text":"<pre><code>// Handle a barcode scan.\n// Remember that PostalPoint will probably also be doing something in response to the barcode.\nglobal.apis.eventbus.on(\"barcodeScanned\", function (barcodedata) {\n // do something with the barcode\n});\n\n// Close the embedded web browser, returning the user to whatever was onscreen before it opened\nglobal.apis.eventbus.emit(\"browserCloseRequest\");\n</code></pre>"},{"location":"Docs/Events/#event-data-objects","title":"Event Data Objects","text":"<p>For events that return an object instead of a single value.</p>"},{"location":"Docs/Events/#transactionfinished","title":"transactionFinished","text":"<p>See Receipt</p>"},{"location":"Docs/Events/#customersignaturecollected","title":"customerSignatureCollected","text":"<pre><code>{\n \"svg\": \"data:image/svg+xml;base64,...\",\n \"png\": \"data:image/png;base64,...\"\n}\n</code></pre>"},{"location":"Docs/Events/#packagecheckin","title":"packageCheckIn","text":"<pre><code>{\n tag: \"abcxyz123456\", // Unique ID for the package, also found in the shelf label barcode.\n tracking: \"94001...\", // Package tracking number. May be an empty string for items without tracking.\n carrier: \"FedEx\", // Package carrier name, if detectable from the tracking number. Otherwise an empty string.\n mailbox: \"123\", // Mailbox number. Will be \"HAL\" for Hold At Location packages.\n isHAL: false, // True if package is for Hold At Location.\n recipient: \"\", // Hold At Location recipient name, or empty string if not HAL.\n toLocker: \"5\", // Parcel locker number, or false if not going to a parcel locker.\n 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.\n}\n</code></pre>"},{"location":"Docs/FormPS1583/","title":"FormPS1583 object","text":"<pre><code>export class FormPS1583 {\n constructor() {\n this.formRevision = LATEST_FORM_REVISION; // Currently \"June2024\"\n this.pmbOpenedDate = new Date();\n this.pmbClosedDate = null;\n this.cmraStreetAddress = getSetting(\"origin_street1\");\n this.pmbNumber = \"\";\n this.cmraZIP = getSetting(\"origin_zip\");\n var cmraZIPData = getZIP(this.cmraZIP);\n if (cmraZIPData) {\n this.cmraCity = cmraZIPData.city;\n this.cmraState = cmraZIPData.state;\n } else {\n this.cmraCity = getSetting(\"origin_city\", \"\");\n this.cmraState = getSetting(\"origin_state\", \"\");\n }\n this.serviceTypeBusiness = false; // true for business PMB, false for residential\n this.applicant = {\n firstName: \"\",\n lastName: \"\",\n middleName: \"\",\n phone: \"\",\n email: \"\",\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n courtProtected: false,\n photoID: {\n name: \"\",\n number: \"\",\n issuer: \"\",\n expirationDate: null,\n type: null // \"DL/ID\", \"UniformedService\", \"USAccess\", \"USUni\",\n // \"Passport\", \"Matricula\", \"NEXUS\",\n // \"CertOfNaturalization\", \"USPermResident\"\n },\n addressID: {\n name: \"\",\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n type: null, // \"DL/ID\", \"Lease\", \"Mortgage\", \"Insurance\", \"VehicleReg\", \"Voter\"\n expirationDate: null // Optional currently but must be kept current - Oct 2025\n }\n };\n this.authorizedIndividual = {\n firstName: \"\",\n lastName: \"\",\n middleName: \"\",\n phone: \"\",\n email: \"\",\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n photoID: {\n name: \"\",\n number: \"\",\n issuer: \"\",\n expirationDate: null,\n type: null // \"DL/ID\", \"UniformedService\", \"USAccess\", \"USUni\",\n // \"Passport\", \"Matricula\", \"NEXUS\",\n // \"CertOfNaturalization\", \"USPermResident\"\n },\n addressID: {\n name: \"\",\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n type: null, // \"DL/ID\", \"Lease\", \"Mortgage\", \"Insurance\", \"VehicleReg\", \"Voter\"\n expirationDate: null // Optional currently but must be kept current - Oct 2025\n }\n };\n this.mailTransferredTo = {\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n phone: \"\",\n email: \"\"\n };\n this.business = {\n name: \"\",\n type: \"\",\n streetAddress: \"\",\n city: \"\",\n state: \"\",\n zip: \"\",\n country: \"\",\n phone: \"\",\n placeOfRegistration: \"\"\n };\n this.additionalRecipients = []; // Array of strings containing names\n this.applicantSignature = \"\"; // PNG image data URI\n this.applicantSignatureDate = null;\n this.cmraSignature = \"\"; // PNG image data URI\n this.cmraSignatureDate = null;\n this.hasForwardingAddress = false;\n }\n\n getTermsAndConditions() {\n return DEFAULT_TERMS_CONDITIONS[this.formRevision];\n }\n\n getApplicantForwardingAddress() {\n if (this.mailTransferredTo.streetAddress != \"\") {\n return new Address(null,\n [this.applicant.firstName, this.applicant.lastName].filter(Boolean).join(\" \"),\n this.business.name ?? \"\",\n this.mailTransferredTo.streetAddress,\n \"\",\n this.mailTransferredTo.zip,\n this.mailTransferredTo.city,\n this.mailTransferredTo.state,\n this.mailTransferredTo.country ?? \"US\",\n this.mailTransferredTo.phone ?? \"\",\n this.mailTransferredTo.email ?? \"\"\n );\n }\n return new Address(null,\n [this.applicant.firstName, this.applicant.lastName].filter(Boolean).join(\" \"),\n this.business.name ?? \"\",\n this.applicant.streetAddress,\n \"\",\n this.applicant.zip,\n this.applicant.city,\n this.applicant.state,\n this.applicant.country ?? \"US\",\n this.applicant.phone ?? \"\",\n this.applicant.email ?? \"\"\n );\n }\n\n getFormFields() {\n var fields = FORM_FIELDS[this.formRevision];\n function getNestedValue(obj, path) {\n return path.split('.').reduce((o, key) => (o ? o[key] : \"\"), obj);\n }\n var outfields = [];\n var groupheading = {};\n var groupfields = [];\n for (var prop in fields) {\n if (fields[prop].t == \"heading\") {\n if (groupfields.length > 0) {\n groupheading.fields = groupfields;\n outfields.push(groupheading);\n groupfields = [];\n }\n groupheading = {\n heading: fields[prop].l,\n groupid: fields[prop].group ?? null,\n fields: []\n };\n }\n fields[prop].n = prop;\n fields[prop].v = getNestedValue(this, prop);\n if (typeof fields[prop].v == \"undefined\" || fields[prop].v == null) {\n fields[prop].v = \"\";\n }\n if (fields[prop].t == \"date\") {\n if (fields[prop].v instanceof Date) {\n // Cancel out the timezone in the date object\n // If we don't do this, the dates will be subtracted by one day each time we load\n // https://stackoverflow.com/a/17329571\n fields[prop].v.setTime(fields[prop].v.getTime() + fields[prop].v.getTimezoneOffset() * 60 * 1000);\n }\n fields[prop].v = formatTimestamp(\"Y-m-d\", fields[prop].v);\n if (fields[prop].v == \"1969-12-31\" || fields[prop].v == \"1970-01-01\") {\n fields[prop].v = \"\";\n }\n }\n if (fields[prop].t == \"select\" && typeof fields[prop].b == \"boolean\") {\n fields[prop].v = fields[prop].v ? \"true\" : \"\";\n }\n if (fields[prop].t != \"heading\") {\n groupfields.push(fields[prop]);\n }\n }\n if (groupfields != []) {\n groupheading.fields = groupfields;\n outfields.push(groupheading);\n }\n return outfields;\n }\n\n static fromHTMLFormData(formdata, revision = LATEST_FORM_REVISION) {\n var f = new FormPS1583();\n\n function setNestedValue(obj, path, value) {\n const keys = path.split('.');\n const lastKey = keys.pop();\n const target = keys.reduce((o, key) => {\n if (o[key] === undefined)\n o[key] = {};\n return o[key];\n }, obj);\n if (typeof FORM_FIELDS[revision][path].b == \"boolean\") {\n target[lastKey] = (value == \"true\" || value == true);\n } else {\n target[lastKey] = value;\n }\n }\n\n for (var prop in formdata) {\n setNestedValue(f, prop, formdata[prop]);\n }\n\n return f;\n }\n\n static fromJSON(o) {\n var f = new FormPS1583();\n f.formRevision = o.formRevision ?? LATEST_FORM_REVISION;\n f.pmbOpenedDate = new Date(o.pmbOpenedDate);\n f.pmbClosedDate = o.pmbClosedDate ? new Date(o.pmbClosedDate) : null;\n f.cmraStreetAddress = o.cmraStreetAddress;\n f.pmbNumber = o.pmbNumber;\n f.cmraCity = o.cmraCity;\n // snip, see constructor for full data structure\n return f;\n }\n\n toJSON() {\n return {\n formRevision: this.formRevision,\n pmbOpenedDate: this.pmbOpenedDate,\n pmbClosedDate: this.pmbClosedDate,\n cmraStreetAddress: this.cmraStreetAddress,\n pmbNumber: this.pmbNumber,\n cmraCity: this.cmraCity,\n // snip, see constructor for full data structure\n };\n }\n\n /**\n * Render this form to PDF\n * @returns PDF bytes\n */\n async getPDF() {\n // snip, it draws the form contents onto a PDF using the pdf-lib library\n // If you really want to see how, email us for the code\n return await document.save();\n }\n}\n</code></pre>"},{"location":"Docs/Parcel/","title":"Parcel/Package Object","text":"<p>This object is supplied a plugin registered with <code>registerRateEndpoint</code> when PostalPoint requests shipping rates from the plugin.</p> <pre><code>export class Package {\n constructor(isPrepaid = false) {\n this.prepaid = isPrepaid;\n this.packaging = {\n type: \"Parcel\",\n service: \"\",\n carrier: \"\",\n length: 999999,\n width: 999999,\n height: 999999,\n weightOz: 999999,\n nonmachinable: false,\n additionalHandling: false,\n internalid: 100,\n oversizeFlag: false\n };\n this.extraServices = {\n certifiedMail: false,\n barcode3800: \"\",\n registeredMail: false,\n registeredMailAmount: false, // can be a number in USD\n returnReceipt: false,\n returnReceiptElectronic: false,\n insurance: false, // can be a number in USD\n signature: false, // can be false, \"SIGNATURE\", or \"SIGNATURE_RESTRICTED\"\n hazmat: false,\n perishable: false,\n crematedRemains: false,\n liveAnimal: false, // BEES, DAY_OLD_POULTRY, ADULT_BIRDS, OTHER_LIVES\n cod: false, // Collect on Delivery\n codAmount: false,\n endorsement: \"\", // ADDRESS_SERVICE_REQUESTED, CHANGE_SERVICE_REQUESTED, FORWARDING_SERVICE_REQUESTED, LEAVE_IF_NO_RESPONSE, RETURN_SERVICE_REQUESTED\n carrier_billing_account: {// Bill a third party's account number for the label\n type: \"\", // \"\" (ignores this entire option), \"SENDER\" (EasyPost default), \"THIRD_PARTY\", \"RECEIVER\", \"COLLECT\"\n carrier: \"\", // Carrier ID (should be used to filter rates)\n account_number: \"\", // Carrier account number to bill\n country: \"\", // Country account is based in\n postal_code: \"\" // Postal code of account\n },\n dryIce: false,\n dryIceWeight: 0,\n dryIceMedical: false\n };\n this.description = \"\"; // Fillable on customs form, or generated before rating call using customs items\n this.specialRateEligibility = false;\n this.customs = {\n contents: \"\",\n contentsExplanation: \"\", // needed if contents is \"other\", will be copied from this.description if blank for maximum carrier compatibility\n signature: \"\",\n restriction: \"\",\n restrictionComments: \"\", // needed if restriction is \"other\"\n nonDelivery: \"return\", // \"return\" or \"abandon\",\n eel_pfc: \"\",\n items: [] // {index: 0, description: \"\", qty: \"\", lbs: \"\", oz: \"\", value: \"\", hscode: \"\", origin: US\"}\n };\n this.toAddress = new Address();\n this.returnAddress = new Address();\n this.originAddress = new Address();\n this.trackingNumber = \"\";\n }\n\n /**\n * Format as EasyPost shipment object\n * @returns {Package.toEasyPostShipment.shipment}\n */\n async toEasyPostShipment() {\n // Not relevant to plugins\n }\n\n /**\n * Format as Endicia shipment object\n * @returns {Package.toSERAShipment.shipment}\n */\n async toSERAShipment() {\n // Not relevant to plugins\n }\n\n /**\n * Get a human-readable summary of size and options.\n * Does not include address data.\n * @returns {String}\n */\n async toString() {\n let summary = [];\n let packaging = await getPackagingByID(this.packaging.internalid);\n let weight = ozToLbsOz(this.packaging.weightOz);\n let weightStr = this.packaging.weightOz >= 16 ? `${weight[0]} lbs ${weight[1]} oz` : `${weight[1]} oz`;\n if (packaging != false) {\n if (packaging.irregular) {\n if (packaging.weight === false) {\n summary.push(\"Parcel\");\n } else {\n summary.push(`${weightStr} Parcel`);\n }\n summary.push(\"Additional Handling\");\n } else {\n if (packaging.weight === false) {\n summary.push(packaging.name);\n } else {\n summary.push(`${weightStr} ${packaging.name}`);\n }\n }\n } else {\n summary.push(weightStr);\n }\n if (this.extraServices.hazmat) {\n summary.push(\"HAZMAT\");\n }\n if (this.extraServices.liveAnimal === true) {\n summary.push(\"Live Animals\");\n } else if (typeof this.extraServices.liveAnimal == \"string\") {\n switch (this.extraServices.liveAnimal) {\n case \"BEES\":\n summary.push(\"Live Bees\");\n break;\n case \"DAY_OLD_POULTRY\":\n summary.push(\"Day-old Poultry\");\n break;\n case \"ADULT_BIRDS\":\n summary.push(\"Live Adult Birds\");\n break;\n case \"OTHER_LIVES\":\n default:\n summary.push(\"Live Animals\");\n break;\n }\n }\n if (this.extraServices.perishable) {\n summary.push(\"Perishable\");\n }\n if (this.extraServices.crematedRemains) {\n summary.push(\"Cremated Remains\");\n }\n if (this.extraServices.certifiedMail) {\n summary.push(\"Certified Mail\");\n } else if (this.extraServices.registeredMail) {\n summary.push(\"Registered Mail\");\n summary.push(\"Registered for $\" + (this.extraServices.registeredMailAmount * 1.0).toFixed(2));\n } else if (this.extraServices.signature == \"SIGNATURE\") {\n summary.push(\"Signature Required\");\n }\n if (this.extraServices.signature == \"ADULT_SIGNATURE\") {\n summary.push(\"Adult Signature Required\");\n }\n if (this.extraServices.signature == \"SIGNATURE_RESTRICTED\") {\n summary.push(\"Restricted Delivery\");\n }\n if (this.extraServices.returnReceiptElectronic) {\n summary.push(\"Return Receipt Electronic\");\n }\n if (this.extraServices.returnReceipt) {\n summary.push(\"Return Receipt\");\n }\n if (this.extraServices.insurance) {\n summary.push(\"Insured for $\" + (this.extraServices.insurance * 1.0).toFixed(2));\n }\n if (this.extraServices.cod) {\n summary.push(\"Collect on Delivery: $\" + (this.extraServices.codAmount * 1.0).toFixed(2));\n }\n if (this.extraServices.dryIce && this.extraServices.dryIceWeight > 0) {\n summary.push(\"Dry Ice: \" + (this.extraServices.dryIceWeight * 1).toFixed(0) + \" oz\");\n }\n if (this.extraServices.carrier_billing_account?.type) {\n if (this.extraServices.carrier_billing_account.type != \"\") {\n var accountNumber = this.extraServices.carrier_billing_account.account_number;\n var accountNumberCensored = accountNumber.substring(accountNumber.length - 4).padStart(accountNumber.length, \"X\");\n var carrierName = this.extraServices.carrier_billing_account.carrier;\n switch (this.extraServices.carrier_billing_account.type) {\n case \"SENDER\":\n summary.push(`Bill to sender ${carrierName} account #${accountNumberCensored}`);\n break;\n case \"THIRD_PARTY\":\n summary.push(`Bill to third party ${carrierName} account #${accountNumberCensored}`);\n break;\n case \"RECEIVER\":\n summary.push(`Bill to receiver ${carrierName} account #${accountNumberCensored}`);\n break;\n case \"COLLECT\":\n if (accountNumber.length > 0) {\n summary.push(`Bill collect ${carrierName} account #${accountNumberCensored}`);\n } else {\n summary.push(`Bill collect`);\n }\n break;\n }\n }\n }\n return summary.join(\"\\n\");\n }\n\n async needsHAZMATPrompt() {\n try {\n let packagingInfo = await getPackagingByID(this.packaging.internalid);\n if (packagingInfo.hazmat) {\n return true;\n }\n if (this.packaging.weight > 10) {\n return true;\n }\n if (packagingInfo.l >= -1 && Math.max(this.packaging.length, this.packaging.width, this.packaging.height) > 0.5) {\n return true;\n }\n switch (packagingInfo.type) {\n case \"Letter\":\n case \"Card\":\n return false;\n }\n return true;\n } catch (ex) {\n return true;\n }\n }\n\n get isPrepaid() {\n return this.prepaid == true;\n }\n\n setCustomsInfo(contents, contentsExplanation, signature, restriction, restrictionComments, nonDelivery) {\n let items = this.customs.items; // Save this and copy it back in so we don't overwrite it\n this.customs = {\n contents: contents,\n contentsExplanation: contentsExplanation, // needed if contents is \"other\"\n signature: signature,\n restriction: restriction,\n restrictionComments: restrictionComments, // needed if restriction is \"other\"\n nonDelivery: nonDelivery, // \"return\" or \"abandon\",\n items: items\n };\n }\n\n /**\n * Get the customs items, ignoring any that are blank.\n * @returns {Array}\n */\n getCustomsItems() {\n let items = [];\n for (let i = 0; i < this.customs.items.length; i++) {\n let item = this.customs.items[i];\n if (item.description == \"\" && (item.qty == \"\" || item.qty == 0) && (item.weight == \"\" || item.weight == 0) && (item.value == \"\" || item.value == 0)) {\n continue;\n }\n items.push(item);\n }\n return items;\n }\n\n setCustomsItems(items) {\n this.customs.items = items;\n }\n\n getCustoms() {\n this.customs.items = this.getCustomsItems();\n return this.customs;\n }\n\n /**\n * Attempt to automatically fix simple issues like overweight letters.\n * @returns {undefined}\n */\n async fixIssues() {\n if (this.packaging.type == \"Letter\" && this.packaging.weightOz > 3.5) {\n if (this.packaging.nonmachinable) {\n return; // Has to be a parcel, can't fix without dimensions\n }\n this.packaging.type = \"Flat\";\n this.packaging.internalid = 104;\n }\n }\n\n /**\n * Do some basic checks to see if this package is even remotely shippable\n * @param {boolean} kioskMode If true, returned strings are suitable for display in kiosk mode.\n * @returns {boolean|string} true if okay, human-readable error message and instructions if not okay\n */\n async isValid(kioskMode = false) {\n // Removed from docs for brevity. Just a bunch of if statements to catch problems.\n }\n\n /**\n * Set package characteristics\n * @param {string} type \"Parcel\", \"Letter\", \"Flat\", \"Card\"\n * @param {type} service\n * @param {type} carrier\n * @param {type} length\n * @param {type} width\n * @param {type} height\n * @param {type} weightOz\n * @returns {undefined}\n */\n setPackaging(type, service, carrier, length, width, height, weightOz, nonmachinable) {\n if (typeof nonmachinable == \"undefined\") {\n nonmachinable = false;\n }\n if (type == \"Card\") {\n // Postcards\n weightOz = 1;\n this.packaging.internalid = 105;\n } else if (type == \"Flat\") {\n this.packaging.internalid = 104;\n } else if (type == \"Letter\") {\n this.packaging.internalid = 102;\n if (nonmachinable) {\n this.packaging.internalid = 103;\n }\n }\n this.packaging.type = type;\n this.packaging.service = service;\n this.packaging.carrier = carrier;\n this.packaging.weightOz = weightOz;\n this.packaging.nonmachinable = nonmachinable;\n\n // Enforce Length > Width > Height\n let size = [length, width, height];\n size.sort(function (a, b) {\n return b - a;\n });\n this.packaging.length = size[0];\n this.packaging.width = size[1];\n this.packaging.height = size[2];\n }\n\n /**\n * Set an extra service\n * @param {string} id Service ID\n * @param {boolean} enabled Turn it on or off\n * @param {string} value Service value, if needed (some are not just a boolean)\n * @returns {undefined}\n */\n setExtraService(id, enabled, value) {\n if (typeof value != \"undefined\" && enabled) {\n this.extraServices[id] = value;\n } else {\n this.extraServices[id] = enabled == true;\n }\n }\n\n getExtraServices() {\n return this.extraServices;\n }\n\n /**\n * Set to \"MEDIA_MAIL\", \"LIBRARY_MAIL\", or false\n * @param {type} rate\n * @returns {undefined}\n */\n set specialRate(rate) {\n if (rate == \"MEDIA\") {\n rate = \"MEDIA_MAIL\";\n } else if (rate == \"LIBRARY\") {\n rate = \"LIBRARY_MAIL\";\n }\n if (rate != \"MEDIA_MAIL\" && rate != \"LIBRARY_MAIL\") {\n rate = false;\n }\n this.specialRateEligibility = rate;\n }\n\n get specialRate() {\n return this.specialRateEligibility;\n }\n\n /**\n * Save an address to this package.\n * @param {string} type \"to\", \"return\", or \"origin\"\n * @param {string} name\n * @param {string} company\n * @param {string} street1\n * @param {string} street2\n * @param {string} city\n * @param {string} state\n * @param {string} zip\n * @param {string} country ISO 2-char country code\n * @param {string} phone\n * @param {string} email\n * @returns {undefined}\n */\n setAddress(type, name, company, street1, street2, city, state, zip, country, phone, email) {\n let address = Address.fromObject({\n name: name,\n company: company,\n street1: street1,\n street2: street2,\n city: city,\n state: state,\n zip: zip,\n country: country,\n phone: phone,\n email: email\n });\n switch (type) {\n case \"to\":\n this.toAddress = address;\n break;\n case \"return\":\n this.returnAddress = address;\n break;\n case \"origin\":\n this.originAddress = address;\n break;\n }\n }\n\n /**\n * Set an address using an object that matches the internal form (see setAddress())\n * @param {string} type\n * @param {object} data\n * @returns {undefined}\n */\n setAddressWhole(type, address) {\n switch (type) {\n case \"to\":\n this.toAddress = Address.fromObject(address);\n break;\n case \"return\":\n this.returnAddress = Address.fromObject(address);\n break;\n case \"origin\":\n this.originAddress = Address.fromObject(address);\n break;\n }\n }\n\n get tracking() {\n return this.trackingNumber;\n }\n\n set tracking(n) {\n this.trackingNumber = n;\n }\n\n /**\n * Get the \"from\" address that will be shown,\n * using the return address or origin address as needed\n * @returns {address}\n */\n getReturnAddress() {\n var a = null;\n if (typeof this.returnAddress == \"object\") {\n a = Address.fromObject(this.returnAddress);\n } else {\n a = Address.fromObject(this.originAddress);\n }\n if (a.country == \"\") {\n a.country = defaultCountryCode();\n }\n return a;\n }\n\n getToAddress() {\n var a = Address.fromObject(this.toAddress);\n if (a.country == \"\") {\n a.country = defaultCountryCode();\n }\n return a;\n }\n\n getFromAddress() {\n var a = null;\n if (typeof this.originAddress == \"object\") {\n a = Address.fromObject(this.originAddress);\n } else {\n a = Address.fromObject(this.returnAddress);\n }\n if (a.country == \"\") {\n a.country = defaultCountryCode();\n }\n return a;\n }\n}\n</code></pre>"},{"location":"Docs/Receipt/","title":"Receipt Objects","text":""},{"location":"Docs/Receipt/#sample-receipt-object","title":"Sample receipt object","text":"<p>This is an example of the data <code>global.apis.pos.onReceiptChange</code> and <code>global.apis.pos.onTransactionFinished</code> send to plugins. All data for a PostalPoint transaction is available in its receipt object.</p> <p>The money-related properties near the bottom of this sample are generated by PostalPoint from the items and payments.</p>"},{"location":"Docs/Receipt/#notes","title":"Notes:","text":"<ul> <li>The <code>due</code> property will be a negative number if change is owed to the customer.</li> <li><code>pendingEmailTo</code> is set to a suggested email address for the email receipt, and if the receipt should actually be emailed, it will be set in <code>emailTo</code>.</li> <li><code>uuid</code> is a unique 16-character alphanumeric receipt ID number, which is shown and used in several places. The <code>uuid</code> is generated using <code>global.apis.util.uuid.short()</code>.</li> <li><code>customerAccountId</code> is the UUID for the customer's account, or null if there isn't a customer attached.</li> <li>This example happens to be the object used when test printing a receipt from the PostalPoint settings menu, so press that button to see what this is rendered into.</li> </ul> <pre><code>{\n \"items\": [\n ReceiptItem.fromJSON({\n \"id\": \"9100123456789012345678\",\n \"label\": \"Test Package\",\n \"text\": \"Package Details\\nTracking # 9100 1234 5678 9012 3456 78\\nTo:\\nTEST PERSON\\nORGANIZATION INC\\n123 TEST ROAD\\nTESTTOWN TE 99999-0001\",\n \"priceEach\": 8,\n \"qty\": 1,\n \"cost\": 0,\n \"retail\": 8,\n \"taxRate\": 0,\n \"free\": false,\n \"barcode\": \"9100123456789012345678\",\n \"certifiedInfo\": false,\n \"isMerch\": false,\n \"surcharge\": false,\n \"toAddress\": {\n \"name\": \"TEST PERSON\",\n \"company\": \"ORGANIZATION INC\",\n \"street1\": \"123 TEST ROAD\",\n \"street2\": null,\n \"city\": \"TESTTOWN\",\n \"state\": \"TE\",\n \"zip\": \"99999-0001\",\n \"email\": null,\n \"phone\": null,\n \"country\": \"US\"\n },\n \"fromAddress\": {\n \"name\": \"TEST PERSON\",\n \"company\": \"ORGANIZATION INC\",\n \"street1\": \"123 TEST ROAD\",\n \"street2\": null,\n \"city\": \"TESTTOWN\",\n \"state\": \"TE\",\n \"zip\": \"99999-0001\",\n \"email\": null,\n \"phone\": null,\n \"country\": \"US\"\n }\n }),\n ReceiptItem.fromJSON({\n \"id\": \"testitem\",\n \"label\": \"Test Item\",\n \"text\": \"\",\n \"priceEach\": 2,\n \"qty\": 1,\n \"cost\": 0,\n \"retail\": 2,\n \"taxRate\": 0.1,\n \"free\": false,\n \"barcode\": \"\",\n \"certifiedInfo\": false,\n \"isMerch\": true,\n \"surcharge\": false\n })\n ],\n \"payments\": [\n ReceiptPayment.fromJSON({\n \"amount\": 10,\n \"type\": \"cash\",\n \"text\": \"\",\n \"id\": \"testcash\"\n })\n ],\n \"subtotal\": 10,\n \"subtotalFormatted\": \"$10.00\",\n \"tax\": 0.2,\n \"taxFormatted\": \"$0.20\",\n \"grandTotal\": 10.2,\n \"grandTotalFormatted\": \"$10.20\",\n \"paid\": 10.2,\n \"paidFormatted\": \"$10.20\",\n \"due\": 0,\n \"dueFormatted\": \"$0.00\",\n \"emailTo\": null,\n \"pendingEmailTo\": null,\n \"uuid\": \"1234567890abcdef\",\n \"customerAccountId\": null,\n \"topTextHTML\": \"\",\n \"bottomTextHTML\": \"\"\n}\n</code></pre>"},{"location":"Docs/Receipt/#globalapisposreceiptitem","title":"global.apis.pos.ReceiptItem","text":"<pre><code>export class ReceiptItem {\n /**\n *\n * @param {string|number} id Unique ID number for this item (UPC code, inventory number, etc). Used to deduplicate line items. Unique items (like shipping labels) should be random or empty.\n * @param {string} label One-line item information.\n * @param {string} text Extra item information.\n * @param {number} priceEach Price per unit\n * @param {number} quantity Number of units\n * @param {number} cost Cost per unit. Used for automatic expense tracking.\n * @param {number} taxrate Examples: 0 (for 0%), 0.05 (for 5%), etc\n * @param {string} taxableAmount The part of the sale price that's taxable. \"\" for default (all), \"markup\" for only taxing profit.\n * @returns {ReceiptItem}\n */\n constructor(id, label, text, priceEach, quantity, cost, taxrate = 0.0, taxableAmount = \"\") {\n this.id = id;\n this.label = label;\n if (text == null) {\n this.txt == \"\";\n } else {\n this.txt = text;\n }\n this.priceEach = num(priceEach);\n this.qty = num(quantity);\n this.cost = num(cost);\n if (isNaN(taxrate)) {\n this.taxRate = 0;\n } else {\n this.taxRate = num(taxrate);\n }\n this.taxableAmount = taxableAmount;\n this.merch = false;\n this.merchid = null;\n this.surcharge = false;\n this.retail = 0; // For ensuring PostalPoint fee collection on office mode shipments\n this.mailboxNumber = null;\n this.mailboxDays = 0;\n this.mailboxMonths = 0;\n this.category = \"\"; // merch category\n this.electronicReturnReceipt = false;\n }\n\n static fromJSON(obj) {\n var item = new ReceiptItem(obj.id, obj.label, obj.text, obj.priceEach, obj.qty, obj.cost, obj.taxRate, obj.taxableAmount ?? \"\");\n item.free = obj.free;\n item.barcode = obj.barcode;\n item.certifiedInfo = obj.certifiedInfo;\n item.toAddress = obj.toAddress;\n item.fromAddress = obj.fromAddress;\n item.merch = obj.isMerch == true || (typeof obj.merchid == \"string\" && obj.merchid.length > 0);\n item.merchid = obj.merchid ?? null;\n item.mailboxNumber = obj.mailboxNumber ?? null;\n item.mailboxDays = obj.mailboxDays ?? 0;\n item.mailboxMonths = obj.mailboxMonths ?? 0;\n item.surcharge = obj.surcharge;\n item.retailPrice = obj.retail;\n item.carrier = obj.carrier ?? null;\n item.service = obj.service ?? null;\n item.category = obj.category ?? \"\";\n item.electronicReturnReceipt = obj.electronicReturnReceipt ?? false;\n return item;\n }\n\n toJSON() {\n return {\n id: this.id,\n label: this.label,\n text: this.text,\n priceEach: num(this.priceEach),\n qty: num(this.qty),\n cost: num(this.cost),\n retail: num(this.retail),\n taxRate: num(this.taxRate),\n taxableAmount: this.taxableAmount,\n taxTotal: this.taxAmount,\n free: this.free,\n barcode: this.barcode,\n certifiedInfo: this.certifiedInfo,\n isMerch: this.merch,\n merchid: this.merchid,\n surcharge: this.surcharge,\n toAddress: this.toAddress,\n fromAddress: this.fromAddress,\n mailboxNumber: this.mailboxNumber,\n mailboxDays: this.mailboxDays,\n mailboxMonths: this.mailboxMonths,\n carrier: this.carrier,\n service: this.service,\n category: this.category,\n electronicReturnReceipt: this.electronicReturnReceipt\n };\n }\n\n get text() {\n if (typeof this.txt == \"string\") {\n return this.txt;\n }\n return \"\";\n }\n\n set text(t) {\n if (typeof t == \"string\") {\n this.txt = t;\n } else {\n this.txt = \"\";\n }\n }\n\n get certifiedInfo() {\n if (typeof this.certified == \"undefined\") {\n return false;\n }\n return this.certified;\n }\n\n set certifiedInfo(info) {\n this.certified = info;\n }\n\n setCertifiedInfo(tracking, certfee, extrafees, postage, date, location, toaddress) {\n this.certified = {\n tracking: tracking,\n certifiedFee: num(certfee),\n extraFees: extrafees,\n postage: num(postage),\n date: date,\n location: location,\n to: toaddress\n };\n }\n\n setQuantity(q) {\n this.qty = num(q);\n }\n\n get free() {\n return this.isFree == true;\n }\n\n set free(free) {\n this.isFree = free == true;\n }\n\n get barcode() {\n if (typeof this.barcodeData != \"string\") {\n return \"\";\n }\n return this.barcodeData;\n }\n\n set barcode(data) {\n this.barcodeData = data;\n }\n\n get linePrice() {\n return round(m(this.priceEach, this.qty), 2);\n }\n\n get priceEachFormatted() {\n return getCurrencySymbol() + round(num(this.priceEach), 2).toFixed(2);\n }\n\n get linePriceFormatted() {\n return getCurrencySymbol() + round(num(this.linePrice), 2).toFixed(2);\n }\n\n get texthtml() {\n if (typeof this.text != \"string\") {\n return \"\";\n }\n var lines = this.text.split(\"\\n\");\n for (var i = 0; i < lines.length; i++) {\n if (lines[i].startsWith(\"Tracking # \")) {\n // Allow copying tracking number\n lines[i] = \"Tracking # <span class=\\\"usall\\\">\" + lines[i].replace(\"Tracking # \", \"\") + \"</span>\";\n }\n }\n return lines.join(\"<br />\");\n }\n\n get taxAmount() {\n if (this.taxableAmount == \"markup\") {\n var lineCost = m(this.cost, this.qty);\n var margin = s(this.linePrice, lineCost);\n if (margin <= 0) {\n return 0;\n }\n return round(m(margin, this.taxRate), 2);\n } else {\n return round(m(this.linePrice, this.taxRate), 2);\n }\n }\n\n get retailPrice() {\n if (typeof this.retail == \"number\") {\n return this.retail;\n }\n return this.priceEach * this.qty;\n }\n\n set retailPrice(price) {\n this.retail = num(price);\n }\n\n}\n</code></pre>"},{"location":"Docs/Receipt/#globalapisposreceiptpayment","title":"global.apis.pos.ReceiptPayment","text":"<pre><code>export class ReceiptPayment {\n\n /**\n *\n * @param {number} amount amount paid\n * @param {string} type payment type\n * @param {string} text extra data (credit card info, etc)\n * @returns {ReceiptPayment}\n */\n constructor(amount, type, text) {\n this.id = (Math.random() * 100000000) + \"_\" + type + \"_\" + amount;\n this.text = (typeof text != \"string\" ? \"\" : text);\n this.type = type;\n this.amount = amount;\n }\n\n static fromJSON(obj) {\n var item = new ReceiptPayment(obj.amount, obj.type, obj.text);\n item.id = obj.id;\n return item;\n }\n\n toJSON() {\n return {\n amount: round(this.amount, 2),\n type: this.type,\n text: this.text,\n id: this.id\n };\n }\n\n get texthtml() {\n if (typeof this.text != \"string\") {\n return \"\";\n }\n return this.text.replaceAll(\"\\n\", \"<br />\");\n }\n\n get amountFormatted() {\n return getCurrencySymbol() + this.amount.toFixed(2);\n }\n\n get label() {\n if (typeof this.type != \"string\") {\n return \"Payment\";\n }\n switch (this.type) {\n case \"cash\":\n return \"Cash\";\n case \"check\":\n return \"Check\";\n case \"card\":\n return \"Card\";\n case \"card_manual\":\n return \"Card\";\n case \"account\":\n return \"Account\";\n case \"free\":\n return \"Free\";\n case \"discount\":\n return \"Discount\";\n case \"crypto\":\n return \"Cryptocurrency\";\n case \"ach\":\n return \"ACH Debit\";\n case \"rounding\":\n return \"Cash Rounding\"; // Used in penniless countries to balance a cash-only transaction\n default:\n return this.type;\n }\n }\n}\n</code></pre>"},{"location":"Docs/ReceiptPrinter/","title":"Receipt Printer driver functions","text":"<p>PostalPoint abstracts the receipt printer hardware commands, so the same functions are available on all brands and languages of receipt printer, and printer media size and settings are also handled for you.</p> <p>The drivers operate in line mode, where each successive command appends content to the bottom of the page.</p> <p>These functions are available on the object supplied by the promise returned from <code>global.apis.print.getReceiptPrinter()</code>.</p>"},{"location":"Docs/ReceiptPrinter/#functions","title":"Functions","text":"<pre><code>//\n// Add one or more lines of text, with automatic wrapping.\n// If both firsttext and secondtext are provided, two columns of text are generated,\n// with the first left-justified and the second right-justified.\n// `firstjustify` can be \"L\" (left), \"C\" (center), or \"R\" (right).\n// Not all printers support all the formatting options, and may render them in different ways,\n// but the formatting intent is made clear regardless.\naddFieldBlock(firsttext, firstjustify, secondtext = \"\", secondjustify = \"R\", bold = false, doubleheight = false, underline = false);\n\n// Add a blank line to the label.\nnewLine();\n\n// Draw a horizontal line across the page.\ndrawLine();\n\n// Render a Code 128 barcode, centered horizontally, with a human-readable label beneath.\n// Important: this function is sometimes asynchronous depending on the printer driver.\nbarcode128(content);\n\n// Print an image. Width is in pixels.\n// pixelByteArray is a Uint8Array where each bit is a pixel (1=black, 0=white),\n// starting at the top-left of the image and going across and then down. Use `imageToBitmap` to\n// obtain this data from a Jimp image.\n// Use \"L\" as the position to print on the next line, centered horizontally.\n// Some printers also support position = \"C\", which will\n// ignore other commands and print the image centered on the label,\n// but if you're doing that, just use `global.apis.print.printLabelImage()` instead.\ndrawImage(width, position, pixelByteArray);\n\n// If supported by the printer, opens an attached cash drawer. Command is ignored if unavailable.\nopenCashDrawer();\n\n// The last command to run, when ready to print. Returns the raw data to send to the printer.\n// Important: this function is sometimes asynchronous depending on the printer driver.\ngetData();\n</code></pre>"},{"location":"Docs/ReceiptPrinter/#example","title":"Example","text":"<pre><code>var printer = await global.apis.print.getReceiptPrinter();\n\nprinter.addFieldBlock(\"Hello Bold World!\", \"C\", \"\", \"\", true);\nprinter.drawLine();\nawait printer.barcode128(\"1234567890\");\nprinter.newLine();\n\nawait global.apis.printer.printReceiptData(await printer.getData());\n</code></pre>"},{"location":"Docs/TrackingBarcode/","title":"TrackingBarcode class","text":"<p>For your reference, here is the source code of the TrackingBarcode class, used to represent a prepaid drop-off. This class is provided to plugins as <code>global.apis.barcode.TrackingBarcode</code>.</p> <pre><code>export class TrackingBarcode {\n /**\n * Create a tracking barcode object.\n * @param {string} code Tracking number.\n * @returns {TrackingBarcode}\n */\n constructor(code) {\n // All data are optional except for the tracking number. Missing data is gracefully handled by the PostalPoint UI.\n this.cleanCode = code;\n // Original barcode data this was created from\n this.barcode = code;\n // Destination ZIP Code, for domestic shipments. The city and state are automatically added. If toAddress is specified, toZip is ignored in favor of it.\n this.toZip = \"\";\n // Two-letter destination country code. If not \"US\", toZip is ignored, and the full country name is appended to the displayed address information.\n this.toCountry = defaultCountryCode();\n // If toAddress is set, it will be used instead of the toZip when displaying the destination.\n // If both toZip and toAddress are empty strings, no destination will be displayed.\n this.toAddress = \"\";\n // If message is not empty, the barcode will NOT be added and the message will be displayed to the user.\n this.message = \"\";\n // If warning is not empty, the barcode WILL be added and a message will be displayed to the user.\n this.warning = \"\";\n // Shipping carrier name.\n this.carrier = \"\";\n // Shipping service/mail class full name and description. Example: \"Priority Mail Adult Signature Required\".\n this.serviceName = \"\";\n // Shipping service/mail class name, without extra info such as \"signature required\".\n // Example: \"Priority Mail\"\n this.serviceShort = \"\";\n // If set to false, the barcode will be rejected with a suitable message when PostalPoint is running in self-serve kiosk mode.\n this.dropoff = true;\n // If false, app may prompt user to specify the shipping carrier\n this.confidentCarrier = true;\n // Extra description strings, like \"Signature Required\"\n this.extraInfo = [];\n }\n\n /**\n * Set the tracking number\n * @param {string} str\n * @returns {undefined}\n */\n set tracking(str) {\n this.cleanCode = str;\n }\n\n /**\n * Set the service/mail class description string.\n * @param {string} str\n * @returns {undefined}\n */\n set service(str) {\n this.serviceShort = str;\n this.serviceName = str;\n }\n\n /**\n * Get the tracking number.\n * @returns {String}\n */\n get tracking() {\n return this.cleanCode;\n }\n\n /**\n * Get the destination ZIP code.\n * @returns {String}\n */\n get zip() {\n return this.toZip;\n }\n\n /**\n * Get the service/mail class description.\n * @returns {String}\n */\n get service() {\n if (this.serviceShort != \"\") {\n return this.serviceShort;\n } else if (this.serviceName != \"\") {\n return this.serviceName;\n }\n return \"\";\n }\n\n /**\n * Get the carrier and service info.\n * @returns {String}\n */\n get serviceString() {\n var str = [];\n if (this.carrier != \"\") {\n str.push(this.carrier);\n }\n if (this.serviceShort != \"\") {\n str.push(this.serviceShort);\n } else if (this.serviceName != \"\") {\n str.push(this.serviceName);\n }\n return str.join(\" \");\n }\n\n /**\n * Get the destination information as a human-presentable multiline string.\n * @returns {String}\n */\n get destString() {\n var addressLines = [];\n if (this.toAddress != \"\") {\n addressLines.push(...this.toAddress.split(\"\\n\"));\n }\n if (defaultCountryCode() == this.toCountry.toUpperCase() && this.toCountry.toUpperCase() == \"US\" && this.toZip != \"\" && this.toAddress == \"\") {\n // Domestic shipment within USA, look up ZIP code\n var zipdata = getZIP(this.toZip);\n if (zipdata != false) {\n addressLines.push(`${zipdata.city} ${zipdata.state} ${this.toZip}`);\n } else {\n addressLines.push(`${this.toZip}`);\n }\n } else if (defaultCountryCode() == this.toCountry.toUpperCase()) {\n // Domestic shipment, outside USA, add postal code line if we have one\n if (this.toZip != \"\" && this.toAddress.includes(this.toZip) != true) {\n addressLines.push(`${this.toZip}`);\n }\n } else {\n // International shipment, add country name\n addressLines.push(getCountryNameForISO(this.toCountry));\n }\n return addressLines.join(\"\\n\");\n }\n\n /**\n * Get the package information in a format suitable for display on a receipt.\n * @param {boolean} includeTrackingNumber If false, the tracking number will be suppressed.\n * @returns {String}\n */\n toString(includeTrackingNumber = true) {\n var lines = [];\n if (includeTrackingNumber && this.cleanCode) {\n lines.push(this.cleanCode);\n }\n var serv = this.serviceString;\n if (serv != \"\") {\n lines.push(serv);\n }\n var dest = this.destString;\n if (dest != \"\") {\n var destlines = dest.split(\"\\n\");\n destlines[0] = \"To \" + destlines[0];\n lines.push(...destlines);\n }\n\n if (typeof this.extraInfo == \"object\" && this.extraInfo.length > 0) {\n lines.push(...this.extraInfo);\n }\n\n return lines.join(\"\\n\");\n }\n}\n</code></pre>"},{"location":"Examples/01Minimal/","title":"Minimal Plugin","text":"<p>This is the smallest possible valid plugin.</p> plugin-name/plugin.js<pre><code>exports.init = function () {\n global.apis.alert(\"This message appears when PostalPoint launches.\", \"Hello!\");\n};\n</code></pre>"},{"location":"Examples/02Basic/","title":"Basic Plugin","text":"<p>This sample plugin showcases some of the features many plugins will want to use.</p> <p>Download JavaScript</p> plugin.js<pre><code>// Sample plugin to demonstrate plugin capabilities and structure.\n\nasync function getPage() {\n // A Framework7 component page\n return global.apis.getPluginFolder(\"basic-demo\") + \"/uipluginpage.f7\";\n}\n\n// This is run when PostalPoint loads the plugin at launch.\n// Use it to register for things you want to do, like adding a page, hooking into payments or shipping rates, etc.\nexports.init = function () {\n console.log(global.apis.settings.get(\"basic-demo_secretcode\"));\n global.apis.ui.addToolsPage(getPage, \"Sample Page Title\", \"sampletool1234\", \"A sample plugin page\", \"Sample\", \"fa-solid fa-circle\");\n};\n\n// This defines a settings UI to display for the plugin.\n// If exports.config is a function instead of an array, it will be executed when opening the settings\n// and must return an array like the one below.\n// If exports.config is undefined, a settings menu will not be provided to the user.\nexports.config = [\n {\n type: \"button\",\n label: \"Test Button\",\n text: \"Some text about the button\",\n onClick: function () {\n global.apis.alert(\"Button pressed\");\n }\n },\n {\n type: \"text\",\n key: \"app.postalpoint.basic-demo_somestring\", // Try to make sure this is unique by using a prefix,\n // settings storage is global so there could be conflicts if you aren't careful\n defaultVal: \"\",\n label: \"Type a string\",\n placeholder: \"\",\n text: \"Description text next to the input box\",\n sync: false // Add sync: false to prevent automatically syncing this setting between\n // PostalPoint installations (i.e. it's a device-specific setting, like a pairing code)\n // If it's not present, or is any truthy value, it could be synced between PCs\n },\n {\n type: \"password\",\n key: \"app.postalpoint.basic-demo_secretcode\",\n defaultVal: \"\",\n label: \"Secret Code\",\n placeholder: \"\",\n text: \"Don't tell anyone this secret code:\"\n },\n {\n type: \"textarea\",\n key: \"app.postalpoint.basic-demo_sometext\",\n defaultVal: \"\",\n label: \"Text Box\",\n placeholder: \"...\",\n text: \"You can type a few lines of text here.\"\n },\n {\n type: \"select\",\n key: \"app.postalpoint.basic-demo_dropdownbox\",\n defaultVal: \"\",\n label: \"Choose an option\",\n placeholder: \"\",\n text: \"\",\n options: [[\"key1\", \"Value 1\"], [\"key2\", \"Value 2\"]]\n }\n];\n</code></pre> <p>Download HTML</p> uipluginpage.f7<pre><code><template>\n <div class=\"page\">\n <div class=\"navbar\">\n <div class=\"navbar-bg\"></div>\n <div class=\"navbar-inner\">\n <div class=\"title\">${title}</div>\n </div>\n </div>\n <div class=\"page-content\">\n <a class=\"button\" @click=${openAlert}>Open Alert</a>\n <a class=\"button\" @click=${printSomething}>Print Something</a>\n <div class=\"list simple-list\">\n <ul>\n ${names.map((name) => $h`\n <li>${name}</li>\n `)}\n </ul>\n </div>\n </div>\n </div>\n</template>\n<!-- component styles -->\n<style>\n .red-link {\n color: red;\n }\n</style>\n<!-- rest of component logic -->\n<script>\n // script must return/export component function\n export default (props, { $f7, $on }) => {\n const title = 'Component Page';\n const names = ['John', 'Vladimir', 'Timo'];\n\n const openAlert = () => {\n $f7.dialog.alert('Hello world!\\nblah blah blah');\n }\n\n async function printSomething() {\n // Print some text to the receipt printer\n var printer = await global.apis.print.getReceiptPrinter();\n printer.addFieldBlock('Hello world!\\nblah blah blah\\n\\n', \"C\");\n global.apis.print.printReceiptData(await printer.getData());\n }\n\n $on('pageInit', () => {\n // do something on page init\n });\n $on('pageAfterOut', () => {\n // page has left the view\n });\n\n // component function must return render function\n return $render;\n }\n</script>\n</code></pre>"},{"location":"Examples/03Shipping/","title":"Shipping Plugin","text":"<p>This sample plugin demonstrates how to add support for a custom shipping carrier.</p> <p>Download JavaScript</p> plugin.js<pre><code>// This is a sample PostalPoint plugin for adding support for a shipping carrier.\n\nvar rateCache = [];\nvar parcelCache = {};\n\nexports.init = function () {\n // Add support for shipping rating and label purchasing\n global.apis.shipping.registerRateEndpoint(getRates, purchase, \"uniqueprefixhere_\");\n\n // Add support for prepaid drop-offs\n global.apis.barcode.onPrepaidScan(function (barcode) {\n if (barcode.startsWith(\"mycarrierbarcode\")) { // Replace this with your checks for barcode validity\n var data = new global.apis.barcode.TrackingBarcode(barcode);\n data.carrier = \"Carrier Name\";\n data.service = \"Service Name\";\n return data;\n }\n return false;\n });\n}\n\nasync function purchase(rateid) {\n for (var i = 0; i < rateCache.length; i++) {\n if (rateCache[i].rateid == rateid) {\n var rate = rateCache[i];\n //\n // Fetch label and tracking and such\n //\n var label;\n var tracking = \"123456\";\n var toAddressLines = parcelCache.toAddress.toStringArray();\n\n // Create receipt item\n var receiptitem = new global.apis.pos.ReceiptItem(`uniqueprefixhere_${tracking}`,\n `${rate.carrierName} ${rate.serviceName}`,\n `Tracking # ${global.apis.util.string.chunk(tracking, 3).join(\" \")}\\nTo:\\n${toAddressLines.join(\"\\n\")}`,\n rate.retail_rate, 1, rate.cost_rate, 0\n );\n receiptitem.barcode = tracking;\n receiptitem.carrier = \"Carrier Name\";\n receiptitem.service = \"Service Name\";\n\n return {\n label: label,\n labeltype: \"PNG\",\n receiptItem: receiptitem,\n tracking: tracking,\n cost: rate.cost_rate,\n price: rate.retail_rate,\n carrier: rate.carrierName,\n service: rate.serviceName,\n delivery_days: rate.delivery_days,\n delivery_date: rate.delivery_date,\n to: toAddressLines\n };\n }\n }\n}\n\nasync function getRates(parcel) {\n // parcel is an object as shown in docs/Parcel.md\n var rates = [];\n rates.push({\n rateid: \"uniqueprefixhere_\" + global.apis.util.uuid.v4(),\n carrier: \"Carrier\",\n carrierName: \"Carrier Name\",\n service: \"CARRIER_SERVICE_ID\",\n cost_rate: 10,\n retail_rate: 15,\n delivery_days: 3,\n delivery_date: null,\n guaranteed: true,\n serviceName: \"Service Name\",\n color: \"green\" // Rate card color\n });\n\n // Save details for later use if purchased\n rateCache = rates;\n parcelCache = parcel;\n\n return rates;\n}\n</code></pre>"},{"location":"Examples/04CardProcessor/","title":"Card Payments","text":"<p>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.</p> <p>Download JavaScript</p> plugin-name/plugin.js<pre><code>// This is a sample PostalPoint plugin that adds a card payment processor.\n\nexports.init = function () {\n global.apis.pos.registerCardProcessor({\n name: \"Demo Card Processor\",\n init: async function () {\n // This function runs once after starting PostalPoint\n // and before any other card processor functions are called.\n },\n checkout: async function({amount, capture = true}) {\n // amount is an integer number of pennies.\n\n // If an error is encountered during processing,\n // display an error message in a dialog and return boolean false.\n // If this function returns anything except false or undefined, and doesn't throw an error,\n // it is assumed the payment was successful.\n try {\n if (capture) {\n // authorize, capture, add a ReceiptPayment to the receipt, and return boolean true.\n global.apis.pos.addOnscreenPaymentLog(\"Getting card payment...\"); // Add a line to the onscreen card processing status log\n await global.apis.util.delay(1000); // Replace this with something useful!\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n (amount / 100).toFixed(2) * 1,\n \"card\", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free. Other types will be displayed as-is to the user and on the receipt.\n \"Demo Card\\nCardholder Name, etc\\nMore info for receipt\" // Additional text for receipt\n )\n );\n global.apis.pos.addOnscreenPaymentLog(\"Payment successful!\");\n return true;\n } else {\n // only authorize the payment, don't actually capture/charge the payment method,\n // and return whatever transaction data that will be passed to finishPayment to capture the payment.\n await global.apis.util.delay(1000); // Replace this with something useful!\n return {amount: amount};\n }\n } catch (ex) {\n global.apis.pos.addOnscreenPaymentLog(`Error: ${ex.message} [okay to put extra details here for troubleshooting or tech support, it's visible to the cashier]`);\n if (global.apis.kiosk.isKiosk()) {\n // This message will be shown to an end-user/customer, not a cashier/employee\n global.apis.alert(\"Your card was declined.\", \"Card Error\");\n } else {\n global.apis.alert(\"The customer's card was declined.\", \"Card Error\");\n }\n return false;\n }\n },\n cancelCheckout: function () {\n // The user requested to cancel the payment.\n // Reset the terminal to its resting state, clear its screen, etc.\n },\n finishPayment: async function ({checkoutResponse}) {\n // Finish a payment that was authorized but not captured because checkout was called with capture = false\n // If payment was already captured and added to the receipt for some reason, just return true.\n await global.apis.util.delay(1000); // Replace this with something useful!\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n (checkoutResponse.amount / 100).toFixed(2) * 1,\n \"card\", // Payment type.\n \"Demo Card\\nCardholder Name, etc\\nMore info for receipt\" // Additional text for receipt\n )\n );\n return true;\n },\n updateCartDisplay: function (receipt) {\n // Show transaction data on the card reader display.\n // This function will be called when the cart or total changes.\n console.log(receipt);\n // Sample structure of the receipt variable:\n receipt = {\n \"items\": [\n {\n \"id\": \"testitem\",\n \"label\": \"Test Item\",\n \"text\": \"\",\n \"priceEach\": 2,\n \"qty\": 1,\n \"cost\": 0,\n \"retail\": 2,\n \"taxRate\": 0.1,\n \"free\": false,\n \"barcode\": \"\",\n \"certifiedInfo\": false,\n \"isMerch\": true,\n \"surcharge\": false\n },\n {\n \"id\": \"9100123456789012345678\",\n \"label\": \"Test Package\",\n \"text\": \"Package Details\\nTracking # 9100 1234 5678 9012 3456 78\\nTo:\\nTEST PERSON\\nORGANIZATION INC\\n123 TEST ROAD\\nTESTTOWN TE 99999-0001\",\n \"priceEach\": 8,\n \"qty\": 1,\n \"cost\": 0,\n \"retail\": 8,\n \"taxRate\": 0,\n \"free\": false,\n \"barcode\": \"9100123456789012345678\",\n \"certifiedInfo\": false,\n \"isMerch\": false,\n \"surcharge\": false,\n \"toAddress\": {\n \"name\": \"TEST PERSON\",\n \"company\": \"ORGANIZATION INC\",\n \"street1\": \"123 TEST ROAD\",\n \"street2\": null,\n \"city\": \"TESTTOWN\",\n \"state\": \"TE\",\n \"zip\": \"99999-0001\",\n \"email\": null,\n \"phone\": null,\n \"country\": \"US\"\n },\n \"fromAddress\": {\n \"name\": \"TEST PERSON\",\n \"company\": \"ORGANIZATION INC\",\n \"street1\": \"123 TEST ROAD\",\n \"street2\": null,\n \"city\": \"TESTTOWN\",\n \"state\": \"TE\",\n \"zip\": \"99999-0001\",\n \"email\": null,\n \"phone\": null,\n \"country\": \"US\"\n }\n }\n ],\n \"payments\": [\n {\n \"amount\": 10,\n \"amountFormatted\": \"$10.00\",\n \"type\": \"cash\",\n \"label\": \"Cash\",\n \"text\": \"\",\n \"texthtml\": \"\",\n \"id\": \"12345678_cash_10\"\n },\n {\n \"amount\": 12.34,\n \"amountFormatted\": \"$12.34\",\n \"type\": \"card\",\n \"label\": \"Card\",\n \"text\": \"Card Details here\\n1234abcd\",\n \"texthtml\": \"Card Details here<br />1234abcd\",\n \"id\": \"87654321_card_12.34\"\n }\n ],\n \"subtotal\": 10,\n \"subtotalFormatted\": \"$10.00\",\n \"tax\": 0.2,\n \"taxFormatted\": \"$0.20\",\n \"grandTotal\": 10.2,\n \"grandTotalFormatted\": \"$10.20\",\n \"paid\": 22.34,\n \"paidFormatted\": \"$22.34\",\n \"due\": -12.14, // If negative, is the amount of change owed to the customer instead\n \"dueFormatted\": \"$12.14\"\n };\n },\n checkoutSavedMethod: async function ({customerID, paymentMethodID, amount}) {\n // Same as checkout() except using a payment method already on file.\n // customerID and paymentMethodID are provided by getSavedPaymentMethods below.\n await global.apis.util.delay(1000); // Replace this with something useful!\n var error = false;\n if (error) {\n // If you can't charge the payment method, throw an Error with a string to display to the user.\n throw new Error(\"The saved card didn't work.\");\n }\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n (amount / 100).toFixed(2) * 1,\n \"card\", // Payment type.\n \"Card on File\\nx1234\" // Additional text for receipt\n )\n );\n // Must return true upon success.\n // If the payment is not successful, and you didn't throw an Error to show the user,\n // then `return false` instead and it'll appear that the user's action to start the payment did nothing.\n return true;\n },\n saveCardForOfflineUse: async function ({statusCallback, customerUUID, name, company, street1, street2, city, state, zip, country, email, phone}) {\n // Use the card reader to capture an in-person card and save it for offline use.\n // Provided details are the customer's info, which might be empty strings except for the customerUUID.\n // Saved card details must be tied to the customerUUID, as that's how saved cards are looked up.\n\n // statusCallback(string, boolean) updates the progress message on the cashier's screen.\n // If the boolean is true, the progress message is replaced with a confirmation message.\n statusCallback(\"Insert the card into the reader.\", false);\n\n await global.apis.util.delay(1000); // Wait for the customer to insert their card,\n //then save it for later offline billing\n\n statusCallback(\"Saving card details...\", false);\n\n await global.apis.util.delay(1000);\n\n statusCallback(\"Card saved!\", true);\n\n return true; // Card saved to customer\n // If an error occurred, you can throw it and the error message will be displayed to the cashier.\n // Alternatively, return boolean false and display the error yourself with global.apis.alert(message, title) or something.\n },\n cancelSaveCardForOfflineUse: function () {\n // Cancel the process running in saveCardForOfflineUse() at the user/cashier's request.\n },\n getSavedPaymentMethods: async function ({customerUUID}) {\n // Return all saved payment methods tied to the provided customer UUID.\n var methods = [];\n methods.push({\n customer: \"<internal string referencing the customer>\", // Passed to checkoutSavedMethod as customerID\n customer_uuid: customerUUID,\n id: \"<card/payment method identifier>\", // Passed to checkoutSavedMethod as paymentMethodID\n type: \"card\", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free.\n label: \"Visa debit x1234 (exp. 12/29)\", // Label for payment method\n label_short: \"Visa debit x1234\" // Abbreviated label for payment method\n });\n return methods;\n },\n deleteSavedPaymentMethod: async function ({customerUUID, customerID, paymentMethodID}) {\n // Delete the payment method identified by paymentMethodID and tied to the PostalPoint customerUUID and the card processor customerID.\n // If unable to delete, throw an error and the error message will be displayed to the cashier.\n await global.apis.util.delay(1000);\n }\n });\n}\n\n// Plugin settings to display.\nexports.config = [\n {\n type: \"password\",\n key: \"democardprocessor_apikey\",\n defaultVal: \"\",\n label: \"API Key\",\n placeholder: \"\",\n text: \"API Key\"\n },\n {\n type: \"button\",\n label: \"Test Button\",\n text: \"Some text about the button\",\n onClick: function () {\n global.apis.ui.openSystemWebBrowser(\"https://postalpoint.app\");\n }\n }\n];\n</code></pre>"},{"location":"Examples/05CryptoProcessor/","title":"Cryptocurrency Payments","text":"<p>This plugin template shows how to implement a cryptocurrency payment processor, using the customer-facing display to show a payment QR code webpage.</p> <p>Download JavaScript</p> plugin-name/plugin.js<pre><code>// This is a sample PostalPoint plugin that adds a card payment processor.\n\nexports.init = function () {\n global.apis.pos.registerCryptoProcessor({\n name: \"Demo Crypto\",\n init: async function () {\n // This is run after PostalPoint starts, and before any other crypto functions are called.\n },\n checkout: async function ( {amount}) {\n // Run the checkout process.\n // amount is the amount of USD to collect, in pennies.\n\n // If an error is encountered during processing,\n // display an error message in a dialog and return boolean false.\n // If this function returns anything except false or undefined, and doesn't throw an error,\n // it is assumed the payment was successful.\n\n // Adds a line of text visible to the cashier\n global.apis.pos.addOnscreenPaymentLog(\"Getting crypto payment...\");\n\n // Display a web page (i.e. with a payment QR code) to the customer on the customer-facing display.\n global.apis.ui.setCustomerScreen(\"<html></html>\", \"html\");\n global.apis.ui.setCustomerScreen(\"https://postalpoint.app\", \"raw\");\n\n // Poll the status of the crypto transaction\n var paymentComplete = false;\n do {\n await global.apis.util.delay(1000);\n paymentComplete = true;\n } while (paymentComplete != true);\n\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n (amount / 100).toFixed(2) * 1,\n \"crypto\", // Payment type.\n \"Bitcoin\\n0.00001234 BTC\" // Additional text for receipt\n )\n );\n global.apis.pos.addOnscreenPaymentLog(\"Payment successful!\");\n global.apis.ui.clearCustomerScreen();\n },\n cancelCheckout: function () {\n // The user requested to cancel the payment.\n // Reset things accordingly.\n global.apis.ui.clearCustomerScreen();\n },\n isConfigured: function () {\n // Is this plugin properly setup and able to process payments? If not, return false.\n return true;\n }\n });\n}\n\n// Plugin settings to display.\nexports.config = [\n {\n type: \"password\",\n key: \"democryproprocessor_apikey\",\n defaultVal: \"\",\n label: \"API Key\",\n placeholder: \"\",\n text: \"API Key\"\n },\n {\n type: \"button\",\n label: \"Test Button\",\n text: \"Some text about the button\",\n onClick: function () {\n global.apis.ui.openSystemWebBrowser(\"https://postalpoint.app\");\n }\n }\n];\n</code></pre>"},{"location":"Plugin%20API/barcode/","title":"Barcode","text":""},{"location":"Plugin%20API/barcode/#barcode-object","title":"barcode : <code>object</code>","text":"<p>Handle tracking barcodes</p> <p>Kind: global namespace </p> <ul> <li>barcode : <code>object</code><ul> <li>.TrackingBarcode<ul> <li>new TrackingBarcode(code)</li> </ul> </li> <li>.addPrepaidBarcode(trackingBarcodeData)</li> <li>.inject(barcodeData)</li> <li>.onPrepaidScan(f)</li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/barcode/#barcodetrackingbarcode","title":"barcode.TrackingBarcode","text":"<p>Kind: static class of <code>barcode</code> Properties</p> Name Type Description tracking <code>string</code> Tracking number barcode <code>string</code> Original barcode data this was created from toZip <code>string</code> 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 <code>string</code> 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 <code>string</code> Destination mailing/shipping address. carrier <code>string</code> Shipping carrier name. service <code>string</code> Shipping service/mail class name. Example: \"Priority Mail\". dropoff <code>boolean</code> If set to false, the barcode will be rejected with a suitable message when PostalPoint is running in self-serve kiosk mode. confidentCarrier <code>boolean</code> If false, PostalPoint may prompt user to specify the shipping carrier. extraInfo <code>Array.<string></code> Extra description strings, like \"Signature Required\". message <code>string</code> If not empty, the barcode will NOT be added and the contents of <code>message</code> will be displayed to the user. warning <code>string</code> If not empty, the barcode WILL be added and the contents of <code>warning</code> will be displayed to the user. destString <code>string</code> (read only) Get the destination information as a human-presentable multiline string. serviceString <code>string</code> (read only) Get the carrier and service. toString() <code>function</code> Get the package information in a format suitable for display on a receipt. toString(false) <code>function</code> Get the package information in a format suitable for display on a receipt, suppressing the tracking number. <p></p>"},{"location":"Plugin%20API/barcode/#new-trackingbarcodecode","title":"new TrackingBarcode(code)","text":"<p>A Tracking barcode object.</p> Param Type Description code <code>string</code> Barcode data <p></p>"},{"location":"Plugin%20API/barcode/#barcodeaddprepaidbarcodetrackingbarcodedata","title":"barcode.addPrepaidBarcode(trackingBarcodeData)","text":"<p>Add a TrackingBarcode object to the transaction receipt at any time other than <code>onPrepaidScan</code>.</p> <p>Kind: static method of <code>barcode</code> </p> Param Type trackingBarcodeData <code>TrackingBarcode</code> <p></p>"},{"location":"Plugin%20API/barcode/#barcodeinjectbarcodedata","title":"barcode.inject(barcodeData)","text":"<p>Pass data to the internal barcode event subsystem. The data is handled as if it were just received from a physical barcode scanner.</p> <p>Kind: static method of <code>barcode</code> </p> Param Type barcodeData <code>string</code> <p></p>"},{"location":"Plugin%20API/barcode/#barcodeonprepaidscanf","title":"barcode.onPrepaidScan(f)","text":"<p>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.</p> <p>Kind: static method of <code>barcode</code> </p> Param Type f <code>function</code>"},{"location":"Plugin%20API/database/","title":"Database","text":""},{"location":"Plugin%20API/database/#database-object","title":"database : <code>object</code>","text":"<p>Database connection</p> <p>Kind: global namespace </p>"},{"location":"Plugin%20API/database/#databasegetconnection-promisedatabaseadapter","title":"database.getConnection() \u21d2 <code>Promise.<DatabaseAdapter></code>","text":"<p>Return a database connection object to run SQL against the store database. See the Database docs for details.</p> <p>Kind: static method of <code>database</code> </p>"},{"location":"Plugin%20API/fs/","title":"Fs","text":""},{"location":"Plugin%20API/fs/#fs-object","title":"fs : <code>object</code>","text":"<p>Basic filesystem access utility functions, wrapping Node.JS and/or NW.JS code.</p> <p>Kind: global namespace </p> <ul> <li>fs : <code>object</code><ul> <li>.openFileSaveDialog(suggestedFilename, fileExtensions) \u21d2 <code>Promise.<(string|null)></code></li> <li>.openFileBrowseDialog(chooseFolder, accept, dialogTitle) \u21d2 <code>string</code> | <code>null</code></li> <li>.writeFile(filename, data, encoding, flag) \u21d2 <code>Promise</code></li> <li>.readFile(filename, encoding, flag) \u21d2 <code>Promise.<(string|Buffer)></code></li> <li>.fileExists(filename) \u21d2 <code>boolean</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/fs/#fsopenfilesavedialogsuggestedfilename-fileextensions-promisestringnull","title":"fs.openFileSaveDialog(suggestedFilename, fileExtensions) \u21d2 <code>Promise.<(string|null)></code>","text":"<p>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.</p> <p>Kind: static method of <code>fs</code> Returns: <code>Promise.<(string|null)></code> - The full file path the user selected, or null if they cancelled. </p> Param Type Description suggestedFilename <code>string</code> The filename string to pre-fill in the dialog. fileExtensions <code>string</code> The file type filter to show. Examples: \".csv\", \".csv,.html\" <p></p>"},{"location":"Plugin%20API/fs/#fsopenfilebrowsedialogchoosefolder-accept-dialogtitle-string-null","title":"fs.openFileBrowseDialog(chooseFolder, accept, dialogTitle) \u21d2 <code>string</code> | <code>null</code>","text":"<p>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.</p> <p>Kind: static method of <code>fs</code> Returns: <code>string</code> | <code>null</code> - The selected file/folder path, or null if cancelled. </p> Param Type Default Description chooseFolder <code>boolean</code> <code>false</code> Set to true to choose a folder instead of a file. accept <code>string</code> File filter. \".csv,.html\", \"image/*\", etc. dialogTitle <code>string</code> | <code>null</code> <code>null</code> Title of the file open dialog. <p></p>"},{"location":"Plugin%20API/fs/#fswritefilefilename-data-encoding-flag-promise","title":"fs.writeFile(filename, data, encoding, flag) \u21d2 <code>Promise</code>","text":"<p>Write a file to disk.</p> <p>Kind: static method of <code>fs</code> </p> Param Type Default Description filename <code>string</code> The path and filename to write to. data <code>string</code> | <code>Buffer</code> | <code>ArrayBuffer</code> | <code>Uint8Array</code> Data to write to the file. encoding <code>string</code> | <code>null</code> <code>\"utf8\"</code> Text encoding. Set to empty if not passing string data. flag <code>string</code> | <code>null</code> <code>\"w+\"</code> Filesystem flag. <p></p>"},{"location":"Plugin%20API/fs/#fsreadfilefilename-encoding-flag-promisestringbuffer","title":"fs.readFile(filename, encoding, flag) \u21d2 <code>Promise.<(string|Buffer)></code>","text":"<p>Read a file from disk and return its contents.</p> <p>Kind: static method of <code>fs</code> </p> Param Type Default Description filename <code>string</code> The path and filename to read from. encoding <code>string</code> <code>\"utf8\"</code> File encoding. Set to null or empty string when reading binary data. flag <code>string</code> <code>\"r+\"</code> Filesystem flag. <p></p>"},{"location":"Plugin%20API/fs/#fsfileexistsfilename-boolean","title":"fs.fileExists(filename) \u21d2 <code>boolean</code>","text":"<p>Check if a file exists.</p> <p>Kind: static method of <code>fs</code> </p> Param Type Description filename <code>string</code> Path and filename to check."},{"location":"Plugin%20API/global%20functions/","title":"Global functions","text":""},{"location":"Plugin%20API/global%20functions/#f7","title":"f7","text":"<p>The Framework7 app instance for PostalPoint's entire UI, created by new Framework7(). See https://framework7.io/docs/app for details.</p> <p>Kind: global constant </p>"},{"location":"Plugin%20API/global%20functions/#getpluginfolderid-string","title":"getPluginFolder([id]) \u21d2 <code>string</code>","text":"<p>Get the filesystem path to a plugin's installation folder.</p> <p>Kind: global function Returns: <code>string</code> - \"/home/user/.config/postalpoint-retail/Default/storage/plugins/...\", \"C:\\Users\\user\\AppData...\", etc </p> Param Type Description [id] <code>string</code> Plugin ID. If omitted or empty, will return the parent folder plugins are installed within. <p></p>"},{"location":"Plugin%20API/global%20functions/#getappfolder-string","title":"getAppFolder() \u21d2 <code>string</code>","text":"<p>Get the filesystem path to the PostalPoint installation folder.</p> <p>Kind: global function </p>"},{"location":"Plugin%20API/global%20functions/#alerttext-title-callback","title":"alert(text, title, [callback])","text":"<p>Display a simple alert-style dialog box.</p> <p>Kind: global function </p> Param Type Default Description text <code>string</code> Body text of the dialog. title <code>string</code> Dialog title. [callback] <code>function</code> <code></code> Function to call when the alert is closed."},{"location":"Plugin%20API/graphics/","title":"Graphics","text":""},{"location":"Plugin%20API/graphics/#graphics-object","title":"graphics : <code>object</code>","text":"<p>PostalPoint uses the Jimp library version 1.6 for creating and manipulating images and shipping labels.</p> <p>Kind: global namespace </p> <ul> <li>graphics : <code>object</code><ul> <li>.Jimp() \u21d2 <code>Jimp</code></li> <li>.loadFont(filename) \u21d2 <code>Promise</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/graphics/#graphicsjimp-jimp","title":"graphics.Jimp() \u21d2 <code>Jimp</code>","text":"<p>The JavaScript Image Manipulation Program.</p> <p>Kind: static method of <code>graphics</code> Example <pre><code>const {Jimp} = global.apis.graphics.Jimp();\n</code></pre> </p>"},{"location":"Plugin%20API/graphics/#graphicsloadfontfilename-promise","title":"graphics.loadFont(filename) \u21d2 <code>Promise</code>","text":"<p>Replacement for Jimp's loadFont function, which gets very confused about our JS environment and ends up crashing everything.</p> <p>Kind: static method of <code>graphics</code> </p> Param Type filename <code>string</code>"},{"location":"Plugin%20API/httpserver/","title":"Httpserver","text":""},{"location":"Plugin%20API/httpserver/#httpserver-object","title":"httpserver : <code>object</code>","text":"<p>Add features to PostalPoint's integrated LAN HTTP API server.</p> <p>Kind: global namespace </p> <ul> <li>httpserver : <code>object</code><ul> <li>.addEndpoint(id, onCall)</li> <li>.getServerPort() \u21d2 <code>number</code></li> <li>.getClientKey() \u21d2 <code>string</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/httpserver/#httpserveraddendpointid-oncall","title":"httpserver.addEndpoint(id, onCall)","text":"<p>Add a custom HTTP JSON POST endpoint to the LAN HTTP API server running inside PostalPoint. Requests must be POSTed and contain a JSON body (or empty body, which will be converted to <code>null</code>).</p> <p>Kind: static method of <code>httpserver</code> </p> Param Type Description id <code>string</code> Endpoint ID. Used in URL, for example: <code>http://<host>:7678/<id></code> onCall <code>function</code> Async function to call when the endpoint is called, which returns the response. <p>Example <pre><code>global.apis.httpserver.addEndpoint(\"testendpoint\", async function (request) {\n if (request.abc == \"123\") {\n // A non-string `body` is converted to JSON before the HTTP reply is sent.\n return {body: {json: true, abc: 123}, httpcode: 200, contentType: \"application/json\"};\n }\n // A string `body` is sent to the client as-is using whatever contentType you specify.\n return {body: \"abc\", httpcode: 200, contentType: \"text/plain\"};\n});\n</code></pre> </p>"},{"location":"Plugin%20API/httpserver/#httpservergetserverport-number","title":"httpserver.getServerPort() \u21d2 <code>number</code>","text":"<p>Get the local HTTP server's port number.</p> <p>Kind: static method of <code>httpserver</code> </p>"},{"location":"Plugin%20API/httpserver/#httpservergetclientkey-string","title":"httpserver.getClientKey() \u21d2 <code>string</code>","text":"<p>Get the local machine's HTTP client key it uses to authenticate with other installations of PostalPoint on the LAN.</p> <p>Kind: static method of <code>httpserver</code> </p>"},{"location":"Plugin%20API/i18n/","title":"I18n","text":""},{"location":"Plugin%20API/i18n/#i18n-object","title":"i18n : <code>object</code>","text":"<p>Functions to help support multiple currencies and countries.</p> <p>Kind: global namespace </p> <ul> <li>i18n : <code>object</code><ul> <li>.country() \u21d2 <code>string</code></li> <li>.currency() \u21d2 <code>string</code></li> <li>.symbol() \u21d2 <code>string</code></li> <li>.decimals() \u21d2 <code>number</code></li> <li>.convertCurrency(amount, fromCurrency, [toCurrency]) \u21d2 <code>Promise.<number></code></li> <li>.moneyToFixed(amount) \u21d2 <code>string</code></li> <li>.moneyString(amount) \u21d2 <code>string</code></li> <li>.currencyMinorToMajor(amount) \u21d2 <code>number</code></li> <li>.currencyMajorToMinor(amount) \u21d2 <code>number</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/i18n/#i18ncountry-string","title":"i18n.country() \u21d2 <code>string</code>","text":"<p>Get the 2-character ISO country code that PostalPoint is running in.</p> <p>Kind: static method of <code>i18n</code> Returns: <code>string</code> - \"US\", \"CA\", etc. </p>"},{"location":"Plugin%20API/i18n/#i18ncurrency-string","title":"i18n.currency() \u21d2 <code>string</code>","text":"<p>Get the 3-character currency code in use.</p> <p>Kind: static method of <code>i18n</code> Returns: <code>string</code> - \"usd\", \"cad\", etc. </p>"},{"location":"Plugin%20API/i18n/#i18nsymbol-string","title":"i18n.symbol() \u21d2 <code>string</code>","text":"<p>Get the currency symbol.</p> <p>Kind: static method of <code>i18n</code> Returns: <code>string</code> - \"$\", \"\u20ac\", \"\u20a4\", etc </p>"},{"location":"Plugin%20API/i18n/#i18ndecimals-number","title":"i18n.decimals() \u21d2 <code>number</code>","text":"<p>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).</p> <p>Kind: static method of <code>i18n</code> Returns: <code>number</code> - 0, 2, 3, or 4 </p>"},{"location":"Plugin%20API/i18n/#i18nconvertcurrencyamount-fromcurrency-tocurrency-promisenumber","title":"i18n.convertCurrency(amount, fromCurrency, [toCurrency]) \u21d2 <code>Promise.<number></code>","text":"<p>Convert an amount of money to a different currency. Conversion rate is retrieved from the internet and cached for 4 hours.</p> <p>Kind: static method of <code>i18n</code> </p> Param Type Default Description amount <code>number</code> Amount of money in the \"wrong\" currency fromCurrency <code>string</code> The currency code for the \"wrong\" currency that needs conversion [toCurrency] <code>string</code> <code>\"getCurrencyCode()\"</code> The \"correct\" currency we want the amount to be in. <p></p>"},{"location":"Plugin%20API/i18n/#i18nmoneytofixedamount-string","title":"i18n.moneyToFixed(amount) \u21d2 <code>string</code>","text":"<p>Returns the amount as a string formatted with the correct number of decimal places for the currency in use.</p> <p>Kind: static method of <code>i18n</code> Returns: <code>string</code> - \"1.23\", \"1.2345\", etc </p> Param Type amount <code>number</code> <p></p>"},{"location":"Plugin%20API/i18n/#i18nmoneystringamount-string","title":"i18n.moneyString(amount) \u21d2 <code>string</code>","text":"<p>Returns the amount as a string, with the correct decimal places, and the local currency symbol.</p> <p>Kind: static method of <code>i18n</code> Returns: <code>string</code> - \"$1.23\", etc </p> Param Type amount <code>number</code> <p></p>"},{"location":"Plugin%20API/i18n/#i18ncurrencyminortomajoramount-number","title":"i18n.currencyMinorToMajor(amount) \u21d2 <code>number</code>","text":"<p>Convert an amount in cents to dollars (or the local equivalent currency units).</p> <p>Kind: static method of <code>i18n</code> Returns: <code>number</code> - Dollars, etc </p> Param Type Description amount <code>number</code> Cents, etc <p></p>"},{"location":"Plugin%20API/i18n/#i18ncurrencymajortominoramount-number","title":"i18n.currencyMajorToMinor(amount) \u21d2 <code>number</code>","text":"<p>Convert an amount in dollars to cents (or the local equivalent currency units).</p> <p>Kind: static method of <code>i18n</code> Returns: <code>number</code> - Cents, etc </p> Param Type Description amount <code>number</code> Dollars, etc"},{"location":"Plugin%20API/kiosk/","title":"Kiosk","text":""},{"location":"Plugin%20API/kiosk/#kiosk-object","title":"kiosk : <code>object</code>","text":"<p>Self-serve kiosk mode</p> <p>Kind: global namespace </p>"},{"location":"Plugin%20API/kiosk/#kioskiskiosk-boolean","title":"kiosk.isKiosk() \u21d2 <code>boolean</code>","text":"<p>Check if PostalPoint is running in kiosk mode.</p> <p>Kind: static method of <code>kiosk</code> Returns: <code>boolean</code> - - True if system is in kiosk mode, else false. </p>"},{"location":"Plugin%20API/mailboxes/","title":"Mailboxes","text":""},{"location":"Plugin%20API/mailboxes/#mailboxes-object","title":"mailboxes : <code>object</code>","text":"<p>Add, modify, and delete mailboxes and mailbox customers.</p> <p>Kind: global namespace </p> <ul> <li>mailboxes : <code>object</code><ul> <li>.FormPS1583<ul> <li>new FormPS1583()</li> </ul> </li> <li>.getList(filter) \u21d2 <code>Promise.<Array></code></li> <li>.addDaysToMailbox(boxNumber, days, months) \u21d2 <code>Promise</code></li> <li>.setMailboxExpirationDate(boxNumber, date) \u21d2 <code>Promise</code></li> <li>.createMailbox(number, size, notes, barcode) \u21d2 <code>Promise</code></li> <li>.editMailbox(oldNumber, newNumber, newSize, barcode) \u21d2 <code>Promise</code></li> <li>.deleteMailbox(number) \u21d2 <code>Promise</code></li> <li>.closeMailbox(number) \u21d2 <code>Promise</code></li> <li>.mailboxExists(number) \u21d2 <code>Promise.<boolean></code></li> <li>.addOrUpdateBoxholder(boxNumber, info) \u21d2 <code>Promise</code></li> <li>.removeBoxholder(boxNumber, uuid) \u21d2 <code>Promise</code></li> <li>.get1583(boxNumber, uuid, archiveNumber) \u21d2 <code>Promise.<FormPS1583></code></li> <li>.set1583(boxNumber, uuid, formps1583) \u21d2 <code>Promise</code></li> <li>.boxNumberValid() \u21d2 <code>boolean</code></li> <li>.getMailboxProducts() \u21d2 <code>Promise.<Array></code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesformps1583","title":"mailboxes.FormPS1583","text":"<p>Kind: static class of <code>mailboxes</code> </p>"},{"location":"Plugin%20API/mailboxes/#new-formps1583","title":"new FormPS1583()","text":"<p>USPS Form PS1583 object, with all the fields needed by USPS for CMRA customers.</p> <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesgetlistfilter-promisearray","title":"mailboxes.getList(filter) \u21d2 <code>Promise.<Array></code>","text":"<p>Get the list of mailboxes and boxholders as an array of objects, see example.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Default Description filter <code>null</code> | <code>object</code> <code></code> Filter to mailboxes matching a column condition, such as <code>getList({number: \"102\"})</code> or <code>getList({\"size >=\": \"2\"})</code>. 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. <p>Example <pre><code>[{\n num: \"123\", // Box number as string\n expires: 1234567890, // UNIX timestamp (in seconds) or false if box vacant\n size: \"2\", // Box size, 1-10\n notes: \"\", // Notes for mailbox, not currently shown in Mailbox Manager UI but may be used in the future\n barcode: \"\", // Unique barcode for the mailbox, for future use\n renewalMerchID: \"\", // Merchandise item ID used for autorenewing this mailbox\n isBusiness: false, // True if the box is for a business, false if for personal use\n names: [], // Array of boxholders. See addOrUpdateBoxholder for the format.\n packages: [], // Array of packages awaiting pickup, see below\n vacant: false // True if the box is currently vacant, else false\n}]\n</code></pre> Example <pre><code>// Data objects in the packages array:\n{\n tracking: tracking ?? \"[Untracked]\", // Package tracking number\n finalized: true, // True if package check-in is finished and shelf tag/mailbox slips printed, false if not finalized\n available_date: Date(), // The date and time the package was checked in\n tag: \"\" // Unique number assigned to the package and printed on shelf tags, scanned by employee when customer picks up package\n}\n</code></pre> </p>"},{"location":"Plugin%20API/mailboxes/#mailboxesadddaystomailboxboxnumber-days-months-promise","title":"mailboxes.addDaysToMailbox(boxNumber, days, months) \u21d2 <code>Promise</code>","text":"<p>Add a number of days or months to a mailbox's expiration. Use either days or months, not both.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Default Description boxNumber <code>string</code> Mailbox number. days <code>number</code> <code>0</code> Days to add. months <code>number</code> <code>0</code> Months to add. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxessetmailboxexpirationdateboxnumber-date-promise","title":"mailboxes.setMailboxExpirationDate(boxNumber, date) \u21d2 <code>Promise</code>","text":"<p>Set the box expiration to a specific JavaScript Date object, or a UNIX timestamp (in seconds).</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type boxNumber <code>string</code> date <code>number</code> | <code>Date</code> <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxescreatemailboxnumber-size-notes-barcode-promise","title":"mailboxes.createMailbox(number, size, notes, barcode) \u21d2 <code>Promise</code>","text":"<p>Create a new mailbox number with the specified box size. Throws an error if the box number is already in use.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description number <code>string</code> Mailbox number size <code>number</code> Box size (1 - 10) notes <code>string</code> Arbitrary string with human-readable notes about the box. barcode <code>null</code> | <code>string</code> A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxeseditmailboxoldnumber-newnumber-newsize-barcode-promise","title":"mailboxes.editMailbox(oldNumber, newNumber, newSize, barcode) \u21d2 <code>Promise</code>","text":"<p>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.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Default Description oldNumber <code>string</code> Currently assigned box number. newNumber <code>string</code> New box number. Must not exist yet. newSize <code>number</code> | <code>null</code> <code></code> Box size (1 - 10), if changing the size. barcode <code>null</code> | <code>string</code> A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesdeletemailboxnumber-promise","title":"mailboxes.deleteMailbox(number) \u21d2 <code>Promise</code>","text":"<p>Delete a mailbox. Throws an Error if the mailbox has boxholders attached.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description number <code>string</code> Mailbox number to delete. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesclosemailboxnumber-promise","title":"mailboxes.closeMailbox(number) \u21d2 <code>Promise</code>","text":"<p>Close a mailbox by removing the boxholders and marking it as vacant. Boxholder PS Form 1583 records are automatically archived per USPS regulations.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description number <code>string</code> Mailbox number to close. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesmailboxexistsnumber-promiseboolean","title":"mailboxes.mailboxExists(number) \u21d2 <code>Promise.<boolean></code>","text":"<p>Returns true if the mailbox number exists, false if it doesn't.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description number <code>string</code> Mailbox number to check. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesaddorupdateboxholderboxnumber-info-promise","title":"mailboxes.addOrUpdateBoxholder(boxNumber, info) \u21d2 <code>Promise</code>","text":"<p>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.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description boxNumber <code>string</code> Mailbox number info <code>Object</code> Boxholder information. <p>Example <pre><code>// Unless noted, all fields are strings and default to an empty string.\n{\n name: [bizname, fname, mname, lname].filter(Boolean).join(\" \"),\n fname: \"\", // First name\n mname: \"\", // Middle name\n lname: \"\", // Last name\n email: \"\", // Email\n phone: \"\", // Phone\n uuid: \"\", // Customer UUID\n bizname: \"\", // Business name\n street1: \"\", // Street address\n city: \"\", // City\n state: \"\", // Two-character state\n zipcode: \"\", // ZIP or postal code\n country: \"\", // Two-character country code\n primary: true // True if the primary (first) boxholder, false if an additional authorized mail recipient\n}\n</code></pre> </p>"},{"location":"Plugin%20API/mailboxes/#mailboxesremoveboxholderboxnumber-uuid-promise","title":"mailboxes.removeBoxholder(boxNumber, uuid) \u21d2 <code>Promise</code>","text":"<p>Remove a boxholder by their UUID, and archive their PS Form 1583 data per USPS regulations.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description boxNumber <code>string</code> Mailbox number. uuid <code>string</code> Boxholder UUID. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesget1583boxnumber-uuid-archivenumber-promiseformps1583","title":"mailboxes.get1583(boxNumber, uuid, archiveNumber) \u21d2 <code>Promise.<FormPS1583></code>","text":"<p>Get the FormPS1583 object for a boxholder by UUID.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Default Description boxNumber <code>string</code> Mailbox number. uuid <code>string</code> Boxholder UUID. archiveNumber <code>boolean</code> <code>false</code> If true, returns the form for a deleted boxholder from the archive. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesset1583boxnumber-uuid-formps1583-promise","title":"mailboxes.set1583(boxNumber, uuid, formps1583) \u21d2 <code>Promise</code>","text":"<p>Set the FormPS1583 object for a boxholder by UUID.</p> <p>Kind: static method of <code>mailboxes</code> </p> Param Type Description boxNumber <code>string</code> Mailbox number. uuid <code>string</code> Boxholder UUID. formps1583 <code>FormPS1583</code> The FormPS1583 object to use. <p></p>"},{"location":"Plugin%20API/mailboxes/#mailboxesboxnumbervalid-boolean","title":"mailboxes.boxNumberValid() \u21d2 <code>boolean</code>","text":"<p>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.</p> <p>Kind: static method of <code>mailboxes</code> </p>"},{"location":"Plugin%20API/mailboxes/#mailboxesgetmailboxproducts-promisearray","title":"mailboxes.getMailboxProducts() \u21d2 <code>Promise.<Array></code>","text":"<p>Get a list of merchandise items that are usable for mailbox renewals.</p> <p>Kind: static method of <code>mailboxes</code> Example <pre><code>[{\n id: \"\", // Unique ID for this entry in the merchandise table\n name: \"\", // Merch item name\n category: \"\", // Merch item category\n price: 0.0, // Sale price in dollars\n cost: 0.0, // Merchandise cost in dollars (likely not used for mailboxes)\n barcode: \"\", // Barcode/UPC (likely not used for mailboxes)\n tax: 0.0, // Sales tax rate\n rentaldays: 30, // Number of days this item adds to a mailbox (mutually exclusive with rentalmonths)\n rentalmonths: 1, // Number of months (mutually exclusive with rentaldays)\n boxsize: \"1\" // Mailbox size tier, 1-10\n}]\n</code></pre></p>"},{"location":"Plugin%20API/pos/","title":"Pos","text":""},{"location":"Plugin%20API/pos/#pos-object","title":"pos : <code>object</code>","text":"<p>Point of Sale, transaction, and payment-related functionality.</p> <p>Kind: global namespace </p> <ul> <li>pos : <code>object</code><ul> <li>.ReceiptItem<ul> <li>new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)</li> </ul> </li> <li>.ReceiptPayment<ul> <li>new ReceiptPayment(amount, type, text)</li> </ul> </li> <li>.addReceiptItem(item)</li> <li>.addReceiptPayment(payment)</li> <li>.addOnscreenPaymentLog(msg)</li> <li>.getReceiptID() \u21d2 <code>string</code></li> <li>.onReceiptChange(f)</li> <li>~~.onTransactionFinished(f)~~</li> <li>.registerCardProcessor(f)</li> <li>.registerCryptoProcessor(f)</li> <li>.getShippingSalesTax() \u21d2 <code>Object</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/pos/#posreceiptitem","title":"pos.ReceiptItem","text":"<p>Kind: static class of <code>pos</code> Properties</p> Name Type Default Description merch <code>boolean</code> <code>false</code> True if merchandise, false if shipping. barcode <code>string</code> Item barcode, or tracking number if <code>merch = false</code>. qty <code>number</code> <code>1</code> Item quantity. retailPrice <code>number</code> The calculated retail/markup price for a shipment, regardless of actual sale price. If unset, defaults to priceEach * qty. taxRate <code>number</code> <code>0</code> Tax rate toAddress <code>Address</code> Shipping destination address. fromAddress <code>Address</code> Shipping return address. carrier <code>string</code> Shipping carrier. service <code>string</code> Shipping service. category <code>string</code> Merchandise/item category. electronicReturnReceipt <code>boolean</code> <code>false</code> If true, the customer's receipt will have instructions on retrieveing the return receipt from USPS. mailboxDays <code>number</code> <code>0</code> Number of days this item adds to a mailbox's expiration date. mailboxMonths <code>number</code> <code>0</code> Number of months this item adds to a mailbox's expiration date. mailboxNumber <code>string</code> Mailbox number to apply <code>mailboxDays</code> or <code>mailboxMonths</code> to after checkout. setCertifiedInfo() <code>function</code> Set Certified Mail receipt data. <code>setCertifiedInfo(trackingNumber, certfee, extrafees, postage, date, location, toaddress)</code> toJSON() <code>function</code> Get the item as an object suitable for JSON encoding. fromJSON(json) <code>static_function</code> Returns a ReceiptItem created from the object returned by <code>item.toJSON()</code>. <p></p>"},{"location":"Plugin%20API/pos/#new-receiptitemid-label-text-priceeach-quantity-cost-taxrate-taxableamount","title":"new ReceiptItem(id, label, text, priceEach, quantity, cost, taxrate, taxableAmount)","text":"<p>A class representing a sale item in the current transaction.</p> Param Type Default Description id <code>string</code> 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 <code>string</code> One-line item information. text <code>string</code> Extra multi-line item information. priceEach <code>number</code> Sale price per unit. quantity <code>number</code> Number of units. cost <code>number</code> Cost per unit. Used for automatic expense tracking. taxrate <code>number</code> <code>0.0</code> Examples: 0 (for 0%), 0.05 (for 5%), etc taxableAmount <code>string</code> The part of the sale price that's taxable. \"\" for default (all), \"markup\" for only taxing profit. <p></p>"},{"location":"Plugin%20API/pos/#posreceiptpayment","title":"pos.ReceiptPayment","text":"<p>Kind: static class of <code>pos</code> Properties</p> Name Type Description label <code>string</code> (readonly) The human-readable string of the payment type. id <code>string</code> Automatically-generated unique ID for this payment. toJSON() <code>function</code> Get the payment as an object suitable for JSON encoding. fromJSON(json) <code>static_function</code> Returns a ReceiptPayment created from the object returned by <code>payment.toJSON()</code>. <p></p>"},{"location":"Plugin%20API/pos/#new-receiptpaymentamount-type-text","title":"new ReceiptPayment(amount, type, text)","text":"<p>A class representing a payment entry for the current transaction.</p> Param Type Description amount <code>number</code> amount paid type <code>string</code> payment type text <code>string</code> extra data (credit card info, etc) <p></p>"},{"location":"Plugin%20API/pos/#posaddreceiptitemitem","title":"pos.addReceiptItem(item)","text":"<p>Add an item (shipment, merchandise, etc) to the current transaction.</p> <p>Kind: static method of <code>pos</code> </p> Param Type item <code>ReceiptItem</code> <p></p>"},{"location":"Plugin%20API/pos/#posaddreceiptpaymentpayment","title":"pos.addReceiptPayment(payment)","text":"<p>Add a payment to the current transaction/receipt.</p> <p>Kind: static method of <code>pos</code> </p> Param Type payment <code>ReceiptPayment</code> <p></p>"},{"location":"Plugin%20API/pos/#posaddonscreenpaymentlogmsg","title":"pos.addOnscreenPaymentLog(msg)","text":"<p>Append a line of text to the onscreen log displayed during credit card processing. Not shown in kiosk mode.</p> <p>Kind: static method of <code>pos</code> </p> Param Type Description msg <code>string</code> Line of text to add to the log. <p></p>"},{"location":"Plugin%20API/pos/#posgetreceiptid-string","title":"pos.getReceiptID() \u21d2 <code>string</code>","text":"<p>Get the unique alphanumeric ID for the current transaction/receipt. This is the same code printed on receipts and used in digital receipt URLs.</p> <p>Kind: static method of <code>pos</code> </p>"},{"location":"Plugin%20API/pos/#posonreceiptchangef","title":"pos.onReceiptChange(f)","text":"<p>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.</p> <p>Kind: static method of <code>pos</code> </p> Param Type f <code>function</code> <p></p>"},{"location":"Plugin%20API/pos/#posontransactionfinishedf","title":"~~pos.onTransactionFinished(f)~~","text":"<p>Deprecated</p> <p>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 <code>transactionFinished</code> event instead.</p> <p>Kind: static method of <code>pos</code> </p> Param Type f <code>function</code> <p></p>"},{"location":"Plugin%20API/pos/#posregistercardprocessorf","title":"pos.registerCardProcessor(f)","text":"<p>Register as a card payment processor.</p> <p>Kind: static method of <code>pos</code> </p> Param Type Description f <code>Object</code> Payment processor functions <p>Example <pre><code>global.apis.pos.registerCardProcessor({\n name: \"Demo Card Processor\", // Shown in PostalPoint settings menu\n init: async function () {\n // This will run after PostalPoint launches\n // and before any payments are processed.\n // In some situations it might run multiple times in a session.\n },\n checkout: async function ({amount, capture = true}) {\n // Charge a credit card using a card reader device.\n // amount is in pennies (or the equivalent base unit in the local currency).\n\n // Add a payment to the receipt with the total amount paid, card details, etc.\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n global.apis.i18n.currencyMinorToMajor(amount),\n \"card\", // Payment type. Accepted values are card, ach, crypto, cash,\n // check, account, and free. Other types will be displayed as-is.\n \"Demo Card\\nCardholder Name, etc\\nMore info for receipt\" // Additional text for receipt\n )\n );\n\n\n // Must return boolean false if the payment failed.\n // Otherwise it will be assumed it succeeded.\n // If an error is encountered, handle it and return false.\n // It's recommended to display a short \"payment failed\" error\n // message via global.apis.alert, and outputting more details\n // via global.apis.pos.addOnscreenPaymentLog.\n\n // If capture is false, perform an authorization but don't capture,\n // and return a value you can use to identify the authorization later\n // and complete it. The value will be passed back to finishPayment, below.\n // This is used mainly for the self-serve kiosk mode, in case the label fails\n // to be purchased/generated by the carrier.\n },\n cancelCheckout: function () {\n // The user has requested the card transaction be canceled before it completes.\n // Reset the terminal to its resting state, clear its screen, etc.\n },\n finishPayment: async function ({checkoutResponse}) {\n // Finish a payment that was authorized but not captured\n // because checkout() was called with capture = false.\n // If payment was already captured and added\n // to the receipt, just return true.\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n global.apis.i18n.currencyMinorToMajor(amount),\n \"card\",\n \"Demo Card\\nCardholder Name, etc\\nMore info for receipt\"\n )\n );\n },\n updateCartDisplay: function (receipt) {\n // Show transaction data on the card reader display.\n // This function is called when the \"cart\" or total changes.\n // `receipt` is a receipt object, see docs for details.\n },\n checkoutSavedMethod: async function ({customerID, paymentMethodID, amount}) {\n // Same as checkout() except using a payment method already on file.\n // customerID and paymentMethodID are provided by getSavedPaymentMethods below.\n\n // Must return true upon success.\n // If the payment is not successful, and you didn't throw an Error to show the user,\n // then `return false` instead and it'll appear that the user's action to start the payment did nothing.\n return true;\n },\n saveCardForOfflineUse: async function ({statusCallback, customerUUID, name,\n company, street1, street2, city, state, zip, country, email, phone}) {\n // Use the card reader to capture an in-person card and save it for offline use.\n // Provided details are the customer's info, which might be empty strings except for the customerUUID.\n // Saved card details must be tied to the customerUUID, as that's how saved cards are looked up.\n\n // statusCallback(string, boolean) updates the progress message on the cashier's screen.\n // If the boolean is true, the progress message is replaced with a confirmation message.\n statusCallback(\"Saving card details...\", false);\n\n return true; // Card saved to customer\n // If an error occurred, you can throw it and the error\n // message will be displayed to the cashier.\n // Alternatively, return boolean false and display the error\n // yourself with global.apis.alert(message, title) or something.\n },\n cancelSaveCardForOfflineUse: function () {\n // Cancel the process running in saveCardForOfflineUse() at the user/cashier's request.\n },\n getSavedPaymentMethods: async function ({customerUUID}) {\n // Return all saved payment methods tied to the provided customer UUID.\n return [{\n customer: \"<internal string referencing the customer>\", // Passed to checkoutSavedMethod as customerID\n customer_uuid: customerUUID,\n id: \"<card/payment method identifier>\", // Passed to checkoutSavedMethod as paymentMethodID\n type: \"card\", // Payment type. Accepted values are card, ach, crypto, cash, check, account, and free.\n label: \"Visa debit x1234 (exp. 12/29)\", // Label for payment method\n label_short: \"Visa debit x1234\" // Abbreviated label for payment method\n }];\n },\n deleteSavedPaymentMethod: async function ({customerUUID, customerID, paymentMethodID}) {\n // Delete the payment method identified by paymentMethodID\n // and tied to the PostalPoint customerUUID and the card processor customerID.\n // If unable to delete, throw an error and the error message\n // will be displayed to the cashier.\n }\n});\n</code></pre> </p>"},{"location":"Plugin%20API/pos/#posregistercryptoprocessorf","title":"pos.registerCryptoProcessor(f)","text":"<p>Register as a cryptocurrency payment processor.</p> <p>Kind: static method of <code>pos</code> </p> Param Type Description f <code>Object</code> Payment processor functions <p>Example <pre><code>global.apis.pos.registerCryptoProcessor({\n name: \"Demo Crypto\", // Shown in PostalPoint settings menu\n init: async function () {\n // This is run after PostalPoint starts,\n // and before any other crypto functions are called.\n },\n checkout: async function ({amount}) {\n // Run the checkout process.\n // amount is the amount of fiat currency to collect,\n // in pennies (or the local equivalent).\n\n // If an error is encountered during processing,\n // display an error message in a dialog and return boolean false.\n // If this function returns anything except false or undefined,\n // and doesn't throw an error,\n // it is assumed the payment was successful.\n\n // Adds a line of text visible to the cashier\n global.apis.pos.addOnscreenPaymentLog(\"Getting crypto payment...\");\n\n // Display a web page (i.e. with a payment QR code)\n // to the customer on the customer-facing display.\n global.apis.ui.setCustomerScreen(\"<html></html>\", \"html\");\n global.apis.ui.setCustomerScreen(\"https://postalpoint.app\", \"raw\");\n\n // Poll the status of the crypto transaction\n var paymentComplete = false;\n do {\n await global.apis.util.delay(1000);\n paymentComplete = true;\n } while (paymentComplete != true);\n\n global.apis.pos.addReceiptPayment(\n new global.apis.pos.ReceiptPayment(\n global.apis.i18n.currencyMinorToMajor(amount),\n \"crypto\", // Payment type.\n \"Bitcoin\\n0.00001234 BTC\" // Additional text for receipt\n )\n );\n global.apis.pos.addOnscreenPaymentLog(\"Payment successful!\");\n global.apis.ui.clearCustomerScreen();\n },\n cancelCheckout: function () {\n // The user requested to cancel the payment.\n // Reset things accordingly.\n global.apis.ui.clearCustomerScreen();\n },\n isConfigured: function () {\n // Is this plugin properly setup\n // and able to process payments?\n // If not, return false.\n // This determines if the crypto payment method button will be shown.\n return true;\n }\n});\n</code></pre> </p>"},{"location":"Plugin%20API/pos/#posgetshippingsalestax-object","title":"pos.getShippingSalesTax() \u21d2 <code>Object</code>","text":"<p>Get the sales tax percentage to charge on a shipping service ReceiptItem.</p> <p>Kind: static method of <code>pos</code> Returns: <code>Object</code> - <code>{type: \"\", percent: 0.15}</code> <code>type</code> is an empty string for taxing the entire price, or \"markup\" for only adding tax to the markup amount. <code>percent</code> is the tax percentage. A value of 0.15 means a 15% tax. </p>"},{"location":"Plugin%20API/print/","title":"Print","text":""},{"location":"Plugin%20API/print/#print-object","title":"print : <code>object</code>","text":"<p>Printing to connected printers</p> <p>Kind: global namespace </p> <ul> <li>print : <code>object</code><ul> <li>.printLabelImage(image)</li> <li>.getReceiptPrinter() \u21d2 <code>Promise.<Object></code></li> <li>.printReceiptData(data)</li> <li>.imageToBitmap(jimpImage, [dpiFrom], [dpiTo]) \u21d2 <code>Object</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/print/#printprintlabelimageimage","title":"print.printLabelImage(image)","text":"<p>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.</p> <p>Kind: static method of <code>print</code> </p> Param Type Description image <code>ArrayBuffer</code> | <code>Buffer</code> | <code>Uint8Array</code> | <code>string</code> | <code>Jimp</code> 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. <p></p>"},{"location":"Plugin%20API/print/#printgetreceiptprinter-promiseobject","title":"print.getReceiptPrinter() \u21d2 <code>Promise.<Object></code>","text":"<p>Get the receipt printer interface. See the ReceiptPrinter docs for available functions.</p> <p>Kind: static method of <code>print</code> </p>"},{"location":"Plugin%20API/print/#printprintreceiptdatadata","title":"print.printReceiptData(data)","text":"<p>Send raw data (generated by the printer interface) to the receipt printer.</p> <p>Kind: static method of <code>print</code> </p> Param Type Description data <code>string</code> | <code>Uint8Array</code> | <code>Array.<string></code> | <code>Array.<Uint8Array></code> Data to send to printer. <p></p>"},{"location":"Plugin%20API/print/#printimagetobitmapjimpimage-dpifrom-dpito-object","title":"print.imageToBitmap(jimpImage, [dpiFrom], [dpiTo]) \u21d2 <code>Object</code>","text":"<p>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.</p> <p>Kind: static method of <code>print</code> Returns: <code>Object</code> - - Example: <code>{width: 300, height: 200, img: Uint8Array}</code>. Pass <code>img</code> to <code>drawImage</code> on a printer interface. </p> Param Type Default Description jimpImage <code>Jimp</code> [dpiFrom] <code>number</code> <code>300</code> Original image DPI. [dpiTo] <code>number</code> <code>300</code> New image DPI."},{"location":"Plugin%20API/reports/","title":"Reports","text":""},{"location":"Plugin%20API/reports/#reports-object","title":"reports : <code>object</code>","text":"<p>Define custom reports for the user.</p> <p>Kind: global namespace </p>"},{"location":"Plugin%20API/reports/#reportsregisterreportname-onloadstartdateenddate-date","title":"reports.registerReport(name, onload(startDate,endDate), date)","text":"<p>Kind: static method of <code>reports</code> </p> Param Type Description name <code>string</code> Report name onload(startDate,endDate) <code>function</code> Called when the report is loaded, with start and end Date objects. See example. date <code>boolean</code> If the report requires a date range be selected. <p>Example <pre><code>global.apis.reports.registerReport(\"sample\", function (startDate, endDate) {\n\n // Note about column datatypes:\n // Use \"string\" for the datatype, except for the special cases listed here.\n // Other datatypes may be added in the future, so use \"string\"\n // unless you like unexpected behavior!\n //\n // datetime: Column is a UNIX timestamp (in seconds).\n // It is displayed as a formatted date and time string.\n // receiptid: Column is a PostalPoint receipt ID number. Displayed as a link.\n // Clicking the ID will fetch and open the receipt in a popup.\n // userid: Column contains an employee ID number from the PostalPoint database.\n // It is queried in the database and replaced with the employee's name,\n // or with an empty string if the ID lookup has no results.\n // money: Column is a number that will be formatted as currency for display.\n // percent: Column is a percent value (as 12.3, not .123) and will be formatted\n // with a trailing % sign and rounded to two decimal places.\n\n // Single-table report\n return {\n table: {\n header: [\"Column 1\", \"Column 2\"],\n datatypes: [\"string\", \"string\"],\n rows: [\n [\"Row 1 Col 1\", \"Row 1 Col 2\"],\n [\"Row 2 Col 1\", \"Row 2 Col 2\"]\n ]\n }\n };\n\n // Multiple-table report\n return {\n multitable: true,\n table: {\n titles: [\"Report 1 Title\", \"Report 2 Title\"],\n header: [[\"Report 1 Column 1\", \"Report 1 Column 2\"], [\"Report 2 Column 1\", ...]],\n datatypes: [[\"string\", \"string\"], [\"string\", \"string\"]],\n rows: [\n [\n [\"Report 1 Row 1 Col 1\", \"Report 1 Row 1 Col 2\"],\n [\"Report 1 Row 2 Col 1\", \"Report 1 Row 2 Col 2\"]\n ],\n [\n [\"Report 2 Row 1 Col 1\", \"Report 2 Row 1 Col 2\"],\n [\"Report 2 Row 2 Col 1\", \"Report 2 Row 2 Col 2\"]\n ]\n ]\n }\n }\n}, true);\n</code></pre></p>"},{"location":"Plugin%20API/settings/","title":"Settings","text":""},{"location":"Plugin%20API/settings/#settings-object","title":"settings : <code>object</code>","text":"<p>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\").</p> <p>Kind: global namespace </p> <ul> <li>settings : <code>object</code><ul> <li>.get(key, defaultValue) \u21d2 <code>*</code></li> <li>.set(key, value)</li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/settings/#settingsgetkey-defaultvalue","title":"settings.get(key, defaultValue) \u21d2 <code>*</code>","text":"<p>Get a setting.</p> <p>Kind: static method of <code>settings</code> </p> Param Type Description key <code>string</code> Setting key/ID defaultValue <code>*</code> Value to return if setting has no stored value. <p></p>"},{"location":"Plugin%20API/settings/#settingssetkey-value","title":"settings.set(key, value)","text":"<p>Set a setting.</p> <p>Kind: static method of <code>settings</code> </p> Param Type Description key <code>string</code> Setting key/ID value <code>string</code> Value to set."},{"location":"Plugin%20API/shipping/","title":"Shipping","text":""},{"location":"Plugin%20API/shipping/#shipping-object","title":"shipping : <code>object</code>","text":"<p>Add custom carrier and rates, and adjust markup.</p> <p>Kind: global namespace </p> <ul> <li>shipping : <code>object</code><ul> <li>.Address<ul> <li>new Address()</li> </ul> </li> <li>.getZIPCode(zipcode, country) \u21d2 <code>Object</code></li> <li>.getPackagingByID(id) \u21d2 <code>Promise.<Object></code></li> <li>.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging) \u21d2 <code>Promise.<number></code></li> <li>.getCarrierName(carrierId) \u21d2 <code>string</code></li> <li>.getServiceName(serviceId, carrier) \u21d2 <code>string</code></li> <li>.registerRateEndpoint(getRates, purchase, idPrefix)</li> <li>.registerMarkupCalculator(markupFn)</li> <li>.registerInsuranceProvider(id, name, cardText, maxValue, getQuote, insure)</li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/shipping/#shippingaddress","title":"shipping.Address","text":"<p>Kind: static class of <code>shipping</code> </p>"},{"location":"Plugin%20API/shipping/#new-address","title":"new Address()","text":"<p>A class representing an address.</p> <p></p>"},{"location":"Plugin%20API/shipping/#shippinggetzipcodezipcode-country-object","title":"shipping.getZIPCode(zipcode, country) \u21d2 <code>Object</code>","text":"<p>Get data for a ZIP Code.</p> <p>Kind: static method of <code>shipping</code> Returns: <code>Object</code> - Data about the ZIP code. See example. Fields may be empty if not available. Type may be \"STANDARD\", \"UNIQUE\", \"PO BOX\", or \"MILITARY\". </p> Param Type Default Description zipcode <code>string</code> ZIP or postal code. country <code>string</code> <code>\"US\"</code> Currently only \"US\" and \"CA\" are supported. <p>Example <pre><code>{city: \"NEW YORK\", state: \"NY\", type: \"STANDARD\"}\n</code></pre> </p>"},{"location":"Plugin%20API/shipping/#shippinggetpackagingbyidid-promiseobject","title":"shipping.getPackagingByID(id) \u21d2 <code>Promise.<Object></code>","text":"<p>Get a parcel's packaging type from PostalPoint's internal ID for it.</p> <p>Kind: static method of <code>shipping</code> Returns: <code>Promise.<Object></code> - See examples. </p> Param Type id <code>number</code> <p>Example <pre><code>{\n id: 100,\n type: \"Parcel\",\n img: \"box.png\",\n name: \"Box\",\n service: \"\",\n l: -1,\n w: -1,\n h: -1,\n weight: true,\n hazmat: true,\n source: \"Customer\"\n}\n</code></pre> Example <pre><code>{\n id: 1,\n type: \"FlatRateEnvelope\",\n img: \"pm-fres.png\",\n name: \"Flat Rate Envelope\",\n service: \"Priority\",\n l: -2,\n w: -2,\n h: -2,\n weight: false,\n hazmat: true,\n usps_supplied: true,\n envelope: true,\n source: \"USPS\",\n skus: [\"PS00001000014\", \"PS00001000012\", \"PS00001000027\", \"PS00001000064\", \"PS00001001921\", \"PS00001035000\", \"PS00001036014\", \"PS00001128600\", \"https://qr.usps.com/epsspu?p=30\", \"https://qr.usps.com/epsspu?p=8\"]\n}\n</code></pre> Example <pre><code>{\n id: 201,\n type: \"UPSLetter\",\n img: \"ups-env.png\",\n name: \"Envelope\",\n carrier: \"UPS\",\n l: -2,\n w: -2,\n h: -2,\n weight: true,\n hazmat: true,\n source: \"OtherCarrier\"\n}\n</code></pre> </p>"},{"location":"Plugin%20API/shipping/#shippinggetretailpricewithmarkupcost-retail-carrier-service-weightoz-packaging-promisenumber","title":"shipping.getRetailPriceWithMarkup(cost, retail, carrier, service, weightOz, packaging) \u21d2 <code>Promise.<number></code>","text":"<p>Calculate the retail price for a shipment rate based on the configured margin settings.</p> <p>Kind: static method of <code>shipping</code> Returns: <code>Promise.<number></code> - The amount to charge the customer </p> Param Type Description cost <code>number</code> Cost of shipment to business retail <code>number</code> Default retail price from label provider carrier <code>string</code> Shipment carrier service <code>string</code> Shipment service weightOz <code>number</code> The weight of the shipment in ounces, or null if not available. packaging <code>string</code> An empty string if not available, or \"Letter\", \"FlatRateEnvelope\", etc. <p></p>"},{"location":"Plugin%20API/shipping/#shippinggetcarriernamecarrierid-string","title":"shipping.getCarrierName(carrierId) \u21d2 <code>string</code>","text":"<p>Converts the carrier ID string into a consistent and human-readable name.</p> <p>Kind: static method of <code>shipping</code> </p> Param Type carrierId <code>string</code> <p></p>"},{"location":"Plugin%20API/shipping/#shippinggetservicenameserviceid-carrier-string","title":"shipping.getServiceName(serviceId, carrier) \u21d2 <code>string</code>","text":"<p>Converts the service ID string into a consistent and human-readable name. Set the carrier ID for better results.</p> <p>Kind: static method of <code>shipping</code> </p> Param Type Default serviceId <code>string</code> carrier <code>string</code> <code>\"USPS\"</code> <p></p>"},{"location":"Plugin%20API/shipping/#shippingregisterrateendpointgetrates-purchase-idprefix","title":"shipping.registerRateEndpoint(getRates, purchase, idPrefix)","text":"<p>Register the plugin as a shipping rate and label provider. See the Shipping example plugin.</p> <p>Kind: static method of <code>shipping</code> </p> Param Type Description getRates <code>function</code> A function passed a Parcel object to get rates for. Returns a Promise that resolves to an array of rate objects. purchase <code>function</code> A function passed a rate ID to purchase. Returns a Promise that resolves to the label information. idPrefix <code>string</code> A unique string that will be prefixing all rate IDs from this plugin. <p>Example <pre><code>// getRates sample return value:\n[{\n rateid: `${idPrefix}_${global.apis.util.uuid.v4()}`,\n carrier: \"CarrierID\",\n carrierName: \"Carrier Name\",\n service: \"CARRIER_SERVICE_ID\",\n cost_rate: 10,\n retail_rate: 15,\n delivery_days: 3,\n delivery_date: null,\n guaranteed: true,\n serviceName: \"Service Name\",\n color: \"green\" // Rate card color\n}]\n</code></pre> Example <pre><code>// purchase sample return value:\n{\n label: labelImageToPrint,\n labeltype: \"PNG\",\n receiptItem: ReceiptItem,\n tracking: \"12345678901234567890\",\n cost: 10.0,\n price: 15.0,\n carrier: \"Carrier Name\",\n service: \"Service Name\",\n delivery_days: 3,\n delivery_date: 1234567890, // UNIX timestamp\n to: toAddressLines // Array of strings\n}\n</code></pre> </p>"},{"location":"Plugin%20API/shipping/#shippingregistermarkupcalculatormarkupfn","title":"shipping.registerMarkupCalculator(markupFn)","text":"<p>Register the plugin to modify PostalPoint's shipping markup calculation during shipment rating.</p> <p>Kind: static method of <code>shipping</code> Throws:</p> <ul> <li><code>Error</code> Only one plugin may register with this function; any subsequent attempts to register will throw an Error.</li> </ul> Param Type Description markupFn <code>function</code> A function that must return either the retail price to charge for this rate, or <code>false</code> to opt-out of setting this particular rate. <p>Example <pre><code>global.apis.shipping.registerMarkupCalculator(\n // Parameters:\n // cost: Cost to shipper\n // retail: Carrier-suggested retail price\n // suggested: PostalPoint-suggested retail (default margin calc)\n // carrier: Shipping carrier name\n // service: Shipping service code\n // weightOz: The weight of the shipment in ounces, or null if not available.\n // packaging: An empty string if not available, or \"Letter\", \"FlatRateEnvelope\", etc. See https://docs.easypost.com/docs/parcels#predefined-package\n // parcel: The Parcel object for this shipment. May be null for some rate-only requests without a shipment, such as USPS price calculations.\n function (cost, retail, suggested, carrier, service, weightOz, packaging, parcel) {\n if (carrier == \"USPS\") {\n if (service == \"First-Class Mail\") {\n // Handle First-Class Mail differently if it's a 1oz letter (i.e. Forever stamp)\n if (weightOz <= 1 && packaging == \"Letter\") {\n return retail + 0.05;\n } else {\n return retail + 0.25;\n }\n }\n // Handle flat rate envelopes differently\n if (global.apis.shipping.getServiceName(service, carrier) == \"Priority Mail\" && packaging == \"FlatRateEnvelope\") {\n return retail + 1.0;\n }\n return suggested + 2.0; // Charge the PostalPoint-calculated amount plus $2\n } else {\n return cost * 2; // Charges the customer double the shipment's cost.\n }\n }\n);\n</code></pre> </p>"},{"location":"Plugin%20API/shipping/#shippingregisterinsuranceproviderid-name-cardtext-maxvalue-getquote-insure","title":"shipping.registerInsuranceProvider(id, name, cardText, maxValue, getQuote, insure)","text":"<p>Add a shipping insurance provider.</p> <p>Kind: static method of <code>shipping</code> </p> Param Type Description id <code>string</code> | <code>null</code> Unique ID for the provider. Will be autogenerated if null. name <code>string</code> Human-readable name for the provider. Shown as the card heading on the Insurance section of the Ship screen. cardText <code>string</code> Text or HTML to display on the Ship screen card for this provider. maxValue <code>number</code> The largest number that will be accepted for the \"Insured for\" value. getQuote <code>function</code> Returns the cost and retail price for insuring the parcel, or a Promise that resolves into the same. See the example for details. insure <code>function</code> Insure the parcel and add the insurance details to the receipt. See example. <p>Example <pre><code>async function getQuote(value, parcel, carrier, service) {\n // Do math, etc\n var cost = value / 100;\n\n return {\n cost: cost,\n retail: cost * 2\n };\n // Or, to remove this shipping rate from the list,\n // because the shipment/carrier/service combination\n // is not eligible for insurance:\n return false;\n}\n\nasync function insure(value, parcel, carrier = \"USPS\", service = \"Priority\", trackingNumber = \"94055...\") {\n // Purchase the insurance\n var cost = value / 100;\n var retailPrice = cost * 2;\n var costPrice = cost;\n\n var receiptitem = new global.apis.pos.ReceiptItem(`sampleinsurance_${trackingNumber}`,\n \"Sample Insurance\",\n \"Insured for \" + global.apis.i18n.moneyString(value),\n retailPrice, 1, costPrice, 0\n );\n receiptitem.merch = true;\n receiptitem.category = \"Shipping Insurance\";\n receiptitem.barcode = trackingNumber;\n global.apis.pos.addReceiptItem(receiptitem);\n}\n\nglobal.apis.shipping.registerInsuranceProvider(\n \"sampleproviderid\", \"Sample Insurance\",\n \"Insurance coverage from Sample Insurance. $1 per $100 of value.\",\n 5000, getQuote, insure);\n</code></pre></p>"},{"location":"Plugin%20API/storage/","title":"Storage","text":""},{"location":"Plugin%20API/storage/#storage-object","title":"storage : <code>object</code>","text":"<p>Get and set data.</p> <p>Kind: global namespace </p> <ul> <li>storage : <code>object</code><ul> <li>.getSmall(key, defaultValue) \u21d2 <code>*</code></li> <li>.setSmall(key, value)</li> <li>.getBig(key, defaultValue)</li> <li>.setBig(key, value)</li> <li>.getDB(key, defaultValue) \u21d2 <code>Promise.<*></code></li> <li>.setDB(key, value) \u21d2 <code>Promise</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/storage/#storagegetsmallkey-defaultvalue","title":"storage.getSmall(key, defaultValue) \u21d2 <code>*</code>","text":"<p>Get a value from the small data storage, using localStorage or a similar mechanism (may change in the future).</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID defaultValue <code>*</code> Value to return if the item key doesn't have a stored value. <p></p>"},{"location":"Plugin%20API/storage/#storagesetsmallkey-value","title":"storage.setSmall(key, value)","text":"<p>Set a value in the small data storage, using localStorage or a similar mechanism (may change in the future).</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID value <code>*</code> Value to store. <p></p>"},{"location":"Plugin%20API/storage/#storagegetbigkey-defaultvalue","title":"storage.getBig(key, defaultValue)","text":"<p>Get a value in the large data storage. Unserialized from a JSON file on disk.</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID defaultValue <code>*</code> Value to return if the item key doesn't have a stored value. <p></p>"},{"location":"Plugin%20API/storage/#storagesetbigkey-value","title":"storage.setBig(key, value)","text":"<p>Set a value in the large data storage. Serialized to JSON and stored on disk as a file.</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID value <code>*</code> Value to store. <p></p>"},{"location":"Plugin%20API/storage/#storagegetdbkey-defaultvalue-promise","title":"storage.getDB(key, defaultValue) \u21d2 <code>Promise.<*></code>","text":"<p>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.</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID defaultValue <code>*</code> Value to return if the item key doesn't have a stored value. <p></p>"},{"location":"Plugin%20API/storage/#storagesetdbkey-value-promise","title":"storage.setDB(key, value) \u21d2 <code>Promise</code>","text":"<p>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.</p> <p>Kind: static method of <code>storage</code> </p> Param Type Description key <code>string</code> Storage item key/ID value <code>*</code> Value to store."},{"location":"Plugin%20API/ui/","title":"Ui","text":""},{"location":"Plugin%20API/ui/#ui-object","title":"ui : <code>object</code>","text":"<p>Interact with and modify the PostalPoint user interface.</p> <p>Kind: global namespace </p> <ul> <li>ui : <code>object</code><ul> <li>.addToolsPage(page, title, id, description, cardTitle, icon, type)</li> <li>.addHomeTab(content, title, icon, id) \u21d2 <code>undefined</code></li> <li>.showProgressSpinner(title, text, subtitle) \u21d2 <code>undefined</code></li> <li>.hideProgressSpinner()</li> <li>.openSystemWebBrowser(url)</li> <li>.openInternalWebBrowser(url)</li> <li>.clearCustomerScreen()</li> <li>.setCustomerScreen(content, type, displayInCard, cardSize, displayStatusBar)</li> <li>.collectSignatureFromCustomerScreen(title, terms, termstype)</li> <li>.cancelSignatureCollection()</li> <li>.clearSignaturePad()</li> <li>.getCustomerDisplayInfo() \u21d2 <code>Object</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/ui/#uiaddtoolspagepage-title-id-description-cardtitle-icon-type","title":"ui.addToolsPage(page, title, id, description, cardTitle, icon, type)","text":"<p>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</p> <p>Kind: static method of <code>ui</code> </p> Param Type Default Description page <code>string</code> | <code>function</code> Page content as a Framework7 component page. If <code>page</code> is a string ending in <code>.f7</code> it is treated as a file path and the page content will be loaded from disk. If <code>page</code> is any other string, it is treated as the page content. If <code>page</code> is a function, it will be called and must return the page content (unless <code>type</code> is set to <code>\"function\"</code>, see examples) title <code>string</code> Page title. id <code>string</code> Page ID. Make it unique, or pass an empty string to be assigned a random ID. description <code>string</code> Description of this tool for its card on the Tools screen. cardTitle <code>string</code> Title of the card for this page on the Tools screen. icon <code>string</code> FontAwesome icon class, for example, \"fa-solid fa-globe\". FontAwesome Pro solid, regular, light, and duotone icons are available. type <code>string</code> <code>\"page\"</code> What kind of data is supplied by <code>page</code>: \"page\" or \"function\". <p>Example <pre><code>// Full plugin that displays an alert when the card is clicked on the Tools page\nexports.init = function () {\n global.apis.ui.addToolsPage(\n displayMessage,\n \"click me\",\n \"clickmecard\",\n \"Click here to see a message\",\n \"Click This Card\",\n \"fa-solid fa-arrow-pointer\",\n \"function\"\n );\n}\n\nfunction displayMessage() {\n global.apis.alert(\"Card clicked\");\n}\n</code></pre> Example <pre><code>// Open a dynamically-generated page\nfunction rollDice() {\n var randomNumber = Math.round(Math.random() * 6) + 1;\n return `<div class=\"page\">\n <div class=\"navbar\">\n <div class=\"navbar-bg\"></div>\n <div class=\"navbar-inner\">\n <a href=\"#\" class=\"link back\">\n <i class=\"icon icon-back\"></i>\n </a>\n <div class=\"title\">Random Number</div>\n </div>\n </div>\n <div class=\"page-content\">\n <div class=\"block\">\n <h1>You rolled ${randomNumber}</h1>\n </div>\n </div>\n </div>`;\n}\nglobal.apis.ui.addToolsPage(\n rollDice,\n \"Random\",\n \"randomnumbercard\",\n \"Click here for a random number\",\n \"Random Number\",\n \"fa-regular fa-dice\",\n \"page\"\n );\n</code></pre> Example <pre><code>// Open a page from a file.\n// See https://framework7.io/docs/router-component#single-file-component\nglobal.apis.ui.addToolsPage(\n global.apis.getPluginFolder(\"example-plugin\") + \"/page.f7\",\n \"Page\",\n \"filepage\",\n \"Open page.f7 from the plugin installation folder\",\n \"Open Custom Page\",\n \"fa-regular fa-file\",\n \"page\"\n );\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uiaddhometabcontent-title-icon-id-undefined","title":"ui.addHomeTab(content, title, icon, id) \u21d2 <code>undefined</code>","text":"<p>Add a custom tab to the PostalPoint home screen. Works almost the same as addToolsPage.</p> <p>Kind: static method of <code>ui</code> </p> Param Type Description content <code>string</code> | <code>function</code> 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 <code>content</code> is a string ending in <code>.f7</code> it is treated as a file path and the content will be loaded from disk. If <code>content</code> is any other string, it is treated as the content. If <code>content</code> is a function, it will be called and must return the content. title <code>string</code> Tab title. Keep it short; depending on screen size and tab count, you have as little as 150px of space. icon <code>string</code> FontAwesome icon displayed above the tab title. id <code>string</code> 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. <p>Example <pre><code>global.apis.ui.addHomeTab(\"<div class='block'>Hello</div>\", \"Hello Tab\", \"fa-duotone fa-hand-wave\", \"hellotab\");\n</code></pre> Example <pre><code>function renderTab() {\n return \"<template><div><h1>${hellovar}</h1></div></template><script>export default (props, {$on, $update, $f7}) => {var hellovar = 'hello world'; return $render;}</script>\";\n}\nglobal.apis.ui.addHomeTab(renderTab, \"Hello Template\", \"fa-duotone fa-file-code\", \"hellotemplatetab\");\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uishowprogressspinnertitle-text-subtitle-undefined","title":"ui.showProgressSpinner(title, text, subtitle) \u21d2 <code>undefined</code>","text":"<p>Show a notification with a loading icon.</p> <p>Kind: static method of <code>ui</code> </p> Param Type Description title <code>string</code> The message to show on the spinner. text <code>string</code> Optional. Body text on the spinner. subtitle <code>string</code> Optional. Sub-heading under the <code>title</code>. <p></p>"},{"location":"Plugin%20API/ui/#uihideprogressspinner","title":"ui.hideProgressSpinner()","text":"<p>Close the notification opened by <code>showProgressSpinner</code>.</p> <p>Kind: static method of <code>ui</code> </p>"},{"location":"Plugin%20API/ui/#uiopensystemwebbrowserurl","title":"ui.openSystemWebBrowser(url)","text":"<p>Open the native OS default browser to the URL given.</p> <p>Kind: static method of <code>ui</code> </p> Param Type url <code>string</code> <p></p>"},{"location":"Plugin%20API/ui/#uiopeninternalwebbrowserurl","title":"ui.openInternalWebBrowser(url)","text":"<p>Open a web browser inside PostalPoint. The browser has forward/back/close buttons.</p> <p>Kind: static method of <code>ui</code> </p> Param Type url <code>string</code> <p>Example <pre><code>global.apis.ui.openInternalWebBrowser(\"https://postalpoint.app\");\nglobal.apis.eventbus.on(\"browserNavigate\", function (newUrl) {\n global.apis.alert(`New URL: ${newUrl}`, \"Browser Navigated\");\n if (newUrl == \"https://closeme.com\") {\n global.apis.eventbus.emit(\"browserCloseRequest\");\n }\n});\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uiclearcustomerscreen","title":"ui.clearCustomerScreen()","text":"<p>Clear any custom content on the customer-facing display, defaulting back to blank/receipt/shipping rates, as applicable.</p> <p>Kind: static method of <code>ui</code> </p>"},{"location":"Plugin%20API/ui/#uisetcustomerscreencontent-type-displayincard-cardsize-displaystatusbar","title":"ui.setCustomerScreen(content, type, displayInCard, cardSize, displayStatusBar)","text":"<p>Render content on the customer-facing display. Encodes content as a data URI (example: <code>data:text/html;charset=utf-8,${content}</code>) 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.</p> <p>Kind: static method of <code>ui</code> </p> Param Type Default Description content <code>string</code> Page content. type <code>string</code> <code>\"html\"</code> Format of the <code>content</code>. One of \"html\", \"pdf\", \"raw\", \"body\", or \"text\". displayInCard <code>boolean</code> <code>false</code> Set to true to wrap the content in a card UI. cardSize <code>Array.<number></code> <code>[300,300</code> Size of the card UI if displayInCard == true. displayStatusBar <code>boolean</code> <code>true</code> Whether the bar on the bottom of the screen should be visible, containing the store logo and scale weight. <p>Example <pre><code>// How content is converted by PostalPoint before display:\nif (type == \"html\") {\n customerScreenContent = `data:text/html;charset=utf-8,${content}`;\n} else if (type == \"pdf\") {\n customerScreenContent = `data:application/pdf,${content}`;\n} else if (type == \"raw\") {\n global.customerScreenContent = `${content}`;\n} else if (type == \"body\") {\n customerScreenContent = `data:text/html;charset=utf-8,<!DOCTYPE html>\n <meta charset=\"utf-8\">\n <title></title>\n <style>\n html, body {margin: 0; padding: 0; font-family: Roboto, Ubuntu, Arial, sans-serif;}\n h1, h2, h3 {margin: 0;}\n </style>\n <div id=\"maindiv\">${content}</div>`;\n} else {\n customerScreenContent = `data:text/plain;charset=utf-8,${content}`;\n}\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uicollectsignaturefromcustomerscreentitle-terms-termstype","title":"ui.collectSignatureFromCustomerScreen(title, terms, termstype)","text":"<p>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,...\"}</p> <p>Kind: static method of <code>ui</code> </p> Param Type Default Description title <code>string</code> <code>null</code> Display a title/header on the customer screen. Currently ignored, but may be used in the future. terms <code>string</code> | <code>boolean</code> <code>false</code> Set to a string to display terms and conditions or other text content next to the signature pad. termstype <code>string</code> <code>\"body\"</code> \"html\", \"pdf\", \"raw\", or \"body\". See setCustomerScreen() <p>Example <pre><code>global.apis.ui.collectSignatureFromCustomerScreen(\"\", \"<p>By signing, you agree to pay us lots of money</p>\", \"body\");\nglobal.apis.eventbus.on(\"customerSignatureCollected\", function (sigdata) {\n const pngDataURL = sigdata.png;\n const svgDataURL = sigdata.svg;\n});\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uicancelsignaturecollection","title":"ui.cancelSignatureCollection()","text":"<p>Cancels customer signature collection and returns the customer-facing display to normal operation.</p> <p>Kind: static method of <code>ui</code> Example <pre><code>global.apis.ui.cancelSignatureCollection();\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uiclearsignaturepad","title":"ui.clearSignaturePad()","text":"<p>Erase the signature drawn on the customer-facing display. Note that the customer is also provided a button to do this.</p> <p>Kind: static method of <code>ui</code> Example <pre><code>global.apis.ui.clearSignaturePad();\n</code></pre> </p>"},{"location":"Plugin%20API/ui/#uigetcustomerdisplayinfo-object","title":"ui.getCustomerDisplayInfo() \u21d2 <code>Object</code>","text":"<p>Describes if the customer-facing display is currently enabled, and if it supports customer touch interaction.</p> <p>Kind: static method of <code>ui</code> Returns: <code>Object</code> - {\"enabled\": true, \"touch\": true} Example <pre><code>var info = global.apis.ui.getCustomerDisplayInfo();\n</code></pre></p>"},{"location":"Plugin%20API/user/","title":"User","text":""},{"location":"Plugin%20API/user/#user-object","title":"user : <code>object</code>","text":"<p>Access data about employees.</p> <p>Kind: global namespace </p> <ul> <li>user : <code>object</code><ul> <li>.User<ul> <li>new User(id, name, password, barcode, enabled)</li> </ul> </li> <li>.getUser() \u21d2 <code>User</code></li> <li>.getUserID() \u21d2 <code>number</code></li> <li>.getUserByID() \u21d2 <code>Promise.<User></code></li> <li>.listUsers([managerMode]) \u21d2 <code>Promise.<Array.<User>></code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/user/#useruser","title":"user.User","text":"<p>Kind: static class of <code>user</code> Properties</p> Name Type Description id <code>number</code> name <code>string</code> pass <code>string</code> barcode <code>string</code> enabled <code>boolean</code> hasPassword() <code>function</code> Returns true if the user has a password set, else false. checkPassword(string) <code>function</code> Returns true if the provided password matches the user's password, or if there is no password set. icon(number) <code>function</code> Returns a SVG data URI with a procedurally-generated icon for the user. Size defaults to 50px if not specified. <p></p>"},{"location":"Plugin%20API/user/#new-userid-name-password-barcode-enabled","title":"new User(id, name, password, barcode, enabled)","text":"<p>A User object.</p> Param Type id <code>number</code> name <code>string</code> password <code>string</code> barcode <code>string</code> enabled <code>boolean</code> <p></p>"},{"location":"Plugin%20API/user/#usergetuser-user","title":"user.getUser() \u21d2 <code>User</code>","text":"<p>Get the user currently logged in.</p> <p>Kind: static method of <code>user</code> </p>"},{"location":"Plugin%20API/user/#usergetuserid-number","title":"user.getUserID() \u21d2 <code>number</code>","text":"<p>Get the current user's ID number.</p> <p>Kind: static method of <code>user</code> </p>"},{"location":"Plugin%20API/user/#usergetuserbyid-promiseuser","title":"user.getUserByID() \u21d2 <code>Promise.<User></code>","text":"<p>Look up the User for an ID number.</p> <p>Kind: static method of <code>user</code> </p>"},{"location":"Plugin%20API/user/#userlistusersmanagermode-promisearrayuser","title":"user.listUsers([managerMode]) \u21d2 <code>Promise.<Array.<User>></code>","text":"<p>Get a list of all users in the system.</p> <p>Kind: static method of <code>user</code> </p> Param Type Default Description [managerMode] <code>boolean</code> <code>false</code> 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)."},{"location":"Plugin%20API/util/","title":"Util","text":""},{"location":"Plugin%20API/util/#util-object","title":"util : <code>object</code>","text":"<p>Various utility functions: HTTP, time/date, barcode creation, clipboard, etc.</p> <p>Kind: global namespace </p> <ul> <li>util : <code>object</code><ul> <li>.uuid : <code>object</code><ul> <li>.v4() \u21d2 <code>string</code></li> <li>.short([length]) \u21d2 <code>string</code></li> </ul> </li> <li>.http : <code>object</code><ul> <li>.webhook : <code>object</code><ul> <li>.geturl(sourcename) \u21d2 <code>Promise.<string></code></li> <li>.poll(sourcename) \u21d2 <code>Promise.<Array.<Object>></code></li> <li>.ack(webhookid)</li> </ul> </li> <li>.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code></li> <li>.fetch(url, [responseType], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code></li> </ul> </li> <li>.string : <code>object</code><ul> <li>.split(input, separator, [limit]) \u21d2 <code>Array.<string></code></li> <li>.chunk(input, chunksize) \u21d2 <code>Array.<string></code></li> </ul> </li> <li>.time : <code>object</code><ul> <li>.now() \u21d2 <code>number</code></li> <li>.diff(compareto) \u21d2 <code>number</code></li> <li>.strtotime(str) \u21d2 <code>number</code></li> <li>.format(format, [timestamp]) \u21d2 <code>string</code></li> <li>.toDateString(timestamp) \u21d2 <code>string</code></li> <li>.toTimeString(timestamp) \u21d2 <code>string</code></li> </ul> </li> <li>.clipboard : <code>object</code><ul> <li>.copy(text, [showNotification]) \u21d2 <code>Promise.<boolean></code></li> </ul> </li> <li>.barcode : <code>object</code><ul> <li>.getBuffer(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<Buffer></code></li> <li>.getBase64(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<string></code></li> </ul> </li> <li>.geography : <code>object</code><ul> <li>.isoToCountryName(iso) \u21d2 <code>string</code></li> </ul> </li> <li>.objectEquals(a, b) \u21d2 <code>boolean</code></li> <li>.delay([ms]) \u21d2 <code>Promise</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#utiluuid-object","title":"util.uuid : <code>object</code>","text":"<p>Unique ID generators.</p> <p>Kind: static namespace of <code>util</code> </p> <ul> <li>.uuid : <code>object</code><ul> <li>.v4() \u21d2 <code>string</code></li> <li>.short([length]) \u21d2 <code>string</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#uuidv4-string","title":"uuid.v4() \u21d2 <code>string</code>","text":"<p>Generate a UUID string</p> <p>Kind: static method of <code>uuid</code> Returns: <code>string</code> - UUID v4 with dashes: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx </p>"},{"location":"Plugin%20API/util/#uuidshortlength-string","title":"uuid.short([length]) \u21d2 <code>string</code>","text":"<p>Generate a short random alphanumeric string.</p> <p>Kind: static method of <code>uuid</code> Returns: <code>string</code> - A string of length <code>length</code>, from the character set \"acdefhjkmnpqrtuvwxy0123456789\". </p> Param Type Default Description [length] <code>number</code> <code>16</code> String character count. <p></p>"},{"location":"Plugin%20API/util/#utilhttp-object","title":"util.http : <code>object</code>","text":"<p>HTTP requests and webhooks.</p> <p>Kind: static namespace of <code>util</code> </p> <ul> <li>.http : <code>object</code><ul> <li>.webhook : <code>object</code><ul> <li>.geturl(sourcename) \u21d2 <code>Promise.<string></code></li> <li>.poll(sourcename) \u21d2 <code>Promise.<Array.<Object>></code></li> <li>.ack(webhookid)</li> </ul> </li> <li>.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code></li> <li>.fetch(url, [responseType], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#httpwebhook-object","title":"http.webhook : <code>object</code>","text":"<p>Use webhooks via a PostalPoint cloud relay service.</p> <p>Kind: static namespace of <code>http</code> </p> <ul> <li>.webhook : <code>object</code><ul> <li>.geturl(sourcename) \u21d2 <code>Promise.<string></code></li> <li>.poll(sourcename) \u21d2 <code>Promise.<Array.<Object>></code></li> <li>.ack(webhookid)</li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#webhookgeturlsourcename-promisestring","title":"webhook.geturl(sourcename) \u21d2 <code>Promise.<string></code>","text":"<p>geturl - Returns a public URL that can be used as a webhook target/endpoint for third-party integrations.</p> <p>Kind: static method of <code>webhook</code> Returns: <code>Promise.<string></code> - A URL for the webhook. </p> Param Type Description sourcename <code>string</code> Unique identifier for the webhook <p></p>"},{"location":"Plugin%20API/util/#webhookpollsourcename-promisearrayobject","title":"webhook.poll(sourcename) \u21d2 <code>Promise.<Array.<Object>></code>","text":"<p>poll - Returns an array of webhook payloads received by the webhook identified by <code>sourcename</code>.</p> <p>Kind: static method of <code>webhook</code> Returns: <code>Promise.<Array.<Object>></code> - Payloads as received by the webhook relay service. </p> Param Type Description sourcename <code>string</code> Unique identifier for the webhook <p>Example <pre><code>[\n {\n // Unique ID. Used for ack(webhookid).\n id: 123,\n\n // UNIX timestamp (in seconds) of when the data was received by the webhook URL.\n timestamp: 1234567890,\n\n // Source name set in geturl()\n source: \"sourcename\",\n\n // JSON string of all the HTTP headers sent to the webhook URL.\n headers: \"{'Content-Type': 'application/json'}\",\n\n // Entire HTTP request body sent to the webhook URL.\n body: \"\"\n }\n]\n</code></pre> </p>"},{"location":"Plugin%20API/util/#webhookackwebhookid","title":"webhook.ack(webhookid)","text":"<p>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.</p> <p>Kind: static method of <code>webhook</code> </p> Param Type Description webhookid <code>number</code> Numeric unique ID received with the payload. See <code>poll</code>. <p></p>"},{"location":"Plugin%20API/util/#httpposturl-data-responsetype-headers-method-continueonbadstatuscode-timeoutseconds-promisestringblobarraybufferobject","title":"http.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code>","text":"<p>post - Fetch a HTTP POST request.</p> <p>Kind: static method of <code>http</code> Returns: <code>Promise.<(string|Blob|ArrayBuffer|Object)></code> - The server response body. See <code>responseType</code> parameter. </p> Param Type Default Description url <code>string</code> data <code>Object.<string, string></code> POST data key/value list [responseType] <code>string</code> <code>\"text\"</code> \"text\", \"blob\", \"buffer\", or \"json\" [headers] <code>Object.<string, string></code> HTTP headers to send. Defaults to <code>{\"Content-Type\": \"application/json\"}</code>. [method] <code>string</code> <code>\"POST\"</code> [continueOnBadStatusCode] <code>boolean</code> <code>false</code> If false, throws an Error when the HTTP response code is not 2XX. If true, ignores the response code and proceeds as normal. [timeoutSeconds] <code>number</code> <code>15</code> Aborts the request (timeout) after this many seconds. <p></p>"},{"location":"Plugin%20API/util/#httpfetchurl-responsetype-timeoutseconds-promisestringblobarraybufferobject","title":"http.fetch(url, [responseType], [timeoutSeconds]) \u21d2 <code>Promise.<(string|Blob|ArrayBuffer|Object)></code>","text":"<p>fetch - Fetch a HTTP GET request.</p> <p>Kind: static method of <code>http</code> Returns: <code>Promise.<(string|Blob|ArrayBuffer|Object)></code> - The server response body. See <code>responseType</code> parameter. </p> Param Type Default Description url <code>string</code> [responseType] <code>string</code> <code>\"text\"</code> \"text\", \"blob\", \"buffer\", or \"json\" [timeoutSeconds] <code>number</code> <code>15</code> Aborts the request (timeout) after this many seconds. <p></p>"},{"location":"Plugin%20API/util/#utilstring-object","title":"util.string : <code>object</code>","text":"<p>String manipulation functions.</p> <p>Kind: static namespace of <code>util</code> </p> <ul> <li>.string : <code>object</code><ul> <li>.split(input, separator, [limit]) \u21d2 <code>Array.<string></code></li> <li>.chunk(input, chunksize) \u21d2 <code>Array.<string></code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#stringsplitinput-separator-limit-arraystring","title":"string.split(input, separator, [limit]) \u21d2 <code>Array.<string></code>","text":"<p>Split a string with a separator regex.</p> <p>Kind: static method of <code>string</code> </p> Param Type Description input <code>string</code> Input string separator <code>string</code> Passed to <code>new RegExp(separator, 'g')</code> [limit] <code>number</code> Maximum number of splits to perform <p></p>"},{"location":"Plugin%20API/util/#stringchunkinput-chunksize-arraystring","title":"string.chunk(input, chunksize) \u21d2 <code>Array.<string></code>","text":"<p>Split a string into chunks of length <code>chunksize</code>.</p> <p>Kind: static method of <code>string</code> </p> Param Type Description input <code>string</code> Input string chunksize <code>string</code> Number of characters per chunk <p></p>"},{"location":"Plugin%20API/util/#utiltime-object","title":"util.time : <code>object</code>","text":"<p>Date and time functions</p> <p>Kind: static namespace of <code>util</code> </p> <ul> <li>.time : <code>object</code><ul> <li>.now() \u21d2 <code>number</code></li> <li>.diff(compareto) \u21d2 <code>number</code></li> <li>.strtotime(str) \u21d2 <code>number</code></li> <li>.format(format, [timestamp]) \u21d2 <code>string</code></li> <li>.toDateString(timestamp) \u21d2 <code>string</code></li> <li>.toTimeString(timestamp) \u21d2 <code>string</code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#timenow-number","title":"time.now() \u21d2 <code>number</code>","text":"<p>Get the current UNIX timestamp in seconds.</p> <p>Kind: static method of <code>time</code> </p>"},{"location":"Plugin%20API/util/#timediffcompareto-number","title":"time.diff(compareto) \u21d2 <code>number</code>","text":"<p>Get the number of seconds between now and the given Date or UNIX timestamp in seconds.</p> <p>Kind: static method of <code>time</code> </p> Param Type compareto <code>number</code> | <code>Date</code> <p></p>"},{"location":"Plugin%20API/util/#timestrtotimestr-number","title":"time.strtotime(str) \u21d2 <code>number</code>","text":"<p>Parse a string date and return UNIX timestamp (in seconds).</p> <p>Kind: static method of <code>time</code> </p> Param Type str <code>string</code> <p></p>"},{"location":"Plugin%20API/util/#timeformatformat-timestamp-string","title":"time.format(format, [timestamp]) \u21d2 <code>string</code>","text":"<p>Take a Date or UNIX timestamp in seconds and format it to a string. Mostly compatible with the PHP date format codes.</p> <p>Kind: static method of <code>time</code> </p> Param Type Default Description format <code>string</code> \"Y-m-d H:i:s\", etc [timestamp] <code>number</code> | <code>Date</code> <code>now()</code> <p></p>"},{"location":"Plugin%20API/util/#timetodatestringtimestamp-string","title":"time.toDateString(timestamp) \u21d2 <code>string</code>","text":"<p>Format a UNIX timestamp (in seconds) as a localized date string.</p> <p>Kind: static method of <code>time</code> </p> Param Type timestamp <code>number</code> <p></p>"},{"location":"Plugin%20API/util/#timetotimestringtimestamp-string","title":"time.toTimeString(timestamp) \u21d2 <code>string</code>","text":"<p>Format a UNIX timestamp (in seconds) as a localized time string.</p> <p>Kind: static method of <code>time</code> </p> Param Type timestamp <code>number</code> <p></p>"},{"location":"Plugin%20API/util/#utilclipboard-object","title":"util.clipboard : <code>object</code>","text":"<p>OS clipboard</p> <p>Kind: static namespace of <code>util</code> </p>"},{"location":"Plugin%20API/util/#clipboardcopytext-shownotification-promiseboolean","title":"clipboard.copy(text, [showNotification]) \u21d2 <code>Promise.<boolean></code>","text":"<p>Copy a string to the system clipboard.</p> <p>Kind: static method of <code>clipboard</code> Returns: <code>Promise.<boolean></code> - True if the copy succeeded, else false. </p> Param Type Default Description text <code>string</code> [showNotification] <code>boolean</code> <code>false</code> If true, a \"Copied\" notification will appear onscreen briefly. <p></p>"},{"location":"Plugin%20API/util/#utilbarcode-object","title":"util.barcode : <code>object</code>","text":"<p>Barcode image generation functions.</p> <p>Kind: static namespace of <code>util</code> </p> <ul> <li>.barcode : <code>object</code><ul> <li>.getBuffer(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<Buffer></code></li> <li>.getBase64(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<string></code></li> </ul> </li> </ul> <p></p>"},{"location":"Plugin%20API/util/#barcodegetbufferdata-type-height-scale-includetext-promisebuffer","title":"barcode.getBuffer(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<Buffer></code>","text":"<p>Get a PNG image buffer of a barcode. Uses library \"bwip-js\".</p> <p>Kind: static method of <code>barcode</code> Returns: <code>Promise.<Buffer></code> - PNG data for the barcode. </p> Param Type Default Description data <code>string</code> [type] <code>string</code> <code>\"\\\"code128\\\"\"</code> [height] <code>number</code> <code>10</code> [scale] <code>number</code> <code>2</code> [includetext] <code>boolean</code> <code>false</code> Set true to render the barcode's content as text below the code. <p></p>"},{"location":"Plugin%20API/util/#barcodegetbase64data-type-height-scale-includetext-promisestring","title":"barcode.getBase64(data, [type], [height], [scale], [includetext]) \u21d2 <code>Promise.<string></code>","text":"<p>Get a PNG image of a barcode as a base64 data URI. Uses library \"bwip-js\".</p> <p>Kind: static method of <code>barcode</code> Returns: <code>Promise.<string></code> - \"data:image/png;base64,...\" </p> Param Type Default Description data <code>string</code> [type] <code>string</code> <code>\"\\\"code128\\\"\"</code> [height] <code>number</code> <code>10</code> [scale] <code>number</code> <code>2</code> [includetext] <code>boolean</code> <code>false</code> Set true to render the barcode's content as text below the code. <p></p>"},{"location":"Plugin%20API/util/#utilgeography-object","title":"util.geography : <code>object</code>","text":"<p>Kind: static namespace of <code>util</code> </p>"},{"location":"Plugin%20API/util/#geographyisotocountrynameiso-string","title":"geography.isoToCountryName(iso) \u21d2 <code>string</code>","text":"<p>Get a human-readable country name from an ISO country code.</p> <p>Kind: static method of <code>geography</code> </p> Param Type Description iso <code>string</code> | <code>number</code> 2 or 3 letter country code, or numeric country code. <p></p>"},{"location":"Plugin%20API/util/#utilobjectequalsa-b-boolean","title":"util.objectEquals(a, b) \u21d2 <code>boolean</code>","text":"<p>Compare two objects for equality. See https://stackoverflow.com/a/16788517</p> <p>Kind: static method of <code>util</code> Returns: <code>boolean</code> - True if equal, else false. </p> Param Type a <code>*</code> b <code>*</code> <p></p>"},{"location":"Plugin%20API/util/#utildelayms-promise","title":"util.delay([ms]) \u21d2 <code>Promise</code>","text":"<p>Pause execution for some amount of time in an async function, i.e., returns a Promise that resolves in some number of milliseconds.</p> <p>Kind: static method of <code>util</code> </p> Param Type Default Description [ms] <code>number</code> <code>1000</code> Number of milliseconds to pause."}]} |