Update APIs

docs/Plugin API/shipping.md

@@ -15,6 +15,7 @@ Add custom carrier and rates, and adjust markup.
     * [.getServiceName(serviceId, carrier)](#shipping.getServiceName) ⇒ <code>string</code>
     * [.registerRateEndpoint(getRates, purchase, idPrefix)](#shipping.registerRateEndpoint)
     * [.registerMarkupCalculator(markupFn)](#shipping.registerMarkupCalculator)
+    * [.registerInsuranceProvider(id, name, cardText, maxValue, getQuote, insure)](#shipping.registerInsuranceProvider)
 
 <a name="shipping.Address"></a>
 
@@ -241,3 +242,57 @@ global.apis.shipping.registerMarkupCalculator(
     }
 );
 ```
+<a name="shipping.registerInsuranceProvider"></a>
+
+### shipping.registerInsuranceProvider(id, name, cardText, maxValue, getQuote, insure)
+Add a shipping insurance provider.
+
+**Kind**: static method of [<code>shipping</code>](#shipping)  
+
+| 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. |
+
+**Example**  
+```js
+async function getQuote(value, parcel, carrier, service) {
+    // Do math, etc
+    var cost = value / 100;
+
+    return {
+        cost: cost,
+        retail: cost * 2
+    };
+    // Or, to remove this shipping rate from the list,
+    // because the shipment/carrier/service combination
+    // is not eligible for insurance:
+    return false;
+}
+
+async function insure(value, parcel, carrier = "USPS", service = "Priority", trackingNumber = "94055...") {
+    // Purchase the insurance
+    var cost = value / 100;
+    var retailPrice = cost * 2;
+    var costPrice = cost;
+
+    var receiptitem = new global.apis.pos.ReceiptItem(`sampleinsurance_${trackingNumber}`,
+        "Sample Insurance",
+        "Insured for " + global.apis.i18n.moneyString(value),
+        retailPrice, 1, costPrice, 0
+    );
+    receiptitem.merch = true;
+    receiptitem.category = "Shipping Insurance";
+    receiptitem.barcode = trackingNumber;
+    global.apis.pos.addReceiptItem(receiptitem);
+}
+
+global.apis.shipping.registerInsuranceProvider(
+     "sampleproviderid", "Sample Insurance",
+     "Insurance coverage from Sample Insurance. $1 per $100 of value.",
+     5000, getQuote, insure);
+```