475 lines
16 KiB
Markdown
475 lines
16 KiB
Markdown
# Parcel/Package Object
|
|
|
|
This object is supplied a plugin registered with `registerRateEndpoint` when PostalPoint requests
|
|
shipping rates from the plugin.
|
|
|
|
```javascript
|
|
export class Package {
|
|
constructor(isPrepaid = false) {
|
|
this.prepaid = isPrepaid;
|
|
this.packaging = {
|
|
type: "Parcel",
|
|
service: "",
|
|
carrier: "",
|
|
length: 999999,
|
|
width: 999999,
|
|
height: 999999,
|
|
weightOz: 999999,
|
|
nonmachinable: false,
|
|
additionalHandling: false,
|
|
internalid: 100,
|
|
oversizeFlag: false
|
|
};
|
|
this.extraServices = {
|
|
certifiedMail: false,
|
|
barcode3800: "",
|
|
registeredMail: false,
|
|
registeredMailAmount: false, // can be a number in USD
|
|
returnReceipt: false,
|
|
returnReceiptElectronic: false,
|
|
insurance: false, // can be a number in USD
|
|
signature: false, // can be false, "SIGNATURE", or "SIGNATURE_RESTRICTED"
|
|
hazmat: false,
|
|
perishable: false,
|
|
crematedRemains: false,
|
|
liveAnimal: false, // BEES, DAY_OLD_POULTRY, ADULT_BIRDS, OTHER_LIVES
|
|
cod: false, // Collect on Delivery
|
|
codAmount: false,
|
|
endorsement: "", // ADDRESS_SERVICE_REQUESTED, CHANGE_SERVICE_REQUESTED, FORWARDING_SERVICE_REQUESTED, LEAVE_IF_NO_RESPONSE, RETURN_SERVICE_REQUESTED
|
|
carrier_billing_account: {// Bill a third party's account number for the label
|
|
type: "", // "" (ignores this entire option), "SENDER" (EasyPost default), "THIRD_PARTY", "RECEIVER", "COLLECT"
|
|
carrier: "", // Carrier ID (should be used to filter rates)
|
|
account_number: "", // Carrier account number to bill
|
|
country: "", // Country account is based in
|
|
postal_code: "" // Postal code of account
|
|
},
|
|
dryIce: false,
|
|
dryIceWeight: 0,
|
|
dryIceMedical: false
|
|
};
|
|
this.specialRateEligibility = false;
|
|
this.customs = {
|
|
contents: "",
|
|
contentsExplanation: "", // needed if contents is "other"
|
|
signature: "",
|
|
restriction: "",
|
|
restrictionComments: "", // needed if restriction is "other"
|
|
nonDelivery: "return", // "return" or "abandon",
|
|
eel_pfc: "",
|
|
items: [] // {index: 0, description: "", qty: "", lbs: "", oz: "", value: "", hscode: "", origin: US"}
|
|
};
|
|
this.toAddress = new Address();
|
|
this.returnAddress = new Address();
|
|
this.originAddress = new Address();
|
|
this.trackingNumber = "";
|
|
}
|
|
|
|
/**
|
|
* Format as EasyPost shipment object
|
|
* @returns {Package.toEasyPostShipment.shipment}
|
|
*/
|
|
async toEasyPostShipment() {
|
|
// Not relevant to plugins
|
|
}
|
|
|
|
/**
|
|
* Format as Endicia shipment object
|
|
* @returns {Package.toSERAShipment.shipment}
|
|
*/
|
|
async toSERAShipment() {
|
|
// Not relevant to plugins
|
|
}
|
|
|
|
/**
|
|
* Get a human-readable summary of size and options.
|
|
* Does not include address data.
|
|
* @returns {String}
|
|
*/
|
|
async toString() {
|
|
let summary = [];
|
|
let packaging = await getPackagingByID(this.packaging.internalid);
|
|
let weight = ozToLbsOz(this.packaging.weightOz);
|
|
let weightStr = this.packaging.weightOz >= 16 ? `${weight[0]} lbs ${weight[1]} oz` : `${weight[1]} oz`;
|
|
if (packaging != false) {
|
|
if (packaging.irregular) {
|
|
if (packaging.weight === false) {
|
|
summary.push("Parcel");
|
|
} else {
|
|
summary.push(`${weightStr} Parcel`);
|
|
}
|
|
summary.push("Additional Handling");
|
|
} else {
|
|
if (packaging.weight === false) {
|
|
summary.push(packaging.name);
|
|
} else {
|
|
summary.push(`${weightStr} ${packaging.name}`);
|
|
}
|
|
}
|
|
} else {
|
|
summary.push(weightStr);
|
|
}
|
|
if (this.extraServices.hazmat) {
|
|
summary.push("HAZMAT");
|
|
}
|
|
if (this.extraServices.liveAnimal === true) {
|
|
summary.push("Live Animals");
|
|
} else if (typeof this.extraServices.liveAnimal == "string") {
|
|
switch (this.extraServices.liveAnimal) {
|
|
case "BEES":
|
|
summary.push("Live Bees");
|
|
break;
|
|
case "DAY_OLD_POULTRY":
|
|
summary.push("Day-old Poultry");
|
|
break;
|
|
case "ADULT_BIRDS":
|
|
summary.push("Live Adult Birds");
|
|
break;
|
|
case "OTHER_LIVES":
|
|
default:
|
|
summary.push("Live Animals");
|
|
break;
|
|
}
|
|
}
|
|
if (this.extraServices.perishable) {
|
|
summary.push("Perishable");
|
|
}
|
|
if (this.extraServices.crematedRemains) {
|
|
summary.push("Cremated Remains");
|
|
}
|
|
if (this.extraServices.certifiedMail) {
|
|
summary.push("Certified Mail");
|
|
} else if (this.extraServices.registeredMail) {
|
|
summary.push("Registered Mail");
|
|
summary.push("Registered for $" + (this.extraServices.registeredMailAmount * 1.0).toFixed(2));
|
|
} else if (this.extraServices.signature == "SIGNATURE") {
|
|
summary.push("Signature Required");
|
|
}
|
|
if (this.extraServices.signature == "ADULT_SIGNATURE") {
|
|
summary.push("Adult Signature Required");
|
|
}
|
|
if (this.extraServices.signature == "SIGNATURE_RESTRICTED") {
|
|
summary.push("Restricted Delivery");
|
|
}
|
|
if (this.extraServices.returnReceiptElectronic) {
|
|
summary.push("Return Receipt Electronic");
|
|
}
|
|
if (this.extraServices.returnReceipt) {
|
|
summary.push("Return Receipt");
|
|
}
|
|
if (this.extraServices.insurance) {
|
|
summary.push("Insured for $" + (this.extraServices.insurance * 1.0).toFixed(2));
|
|
}
|
|
if (this.extraServices.cod) {
|
|
summary.push("Collect on Delivery: $" + (this.extraServices.codAmount * 1.0).toFixed(2));
|
|
}
|
|
if (this.extraServices.dryIce && this.extraServices.dryIceWeight > 0) {
|
|
summary.push("Dry Ice: " + (this.extraServices.dryIceWeight * 1).toFixed(0) + " oz");
|
|
}
|
|
if (this.extraServices.carrier_billing_account?.type) {
|
|
if (this.extraServices.carrier_billing_account.type != "") {
|
|
var accountNumber = this.extraServices.carrier_billing_account.account_number;
|
|
var accountNumberCensored = accountNumber.substring(accountNumber.length - 4).padStart(accountNumber.length, "X");
|
|
var carrierName = this.extraServices.carrier_billing_account.carrier;
|
|
switch (this.extraServices.carrier_billing_account.type) {
|
|
case "SENDER":
|
|
summary.push(`Bill to sender ${carrierName} account #${accountNumberCensored}`);
|
|
break;
|
|
case "THIRD_PARTY":
|
|
summary.push(`Bill to third party ${carrierName} account #${accountNumberCensored}`);
|
|
break;
|
|
case "RECEIVER":
|
|
summary.push(`Bill to receiver ${carrierName} account #${accountNumberCensored}`);
|
|
break;
|
|
case "COLLECT":
|
|
if (accountNumber.length > 0) {
|
|
summary.push(`Bill collect ${carrierName} account #${accountNumberCensored}`);
|
|
} else {
|
|
summary.push(`Bill collect`);
|
|
}
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
return summary.join("\n");
|
|
}
|
|
|
|
async needsHAZMATPrompt() {
|
|
try {
|
|
let packagingInfo = await getPackagingByID(this.packaging.internalid);
|
|
if (packagingInfo.hazmat) {
|
|
return true;
|
|
}
|
|
if (this.packaging.weight > 10) {
|
|
return true;
|
|
}
|
|
if (packagingInfo.l >= -1 && Math.max(this.packaging.length, this.packaging.width, this.packaging.height) > 0.5) {
|
|
return true;
|
|
}
|
|
switch (packagingInfo.type) {
|
|
case "Letter":
|
|
case "Card":
|
|
return false;
|
|
}
|
|
return true;
|
|
} catch (ex) {
|
|
return true;
|
|
}
|
|
}
|
|
|
|
get isPrepaid() {
|
|
return this.prepaid == true;
|
|
}
|
|
|
|
setCustomsInfo(contents, contentsExplanation, signature, restriction, restrictionComments, nonDelivery) {
|
|
let items = this.customs.items; // Save this and copy it back in so we don't overwrite it
|
|
this.customs = {
|
|
contents: contents,
|
|
contentsExplanation: contentsExplanation, // needed if contents is "other"
|
|
signature: signature,
|
|
restriction: restriction,
|
|
restrictionComments: restrictionComments, // needed if restriction is "other"
|
|
nonDelivery: nonDelivery, // "return" or "abandon",
|
|
items: items
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Get the customs items, ignoring any that are blank.
|
|
* @returns {Array}
|
|
*/
|
|
getCustomsItems() {
|
|
let items = [];
|
|
for (let i = 0; i < this.customs.items.length; i++) {
|
|
let item = this.customs.items[i];
|
|
if (item.description == "" && (item.qty == "" || item.qty == 0) && (item.weight == "" || item.weight == 0) && (item.value == "" || item.value == 0)) {
|
|
continue;
|
|
}
|
|
items.push(item);
|
|
}
|
|
return items;
|
|
}
|
|
|
|
setCustomsItems(items) {
|
|
this.customs.items = items;
|
|
}
|
|
|
|
getCustoms() {
|
|
this.customs.items = this.getCustomsItems();
|
|
return this.customs;
|
|
}
|
|
|
|
/**
|
|
* Attempt to automatically fix simple issues like overweight letters.
|
|
* @returns {undefined}
|
|
*/
|
|
async fixIssues() {
|
|
if (this.packaging.type == "Letter" && this.packaging.weightOz > 3.5) {
|
|
if (this.packaging.nonmachinable) {
|
|
return; // Has to be a parcel, can't fix without dimensions
|
|
}
|
|
this.packaging.type = "Flat";
|
|
this.packaging.internalid = 104;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Do some basic checks to see if this package is even remotely shippable
|
|
* @param {boolean} kioskMode If true, returned strings are suitable for display in kiosk mode.
|
|
* @returns {boolean|string} true if okay, human-readable error message and instructions if not okay
|
|
*/
|
|
async isValid(kioskMode = false) {
|
|
// Removed from docs for brevity. Just a bunch of if statements to catch problems.
|
|
}
|
|
|
|
/**
|
|
* Set package characteristics
|
|
* @param {string} type "Parcel", "Letter", "Flat", "Card"
|
|
* @param {type} service
|
|
* @param {type} carrier
|
|
* @param {type} length
|
|
* @param {type} width
|
|
* @param {type} height
|
|
* @param {type} weightOz
|
|
* @returns {undefined}
|
|
*/
|
|
setPackaging(type, service, carrier, length, width, height, weightOz, nonmachinable) {
|
|
if (typeof nonmachinable == "undefined") {
|
|
nonmachinable = false;
|
|
}
|
|
if (type == "Card") {
|
|
// Postcards
|
|
weightOz = 1;
|
|
this.packaging.internalid = 105;
|
|
} else if (type == "Flat") {
|
|
this.packaging.internalid = 104;
|
|
} else if (type == "Letter") {
|
|
this.packaging.internalid = 102;
|
|
if (nonmachinable) {
|
|
this.packaging.internalid = 103;
|
|
}
|
|
}
|
|
this.packaging.type = type;
|
|
this.packaging.service = service;
|
|
this.packaging.carrier = carrier;
|
|
this.packaging.weightOz = weightOz;
|
|
this.packaging.nonmachinable = nonmachinable;
|
|
|
|
// Enforce Length > Width > Height
|
|
let size = [length, width, height];
|
|
size.sort(function (a, b) {
|
|
return b - a;
|
|
});
|
|
this.packaging.length = size[0];
|
|
this.packaging.width = size[1];
|
|
this.packaging.height = size[2];
|
|
}
|
|
|
|
/**
|
|
* Set an extra service
|
|
* @param {string} id Service ID
|
|
* @param {boolean} enabled Turn it on or off
|
|
* @param {string} value Service value, if needed (some are not just a boolean)
|
|
* @returns {undefined}
|
|
*/
|
|
setExtraService(id, enabled, value) {
|
|
if (typeof value != "undefined" && enabled) {
|
|
this.extraServices[id] = value;
|
|
} else {
|
|
this.extraServices[id] = enabled == true;
|
|
}
|
|
}
|
|
|
|
getExtraServices() {
|
|
return this.extraServices;
|
|
}
|
|
|
|
/**
|
|
* Set to "MEDIA_MAIL", "LIBRARY_MAIL", or false
|
|
* @param {type} rate
|
|
* @returns {undefined}
|
|
*/
|
|
set specialRate(rate) {
|
|
if (rate == "MEDIA") {
|
|
rate = "MEDIA_MAIL";
|
|
} else if (rate == "LIBRARY") {
|
|
rate = "LIBRARY_MAIL";
|
|
}
|
|
if (rate != "MEDIA_MAIL" && rate != "LIBRARY_MAIL") {
|
|
rate = false;
|
|
}
|
|
this.specialRateEligibility = rate;
|
|
}
|
|
|
|
get specialRate() {
|
|
return this.specialRateEligibility;
|
|
}
|
|
|
|
/**
|
|
* Save an address to this package.
|
|
* @param {string} type "to", "return", or "origin"
|
|
* @param {string} name
|
|
* @param {string} company
|
|
* @param {string} street1
|
|
* @param {string} street2
|
|
* @param {string} city
|
|
* @param {string} state
|
|
* @param {string} zip
|
|
* @param {string} country ISO 2-char country code
|
|
* @param {string} phone
|
|
* @param {string} email
|
|
* @returns {undefined}
|
|
*/
|
|
setAddress(type, name, company, street1, street2, city, state, zip, country, phone, email) {
|
|
let address = Address.fromObject({
|
|
name: name,
|
|
company: company,
|
|
street1: street1,
|
|
street2: street2,
|
|
city: city,
|
|
state: state,
|
|
zip: zip,
|
|
country: country,
|
|
phone: phone,
|
|
email: email
|
|
});
|
|
switch (type) {
|
|
case "to":
|
|
this.toAddress = address;
|
|
break;
|
|
case "return":
|
|
this.returnAddress = address;
|
|
break;
|
|
case "origin":
|
|
this.originAddress = address;
|
|
break;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Set an address using an object that matches the internal form (see setAddress())
|
|
* @param {string} type
|
|
* @param {object} data
|
|
* @returns {undefined}
|
|
*/
|
|
setAddressWhole(type, address) {
|
|
switch (type) {
|
|
case "to":
|
|
this.toAddress = Address.fromObject(address);
|
|
break;
|
|
case "return":
|
|
this.returnAddress = Address.fromObject(address);
|
|
break;
|
|
case "origin":
|
|
this.originAddress = Address.fromObject(address);
|
|
break;
|
|
}
|
|
}
|
|
|
|
get tracking() {
|
|
return this.trackingNumber;
|
|
}
|
|
|
|
set tracking(n) {
|
|
this.trackingNumber = n;
|
|
}
|
|
|
|
/**
|
|
* Get the "from" address that will be shown,
|
|
* using the return address or origin address as needed
|
|
* @returns {address}
|
|
*/
|
|
getReturnAddress() {
|
|
var a = null;
|
|
if (typeof this.returnAddress == "object") {
|
|
a = Address.fromObject(this.returnAddress);
|
|
} else {
|
|
a = Address.fromObject(this.originAddress);
|
|
}
|
|
if (a.country == "") {
|
|
a.country = defaultCountryCode();
|
|
}
|
|
return a;
|
|
}
|
|
|
|
getToAddress() {
|
|
var a = Address.fromObject(this.toAddress);
|
|
if (a.country == "") {
|
|
a.country = defaultCountryCode();
|
|
}
|
|
return a;
|
|
}
|
|
|
|
getFromAddress() {
|
|
var a = null;
|
|
if (typeof this.originAddress == "object") {
|
|
a = Address.fromObject(this.originAddress);
|
|
} else {
|
|
a = Address.fromObject(this.returnAddress);
|
|
}
|
|
if (a.country == "") {
|
|
a.country = defaultCountryCode();
|
|
}
|
|
return a;
|
|
}
|
|
}
|
|
``` |