## util : object Various utility functions: HTTP, time/date, barcode creation, clipboard, etc. **Kind**: global namespace * [util](#util) : object * [.uuid](#util.uuid) : object * [.v4()](#util.uuid.v4) ⇒ string * [.short([length])](#util.uuid.short) ⇒ string * [.http](#util.http) : object * [.webhook](#util.http.webhook) : object * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> * [.ack(webhookid)](#util.http.webhook.ack) * [.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds])](#util.http.post) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> * [.fetch(url, [responseType], [timeoutSeconds])](#util.http.fetch) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> * [.string](#util.string) : object * [.split(input, separator, [limit])](#util.string.split) ⇒ Array.<string> * [.chunk(input, chunksize)](#util.string.chunk) ⇒ Array.<string> * [.time](#util.time) : object * [.now()](#util.time.now) ⇒ number * [.diff(compareto)](#util.time.diff) ⇒ number * [.strtotime(str)](#util.time.strtotime) ⇒ number * [.format(format, [timestamp])](#util.time.format) ⇒ string * [.toDateString(timestamp)](#util.time.toDateString) ⇒ string * [.toTimeString(timestamp)](#util.time.toTimeString) ⇒ string * [.clipboard](#util.clipboard) : object * [.copy(text, [showNotification])](#util.clipboard.copy) ⇒ Promise.<boolean> * [.barcode](#util.barcode) : object * [.getBuffer(data, [type], [height], [scale], [includetext])](#util.barcode.getBuffer) ⇒ Promise.<Buffer> * [.getBase64(data, [type], [height], [scale], [includetext])](#util.barcode.getBase64) ⇒ Promise.<string> * [.geography](#util.geography) : object * [.isoToCountryName(iso)](#util.geography.isoToCountryName) ⇒ string * [.objectEquals(a, b)](#util.objectEquals) ⇒ boolean * [.delay([ms])](#util.delay) ⇒ Promise ### util.uuid : object Unique ID generators. **Kind**: static namespace of [util](#util) * [.uuid](#util.uuid) : object * [.v4()](#util.uuid.v4) ⇒ string * [.short([length])](#util.uuid.short) ⇒ string #### uuid.v4() ⇒ string Generate a UUID string **Kind**: static method of [uuid](#util.uuid) **Returns**: string - UUID v4 with dashes: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx #### uuid.short([length]) ⇒ string Generate a short random alphanumeric string. **Kind**: static method of [uuid](#util.uuid) **Returns**: string - A string of length `length`, from the character set "acdefhjkmnpqrtuvwxy0123456789". | Param | Type | Default | Description | | --- | --- | --- | --- | | [length] | number | 16 | String character count. | ### util.http : object HTTP requests and webhooks. **Kind**: static namespace of [util](#util) * [.http](#util.http) : object * [.webhook](#util.http.webhook) : object * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> * [.ack(webhookid)](#util.http.webhook.ack) * [.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds])](#util.http.post) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> * [.fetch(url, [responseType], [timeoutSeconds])](#util.http.fetch) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> #### http.webhook : object Use webhooks via a PostalPoint cloud relay service. **Kind**: static namespace of [http](#util.http) * [.webhook](#util.http.webhook) : object * [.geturl(sourcename)](#util.http.webhook.geturl) ⇒ Promise.<string> * [.poll(sourcename)](#util.http.webhook.poll) ⇒ Promise.<Array.<Object>> * [.ack(webhookid)](#util.http.webhook.ack) ##### webhook.geturl(sourcename) ⇒ Promise.<string> geturl - Returns a public URL that can be used as a webhook target/endpoint for third-party integrations. **Kind**: static method of [webhook](#util.http.webhook) **Returns**: Promise.<string> - A URL for the webhook. | Param | Type | Description | | --- | --- | --- | | sourcename | string | Unique identifier for the webhook | ##### webhook.poll(sourcename) ⇒ Promise.<Array.<Object>> poll - Returns an array of webhook payloads received by the webhook identified by `sourcename`. **Kind**: static method of [webhook](#util.http.webhook) **Returns**: Promise.<Array.<Object>> - Payloads as received by the webhook relay service. | Param | Type | Description | | --- | --- | --- | | sourcename | string | Unique identifier for the webhook | **Example** ```js [ { // Unique ID. Used for ack(webhookid). id: 123, // UNIX timestamp (in seconds) of when the data was received by the webhook URL. timestamp: 1234567890, // Source name set in geturl() source: "sourcename", // JSON string of all the HTTP headers sent to the webhook URL. headers: "{'Content-Type': 'application/json'}", // Entire HTTP request body sent to the webhook URL. body: "" } ] ``` ##### webhook.ack(webhookid) Acknowledge receipt of a webhook payload, deleting it from the relay server. Webhook payload is only queued for deletion, so polling may still return it for a short time. **Kind**: static method of [webhook](#util.http.webhook) | Param | Type | Description | | --- | --- | --- | | webhookid | number | Numeric unique ID received with the payload. See `poll`. | #### http.post(url, data, [responseType], [headers], [method], [continueOnBadStatusCode], [timeoutSeconds]) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> post - Fetch a HTTP POST request. **Kind**: static method of [http](#util.http) **Returns**: Promise.<(string\|Blob\|ArrayBuffer\|Object)> - The server response body. See `responseType` parameter. | Param | Type | Default | Description | | --- | --- | --- | --- | | url | string | | | | data | Object.<string, string> | | POST data key/value list | | [responseType] | string | "text" | "text", "blob", "buffer", or "json" | | [headers] | Object.<string, string> | | HTTP headers to send. Defaults to `{"Content-Type": "application/json"}`. | | [method] | string | "POST" | | | [continueOnBadStatusCode] | boolean | false | If false, throws an Error when the HTTP response code is not 2XX. If true, ignores the response code and proceeds as normal. | | [timeoutSeconds] | number | 15 | Aborts the request (timeout) after this many seconds. | #### http.fetch(url, [responseType], [timeoutSeconds]) ⇒ Promise.<(string\|Blob\|ArrayBuffer\|Object)> fetch - Fetch a HTTP GET request. **Kind**: static method of [http](#util.http) **Returns**: Promise.<(string\|Blob\|ArrayBuffer\|Object)> - The server response body. See `responseType` parameter. | Param | Type | Default | Description | | --- | --- | --- | --- | | url | string | | | | [responseType] | string | "text" | "text", "blob", "buffer", or "json" | | [timeoutSeconds] | number | 15 | Aborts the request (timeout) after this many seconds. | ### util.string : object String manipulation functions. **Kind**: static namespace of [util](#util) * [.string](#util.string) : object * [.split(input, separator, [limit])](#util.string.split) ⇒ Array.<string> * [.chunk(input, chunksize)](#util.string.chunk) ⇒ Array.<string> #### string.split(input, separator, [limit]) ⇒ Array.<string> Split a string with a separator regex. **Kind**: static method of [string](#util.string) | Param | Type | Description | | --- | --- | --- | | input | string | Input string | | separator | string | Passed to `new RegExp(separator, 'g')` | | [limit] | number | Maximum number of splits to perform | #### string.chunk(input, chunksize) ⇒ Array.<string> Split a string into chunks of length `chunksize`. **Kind**: static method of [string](#util.string) | Param | Type | Description | | --- | --- | --- | | input | string | Input string | | chunksize | string | Number of characters per chunk | ### util.time : object Date and time functions **Kind**: static namespace of [util](#util) * [.time](#util.time) : object * [.now()](#util.time.now) ⇒ number * [.diff(compareto)](#util.time.diff) ⇒ number * [.strtotime(str)](#util.time.strtotime) ⇒ number * [.format(format, [timestamp])](#util.time.format) ⇒ string * [.toDateString(timestamp)](#util.time.toDateString) ⇒ string * [.toTimeString(timestamp)](#util.time.toTimeString) ⇒ string #### time.now() ⇒ number Get the current UNIX timestamp in seconds. **Kind**: static method of [time](#util.time) #### time.diff(compareto) ⇒ number Get the number of seconds between now and the given Date or UNIX timestamp in seconds. **Kind**: static method of [time](#util.time) | Param | Type | | --- | --- | | compareto | number \| Date | #### time.strtotime(str) ⇒ number Parse a string date and return UNIX timestamp (in seconds). **Kind**: static method of [time](#util.time) | Param | Type | | --- | --- | | str | string | #### time.format(format, [timestamp]) ⇒ string Take a Date or UNIX timestamp in seconds and format it to a string. Mostly compatible with the [PHP date format codes](https://www.php.net/manual/en/datetime.format.php). **Kind**: static method of [time](#util.time) | Param | Type | Default | Description | | --- | --- | --- | --- | | format | string | | "Y-m-d H:i:s", etc | | [timestamp] | number \| Date | now() | | #### time.toDateString(timestamp) ⇒ string Format a UNIX timestamp (in seconds) as a localized date string. **Kind**: static method of [time](#util.time) | Param | Type | | --- | --- | | timestamp | number | #### time.toTimeString(timestamp) ⇒ string Format a UNIX timestamp (in seconds) as a localized time string. **Kind**: static method of [time](#util.time) | Param | Type | | --- | --- | | timestamp | number | ### util.clipboard : object OS clipboard **Kind**: static namespace of [util](#util) #### clipboard.copy(text, [showNotification]) ⇒ Promise.<boolean> Copy a string to the system clipboard. **Kind**: static method of [clipboard](#util.clipboard) **Returns**: Promise.<boolean> - True if the copy succeeded, else false. | Param | Type | Default | Description | | --- | --- | --- | --- | | text | string | | | | [showNotification] | boolean | false | If true, a "Copied" notification will appear onscreen briefly. | ### util.barcode : object Barcode image generation functions. **Kind**: static namespace of [util](#util) * [.barcode](#util.barcode) : object * [.getBuffer(data, [type], [height], [scale], [includetext])](#util.barcode.getBuffer) ⇒ Promise.<Buffer> * [.getBase64(data, [type], [height], [scale], [includetext])](#util.barcode.getBase64) ⇒ Promise.<string> #### barcode.getBuffer(data, [type], [height], [scale], [includetext]) ⇒ Promise.<Buffer> Get a PNG image buffer of a barcode. Uses library "bwip-js". **Kind**: static method of [barcode](#util.barcode) **Returns**: Promise.<Buffer> - PNG data for the barcode. | Param | Type | Default | Description | | --- | --- | --- | --- | | data | string | | | | [type] | string | "\"code128\"" | | | [height] | number | 10 | | | [scale] | number | 2 | | | [includetext] | boolean | false | Set true to render the barcode's content as text below the code. | #### barcode.getBase64(data, [type], [height], [scale], [includetext]) ⇒ Promise.<string> Get a PNG image of a barcode as a base64 data URI. Uses library "bwip-js". **Kind**: static method of [barcode](#util.barcode) **Returns**: Promise.<string> - "data:image/png;base64,..." | Param | Type | Default | Description | | --- | --- | --- | --- | | data | string | | | | [type] | string | "\"code128\"" | | | [height] | number | 10 | | | [scale] | number | 2 | | | [includetext] | boolean | false | Set true to render the barcode's content as text below the code. | ### util.geography : object **Kind**: static namespace of [util](#util) #### geography.isoToCountryName(iso) ⇒ string Get a human-readable country name from an ISO country code. **Kind**: static method of [geography](#util.geography) | Param | Type | Description | | --- | --- | --- | | iso | string \| number | 2 or 3 letter country code, or numeric country code. | ### util.objectEquals(a, b) ⇒ boolean Compare two objects for equality. See https://stackoverflow.com/a/16788517 **Kind**: static method of [util](#util) **Returns**: boolean - True if equal, else false. | Param | Type | | --- | --- | | a | \* | | b | \* | ### util.delay([ms]) ⇒ Promise Pause execution for some amount of time in an async function, i.e., returns a Promise that resolves in some number of milliseconds. **Kind**: static method of [util](#util) | Param | Type | Default | Description | | --- | --- | --- | --- | | [ms] | number | 1000 | Number of milliseconds to pause. |