@shipengine/connect-carrier-api 4.0.0-beta.2 → 4.0.0

package/spec.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Shipping API",
     "description": "This API specification describes the canonical ShipEngine Shipping API connector module.",
-    "version": "1.17.1"
+    "version": "1.17.3"
   },
   "paths": {
     "/Register": {
@@ -754,6 +754,13 @@
             },
             "description": "Amount to be paid to the driver, used for local delivery and courier services.",
             "nullable": true
+          },
+          "additional_handling": {
+            "type": "boolean",
+            "description": "Describes whether Additional Handling is requested for the shipment."
+          },
+          "collect_on_delivery": {
+            "$ref": "#/components/schemas/CollectOnDelivery"
           }
         },
         "additionalProperties": { },
@@ -1085,6 +1092,47 @@
         "additionalProperties": false,
         "description": "This model represents a response for a successful cancel pickup request."
       },
+      "CodPaymentType": {
+        "enum": [
+          "any",
+          "cash",
+          "guaranteed_funds"
+        ],
+        "type": "string",
+        "description": "Specifies which payment method is permitted when Collect on Delivery (COD) is requested on a shipment.\r\nany - Any payment method is permitted.\r\ncash - Only cash is permitted.\r\nguaranteed_funds - Only guaranteed funds are permitted, such as a money order or cashier's check."
+      },
+      "CollectOnDelivery": {
+        "required": [
+          "payment_amount"
+        ],
+        "type": "object",
+        "properties": {
+          "payment_amount": {
+            "required": [
+              "currency",
+              "amount"
+            ],
+            "type": "object",
+            "properties": {
+              "amount": {
+                "type": "string",
+                "description": "Decimal currency value, as a string."
+              },
+              "currency": {
+                "type": "string",
+                "description": "Alpha-3 currency code complying with ISO 4217."
+              }
+            },
+            "description": "The payment amount for Collect on Delivery (COD).",
+            "nullable": true
+          },
+          "payment_type": {
+            "$ref": "#/components/schemas/CodPaymentType"
+          }
+        },
+        "additionalProperties": false,
+        "description": "This model represents the option to defer payment for a shipment, otherwise known as Collect on Delivery (COD)."
+      },
       "ConfirmationTypes": {
         "enum": [
           "None",
@@ -1527,6 +1575,11 @@
             "description": "Other Charge for international shipments.",
             "nullable": true
           },
+          "other_charge_description": {
+            "type": "string",
+            "description": "Description for other_charge",
+            "nullable": true
+          },
           "insurance_charge": {
             "required": [
               "currency",

package/src/app/create-endpoint-mapping.ts

@@ -5,6 +5,8 @@ import { CarrierAppDefinition } from './carrier-app-definition';
 export const createEndpointMapping = (
   definition: CarrierAppDefinition,
 ): [Method, ApiEndpoints, ((req: any) => any | Promise<any>) | undefined][] => [
+  //TODO: Remove `Method.POST` from this and all other maps since they are ALL post
+  //TODO: Remove JOI validation from all endpoints and replace them with OpenAPI validation
   [Method.POST, ApiEndpoints.CancelNotification, definition.CancelNotification],
   [Method.POST, ApiEndpoints.CancelPickup, definition.CancelPickup],
   [Method.POST, ApiEndpoints.CreateLabel, definition.CreateLabel],

package/src/constants.ts

@@ -0,0 +1,2 @@
+// Name of the file that will contain rating logic used by Native Rating
+export const rateLogicName = 'rate-shipments.js';

package/src/index.ts

@@ -3,6 +3,7 @@ export * as requests from './requests';
 export * as responses from './responses';
 
 export * from './app';
+export * from './constants';
 export * from './models';
 export * from './requests';
 export * from './responses';

package/src/models/advanced-options.ts

@@ -1,3 +1,4 @@
+import { CollectOnDelivery } from './collect-on-delivery';
 import { Currency } from './currency';
 
 /** @description Basic structure for shipping options */
@@ -14,6 +15,10 @@ export class AdvancedOptions {
   saturday_delivery?: boolean;
   /** @description Amount to be paid to the driver, used for local delivery and courier services */
   tip?: Currency;
+  /** @description Describes whether Additional Handling is requested for the shipment  */
+  additional_handling?: boolean;
+  /** @description Describes details for Collect on Delivery (COD) if requested for the shipment */
+  collect_on_delivery?: CollectOnDelivery;
   /** @description Any other custom shipping options */
   [key: string]: any;
 }

package/src/models/bill-to.ts

@@ -0,0 +1,15 @@
+import { AddressBase } from './addresses';
+import { BillToParty } from './billing';
+
+/**
+ * @description Bill to is a generic object used for billing a part of the shipment, duties, taxes, or otherwise to a party
+        other than the shipper (the shipper is considered the default party responsible). Ref: BillTo extends AddressBase.
+        since address fields are often required when associating billing to
+        another account.  Additionally, this allows for a contact to be specified, if necessary.
+ */
+export class BillTo extends AddressBase {
+  /** @description The bill_to_party mentions the type of billing option*/
+  bill_to_party?: BillToParty;
+  /** @description Specified if there is an account number associated with the Bill To Party, and the Bill To Party is not the account holder. */
+  account_number?: string;
+}

package/src/models/billing/billing-to-party.ts

@@ -0,0 +1,10 @@
+/** @description The type of party responsible for a given category of charges associated with a shipment, such as
+ * shipping charges or import duties. */
+export enum BillToParty {
+  /** @description The shipper is generally regarded as the party responsible for the billing. */
+  Shipper = 'shipper',
+  /** @description The recipient may be responsible for the billing of some entities, that could include the shipping cost. */
+  Recipient = 'recipient',
+  /** @description A shipper may want to bill to a third-party; especially common for 3PLs and larger volume. merchants */
+  ThirdPartyAccount = 'third_party_account',
+}

package/src/models/billing/index.ts

@@ -2,3 +2,4 @@ export * from './billing-categories';
 export * from './billing-categories-schema';
 export * from './billing-line-item';
 export * from './billing-line-item-schema';
+export * from './billing-to-party';

package/src/models/cod-payment-type.ts

@@ -0,0 +1,9 @@
+/** @description Specifies which payment method is permitted when Collect on Delivery (COD) is requested on a shipment */
+export enum CodPaymentType {
+  /** @description Any payment method is permitted */
+  Any = 'any',
+  /** @description Only cash is permitted */
+  Cash = 'cash',
+  /** @description Only guaranteed funds are permitted, such as a money order or cashier's check */
+  GuaranteedFunds = 'guaranteed_funds',
+}

package/src/models/collect-on-delivery.ts

@@ -0,0 +1,10 @@
+import { CodPaymentType } from './cod-payment-type';
+import { Currency } from './currency';
+
+/** @description This model represents the option to defer payment for a shipment, otherwise known as Collect on Delivery (COD) */
+export class CollectOnDelivery {
+  /** @description The payment amount for Collect on Delivery (COD) */
+  payment_amount!: Currency;
+  /** @description The payment method permitted for Collect on Delivery (COD) */
+  payment_type?: CodPaymentType;
+}

package/src/models/customs/customs-charges.ts

@@ -6,6 +6,8 @@ export class CustomsCharges {
   freight_charge?: Currency;
   /** @description Other charge for international shipments. */
   other_charge?: Currency;
+  /** @description : Description for other charge for international shipments.*/
+  other_charge_description?: string;
   /** @description Insurance charge for international shipments. */
   insurance_charge?: Currency;
   /** @description Discount for international shipments. */

package/src/models/customs/customs.ts

@@ -21,7 +21,7 @@ export class Customs {
   /** @description Declaration statement to be placed on the commercial invoice */
   declaration?: string;
   /** @description  Incoterms specify who is responsible for paying for and managing the shipment*/
-  termsOfTradeCode?: TermsOfTradeCode;
+  terms_of_trade_code?: TermsOfTradeCode;
   /** @description The owner or purchaser of the products being imported into a destination country.*/
   importer_of_record?: ImporterOfRecord;
   /** @description The charges related with customs.*/

package/src/models/index.ts

@@ -1,6 +1,8 @@
 export * from './addresses';
 export * from './advanced-options';
 export * from './authorization';
+export * from './cod-payment-type';
+export * from './collect-on-delivery';
 export * from './billing';
 export * from './confirmation-types';
 export * from './currency-schema';
@@ -18,6 +20,7 @@ export * from './inbound-content-types';
 export * from './insurance-providers';
 export * from './labels';
 export * from './manifests';
+export * from './native-rating';
 export * from './package';
 export * from './pickup';
 export * from './rates';
@@ -30,3 +33,4 @@ export * from './time-window-schema';
 export * from './time-window';
 export * from './tracking';
 export * from './units';
+export * from './bill-to';

package/src/models/native-rating/context-results.ts

@@ -0,0 +1,3 @@
+export interface ContextResults<T> {
+  [dataKey: string]: T;
+}

package/src/models/native-rating/get-rates.ts

@@ -0,0 +1,9 @@
+import { ContextResults } from './context-results';
+import { NumericCurrency } from './numeric-currency';
+
+export type GetRatesResults = ContextResults<NumericCurrency>;
+
+/** Function to get rates from the context */
+export interface GetRates {
+  (dataKeys: string[]): Promise<GetRatesResults>;
+}

package/src/models/native-rating/get-variables.ts

@@ -0,0 +1,8 @@
+import { ContextResults } from './context-results';
+
+export type GetVariableResults = ContextResults<any>;
+
+/** Function to get rating variables from the context */
+export interface GetVariables {
+  (dataKeys: string[]): Promise<GetVariableResults>;
+}

package/src/models/native-rating/get-zone.ts

@@ -0,0 +1,9 @@
+import { ContextResults } from './context-results';
+
+export type GetZoneResults = ContextResults<any>;
+
+/** Function to get zone data from the context */
+export interface GetZone {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (dataKeys: string[]): Promise<GetZoneResults>;
+}

package/src/models/native-rating/implementation-type.ts

@@ -0,0 +1,33 @@
+import type { GetRatesRequest, Rate } from '@shipengine/connect-carrier-api';
+import type { RatingContext } from './rating-context';
+
+/** A rate request shipment with its corresponding id */
+export interface ShipmentAndId {
+  /** rate_request_identifier for the rate request */
+  id: string;
+  /** Shipment for the rate request */
+  shipment: GetRatesRequest;
+}
+
+/** Rate results with its corresponding rate request id */
+export interface RateResultsAndId {
+  /** rate_request_identifier for the corresponding rate request */
+  id: string;
+  /** Error, if any */
+  error?: unknown;
+  /** Rates for a given rate request */
+  rates: Rate[];
+}
+
+/** Implementation of a carrier */
+export interface RatingCarrier {
+  /** Rate shipments
+   * @param context Native Rating context that can be used by the implementation to interact with the underlying service
+   * @param shipment Shipments that should be rated
+   * @returns List of rates for the given shipments
+   */
+  rateShipments: (context: RatingContext, shipment: ShipmentAndId[]) => Promise<RateResultsAndId[]>;
+}
+
+/** Signify a validation error from the carrier */
+export class CarrierValidationError extends Error {}

package/src/models/native-rating/index.ts

@@ -0,0 +1,7 @@
+export * from './context-results';
+export * from './get-rates';
+export * from './get-variables';
+export * from './get-zone';
+export * from './implementation-type';
+export * from './numeric-currency';
+export * from './rating-context';

package/src/models/native-rating/numeric-currency.ts

@@ -0,0 +1,5 @@
+/** NumericCurrency so that we don't have to convert from the string Currency all over the place */
+export interface NumericCurrency {
+  currency: string;
+  amount: number | undefined;
+}

package/src/models/native-rating/rating-context.ts

@@ -0,0 +1,19 @@
+import { Logger } from 'winston';
+import { GetVariables } from './get-variables';
+import { GetRates } from './get-rates';
+import { GetZone } from './get-zone';
+
+/** Rates request context */
+export interface RatingContext {
+  /** Function to get rates for given keys */
+  getRates: GetRates;
+
+  /** Function to get variables for given keys */
+  getVariables: GetVariables;
+
+  /** Function to get zone for given keys */
+  getZone: GetZone;
+
+  /** Logger that implementers can use */
+  log: Logger;
+}

package/src/models/taxes/tax-identifier.ts

@@ -6,8 +6,10 @@ export class TaxIdentifier {
   id!: string;
   /** @description The Tax ID type */
   type!: TaxIdentifierType;
-  /** @description The country where the Tax ID is registered with */
+  /** @deprecated This property has been deprecated, please use registration_country instead */
   registration_county?: string;
+  /** @description The country where the Tax ID is registered with */
+  registration_country?: string;
   /** @description Description of the tax ID that may give the customs agent more context */
   description?: string;
 }

package/src/requests/create-label-request.ts

@@ -17,6 +17,7 @@ import {
   RelayPointDetails,
   DisplayScheme,
   Customs,
+  BillTo,
 } from '../models';
 
 /** @description Basic structure for a request to create a label */
@@ -54,4 +55,6 @@ export class CreateLabelRequest extends BaseRequest {
   /** @description Display schemes that the label will be returned in. Label is returned by default */
   display_schemes?: DisplayScheme[];
   customs?: Customs;
+  /** @description Bill the shipping charges to this entity. If null, it should be assumed the "shipper" is responsible for the shipping charges. */
+  bill_shipping_to?: BillTo;
 }

package/src/requests/get-rates-request.ts

@@ -10,6 +10,7 @@ import {
   PudoLocation,
   FulfillmentPlanDetails,
   TimeWindow,
+  BillTo,
 } from '../models';
 import { ShipmentItem } from '../models/shipment-item';
 
@@ -33,4 +34,6 @@ export class GetRatesRequest extends BaseRequest {
   carrier_pickup_window?: TimeWindow;
   /** Items included in the shipment */
   items?: ShipmentItem[];
+  /** @description Bill the shipping charges to this entity. If null, it should be assumed the "shipper" is responsible for the shipping charges. */
+  bill_shipping_to?: BillTo;
 }