@shipengine/connect-carrier-api 2.12.14 → 2.12.17

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.16.24"
+    "version": "1.17.1"
   },
   "paths": {
     "/Register": {
@@ -570,6 +570,40 @@
           }
         }
       }
+    },
+    "/ImportTrackingEvents": {
+      "post": {
+        "tags": [
+          "Tracking"
+        ],
+        "description": "This method returns imported tracking events for a connection, and should only be implemented if you support\r\nimporting tracking data in bulk via file exchange or API requests.\r\n            \r\nAny information needed to retrieve tracking data for a connection should be collected in your registration\r\nform and will be made available as metadata in the request.",
+        "operationId": "ImportTrackingEvents",
+        "requestBody": {
+          "description": "An object containing information about the connection to import tracking events for.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ImportTrackingEventsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "A list of imported tracking events",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/ImportedTrackingEvent"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -2224,6 +2258,35 @@
         "additionalProperties": false,
         "description": "A key value pair, allowing custom properties to be stored."
       },
+      "ImportedTrackingEvent": {
+        "type": "object",
+        "properties": {
+          "tracking_info": {
+            "$ref": "#/components/schemas/TrackingInfo"
+          },
+          "update_method": {
+            "$ref": "#/components/schemas/UpdateMethods"
+          },
+          "error_messages": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Any error messages resulting from processing the tracking event",
+            "nullable": true
+          },
+          "warning_messages": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Any warning messages resulting from processing the tracking event",
+            "nullable": true
+          }
+        },
+        "additionalProperties": false,
+        "description": "This model represents an imported tracking event"
+      },
       "ImporterOfRecord": {
         "type": "object",
         "properties": {
@@ -2289,6 +2352,18 @@
         "additionalProperties": false,
         "description": "Basic structure for a Importer Record"
       },
+      "ImportTrackingEventsRequest": {
+        "required": [
+          "transaction_id"
+        ],
+        "type": "object",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseRequest"
+          }
+        ],
+        "additionalProperties": false
+      },
       "InboundDataContentTypes": {
         "enum": [
           "tracking"
@@ -3194,8 +3269,7 @@
             "nullable": true
           },
           "type": {
-            "$ref": "#/components/schemas/ServicePointLocationType",
-            "nullable": true
+            "$ref": "#/components/schemas/ServicePointLocationType"
           }
         },
         "additionalProperties": false
@@ -3353,6 +3427,9 @@
           "label_messages": {
             "$ref": "#/components/schemas/LabelMessage"
           },
+          "customs": {
+            "$ref": "#/components/schemas/Customs"
+          },
           "insured_value": {
             "required": [
               "currency",
@@ -3371,9 +3448,6 @@
             },
             "description": "The insured value of this package.",
             "nullable": true
-          },
-          "customs": {
-            "$ref": "#/components/schemas/Customs"
           }
         },
         "additionalProperties": false,

package/src/app/carrier-app-definition.ts

@@ -1,3 +1,4 @@
+import { ImportedTrackingEvent } from '../models';
 import {
   RegisterRequest,
   CreateLabelRequest,
@@ -15,6 +16,7 @@ import {
   GetRelayPointsRequest,
   GetServicePointsRequest,
   GetServicePointRequest,
+  ImportTrackingEventsRequest,
 } from '../requests';
 
 import {
@@ -144,4 +146,11 @@ export interface CarrierAppDefinition {
   GetServicePoint?: (
     request: GetServicePointRequest,
   ) => GetServicePointResponse | Promise<GetServicePointResponse>;
+  /**
+   * @description This endpoint is used to import tracking events for a connection by id
+   * @param request Data needed by the provider to import tracking events
+   */
+  ImportTrackingEvents?: (
+    request: ImportTrackingEventsRequest,
+  ) => AsyncGenerator<ImportedTrackingEvent>;
 }

package/src/app/carrier-app.ts

@@ -6,6 +6,7 @@ import { OpenApiSpecification } from '../spec';
 import { Metadata } from './internal/metadata';
 import { CarrierSpecification } from './internal/carrier-specification';
 import { CarrierAppMetadataSchema } from './metadata';
+import { ImportedTrackingEventSchema } from '../models';
 import {
   RegisterResponseSchema,
   CancelNotificationResponseSchema,
@@ -152,6 +153,12 @@ export class CarrierApp implements ConnectRuntimeApp {
         definition.GetServicePoint,
         GetServicePointResponseSchema,
       ],
+      [
+        Method.POST,
+        ApiEndpoints.ImportTrackingEvents,
+        definition.ImportTrackingEvents,
+        ImportedTrackingEventSchema,
+      ],
     ).forEach(([method, path, implementation, schema]) => {
       if (implementation) {
         this.routes.push({

package/src/app/constants.ts

@@ -15,4 +15,5 @@ export enum ApiEndpoints {
   GetRelayPoints = '/GetRelayPoints',
   GetServicePoints = '/GetServicePoints',
   GetServicePoint = '/GetServicePoint',
+  ImportTrackingEvents = '/ImportTrackingEvents',
 }

package/src/app/internal/metadata.ts

@@ -50,6 +50,10 @@ const mapFunctions = (app: CarrierAppDefinition): FunctionSpecification[] => {
     fns.push(fn('Track'));
   }
 
+  if (app.ImportTrackingEvents) {
+    fns.push(fn('ImportTrackingEvents'));
+  }
+
   return fns;
 };
 

package/src/app/internal/route.ts

@@ -17,7 +17,7 @@ export interface FileRoute {
 /** @description The definition for a route and how it will be handled */
 export interface HandlerRoute {
   /** @description The method that will be called to handle this request */
-  handler?: (req: any) => any | Promise<any>;
+  handler?: (req: any) => any | Promise<any> | AsyncGenerator<any>;
   /** @description The optional method used to validate the response for this route. Used for warning purposes. */
   validateResponse?: (response: any) => string[] | undefined;
 }

package/src/index.ts

@@ -2,8 +2,8 @@ export * as models from './models';
 export * as requests from './requests';
 export * as responses from './responses';
 
-export * from './requests';
-export * from './responses';
 export * from './app';
 export * from './models';
+export * from './requests';
+export * from './responses';
 export * from './spec';

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/index.ts

@@ -30,3 +30,4 @@ export * from './time-window-schema';
 export * from './time-window';
 export * from './tracking';
 export * from './units';
+export * from './bill-to';

package/src/models/tracking/imported-tracking-event-schema.ts

@@ -0,0 +1,8 @@
+import Joi from 'joi';
+import { TrackingInfoSchema } from './tracking-info-schema';
+
+export const ImportedTrackingEventSchema = Joi.object({
+  tracking_info: TrackingInfoSchema.optional(),
+  error_messages: Joi.array().optional().items(Joi.string()),
+  warning_messages: Joi.array().optional().items(Joi.string()),
+});

package/src/models/tracking/imported-tracking-event.ts

@@ -0,0 +1,17 @@
+import { TrackingInfo } from './tracking-info';
+import { UpdateMethods } from './update-method';
+
+export class ImportedTrackingEvent {
+  /** @description The tracking information for the shipment */
+  tracking_info?: TrackingInfo;
+  /**
+   * @description Optional method for updating the tracking information state, i.e. is the returned
+   * information the complete state of the package or should it be appended to the existing state.
+   * Defaults to `append` if not specified.
+   */
+  update_method?: UpdateMethods;
+  /** @description Any error messages resulting from processing the tracking event */
+  error_messages?: string[];
+  /** @description Any warning messages resulting from processing the tracking event */
+  warning_messages?: string[];
+}

package/src/models/tracking/index.ts

@@ -1,3 +1,5 @@
+export * from './imported-tracking-event-schema';
+export * from './imported-tracking-event';
 export * from './lat-long-schema';
 export * from './lat-long';
 export * from './service-schema';

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;
 }

package/src/requests/import-tracking-events-request.ts

@@ -0,0 +1,3 @@
+import { BaseRequest } from './base-request';
+
+export class ImportTrackingEventsRequest extends BaseRequest {}

package/src/requests/index.ts

@@ -1,16 +1,17 @@
+export * from './cancel-notification-request';
 export * from './cancel-pickup-request';
 export * from './create-label-request';
 export * from './create-manifest-request';
+export * from './create-notification-request';
 export * from './get-manifest-request';
 export * from './get-rates-request';
+export * from './get-relay-points-request';
+export * from './get-service-point-request';
+export * from './get-service-points-request';
+export * from './import-tracking-events-request';
+export * from './normalize-tracking-data-request';
 export * from './register-request';
 export * from './schedule-pickup-request';
 export * from './tracking-request';
-export * from './void-labels-request';
-export * from './create-notification-request';
-export * from './cancel-notification-request';
 export * from './validate-inbound-data-request';
-export * from './normalize-tracking-data-request';
-export * from './get-relay-points-request';
-export * from './get-service-points-request';
-export * from './get-service-point-request';
+export * from './void-labels-request';

package/tsconfig.json

@@ -3,14 +3,11 @@
   "compilerOptions": {
     "allowJs": true,
     "declaration": true,
-    "esModuleInterop": true,
     "importHelpers": true,
     "module": "commonjs",
     "outDir": "lib",
     "rootDir": "src",
     "sourceMap": true,
-    "strict": true,
-    "target": "es2017",
     "composite": true
   },
   "include": ["src/**/*"],